agentsqripts/lib/scalability/analyzeScalability.js

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

/**
 * @file Scalability Analysis orchestrator for performance bottleneck detection
 * @description Single responsibility: Coordinate comprehensive scalability analysis
 * 
 * This main interface orchestrates scalability analysis across files and projects,
 * detecting performance bottlenecks, blocking operations, N+1 query patterns,
 * and other scalability anti-patterns that could impact application performance
 * under load or with large datasets.
 * 
 * Design rationale:
 * - Unified interface handles both file-level and project-level analysis
 * - Multiple specialized detectors focus on specific scalability concerns
 * - Automatic routing based on target type simplifies usage
 * - Comprehensive analysis coverage from database to CPU-bound operations
 */

const { promises: fsPromises } = require('fs');
const { analyzeFileScalability } = require('./scalabilityFileAnalyzer');
const { analyzeProjectScalability } = require('./scalabilityProjectAnalyzer');

// Import additional functions for export
const { detectBlockingSync } = require('./blockingSyncDetector');
const { detectNPlusOne } = require('./nPlusOneDetector');

/**
 * Analyze scalability issues with automatic file vs project detection
 * 
 * Technical function: Routes scalability analysis to appropriate analyzer based on target type
 * 
 * Implementation rationale:
 * - fs.stat() determines target type without additional user input
 * - Async operation prevents blocking during file system checks
 * - Delegation pattern enables specialized analysis for different scopes
 * - Consistent return format regardless of analysis scope
 * 
 * Scalability analysis scope:
 * - File-level: Individual file bottlenecks and anti-patterns
 * - Project-level: Cross-file dependencies and system-wide scalability issues
 * - Both scopes: Blocking operations, database patterns, memory usage
 * - Performance: CPU-bound operations, I/O efficiency, concurrency issues
 * 
 * Analysis routing strategy:
 * - Directory targets trigger comprehensive project-wide analysis
 * - File targets enable focused analysis for specific components
 * - Options parameter allows customization for different analysis needs
 * - Error handling maintains robustness for invalid paths
 * 
 * Scalability detection categories:
 * - Blocking synchronous operations that prevent concurrency
 * - N+1 query patterns that cause database performance issues
 * - CPU-intensive loops that could block event loops
 * - Memory leaks and unbounded data structures
 * - File I/O operations in request paths
 * 
 * @param {string} target - File or directory path to analyze for scalability issues
 * @param {Object} options - Analysis configuration options
 * @returns {Promise<Object>} Scalability analysis results with issues and recommendations
 * @example
 *   // File analysis
 *   const fileResults = await analyzeScalability('./api/users.js');
 *   
 *   // Project analysis
 *   const projectResults = await analyzeScalability('./src', { excludePatterns: ['test'] });
 */
async function analyzeScalability(target, options = {}) {
  const stat = await fsPromises.stat(target);
  if (stat.isDirectory()) {
    return analyzeProjectScalability(target, options);
  } else {
    return analyzeFileScalability(target, options);
  }
}



module.exports = {
  analyzeScalability,
  analyzeFileScalability,
  analyzeProjectScalability,
  detectBlockingSync,
  detectNPlusOne
};