@kevinrabun/judges-cli 3.124.0

package/dist/dedup.js

@@ -0,0 +1,606 @@
+/**
+ * Cross-Evaluator Deduplication
+ *
+ * Extracted from the evaluators monolith. Uses union-find to cluster findings
+ * from different evaluators that flag the same line(s) for the same root cause,
+ * keeping the highest-severity instance and annotating cross-references.
+ *
+ * Also provides cross-file deduplication for project-level analysis, merging
+ * identical-topic findings across different files into single consolidated entries.
+ */
+// ─── Severity Ranking (shared with app-builder flow) ─────────────────────────
+export function severityRank(severity) {
+    switch (severity) {
+        case "critical":
+            return 5;
+        case "high":
+            return 4;
+        case "medium":
+            return 3;
+        case "low":
+            return 2;
+        case "info":
+            return 1;
+        default:
+            return 0;
+    }
+}
+// ─── Topic Detection ─────────────────────────────────────────────────────────
+/**
+ * Known semantic topic patterns for cross-evaluator deduplication.
+ * When multiple evaluators flag the same line(s) for the same root cause,
+ * these patterns identify the canonical topic so duplicates can be merged.
+ */
+const DEDUP_TOPIC_PATTERNS = [
+    [/sql\s*inject|inject.*sql|query.*concat.*input|unsanitized.*query/i, "sql-injection"],
+    [/cross.?site\s*script|\bxss\b|unsanitized.*html|\.innerHTML/i, "xss"],
+    [/command\s*inject|shell\s*inject|os\s*command|exec.*inject/i, "cmd-injection"],
+    [/path\s*travers|directory\s*travers/i, "path-traversal"],
+    [/empty\s*catch|catch.*(?:empty|block)|error.*(?:swallow|silent|suppress|ignor)/i, "empty-catch"],
+    [
+        /hardcod.*(?:secret|cred|password|key|token)|(?:secret|cred|password|api.?key|token).*(?:hardcod|plain|literal|embed)/i,
+        "hardcoded-secret",
+    ],
+    [/magic\s*(?:number|value)|unnamed\s*constant/i, "magic-number"],
+    [/\bn\s*\+\s*1\b|loop.*(?:query|request|fetch)|(?:query|request|fetch).*(?:inside|within|in)\s*loop/i, "n-plus-one"],
+    [/rate\s*limit|throttl/i, "rate-limiting"],
+    [/input\s*(?:valid|sanitiz)|(?:valid|sanitiz).*input/i, "input-validation"],
+    [/timeout/i, "timeout"],
+    [/synchronous.*(?:i\/o|io|call)|blocking\s*(?:i\/o|io|call)|Sync\s*\(/i, "sync-io"],
+    [/(?:insecure|weak)\s*(?:hash|crypto|algorithm|cipher)/i, "weak-crypto"],
+    [/prototype\s*pollut/i, "prototype-pollution"],
+    [/open\s*redirect/i, "open-redirect"],
+    [/csrf|cross.?site\s*request\s*forg/i, "csrf"],
+    [/(?:eval|dynamic\s*code\s*exec)/i, "code-injection"],
+    // ── Cross-judge overlap patterns (v3.18.0) ────────────────────────────────
+    [/deeply?\s*nest|nesting.*(?:level|depth|complex)|callback.*(?:hell|pyramid)/i, "deep-nesting"],
+    [/no\s*test|test.*(?:not|without|missing)|test\s*infra/i, "missing-tests"],
+    [/weak.*type|dynamic.*type|type.*(?:safe|usage)|any\s*type|untyped/i, "type-safety"],
+    [/no\s*health|health\s*check|healthcheck/i, "missing-healthcheck"],
+    [/no\s*lint|linting.*config|formatting.*config|eslint|prettier/i, "missing-linting"],
+    [/no\s*build|build\s*script|missing.*build/i, "missing-build-script"],
+    [/(?:doc|documentation).*(?:missing|without|absent|lack)/i, "missing-documentation"],
+    [/error.*(?:log|report|track|monitor).*(?:missing|without|absent)/i, "missing-error-tracking"],
+    // ── Additional cross-judge overlap patterns (v3.19.5) ─────────────────────
+    [/api.*version|version.*api|endpoint.*version/i, "api-versioning"],
+    [/pagination|paginate|without.*paginat|unbounded.*(?:data|fetch|query|result)/i, "pagination"],
+    [
+        /abrupt.*(?:termination|exit|shutdown)|(?:process|hard).*(?:termination|exit)|panic.*exit|process\.exit|graceful.*(?:shutdown|lifecycle)/i,
+        "abrupt-termination",
+    ],
+    // ── Extended coverage (v3.22.0) ───────────────────────────────────────────
+    // Authentication & session
+    [/session\s*(?:fixation|hijack|management)|insecure.*session/i, "session-vulnerability"],
+    [/auth(?:entication)?\s*bypass|bypass.*auth/i, "auth-bypass"],
+    [/\bJWT\b.*(?:verif|valid|exp)|token.*expir|expired?\s*token/i, "jwt-validation"],
+    [/password.*(?:plain|clear|unhash|weak)|plain.*password|bcrypt|argon2|pbkdf/i, "password-handling"],
+    // Concurrency
+    [/race\s*condition|data\s*race|toctou|time.*of.*check/i, "race-condition"],
+    [/deadlock|dead\s*lock|circular.*(?:wait|lock)/i, "deadlock"],
+    [/(?:thread|goroutine|async)\s*(?:safe|safety|unsafe)|shared\s*(?:state|mutable)/i, "thread-safety"],
+    // Database & data
+    [/connection\s*pool|pool.*(?:exhaust|leak|size)|max.*connect/i, "connection-pooling"],
+    [/(?:missing|no)\s*(?:db\s*)?(?:transact|commit|rollback)|transact.*(?:missing|absent)/i, "missing-transaction"],
+    [/(?:missing|no)\s*(?:db\s*)?(?:index|indices)|table\s*scan|full\s*scan/i, "missing-index"],
+    [/(?:unescaped|unsanitized).*(?:output|render|template)|template\s*inject/i, "template-injection"],
+    // Logging & privacy
+    [/(?:log|print|console).*(?:sensitive|pii|credential|password|secret|token)/i, "sensitive-data-logging"],
+    [/\bpii\b|personal.*(?:data|information)|data.*(?:privacy|protection)/i, "pii-exposure"],
+    // Configuration & infrastructure
+    [/(?:cors|cross.?origin).*(?:permissive|wildcard|\*)|allow.*origin.*\*/i, "cors-misconfiguration"],
+    [
+        /tls|ssl|https.*(?:missing|disabled|insecure)|(?:insecure|plain|cleartext)\s*(?:http|connect)/i,
+        "insecure-transport",
+    ],
+    [/debug.*(?:mode|enabled|production)|(?:production|prod).*debug/i, "debug-in-production"],
+    [/env(?:ironment)?\s*var.*(?:missing|unset|undefined|fallback)|missing.*env/i, "missing-env-var"],
+    // Dependency & supply-chain
+    [/(?:outdated|vulnerable)\s*(?:dep|package|lib)|known\s*vulnerabilit/i, "vulnerable-dependency"],
+    [/unpinned.*(?:dep|version)|version.*(?:range|wildcard|\^|~)/i, "unpinned-dependency"],
+    [/(?:unused|dead)\s*(?:dep|import|require|package)/i, "unused-dependency"],
+    // Resource management
+    [
+        /(?:resource|file|handle|stream|socket)\s*leak|(?:unclosed|leaked)\s*(?:resource|file|handle|connection)/i,
+        "resource-leak",
+    ],
+    [/memory\s*leak|(?:unbounded|growing)\s*(?:cache|queue|buffer|array)/i, "memory-leak"],
+    // Error handling
+    [/(?:unchecked|unhandled)\s*(?:error|exception|rejection|promise)/i, "unhandled-error"],
+    [/(?:generic|bare)\s*(?:catch|except)|catch.*(?:Exception|Error)\s*[^a-z]/i, "generic-catch"],
+    // ── Cross-judge dedup gaps (v3.35.0) ──────────────────────────────────────
+    // Timing & side-channel
+    [
+        /(?:non.?constant.?time|timing.?(?:attack|unsafe|side)).*(?:compar|secret|token|crypt)|constant.?time.*compar/i,
+        "timing-attack",
+    ],
+    // Network & SSRF
+    [/ssrf|server.?side\s*request\s*forg|url.*(?:user|unvalidat|whitelist)/i, "ssrf"],
+    // Mass assignment / over-posting
+    [/mass\s*assign|over.?post|bulk\s*assign|whitelist.*(?:field|param|attr)/i, "mass-assignment"],
+    // Deserialization
+    [
+        /(?:insecure|unsafe)\s*deserialization|deserialization.*(?:attack|untrusted|remote)|pickle|ObjectInputStream/i,
+        "insecure-deserialization",
+    ],
+    // Information disclosure
+    [
+        /(?:verbose|stack.?trace|detailed)\s*error.*(?:user|client|response)|information\s*(?:disclosure|leak)/i,
+        "info-disclosure",
+    ],
+    // Denial of service
+    [
+        /(?:denial|dos)\s*(?:of\s*)?service|\bReDoS\b|catastrophic\s*backtrack|unbounded.*(?:loop|alloc)/i,
+        "denial-of-service",
+    ],
+    // File upload
+    [
+        /file\s*upload.*(?:unvalidat|unchecked|size|type)|upload.*(?:without|no).*(?:valid|restrict|limit)/i,
+        "file-upload-security",
+    ],
+    // Missing access control
+    [/(?:missing|no)\s*(?:access\s*control|authorization|authz)|broken\s*access\s*control/i, "missing-access-control"],
+    // Hardcoded port / IP / URL
+    [/hardcod.*(?:port|ip|host|url)|(?:port|ip|host).*hardcod/i, "hardcoded-config"],
+    // Frontend-specific overlaps
+    [/dangerouslySetInnerHTML|v-html|bypassSecurityTrust/i, "unsafe-html-render"],
+    [/(?:missing|no)\s*(?:alt|aria|label).*(?:accessib|a11y)|accessibility.*(?:missing|violat)/i, "a11y-violation"],
+];
+const TOPIC_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "is",
+    "are",
+    "was",
+    "be",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "of",
+    "with",
+    "by",
+    "from",
+    "as",
+    "no",
+    "not",
+    "but",
+    "or",
+    "and",
+    "if",
+    "it",
+    "its",
+    "has",
+    "have",
+    "had",
+    "do",
+    "does",
+    "may",
+    "can",
+    "could",
+    "should",
+    "will",
+    "use",
+    "used",
+    "using",
+    "without",
+    "missing",
+    "detected",
+    "found",
+    "via",
+    "into",
+    "that",
+]);
+/**
+ * Extract a semantic topic string from a finding's title.
+ * First checks known topic patterns, then falls back to normalized title words.
+ */
+function extractFindingTopic(finding) {
+    const title = finding.title;
+    for (const [pattern, topic] of DEDUP_TOPIC_PATTERNS) {
+        if (pattern.test(title))
+            return topic;
+    }
+    // Fallback: normalize title to sorted core words
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !TOPIC_STOP_WORDS.has(w))
+        .sort()
+        .join("-");
+}
+// ─── Semantic Similarity for Cross-Judge Dedup ──────────────────────────────
+/**
+ * Minimum Jaccard-like similarity for two findings to be considered duplicates.
+ * Set high to avoid false merges — 0.6 catches paraphrases like
+ * "comparison of secrets" vs "comparison of cryptographic material" while
+ * keeping genuinely different findings apart.
+ */
+const SEMANTIC_DEDUP_THRESHOLD = 0.6;
+/** Tokenize text into meaningful lower-case word stems */
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !TOPIC_STOP_WORDS.has(w)));
+}
+/**
+ * Compute a similarity score (0-1) between two findings based on token overlap
+ * of their titles and recommendations. Uses Jaccard index on the combined
+ * token sets.
+ */
+function findingSimilarity(a, b) {
+    const tokensA = tokenize(`${a.title} ${a.recommendation ?? ""}`);
+    const tokensB = tokenize(`${b.title} ${b.recommendation ?? ""}`);
+    if (tokensA.size === 0 || tokensB.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of tokensA) {
+        if (tokensB.has(t))
+            intersection++;
+    }
+    const unionSize = tokensA.size + tokensB.size - intersection;
+    return unionSize > 0 ? intersection / unionSize : 0;
+}
+// ─── Union-Find Deduplication ────────────────────────────────────────────────
+/**
+ * Deduplicate findings across evaluators. When different judges flag the same
+ * line(s) for the same root cause, keeps the highest-severity instance and
+ * annotates it with cross-references to the other rule IDs.
+ *
+ * Uses union-find to cluster findings that share any (topic, lineNumber) pair,
+ * then picks the best finding from each cluster.
+ */
+export function crossEvaluatorDedup(findings) {
+    if (findings.length <= 1)
+        return findings;
+    // Map each finding to (topic, line) keys
+    const groups = new Map();
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        const topic = extractFindingTopic(f);
+        if (f.lineNumbers && f.lineNumbers.length > 0) {
+            const seen = new Set();
+            for (const line of f.lineNumbers) {
+                const key = `${topic}:L${line}`;
+                if (!seen.has(key)) {
+                    const group = groups.get(key) ?? [];
+                    group.push(i);
+                    groups.set(key, group);
+                    seen.add(key);
+                }
+            }
+        }
+        else {
+            const key = `${topic}:noLine`;
+            const group = groups.get(key) ?? [];
+            group.push(i);
+            groups.set(key, group);
+        }
+    }
+    // Union-Find to merge findings sharing any (topic, line) key
+    const parent = Array.from({ length: findings.length }, (_, i) => i);
+    function find(x) {
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]];
+            x = parent[x];
+        }
+        return x;
+    }
+    function union(a, b) {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[ra] = rb;
+    }
+    for (const indices of groups.values()) {
+        for (let j = 1; j < indices.length; j++) {
+            union(indices[0], indices[j]);
+        }
+    }
+    // Bridge same-known-topic findings regardless of line numbers.
+    // When different evaluators flag the same conceptual issue (e.g., "rate-limiting")
+    // but detect different lines (AST vs regex, or one is noLine), union them
+    // so only the best finding per root cause survives.
+    const knownTopics = new Set(DEDUP_TOPIC_PATTERNS.map(([, t]) => t));
+    const topicBridgeGroups = new Map();
+    for (let i = 0; i < findings.length; i++) {
+        const topic = extractFindingTopic(findings[i]);
+        if (knownTopics.has(topic)) {
+            const group = topicBridgeGroups.get(topic) ?? [];
+            group.push(i);
+            topicBridgeGroups.set(topic, group);
+        }
+    }
+    for (const indices of topicBridgeGroups.values()) {
+        for (let j = 1; j < indices.length; j++) {
+            union(indices[0], indices[j]);
+        }
+    }
+    // ── Semantic similarity bridge (v3.36.0) ────────────────────────────────
+    // After pattern-based topic matching, use token-set Jaccard similarity on
+    // (title + recommendation) to catch findings that describe the same issue
+    // with different wording — e.g. "Non-constant-time comparison of secrets"
+    // vs "Non-constant-time comparison of cryptographic material".
+    // Only merge findings whose similarity ≥ SEMANTIC_DEDUP_THRESHOLD and
+    // that share at least one overlapping line number (or both have no line).
+    for (let i = 0; i < findings.length; i++) {
+        for (let j = i + 1; j < findings.length; j++) {
+            if (find(i) === find(j))
+                continue; // already merged
+            const sim = findingSimilarity(findings[i], findings[j]);
+            if (sim < SEMANTIC_DEDUP_THRESHOLD)
+                continue;
+            // Require overlapping lines (or both line-less)
+            const linesI = findings[i].lineNumbers ?? [];
+            const linesJ = findings[j].lineNumbers ?? [];
+            if (linesI.length === 0 && linesJ.length === 0) {
+                union(i, j);
+            }
+            else if (linesI.length > 0 && linesJ.length > 0) {
+                const setI = new Set(linesI);
+                if (linesJ.some((l) => setI.has(l)))
+                    union(i, j);
+            }
+        }
+    }
+    // Collect connected components
+    const components = new Map();
+    for (let i = 0; i < findings.length; i++) {
+        const root = find(i);
+        const comp = components.get(root) ?? [];
+        comp.push(i);
+        components.set(root, comp);
+    }
+    // Pick the best finding from each component, annotating with cross-refs.
+    const result = [];
+    for (const indices of components.values()) {
+        if (indices.length === 1) {
+            result.push(findings[indices[0]]);
+            continue;
+        }
+        // Sort: severity desc → suggestedFix → confidence → description length
+        const sorted = indices
+            .map((i) => findings[i])
+            .sort((a, b) => {
+            const sevDiff = severityRank(b.severity) - severityRank(a.severity);
+            if (sevDiff !== 0)
+                return sevDiff;
+            const fixDiff = (b.suggestedFix ? 1 : 0) - (a.suggestedFix ? 1 : 0);
+            if (fixDiff !== 0)
+                return fixDiff;
+            const confDiff = (b.confidence ?? 0) - (a.confidence ?? 0);
+            if (confDiff !== 0)
+                return confDiff;
+            return b.description.length - a.description.length;
+        });
+        const best = { ...sorted[0] };
+        // Merge line numbers from all findings in the cluster
+        const allLines = new Set();
+        for (const f of sorted) {
+            if (f.lineNumbers)
+                f.lineNumbers.forEach((ln) => allLines.add(ln));
+        }
+        if (allLines.size > 0)
+            best.lineNumbers = [...allLines].sort((a, b) => a - b);
+        // Annotate with cross-references
+        const otherIds = sorted.slice(1).map((f) => f.ruleId);
+        if (otherIds.length > 0) {
+            best.description += `\n\n_Also identified by: ${otherIds.join(", ")}_`;
+        }
+        result.push(best);
+    }
+    return result;
+}
+// ─── Cross-File Deduplication (Project Level) ────────────────────────────────
+/**
+ * Deduplicate non-absence findings across files in project-level analysis.
+ *
+ * When the same concrete issue (e.g., sql-injection, xss, hardcoded-secret) is
+ * identified with the SAME rule ID in multiple files, the finding is likely a
+ * repeated pattern rather than independent vulnerabilities. This function
+ * consolidates those into a single representative finding annotated with the
+ * list of affected files and combined line counts.
+ *
+ * Only groups findings that share BOTH a known topic AND the same ruleId.
+ * Findings with fallback topics (no known-pattern match) are left as-is since
+ * fallback topic collisions are unreliable.
+ *
+ * @param fileFindings Array of per-file findings with their source file paths
+ * @returns Deduplicated findings with file-count annotations
+ */
+export function crossFileDedup(fileFindings) {
+    if (fileFindings.length <= 1) {
+        return fileFindings.flatMap((f) => f.findings);
+    }
+    const knownTopics = new Set(DEDUP_TOPIC_PATTERNS.map(([, t]) => t));
+    // Index: (topic + ruleId) → list of { path, finding }
+    const topicRuleGroups = new Map();
+    const ungrouped = [];
+    for (const ff of fileFindings) {
+        for (const finding of ff.findings) {
+            const topic = extractFindingTopic(finding);
+            // Only group on known topics with a ruleId — fallback topics are too noisy
+            if (knownTopics.has(topic) && finding.ruleId) {
+                const key = `${topic}::${finding.ruleId}`;
+                const group = topicRuleGroups.get(key) ?? [];
+                group.push({ path: ff.path, finding });
+                topicRuleGroups.set(key, group);
+            }
+            else {
+                ungrouped.push(finding);
+            }
+        }
+    }
+    const result = [...ungrouped];
+    for (const entries of topicRuleGroups.values()) {
+        if (entries.length === 1) {
+            // Single occurrence — keep as-is
+            result.push(entries[0].finding);
+            continue;
+        }
+        // Multiple files have the same topic + ruleId — consolidate
+        // Sort by severity desc → confidence desc → description length desc
+        const sorted = entries.sort((a, b) => {
+            const sevDiff = severityRank(b.finding.severity) - severityRank(a.finding.severity);
+            if (sevDiff !== 0)
+                return sevDiff;
+            const confDiff = (b.finding.confidence ?? 0) - (a.finding.confidence ?? 0);
+            if (confDiff !== 0)
+                return confDiff;
+            return b.finding.description.length - a.finding.description.length;
+        });
+        const best = { ...sorted[0].finding };
+        // Collect all affected file paths (deduplicated, sorted)
+        const affectedFiles = [...new Set(sorted.map((e) => e.path))].sort();
+        // Merge all line numbers (per-file line numbers aren't meaningful
+        // in a cross-file context, but keep them for reference)
+        const allLines = new Set();
+        for (const entry of sorted) {
+            for (const l of entry.finding.lineNumbers ?? [])
+                allLines.add(l);
+        }
+        if (allLines.size > 0) {
+            best.lineNumbers = [...allLines].sort((a, b) => a - b);
+        }
+        // Annotate description with cross-file information
+        best.description += `\n\n_Pattern repeated in ${affectedFiles.length} file(s): ${affectedFiles.join(", ")}_`;
+        // Boost confidence slightly for findings confirmed across multiple files
+        if (best.confidence !== undefined) {
+            best.confidence = Math.min(1.0, best.confidence + 0.05 * Math.min(affectedFiles.length - 1, 3));
+        }
+        result.push(best);
+    }
+    return result;
+}
+/**
+ * Generate a stable key for a finding to match across runs.
+ * Uses ruleId + file path + first line number for identity.
+ */
+function findingDiffKey(f, filePath) {
+    const path = filePath || "";
+    const line = f.lineNumbers?.[0] ?? 0;
+    return `${f.ruleId}::${path}::${line}`;
+}
+/**
+ * Compare two sets of findings to identify new, fixed, and recurring issues.
+ * Useful for tracking regression between evaluation runs.
+ *
+ * @param previous  - Findings from the previous run
+ * @param current   - Findings from the current run
+ * @param filePath  - Optional file path context (used when findings lack filePath)
+ * @returns Diff with new, fixed, and recurring findings plus stats
+ */
+export function diffFindings(previous, current, filePath) {
+    const prevKeys = new Map();
+    for (const f of previous) {
+        prevKeys.set(findingDiffKey(f, filePath), f);
+    }
+    const currKeys = new Map();
+    for (const f of current) {
+        currKeys.set(findingDiffKey(f, filePath), f);
+    }
+    const newFindings = [];
+    const recurringFindings = [];
+    const fixedFindings = [];
+    for (const [key, f] of currKeys) {
+        if (prevKeys.has(key)) {
+            recurringFindings.push(f);
+        }
+        else {
+            newFindings.push(f);
+        }
+    }
+    for (const [key, f] of prevKeys) {
+        if (!currKeys.has(key)) {
+            fixedFindings.push(f);
+        }
+    }
+    return {
+        newFindings,
+        fixedFindings,
+        recurringFindings,
+        stats: {
+            totalPrevious: previous.length,
+            totalCurrent: current.length,
+            newCount: newFindings.length,
+            fixedCount: fixedFindings.length,
+            recurringCount: recurringFindings.length,
+            delta: current.length - previous.length,
+        },
+    };
+}
+/**
+ * Format a finding diff as human-readable text.
+ */
+export function formatFindingDiff(diff) {
+    const lines = [];
+    lines.push("╔══════════════════════════════════════════════════════════════╗");
+    lines.push("║              Judges Panel — Finding Diff                    ║");
+    lines.push("╚══════════════════════════════════════════════════════════════╝");
+    lines.push("");
+    lines.push(`  Previous run  : ${diff.stats.totalPrevious} finding(s)`);
+    lines.push(`  Current run   : ${diff.stats.totalCurrent} finding(s)`);
+    lines.push(`  Delta         : ${diff.stats.delta >= 0 ? "+" : ""}${diff.stats.delta}`);
+    lines.push("");
+    if (diff.newFindings.length > 0) {
+        lines.push(`  🆕 New Findings (${diff.stats.newCount}):`);
+        lines.push("  " + "─".repeat(55));
+        for (const f of diff.newFindings) {
+            lines.push(`    ${f.ruleId.padEnd(12)} [${f.severity}] ${f.title} (line ${f.lineNumbers?.[0] ?? "?"})`);
+        }
+        lines.push("");
+    }
+    if (diff.fixedFindings.length > 0) {
+        lines.push(`  ✅ Fixed Findings (${diff.stats.fixedCount}):`);
+        lines.push("  " + "─".repeat(55));
+        for (const f of diff.fixedFindings) {
+            lines.push(`    ${f.ruleId.padEnd(12)} [${f.severity}] ${f.title} (line ${f.lineNumbers?.[0] ?? "?"})`);
+        }
+        lines.push("");
+    }
+    if (diff.recurringFindings.length > 0) {
+        lines.push(`  🔄 Recurring Findings (${diff.stats.recurringCount}):`);
+        lines.push("  " + "─".repeat(55));
+        for (const f of diff.recurringFindings) {
+            lines.push(`    ${f.ruleId.padEnd(12)} [${f.severity}] ${f.title} (line ${f.lineNumbers?.[0] ?? "?"})`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Evaluate whether a PR's net change is positive — i.e., it fixed more
+ * findings than it introduced. Designed for CI pipelines where teams want to
+ * enforce a "leave the codebase better than you found it" policy.
+ *
+ * @param diff - The FindingDiff from comparing baseline vs current findings
+ * @param options - Gate configuration
+ */
+export function evaluateNetChangeGate(diff, options) {
+    const minNetFixed = options?.minNetFixed ?? 0;
+    const blockOnNewHigh = options?.blockOnNewHighSeverity ?? true;
+    const netFixed = diff.stats.fixedCount - diff.stats.newCount;
+    // Check for new critical/high findings
+    const blockers = blockOnNewHigh
+        ? diff.newFindings.filter((f) => f.severity === "critical" || f.severity === "high")
+        : [];
+    const passed = blockers.length === 0 && netFixed >= minNetFixed;
+    const parts = [];
+    parts.push(`Net change: ${netFixed >= 0 ? "+" : ""}${netFixed} (${diff.stats.fixedCount} fixed, ${diff.stats.newCount} introduced)`);
+    if (blockers.length > 0) {
+        parts.push(`Blocked by ${blockers.length} new critical/high finding(s): ${blockers.map((b) => b.ruleId).join(", ")}`);
+    }
+    parts.push(`Gate: ${passed ? "PASSED" : "FAILED"}`);
+    return {
+        passed,
+        netFixed,
+        introduced: diff.stats.newCount,
+        resolved: diff.stats.fixedCount,
+        blockers,
+        summary: parts.join(". "),
+    };
+}

package/dist/disk-cache.d.ts

@@ -0,0 +1,59 @@
+export declare class DiskCache<T = unknown> {
+    private dir;
+    private maxEntries;
+    private maxAgeMs;
+    private index;
+    constructor(options?: {
+        cacheDir?: string;
+        maxEntries?: number;
+        maxAgeMs?: number;
+    });
+    /**
+     * Compute a cache key from code + language.
+     *
+     * @returns A content-addressable hash key.
+     */
+    static key(code: string, language: string): string;
+    /**
+     * Retrieve a cached result, or `undefined` if miss / stale.
+     *
+     * @returns The cached value, or `undefined` on miss or staleness.
+     */
+    get(key: string): T | undefined;
+    /** Store a result on disk. */
+    set(key: string, value: T, filePath?: string): void;
+    /**
+     * Check if a key exists (not stale).
+     *
+     * @returns `true` if the key is cached and not expired.
+     */
+    has(key: string): boolean;
+    /** Remove all cache entries. */
+    clear(): void;
+    /**
+     * Number of entries currently cached.
+     *
+     * @returns The current entry count.
+     */
+    get size(): number;
+    private entryPath;
+    private indexPath;
+    private ensureDir;
+    private loadIndex;
+    private saveIndex;
+    private evictEntry;
+    private enforceLimit;
+}
+/**
+ * Get or create the shared disk cache instance.
+ *
+ * @returns The shared `DiskCache` instance, or `null` if disk caching is disabled
+ *          via `JUDGES_NO_DISK_CACHE=1`.
+ */
+export declare function getSharedDiskCache(): DiskCache | null;
+/**
+ * Clear the shared disk cache (useful in tests).
+ *
+ * @returns Nothing — clears state and resets the singleton.
+ */
+export declare function clearSharedDiskCache(): void;