@kevinrabun/judges-cli 3.124.0

package/dist/commands/timeout-audit.js

@@ -0,0 +1,210 @@
+/**
+ * Timeout audit — trace timeout and deadline settings through call chains.
+ */
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, extname } from "path";
+// ─── File Collection ────────────────────────────────────────────────────────
+const CODE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".java", ".go", ".rs"]);
+function collectFiles(dir, max = 300) {
+    const files = [];
+    function walk(d) {
+        if (files.length >= max)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (files.length >= max)
+                return;
+            if (e.startsWith(".") || e === "node_modules" || e === "dist" || e === "build")
+                continue;
+            const full = join(d, e);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full);
+                else if (CODE_EXTS.has(extname(full)))
+                    files.push(full);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    }
+    walk(dir);
+    return files;
+}
+// ─── Analysis ───────────────────────────────────────────────────────────────
+function analyzeFile(filepath) {
+    const issues = [];
+    let content;
+    try {
+        content = readFileSync(filepath, "utf-8");
+    }
+    catch {
+        return issues;
+    }
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Hardcoded timeout values
+        const hardcodedMatch = line.match(/timeout\s*[:=]\s*(\d+)/i);
+        if (hardcodedMatch) {
+            const val = parseInt(hardcodedMatch[1], 10);
+            if (val > 0 && !line.includes("config") && !line.includes("option") && !line.includes("env")) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Hardcoded timeout value",
+                    severity: "medium",
+                    detail: `Timeout = ${val}${val >= 1000 ? "ms" : ""} — extract to configuration for tunability`,
+                });
+            }
+        }
+        // Missing timeout on fetch/axios/http calls
+        if (/(?:fetch|axios|http\.(?:get|post|put|delete|request)|got|superagent)\s*\(/.test(line)) {
+            const block = lines.slice(i, Math.min(i + 5, lines.length)).join("\n");
+            if (!/timeout|signal|AbortController|deadline/i.test(block)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "HTTP call without timeout",
+                    severity: "high",
+                    detail: "Network call has no timeout — can hang indefinitely under failure conditions",
+                });
+            }
+        }
+        // Missing timeout on database queries
+        if (/\.(?:query|execute|find|findOne|aggregate|raw)\s*\(/.test(line)) {
+            const block = lines.slice(i, Math.min(i + 5, lines.length)).join("\n");
+            if (/(?:db|pool|connection|prisma|knex|sequelize|mongo)/i.test(block) &&
+                !/timeout|maxTimeMS|statement_timeout/i.test(block)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Database query without timeout",
+                    severity: "medium",
+                    detail: "DB query has no timeout — long-running queries can exhaust connection pool",
+                });
+            }
+        }
+        // setTimeout with very large values
+        const setTimeoutMatch = line.match(/setTimeout\s*\([^,]+,\s*(\d+)\)/);
+        if (setTimeoutMatch) {
+            const val = parseInt(setTimeoutMatch[1], 10);
+            if (val > 300000) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Excessive setTimeout delay",
+                    severity: "low",
+                    detail: `setTimeout delay = ${Math.round(val / 1000)}s — consider persistent scheduling instead`,
+                });
+            }
+        }
+        // Promise.race without timeout
+        if (/Promise\.all\s*\(/.test(line)) {
+            const block = lines.slice(i, Math.min(i + 5, lines.length)).join("\n");
+            if (!/timeout|Promise\.race|AbortController/i.test(block)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Promise.all without timeout guard",
+                    severity: "medium",
+                    detail: "Promise.all can hang if any promise never resolves — wrap with Promise.race timeout",
+                });
+            }
+        }
+        // Upstream vs downstream timeout mismatch (heuristic)
+        if (/server.*timeout|listen.*timeout|request.*timeout/i.test(line)) {
+            const downstreamBlock = lines.slice(i, Math.min(i + 30, lines.length)).join("\n");
+            const serverTimeout = line.match(/timeout\s*[:=]\s*(\d+)/i);
+            const clientTimeout = downstreamBlock.match(/(?:fetch|axios|http).*timeout\s*[:=]\s*(\d+)/i);
+            if (serverTimeout && clientTimeout) {
+                const server = parseInt(serverTimeout[1], 10);
+                const client = parseInt(clientTimeout[1], 10);
+                if (client > server) {
+                    issues.push({
+                        file: filepath,
+                        line: i + 1,
+                        issue: "Downstream timeout exceeds upstream",
+                        severity: "high",
+                        detail: `Client timeout (${client}) > server timeout (${server}) — response may be dropped after server times out`,
+                    });
+                }
+            }
+        }
+        // gRPC / streaming without deadline
+        if (/grpc|\.stream\s*\(|createReadStream|createWriteStream/i.test(line)) {
+            const block = lines.slice(i, Math.min(i + 5, lines.length)).join("\n");
+            if (!/deadline|timeout|destroy|abort/i.test(block)) {
+                issues.push({
+                    file: filepath,
+                    line: i + 1,
+                    issue: "Stream/gRPC call without deadline",
+                    severity: "medium",
+                    detail: "Streaming call has no deadline — can leak resources if peer becomes unresponsive",
+                });
+            }
+        }
+    }
+    return issues;
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runTimeoutAudit(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges timeout-audit — Trace timeout and deadline propagation gaps
+
+Usage:
+  judges timeout-audit [dir]
+  judges timeout-audit src/ --format json
+
+Options:
+  [dir]                 Directory to scan (default: .)
+  --format json         JSON output
+  --help, -h            Show this help
+
+Checks: missing HTTP timeouts, hardcoded values, DB query timeouts,
+excessive setTimeout, Promise.all without guards, downstream > upstream mismatch.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const dir = argv.find((a) => !a.startsWith("-") && argv.indexOf(a) > 0) || ".";
+    const files = collectFiles(dir);
+    const allIssues = [];
+    for (const f of files)
+        allIssues.push(...analyzeFile(f));
+    const highCount = allIssues.filter((i) => i.severity === "high").length;
+    const medCount = allIssues.filter((i) => i.severity === "medium").length;
+    const score = Math.max(0, 100 - highCount * 10 - medCount * 4);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            issues: allIssues,
+            score,
+            summary: { high: highCount, medium: medCount, total: allIssues.length },
+            timestamp: new Date().toISOString(),
+        }, null, 2));
+    }
+    else {
+        const badge = score >= 80 ? "✅ ROBUST" : score >= 50 ? "⚠️  GAPS" : "❌ FRAGILE";
+        console.log(`\n  Timeout Safety: ${badge} (${score}/100)\n  ─────────────────────────────`);
+        if (allIssues.length === 0) {
+            console.log("    No timeout issues detected.\n");
+            return;
+        }
+        for (const issue of allIssues.slice(0, 25)) {
+            const icon = issue.severity === "high" ? "🔴" : issue.severity === "medium" ? "🟡" : "🔵";
+            console.log(`    ${icon} ${issue.issue}`);
+            console.log(`        ${issue.file}:${issue.line}`);
+            console.log(`        ${issue.detail}`);
+        }
+        if (allIssues.length > 25)
+            console.log(`    ... and ${allIssues.length - 25} more`);
+        console.log(`\n    Total: ${allIssues.length} | High: ${highCount} | Medium: ${medCount} | Score: ${score}/100\n`);
+    }
+}

