@kevinrabun/judges-cli 3.124.0

package/dist/commands/finding-top-offender.js

@@ -0,0 +1,75 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+function findTopOffenders(verdict) {
+    const findings = verdict.findings ?? [];
+    if (findings.length === 0)
+        return [];
+    const ruleMap = {};
+    for (const f of findings) {
+        if (!ruleMap[f.ruleId]) {
+            ruleMap[f.ruleId] = { count: 0, severities: {}, sampleTitle: f.title };
+        }
+        ruleMap[f.ruleId].count += 1;
+        ruleMap[f.ruleId].severities[f.severity] = (ruleMap[f.ruleId].severities[f.severity] ?? 0) + 1;
+    }
+    const entries = [];
+    for (const [ruleId, data] of Object.entries(ruleMap)) {
+        entries.push({
+            ruleId,
+            count: data.count,
+            severities: data.severities,
+            sampleTitle: data.sampleTitle,
+            percentage: Math.round((data.count / findings.length) * 100),
+        });
+    }
+    entries.sort((a, b) => b.count - a.count);
+    return entries;
+}
+export function runFindingTopOffender(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`Usage: judges finding-top-offender [options]
+
+Identify the most frequently triggered rules.
+
+Options:
+  --report <path>      Path to verdict JSON
+  --top <n>            Number of top offenders to show (default: 10)
+  --format <fmt>       Output format: table (default) or json
+  -h, --help           Show this help message`);
+        return;
+    }
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx !== -1 && argv[formatIdx + 1] ? argv[formatIdx + 1] : "table";
+    const topIdx = argv.indexOf("--top");
+    const topN = topIdx !== -1 && argv[topIdx + 1] ? parseInt(argv[topIdx + 1], 10) : 10;
+    const reportIdx = argv.indexOf("--report");
+    const reportPath = reportIdx !== -1 && argv[reportIdx + 1]
+        ? join(process.cwd(), argv[reportIdx + 1])
+        : join(process.cwd(), ".judges", "last-verdict.json");
+    if (!existsSync(reportPath)) {
+        console.log(`No report found at: ${reportPath}`);
+        return;
+    }
+    const data = JSON.parse(readFileSync(reportPath, "utf-8"));
+    const offenders = findTopOffenders(data);
+    const shown = offenders.slice(0, topN);
+    if (format === "json") {
+        console.log(JSON.stringify(shown, null, 2));
+        return;
+    }
+    console.log(`\n=== Top Offenders (${shown.length}/${offenders.length} rules) ===\n`);
+    if (shown.length === 0) {
+        console.log("No findings to analyse.");
+        return;
+    }
+    for (let i = 0; i < shown.length; i++) {
+        const e = shown[i];
+        const severityStr = Object.entries(e.severities)
+            .map(([s, n]) => `${s}:${n}`)
+            .join(" ");
+        console.log(`  #${i + 1}  ${e.ruleId} — ${e.count} findings (${e.percentage}%)`);
+        console.log(`       Severities: ${severityStr}`);
+        console.log(`       Example: ${e.sampleTitle}`);
+        console.log();
+    }
+}

package/dist/commands/finding-trace.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Finding-trace — Trace findings to their origin commit.
+ */
+export declare function runFindingTrace(argv: string[]): void;

package/dist/commands/finding-trace.js

