agentsqripts/lib/performance/ast/string-concat/createIssue.js

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

/**
 * @file Create string concatenation issue object with detailed context
 * @description Single responsibility: Generate standardized issue objects for performance analysis
 * 
 * This utility creates comprehensive issue objects for string concatenation performance
 * problems detected in loops. It combines AST node information with performance metrics
 * to provide actionable feedback for developers about inefficient string operations.
 * 
 * Design rationale:
 * - Standardized issue format enables consistent reporting across all performance analyzers
 * - Rich context information helps developers understand and fix performance issues
 * - AST-based location tracking provides precise source code references
 * - Performance impact estimates help prioritize optimization efforts
 */

const { getNodeLine, getNodeSource } = require('../astParser');
const getLoopType = require('./getLoopType');

/**
 * Create comprehensive issue object for string concatenation performance problems
 * 
 * Technical function: Transforms AST analysis results into actionable issue reports
 * 
 * Implementation rationale:
 * - Combines multiple data sources (AST nodes, file content, patterns) into unified issue
 * - Uses helper functions for consistent location and source code extraction
 * - Includes both technical details and human-readable descriptions
 * - Provides specific performance estimates based on established benchmarks
 * 
 * Issue object structure design:
 * - type: Unique identifier for issue classification and filtering
 * - severity/category: From pattern configuration for consistent priority handling
 * - location: Standard format (file:line) for IDE integration and navigation
 * - code: Extracted source code for context and verification
 * - loopType: Specific loop construct for targeted recommendations
 * 
 * Performance analysis integration:
 * - Loop type detection enables context-specific recommendations
 * - Estimated savings based on real-world benchmarks (array.join vs string concat)
 * - Effort estimates help teams prioritize refactoring work
 * - Impact descriptions connect technical issues to business value
 * 
 * Context information strategy:
 * - File path and line number enable precise navigation to problematic code
 * - Source code snippet provides immediate context without opening files
 * - Loop type classification enables targeted optimization recommendations
 * - Performance estimates based on empirical testing of string operations
 * 
 * String concatenation performance rationale:
 * - String concatenation in loops creates new string objects each iteration
 * - Array.push() + join() pattern reuses array capacity and performs single allocation
 * - Performance difference becomes significant with iteration counts > 100
 * - Memory pressure reduction improves garbage collection performance
 * 
 * Alternative approaches considered:
 * - Generic issue template: Rejected as less informative for specific performance problems
 * - Separate metadata objects: Rejected to maintain single source of truth
 * - Dynamic property generation: Rejected for predictable object structure
 * 
 * @param {Object} node - AST node representing the string concatenation operation
 * @param {Object} loop - AST node representing the containing loop construct
 * @param {string} content - Complete source code content for context extraction
 * @param {string} filePath - File path for issue location identification
 * @param {Object} pattern - Pattern configuration object with severity and effort data
 * @returns {Object} Comprehensive issue object with location, context, and recommendations
 * @example
 *   // For: for(let i=0; i<items.length; i++) { result += items[i]; }
 *   {
 *     type: 'string_concat_loop',
 *     severity: 'MEDIUM',
 *     location: 'src/processor.js:15',
 *     code: 'result += items[i]',
 *     loopType: 'for',
 *     description: 'String concatenation in for creates new strings each iteration',
 *     recommendation: 'Use array.push() and join() instead of string concatenation',
 *     estimatedSavings: '20-40% performance gain for string operations'
 *   }
 */
function createIssue(node, loop, content, filePath, pattern) {
  const line = getNodeLine(node);
  const loopType = getLoopType(loop);
  
  return {
    type: 'string_concat_loop',
    severity: pattern.severity,
    category: pattern.category,
    location: `${filePath}:${line}`,
    line: line,
    code: getNodeSource(content, node).trim(),
    loopType: loopType,
    description: `String concatenation in ${loopType} creates new strings each iteration`,
    summary: `Inefficient string concatenation in ${loopType}`,
    recommendation: 'Use array.push() and join() instead of string concatenation',
    effort: pattern.effort,
    impact: pattern.impact,
    estimatedSavings: '20-40% performance gain for string operations'
  };
}

module.exports = createIssue;