pumuki-ast-hooks 5.3.1

package/scripts/hooks-system/infrastructure/orchestration/intelligent-audit.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+
+const { evaluateViolations } = require('../severity/severity-evaluator');
+const { GatePolicies } = require('../severity/policies/gate-policies');
+const { ReportGenerator } = require('../reporting/report-generator');
+const { SeverityTracker } = require('../reporting/severity-tracker');
+const { TokenManager } = require('../utils/token-manager');
+const { toErrorMessage } = require('../utils/error-utils');
+const fs = require('fs');
+const path = require('path');
+
+function resolveAuditTmpDir() {
+  const configured = (process.env.AUDIT_TMP || '').trim();
+  if (configured.length > 0) {
+    return path.isAbsolute(configured) ? configured : path.join(process.cwd(), configured);
+  }
+  return path.join(process.cwd(), '.audit_tmp');
+}
+
+/**
+ * Main orchestration function
+ * Called by audit.sh after AST analysis completes
+ */
+async function runIntelligentAudit() {
+  try {
+    console.log('[Intelligent Audit] Starting severity evaluation...');
+
+    const rawViolations = loadRawViolations();
+    console.log(`[Intelligent Audit] Loaded ${rawViolations.length} violations from AST`);
+
+    const gateScope = String(process.env.AI_GATE_SCOPE || 'staging').trim().toLowerCase();
+    const isRepoScope = gateScope === 'repo' || gateScope === 'repository';
+
+    let violationsForGate = [];
+    let violationsForEvidence = [];
+
+    if (isRepoScope) {
+      console.log('[Intelligent Audit] Gate scope: REPOSITORY');
+      violationsForGate = rawViolations;
+      violationsForEvidence = rawViolations;
+    } else {
+      const stagedFiles = getStagedFiles();
+      const stagedViolations = rawViolations.filter(v =>
+        stagedFiles.some(sf => v.filePath && v.filePath.includes(sf))
+      );
+
+      console.log(`[Intelligent Audit] Gate scope: STAGING (${stagedFiles.length} files)`);
+      console.log(`[Intelligent Audit] Filtered to ${stagedViolations.length} violations in staged files`);
+
+      violationsForGate = stagedViolations;
+      violationsForEvidence = stagedViolations;
+    }
+
+    if (violationsForGate.length === 0) {
+      console.log('[Intelligent Audit] ✅ No violations in staged files - PASSED');
+      const enhancedAll = evaluateViolations(violationsForEvidence);
+      const gateResult = { passed: true, exitCode: 0, blockedBy: null };
+      const tokenManager = new TokenManager();
+      const tokenUsage = tokenManager.estimate(enhancedAll, {});
+      updateAIEvidence(enhancedAll, gateResult, tokenUsage);
+      process.exit(0);
+    }
+
+    console.log('[Intelligent Audit] Evaluating severities...');
+    const enhancedViolations = evaluateViolations(violationsForGate);
+
+    const intelligentCount = enhancedViolations.filter(v => v.intelligentEvaluation).length;
+    console.log(`[Intelligent Audit] ✅ ${intelligentCount}/${enhancedViolations.length} violations intelligently evaluated`);
+
+    console.log('[Intelligent Audit] Applying quality gate...');
+    const gatePolicies = new GatePolicies();
+    const gateResult = gatePolicies.apply(enhancedViolations);
+
+    console.log(`[Intelligent Audit] Gate status: ${gateResult.passed ? '✅ PASSED' : '❌ FAILED'}`);
+    if (gateResult.blockedBy) {
+      console.log(`[Intelligent Audit] Blocked by: ${gateResult.blockedBy} violations`);
+    }
+
+    console.log('[Intelligent Audit] Generating reports...');
+    const reportGenerator = new ReportGenerator();
+    const reportPaths = reportGenerator.save(enhancedViolations, gateResult);
+
+    console.log(`[Intelligent Audit] ✅ Reports saved:`);
+    console.log(`  - JSON: ${reportPaths.jsonPath}`);
+    console.log(`  - Text: ${reportPaths.textPath}`);
+
+    const tracker = new SeverityTracker();
+    tracker.record(enhancedViolations, gateResult);
+
+    const trend = tracker.getTrend(10);
+    if (trend.trend !== 'INSUFFICIENT_DATA') {
+      console.log(`[Intelligent Audit] 📈 Trend: ${trend.trend} (avg score ${trend.latest.averageScore}/100)`);
+    }
+
+    const tokenManager = new TokenManager();
+    const report = reportGenerator.generate(enhancedViolations, gateResult);
+    const tokenUsage = tokenManager.estimate(enhancedViolations, report);
+    const warning = tokenManager.checkWarnings(tokenUsage);
+
+    if (warning.shouldWarn) {
+      console.log(`[Token Manager] ${warning.message}`);
+    }
+
+    tokenManager.record(tokenUsage);
+
+    updateAIEvidence(enhancedViolations, gateResult, tokenUsage);
+
+    saveEnhancedViolations(enhancedViolations);
+
+    console.log('[Intelligent Audit] ✅ Complete');
+
+    process.exit(gateResult.exitCode);
+
+  } catch (auditExecutionError) {
+    process.stderr.write(`[Intelligent Audit] ❌ Fatal error during audit execution: ${toErrorMessage(auditExecutionError)}\n`);
+    throw auditExecutionError;
+  }
+}
+
+function loadRawViolations() {
+  const astSummaryPath = path.join(resolveAuditTmpDir(), 'ast-summary.json');
+
+  if (!fs.existsSync(astSummaryPath)) {
+    console.error('[Intelligent Audit] ⚠️  No ast-summary.json found - running without violations');
+    return [];
+  }
+
+  const astSummary = JSON.parse(fs.readFileSync(astSummaryPath, 'utf8'));
+
+  return astSummary.findings || astSummary.violations || [];
+}
+
+function getStagedFiles() {
+  const { execSync } = require('child_process');
+
+  try {
+    const result = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+    return result.trim().split('\n').filter(f => f);
+  } catch (error) {
+    process.stderr.write(`[Intelligent Audit] ⚠️  Failed to read staged files: ${toErrorMessage(error)}\n`);
+    return [];
+  }
+}
+
+function saveEnhancedViolations(violations) {
+  const outputPath = path.join(resolveAuditTmpDir(), 'ast-summary-enhanced.json');
+
+  const enhanced = {
+    timestamp: new Date().toISOString(),
+    generator: 'AST Intelligence v2.0 with Severity Evaluation',
+    intelligentEvaluation: true,
+    totalViolations: violations.length,
+    findings: violations,
+    summary: {
+      total: violations.length,
+      CRITICAL: violations.filter(v => v.severity === 'CRITICAL').length,
+      HIGH: violations.filter(v => v.severity === 'HIGH').length,
+      MEDIUM: violations.filter(v => v.severity === 'MEDIUM').length,
+      LOW: violations.filter(v => v.severity === 'LOW').length
+    }
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  } catch (error) {
+    process.stderr.write(`[Intelligent Audit] ⚠️  Failed to create output directory: ${toErrorMessage(error)}\n`);
+  }
+  fs.writeFileSync(outputPath, JSON.stringify(enhanced, null, 2));
+}
+
+function updateAIEvidence(violations, gateResult, tokenUsage) {
+  const evidencePath = '.AI_EVIDENCE.json';
+
+  if (!fs.existsSync(evidencePath)) {
+    console.warn('[Intelligent Audit] ⚠️  .AI_EVIDENCE.json not found - skipping update');
+    return;
+  }
+
+  try {
+    const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf8'));
+
+    evidence.severity_metrics = {
+      last_updated: new Date().toISOString(),
+      total_violations: violations.length,
+      by_severity: {
+        CRITICAL: violations.filter(v => v.severity === 'CRITICAL').length,
+        HIGH: violations.filter(v => v.severity === 'HIGH').length,
+        MEDIUM: violations.filter(v => v.severity === 'MEDIUM').length,
+        LOW: violations.filter(v => v.severity === 'LOW').length
+      },
+      average_severity_score: Math.round(
+        violations.filter(v => v.severityScore).reduce((sum, v) => sum + v.severityScore, 0) /
+        Math.max(1, violations.filter(v => v.severityScore).length)
+      ),
+      intelligent_evaluation_rate: Math.round(
+        (violations.filter(v => v.intelligentEvaluation).length / Math.max(1, violations.length)) * 100
+      ),
+      gate_status: gateResult.passed ? 'PASSED' : 'FAILED',
+      blocked_by: gateResult.blockedBy || null
+    };
+
+    evidence.token_usage = {
+      estimated: tokenUsage.estimated,
+      percent_used: Math.round(tokenUsage.percentUsed),
+      remaining: tokenUsage.remaining,
+      warning_level: tokenUsage.percentUsed > 95 ? 'CRITICAL' :
+        tokenUsage.percentUsed > 85 ? 'WARNING' :
+          tokenUsage.percentUsed > 75 ? 'INFO' : 'OK'
+    };
+
+    const { execSync } = require('child_process');
+    const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+
+    const resolveBaseBranch = () => {
+        const configured = process.env.AST_BASE_BRANCH;
+        if (configured && configured.trim().length > 0) {
+            return configured.trim();
+        }
+        try {
+            execSync('git show-ref --verify --quiet refs/heads/develop', { stdio: 'ignore' });
+            return 'develop';
+        } catch {
+            try {
+                execSync('git show-ref --verify --quiet refs/heads/main', { stdio: 'ignore' });
+                return 'main';
+            } catch {
+                return 'main';
+            }
+        }
+    };
+    const baseBranch = resolveBaseBranch();
+    const isProtected = ['main', 'master', baseBranch].includes(currentBranch);
+    const criticalViolations = violations.filter(v => v.severity === 'CRITICAL');
+    const highViolations = violations.filter(v => v.severity === 'HIGH');
+    const blockingViolations = [...criticalViolations, ...highViolations].slice(0, 50);
+
+    const gateScope = String(process.env.AI_GATE_SCOPE || 'staging').trim().toLowerCase();
+
+    const existingGate = evidence.ai_gate && typeof evidence.ai_gate === 'object' ? evidence.ai_gate : null;
+    let preserveExistingRepoGate = false;
+    if (gateScope !== 'repo' && gateScope !== 'repository' && existingGate && existingGate.scope === 'repo' && existingGate.status === 'BLOCKED') {
+      const preserveMs = Number(process.env.AI_GATE_REPO_PRESERVE_MS || 600000);
+      const lastCheckMs = Date.parse(existingGate.last_check || '');
+      if (!Number.isNaN(preserveMs) && preserveMs > 0 && !Number.isNaN(lastCheckMs)) {
+        const ageMs = Date.now() - lastCheckMs;
+        if (ageMs >= 0 && ageMs < preserveMs) {
+          preserveExistingRepoGate = true;
+        }
+      }
+    }
+
+    const nextGate = {
+      status: gateResult.passed ? 'ALLOWED' : 'BLOCKED',
+      scope: gateScope === 'repo' || gateScope === 'repository' ? 'repo' : 'staging',
+      last_check: new Date().toISOString(),
+      violations: blockingViolations.map(v => ({
+        file: v.filePath || v.file || 'unknown',
+        line: v.line || null,
+        severity: v.severity,
+        rule: v.ruleId || v.rule || 'unknown',
+        message: v.message || v.description || '',
+        category: v.category || 'unknown',
+        intelligent_evaluation: v.intelligentEvaluation || false,
+        severity_score: v.severityScore || 0
+      })),
+      instruction: '🚨 AI MUST call mcp_ast-intelligence-automation_ai_gate_check BEFORE any action. If BLOCKED, fix violations first!',
+      mandatory: true
+    };
+
+    evidence.ai_gate = preserveExistingRepoGate ? existingGate : nextGate;
+
+    evidence.git_flow = {
+      branch_protection: {
+        main: 'protected',
+        [baseBranch]: 'protected',
+        feature_branches: 'allowed'
+      },
+      commit_validation: {
+        require_evidence: true,
+        require_tests: true,
+        require_build: true,
+        allow_no_verify: false
+      },
+      current_branch: currentBranch,
+      base_branch: baseBranch,
+      is_protected: isProtected
+    };
+
+    const tokenFile = path.join(resolveAuditTmpDir(), 'token-usage.jsonl');
+    let realTokenData = { estimated: tokenUsage.estimated, percentUsed: tokenUsage.percentUsed };
+    try {
+      if (fs.existsSync(tokenFile)) {
+        const lastLine = execSync(`tail -1 ${tokenFile}`, { encoding: 'utf8' }).trim();
+        if (lastLine) {
+          realTokenData = JSON.parse(lastLine);
+        }
+      }
+    } catch (tokenReadError) {
+      process.stderr.write(`[Token] Using estimated data (read failed: ${toErrorMessage(tokenReadError)})\n`);
+    }
+
+    const tokenPercent = Math.round(realTokenData.percentUsed || tokenUsage.percentUsed);
+    const tokenEstimated = Math.round((realTokenData.estimated || tokenUsage.estimated) / 1000);
+
+    if (tokenPercent >= 90) {
+      try {
+        execSync('osascript -e \'display notification "Token usage at ' + tokenPercent + '%! Update evidence to avoid context loss." with title "⚠️ Token Usage Critical" sound name "Basso"\'', { stdio: 'ignore' });
+      } catch (notificationError) {
+        if (toErrorMessage(notificationError).includes('osascript')) {
+          process.stderr.write('[Token] Notification skipped (not macOS)\n');
+        }
+      }
+    }
+
+    evidence.watchers = {
+      token_monitor: {
+        enabled: true,
+        status: tokenPercent >= 90 ? 'critical' : tokenPercent >= 75 ? 'warning' : 'active',
+        current_usage: `${tokenEstimated}K/1M tokens (${tokenPercent}%)`,
+        warning_threshold: 750000,
+        critical_threshold: 900000,
+        notify_at_percent: 90
+      },
+      violations_watcher: {
+        enabled: true,
+        status: 'monitoring',
+        blocking_threshold: 'HIGH',
+        auto_fix_enabled: false
+      },
+      evidence_watcher: {
+        enabled: true,
+        status: 'active',
+        sla_minutes: 10,
+        auto_refresh: true
+      }
+    };
+
+    fs.writeFileSync(evidencePath, JSON.stringify(evidence, null, 2));
+    console.log('[Intelligent Audit] ✅ .AI_EVIDENCE.json updated with complete format (ai_gate, severity_metrics, token_usage, git_flow, watchers)');
+
+  } catch (evidenceFileUpdateError) {
+    process.stderr.write(`[Intelligent Audit] ⚠️  Evidence update failed: ${toErrorMessage(evidenceFileUpdateError)}\n`);
+  }
+}
+
+if (require.main === module) {
+  runIntelligentAudit().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { runIntelligentAudit };

package/scripts/hooks-system/infrastructure/patterns/pattern-checks.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Pattern Checks - Infrastructure Layer
+# Implementation of pattern-based code checks
+
+source "$(dirname "${BASH_SOURCE[0]}")/../shell/core/constants.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/../shell/core/utils.sh"
+
+check_grep() {
+  local name="$1"
+  local pattern="$2"
+  local files_list="$3"
+  if [[ ! -s "$files_list" ]]; then
+    echo "$name:0"
+    return
+  fi
+  local count
+  count=$(while IFS= read -r file; do
+    if [[ -f "$file" ]]; then
+      # Excluir archivos del sistema que definen los propios patrones
+      if [[ "$file" =~ pattern-checks\.sh$ ]]; then
+        continue
+      fi
+      # Excluir AST tooling interno de la librería (contiene strings de reglas que generan falsos positivos)
+      if [[ "$file" == *"/infrastructure/ast/"* ]] || [[ "$file" == *"/scripts/hooks-system/infrastructure/ast/"* ]]; then
+        continue
+      fi
+      # Excluir tooling/CLI scripts (ruido alto, no es código de producto)
+      if [[ "$file" == *"/bin/"* ]] || [[ "$file" == *"/scripts/hooks-system/bin/"* ]]; then
+        continue
+      fi
+      # Excluir archivos temporales/backups y configuraciones del editor
+      if [[ "$file" == *"/.cursor/"* ]] || [[ "$file" == *".bak"* ]]; then
+        continue
+      fi
+      # Excluir archivos de metadata/configuración (.json, .md)
+      if [[ "$file" =~ \.(json|md|mdc)$ ]]; then
+        continue
+      fi
+      # Filtrar comentarios de una sola línea (//) y comentarios de bloque (/* */ y *)
+      grep -E -n "$pattern" "$file" 2>/dev/null | grep -v "^\s*//" | grep -v "^\s*\*" | grep -v "/\*.*\*/"
+    fi
+  done < "$files_list" | wc -l | tr -d ' ' || echo "0")
+  echo "$name:$count"
+}
+
+check_grep_console_exclude_logger() {
+  local files_list="$1"
+  if [[ ! -s "$files_list" ]]; then
+    echo "CONSOLE_LOG:0"
+    return
+  fi
+  local count=0
+  while IFS= read -r file; do
+    if [[ -f "$file" ]]; then
+      if [[ "$file" == *"/bin/"* ]] || [[ "$file" == *"/scripts/hooks-system/bin/"* ]]; then
+        continue
+      fi
+      while IFS=: read -r line_num line_content; do
+        if [[ -n "$line_num" ]] && ! echo "$line_content" | grep -q "logger\."; then
+          count=$((count + 1))
+        fi
+      done < <(grep -E -n "console\\.(log|debug|warn|error)\\(" "$file" 2>/dev/null || true)
+    fi
+  done < "$files_list"
+  echo "CONSOLE_LOG:$count"
+}
+
+check_any_type_ts_only() {
+  local files_list="$1"
+  # Crear lista temporal solo con archivos TS/JS (excluir .sh, .json, .md, etc.)
+  local ts_files=$(mktemp)
+  while IFS= read -r file; do
+    if [[ "$file" =~ \.(ts|tsx|js|jsx)$ ]]; then
+      echo "$file" >> "$ts_files"
+    fi
+  done < "$files_list"
+
+  local result=$(check_grep "ANY_TYPE" ": any(\b|[^a-zA-Z_])" "$ts_files")
+  rm -f "$ts_files"
+  echo "$result"
+}
+
+run_pattern_checks() {
+  local files_list="$1"
+  local checks_total=6
+  local step=0
+  local check_names=("Task Markers" "Console.log" "Any Types" "Raw SQL" "Hardcoded Secrets" "Disabled Lint")
+
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[0]}..." >&2; local r1=$(check_grep "TODO_FIXME" "TODO|FIXME|HACK" "$files_list")
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[1]}..." >&2; local r2=$(check_grep_console_exclude_logger "$files_list")
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[2]}..." >&2; local r3=$(check_any_type_ts_only "$files_list")
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[3]}..." >&2; local r4=$(check_grep "SQL_RAW" "(SELECT[[:space:]].*[[:space:]]FROM[[:space:]]|INSERT[[:space:]].*[[:space:]]INTO[[:space:]]|UPDATE[[:space:]].*[[:space:]]SET[[:space:]]|DELETE[[:space:]].*[[:space:]]FROM[[:space:]]|DROP[[:space:]]TABLE[[:space:]]|ALTER[[:space:]]TABLE[[:space:]]|TRUNCATE[[:space:]]TABLE[[:space:]])" "$files_list")
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[4]}..." >&2; local r5=$(check_grep "HARDCODED_SECRET" "(API_KEY|SECRET|TOKEN|PASSWORD)\s*[:=]\s*['\"]" "$files_list")
+  step=$((step+1)); progress_bar_simple $step $checks_total "[${step}/${checks_total}] Checking ${check_names[5]}..." >&2; local r6=$(check_grep "DISABLED_LINT" "eslint-disable|ts-ignore" "$files_list")
+
+  printf "%b✅ Pattern checks completed%b\n" "$GREEN" "$NC" >&2
+  printf "%s\n%s\n%s\n%s\n%s\n%s\n" "$r1" "$r2" "$r3" "$r4" "$r5" "$r6"
+}

