agentsqripts/lib/utils/helpers/analyzeSingleFile.js

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

/**
 * @file Analyze single file with comprehensive error handling
 * @description Single responsibility: Execute file analysis with robust error recovery
 * 
 * This utility serves as a critical wrapper for all file analysis operations across
 * the AgentSqripts platform. It provides consistent error handling, standardized
 * result formatting, and ensures analysis pipelines can continue even when individual
 * files fail to process.
 * 
 * Design rationale:
 * - Centralized error handling prevents analysis pipeline failures
 * - Consistent result format enables uniform processing downstream
 * - Graceful degradation allows partial results when some files fail
 * - Detailed error context helps with debugging and user feedback
 */

const fs = require('fs').promises;

/**
 * Execute analysis function on a single file with comprehensive error handling
 * 
 * Technical function: Reads file content, executes analysis, and returns standardized result
 * 
 * Implementation rationale:
 * - Uses fs.promises for async/await compatibility and better error handling
 * - UTF-8 encoding assumption works for all JavaScript/text files in scope
 * - Spread operator preserves all analyzer-specific result properties
 * - Error object includes context for debugging and user feedback
 * - Empty issues array ensures consistent interface for failed analyses
 * 
 * Error handling strategy:
 * - Try/catch prevents individual file failures from stopping batch operations
 * - Error messages include file path and original error for debugging
 * - Failed analyses return empty issues array (not null) for consistency
 * - Error property explicitly set to null on success for clear status indication
 * 
 * Result format considerations:
 * - filePath included for context in batch operations
 * - Spread operator preserves analyzer-specific properties (issues, metrics, etc.)
 * - error field provides clear success/failure indication
 * - Consistent schema enables uniform processing in analysis aggregators
 * 
 * Performance considerations:
 * - File reading is async to prevent blocking on large files
 * - Error handling is lightweight to avoid performance impact
 * - Memory usage is bounded by single file size (not accumulated)
 * 
 * Alternative approaches considered:
 * - Synchronous file reading: Rejected due to blocking behavior
 * - Throwing errors instead of returning them: Rejected as too disruptive
 * - Different result schema: Rejected to maintain consistency with existing code
 * 
 * @param {string} filePath - Absolute or relative path to file for analysis
 * @param {Function} analyzeFunc - Analysis function that takes (content, filePath)
 * @param {string} analyzerName - Human-readable analyzer name for error context
 * @returns {Promise<Object>} Analysis result with standardized format:
 *   - filePath: Original file path for reference
 *   - error: Error message string or null if successful
 *   - ...rest: All properties returned by analyzeFunc
 *   - issues: Array of issues found (empty array if error occurred)
 */
async function analyzeSingleFile(filePath, analyzeFunc, analyzerName) {
  try {
    const content = await fs.readFile(filePath, 'utf-8');
    const result = await analyzeFunc(content, filePath);
    return {
      filePath,
      ...result,
      error: null
    };
  } catch (error) {
    return {
      filePath,
      error: `Failed to analyze ${filePath}: ${error.message}`,
      issues: []
    };
  }
}

module.exports = analyzeSingleFile;