agentsqripts/lib/performance/analyzePerformance.js

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

/**
 * @file Performance Analysis orchestrator for optimization opportunity detection
 * @description Single responsibility: Coordinate comprehensive performance analysis
 * 
 * This main interface orchestrates performance analysis across files and projects,
 * detecting algorithmic inefficiencies, I/O bottlenecks, memory issues, and other
 * performance anti-patterns that could impact application speed, throughput,
 * and resource utilization.
 * 
 * Design rationale:
 * - Unified interface handles both file-level and project-level analysis
 * - Multiple specialized detectors focus on specific performance categories
 * - Automatic routing based on target type simplifies integration
 * - Comprehensive coverage from algorithm complexity to system resource usage
 */

const fs = require('fs');
const path = require('path');
const { analyzeFilePerformance } = require('./performanceFileAnalyzer');
const { analyzeProjectPerformance } = require('./performanceProjectAnalyzer');

// Import additional functions for export
const { detectQuadraticPatterns } = require('./quadraticPatternDetector');
const { detectSyncIO } = require('./syncIODetector');
const { calculatePerformanceScore } = require('./performanceScoreCalculator');
const { generatePerformanceRecommendations } = require('./performanceRecommendationGenerator');

/**
 * Analyze performance issues with automatic file vs project detection
 * 
 * Technical function: Routes performance analysis to appropriate analyzer based on target type
 * 
 * Implementation rationale:
 * - fs.stat() determines target type for appropriate analysis routing
 * - Promise-based operation maintains non-blocking behavior
 * - Delegation pattern enables specialized analysis optimized for different scopes
 * - Consistent API interface regardless of analysis scope
 * 
 * Performance analysis dimensions:
 * - Algorithmic complexity: O(n²), O(2^n) patterns, recursive inefficiencies
 * - I/O optimization: Synchronous operations, file system bottlenecks
 * - Memory efficiency: Memory leaks, unbounded data structures, garbage collection
 * - Concurrency: Blocking operations, serial vs parallel async patterns
 * - Framework-specific: React rendering, database query optimization
 * 
 * Analysis routing strategy:
 * - Directory targets enable project-wide performance assessment
 * - File targets provide focused optimization recommendations
 * - Options parameter customizes analysis depth and focus areas
 * - Error handling ensures robust operation across different environments
 * 
 * Performance detection categories:
 * - Quadratic algorithms that don't scale with data size
 * - Synchronous I/O operations that block execution
 * - String concatenation in loops causing memory allocation issues
 * - Serial await patterns that could be parallelized
 * - Database N+1 patterns and inefficient queries
 * - Memory leaks and reference retention issues
 * 
 * Cross-file analysis considerations:
 * - Import/export dependency analysis for load-time optimization
 * - Cross-module data flow analysis for bottleneck identification
 * - Shared resource contention detection
 * - Call graph analysis for hot path identification
 * 
 * @param {string} target - File or directory path to analyze for performance issues
 * @param {Object} options - Analysis configuration options for customization
 * @returns {Promise<Object>} Performance analysis results with metrics and recommendations
 * @example
 *   // Single file analysis
 *   const fileResults = await analyzePerformance('./utils/processor.js');
 *   
 *   // Project-wide analysis
 *   const projectResults = await analyzePerformance('./src', { 
 *     excludePatterns: ['test', 'demo'],
 *     maxFiles: 100 
 *   });
 */
async function analyzePerformance(target, options = {}) {
  const stats = await fs.promises.stat(target);
  if (stats.isDirectory()) {
    return analyzeProjectPerformance(target, options);
  } else {
    return analyzeFilePerformance(target, options);
  }
}



/**
 * Generate optimization recommendations based on performance issues
 * @param {Array} issues - Performance issues found
 * @param {number} totalEffort - Total effort estimate  
 * @param {number} fileCount - Number of files analyzed
 * @returns {Array} Optimization recommendations
 */
function generateOptimizationRecommendations(issues, totalEffort = 0, fileCount = 0) {
  return generatePerformanceRecommendations(issues, totalEffort, fileCount);
}

module.exports = {
  analyzePerformance,
  analyzeFilePerformance,
  analyzeProjectPerformance,
  calculatePerformanceScore,
  generateOptimizationRecommendations,
  detectQuadraticPatterns,
  detectSyncIO
};