@@ -0,0 +1,118 @@
+/**
+ * Finding-trace — Trace findings to their origin commit.
+ */
+import { readFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingTrace(argv) {
+    if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
+        console.log(`
+judges finding-trace — Trace findings to origin commits
+
+Usage:
+  judges finding-trace --file <results.json> [options]
+
+Options:
+  --file <path>      Result file (required)
+  --source <path>    Source file to trace against (for git blame)
+  --top <n>          Show top N findings (default: 10)
+  --format json      JSON output
+  --help, -h         Show this help
+
+Uses git blame to associate findings with the commits that introduced them.
+`);
+        return;
+    }
+    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;
+    }
+    const sourcePath = argv.find((_a, i) => argv[i - 1] === "--source");
+    const topStr = argv.find((_a, i) => argv[i - 1] === "--top");
+    const top = topStr ? parseInt(topStr, 10) : 10;
+    const format = argv.find((_a, i) => argv[i - 1] === "--format") || "text";
+    let verdict;
+    try {
+        verdict = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch {
+        console.error("Error: could not parse file");
+        process.exitCode = 1;
+        return;
+    }
+    const findings = verdict.findings || [];
+    const traced = [];
+    // Get blame info for source if provided
+    let blameLines = [];
+    if (sourcePath && existsSync(sourcePath)) {
+        try {
+            blameLines = execSync(`git blame --porcelain "${sourcePath}"`, { encoding: "utf-8" }).split("\n");
+        }
+        catch {
+            // Not in a git repo or file not tracked
+        }
+    }
+    // Parse blame data into commit map
+    const lineCommits = new Map();
+    if (blameLines.length > 0) {
+        let currentLine = 0;
+        for (const line of blameLines) {
+            const match = /^[0-9a-f]{40}\s+\d+\s+(\d+)/.exec(line);
+            if (match) {
+                currentLine = parseInt(match[1], 10);
+            }
+            if (line.startsWith("summary ") && currentLine > 0) {
+                lineCommits.set(currentLine, line.slice(8));
+            }
+        }
+    }
+    for (const f of findings) {
+        const lines = f.lineNumbers || [];
+        const commits = [];
+        for (const ln of lines) {
+            const commit = lineCommits.get(ln);
+            if (commit && !commits.includes(commit))
+                commits.push(commit);
+        }
+        traced.push({
+            ruleId: f.ruleId,
+            title: f.title,
+            severity: f.severity,
+            lineNumbers: lines,
+            commitInfo: commits,
+        });
+    }
+    const display = traced.slice(0, top);
+    if (format === "json") {
+        console.log(JSON.stringify({ totalFindings: findings.length, traced: display.length, findings: display }, null, 2));
+        return;
+    }
+    console.log(`\nFinding Trace:`);
+    console.log("═".repeat(70));
+    console.log(`  ${findings.length} findings, showing top ${display.length}`);
+    if (sourcePath)
+        console.log(`  Source: ${sourcePath}`);
+    console.log("─".repeat(70));
+    for (const t of display) {
+        console.log(`\n  ${t.ruleId || "unknown"} [${t.severity.toUpperCase()}]`);
+        console.log(`    ${t.title}`);
+        if (t.lineNumbers.length > 0)
+            console.log(`    Lines: ${t.lineNumbers.join(", ")}`);
+        if (t.commitInfo.length > 0) {
+            console.log(`    Commits:`);
+            for (const c of t.commitInfo.slice(0, 3))
+                console.log(`      → ${c}`);
+        }
+        else {
+            console.log(`    (no commit trace available)`);
+        }
+    }
+    console.log("\n" + "═".repeat(70));
+}

package/dist/commands/finding-trend-alert.d.ts

@@ -0,0 +1 @@
+export declare function runFindingTrendAlert(argv: string[]): void;

package/dist/commands/finding-trend-alert.js