package/scripts/hooks-system/infrastructure/reporting/ReportImpactAnalyzer.js

@@ -0,0 +1,109 @@
+class ReportImpactAnalyzer {
+    constructor(metricsCalculator) {
+        this.metricsCalculator = metricsCalculator;
+    }
+
+    analyze(violations) {
+        const withImpact = violations.filter(v => v.impactBreakdown);
+
+        if (withImpact.length === 0) {
+            return null;
+        }
+
+        const totals = withImpact.reduce((acc, v) => {
+            acc.security += v.impactBreakdown.security || 0;
+            acc.stability += v.impactBreakdown.stability || 0;
+            acc.performance += v.impactBreakdown.performance || 0;
+            acc.maintainability += v.impactBreakdown.maintainability || 0;
+            acc.count++;
+            return acc;
+        }, { security: 0, stability: 0, performance: 0, maintainability: 0, count: 0 });
+
+        return {
+            averages: {
+                security: Math.round(totals.security / totals.count),
+                stability: Math.round(totals.stability / totals.count),
+                performance: Math.round(totals.performance / totals.count),
+                maintainability: Math.round(totals.maintainability / totals.count)
+            },
+            dominantImpact: this.findDominantImpact(totals),
+            riskProfile: this.assessRiskProfile(totals, violations.length)
+        };
+    }
+
+    findDominantImpact(totals) {
+        const impacts = {
+            security: totals.security,
+            stability: totals.stability,
+            performance: totals.performance,
+            maintainability: totals.maintainability
+        };
+
+        return Object.entries(impacts)
+            .sort((a, b) => b[1] - a[1])[0][0];
+    }
+
+    assessRiskProfile(totals, totalCount) {
+        const avgTotal = (totals.security + totals.stability + totals.performance + totals.maintainability) / (totals.count * 4);
+
+        if (avgTotal > 70) return 'HIGH_RISK';
+        if (avgTotal > 50) return 'MEDIUM_RISK';
+        if (avgTotal > 30) return 'LOW_RISK';
+        return 'MINIMAL_RISK';
+    }
+
+    generateRecommendations(violations) {
+        const recommendations = [];
+
+        const sortedBySeverity = [...violations]
+            .filter(v => v.severityScore)
+            .sort((a, b) => (b.severityScore || 0) - (a.severityScore || 0))
+            .slice(0, 5);
+
+        sortedBySeverity.forEach((v, idx) => {
+            recommendations.push({
+                priority: idx + 1,
+                ruleId: v.ruleId,
+                filePath: v.filePath,
+                line: v.line,
+                severityScore: v.severityScore,
+                action: v.recommendation || v.message
+            });
+        });
+
+        const byCategory = this.metricsCalculator.groupByCategory(violations);
+        Object.entries(byCategory).forEach(([category, violationsList]) => {
+            if (violationsList.length > 5) {
+                recommendations.push({
+                    type: 'CATEGORY_PATTERN',
+                    category,
+                    count: violationsList.length,
+                    action: `Consider architectural review of ${category} - ${violationsList.length} violations detected`
+                });
+            }
+        });
+
+        return recommendations;
+    }
+
+    extractCriticalIssues(violations) {
+        const critical = violations.filter(v => v.severity === 'CRITICAL');
+
+        return critical.map(v => ({
+            ruleId: v.ruleId,
+            filePath: v.filePath,
+            line: v.line,
+            message: v.message,
+            severityScore: v.severityScore,
+            impactBreakdown: v.impactBreakdown,
+            recommendation: v.recommendation,
+            context: {
+                isCriticalPath: v.context?.isCriticalPath,
+                isProduction: v.context?.isProduction,
+                dependencyCount: v.context?.dependencyCount
+            }
+        }));
+    }
+}
+
+module.exports = ReportImpactAnalyzer;

