@kevinrabun/judges 3.115.0 → 3.115.2

package/dist/commands/false-negatives.js

@@ -0,0 +1,165 @@
+/**
+ * False-negative report — collect and analyze cases where Judges
+ * missed a real vulnerability or bug that was later found manually.
+ *
+ * Builds a local feedback database (.judges-false-negatives.json)
+ * that helps teams understand blind spots and request new rules.
+ */
+import { createHash } from "crypto";
+// ─── Database ───────────────────────────────────────────────────────────────
+const DB_FILE = ".judges-false-negatives.json";
+function loadDb() {
+    const { readFileSync, existsSync } = require("fs");
+    if (existsSync(DB_FILE)) {
+        try {
+            return JSON.parse(readFileSync(DB_FILE, "utf-8"));
+        }
+        catch {
+            /* corrupt */
+        }
+    }
+    return { entries: [], version: "1.0" };
+}
+function saveDb(db) {
+    const { writeFileSync } = require("fs");
+    writeFileSync(DB_FILE, JSON.stringify(db, null, 2), "utf-8");
+}
+export function addFalseNegative(entry) {
+    const db = loadDb();
+    const fn = {
+        ...entry,
+        id: createHash("sha256")
+            .update(Date.now().toString() + entry.file + entry.description)
+            .digest("hex")
+            .slice(0, 10),
+        timestamp: new Date().toISOString(),
+        status: "open",
+    };
+    db.entries.push(fn);
+    saveDb(db);
+    return fn;
+}
+export function getFalseNegativeStats(db) {
+    const open = db.entries.filter((e) => e.status === "open").length;
+    const byCategory = {};
+    const bySeverity = {};
+    const byLanguage = {};
+    for (const e of db.entries) {
+        byCategory[e.category] = (byCategory[e.category] || 0) + 1;
+        bySeverity[e.severity] = (bySeverity[e.severity] || 0) + 1;
+        byLanguage[e.language] = (byLanguage[e.language] || 0) + 1;
+    }
+    return { total: db.entries.length, open, byCategory, bySeverity, byLanguage };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFalseNegativeReport(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges false-negatives — Report and track missed vulnerabilities
+
+Usage:
+  judges false-negatives                              Show report
+  judges false-negatives --add --file src/app.ts \\
+    --line 42 --category injection --severity high \\
+    --description "SQL injection via user input"     Add a missed finding
+  judges false-negatives --resolve <id>               Mark as resolved
+
+Options:
+  --add                  Add a new false-negative report
+  --file <path>          File where the issue was found
+  --line <n>             Line number
+  --category <cat>       Category (injection, auth, crypto, xss, etc.)
+  --severity <level>     Severity (critical, high, medium, low)
+  --description <text>   Description of what was missed
+  --language <lang>      Language (auto-detected from file)
+  --resolve <id>         Mark entry as resolved
+  --format json          JSON output
+  --help, -h             Show this help
+
+This builds a local feedback database that helps identify blind spots
+in the current rule set, informing future rule development.
+`);
+        return;
+    }
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    if (argv.includes("--add")) {
+        const file = argv.find((_a, i) => argv[i - 1] === "--file") || "";
+        const lineStr = argv.find((_a, i) => argv[i - 1] === "--line");
+        const category = argv.find((_a, i) => argv[i - 1] === "--category") || "unknown";
+        const severity = argv.find((_a, i) => argv[i - 1] === "--severity") || "medium";
+        const description = argv.find((_a, i) => argv[i - 1] === "--description") || "";
+        const language = argv.find((_a, i) => argv[i - 1] === "--language") || detectLanguage(file);
+        if (!file || !description) {
+            console.error("Error: --file and --description required");
+            process.exit(1);
+        }
+        const entry = addFalseNegative({
+            file,
+            line: lineStr ? parseInt(lineStr, 10) : undefined,
+            category,
+            severity,
+            description,
+            language,
+        });
+        console.log(`  ✅ Added false-negative report: ${entry.id}`);
+        return;
+    }
+    const resolveId = argv.find((_a, i) => argv[i - 1] === "--resolve");
+    if (resolveId) {
+        const db = loadDb();
+        const entry = db.entries.find((e) => e.id === resolveId);
+        if (!entry) {
+            console.error(`Error: entry ${resolveId} not found`);
+            process.exit(1);
+        }
+        entry.status = "rule-added";
+        saveDb(db);
+        console.log(`  ✅ Resolved: ${resolveId}`);
+        return;
+    }
+    // Show report
+    const db = loadDb();
+    if (db.entries.length === 0) {
+        console.log("\n  No false-negative reports. Use --add to report a missed finding.\n");
+        return;
+    }
+    const stats = getFalseNegativeStats(db);
+    if (format === "json") {
+        console.log(JSON.stringify({ stats, entries: db.entries }, null, 2));
+        return;
+    }
+    console.log(`\n  False-Negative Analysis\n`);
+    console.log(`  Total: ${stats.total} | Open: ${stats.open}\n`);
+    console.log("  By Category:");
+    for (const [cat, count] of Object.entries(stats.byCategory).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${cat.padEnd(20)} ${count}`);
+    }
+    console.log("\n  By Severity:");
+    for (const [sev, count] of Object.entries(stats.bySeverity).sort((a, b) => b[1] - a[1])) {
+        console.log(`    ${sev.padEnd(20)} ${count}`);
+    }
+    console.log("\n  Recent entries:");
+    for (const e of db.entries.slice(-10)) {
+        const status = e.status === "open" ? "🔴" : "✅";
+        console.log(`    ${status} ${e.id}  ${e.severity.padEnd(8)} ${e.category.padEnd(15)} ${e.description.slice(0, 50)}`);
+    }
+    console.log("");
+}
+function detectLanguage(file) {
+    const { extname } = require("path");
+    const ext = extname(file).toLowerCase();
+    const map = {
+        ".ts": "typescript",
+        ".tsx": "typescript",
+        ".js": "javascript",
+        ".jsx": "javascript",
+        ".py": "python",
+        ".go": "go",
+        ".rs": "rust",
+        ".java": "java",
+        ".cs": "csharp",
+        ".rb": "ruby",
+        ".php": "php",
+    };
+    return map[ext] || "unknown";
+}