package/dist/commands/trace.d.ts

@@ -0,0 +1,64 @@
+import type { TribunalVerdict } from "../types.js";
+export interface TraceStep {
+    /** Stage name in the pipeline */
+    stage: string;
+    /** What happened at this stage */
+    action: "kept" | "suppressed" | "demoted" | "boosted" | "merged" | "capped" | "added";
+    /** Human-readable explanation */
+    reason: string;
+}
+export interface FindingTrace {
+    /** The final (or suppressed) finding */
+    ruleId: string;
+    title: string;
+    severity: string;
+    /** Final disposition */
+    disposition: "reported" | "suppressed" | "merged";
+    /** Ordered pipeline steps */
+    steps: TraceStep[];
+    /** Confidence journey: initial → final */
+    confidenceJourney?: {
+        initial: number;
+        final: number;
+        adjustments: string[];
+    };
+}
+export interface EvaluationTrace {
+    /** File evaluated */
+    filePath?: string;
+    /** Language detected */
+    language: string;
+    /** Total judges that ran */
+    judgesRun: number;
+    /** Total raw findings before any filtering */
+    rawFindingCount: number;
+    /** Total findings after full pipeline */
+    finalFindingCount: number;
+    /** Findings suppressed by each pipeline stage */
+    suppressionSummary: {
+        stage: string;
+        count: number;
+    }[];
+    /** Per-finding trace */
+    findings: FindingTrace[];
+    /** Per-judge summary */
+    judgeSummaries: {
+        judgeId: string;
+        judgeName: string;
+        findingsProduced: number;
+        durationMs: number;
+    }[];
+}
+/**
+ * Build an evaluation trace from a tribunal verdict.
+ *
+ * This reconstructs the pipeline journey from the data available on the
+ * verdict — it does not require runtime hooks in the evaluator. The trace
+ * is approximate but highly informative for understanding why findings
+ * were kept or dropped.
+ */
+export declare function buildEvaluationTrace(verdict: TribunalVerdict, filePath?: string, language?: string): EvaluationTrace;
+/**
+ * Format an evaluation trace as human-readable text output.
+ */
+export declare function formatTraceText(trace: EvaluationTrace): string;