package/scripts/hooks-system/infrastructure/reporting/ReportMetricsCalculator.js

@@ -0,0 +1,114 @@
+class ReportMetricsCalculator {
+    calculate(violations) {
+        return {
+            totalFiles: new Set(violations.map(v => v.filePath)).size,
+            totalLines: violations.reduce((sum, v) => sum + (v.line || 0), 0),
+            averageSeverityScore: this.calculateAverageSeverityScore(violations),
+            severityDistribution: this.calculateSeverityDistribution(violations),
+            categoryBreakdown: this.calculateCategoryBreakdown(violations),
+            filesWithMostViolations: this.findFilesWithMostViolations(violations, 10)
+        };
+    }
+
+    calculateAverageSeverityScore(violations) {
+        const withScores = violations.filter(v => v.severityScore);
+        if (withScores.length === 0) return 0;
+
+        const total = withScores.reduce((sum, v) => sum + v.severityScore, 0);
+        return Math.round(total / withScores.length);
+    }
+
+    calculateSeverityDistribution(violations) {
+        const total = violations.length;
+        if (total === 0) {
+            return { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+        }
+        const grouped = this.groupBySeverity(violations);
+
+        return {
+            CRITICAL: Math.round(((grouped.CRITICAL?.length || 0) / total) * 100),
+            HIGH: Math.round(((grouped.HIGH?.length || 0) / total) * 100),
+            MEDIUM: Math.round(((grouped.MEDIUM?.length || 0) / total) * 100),
+            LOW: Math.round(((grouped.LOW?.length || 0) / total) * 100)
+        };
+    }
+
+    calculateCategoryBreakdown(violations) {
+        const byCategory = this.groupByCategory(violations);
+
+        return Object.entries(byCategory)
+            .map(([category, violationsList]) => ({
+                category,
+                count: violationsList.length,
+                percentage: Math.round((violationsList.length / violations.length) * 100) || 0,
+                averageScore: this.calculateAverageSeverityScore(violationsList)
+            }))
+            .sort((a, b) => b.count - a.count);
+    }
+
+    findFilesWithMostViolations(violations, limit = 10) {
+        const byFile = this.groupByFile(violations);
+
+        return Object.entries(byFile)
+            .map(([file, violationsList]) => ({
+                file,
+                count: violationsList.length,
+                averageScore: this.calculateAverageSeverityScore(violationsList),
+                highestSeverity: violationsList.reduce((max, v) =>
+                    this.severityRank(v.severity) > this.severityRank(max) ? v.severity : max,
+                    'LOW'
+                )
+            }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, limit);
+    }
+
+    groupBySeverity(violations) {
+        return violations.reduce((acc, v) => {
+            const severity = v.severity || 'LOW';
+            if (!acc[severity]) acc[severity] = [];
+            acc[severity].push(v);
+            return acc;
+        }, {});
+    }
+
+    groupByCategory(violations) {
+        return violations.reduce((acc, v) => {
+            const category = this.extractCategory(v.ruleId);
+            if (!acc[category]) acc[category] = [];
+            acc[category].push(v);
+            return acc;
+        }, {});
+    }
+
+    groupByFile(violations) {
+        return violations.reduce((acc, v) => {
+            const file = v.filePath;
+            if (!acc[file]) acc[file] = [];
+            acc[file].push(v);
+            return acc;
+        }, {});
+    }
+
+    extractCategory(ruleId) {
+        if (!ruleId) return 'Other';
+        if (ruleId.includes('solid.')) return 'SOLID Principles';
+        if (ruleId.includes('clean_arch.')) return 'Clean Architecture';
+        if (ruleId.includes('bdd.') || ruleId.includes('tdd.')) return 'BDD/TDD';
+        if (ruleId.includes('ddd.')) return 'DDD';
+        if (ruleId.includes('cqrs.')) return 'CQRS';
+        if (ruleId.includes('security.')) return 'Security';
+        if (ruleId.includes('performance.')) return 'Performance';
+        if (ruleId.includes('testing.')) return 'Testing';
+        if (ruleId.includes('typescript.') || ruleId.includes('kotlin.')) return 'Type Safety';
+        if (ruleId.includes('react.') || ruleId.includes('compose.')) return 'UI Framework';
+        return 'Other';
+    }
+
+    severityRank(severity) {
+        const ranks = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
+        return ranks[severity] || 0;
+    }
+}
+
+module.exports = ReportMetricsCalculator;