agentsqripts/cli/lib/errorHandler.js

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

/**
 * @file Centralized error handling system for consistent CLI tool behavior
 * @description Single responsibility: Provide standardized error handling and process exit management
 * 
 * This error handling module ensures consistent error reporting, graceful failure modes,
 * and standardized exit behavior across all AgentSqripts CLI tools. It provides typed
 * error handlers for different failure scenarios and severity-based exit strategies
 * to support both interactive and automated usage patterns.
 * 
 * Design rationale:
 * - Consistent error messaging improves user experience across all CLI tools
 * - Structured exit codes enable automation and CI/CD integration
 * - Graceful error handling prevents tool crashes and data loss
 * - Severity-based exit strategies support different operational contexts
 * - Centralized handling reduces code duplication across CLI implementations
 */

/**
 * Handle analysis errors with contextual formatting and configurable exit behavior
 * 
 * Technical function: Standardized error reporting with analysis context and exit control
 * 
 * Implementation rationale:
 * - Analysis type context helps users understand which tool component failed
 * - Configurable exit behavior supports both interactive debugging and automation
 * - Consistent error formatting enables log parsing and monitoring integration
 * - Flexible error input handling supports both Error objects and string messages
 * 
 * Error formatting strategy:
 * - Analysis-specific prefixes clarify the failure context
 * - Generic analysis handler provides fallback for unknown analysis types
 * - Error message extraction handles both Error objects and plain strings
 * - Exit behavior control enables different operational modes
 * 
 * Usage patterns:
 * - Interactive development: exitOnError=false for continued debugging
 * - Automation/CI: exitOnError=true for immediate failure signaling
 * - Analysis tools: context-specific error messages for precise troubleshooting
 * - Library usage: flexible exit control for different integration scenarios
 * 
 * @param {Error|string} error - Error object with message property or direct error message string
 * @param {string} analysisType - Analysis context identifier (e.g., 'cleanup', 'performance', 'security')
 * @param {boolean} exitOnError - Process exit control: true for immediate exit, false for continued execution
 * @example
 *   handleAnalysisError(new Error('File not found'), 'security', true);
 *   // Output: "Error analyzing security: File not found" + process.exit(1)
 */
function handleAnalysisError(error, analysisType = 'analysis', exitOnError = true) {
  const errorMessage = error.message || error;
  
  if (analysisType === 'generic') {
    console.error(`❌ Analysis failed: ${errorMessage}`);
  } else {
    console.error(`Error analyzing ${analysisType}: ${errorMessage}`);
  }
  
  if (exitOnError) {
    process.exit(1);
  }
}

/**
 * Handle file access errors
 * @param {string} filePath - Path that failed to access
 * @param {boolean} exitOnError - Whether to exit process on error (default: true)
 */
function handleFileAccessError(filePath, exitOnError = true) {
  console.error(`Error: Path '${filePath}' does not exist`);
  
  if (exitOnError) {
    process.exit(1);
  }
}

/**
 * Exit with appropriate code based on analysis results
 * @param {Object} results - Analysis results object
 * @param {Object} options - Options for exit conditions
 * @param {string} options.severityField - Field name for severity breakdown (default: 'severityBreakdown')
 * @param {string} options.criticalLevel - Critical level name (default: 'CRITICAL')
 * @param {string} options.highLevel - High level name (default: 'HIGH')
 * @param {boolean} options.exitOnHigh - Whether to exit on high severity (default: true)
 * @param {boolean} options.exitOnCritical - Whether to exit on critical severity (default: true)
 */
function exitOnSeverityThreshold(results, options = {}) {
  const {
    severityField = 'severityBreakdown',
    criticalLevel = 'CRITICAL',
    highLevel = 'HIGH',
    exitOnHigh = true,
    exitOnCritical = true
  } = options;
  
  const severity = results.summary?.[severityField] || {};
  
  if (exitOnCritical && severity[criticalLevel] > 0) {
    process.exit(1);
  }
  
  if (exitOnHigh && severity[highLevel] > 0) {
    process.exit(1);
  }
}

/**
 * Wrap async main function with standard error handling
 * @param {Function} mainFn - Async main function to execute
 * @param {string} analysisType - Type of analysis for error messages
 */
async function runWithErrorHandling(mainFn, analysisType = 'analysis') {
  try {
    await mainFn();
  } catch (error) {
    handleAnalysisError(error, analysisType);
  }
}

module.exports = {
  handleAnalysisError,
  handleFileAccessError,
  exitOnSeverityThreshold,
  runWithErrorHandling
};