agentsqripts/lib/export-promotion/complexityEstimator.js

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

/**
 * @file Code complexity estimation for export promotion prioritization
 * @description Single responsibility: Quantify code complexity to prioritize export candidates
 * 
 * This module implements heuristic-based complexity estimation for code blocks to support
 * export promotion decisions. It combines multiple complexity indicators including control
 * flow structures, function calls, and code length to produce a normalized complexity score
 * that helps prioritize which code blocks are most valuable to promote to reusable exports.
 * 
 * Design rationale:
 * - Multi-factor complexity assessment provides more accurate prioritization
 * - Normalized 1-10 scale enables consistent comparison across different code blocks
 * - Heuristic approach balances accuracy with performance for real-time analysis
 * - Weight-based scoring allows tuning for different types of complexity
 */

/**
 * Estimate code block complexity using multi-factor heuristic analysis
 * 
 * Technical function: Multi-dimensional complexity scoring for export promotion prioritization
 * 
 * Implementation rationale:
 * - Control structure counting measures cognitive complexity and branching logic
 * - Function call analysis identifies API usage density and integration complexity
 * - Line counting provides baseline size-based complexity indication
 * - Weighted scoring prevents any single factor from dominating the assessment
 * 
 * Complexity assessment methodology:
 * - Control structures (if/else/for/while/switch/try/catch) add direct complexity
 * - Function calls indicate external dependencies and interaction complexity
 * - Code length provides baseline complexity floor for larger code blocks
 * - 1-10 scale normalization enables consistent comparison and prioritization
 * 
 * Heuristic weights rationale:
 * - Control structures: 1:1 weight (each adds significant cognitive load)
 * - Function calls: 3:1 ratio (groups of 3 calls add 1 complexity point)
 * - Lines of code: 5:1 ratio (every 5 lines add 1 complexity point)
 * - Maximum cap of 10 prevents extreme scores that skew prioritization
 * 
 * Alternative complexity approaches considered:
 * - AST-based analysis: More accurate but significantly slower
 * - Cyclomatic complexity: More precise but harder to compute quickly
 * - Halstead metrics: Comprehensive but complex to implement efficiently
 * - Simple line counting: Too simplistic, misses logical complexity
 * 
 * Use case optimization:
 * - Export promotion needs fast complexity assessment across many code blocks
 * - Relative ranking is more important than absolute precision
 * - Performance requirements favor heuristic over comprehensive analysis
 * - Good enough accuracy enables effective prioritization without analysis overhead
 * 
 * @param {string} codeBlock - Code block to analyze for complexity assessment
 * @returns {number} Complexity score from 1-10 (1=trivial, 10=very complex)
 * @example
 *   const simpleCode = "const x = 1; return x;";
 *   const complexCode = "if (a) { for (let i=0; i<10; i++) { func(); } }";
 *   console.log(estimateComplexity(simpleCode));  // Returns: 1-2
 *   console.log(estimateComplexity(complexCode)); // Returns: 4-6
 */
function estimateComplexity(codeBlock) {
  let complexity = 1;
  
  // Count control structures
  const controlStructures = (codeBlock.match(/(if|else|for|while|switch|try|catch)/g) || []).length;
  complexity += controlStructures;
  
  // Count function calls
  const functionCalls = (codeBlock.match(/\w+\(/g) || []).length;
  complexity += Math.floor(functionCalls / 3);
  
  // Count lines
  const lines = codeBlock.split('\n').filter(line => line.trim()).length;
  complexity += Math.floor(lines / 5);
  
  return Math.min(10, complexity);
}

module.exports = {
  estimateComplexity
};