agentsqripts/lib/cleanup/orphanedCommentScanner.js

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

/**
 * @file Orphaned comment scanner for code quality improvement identification
 * @description Single responsibility: Identify comments that lack clear relationship to surrounding code
 * 
 * This scanner performs comprehensive analysis to identify orphaned comments that may indicate
 * areas where code has changed but comments were not updated, or where comments provide
 * unclear or outdated information. It serves as a key component in maintaining code quality
 * by flagging documentation that needs attention or removal.
 * 
 * Design rationale:
 * - Orphaned comment detection improves overall code documentation quality
 * - Context-aware analysis considers surrounding code patterns for accurate identification
 * - Multi-validator approach combines different detection strategies for comprehensive coverage
 * - Block and line comment analysis handles different comment patterns appropriately
 * - Quality scoring enables prioritization of documentation improvement efforts
 * 
 * Detection methodology:
 * - Context analysis examines relationship between comments and adjacent code
 * - Pattern matching identifies common orphaned comment characteristics
 * - Block comment extraction enables detailed analysis of multi-line documentation
 * - Validation pipeline combines multiple detection heuristics for accuracy
 * - Comprehensive scanning covers all comment types and placement patterns
 */

const { isLikelyValidComment } = require('./commentValidator');
const { isOrphanedComment } = require('./orphanedCommentDetector');
const { isLikelyOrphanedBlock } = require('./blockCommentValidator');
const { extractBlockComment } = require('./blockCommentExtractor');

/**
 * Find orphaned comments (comments that don't seem to relate to nearby code)
 */
function findOrphanedComments(content) {
  const orphanedComments = [];
  const lines = content.split('\n');
  
  lines.forEach((line, index) => {
    const trimmed = line.trim();
    
    // Check for single-line comments
    if (trimmed.startsWith('//')) {
      const commentText = trimmed.substring(2).trim();
      
      // Skip common comment patterns that are likely valid
      if (isLikelyValidComment(commentText)) {
        return;
      }
      
      // Check context around the comment
      const context = getCommentContext(lines, index);
      
      // If comment doesn't relate to surrounding code, it might be orphaned
      if (isOrphanedComment(commentText, context)) {
        orphanedComments.push({
          line: index + 1,
          comment: commentText,
          context: context.relevantLines
        });
      }
    }
    
    // Check for block comments that might be outdated
    if (trimmed.startsWith('/*') && !trimmed.includes('*')) {
      const blockComment = extractBlockComment(lines, index);
      if (blockComment && isLikelyOrphanedBlock(blockComment.text)) {
        orphanedComments.push({
          line: index + 1,
          comment: blockComment.text,
          type: 'block'
        });
      }
    }
  });
  
  return orphanedComments;
}

/**
 * Get context around a comment
 */
function getCommentContext(lines, commentIndex) {
  const context = {
    before: lines.slice(Math.max(0, commentIndex - 2), commentIndex),
    after: lines.slice(commentIndex + 1, commentIndex + 3),
    relevantLines: []
  };
  
  // Get nearby non-empty lines
  for (let i = Math.max(0, commentIndex - 3); i < Math.min(lines.length, commentIndex + 4); i++) {
    if (i !== commentIndex && lines[i].trim()) {
      context.relevantLines.push(lines[i].trim());
    }
  }
  
  return context;
}

module.exports = {
  findOrphanedComments,
  getCommentContext
};