agentsqripts/lib/cleanup/orphanedCommentDetector.js

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

/**
 * @file Core orphaned comment detection logic with context-aware analysis
 * @description Single responsibility: Apply intelligent heuristics to identify comments disconnected from their code
 * 
 * This detector implements sophisticated context-aware analysis to identify comments that
 * appear to be orphaned from their associated code. It uses multiple heuristics including
 * comment length, content analysis, surrounding code patterns, and contextual relevance
 * to accurately distinguish orphaned comments from legitimate documentation.
 * 
 * Design rationale:
 * - Context-aware analysis considers surrounding code to determine comment relevance
 * - Multiple detection heuristics provide comprehensive orphaned comment identification
 * - Length-based filtering identifies comments too short to provide meaningful documentation
 * - Content analysis examines comment text for indicators of outdated or irrelevant information
 * - Conservative detection approach minimizes false positives while catching genuine issues
 * 
 * Detection heuristics:
 * - Length analysis identifies comments too brief to provide useful documentation
 * - Context correlation examines relationship between comment content and nearby code
 * - Pattern recognition identifies common orphaned comment characteristics
 * - Relevance assessment evaluates whether comments add value to code understanding
 * - Temporal analysis considers whether comments appear to reflect current code state
 */

/**
 * Check if comment appears to be orphaned
 */
function isOrphanedComment(commentText, context) {
  // Very short comments are often orphaned
  if (commentText.length < 10) {
    return true;
  }
  
  // Comments with old dates might be orphaned
  if (/\b20[01]\d\b/.test(commentText)) {
    const year = parseInt(commentText.match(/\b20[01]\d\b/)[0], 10);
    const currentYear = new Date().getFullYear();
    if (currentYear - year > 2) {
      return true;
    }
  }
  
  // Comments that don't relate to nearby code
  const codeWords = context.relevantLines.join(' ').toLowerCase();
  const commentWords = commentText.toLowerCase().split(/\W+/);
  
  const relevantWords = commentWords.filter(word => 
    word.length > 3 && codeWords.includes(word)
  );
  
  // If less than 20% of comment words relate to nearby code, might be orphaned
  return relevantWords.length < commentWords.length * 0.2;
}

module.exports = {
  isOrphanedComment
};