package/dist/commands/feedback-rules.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `judges feedback-rules` — Feedback-to-Rule Pipeline
+ *
+ * Analyzes feedback data and auto-suggests (or auto-writes) suppression rules
+ * to `.judgesrc` when feedback reaches consensus (≥N entries mark as FP).
+ *
+ * Usage:
+ *   judges feedback-rules                # analyze and suggest rules
+ *   judges feedback-rules --apply        # auto-write suppression rules to .judgesrc
+ *   judges feedback-rules --threshold 3  # require 3+ FP verdicts (default: 3)
+ *   judges feedback-rules --fp-rate 0.7  # require 70%+ FP rate (default: 0.75)
+ */
+import { type FeedbackStore } from "./feedback.js";
+export interface RuleSuggestion {
+    ruleId: string;
+    action: "disable" | "downgrade-severity";
+    fpRate: number;
+    fpCount: number;
+    totalCount: number;
+    reason: string;
+    /** Sample FP comments from feedback */
+    sampleComments: string[];
+}
+export declare function analyzeFeedbackForRules(store: FeedbackStore, options?: {
+    minSamples?: number;
+    fpRateThreshold?: number;
+}): RuleSuggestion[];
+export declare function runFeedbackRules(argv: string[]): void;

package/dist/commands/feedback-rules.js