@@ -0,0 +1,126 @@
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+function detectTrends(currentFindings, baselineFindings) {
+    const alerts = [];
+    const currentCounts = new Map();
+    for (const f of currentFindings) {
+        const existing = currentCounts.get(f.ruleId);
+        if (existing !== undefined) {
+            existing.count += 1;
+        }
+        else {
+            currentCounts.set(f.ruleId, { count: 1, severity: f.severity });
+        }
+    }
+    const baselineCounts = new Map();
+    for (const f of baselineFindings) {
+        baselineCounts.set(f.ruleId, (baselineCounts.get(f.ruleId) ?? 0) + 1);
+    }
+    for (const [ruleId, data] of currentCounts) {
+        const baseline = baselineCounts.get(ruleId) ?? 0;
+        const delta = data.count - baseline;
+        if (delta <= 0)
+            continue;
+        let alertLevel;
+        let message;
+        if (delta >= 5 || (baseline === 0 && data.count >= 3)) {
+            alertLevel = "critical";
+            message =
+                baseline === 0
+                    ? `New rule ${ruleId} appeared with ${data.count} findings`
+                    : `Spike: ${ruleId} increased by ${delta} (${baseline} → ${data.count})`;
+        }
+        else if (delta >= 2) {
+            alertLevel = "warning";
+            message = `${ruleId} increased by ${delta} (${baseline} → ${data.count})`;
+        }
+        else {
+            alertLevel = "info";
+            message = `${ruleId} increased by ${delta}`;
+        }
+        alerts.push({
+            ruleId,
+            severity: data.severity,
+            currentCount: data.count,
+            baselineCount: baseline,
+            delta,
+            alertLevel,
+            message,
+        });
+    }
+    alerts.sort((a, b) => {
+        const order = { critical: 0, warning: 1, info: 2 };
+        return (order[a.alertLevel] ?? 3) - (order[b.alertLevel] ?? 3);
+    });
+    return alerts;
+}
+export function runFindingTrendAlert(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`Usage: judges finding-trend-alert [options]
+
+Alert on emerging finding trends compared to baseline.
+
+Options:
+  --current <path>     Path to current verdict JSON
+  --baseline <path>    Path to baseline verdict JSON
+  --dir <path>         Directory with historical verdicts
+  --format <fmt>       Output format: table (default) or json
+  -h, --help           Show this help message`);
+        return;
+    }
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx !== -1 && argv[formatIdx + 1] ? argv[formatIdx + 1] : "table";
+    const currentIdx = argv.indexOf("--current");
+    const currentPath = currentIdx !== -1 && argv[currentIdx + 1]
+        ? join(process.cwd(), argv[currentIdx + 1])
+        : join(process.cwd(), ".judges", "last-verdict.json");
+    let currentFindings = [];
+    if (existsSync(currentPath)) {
+        const data = JSON.parse(readFileSync(currentPath, "utf-8"));
+        currentFindings = data.findings ?? [];
+    }
+    let baselineFindings = [];
+    const baselineIdx = argv.indexOf("--baseline");
+    if (baselineIdx !== -1 && argv[baselineIdx + 1]) {
+        const bPath = join(process.cwd(), argv[baselineIdx + 1]);
+        if (existsSync(bPath)) {
+            const data = JSON.parse(readFileSync(bPath, "utf-8"));
+            baselineFindings = data.findings ?? [];
+        }
+    }
+    else {
+        const dirIdx = argv.indexOf("--dir");
+        const histDir = dirIdx !== -1 && argv[dirIdx + 1]
+            ? join(process.cwd(), argv[dirIdx + 1])
+            : join(process.cwd(), ".judges", "history");
+        if (existsSync(histDir)) {
+            const files = readdirSync(histDir).filter((f) => f.endsWith(".json")).sort();
+            if (files.length > 0) {
+                const latest = files[files.length - 1];
+                const data = JSON.parse(readFileSync(join(histDir, latest), "utf-8"));
+                baselineFindings = data.findings ?? [];
+            }
+        }
+    }
+    if (currentFindings.length === 0) {
+        console.log("No current findings found. Run a review first or provide --current.");
+        return;
+    }
+    const alerts = detectTrends(currentFindings, baselineFindings);
+    if (format === "json") {
+        console.log(JSON.stringify(alerts, null, 2));
+        return;
+    }
+    console.log("\n=== Finding Trend Alerts ===\n");
+    if (alerts.length === 0) {
+        console.log("No significant trends detected.");
+        return;
+    }
+    const critical = alerts.filter((a) => a.alertLevel === "critical").length;
+    const warning = alerts.filter((a) => a.alertLevel === "warning").length;
+    console.log(`Alerts: ${critical} critical, ${warning} warning, ${alerts.length - critical - warning} info\n`);
+    for (const alert of alerts) {
+        console.log(`[${alert.alertLevel.toUpperCase()}] ${alert.message}`);
+        console.log(`  Severity: ${alert.severity} | Delta: +${alert.delta}`);
+    }
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Finding-trend-analysis — Analyze finding trends across multiple reports.
+ */
+export declare function runFindingTrendAnalysis(argv: string[]): void;

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

