agentsqripts/lib/utils/gradeUtils.js

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

/**
 * @file Centralized academic grading system for consistent quality assessment across all analyzers
 * @description Single responsibility: Provide standardized letter grade calculation and description mapping
 * 
 * This utility module implements a consistent academic grading system used across all
 * AgentSqripts analysis tools for quality assessment and scoring. It provides standardized
 * grade calculation based on 0-100 numeric scores and human-readable grade descriptions
 * to ensure consistent quality communication across all analysis domains.
 * 
 * Design rationale:
 * - Academic grading scale provides intuitive quality assessment familiar to all users
 * - Consistent grading prevents confusion when comparing different analysis results
 * - Centralized calculation eliminates duplicate grading logic across analyzers
 * - Standard grade descriptions provide clear quality interpretation
 * - Numeric score input enables flexible integration with different scoring algorithms
 * 
 * Grading scale rationale:
 * - A (90-100): Excellent quality, minimal issues requiring attention
 * - B (80-89): Good quality with minor improvements possible
 * - C (70-79): Average quality requiring moderate attention
 * - D (60-69): Below average quality needing significant improvement
 * - F (0-59): Failing quality requiring immediate comprehensive action
 */

/**
 * Gets letter grade based on numeric score using standard academic grading
 * @param {number} score - Score from 0-100 (higher is better)
 * @returns {string} Letter grade (A-F)
 */
function getLetterGrade(score) {
  if (score >= 90) return 'A';  // Excellent
  if (score >= 80) return 'B';  // Good
  if (score >= 70) return 'C';  // Average
  if (score >= 60) return 'D';  // Below Average
  return 'F';                    // Failing
}

/**
 * Gets grade description based on letter grade
 * @param {string} grade - Letter grade (A-F)
 * @returns {string} Human-readable description
 */
function getGradeDescription(grade) {
  const descriptions = {
    'A': 'Excellent',
    'B': 'Good',
    'C': 'Average', 
    'D': 'Below Average',
    'F': 'Failing'
  };
  return descriptions[grade] || 'Unknown';
}

module.exports = {
  getLetterGrade,
  getGradeDescription
};