package/dist/commands/trace.js

@@ -0,0 +1,245 @@
+// ─── Trace Mode — Show Your Work ─────────────────────────────────────────────
+// Renders a detailed, human-readable trace of exactly how the evaluation
+// pipeline reached its decision for every finding. Each finding's journey
+// through the pipeline is shown: detection → FP filters → dedup → calibration
+// → confidence scoring → final disposition.
+//
+// All data is computed locally from the evaluation result — no external
+// services or data storage involved.
+//
+// Usage:
+//   judges eval src/app.ts --trace            # text trace to stdout
+//   judges eval src/app.ts --trace --format json   # structured trace
+// ──────────────────────────────────────────────────────────────────────────────
+// ─── Trace Builder ──────────────────────────────────────────────────────────
+/**
+ * Build an evaluation trace from a tribunal verdict.
+ *
+ * This reconstructs the pipeline journey from the data available on the
+ * verdict — it does not require runtime hooks in the evaluator. The trace
+ * is approximate but highly informative for understanding why findings
+ * were kept or dropped.
+ */
+export function buildEvaluationTrace(verdict, filePath, language) {
+    const judgeSummaries = verdict.evaluations.map((e) => ({
+        judgeId: e.judgeId,
+        judgeName: e.judgeName,
+        findingsProduced: e.findings.length,
+        durationMs: e.durationMs ?? 0,
+    }));
+    const rawFindingCount = verdict.evaluations.reduce((sum, e) => sum + e.findings.length, 0);
+    // Build per-finding traces from what we can infer
+    const findingTraces = [];
+    // Track what the final set contains
+    const finalRuleIds = new Set(verdict.findings.map((f) => `${f.ruleId}:${f.lineNumbers?.[0] ?? 0}`));
+    // Process each judge's findings
+    for (const evaluation of verdict.evaluations) {
+        for (const finding of evaluation.findings) {
+            const key = `${finding.ruleId}:${finding.lineNumbers?.[0] ?? 0}`;
+            const steps = [];
+            // Step 1: Detection
+            steps.push({
+                stage: "detection",
+                action: "kept",
+                reason: `Detected by ${evaluation.judgeName} (${evaluation.judgeId}) via ${finding.provenance ?? "pattern-match"}`,
+            });
+            // Step 2: Evidence basis
+            if (finding.evidenceBasis) {
+                steps.push({
+                    stage: "confidence-scoring",
+                    action: finding.confidence && finding.confidence >= 0.7 ? "boosted" : "kept",
+                    reason: `Evidence: ${finding.evidenceBasis}`,
+                });
+            }
+            // Step 3: Evidence chain
+            if (finding.evidenceChain) {
+                const chainDesc = finding.evidenceChain.steps
+                    .map((s) => `${s.source}${s.line ? ` L${s.line}` : ""}: ${s.observation}`)
+                    .join(" → ");
+                steps.push({
+                    stage: "evidence-chain",
+                    action: "kept",
+                    reason: chainDesc,
+                });
+            }
+            // Step 4: Absence gating
+            if (finding.isAbsenceBased) {
+                steps.push({
+                    stage: "absence-gating",
+                    action: "demoted",
+                    reason: "Absence-based finding — severity capped at medium, confidence capped at 0.6",
+                });
+            }
+            // Step 5: Confidence tier
+            if (finding.confidenceTier) {
+                steps.push({
+                    stage: "confidence-tiering",
+                    action: "kept",
+                    reason: `Classified as "${finding.confidenceTier}" (confidence: ${((finding.confidence ?? 0.5) * 100).toFixed(0)}%)`,
+                });
+            }
+            // Step 6: Check if it survived to final output
+            const inFinal = finalRuleIds.has(key);
+            if (!inFinal) {
+                // Determine likely suppression reason
+                if (finding.isAbsenceBased) {
+                    steps.push({
+                        stage: "pipeline-filter",
+                        action: "suppressed",
+                        reason: "Suppressed: absence-based finding in single-file mode",
+                    });
+                }
+                else {
+                    steps.push({
+                        stage: "pipeline-filter",
+                        action: "suppressed",
+                        reason: "Suppressed: likely removed by FP heuristics, dedup, or config filter",
+                    });
+                }
+            }
+            // Step 7: OWASP LLM mapping
+            if (finding.owaspLlmTop10) {
+                steps.push({
+                    stage: "ai-risk-mapping",
+                    action: "kept",
+                    reason: `Mapped to ${finding.owaspLlmTop10}`,
+                });
+            }
+            // Step 8: Patch availability
+            if (finding.patch) {
+                steps.push({
+                    stage: "auto-fix",
+                    action: "added",
+                    reason: `Auto-fix available: L${finding.patch.startLine}-${finding.patch.endLine}`,
+                });
+            }
+            const confidenceJourney = finding.evidenceBasis
+                ? {
+                    initial: 0.5,
+                    final: finding.confidence ?? 0.5,
+                    adjustments: finding.evidenceBasis.split(", "),
+                }
+                : undefined;
+            findingTraces.push({
+                ruleId: finding.ruleId,
+                title: finding.title,
+                severity: finding.severity,
+                disposition: inFinal ? "reported" : "suppressed",
+                steps,
+                confidenceJourney,
+            });
+        }
+    }
+    // Add traces for suppressed findings (from inline suppression audit trail)
+    if (verdict.suppressions) {
+        for (const s of verdict.suppressions) {
+            findingTraces.push({
+                ruleId: s.ruleId,
+                title: s.title,
+                severity: s.severity,
+                disposition: "suppressed",
+                steps: [
+                    { stage: "detection", action: "kept", reason: "Detected by pattern match" },
+                    {
+                        stage: "inline-suppression",
+                        action: "suppressed",
+                        reason: `Suppressed by ${s.kind} comment at L${s.commentLine}${s.reason ? `: ${s.reason}` : ""}`,
+                    },
+                ],
+            });
+        }
+    }
+    // Compute suppression summary by stage
+    const suppressionMap = new Map();
+    for (const trace of findingTraces) {
+        if (trace.disposition === "suppressed") {
+            const lastStep = trace.steps[trace.steps.length - 1];
+            const stage = lastStep?.stage ?? "unknown";
+            suppressionMap.set(stage, (suppressionMap.get(stage) ?? 0) + 1);
+        }
+    }
+    const suppressionSummary = [...suppressionMap.entries()]
+        .map(([stage, count]) => ({ stage, count }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        filePath,
+        language: language ?? "unknown",
+        judgesRun: verdict.evaluations.length,
+        rawFindingCount,
+        finalFindingCount: verdict.findings.length,
+        suppressionSummary,
+        findings: findingTraces,
+        judgeSummaries,
+    };
+}
+// ─── Text Formatter ─────────────────────────────────────────────────────────
+/**
+ * Format an evaluation trace as human-readable text output.
+ */
+export function formatTraceText(trace) {
+    const lines = [];
+    lines.push("");
+    lines.push("╔══════════════════════════════════════════════════════════════╗");
+    lines.push("║           Judges Panel — Evaluation Trace                    ║");
+    lines.push("╚══════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    if (trace.filePath)
+        lines.push(`  File      : ${trace.filePath}`);
+    lines.push(`  Language  : ${trace.language}`);
+    lines.push(`  Judges    : ${trace.judgesRun}`);
+    lines.push(`  Raw       : ${trace.rawFindingCount} findings detected`);
+    lines.push(`  Final     : ${trace.finalFindingCount} findings reported`);
+    lines.push(`  Filtered  : ${trace.rawFindingCount - trace.finalFindingCount} findings suppressed`);
+    lines.push("");
+    // Judge timing breakdown
+    lines.push("  ─── Judge Execution ────────────────────────────────────────");
+    lines.push("");
+    for (const j of trace.judgeSummaries) {
+        const icon = j.findingsProduced > 0 ? "🔍" : "✅";
+        lines.push(`  ${icon} ${j.judgeName.padEnd(35)} ${j.findingsProduced} finding(s)  ${j.durationMs}ms`);
+    }
+    lines.push("");
+    // Suppression summary
+    if (trace.suppressionSummary.length > 0) {
+        lines.push("  ─── Suppression Summary ────────────────────────────────────");
+        lines.push("");
+        for (const s of trace.suppressionSummary) {
+            lines.push(`  ⊘ ${s.stage.padEnd(30)} ${s.count} finding(s) removed`);
+        }
+        lines.push("");
+    }
+    // Per-finding traces
+    lines.push("  ─── Finding Decision Traces ────────────────────────────────");
+    lines.push("");
+    for (const f of trace.findings) {
+        const icon = f.disposition === "reported" ? "📋" : f.disposition === "merged" ? "🔀" : "⊘";
+        lines.push(`  ${icon} [${f.severity.toUpperCase().padEnd(8)}] ${f.ruleId}: ${f.title}`);
+        lines.push(`    Disposition: ${f.disposition.toUpperCase()}`);
+        for (const step of f.steps) {
+            const actionIcon = step.action === "kept"
+                ? "  →"
+                : step.action === "suppressed"
+                    ? "  ✗"
+                    : step.action === "demoted"
+                        ? "  ↓"
+                        : step.action === "boosted"
+                            ? "  ↑"
+                            : step.action === "merged"
+                                ? "  ⊕"
+                                : step.action === "added"
+                                    ? "  +"
+                                    : step.action === "capped"
+                                        ? "  ⌐"
+                                        : "  ?";
+            lines.push(`  ${actionIcon} [${step.stage}] ${step.reason}`);
+        }
+        if (f.confidenceJourney) {
+            lines.push(`    Confidence: ${(f.confidenceJourney.initial * 100).toFixed(0)}% → ${(f.confidenceJourney.final * 100).toFixed(0)}%`);
+            for (const adj of f.confidenceJourney.adjustments) {
+                lines.push(`      ${adj.trim()}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/commands/trend-report.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Trend-report — Track finding trends over time to show improvement trajectory.
+ */
+export declare function runTrendReport(argv: string[]): void;

package/dist/commands/trend-report.js

@@ -0,0 +1,148 @@
+/**
+ * Trend-report — Track finding trends over time to show improvement trajectory.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function getTrendDir() {
+    return join(".", ".judges", "trends");
+}
+function loadSnapshots() {
+    const dir = getTrendDir();
+    const indexPath = join(dir, "trend-index.json");
+    if (!existsSync(indexPath))
+        return [];
+    try {
+        return JSON.parse(readFileSync(indexPath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function saveSnapshots(snapshots) {
+    const dir = getTrendDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "trend-index.json"), JSON.stringify(snapshots, null, 2), "utf-8");
+}
+function computeTrend(snapshots) {
+    if (snapshots.length === 0) {
+        return {
+            snapshots: [],
+            trend: "stable",
+            changePercent: 0,
+            averageFindings: 0,
+            bestSnapshot: null,
+            worstSnapshot: null,
+        };
+    }
+    const sorted = [...snapshots].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const totalSum = sorted.reduce((s, snap) => s + snap.totalFindings, 0);
+    const avg = Math.round(totalSum / sorted.length);
+    const best = sorted.reduce((b, s) => (s.totalFindings < b.totalFindings ? s : b), sorted[0]);
+    const worst = sorted.reduce((w, s) => (s.totalFindings > w.totalFindings ? s : w), sorted[0]);
+    let trend = "stable";
+    let changePercent = 0;
+    if (sorted.length >= 2) {
+        const first = sorted[0].totalFindings;
+        const last = sorted[sorted.length - 1].totalFindings;
+        if (first > 0) {
+            changePercent = Math.round(((last - first) / first) * 100);
+        }
+        if (changePercent < -10)
+            trend = "improving";
+        else if (changePercent > 10)
+            trend = "degrading";
+    }
+    return { snapshots: sorted, trend, changePercent, averageFindings: avg, bestSnapshot: best, worstSnapshot: worst };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runTrendReport(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges trend-report — Track finding trends over time
+
+Usage:
+  judges trend-report record --total 15 --critical 1 --high 3 --medium 6 --low 5 --files 42
+  judges trend-report show                    Show trend analysis
+  judges trend-report show --format json      JSON output
+
+Subcommands:
+  record        Record a snapshot of current findings
+  show          Analyze and display trend data
+
+Record Options:
+  --total <n>       Total findings count
+  --critical <n>    Critical severity count
+  --high <n>        High severity count
+  --medium <n>      Medium severity count
+  --low <n>         Low severity count
+  --files <n>       Files scanned count
+  --commit <hash>   Associated commit hash
+
+Show Options:
+  --format json     JSON output
+  --help, -h        Show this help
+
+Snapshots are stored locally in .judges/trends/.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const subcommand = argv.find((a) => !a.startsWith("-") && a !== "trend-report") || "show";
+    if (subcommand === "record") {
+        const getNum = (flag) => {
+            const val = argv.find((_a, i) => argv[i - 1] === flag);
+            return val ? parseInt(val, 10) : 0;
+        };
+        const total = getNum("--total");
+        const critical = getNum("--critical");
+        const high = getNum("--high");
+        const medium = getNum("--medium");
+        const low = getNum("--low");
+        const filesScanned = getNum("--files");
+        const commit = argv.find((_a, i) => argv[i - 1] === "--commit") || "unknown";
+        const snapshot = {
+            timestamp: new Date().toISOString(),
+            commit,
+            totalFindings: total,
+            critical,
+            high,
+            medium,
+            low,
+            filesScanned,
+            findingsPerFile: filesScanned > 0 ? Math.round((total / filesScanned) * 100) / 100 : 0,
+        };
+        const snapshots = loadSnapshots();
+        snapshots.push(snapshot);
+        saveSnapshots(snapshots);
+        console.log(`Recorded snapshot: ${total} findings across ${filesScanned} files.`);
+        return;
+    }
+    // Show
+    const snapshots = loadSnapshots();
+    const report = computeTrend(snapshots);
+    if (format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`\n  Trend Report\n  ─────────────────────────────`);
+    console.log(`    Snapshots: ${report.snapshots.length}`);
+    console.log(`    Average findings: ${report.averageFindings}`);
+    const trendIcon = report.trend === "improving" ? "📉" : report.trend === "degrading" ? "📈" : "➡️";
+    console.log(`    Trend: ${trendIcon} ${report.trend} (${report.changePercent > 0 ? "+" : ""}${report.changePercent}%)`);
+    if (report.bestSnapshot) {
+        console.log(`\n    Best: ${report.bestSnapshot.totalFindings} findings (${report.bestSnapshot.timestamp.slice(0, 10)})`);
+    }
+    if (report.worstSnapshot) {
+        console.log(`    Worst: ${report.worstSnapshot.totalFindings} findings (${report.worstSnapshot.timestamp.slice(0, 10)})`);
+    }
+    if (report.snapshots.length > 0) {
+        console.log("\n    Recent snapshots:");
+        const recent = report.snapshots.slice(-5);
+        for (const snap of recent) {
+            console.log(`      ${snap.timestamp.slice(0, 10)}  ${snap.totalFindings} findings  (C:${snap.critical} H:${snap.high} M:${snap.medium} L:${snap.low})`);
+        }
+    }
+    console.log();
+}