agentsqripts/lib/utils/helpers/filterIssues.js

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

/**
 * @file Filter issues by multiple criteria
 * @description Single responsibility: Apply configurable filtering to issues array
 * 
 * This utility provides flexible filtering for issue arrays based on severity levels,
 * categories, and types. It supports minimum severity thresholds and exact matches
 * for categorization, enabling precise result refinement for analysis reports.
 * 
 * Design rationale:
 * - Supports multiple independent filter criteria for flexibility
 * - Severity filtering uses threshold logic (>= minimum level)
 * - Category/type filtering uses exact matching for precision
 * - Immutable approach preserves original issues array
 * - Graceful handling of missing properties and edge cases
 */

/**
 * Filter issues array based on multiple configurable criteria
 * 
 * Technical function: Applies sequential filtering based on provided options
 * 
 * Implementation rationale:
 * - Spread operator creates immutable copy to avoid mutating input
 * - Sequential filtering with reassignment for clean, readable logic
 * - Explicit severity ordering map provides clear threshold semantics
 * - Optional chaining and defaults handle missing properties gracefully
 * - Early returns avoided to allow multiple simultaneous filters
 * 
 * Severity filtering strategy:
 * - Uses ordinal mapping (LOW=1, MEDIUM=2, HIGH=3, CRITICAL=4) for threshold logic
 * - "severity: HIGH" means "HIGH or CRITICAL" (minimum threshold approach)
 * - Default severity level of 1 (LOW) ensures issues without severity aren't filtered
 * - Supports filtering for minimum severity level, not exact matches
 * 
 * Category/Type filtering strategy:
 * - Uses exact string matching for precise categorization
 * - Case-sensitive comparison for consistency with issue classification
 * - Supports any category/type values (not limited to predefined sets)
 * - Filters are additive (AND logic) - issue must match all specified criteria
 * 
 * Performance considerations:
 * - O(n) time complexity for each active filter criterion
 * - Sequential filtering may be less efficient than single-pass, but more readable
 * - Array.filter creates new arrays - memory usage proportional to result size
 * - Severity map lookup is O(1) for each issue
 * 
 * Edge cases handled:
 * - Empty issues array: Returns empty array
 * - Empty options object: Returns copy of original array
 * - Missing severity property: Treated as minimum level (1)
 * - Unknown severity levels: Filtered out by threshold logic
 * - Missing category/type: Not matched by exact string comparison
 * 
 * Alternative approaches considered:
 * - Single-pass filter with complex condition: Rejected for readability
 * - In-place filtering: Rejected to maintain immutability
 * - Regular expression matching: Rejected for category/type as too complex
 * 
 * @param {Array<Object>} issues - Array of issue objects to filter
 * @param {Object} [options={}] - Filter configuration object
 * @param {string} [options.severity] - Minimum severity level (LOW, MEDIUM, HIGH, CRITICAL)
 * @param {string} [options.category] - Exact category match filter
 * @param {string} [options.type] - Exact type match filter
 * @returns {Array<Object>} New array containing issues matching all specified criteria
 */
function filterIssues(issues, options = {}) {
  let filtered = [...issues];
  
  if (options.severity) {
    const severityOrder = { LOW: 1, MEDIUM: 2, HIGH: 3, CRITICAL: 4 };
    const minLevel = severityOrder[options.severity] || 1;
    filtered = filtered.filter(issue => 
      (severityOrder[issue.severity] || 1) >= minLevel
    );
  }
  
  if (options.category) {
    filtered = filtered.filter(issue => issue.category === options.category);
  }
  
  if (options.type) {
    filtered = filtered.filter(issue => issue.type === options.type);
  }
  
  return filtered;
}

module.exports = filterIssues;