agentsqripts/lib/static-bugs/analyzeStaticBugs.js

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

/**
 * @file Static bug analysis orchestrator for comprehensive error detection
 * @description Single responsibility: Coordinate static bug analysis across files and projects
 * 
 * This main interface orchestrates static bug analysis by routing to appropriate analyzers
 * based on target type and consolidating results from multiple detection modules. It provides
 * a unified entry point for identifying logic errors, security vulnerabilities, type issues,
 * and other common programming mistakes across JavaScript codebases.
 * 
 * Design rationale:
 * - Unified interface simplifies integration with development workflows
 * - Automatic routing based on target type eliminates manual configuration
 * - Modular analyzer architecture enables focused bug detection specialization
 * - Consistent result format supports automated tooling and CI/CD integration
 * - Comprehensive coverage through multiple specialized detection modules
 */

const fs = require('fs');
const path = require('path');
// Use simple analyzer for test compatibility
const { analyzeFileStaticBugs } = require('./simpleStaticBugAnalyzer');
const { getQualityGrade } = require('./qualityGradeProvider');
const { analyzeProjectStaticBugs } = require('./staticBugProjectAnalyzer');
const { checkUnreachableCode } = require('./unreachableCodeChecker');
const { generateBugRecommendations } = require('./bugRecommendationGenerator');

/**
 * Analyze static bugs with automatic file vs project detection and routing
 * 
 * Technical function: Unified analysis interface with automatic scope detection
 * 
 * Implementation rationale:
 * - fs.stat-based detection automatically determines analysis scope
 * - Delegation pattern routes to specialized analyzers for optimal performance
 * - Async design supports large project analysis without blocking
 * - Options parameter provides consistent customization across analysis types
 * 
 * Analysis routing strategy:
 * - Directory targets trigger comprehensive project-wide analysis
 * - File targets enable focused analysis for specific modules or components
 * - Consistent options interface allows analyzer-specific configuration
 * - Error handling ensures robust operation with invalid paths
 * 
 * Result consolidation:
 * - Project analysis aggregates results from multiple files and modules
 * - File analysis provides detailed feedback for specific code units
 * - Unified result format enables consistent tool integration
 * - Quality metrics support development process integration
 * 
 * @param {string} target - File or directory path for analysis
 * @param {Object} options - Analysis configuration with detector settings
 * @returns {Promise<Object>} Comprehensive static bug analysis results
 * @example
 *   const results = await analyzeStaticBugs('./src', { severity: 'HIGH' });
 *   // Returns project-wide analysis with high-severity bugs only
 */
async function analyzeStaticBugs(target, options = {}) {
  const stats = await fs.promises.stat(target);
  const isDir = stats.isDirectory();
  return isDir ? analyzeProjectStaticBugs(target, options) : await analyzeFileStaticBugs(target, options);
}

/**
 * Analyze static bugs in a single file (async wrapper)
 * @param {string} filePath - File path
 * @param {Object} options - Analysis options
 * @returns {Promise<Object>} Analysis results
 */
async function analyzeFileStaticBugsAsync(filePath, options = {}) {
  return analyzeFileStaticBugs(filePath, options);
}

/**
 * Detect bug patterns in code content
 * @param {string} content - Code content
 * @param {Object} options - Detection options
 * @returns {Array} Detected bug patterns
 */
function detectBugPatterns(content, options = {}) {
  const bugs = [];
  const lines = content.split('\n');
  
  // Null reference patterns
  if (content.match(/\w+\.\w+/) && !content.includes('if (') && !content.includes('&& ')) {
    bugs.push({
      type: 'null_reference',
      severity: 'HIGH',
      category: 'Null Reference',
      description: 'Potential null reference - property access without null check',
      line: 1
    });
  }
  
  // Undefined variable patterns
  if (content.match(/return \w+/) && !content.match(/(const|let|var)\s+\w+/)) {
    bugs.push({
      type: 'undefined_variable', 
      severity: 'HIGH',
      category: 'Undefined Variable',
      description: 'Variable used without declaration',
      line: 1
    });
  }
  
  // Logic error patterns
  if (content.includes('i <= ') && content.includes('.length')) {
    bugs.push({
      type: 'off_by_one',
      severity: 'MEDIUM', 
      category: 'Logic Error',
      description: 'Potential off-by-one error in loop condition',
      line: 1
    });
  }
  
  // Type mismatch patterns
  if (content.includes(' == ') && !content.includes(' === ')) {
    bugs.push({
      type: 'type_coercion',
      severity: 'MEDIUM',
      category: 'Type Error', 
      description: 'Type coercion with == operator',
      line: 1
    });
  }
  
  // Missing error handling
  if (content.includes('JSON.parse') && !content.includes('try')) {
    bugs.push({
      type: 'missing_error_handling',
      severity: 'MEDIUM',
      category: 'Error Handling',
      description: 'JSON.parse without error handling',
      line: 1
    });
  }
  
  // Missing await patterns
  if (content.includes('fetch(') && !content.includes('await fetch(') && !content.includes('.then(')) {
    bugs.push({
      type: 'missing_await',
      severity: 'HIGH',
      category: 'Async/Await',
      description: 'Missing await keyword for Promise',
      line: 1
    });
  }
  
  return bugs;
}

module.exports = {
  analyzeStaticBugs,
  analyzeFileStaticBugs,
  analyzeProjectStaticBugs,
  detectBugPatterns,
  checkUnreachableCode,
  generateBugRecommendations,
  getQualityGrade
};