@kevinrabun/judges-cli 3.124.0

package/dist/commands/feedback.js

@@ -0,0 +1,550 @@
+/**
+ * `judges feedback` — False-positive tracking & finding feedback.
+ *
+ * Allows users to mark findings as true positives, false positives,
+ * or "won't fix" and persists feedback to a local .judges-feedback.json file.
+ * This data is used by the confidence calibration system to improve
+ * accuracy over time.
+ *
+ * Usage:
+ *   judges feedback submit --rule SEC-001 --verdict fp          # Mark false positive
+ *   judges feedback submit --rule AUTH-002 --verdict tp          # Mark true positive
+ *   judges feedback submit --rule SEC-001 --verdict wontfix     # Won't fix
+ *   judges feedback stats                                        # Show FP rate stats
+ *   judges feedback export                                       # Export feedback data
+ *   judges feedback reset                                        # Clear all feedback
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve, dirname } from "path";
+import { generateAutoTuneReport, formatAutoTuneReport, formatAutoTuneReportJson } from "../auto-tune.js";
+import { getDataAdapter } from "../data-adapter.js";
+// ─── Feedback Store Operations ──────────────────────────────────────────────
+const DEFAULT_FEEDBACK_FILE = ".judges-feedback.json";
+function createEmptyStore() {
+    const now = new Date().toISOString();
+    return {
+        version: 1,
+        entries: [],
+        metadata: {
+            createdAt: now,
+            lastUpdated: now,
+            totalSubmissions: 0,
+        },
+    };
+}
+export function loadFeedbackStore(feedbackPath) {
+    const filePath = resolve(feedbackPath || DEFAULT_FEEDBACK_FILE);
+    if (!existsSync(filePath)) {
+        return createEmptyStore();
+    }
+    try {
+        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (raw.version === 1 && Array.isArray(raw.entries)) {
+            return raw;
+        }
+        return createEmptyStore();
+    }
+    catch {
+        return createEmptyStore();
+    }
+}
+export function saveFeedbackStore(store, feedbackPath) {
+    const filePath = resolve(feedbackPath || DEFAULT_FEEDBACK_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    store.metadata.lastUpdated = new Date().toISOString();
+    writeFileSync(filePath, JSON.stringify(store, null, 2), "utf-8");
+}
+/**
+ * Load feedback store via the configured DataAdapter.
+ * Falls back to direct filesystem if adapter is not configured.
+ */
+export async function loadFeedbackViaAdapter(projectDir, adapter) {
+    const da = adapter ?? getDataAdapter();
+    return da.loadFeedback(projectDir);
+}
+/**
+ * Save feedback store via the configured DataAdapter.
+ */
+export async function saveFeedbackViaAdapter(store, projectDir, adapter) {
+    const da = adapter ?? getDataAdapter();
+    return da.saveFeedback(store, projectDir);
+}
+export function addFeedback(store, entry) {
+    store.entries.push(entry);
+    store.metadata.totalSubmissions++;
+    store.metadata.lastUpdated = new Date().toISOString();
+    return store;
+}
+// ─── Statistics ─────────────────────────────────────────────────────────────
+export function computeFeedbackStats(store) {
+    const perRule = new Map();
+    const perJudge = new Map();
+    let tp = 0;
+    let fp = 0;
+    let wontfix = 0;
+    for (const entry of store.entries) {
+        // Overall counts
+        if (entry.verdict === "tp")
+            tp++;
+        else if (entry.verdict === "fp")
+            fp++;
+        else if (entry.verdict === "wontfix")
+            wontfix++;
+        // Per-rule stats
+        const ruleStats = perRule.get(entry.ruleId) || {
+            ruleId: entry.ruleId,
+            total: 0,
+            tp: 0,
+            fp: 0,
+            wontfix: 0,
+            fpRate: 0,
+        };
+        ruleStats.total++;
+        if (entry.verdict === "tp")
+            ruleStats.tp++;
+        else if (entry.verdict === "fp")
+            ruleStats.fp++;
+        else if (entry.verdict === "wontfix")
+            ruleStats.wontfix++;
+        ruleStats.fpRate = ruleStats.total > 0 ? ruleStats.fp / ruleStats.total : 0;
+        perRule.set(entry.ruleId, ruleStats);
+        // Per-judge stats (by rule prefix, e.g. "SEC" from "SEC-001")
+        const prefix = entry.ruleId.split("-")[0];
+        if (prefix) {
+            const judgeStats = perJudge.get(prefix) || {
+                judgePrefix: prefix,
+                total: 0,
+                tp: 0,
+                fp: 0,
+                wontfix: 0,
+                fpRate: 0,
+            };
+            judgeStats.total++;
+            if (entry.verdict === "tp")
+                judgeStats.tp++;
+            else if (entry.verdict === "fp")
+                judgeStats.fp++;
+            else if (entry.verdict === "wontfix")
+                judgeStats.wontfix++;
+            judgeStats.fpRate = judgeStats.total > 0 ? judgeStats.fp / judgeStats.total : 0;
+            perJudge.set(prefix, judgeStats);
+        }
+    }
+    const total = store.entries.length;
+    return {
+        total,
+        truePositives: tp,
+        falsePositives: fp,
+        wontFix: wontfix,
+        falsePositiveRate: total > 0 ? fp / total : 0,
+        perRule,
+        perJudge,
+    };
+}
+/**
+ * Get a lookup map of FP rates by rule ID, suitable for confidence calibration.
+ */
+export function getFpRateByRule(store) {
+    const stats = computeFeedbackStats(store);
+    const result = new Map();
+    for (const [ruleId, ruleStat] of stats.perRule) {
+        if (ruleStat.total >= 3) {
+            // Only calibrate if we have enough data
+            result.set(ruleId, ruleStat.fpRate);
+        }
+    }
+    return result;
+}
+// ─── Team-wide Feedback Aggregation ─────────────────────────────────────────
+/**
+ * Merge multiple feedback stores into a single aggregate store.
+ * Entries are deduplicated by {ruleId + verdict + timestamp + filePath}.
+ * Each source can be tagged with a contributor identifier.
+ */
+export function mergeFeedbackStores(stores, contributorLabels) {
+    const merged = createEmptyStore();
+    const seen = new Set();
+    for (let i = 0; i < stores.length; i++) {
+        const store = stores[i];
+        const label = contributorLabels?.[i];
+        for (const entry of store.entries) {
+            // Tag with contributor if not already set
+            const tagged = label && !entry.contributor ? { ...entry, contributor: label } : entry;
+            // Dedup key: ruleId + verdict + timestamp + filePath
+            const key = `${tagged.ruleId}::${tagged.verdict}::${tagged.timestamp}::${tagged.filePath || ""}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                merged.entries.push(tagged);
+            }
+        }
+    }
+    merged.metadata.totalSubmissions = merged.entries.length;
+    merged.metadata.lastUpdated = new Date().toISOString();
+    return merged;
+}
+/**
+ * Compute team-wide feedback statistics with multi-contributor consensus.
+ * Identifies rules where multiple contributors independently flagged issues
+ * as FP (consensus) or where feedback is split between TP and FP (disputed).
+ */
+export function computeTeamFeedbackStats(store) {
+    const base = computeFeedbackStats(store);
+    // Track per-rule contributor data
+    const ruleContributors = new Map();
+    const ruleFpContributors = new Map();
+    for (const entry of store.entries) {
+        const contributor = entry.contributor || "anonymous";
+        const rc = ruleContributors.get(entry.ruleId) ?? new Set();
+        rc.add(contributor);
+        ruleContributors.set(entry.ruleId, rc);
+        if (entry.verdict === "fp") {
+            const fc = ruleFpContributors.get(entry.ruleId) ?? new Set();
+            fc.add(contributor);
+            ruleFpContributors.set(entry.ruleId, fc);
+        }
+    }
+    // Build per-rule team stats
+    const perRuleTeam = new Map();
+    for (const [ruleId, ruleStats] of base.perRule) {
+        const contributors = ruleContributors.get(ruleId)?.size ?? 1;
+        const fpContributors = ruleFpContributors.get(ruleId)?.size ?? 0;
+        perRuleTeam.set(ruleId, {
+            ...ruleStats,
+            contributors,
+            fpContributors,
+            consensus: contributors > 0 ? fpContributors / contributors : 0,
+        });
+    }
+    // Identify consensus FP rules (≥2 contributors independently flagged FP)
+    const consensusFpRules = [];
+    const disputedRules = [];
+    for (const [ruleId, teamStats] of perRuleTeam) {
+        if (teamStats.fpContributors >= 2) {
+            consensusFpRules.push(ruleId);
+        }
+        // Disputed: has both TP and FP verdicts from different contributors
+        if (teamStats.tp > 0 && teamStats.fp > 0 && teamStats.contributors >= 2) {
+            disputedRules.push(ruleId);
+        }
+    }
+    // Count distinct contributors across all entries
+    const allContributors = new Set(store.entries.map((e) => e.contributor || "anonymous"));
+    return {
+        ...base,
+        contributorCount: allContributors.size,
+        perRuleTeam,
+        consensusFpRules: consensusFpRules.sort(),
+        disputedRules: disputedRules.sort(),
+    };
+}
+/**
+ * Format team feedback stats as a human-readable summary.
+ */
+export function formatTeamStatsOutput(stats) {
+    const lines = [];
+    lines.push("╔══════════════════════════════════════════════════════════════╗");
+    lines.push("║        Judges Panel — Team Feedback Statistics              ║");
+    lines.push("╚══════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    lines.push(`  Contributors       : ${stats.contributorCount}`);
+    lines.push(`  Total Feedback     : ${stats.total}`);
+    lines.push(`  True Positives     : ${stats.truePositives}`);
+    lines.push(`  False Positives    : ${stats.falsePositives}`);
+    lines.push(`  Won't Fix          : ${stats.wontFix}`);
+    lines.push(`  Team FP Rate       : ${(stats.falsePositiveRate * 100).toFixed(1)}%`);
+    lines.push("");
+    if (stats.consensusFpRules.length > 0) {
+        lines.push("  ⚠ Consensus FP Rules (≥2 contributors agree):");
+        lines.push("  " + "─".repeat(55));
+        for (const ruleId of stats.consensusFpRules) {
+            const rs = stats.perRuleTeam.get(ruleId);
+            lines.push(`    ${ruleId.padEnd(12)} ${rs.fpContributors}/${rs.contributors} contributors flagged FP (${(rs.fpRate * 100).toFixed(0)}% FP rate)`);
+        }
+        lines.push("");
+    }
+    if (stats.disputedRules.length > 0) {
+        lines.push("  ⚡ Disputed Rules (mixed TP/FP verdicts):");
+        lines.push("  " + "─".repeat(55));
+        for (const ruleId of stats.disputedRules) {
+            const rs = stats.perRuleTeam.get(ruleId);
+            lines.push(`    ${ruleId.padEnd(12)} ${rs.tp}tp / ${rs.fp}fp from ${rs.contributors} contributors`);
+        }
+        lines.push("");
+    }
+    if (stats.perJudge.size > 0) {
+        lines.push("  Per-Judge FP Rates:");
+        lines.push("  " + "─".repeat(55));
+        const sorted = [...stats.perJudge.values()].sort((a, b) => b.fpRate - a.fpRate);
+        for (const j of sorted) {
+            const prefix = j.judgePrefix.padEnd(12);
+            const rate = `${(j.fpRate * 100).toFixed(1)}%`.padStart(6);
+            lines.push(`  ${prefix} FP: ${rate}   (${j.tp}tp / ${j.fp}fp / ${j.wontfix}wf)`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function parseFeedbackArgs(argv) {
+    const args = {
+        subcommand: argv[3] || "stats",
+        format: "text",
+    };
+    for (let i = 4; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--rule":
+            case "-r":
+                args.ruleId = argv[++i];
+                break;
+            case "--verdict":
+            case "-v":
+                args.verdict = argv[++i];
+                break;
+            case "--comment":
+            case "-m":
+                args.comment = argv[++i];
+                break;
+            case "--file":
+            case "-f":
+                args.filePath = argv[++i];
+                break;
+            case "--title":
+                args.title = argv[++i];
+                break;
+            case "--severity":
+                args.severity = argv[++i];
+                break;
+            case "--feedback-file":
+                args.feedbackFile = argv[++i];
+                break;
+            case "--format":
+            case "-o":
+                args.format = argv[++i];
+                break;
+            default:
+                break;
+        }
+    }
+    return args;
+}
+function printFeedbackHelp() {
+    console.log(`
+Judges Panel — Feedback & False Positive Tracking
+
+USAGE:
+  judges feedback submit --rule <id> --verdict <tp|fp|wontfix>   Submit feedback
+  judges feedback stats                                           View FP rate stats
+  judges feedback tune                                            Auto-tune recommendations
+  judges feedback export                                          Export as JSON
+  judges feedback reset                                           Clear all feedback
+
+SUBMIT OPTIONS:
+  --rule, -r <id>          Rule ID (e.g. SEC-001, AUTH-002)
+  --verdict, -v <verdict>  tp (true positive), fp (false positive), wontfix
+  --comment, -m <text>     Optional comment explaining the feedback
+  --file, -f <path>        File where finding was reported
+  --title <text>           Finding title for context
+  --severity <sev>         Finding severity
+  --feedback-file <path>   Path to feedback file (default: .judges-feedback.json)
+  --format, -o <fmt>       Output format: text, json
+
+EXAMPLES:
+  judges feedback submit --rule SEC-001 --verdict fp --comment "Used in test file"
+  judges feedback submit --rule AUTH-002 --verdict tp
+  judges feedback stats
+  judges feedback export > feedback-report.json
+`);
+}
+function formatStatsOutput(stats) {
+    const lines = [];
+    lines.push("╔══════════════════════════════════════════════════════════════╗");
+    lines.push("║           Judges Panel — Feedback Statistics                ║");
+    lines.push("╚══════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    lines.push(`  Total Feedback     : ${stats.total}`);
+    lines.push(`  True Positives     : ${stats.truePositives}`);
+    lines.push(`  False Positives    : ${stats.falsePositives}`);
+    lines.push(`  Won't Fix          : ${stats.wontFix}`);
+    lines.push(`  FP Rate            : ${(stats.falsePositiveRate * 100).toFixed(1)}%`);
+    lines.push("");
+    if (stats.perJudge.size > 0) {
+        lines.push("  Per-Judge FP Rates:");
+        lines.push("  " + "─".repeat(55));
+        const sorted = [...stats.perJudge.values()].sort((a, b) => b.fpRate - a.fpRate);
+        for (const j of sorted) {
+            const prefix = j.judgePrefix.padEnd(12);
+            const rate = `${(j.fpRate * 100).toFixed(1)}%`.padStart(6);
+            const counts = `${j.tp}tp / ${j.fp}fp / ${j.wontfix}wf`;
+            lines.push(`  ${prefix} FP: ${rate}   (${counts})`);
+        }
+        lines.push("");
+    }
+    if (stats.perRule.size > 0) {
+        lines.push("  Per-Rule FP Rates (top 20):");
+        lines.push("  " + "─".repeat(55));
+        const sorted = [...stats.perRule.values()].sort((a, b) => b.fpRate - a.fpRate).slice(0, 20);
+        for (const r of sorted) {
+            const ruleId = r.ruleId.padEnd(12);
+            const rate = `${(r.fpRate * 100).toFixed(1)}%`.padStart(6);
+            const counts = `${r.tp}tp / ${r.fp}fp / ${r.wontfix}wf`;
+            lines.push(`  ${ruleId} FP: ${rate}   (${counts})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Parse dismissed findings from an LLM deep-review response.
+ *
+ * The deep-review prompt instructs the LLM to list dismissed findings in a
+ * "Dismissed Findings" section, each with a rule ID and explanation. This
+ * function extracts those entries from the markdown.
+ *
+ * Accepted formats:
+ *   - `SEC-001` — reason text
+ *   - `**SEC-001**` — reason text
+ *   - `SEC-001: reason text`
+ *   - `- SEC-001 — reason text`
+ *   - `- **SEC-001**: reason text`
+ */
+export function parseDismissedFindings(llmResponse) {
+    const dismissed = [];
+    const lines = llmResponse.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+        // Detect "Dismissed Findings" section header
+        if (/^#+\s*\*{0,2}Dismissed Findings\*{0,2}/i.test(line)) {
+            inSection = true;
+            continue;
+        }
+        // Detect section end (next heading or horizontal rule)
+        if (inSection && /^(?:#+\s|={3,}$|-{3,}$)/.test(line)) {
+            inSection = false;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        // Match rule IDs followed by explanations on each line
+        // Supports: - SEC-001 — reason, - **SEC-001**: reason, SEC-001: reason
+        const match = line.match(/\*{0,2}([A-Z]{2,10}-\d{1,4})\*{0,2}\s*[—:–-]\s*(.+)/);
+        if (match) {
+            const ruleId = match[1].trim();
+            const reason = match[2].trim();
+            if (ruleId && reason) {
+                dismissed.push({ ruleId, reason });
+            }
+        }
+    }
+    return dismissed;
+}
+/**
+ * Record L2 deep-review dismissals as FP feedback entries.
+ *
+ * This closes the feedback loop: when the LLM's deep contextual review
+ * dismisses L1 pattern findings as false positives, those dismissals are
+ * persisted to the feedback store and feed into the confidence calibration
+ * system (auto-tune, FP rate tracking).
+ *
+ * Returns the number of new entries recorded.
+ */
+export function recordL2Feedback(llmResponse, feedbackPath, filePath) {
+    const dismissed = parseDismissedFindings(llmResponse);
+    if (dismissed.length === 0)
+        return 0;
+    const store = loadFeedbackStore(feedbackPath);
+    const now = new Date().toISOString();
+    for (const d of dismissed) {
+        addFeedback(store, {
+            ruleId: d.ruleId,
+            verdict: "fp",
+            comment: `L2 deep review dismissal: ${d.reason}`,
+            filePath,
+            timestamp: now,
+            source: "l2-dismissal",
+        });
+    }
+    saveFeedbackStore(store, feedbackPath);
+    return dismissed.length;
+}
+export function runFeedback(argv) {
+    const args = parseFeedbackArgs(argv);
+    if (args.subcommand === "--help" || args.subcommand === "-h") {
+        printFeedbackHelp();
+        process.exit(0);
+    }
+    const store = loadFeedbackStore(args.feedbackFile);
+    switch (args.subcommand) {
+        case "submit": {
+            if (!args.ruleId) {
+                console.error("Error: --rule is required for submit");
+                process.exit(1);
+            }
+            if (!args.verdict || !["tp", "fp", "wontfix"].includes(args.verdict)) {
+                console.error("Error: --verdict must be one of: tp, fp, wontfix");
+                process.exit(1);
+            }
+            const entry = {
+                ruleId: args.ruleId.toUpperCase(),
+                verdict: args.verdict,
+                comment: args.comment,
+                filePath: args.filePath,
+                title: args.title,
+                severity: args.severity,
+                timestamp: new Date().toISOString(),
+            };
+            addFeedback(store, entry);
+            saveFeedbackStore(store, args.feedbackFile);
+            const verdictLabel = { tp: "true positive", fp: "false positive", wontfix: "won't fix" };
+            console.log(`✓ Recorded ${args.ruleId.toUpperCase()} as ${verdictLabel[args.verdict]}`);
+            process.exit(0);
+            break;
+        }
+        case "stats": {
+            const stats = computeFeedbackStats(store);
+            if (args.format === "json") {
+                // Convert Maps to objects for JSON
+                const jsonStats = {
+                    ...stats,
+                    perRule: Object.fromEntries(stats.perRule),
+                    perJudge: Object.fromEntries(stats.perJudge),
+                };
+                console.log(JSON.stringify(jsonStats, null, 2));
+            }
+            else {
+                console.log(formatStatsOutput(stats));
+            }
+            process.exit(0);
+            break;
+        }
+        case "export": {
+            console.log(JSON.stringify(store, null, 2));
+            process.exit(0);
+            break;
+        }
+        case "reset": {
+            const empty = createEmptyStore();
+            saveFeedbackStore(empty, args.feedbackFile);
+            console.log("✓ Feedback store reset");
+            process.exit(0);
+            break;
+        }
+        case "tune": {
+            const report = generateAutoTuneReport(store);
+            if (args.format === "json") {
+                console.log(formatAutoTuneReportJson(report));
+            }
+            else {
+                console.log(formatAutoTuneReport(report));
+            }
+            process.exit(0);
+            break;
+        }
+        default:
+            console.error(`Unknown feedback subcommand: ${args.subcommand}`);
+            printFeedbackHelp();
+            process.exit(1);
+    }
+}

package/dist/commands/finding-age-analysis.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Finding-age-analysis — Analyze the age and lifecycle of findings over time.
+ */
+export declare function runFindingAgeAnalysis(argv: string[]): void;

package/dist/commands/finding-age-analysis.js

@@ -0,0 +1,144 @@
+/**
+ * Finding-age-analysis — Analyze the age and lifecycle of findings over time.
+ */
+import { readFileSync, existsSync, readdirSync } from "fs";
+// ─── Analysis ───────────────────────────────────────────────────────────────
+function analyzeAge(verdicts) {
+    const ruleOccurrences = new Map();
+    const ruleFirstSeen = new Map();
+    const now = Date.now();
+    const timestamps = verdicts.map((v) => v.timestamp).sort();
+    for (const v of verdicts) {
+        for (const f of v.verdict.findings) {
+            ruleOccurrences.set(f.ruleId, (ruleOccurrences.get(f.ruleId) || 0) + 1);
+            if (!ruleFirstSeen.has(f.ruleId)) {
+                ruleFirstSeen.set(f.ruleId, v.timestamp);
+            }
+        }
+    }
+    // bucket by age
+    const buckets = [
+        { label: "< 1 day", count: 0, ruleIds: [] },
+        { label: "1-7 days", count: 0, ruleIds: [] },
+        { label: "1-4 weeks", count: 0, ruleIds: [] },
+        { label: "> 4 weeks", count: 0, ruleIds: [] },
+    ];
+    for (const [ruleId, firstSeen] of ruleFirstSeen) {
+        const age = now - new Date(firstSeen).getTime();
+        const days = age / (1000 * 60 * 60 * 24);
+        if (days < 1) {
+            buckets[0].count++;
+            buckets[0].ruleIds.push(ruleId);
+        }
+        else if (days < 7) {
+            buckets[1].count++;
+            buckets[1].ruleIds.push(ruleId);
+        }
+        else if (days < 28) {
+            buckets[2].count++;
+            buckets[2].ruleIds.push(ruleId);
+        }
+        else {
+            buckets[3].count++;
+            buckets[3].ruleIds.push(ruleId);
+        }
+    }
+    // recurring rules
+    const recurring = [...ruleOccurrences.entries()]
+        .filter(([, count]) => count > 1)
+        .sort((a, b) => b[1] - a[1])
+        .map(([ruleId, occurrences]) => ({ ruleId, occurrences }));
+    return {
+        totalFindings: ruleFirstSeen.size,
+        oldestTimestamp: timestamps[0] || "",
+        newestTimestamp: timestamps[timestamps.length - 1] || "",
+        buckets,
+        recurringRules: recurring,
+    };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingAgeAnalysis(argv) {
+    const dirIdx = argv.indexOf("--dir");
+    const fileIdx = argv.indexOf("--file");
+    const formatIdx = argv.indexOf("--format");
+    const dirPath = dirIdx >= 0 ? argv[dirIdx + 1] : undefined;
+    const filePath = fileIdx >= 0 ? argv[fileIdx + 1] : undefined;
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges finding-age-analysis — Analyze finding age over time
+
+Usage:
+  judges finding-age-analysis --dir <verdicts-dir> [--format table|json]
+  judges finding-age-analysis --file <verdict.json> [--format table|json]
+
+Options:
+  --dir <path>       Directory of verdict JSON files
+  --file <path>      Single verdict JSON file
+  --format <fmt>     Output format: table (default), json
+  --help, -h         Show this help
+`);
+        return;
+    }
+    const verdicts = [];
+    if (dirPath && existsSync(dirPath)) {
+        const files = readdirSync(dirPath);
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            try {
+                const content = readFileSync(`${dirPath}/${file}`, "utf-8");
+                const verdict = JSON.parse(content);
+                verdicts.push({ verdict, timestamp: verdict.timestamp || file.replace(".json", "") });
+            }
+            catch {
+                // skip invalid files
+            }
+        }
+    }
+    else if (filePath && existsSync(filePath)) {
+        try {
+            const verdict = JSON.parse(readFileSync(filePath, "utf-8"));
+            verdicts.push({ verdict, timestamp: verdict.timestamp || new Date().toISOString() });
+        }
+        catch {
+            console.error("Error: invalid JSON");
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else {
+        console.error("Error: --dir or --file required");
+        process.exitCode = 1;
+        return;
+    }
+    if (verdicts.length === 0) {
+        console.log("No verdict files found");
+        return;
+    }
+    const report = analyzeAge(verdicts);
+    if (format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`\nFinding Age Analysis`);
+    console.log("═".repeat(60));
+    console.log(`  Total unique findings: ${report.totalFindings}`);
+    console.log(`  Reports analyzed: ${verdicts.length}`);
+    console.log(`  Range: ${report.oldestTimestamp} → ${report.newestTimestamp}`);
+    console.log("─".repeat(60));
+    console.log(`${"Age Bucket".padEnd(16)} ${"Count".padEnd(8)} Rules`);
+    console.log("─".repeat(60));
+    for (const b of report.buckets) {
+        const rules = b.ruleIds.slice(0, 3).join(", ");
+        const more = b.ruleIds.length > 3 ? ` +${b.ruleIds.length - 3} more` : "";
+        console.log(`${b.label.padEnd(16)} ${String(b.count).padEnd(8)} ${rules}${more}`);
+    }
+    if (report.recurringRules.length > 0) {
+        console.log(`\n  Recurring Rules (${report.recurringRules.length}):`);
+        for (const r of report.recurringRules.slice(0, 10)) {
+            console.log(`    ${r.ruleId.padEnd(20)} × ${r.occurrences}`);
+        }
+    }
+    console.log("═".repeat(60));
+}