agentsqripts/lib/cleanup/commentValidator.js

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

/**
 * @file Comment validation utility for documentation quality assessment
 * @description Single responsibility: Determine validity and quality of code comments through systematic analysis
 * 
 * This validator implements comprehensive comment quality assessment to distinguish between
 * valuable documentation and comments that should be flagged for review or removal. It
 * analyzes comment content, structure, and contextual relevance to provide accurate
 * validation results that support code quality improvement workflows.
 * 
 * Design rationale:
 * - Quality-focused validation helps maintain high documentation standards
 * - Systematic analysis criteria provide consistent comment assessment across codebases
 * - Context-aware validation considers surrounding code to determine comment relevance
 * - Conservative approach preserves valuable documentation while flagging problematic comments
 * - Standardized validation enables automated documentation quality improvements
 * 
 * Validation criteria:
 * - Content quality assessment examines usefulness and clarity of comment text
 * - Structural analysis evaluates comment format and placement appropriateness
 * - Contextual relevance determines whether comments accurately reflect associated code
 * - Length and detail assessment ensures comments provide sufficient information
 * - Pattern recognition identifies common valid and invalid comment characteristics
 */

/**
 * Check if comment is likely valid and should not be flagged
 */
function isLikelyValidComment(commentText) {
  const validPatterns = [
    /^@\w+/,           // JSDoc tags
    /TODO|FIXME|HACK/i, // TODO comments
    /^\s*\w+:/,        // Parameter descriptions
    /^\s*\*/,          // JSDoc continuation
    /eslint|prettier/i, // Tool directives
    /^\s*[A-Z][a-z]/   // Proper sentences
  ];
  
  return validPatterns.some(pattern => pattern.test(commentText)) ||
         commentText.length > 30; // Longer comments more likely to be valid
}

module.exports = {
  isLikelyValidComment
};