@@ -0,0 +1,95 @@
+/**
+ * Finding-trend-analysis — Analyze finding trends across multiple reports.
+ */
+import { readFileSync, existsSync, readdirSync } from "fs";
+// ─── Analysis ───────────────────────────────────────────────────────────────
+function analyzeTrends(verdicts) {
+    const sorted = [...verdicts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    if (sorted.length < 2) {
+        return { points: sorted, direction: "stable", avgScoreChange: 0, avgFindingsChange: 0 };
+    }
+    const scoreChanges = [];
+    const findingsChanges = [];
+    for (let i = 1; i < sorted.length; i++) {
+        scoreChanges.push(sorted[i].score - sorted[i - 1].score);
+        findingsChanges.push(sorted[i].findingCount - sorted[i - 1].findingCount);
+    }
+    const avgScoreChange = scoreChanges.reduce((a, b) => a + b, 0) / scoreChanges.length;
+    const avgFindingsChange = findingsChanges.reduce((a, b) => a + b, 0) / findingsChanges.length;
+    let direction = "stable";
+    if (avgScoreChange > 2)
+        direction = "improving";
+    else if (avgScoreChange < -2)
+        direction = "degrading";
+    return {
+        points: sorted,
+        direction,
+        avgScoreChange: Math.round(avgScoreChange * 10) / 10,
+        avgFindingsChange: Math.round(avgFindingsChange * 10) / 10,
+    };
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingTrendAnalysis(argv) {
+    const dirIdx = argv.indexOf("--dir");
+    const formatIdx = argv.indexOf("--format");
+    const dirPath = dirIdx >= 0 ? argv[dirIdx + 1] : undefined;
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges finding-trend-analysis — Analyze finding trends
+
+Usage:
+  judges finding-trend-analysis --dir <verdicts-dir> [--format table|json]
+
+Options:
+  --dir <path>       Directory of verdict JSON files (required)
+  --format <fmt>     Output format: table (default), json
+  --help, -h         Show this help
+`);
+        return;
+    }
+    if (!dirPath) {
+        console.error("Error: --dir required");
+        process.exitCode = 1;
+        return;
+    }
+    if (!existsSync(dirPath)) {
+        console.error(`Error: not found: ${dirPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const files = readdirSync(dirPath).filter((f) => f.endsWith(".json"));
+    const points = [];
+    for (const file of files) {
+        try {
+            const v = JSON.parse(readFileSync(`${dirPath}/${file}`, "utf-8"));
+            points.push({
+                timestamp: v.timestamp || file.replace(".json", ""),
+                score: v.overallScore,
+                findingCount: v.findings.length,
+                criticalCount: v.criticalCount,
+                highCount: v.highCount,
+            });
+        }
+        catch {
+            // skip
+        }
+    }
+    const analysis = analyzeTrends(points);
+    if (format === "json") {
+        console.log(JSON.stringify(analysis, null, 2));
+        return;
+    }
+    const icon = analysis.direction === "improving" ? "UP" : analysis.direction === "degrading" ? "DOWN" : "FLAT";
+    console.log(`\nFinding Trend Analysis — ${icon}`);
+    console.log("═".repeat(70));
+    console.log(`  Direction: ${analysis.direction}  |  Avg Score Δ: ${analysis.avgScoreChange}  |  Avg Findings Δ: ${analysis.avgFindingsChange}`);
+    console.log("─".repeat(70));
+    console.log(`${"Timestamp".padEnd(24)} ${"Score".padEnd(8)} ${"Findings".padEnd(10)} ${"Critical".padEnd(10)} High`);
+    console.log("─".repeat(70));
+    for (const p of analysis.points) {
+        const ts = p.timestamp.length > 22 ? p.timestamp.slice(0, 22) + "…" : p.timestamp;
+        console.log(`${ts.padEnd(24)} ${String(p.score).padEnd(8)} ${String(p.findingCount).padEnd(10)} ${String(p.criticalCount).padEnd(10)} ${p.highCount}`);
+    }
+    console.log("═".repeat(70));
+}

package/dist/commands/finding-trend-forecast.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Finding-trend-forecast — Forecast finding trends from historical data.
+ */
+export declare function runFindingTrendForecast(argv: string[]): void;

package/dist/commands/finding-trend-forecast.js

@@ -0,0 +1,106 @@
+/**
+ * Finding-trend-forecast — Forecast finding trends from historical data.
+ */
+import { readFileSync, existsSync } from "fs";
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingTrendForecast(argv) {
+    const historyIdx = argv.indexOf("--history");
+    const periodsIdx = argv.indexOf("--periods");
+    const formatIdx = argv.indexOf("--format");
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    const forecastPeriods = periodsIdx >= 0 ? parseInt(argv[periodsIdx + 1], 10) : 1;
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges finding-trend-forecast — Forecast finding trends
+
+Usage:
+  judges finding-trend-forecast --history <path> [--periods <n>]
+                                [--format table|json]
+
+Options:
+  --history <path>  History file with periodic data
+  --periods <n>     Number of periods to forecast (default: 1)
+  --format <fmt>    Output format: table (default), json
+  --help, -h        Show this help
+
+History file format (JSON array):
+  [{"period":"2026-W10","totalFindings":50,"criticalCount":2,"highCount":8,"passRate":85}, ...]
+`);
+        return;
+    }
+    if (historyIdx < 0) {
+        console.error("Missing --history <path>");
+        process.exitCode = 1;
+        return;
+    }
+    const historyPath = argv[historyIdx + 1];
+    if (!existsSync(historyPath)) {
+        console.error(`History file not found: ${historyPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const entries = JSON.parse(readFileSync(historyPath, "utf-8"));
+    if (entries.length < 2) {
+        console.log("Need at least 2 historical data points for forecasting.");
+        return;
+    }
+    // Simple linear regression on totalFindings
+    const forecasts = [];
+    const n = entries.length;
+    for (let p = 0; p < forecastPeriods; p++) {
+        const xValues = entries.map((_, i) => i);
+        const yTotal = entries.map((e) => e.totalFindings);
+        const yCritical = entries.map((e) => e.criticalCount);
+        const yHigh = entries.map((e) => e.highCount);
+        const slopeTotal = linearSlope(xValues, yTotal);
+        const slopeCritical = linearSlope(xValues, yCritical);
+        const slopeHigh = linearSlope(xValues, yHigh);
+        const predictedFindings = Math.max(0, Math.round(yTotal[n - 1] + slopeTotal * (p + 1)));
+        const predictedCritical = Math.max(0, Math.round(yCritical[n - 1] + slopeCritical * (p + 1)));
+        const predictedHigh = Math.max(0, Math.round(yHigh[n - 1] + slopeHigh * (p + 1)));
+        let trend;
+        if (slopeTotal < -1)
+            trend = "improving";
+        else if (slopeTotal > 1)
+            trend = "declining";
+        else
+            trend = "stable";
+        const confidence = Math.max(0.3, Math.min(0.95, 1 - p * 0.15));
+        forecasts.push({
+            nextPeriod: `${entries[n - 1].period}+${p + 1}`,
+            predictedFindings,
+            predictedCritical,
+            predictedHigh,
+            trend,
+            confidence: Math.round(confidence * 100) / 100,
+        });
+    }
+    if (format === "json") {
+        console.log(JSON.stringify(forecasts, null, 2));
+        return;
+    }
+    console.log(`\nFinding Trend Forecast`);
+    console.log("═".repeat(70));
+    // Historical
+    console.log("  Historical:");
+    for (const e of entries) {
+        console.log(`    ${e.period.padEnd(15)} ${String(e.totalFindings).padEnd(8)} findings (${e.criticalCount} critical, ${e.highCount} high)`);
+    }
+    console.log("\n  Forecast:");
+    for (const f of forecasts) {
+        console.log(`    ${f.nextPeriod.padEnd(15)} ${String(f.predictedFindings).padEnd(8)} findings (${f.predictedCritical} critical, ${f.predictedHigh} high)`);
+        console.log(`${"".padEnd(20)} Trend: ${f.trend}, Confidence: ${f.confidence}`);
+    }
+    console.log("═".repeat(70));
+}
+function linearSlope(x, y) {
+    const n = x.length;
+    const sumX = x.reduce((a, b) => a + b, 0);
+    const sumY = y.reduce((a, b) => a + b, 0);
+    const sumXY = x.reduce((a, xi, i) => a + xi * y[i], 0);
+    const sumX2 = x.reduce((a, xi) => a + xi * xi, 0);
+    const denom = n * sumX2 - sumX * sumX;
+    if (denom === 0)
+        return 0;
+    return (n * sumXY - sumX * sumY) / denom;
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Finding-trend-report — Generate trend reports from historical findings.
+ */
+export declare function runFindingTrendReport(argv: string[]): void;

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

@@ -0,0 +1,107 @@
+/**
+ * Finding-trend-report — Generate trend reports from historical findings.
+ */
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function loadVerdictHistory(dir) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    const files = readdirSync(dir);
+    for (const f of files) {
+        if (!String(f).endsWith(".json"))
+            continue;
+        try {
+            const data = JSON.parse(readFileSync(join(dir, String(f)), "utf-8"));
+            if (data && data.findings) {
+                const date = data.timestamp || String(f).replace(".json", "");
+                results.push({ date, verdict: data });
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return results.sort((a, b) => a.date.localeCompare(b.date));
+}
+function buildTrend(history) {
+    return history.map((h) => ({
+        date: h.date,
+        totalFindings: h.verdict.findings.length,
+        criticalCount: h.verdict.criticalCount,
+        highCount: h.verdict.highCount,
+        score: h.verdict.overallScore,
+        ruleCount: new Set(h.verdict.findings.map((f) => f.ruleId)).size,
+    }));
+}
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export function runFindingTrendReport(argv) {
+    const dirIdx = argv.indexOf("--dir");
+    const formatIdx = argv.indexOf("--format");
+    const lastIdx = argv.indexOf("--last");
+    const dir = dirIdx >= 0 ? argv[dirIdx + 1] : join(process.cwd(), ".judges", "verdicts");
+    const format = formatIdx >= 0 ? argv[formatIdx + 1] : "table";
+    const last = lastIdx >= 0 ? parseInt(argv[lastIdx + 1], 10) : 0;
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(`
+judges finding-trend-report — Generate trend reports
+
+Usage:
+  judges finding-trend-report [--dir <path>] [--format table|json|chart]
+                               [--last <n>]
+
+Options:
+  --dir <path>       Directory with historical verdict files
+  --format <fmt>     Output format: table (default), json, chart
+  --last <n>         Show only last N data points
+  --help, -h         Show this help
+`);
+        return;
+    }
+    const history = loadVerdictHistory(dir);
+    if (history.length === 0) {
+        console.log("No verdict history found.");
+        return;
+    }
+    let trend = buildTrend(history);
+    if (last > 0)
+        trend = trend.slice(-last);
+    if (format === "json") {
+        console.log(JSON.stringify(trend, null, 2));
+        return;
+    }
+    if (format === "chart") {
+        console.log("\nFinding Trend (ASCII Chart)");
+        console.log("═".repeat(60));
+        const maxFindings = Math.max(...trend.map((t) => t.totalFindings), 1);
+        for (const t of trend) {
+            const barLen = Math.round((t.totalFindings / maxFindings) * 40);
+            const bar = "█".repeat(barLen);
+            const dateStr = t.date.slice(0, 10).padEnd(12);
+            console.log(`${dateStr} ${bar} ${t.totalFindings}`);
+        }
+        console.log("═".repeat(60));
+        return;
+    }
+    console.log(`\nFinding Trend Report (${trend.length} data points)`);
+    console.log("═".repeat(70));
+    console.log(`${"Date".padEnd(22)} ${"Findings".padEnd(10)} ${"Crit".padEnd(6)} ${"High".padEnd(6)} ${"Score".padEnd(7)} Rules`);
+    console.log("─".repeat(70));
+    for (const t of trend) {
+        const dateStr = t.date.slice(0, 19).padEnd(22);
+        console.log(`${dateStr} ${String(t.totalFindings).padEnd(10)} ${String(t.criticalCount).padEnd(6)} ` +
+            `${String(t.highCount).padEnd(6)} ${String(t.score).padEnd(7)} ${t.ruleCount}`);
+    }
+    if (trend.length >= 2) {
+        const first = trend[0];
+        const latest = trend[trend.length - 1];
+        const findingDelta = latest.totalFindings - first.totalFindings;
+        const scoreDelta = latest.score - first.score;
+        console.log("─".repeat(70));
+        const fd = findingDelta >= 0 ? `+${findingDelta}` : `${findingDelta}`;
+        const sd = scoreDelta >= 0 ? `+${scoreDelta}` : `${scoreDelta}`;
+        console.log(`Trend: findings ${fd}, score ${sd}`);
+    }
+    console.log("═".repeat(70));
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Finding-trend — Show finding trends over time.
+ */
+export declare function runFindingTrend(argv: string[]): void;