agentsqripts/lib/srp-violations/analyzeSRPViolations.js

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

/**
 * @file Single Responsibility Principle analysis orchestrator for architecture assessment
 * @description Single responsibility: Coordinate SRP violation detection with intelligent context awareness
 * 
 * This analyzer identifies potential Single Responsibility Principle violations by analyzing
 * function distribution, responsibility clustering, and architectural cohesion. It provides
 * nuanced assessment that distinguishes between legitimate multi-function modules and genuine
 * architectural issues requiring refactoring attention.
 * 
 * Design rationale:
 * - Context-aware analysis prevents false positives on legitimate multi-function modules
 * - Function distribution analysis identifies potential responsibility clustering
 * - Intelligent scoring balances mathematical metrics with architectural wisdom
 * - Usage guidance integration provides actionable architectural recommendations
 * - Conservative approach minimizes unnecessary refactoring suggestions
 */

const fs = require('fs');
const { promises: fsPromises } = require('fs');
const path = require('path');
const { scoreFileForSRP } = require('./srpFileScorer');
const { analyzeSingleFile } = require('./srpSingleFileAnalyzer');
const { analyzeSRPViolations: analyzeProjectSRP } = require('./srpProjectAnalyzer');

/**
 * Analyze SRP violations with intelligent context-aware assessment and architectural guidance
 * 
 * Technical function: Unified SRP analysis interface with intelligent architectural assessment
 * 
 * Implementation rationale:
 * - Function distribution analysis provides quantitative foundation for SRP assessment
 * - Context-aware scoring prevents false positives on utility and helper modules
 * - Architectural guidance balances mathematical metrics with practical development wisdom
 * - Conservative approach minimizes disruptive refactoring recommendations
 * 
 * SRP assessment philosophy:
 * - High function count doesn't automatically indicate violations
 * - Related functions may legitimately belong together in utility modules
 * - Architectural context (utils, helpers, config) affects SRP interpretation
 * - Refactoring recommendations should prioritize clear architectural benefits
 * 
 * Analysis dimensions:
 * - Function count and distribution patterns
 * - Responsibility clustering and semantic cohesion
 * - Module purpose and architectural role
 * - Refactoring complexity and benefit assessment
 * 
 * Important guidance considerations:
 * - High scores indicate function density, not necessarily architectural problems
 * - Consider whether functions share genuine responsibility before splitting
 * - Utility modules naturally contain multiple related functions
 * - Focus on clear architectural benefits rather than metric optimization
 * 
 * For detailed decision-making guidance, see lib/srp-violations/USAGE-GUIDANCE.md
 * 
 * @param {string} target - File or directory path for SRP analysis
 * @param {Object} options - Analysis configuration with context-aware settings
 * @returns {Promise<Object>} Comprehensive SRP analysis with architectural recommendations
 * @example
 *   const results = await analyzeSRPViolations('./src/utils', { threshold: 'conservative' });
 *   // Returns analysis with context-aware SRP assessment and architectural guidance
 */
async function analyzeSRPViolations(target, options = {}) {
  const stat = await fsPromises.stat(target);
  if (stat.isDirectory()) {
    return await analyzeProjectSRP(target, options);
  } else {
    return await analyzeSingleFile(target, options);
  }
}

module.exports = {
  analyzeSRPViolations,
  analyzeSingleFile,
  scoreFileForSRP
};