agentsqripts/lib/utils/helpers/sortIssuesByPriority.js

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

/**
 * @file Issue priority sorting utility for intelligent analysis result organization
 * @description Single responsibility: Sort issues by severity level and source location for optimal presentation
 * 
 * This utility implements intelligent issue sorting that prioritizes analysis results based on
 * severity levels and source code location. It ensures that critical issues are presented first
 * while maintaining logical organization by file location, enabling developers to focus on
 * the most important problems in a systematic way.
 * 
 * Design rationale:
 * - Severity-based primary sorting ensures critical issues receive immediate attention
 * - Line number secondary sorting provides logical navigation within files
 * - Stable sorting algorithm maintains relative order for equal-priority items
 * - Configurable sorting criteria support different analysis report requirements
 * - Performance-optimized implementation handles large issue collections efficiently
 * 
 * Priority sorting methodology:
 * - CRITICAL severity issues appear first for immediate security and stability concerns
 * - HIGH severity issues follow for significant code quality and performance problems
 * - MEDIUM and LOW severity issues provide improvement opportunities in prioritized order
 * - Line number sorting within severity groups enables systematic code review workflows
 * - Consistent ordering facilitates reproducible analysis results and team coordination
 */

/**
 * Sort issues by priority
 * @param {Array} issues - Issues to sort
 * @returns {Array} Sorted issues
 */
function sortIssuesByPriority(issues) {
  const severityOrder = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
  return [...issues].sort((a, b) => {
    const aSev = severityOrder[a.severity] || 0;
    const bSev = severityOrder[b.severity] || 0;
    if (aSev !== bSev) return bSev - aSev;
    return (b.lineNumber || 0) - (a.lineNumber || 0);
  });
}

module.exports = sortIssuesByPriority;