@@ -0,0 +1,173 @@
+/**
+ * `judges feedback-rules` — Feedback-to-Rule Pipeline
+ *
+ * Analyzes feedback data and auto-suggests (or auto-writes) suppression rules
+ * to `.judgesrc` when feedback reaches consensus (≥N entries mark as FP).
+ *
+ * Usage:
+ *   judges feedback-rules                # analyze and suggest rules
+ *   judges feedback-rules --apply        # auto-write suppression rules to .judgesrc
+ *   judges feedback-rules --threshold 3  # require 3+ FP verdicts (default: 3)
+ *   judges feedback-rules --fp-rate 0.7  # require 70%+ FP rate (default: 0.75)
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { loadFeedbackStore } from "./feedback.js";
+// ─── Analysis ───────────────────────────────────────────────────────────────
+export function analyzeFeedbackForRules(store, options) {
+    const minSamples = options?.minSamples ?? 3;
+    const fpThreshold = options?.fpRateThreshold ?? 0.75;
+    // Aggregate feedback by rule ID
+    const byRule = new Map();
+    for (const entry of store.entries) {
+        const entries = byRule.get(entry.ruleId) ?? [];
+        entries.push(entry);
+        byRule.set(entry.ruleId, entries);
+    }
+    const suggestions = [];
+    for (const [ruleId, entries] of byRule) {
+        if (entries.length < minSamples)
+            continue;
+        const fpCount = entries.filter((e) => e.verdict === "fp").length;
+        const fpRate = fpCount / entries.length;
+        if (fpRate >= fpThreshold) {
+            // High FP rate — suggest disabling
+            const comments = entries
+                .filter((e) => e.verdict === "fp" && e.comment)
+                .map((e) => e.comment)
+                .slice(0, 3);
+            suggestions.push({
+                ruleId,
+                action: "disable",
+                fpRate,
+                fpCount,
+                totalCount: entries.length,
+                reason: `${fpCount}/${entries.length} feedback entries (${Math.round(fpRate * 100)}%) marked as false positive`,
+                sampleComments: comments,
+            });
+        }
+        else if (fpRate >= 0.5) {
+            // Moderate FP rate — suggest severity downgrade instead of full disable
+            const comments = entries
+                .filter((e) => e.verdict === "fp" && e.comment)
+                .map((e) => e.comment)
+                .slice(0, 3);
+            suggestions.push({
+                ruleId,
+                action: "downgrade-severity",
+                fpRate,
+                fpCount,
+                totalCount: entries.length,
+                reason: `${fpCount}/${entries.length} feedback entries (${Math.round(fpRate * 100)}%) marked as false positive — moderate FP rate suggests downgrade rather than disable`,
+                sampleComments: comments,
+            });
+        }
+    }
+    // Sort by FP rate descending
+    suggestions.sort((a, b) => b.fpRate - a.fpRate);
+    return suggestions;
+}
+// ─── Apply to .judgesrc ────────────────────────────────────────────────────
+function applyToConfig(suggestions, configPath) {
+    let config = {};
+    if (existsSync(configPath)) {
+        try {
+            config = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const disabledRules = new Set(config.disabledRules ?? []);
+    const added = [];
+    const skipped = [];
+    for (const s of suggestions) {
+        if (s.action === "disable") {
+            if (disabledRules.has(s.ruleId)) {
+                skipped.push(s.ruleId);
+            }
+            else {
+                disabledRules.add(s.ruleId);
+                added.push(s.ruleId);
+            }
+        }
+        // downgrade-severity is informational only — doesn't modify config
+    }
+    if (added.length > 0) {
+        config.disabledRules = [...disabledRules].sort();
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    }
+    return { added, skipped };
+}
+// ─── CLI Command ────────────────────────────────────────────────────────────
+export function runFeedbackRules(argv) {
+    let apply = false;
+    let threshold = 3;
+    let fpRate = 0.75;
+    let feedbackPath;
+    for (let i = 3; i < argv.length; i++) {
+        switch (argv[i]) {
+            case "--apply":
+                apply = true;
+                break;
+            case "--threshold":
+                threshold = parseInt(argv[++i], 10) || 3;
+                break;
+            case "--fp-rate":
+                fpRate = parseFloat(argv[++i]) || 0.75;
+                break;
+            case "--feedback":
+                feedbackPath = argv[++i];
+                break;
+        }
+    }
+    const store = loadFeedbackStore(feedbackPath);
+    if (store.entries.length === 0) {
+        console.log("\n  No feedback data found. Submit feedback with `judges feedback add` first.\n");
+        return;
+    }
+    const suggestions = analyzeFeedbackForRules(store, {
+        minSamples: threshold,
+        fpRateThreshold: fpRate,
+    });
+    console.log("");
+    console.log("╔══════════════════════════════════════════════════════════════╗");
+    console.log("║        Judges Panel — Feedback→Rule Analysis                ║");
+    console.log("╚══════════════════════════════════════════════════════════════╝");
+    console.log("");
+    console.log(`  Feedback entries : ${store.entries.length}`);
+    console.log(`  Threshold        : ≥${threshold} entries, ≥${Math.round(fpRate * 100)}% FP rate`);
+    console.log(`  Suggestions      : ${suggestions.length}`);
+    console.log("");
+    if (suggestions.length === 0) {
+        console.log("  ✅ No rules have reached the FP consensus threshold.\n");
+        return;
+    }
+    console.log("  Suggested Rule Changes:");
+    console.log("  " + "─".repeat(58));
+    for (const s of suggestions) {
+        const icon = s.action === "disable" ? "🚫" : "⬇️ ";
+        console.log(`  ${icon} ${s.ruleId.padEnd(14)} ${s.action.padEnd(20)} ${Math.round(s.fpRate * 100)}% FP (${s.fpCount}/${s.totalCount})`);
+        if (s.sampleComments.length > 0) {
+            console.log(`     Comment: "${s.sampleComments[0].slice(0, 60)}"`);
+        }
+    }
+    console.log("");
+    if (apply) {
+        const configPath = resolve(".", ".judgesrc");
+        const result = applyToConfig(suggestions, configPath);
+        if (result.added.length > 0) {
+            console.log(`  ✅ Added ${result.added.length} rule(s) to .judgesrc disabledRules:`);
+            for (const r of result.added) {
+                console.log(`     + ${r}`);
+            }
+        }
+        if (result.skipped.length > 0) {
+            console.log(`  ⬜ ${result.skipped.length} rule(s) already disabled`);
+        }
+        console.log("");
+    }
+    else {
+        console.log("  Run with --apply to write changes to .judgesrc\n");
+    }
+}

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));
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Finding-age-report — Report on finding ages and staleness.
+ */
+export declare function runFindingAgeReport(argv: string[]): void;

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

