agentsqripts/lib/utils/errorMessages.js

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

/**
 * @file Centralized error message utilities for consistent error handling
 * @description Single responsibility: Provide standardized error logging across AgentSqripts
 * 
 * This utility module provides consistent error message formatting and logging
 * for different types of errors that occur throughout the AgentSqripts platform.
 * It standardizes error reporting to improve debugging and maintenance workflows.
 * 
 * Design rationale:
 * - Centralized error formatting ensures consistent error presentation
 * - Context-specific loggers provide targeted error information
 * - Simple console.error usage maintains compatibility across environments
 * - Stack trace inclusion aids in debugging complex analysis failures
 */

/**
 * Log general error with contextual information
 * 
 * Technical function: Provides standardized error logging with context identification
 * 
 * Implementation rationale:
 * - Template literal formatting ensures consistent error message structure
 * - Context parameter provides specific operation identification for debugging
 * - Direct console.error usage maintains simplicity and broad compatibility
 * - Error.message extraction focuses on relevant error information
 * 
 * Error handling strategy:
 * - Context-first approach helps identify where errors occurred
 * - Standardized format enables easy parsing by log aggregation tools
 * - Simple implementation reduces chance of logging errors during error handling
 * - No additional formatting reduces performance overhead during error conditions
 * 
 * @param {string} context - Error context description (e.g., "reading configuration")
 * @param {Error} error - Error object containing message and optional stack trace
 * @example
 *   logError("parsing AST", new Error("Unexpected token"))
 *   // Outputs: "Error parsing AST: Unexpected token"
 */
function logError(context, error) {
  console.error(`Error ${context}: ${error.message}`);
}

/**
 * Log file system access errors with path information
 * 
 * Technical function: Specialized error logging for file system operations
 * 
 * Implementation rationale:
 * - File path inclusion provides immediate context for file system errors
 * - Specialized function enables consistent file error formatting
 * - Template literal maintains readability while providing structured output
 * - Focused on file access scenarios (read, write, stat, etc.)
 * 
 * File system error patterns:
 * - ENOENT: File or directory not found
 * - EACCES: Permission denied
 * - EISDIR: Expected file but found directory
 * - EMFILE: Too many open files
 * 
 * @param {string} filePath - Full or relative path to file that caused error
 * @param {Error} error - File system error object
 * @example
 *   logFileError("/path/to/missing.js", new Error("ENOENT: no such file"))
 *   // Outputs: "Error accessing /path/to/missing.js: ENOENT: no such file"
 */
function logFileError(filePath, error) {
  console.error(`Error accessing ${filePath}: ${error.message}`);
}

/**
 * Log analysis operation errors with stack traces for debugging
 * 
 * Technical function: Specialized error logging for analysis operations with enhanced debugging
 * 
 * Implementation rationale:
 * - Analysis type specification helps identify which analyzer failed
 * - Stack trace inclusion provides detailed debugging information for complex failures
 * - Conditional stack logging prevents undefined access while providing maximum debug info
 * - Analysis-specific formatting aids in troubleshooting analyzer issues
 * 
 * Analysis error scenarios:
 * - AST parsing failures in complex JavaScript
 * - Memory exhaustion during large project analysis
 * - Timeout errors in long-running analysis operations
 * - Dependency resolution failures in cross-file analysis
 * 
 * Debug information strategy:
 * - Primary error message for immediate issue identification
 * - Optional stack trace for detailed debugging and error source location
 * - Analysis type helps categorize errors for systematic improvements
 * - Comprehensive logging aids in identifying patterns across analysis failures
 * 
 * @param {string} analysisType - Type of analysis operation (e.g., "complexity", "performance")
 * @param {Error} error - Analysis error object with message and optional stack trace
 * @example
 *   logAnalysisError("WET code", new Error("Failed to extract semantic blocks"))
 *   // Outputs: "Error during WET code analysis: Failed to extract semantic blocks"
 *   //          [stack trace if available]
 */
function logAnalysisError(analysisType, error) {
  console.error(`Error during ${analysisType} analysis: ${error.message}`);
  if (error.stack) {
    console.error(error.stack);
  }
}

/**
 * Log JSON serialization and file writing errors
 * 
 * Technical function: Specialized error logging for JSON output operations
 * 
 * Implementation rationale:
 * - JSON-specific error handling for report generation failures
 * - File path inclusion enables quick identification of output location issues
 * - Focused on serialization and file writing scenarios
 * - Template formatting maintains consistency with other error loggers
 * 
 * JSON writing error scenarios:
 * - Circular reference errors during JSON.stringify
 * - Disk space exhaustion during large report generation
 * - Permission errors when writing to protected directories
 * - Invalid file path errors for output location
 * 
 * Output operation considerations:
 * - Report generation failures can lose analysis results
 * - JSON serialization errors may indicate data structure issues
 * - File writing errors often indicate environmental problems
 * - Clear error messages help distinguish between data and file system issues
 * 
 * @param {string} filePath - Target file path for JSON output
 * @param {Error} error - JSON writing or serialization error
 * @example
 *   logJsonWriteError("reports/analysis.json", new Error("ENOSPC: no space left"))
 *   // Outputs: "Error writing JSON to reports/analysis.json: ENOSPC: no space left"
 */
function logJsonWriteError(filePath, error) {
  console.error(`Error writing JSON to ${filePath}: ${error.message}`);
}

module.exports = {
  logError,
  logFileError,
  logAnalysisError,
  logJsonWriteError
};