@kevinrabun/judges-cli 3.124.0

package/dist/evaluators/index.js

@@ -0,0 +1,994 @@
+// ─── Evaluators Module ───────────────────────────────────────────────────────
+// Re-exports the evaluation engine: analyser routing, scoring, formatting.
+// ──────────────────────────────────────────────────────────────────────────────
+import { JUDGES } from "../judges/index.js";
+import { analyzeStructure } from "../ast/index.js";
+import { analyzeTaintFlows } from "../ast/index.js";
+import { LRUCache, contentHash } from "../cache.js";
+import { getSharedDiskCache } from "../disk-cache.js";
+// ─── Shared Utilities ────────────────────────────────────────────────────────
+import { calculateScore, deriveVerdict, buildSummary, buildTribunalSummary, formatVerdictAsMarkdown, formatEvaluationAsMarkdown, classifyFile, shouldRunAbsenceRules, applyConfig, applyFrameworkAwareness, } from "./shared.js";
+// ─── Extracted Modules ───────────────────────────────────────────────────────
+import { evaluateMustFixGate, clampConfidence, applyConfidenceThreshold, isAbsenceBasedFinding, mapToOwaspLlmTop10, } from "../scoring.js";
+import { enrichWithPatches } from "../patches/index.js";
+import { crossEvaluatorDedup, severityRank } from "../dedup.js";
+import { filterFalsePositiveHeuristics } from "./false-positive-review.js";
+import { calibrateFindings, loadCalibrationProfile, buildModelCalibrationProfile } from "../calibration.js";
+import { applyAutoTune } from "../auto-tune.js";
+import { loadFeedbackStore } from "../commands/feedback.js";
+import { CROSS_FILE_SECURITY_CATEGORIES } from "./project.js";
+import { applyTriageFeedback, loadFindingStore } from "../finding-lifecycle.js";
+import { enrichWithSecurityIds } from "../security-ids.js";
+import { selectJudges } from "./judge-selector.js";
+import { getGlobalSession } from "../evaluation-session.js";
+import { evaluateEscalations, enhanceReviewWithEscalations } from "../escalation.js";
+import { applyRecallBoost } from "./recall-boost.js";
+import { buildTribunalDeepReviewSection } from "../tools/deep-review.js";
+import { detectProjectContext } from "./shared.js";
+// ── AST-aware post-processing ───────────────────────────────────────────────
+// ── Module-level caches for AST/taint results ───────────────────────────────
+const astStructureCache = new LRUCache(256);
+const taintFlowCache = new LRUCache(256);
+/** Clear all internal evaluation caches. Useful in tests or after large runs. */
+export function clearEvaluationCaches() {
+    astStructureCache.clear();
+    taintFlowCache.clear();
+}
+/**
+ * Pre-warm the AST structure and taint flow caches for a batch of files.
+ * Call this before running evaluateWithTribunal on each file to front-load
+ * the expensive parsing step and avoid redundant computation when the
+ * tribunal processes each file individually.
+ */
+export function preWarmCaches(files, optionsSuffix) {
+    for (const f of files) {
+        const hash = contentHash(f.content, f.language + (optionsSuffix ?? ""));
+        if (!astStructureCache.get(hash)) {
+            astStructureCache.set(hash, analyzeStructure(f.content, f.language));
+        }
+        if (!taintFlowCache.get(hash)) {
+            taintFlowCache.set(hash, analyzeTaintFlows(f.content, f.language));
+        }
+    }
+}
+/**
+ * Known sanitization/security library names. When one is imported, related
+ * findings can have confidence reduced because the developer has taken steps
+ * to mitigate the issue.
+ */
+const SECURITY_IMPORTS = {
+    xss: ["dompurify", "sanitize-html", "xss", "isomorphic-dompurify", "xss-filters"],
+    headers: ["helmet", "secure-headers", "django-security"],
+    rateLimit: ["express-rate-limit", "rate-limiter-flexible", "bottleneck", "limiter", "rate-limit"],
+    validation: ["joi", "zod", "yup", "ajv", "class-validator", "express-validator"],
+    csrf: ["csurf", "csrf", "csrf-csrf"],
+    crypto: ["bcrypt", "argon2", "scrypt"],
+    jwt: ["jsonwebtoken", "jose", "passport-jwt"],
+};
+/**
+ * Returns the containing function for a given line number, if any.
+ */
+function getContainingFunction(line, structure) {
+    return structure.functions.find((f) => line >= f.startLine && line <= f.endLine);
+}
+const TEST_FUNCTION_PATTERN = /^(?:test|it|describe|beforeEach|afterEach|beforeAll|afterAll|setUp|tearDown|test_|spec_)/i;
+// ─── Taint Flow → Finding Matching ───────────────────────────────────────────
+/** Map taint-sink kinds to finding title/ruleId patterns they confirm */
+const TAINT_SINK_TO_FINDING = {
+    "code-execution": /eval|code.?inject|code.?exec|dynamic.?code/i,
+    "command-exec": /command.?inject|os.?command|shell.?inject|exec/i,
+    "sql-query": /sql.?inject|query.?inject|unsanitized.?query/i,
+    xss: /xss|cross.?site\s*script|innerhtml|html.?inject/i,
+    "path-traversal": /path.?travers|directory.?travers|file.?inclu/i,
+    redirect: /open.?redirect|unvalidated.?redirect/i,
+    deserialization: /deseri|unsafe.?parse|untrusted.?data.?parse/i,
+    template: /template.?inject|ssti/i,
+};
+/**
+ * Apply AST-aware refinements to findings:
+ * - Remove findings on dead code lines
+ * - Lower confidence for findings inside test-like functions
+ * - Adjust confidence based on imported security libraries
+ * - Boost/annotate findings confirmed by taint flow analysis
+ */
+function applyAstRefinements(findings, structure, taintFlows) {
+    const deadSet = new Set(structure.deadCodeLines);
+    const importNames = new Set(structure.imports
+        .map((i) => {
+        // Extract package name from path: "@scope/pkg" → "@scope/pkg", "helmet" → "helmet"
+        const parts = i.split("/");
+        return i.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+    })
+        .map((n) => n.toLowerCase()));
+    // Determine which security categories have mitigations imported
+    const mitigatedCategories = new Set();
+    for (const [category, libs] of Object.entries(SECURITY_IMPORTS)) {
+        if (libs.some((lib) => importNames.has(lib))) {
+            mitigatedCategories.add(category);
+        }
+    }
+    // Build a map of sink lines → taint flows for fast lookup
+    const flowsBySinkLine = new Map();
+    if (taintFlows) {
+        for (const flow of taintFlows) {
+            const existing = flowsBySinkLine.get(flow.sink.line) ?? [];
+            existing.push(flow);
+            flowsBySinkLine.set(flow.sink.line, existing);
+        }
+    }
+    return findings
+        .filter((f) => {
+        // Remove findings where ALL referenced lines are dead code — except for
+        // findings that ARE about dead code detection (e.g., LOGIC dead-code
+        // reports). Those findings intentionally reference unreachable lines.
+        if (f.lineNumbers && f.lineNumbers.length > 0 && f.lineNumbers.every((l) => deadSet.has(l))) {
+            if (/dead\s*code|unreachable/i.test(f.title))
+                return true;
+            return false;
+        }
+        return true;
+    })
+        .map((f) => {
+        let confidenceAdj = 0;
+        let descriptionSuffix = "";
+        // Lower confidence for findings inside test-like functions
+        if (f.lineNumbers && f.lineNumbers.length > 0) {
+            const primaryLine = f.lineNumbers[0];
+            const fn = getContainingFunction(primaryLine, structure);
+            if (fn && TEST_FUNCTION_PATTERN.test(fn.name)) {
+                confidenceAdj -= 0.15;
+            }
+        }
+        // Adjust confidence based on security library imports
+        const title = f.title.toLowerCase();
+        if (mitigatedCategories.has("xss") && /xss|innerhtml|cross.?site\s*script/i.test(title)) {
+            confidenceAdj -= 0.2;
+        }
+        if (mitigatedCategories.has("headers") && /security\s*header|helmet/i.test(title)) {
+            confidenceAdj -= 0.25;
+        }
+        if (mitigatedCategories.has("rateLimit") && /rate\s*limit|throttl/i.test(title)) {
+            confidenceAdj -= 0.2;
+        }
+        if (mitigatedCategories.has("validation") && /input\s*valid|sanitiz|unsanitized/i.test(title)) {
+            confidenceAdj -= 0.15;
+        }
+        if (mitigatedCategories.has("csrf") && /csrf|cross.?site\s*request/i.test(title)) {
+            confidenceAdj -= 0.25;
+        }
+        // ── Taint flow confirmation ────────────────────────────────────────
+        if (taintFlows && taintFlows.length > 0 && f.lineNumbers && f.lineNumbers.length > 0) {
+            const matchingFlows = findMatchingTaintFlows(f, flowsBySinkLine);
+            if (matchingFlows.length > 0) {
+                // Confirmed: user input reaches this sink → boost confidence
+                confidenceAdj += 0.2;
+                const flow = matchingFlows[0];
+                const via = flow.intermediates.length > 0 ? ` via ${flow.intermediates.map((i) => i.variable).join(" → ")}` : "";
+                descriptionSuffix = `\n\n**Confirmed data flow**: \`${flow.source.expression}\` (line ${flow.source.line})${via} → sink at line ${flow.sink.line}`;
+            }
+        }
+        if (confidenceAdj !== 0 || descriptionSuffix) {
+            const currentConf = f.confidence ?? 0.5;
+            return {
+                ...f,
+                confidence: clampConfidence(currentConf + confidenceAdj),
+                ...(descriptionSuffix ? { description: (f.description ?? "") + descriptionSuffix } : {}),
+            };
+        }
+        return f;
+    });
+}
+/**
+ * Find taint flows that confirm a given finding.
+ * Matches by checking if any of the finding's referenced lines correspond to
+ * a taint sink and the sink kind matches the finding's topic.
+ */
+function findMatchingTaintFlows(finding, flowsBySinkLine) {
+    if (!finding.lineNumbers || finding.lineNumbers.length === 0)
+        return [];
+    const title = (finding.title + " " + (finding.ruleId ?? "")).toLowerCase();
+    const matched = [];
+    for (const line of finding.lineNumbers) {
+        const flows = flowsBySinkLine.get(line);
+        if (!flows)
+            continue;
+        for (const flow of flows) {
+            const pattern = TAINT_SINK_TO_FINDING[flow.sink.kind];
+            if (pattern && pattern.test(title)) {
+                matched.push(flow);
+            }
+        }
+    }
+    return matched;
+}
+// ── Inline suppression support (delegated to ./suppressions.ts) ─────────────
+export { applyInlineSuppressions, applyInlineSuppressionsWithAudit } from "./suppressions.js";
+import { applyInlineSuppressionsWithAudit } from "./suppressions.js";
+function resolveJudgeSet(options) {
+    const includeAstFindings = options?.includeAstFindings ?? true;
+    let judges = includeAstFindings ? JUDGES : JUDGES.filter((judge) => judge.id !== "code-structure");
+    // Append plugin judges if provided
+    if (options?.pluginJudges && options.pluginJudges.length > 0) {
+        const builtInIds = new Set(judges.map((j) => j.id));
+        const uniquePlugins = options.pluginJudges.filter((j) => !builtInIds.has(j.id));
+        judges = [...judges, ...uniquePlugins];
+    }
+    // Apply config-based judge filtering
+    if (options?.config?.disabledJudges && options.config.disabledJudges.length > 0) {
+        const disabled = new Set(options.config.disabledJudges);
+        judges = judges.filter((j) => !disabled.has(j.id));
+    }
+    // Adaptive judge selection — skip irrelevant judges based on file context
+    if (options?.adaptiveSelection && options.filePath) {
+        const fileCategory = classifyFile("", options.filePath.split(".").pop() ?? "", options.filePath);
+        const ctx = {
+            language: options.filePath.split(".").pop() ?? "unknown",
+            fileCategory,
+            filePath: options.filePath,
+            projectMode: options.projectMode,
+        };
+        const result = selectJudges(judges, ctx);
+        return { judges: result.selected, skipped: result.skipped };
+    }
+    return { judges };
+}
+/**
+ * Check whether an absence-based finding is mitigated by a pre-scanned
+ * project capability. Returns true if the finding matches a security category
+ * that was detected elsewhere in the project.
+ */
+function isAbsenceMitigatedByCapability(finding, capabilities) {
+    const text = `${finding.title} ${finding.ruleId ?? ""}`;
+    for (const cat of CROSS_FILE_SECURITY_CATEGORIES) {
+        if (capabilities.has(cat.category) && cat.findingPattern.test(text)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Run a single judge against the provided code.
+ */
+export function evaluateWithJudge(judge, code, language, context, options) {
+    const findings = [];
+    // ── Registry-based dispatch: each judge carries its own analyze() method ──
+    if (judge.analyze) {
+        // Pass pre-computed AST context so evaluators can make scope-aware decisions
+        const analyzeCtx = options?._astCache || options?._taintFlows
+            ? { ast: options._astCache, taintFlows: options._taintFlows }
+            : undefined;
+        findings.push(...judge.analyze(code, language, analyzeCtx));
+    }
+    // NOTE: Recall boost (applyRecallBoost) is applied once in evaluateWithTribunal()
+    // rather than per-judge, to avoid generating N duplicate boost findings.
+    // ── Absence gating ──
+    // Absence-based findings ("no rate limiting", "no monitoring", etc.) are
+    // project-level concerns that cannot be accurately assessed from a single
+    // file — the missing capability may exist in another module, middleware,
+    // or infrastructure layer. Suppress them entirely in single-file mode
+    // unless projectCapabilities is provided (pre-scanned workspace context).
+    const fileCategory = classifyFile(code, language, options?.filePath);
+    const isProjectMode = options?.projectMode === true;
+    const hasCapabilities = options?.projectCapabilities && options.projectCapabilities.size > 0;
+    const allowAbsence = shouldRunAbsenceRules(fileCategory) && (isProjectMode || hasCapabilities);
+    let gatedFindings;
+    if (allowAbsence && hasCapabilities && !isProjectMode) {
+        // Single-file mode with pre-scanned capabilities: suppress absence findings
+        // where the capability is verified elsewhere in the project.
+        gatedFindings = findings.filter((f) => {
+            if (!isAbsenceBasedFinding(f))
+                return true;
+            return !isAbsenceMitigatedByCapability(f, options.projectCapabilities);
+        });
+    }
+    else {
+        gatedFindings = allowAbsence ? findings : findings.filter((f) => !isAbsenceBasedFinding(f));
+    }
+    // ── Tag & demote remaining absence-based findings ──
+    // In project mode, absence-based findings are kept but demoted: cap severity
+    // at 'medium' and confidence at 0.6 since the missing capability may still
+    // exist in another file not yet analyzed.
+    const taggedFindings = gatedFindings.map((f) => {
+        if (isAbsenceBasedFinding(f)) {
+            const cappedSeverity = { critical: "medium", high: "medium" };
+            return {
+                ...f,
+                isAbsenceBased: true,
+                provenance: f.provenance ?? "absence-of-pattern",
+                severity: (cappedSeverity[f.severity] ?? f.severity),
+                confidence: Math.min(f.confidence ?? 0.5, 0.6),
+            };
+        }
+        return f;
+    });
+    // ── Framework-aware confidence reduction ──
+    // Detect frameworks/middleware from code patterns (works for all languages)
+    // and reduce confidence for findings that the framework inherently handles.
+    const frameworkAware = applyFrameworkAwareness(taggedFindings, code);
+    // ── AST-aware refinements: dead code removal, scope context, import awareness, taint flows ──
+    const astStructure = options?._astCache;
+    const refinedFindings = astStructure
+        ? applyAstRefinements(frameworkAware, astStructure, options?._taintFlows)
+        : frameworkAware;
+    // ── Inline suppression: respect // judges-ignore RULE-ID comments ──
+    const { findings: unsuppressed, suppressed: suppressionRecords } = applyInlineSuppressionsWithAudit(refinedFindings, code);
+    // ── Auto-fix patches: attach machine-applicable patches where possible ──
+    const patchEnriched = enrichWithPatches(unsuppressed, code);
+    // ── Contextual auto-fix: generate suggestedFix for findings that lack one ──
+    const contextuallyFixed = enrichWithContextualFixes(patchEnriched, code);
+    const filteredFindings = applyConfidenceThreshold(contextuallyFixed, options);
+    const configFiltered = applyConfig(filteredFindings, options?.config);
+    const score = calculateScore(configFiltered, code);
+    const verdict = deriveVerdict(configFiltered, score);
+    const summary = buildSummary(judge, configFiltered, score, verdict);
+    return {
+        judgeId: judge.id,
+        judgeName: judge.name,
+        verdict,
+        score,
+        summary,
+        findings: configFiltered,
+        suppressions: suppressionRecords.length > 0 ? suppressionRecords : undefined,
+    };
+}
+// ─── Per-File Finding Cap ────────────────────────────────────────────────────
+/** Default maximum findings per file — keeps output actionable. */
+const DEFAULT_MAX_FINDINGS_PER_FILE = 20;
+/**
+ * Enrich findings that lack a suggestedFix with a contextual fix derived from
+ * the code context around the affected lines + the finding's recommendation.
+ */
+function enrichWithContextualFixes(findings, code) {
+    const lines = code.split("\n");
+    return findings.map((f) => {
+        if (f.suggestedFix || !f.lineNumbers || f.lineNumbers.length === 0)
+            return f;
+        // Build context: extract the offending line(s) and combine with the recommendation
+        const firstLine = f.lineNumbers[0] - 1;
+        if (firstLine < 0 || firstLine >= lines.length)
+            return f;
+        const offendingLine = lines[firstLine].trim();
+        if (!offendingLine || !f.recommendation)
+            return f;
+        // Generate a contextual fix that references the actual code
+        const suggestedFix = `At line ${f.lineNumbers[0]}: \`${offendingLine.slice(0, 80)}\` → ${f.recommendation}`;
+        return { ...f, suggestedFix };
+    });
+}
+/**
+ * Synthesize a code review decision from findings — transforms a flat list of
+ * findings into an actionable reviewer verdict (approve / request-changes / comment).
+ */
+function synthesizeReviewDecision(findings) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const f of findings) {
+        if (f.severity in counts)
+            counts[f.severity]++;
+    }
+    const total = findings.length;
+    const allAutoFixable = total > 0 && findings.every((f) => f.patch || f.suggestedFix);
+    // Determine action
+    let action;
+    if (counts.critical > 0 || counts.high > 0) {
+        action = "request-changes";
+    }
+    else if (counts.medium > 0) {
+        action = "comment";
+    }
+    else {
+        action = "approve";
+    }
+    // Build blocking issues list (top 3 critical/high)
+    const blockingIssues = findings
+        .filter((f) => f.severity === "critical" || f.severity === "high")
+        .slice(0, 3)
+        .map((f) => `[${f.ruleId}] ${f.title}`);
+    // Build human-readable summary
+    let summary;
+    if (action === "approve") {
+        summary =
+            total === 0
+                ? "No issues found. Code looks good to merge."
+                : `${total} minor issue${total > 1 ? "s" : ""} found (${counts.low} low, ${counts.info} info). Safe to merge with optional improvements.`;
+    }
+    else if (action === "request-changes") {
+        const blocking = counts.critical + counts.high;
+        summary = `${blocking} blocking issue${blocking > 1 ? "s" : ""} found that must be resolved before merging`;
+        if (counts.critical > 0)
+            summary += ` (${counts.critical} critical)`;
+        summary += ". " + blockingIssues.join("; ") + ".";
+        if (allAutoFixable)
+            summary += " All issues have auto-fix patches available.";
+    }
+    else {
+        summary = `${counts.medium} medium-severity issue${counts.medium > 1 ? "s" : ""} found. Review recommended before merging.`;
+        if (counts.low + counts.info > 0)
+            summary += ` Plus ${counts.low + counts.info} minor items.`;
+    }
+    return {
+        action,
+        summary,
+        severityCounts: counts,
+        totalFindings: total,
+        allAutoFixable,
+        blockingIssues,
+    };
+}
+/**
+ * Cap the number of findings by priority-sorting and keeping only
+ * the top N.  Ensures high-severity / high-confidence findings always survive.
+ *
+ * In the current single-file `evaluateWithTribunal` pipeline all findings
+ * belong to one file, so a flat cap suffices.  When multi-file evaluation
+ * is added, this function should group findings by file path first.
+ */
+function applyPerFileFindingCap(findings, maxFindings) {
+    if (maxFindings <= 0 || findings.length <= maxFindings)
+        return findings;
+    // Sort by: severity desc → confidence desc → has suggestedFix → description length
+    const sorted = [...findings].sort((a, b) => {
+        const sevDiff = severityRank(b.severity) - severityRank(a.severity);
+        if (sevDiff !== 0)
+            return sevDiff;
+        const confDiff = (b.confidence ?? 0) - (a.confidence ?? 0);
+        if (confDiff !== 0)
+            return confDiff;
+        const fixDiff = (b.suggestedFix ? 1 : 0) - (a.suggestedFix ? 1 : 0);
+        if (fixDiff !== 0)
+            return fixDiff;
+        return b.description.length - a.description.length;
+    });
+    return sorted.slice(0, maxFindings);
+}
+/**
+ * Run the full tribunal — all judges evaluate the code.
+ */
+export function evaluateWithTribunal(code, language, context, options) {
+    // ── Disk cache: check for a previously cached result ──
+    // Include options that affect output in the cache key so different
+    // evaluations of the same code (e.g. with/without AST, different configs)
+    // are cached separately.
+    const optionsSuffix = options
+        ? JSON.stringify({
+            ast: options.includeAstFindings,
+            mc: options.minConfidence,
+            mf: options.maxFindingsPerFile,
+            dr: options.config?.disabledRules,
+            dj: options.config?.disabledJudges,
+            ms: options.config?.minSeverity,
+            jw: options.config?.judgeWeights,
+            mfg: options.mustFixGate,
+            at: options.autoTune,
+            drev: options.deepReview,
+            cf: options.confidenceFilter,
+            rf: options.relatedFiles?.length,
+        })
+        : "";
+    const hash = contentHash(code, language + optionsSuffix);
+    const diskCache = getSharedDiskCache();
+    if (diskCache) {
+        const cached = diskCache.get(hash);
+        if (cached)
+            return cached;
+    }
+    // Compute AST once and share across all judges via options
+    // Use content-hash cache to avoid re-computing for identical code
+    const includeAst = options?.includeAstFindings ?? true;
+    let astResult = options?._astCache;
+    if (!astResult && includeAst) {
+        astResult = astStructureCache.get(hash);
+        if (!astResult) {
+            astResult = analyzeStructure(code, language);
+            astStructureCache.set(hash, astResult);
+        }
+    }
+    let taintResult = options?._taintFlows;
+    if (!taintResult) {
+        taintResult = taintFlowCache.get(hash);
+        if (!taintResult) {
+            taintResult = analyzeTaintFlows(code, language);
+            taintFlowCache.set(hash, taintResult);
+        }
+    }
+    const enrichedOptions = {
+        ...options,
+        ...(astResult ? { _astCache: astResult } : {}),
+        ...(taintResult ? { _taintFlows: taintResult } : {}),
+    };
+    const { judges, skipped: skippedJudges } = resolveJudgeSet(enrichedOptions);
+    const tribunalStart = performance.now();
+    const evaluations = judges.map((judge) => {
+        const start = performance.now();
+        const result = evaluateWithJudge(judge, code, language, context, enrichedOptions);
+        result.durationMs = Math.round(performance.now() - start);
+        return result;
+    });
+    const tribunalDurationMs = Math.round(performance.now() - tribunalStart);
+    // Weighted score aggregation — uses judgeWeights from config when available
+    const weights = enrichedOptions?.config?.judgeWeights;
+    let overallScore;
+    if (weights && Object.keys(weights).length > 0) {
+        let totalWeight = 0;
+        let weightedSum = 0;
+        for (const e of evaluations) {
+            const w = weights[e.judgeId] ?? 1.0;
+            weightedSum += e.score * w;
+            totalWeight += w;
+        }
+        overallScore = totalWeight > 0 ? Math.round(weightedSum / totalWeight) : 0;
+    }
+    else {
+        overallScore = Math.round(evaluations.reduce((sum, e) => sum + e.score, 0) / evaluations.length);
+    }
+    const overallVerdict = evaluations.some((e) => e.verdict === "fail")
+        ? "fail"
+        : evaluations.some((e) => e.verdict === "warning")
+            ? "warning"
+            : "pass";
+    const rawFindings = evaluations.flatMap((e) => e.findings);
+    // ── Recall boost (once, not per-judge) ──
+    // Apply supplementary recall-boost patterns a single time and merge into
+    // the raw findings before cross-evaluator dedup. Previously this ran
+    // inside evaluateWithJudge(), producing N identical copies per judge.
+    const boostResult = applyRecallBoost(code, language);
+    if (boostResult.findings.length > 0) {
+        for (const bf of boostResult.findings) {
+            if (!rawFindings.some((f) => f.ruleId === bf.ruleId)) {
+                rawFindings.push(bf);
+            }
+        }
+    }
+    const dedupedFindings = crossEvaluatorDedup(rawFindings);
+    const { filtered: fpFiltered } = filterFalsePositiveHeuristics(dedupedFindings, code, language, enrichedOptions?.filePath);
+    const configFiltered = applyConfig(fpFiltered, options?.config);
+    // ── Custom rules from .judgesrc ──
+    // Evaluate user-defined pattern-based rules and append to findings
+    if (options?.config?.customRules && options.config.customRules.length > 0) {
+        for (const rule of options.config.customRules) {
+            try {
+                const re = new RegExp(rule.pattern, "gm");
+                const codeLines = code.split("\n");
+                const matchedLines = [];
+                for (let i = 0; i < codeLines.length; i++) {
+                    if (re.test(codeLines[i]))
+                        matchedLines.push(i + 1);
+                    re.lastIndex = 0;
+                }
+                if (matchedLines.length > 0) {
+                    configFiltered.push({
+                        ruleId: rule.id,
+                        severity: rule.severity,
+                        title: rule.title,
+                        description: rule.description || rule.title,
+                        lineNumbers: matchedLines,
+                        recommendation: rule.recommendation || `Review occurrences of pattern: ${rule.pattern}`,
+                        confidence: 0.8,
+                    });
+                }
+            }
+            catch {
+                // Invalid regex in custom rule — skip silently
+            }
+        }
+    }
+    // ── Feedback-driven confidence calibration & auto-tuning ──
+    // When options.calibrate is set, load the feedback store and apply:
+    // 1. Auto-suppression of rules with FP rate ≥ 80%
+    // 2. Severity downgrade for rules with FP rate 50-80%
+    // 3. Confidence calibration based on historical FP rates
+    let calibrated = configFiltered;
+    let autoTuneMetadata;
+    if (enrichedOptions.calibrate) {
+        try {
+            const calOpts = typeof enrichedOptions.calibrate === "object" ? enrichedOptions.calibrate : undefined;
+            const feedbackStore = loadFeedbackStore(calOpts?.feedbackPath);
+            if (feedbackStore.entries.length > 0) {
+                const tuned = applyAutoTune(calibrated, feedbackStore);
+                calibrated = tuned.findings;
+                autoTuneMetadata = { suppressed: tuned.suppressed, downgraded: tuned.downgraded };
+            }
+            else {
+                // No feedback data — try plain calibration profile
+                const profile = loadCalibrationProfile(calOpts);
+                if (profile.isActive) {
+                    calibrated = calibrateFindings(calibrated, profile, calOpts);
+                }
+            }
+        }
+        catch {
+            // Calibration failure is non-fatal — continue with uncalibrated findings
+        }
+    }
+    else if (enrichedOptions.autoTune) {
+        // ── Standalone auto-tune (without full calibrate) ──
+        // Lightweight feedback-only tuning path: applies auto-suppression and
+        // severity downgrades from the feedback store without requiring a
+        // full calibration profile.
+        try {
+            const feedbackStore = loadFeedbackStore();
+            if (feedbackStore.entries.length > 0) {
+                const tuned = applyAutoTune(calibrated, feedbackStore);
+                calibrated = tuned.findings;
+                autoTuneMetadata = { suppressed: tuned.suppressed, downgraded: tuned.downgraded };
+            }
+        }
+        catch {
+            // Auto-tune failure is non-fatal
+        }
+    }
+    // ── Auto-activate model-specific calibration profile ──
+    // If the model-fingerprint judge detected a model, apply the model-specific
+    // calibration profile automatically (when feedback data exists).
+    try {
+        const modelFindings = calibrated.filter((f) => f.ruleId.startsWith("MFPR-"));
+        if (modelFindings.length > 0) {
+            // Extract detected model name from the finding title
+            const title = modelFindings[0].title;
+            const mIdx = title.indexOf("matches ");
+            const gIdx = mIdx >= 0 ? title.indexOf(" generation", mIdx + 8) : -1;
+            if (mIdx >= 0 && gIdx > mIdx) {
+                const detectedModel = title.substring(mIdx + 8, gIdx).trim();
+                const feedbackStore = loadFeedbackStore();
+                if (feedbackStore.entries.length > 0) {
+                    const modelProfile = buildModelCalibrationProfile(feedbackStore, detectedModel);
+                    if (modelProfile.isActive) {
+                        calibrated = calibrateFindings(calibrated, modelProfile);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Model-specific calibration failure is non-fatal
+    }
+    // ── Triage feedback: adjust confidence based on historical false positive rates ──
+    let triageAdjusted = calibrated;
+    try {
+        const triageStore = loadFindingStore();
+        if (triageStore.findings.length > 0) {
+            triageAdjusted = applyTriageFeedback(calibrated, triageStore);
+        }
+    }
+    catch {
+        // No triage data or error loading — continue without adjustment
+    }
+    const maxFindings = options?.maxFindingsPerFile ?? DEFAULT_MAX_FINDINGS_PER_FILE;
+    // ── Session feedback calibration ──
+    // Apply confidence penalties from accumulated FP feedback in the
+    // current evaluation session. This is the real-time agentic loop:
+    // user marks findings as FP → session records it → subsequent
+    // evaluations automatically reduce confidence on those rules.
+    let sessionAdjusted = triageAdjusted;
+    try {
+        const session = getGlobalSession();
+        const tally = session.getFeedbackTally();
+        if (tally.size > 0) {
+            sessionAdjusted = triageAdjusted.map((f) => {
+                const penalty = session.getConfidencePenalty(f.ruleId);
+                if (penalty < 1.0) {
+                    const adjusted = clampConfidence((f.confidence ?? 0.5) * penalty);
+                    return { ...f, confidence: adjusted };
+                }
+                return f;
+            });
+        }
+    }
+    catch {
+        // Session feedback calibration failure is non-fatal
+    }
+    // ── Confidence-based output filtering ──
+    // When confidenceFilter is set, drop findings below the threshold entirely.
+    // This gives callers a first-class knob to control signal-to-noise ratio.
+    let confidenceFiltered = sessionAdjusted;
+    let confidenceFilteredOutCount = 0;
+    if (enrichedOptions.confidenceFilter !== undefined &&
+        enrichedOptions.confidenceFilter !== null &&
+        enrichedOptions.confidenceFilter > 0) {
+        const threshold = enrichedOptions.confidenceFilter;
+        const before = confidenceFiltered.length;
+        confidenceFiltered = confidenceFiltered.filter((f) => (f.confidence ?? 0.5) >= threshold);
+        confidenceFilteredOutCount = before - confidenceFiltered.length;
+    }
+    const cappedFindings = applyPerFileFindingCap(confidenceFiltered, maxFindings);
+    // ── Confidence-based tiering for progressive disclosure ──
+    // Tag each finding with a disclosure tier so downstream consumers (CLI,
+    // formatters, VS Code extension) can show only high-confidence findings
+    // by default and reveal lower tiers on demand.
+    const escalationThreshold = options?.config?.escalationThreshold;
+    const allFindings = cappedFindings.map((f) => {
+        const conf = f.confidence ?? 0.5;
+        const tier = conf >= 0.8 ? "essential" : conf >= 0.6 ? "important" : "supplementary";
+        const needsHumanReview = escalationThreshold !== undefined && conf < escalationThreshold ? true : undefined;
+        const owaspLlmTop10 = mapToOwaspLlmTop10(f);
+        const provenance = f.provenance ?? "regex-pattern-match";
+        return {
+            ...f,
+            confidenceTier: tier,
+            provenance,
+            ...(needsHumanReview ? { needsHumanReview } : {}),
+            ...(owaspLlmTop10 ? { owaspLlmTop10 } : {}),
+        };
+    });
+    // ── Structured CWE/OWASP IDs and Learn More URLs ──
+    const enrichedFindings = enrichWithSecurityIds(allFindings);
+    const mustFixGate = evaluateMustFixGate(enrichedFindings, options?.mustFixGate);
+    const criticalCount = enrichedFindings.filter((f) => f.severity === "critical").length;
+    const highCount = enrichedFindings.filter((f) => f.severity === "high").length;
+    const effectiveVerdict = mustFixGate?.triggered ? "fail" : overallVerdict;
+    const summary = buildTribunalSummary(evaluations, effectiveVerdict, overallScore, criticalCount, highCount) +
+        (mustFixGate
+            ? `\n\n## Must-Fix Gate\n\n- Status: **${mustFixGate.triggered ? "TRIGGERED" : "PASS"}**\n- Minimum confidence: **${Math.round(mustFixGate.minConfidence * 100)}%**\n- Matched findings: **${mustFixGate.matchedCount}**\n- Matched rule IDs: ${mustFixGate.matchedRuleIds.length > 0 ? mustFixGate.matchedRuleIds.map((id) => `\`${id}\``).join(", ") : "none"}\n`
+            : "");
+    // ── Aggregate suppression audit trail across all judges ──
+    const allSuppressions = evaluations.flatMap((e) => e.suppressions ?? []);
+    const result = {
+        overallVerdict: effectiveVerdict,
+        overallScore,
+        summary,
+        evaluations,
+        findings: enrichedFindings,
+        criticalCount,
+        highCount,
+        timestamp: new Date().toISOString(),
+        mustFixGate,
+        ...(allSuppressions.length > 0 ? { suppressions: allSuppressions } : {}),
+        timing: {
+            totalMs: tribunalDurationMs,
+            perJudge: evaluations.map((e) => ({
+                judgeId: e.judgeId,
+                judgeName: e.judgeName,
+                durationMs: e.durationMs ?? 0,
+            })),
+        },
+        reviewDecision: synthesizeReviewDecision(enrichedFindings),
+    };
+    // ── Deep review prompt attachment (P0.1) ──
+    // When deepReview is enabled, build and attach a structured LLM prompt
+    // section so downstream consumers can trigger a second-pass analysis.
+    if (enrichedOptions.deepReview) {
+        try {
+            const projectCtx = detectProjectContext(code, language, enrichedOptions.filePath);
+            const relatedSnippets = enrichedOptions.relatedFiles ?? [];
+            result.deepReviewPrompt = buildTribunalDeepReviewSection(judges, language, context, relatedSnippets.map((r) => ({ path: r.path, snippet: r.snippet, relationship: r.relationship })), projectCtx, enrichedOptions.maxPromptChars);
+        }
+        catch {
+            // Deep review prompt generation failure is non-fatal
+        }
+    }
+    // ── Attach auto-tune metadata ──
+    if (autoTuneMetadata) {
+        result.autoTuneApplied = autoTuneMetadata;
+    }
+    // ── Attach confidence filter metadata ──
+    if (enrichedOptions.confidenceFilter !== undefined &&
+        enrichedOptions.confidenceFilter !== null &&
+        confidenceFilteredOutCount > 0) {
+        result.confidenceFilterApplied = {
+            threshold: enrichedOptions.confidenceFilter,
+            filteredOut: confidenceFilteredOutCount,
+        };
+    }
+    // ── AI model detection escalation ──
+    // When the model-fingerprint judge (MFPR-* rules) fires, attach escalation
+    // metadata so downstream consumers can trigger deeper review or add
+    // provenance annotations automatically.
+    const mfprFindings = enrichedFindings.filter((f) => f.ruleId.startsWith("MFPR"));
+    if (mfprFindings.length > 0) {
+        const modelMap = new Map();
+        for (const f of mfprFindings) {
+            // Extract model name from description patterns like "ChatGPT/GPT-4 fingerprint"
+            const modelMatch = /^([\w/\-.]+)\s+fingerprint/i.exec(f.title) ?? /model:\s*([\w/\-.]+)/i.exec(f.description);
+            const model = modelMatch?.[1] ?? "unknown";
+            const existing = modelMap.get(model) ?? 0;
+            modelMap.set(model, Math.max(existing, f.confidence ?? 0.5));
+        }
+        result.aiEscalation = {
+            detected: true,
+            models: [...modelMap.entries()].map(([model, confidence]) => ({ model, confidence })),
+            triggerRules: [...new Set(mfprFindings.map((f) => f.ruleId))],
+            recommendation: mfprFindings.some((f) => (f.confidence ?? 0) >= 0.8)
+                ? "AI-generated code detected with high confidence — consider requiring human review sign-off"
+                : "AI-generated code patterns detected — review for model-specific biases",
+        };
+    }
+    // ── Human escalation protocol ──
+    // Evaluate which findings need human review based on escalation policy.
+    // Enhances the review decision with escalation routing information.
+    if (options?.config?.escalationThreshold || options?.filePath) {
+        try {
+            const escalationPolicy = options?.config?.escalationThreshold
+                ? { confidenceThreshold: options.config.escalationThreshold }
+                : undefined;
+            const escalations = evaluateEscalations(result, options?.filePath ?? "<unknown>", escalationPolicy);
+            if (escalations.length > 0 && result.reviewDecision) {
+                result.reviewDecision = enhanceReviewWithEscalations(result.reviewDecision, escalations);
+            }
+        }
+        catch {
+            // Escalation evaluation failure is non-fatal
+        }
+    }
+    // ── Disk cache: persist for future runs ──
+    if (diskCache) {
+        try {
+            diskCache.set(hash, result, options?.filePath);
+        }
+        catch {
+            // Non-fatal — disk write failure should not break evaluation
+        }
+    }
+    return result;
+}
+// ─── Streaming Evaluation ────────────────────────────────────────────────────
+/**
+ * Streaming tribunal evaluation — yields per-judge results as each judge
+ * completes, enabling progressive UI updates and early termination.
+ *
+ * Each yielded `StreamingBatch` contains the judge evaluation, execution
+ * trace, and running aggregate statistics.
+ *
+ * Usage:
+ * ```ts
+ * for await (const batch of evaluateWithTribunalStreaming(code, lang)) {
+ *   console.log(`${batch.judgeName}: ${batch.evaluation.findings.length} findings`);
+ *   if (batch.aggregate.criticalSoFar > 10) break; // early termination
+ * }
+ * ```
+ */
+export async function* evaluateWithTribunalStreaming(code, language, context, options) {
+    const includeAst = options?.includeAstFindings ?? true;
+    const hash = contentHash(code, language);
+    let astResult = options?._astCache;
+    if (!astResult && includeAst) {
+        astResult = astStructureCache.get(hash);
+        if (!astResult) {
+            astResult = analyzeStructure(code, language);
+            astStructureCache.set(hash, astResult);
+        }
+    }
+    let taintResult = options?._taintFlows;
+    if (!taintResult) {
+        taintResult = taintFlowCache.get(hash);
+        if (!taintResult) {
+            taintResult = analyzeTaintFlows(code, language);
+            taintFlowCache.set(hash, taintResult);
+        }
+    }
+    const enrichedOptions = {
+        ...options,
+        ...(astResult ? { _astCache: astResult } : {}),
+        ...(taintResult ? { _taintFlows: taintResult } : {}),
+    };
+    const { judges, skipped: skippedJudges } = resolveJudgeSet(enrichedOptions);
+    const totalJudges = judges.length;
+    let completedJudges = 0;
+    let findingsSoFar = 0;
+    let criticalSoFar = 0;
+    let highSoFar = 0;
+    let scoreSum = 0;
+    let hasFailure = false;
+    let hasWarning = false;
+    for (const judge of judges) {
+        const start = performance.now();
+        const evaluation = evaluateWithJudge(judge, code, language, context, enrichedOptions);
+        const durationMs = Math.round(performance.now() - start);
+        evaluation.durationMs = durationMs;
+        completedJudges++;
+        findingsSoFar += evaluation.findings.length;
+        criticalSoFar += evaluation.findings.filter((f) => f.severity === "critical").length;
+        highSoFar += evaluation.findings.filter((f) => f.severity === "high").length;
+        scoreSum += evaluation.score;
+        if (evaluation.verdict === "fail")
+            hasFailure = true;
+        if (evaluation.verdict === "warning")
+            hasWarning = true;
+        const trace = {
+            judgeId: judge.id,
+            judgeName: judge.name,
+            durationMs,
+            rules: buildRuleTraces(evaluation),
+            rawFindingCount: evaluation.findings.length,
+            finalFindingCount: evaluation.findings.length,
+            ...(astResult
+                ? {
+                    astResolution: {
+                        functionsAnalyzed: astResult.functions.length,
+                        maxComplexity: Math.max(0, ...astResult.functions.map((f) => f.cyclomaticComplexity)),
+                        taintFlowsDetected: taintResult?.length ?? 0,
+                    },
+                }
+                : {}),
+        };
+        const currentVerdict = hasFailure ? "fail" : hasWarning ? "warning" : "pass";
+        yield {
+            judgeId: judge.id,
+            judgeName: judge.name,
+            evaluation,
+            trace,
+            aggregate: {
+                completedJudges,
+                totalJudges,
+                findingsSoFar,
+                criticalSoFar,
+                highSoFar,
+                currentScore: Math.round(scoreSum / completedJudges),
+                currentVerdict,
+            },
+            done: completedJudges === totalJudges,
+        };
+        // Yield to the event loop between judges for responsiveness
+        await new Promise((r) => setTimeout(r, 0));
+    }
+}
+/**
+ * Build rule-level traces from a judge evaluation for observability.
+ */
+function buildRuleTraces(evaluation) {
+    const ruleMap = new Map();
+    for (const f of evaluation.findings) {
+        const existing = ruleMap.get(f.ruleId);
+        if (existing) {
+            existing.count++;
+            existing.peakConf = Math.max(existing.peakConf, f.confidence ?? 0.5);
+        }
+        else {
+            ruleMap.set(f.ruleId, { count: 1, peakConf: f.confidence ?? 0.5 });
+        }
+    }
+    return [...ruleMap.entries()].map(([ruleId, { count, peakConf }]) => ({
+        ruleId,
+        matched: true,
+        findingCount: count,
+        peakConfidence: peakConf,
+    }));
+}
+// ─── Project-level Multi-file Analysis (delegated to project.ts) ─────────────
+import { evaluateProject as _evaluateProject } from "./project.js";
+export { scanProjectWideSecurityPatterns } from "./project.js";
+export function evaluateProject(files, context, options) {
+    const runner = { evaluateWithTribunal };
+    // Enable project mode so absence-based findings survive for cross-file resolution
+    return _evaluateProject(runner, files, context, { ...options, projectMode: true });
+}
+// ─── Diff-based Incremental Analysis ──────────────────────────────────────────
+/**
+ * Evaluate only the changed lines in a diff. Runs the full tribunal on the
+ * new code but filters findings to only those affecting changed line ranges.
+ */
+export function evaluateDiff(code, language, changedLines, context, options) {
+    const verdict = evaluateWithTribunal(code, language, context, options);
+    const allFindings = verdict.findings;
+    // Filter findings to only those touching changed lines.
+    // Also drop absence-based findings in diff mode — these flag missing
+    // capabilities (rate limiting, auth, etc.) which cannot be accurately
+    // assessed from a single diff hunk.
+    const changedSet = new Set(changedLines);
+    const diffFindings = allFindings.filter((f) => {
+        if (isAbsenceBasedFinding(f))
+            return false;
+        if (!f.lineNumbers || f.lineNumbers.length === 0)
+            return false;
+        return f.lineNumbers.some((ln) => changedSet.has(ln));
+    });
+    const score = calculateScore(diffFindings, code);
+    const diffVerdict = deriveVerdict(diffFindings, score);
+    return {
+        linesAnalyzed: changedLines.length,
+        findings: diffFindings,
+        score,
+        verdict: diffVerdict,
+        summary: `Diff analysis: ${changedLines.length} changed lines, ${diffFindings.length} findings in changed code, score ${score}/100 — ${diffVerdict.toUpperCase()}`,
+    };
+}
+// ─── Dependency / Supply-chain Analysis (delegated to dependencies.ts) ───────
+export { analyzeDependencies } from "./dependencies.js";
+// ─── App Builder Flow (Review → Translate → Task Plan) ─────────────────────
+import { runAppBuilderWorkflow as _runAppBuilderWorkflow } from "./app-builder.js";
+const engine = { evaluateWithTribunal, evaluateProject, evaluateDiff };
+export function runAppBuilderWorkflow(params) {
+    return _runAppBuilderWorkflow(engine, params);
+}
+// ─── Re-exports ──────────────────────────────────────────────────────────────
+export { formatVerdictAsMarkdown, formatEvaluationAsMarkdown };
+export { enrichWithPatches } from "../patches/index.js";
+export { crossEvaluatorDedup, crossFileDedup, diffFindings, formatFindingDiff, evaluateNetChangeGate, } from "../dedup.js";