@@ -0,0 +1,154 @@
+/**
+ * Finding-age-report — Report on finding ages and staleness.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { dirname } from "path";
+// ─── Storage ────────────────────────────────────────────────────────────────
+const AGE_FILE = ".judges/finding-ages.json";
+function loadStore() {
+    if (!existsSync(AGE_FILE))
+        return { version: "1.0.0", entries: [] };
+    try {
+        return JSON.parse(readFileSync(AGE_FILE, "utf-8"));
+    }
+    catch {
+        return { version: "1.0.0", entries: [] };
+    }
+}
+function saveStore(store) {
+    mkdirSync(dirname(AGE_FILE), { recursive: true });
+    writeFileSync(AGE_FILE, JSON.stringify(store, null, 2), "utf-8");
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingAgeReport(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges finding-age-report — Report on finding ages
+
+Usage:
+  judges finding-age-report                         Show age report
+  judges finding-age-report update --file <results>  Update ages from results
+  judges finding-age-report stale --days <n>         Show findings older than N days
+  judges finding-age-report clear                    Clear age data
+
+Options:
+  --file <path>     Results file
+  --days <n>        Staleness threshold (default: 30)
+  --format json     JSON output
+  --help, -h        Show this help
+`);
+        return;
+    }
+    const subcommand = argv.find((a) => ["update", "stale", "clear"].includes(a));
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    const store = loadStore();
+    if (subcommand === "update") {
+        const file = argv.find((_a, i) => argv[i - 1] === "--file");
+        if (!file) {
+            console.error("Error: --file required");
+            process.exitCode = 1;
+            return;
+        }
+        if (!existsSync(file)) {
+            console.error(`Error: file not found: ${file}`);
+            process.exitCode = 1;
+            return;
+        }
+        let findings;
+        try {
+            const data = JSON.parse(readFileSync(file, "utf-8"));
+            findings = Array.isArray(data) ? data : data.findings || [];
+        }
+        catch {
+            console.error("Error: could not parse results file");
+            process.exitCode = 1;
+            return;
+        }
+        const now = new Date().toISOString();
+        let newCount = 0;
+        let updatedCount = 0;
+        for (const f of findings) {
+            const id = f.ruleId || f.title || "unknown";
+            const existing = store.entries.find((e) => e.findingId === id);
+            if (existing) {
+                existing.lastSeen = now;
+                updatedCount++;
+            }
+            else {
+                store.entries.push({
+                    findingId: id,
+                    ruleId: f.ruleId || "",
+                    severity: f.severity || "medium",
+                    firstSeen: now,
+                    lastSeen: now,
+                });
+                newCount++;
+            }
+        }
+        saveStore(store);
+        console.log(`Updated: ${newCount} new, ${updatedCount} existing findings.`);
+        return;
+    }
+    if (subcommand === "stale") {
+        const days = parseInt(argv.find((_a, i) => argv[i - 1] === "--days") || "30", 10);
+        const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+        const stale = store.entries.filter((e) => new Date(e.firstSeen).getTime() < cutoff);
+        if (stale.length === 0) {
+            console.log(`No findings older than ${days} days.`);
+            return;
+        }
+        if (format === "json") {
+            console.log(JSON.stringify(stale, null, 2));
+            return;
+        }
+        console.log(`\nStale Findings (> ${days} days): ${stale.length}`);
+        console.log("═".repeat(65));
+        for (const e of stale) {
+            const ageDays = Math.round((Date.now() - new Date(e.firstSeen).getTime()) / 86400000);
+            console.log(`  ${e.findingId.padEnd(30)} ${e.severity.padEnd(10)} ${ageDays} days old`);
+        }
+        console.log("═".repeat(65));
+        return;
+    }
+    if (subcommand === "clear") {
+        saveStore({ version: "1.0.0", entries: [] });
+        console.log("Age data cleared.");
+        return;
+    }
+    // Default: show report
+    if (store.entries.length === 0) {
+        console.log("No age data. Use 'judges finding-age-report update --file <f>' to start tracking.");
+        return;
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(store.entries, null, 2));
+        return;
+    }
+    // Group by age bucket
+    const now = Date.now();
+    const buckets = { "< 1 day": 0, "1-7 days": 0, "7-30 days": 0, "30-90 days": 0, "> 90 days": 0 };
+    for (const e of store.entries) {
+        const ageDays = (now - new Date(e.firstSeen).getTime()) / 86400000;
+        if (ageDays < 1)
+            buckets["< 1 day"]++;
+        else if (ageDays < 7)
+            buckets["1-7 days"]++;
+        else if (ageDays < 30)
+            buckets["7-30 days"]++;
+        else if (ageDays < 90)
+            buckets["30-90 days"]++;
+        else
+            buckets["> 90 days"]++;
+    }
+    console.log(`\nFinding Age Report (${store.entries.length} tracked):`);
+    console.log("═".repeat(40));
+    for (const [bucket, count] of Object.entries(buckets)) {
+        if (count > 0)
+            console.log(`  ${bucket.padEnd(15)} ${count}`);
+    }
+    console.log("═".repeat(40));
+    const avgAge = store.entries.reduce((sum, e) => sum + (now - new Date(e.firstSeen).getTime()), 0) /
+        store.entries.length /
+        86400000;
+    console.log(`  Average age: ${avgAge.toFixed(1)} days`);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Finding-age-tracker — Track the age of findings over time.
+ *
+ * Records when findings first appear and tracks their age,
+ * helping prioritize long-standing issues.
+ */
+export declare function runFindingAgeTracker(argv: string[]): void;