@kernlang/review 3.3.8 → 3.4.0

package/dist/index.js

@@ -11,32 +11,46 @@
 import { createRequire } from 'node:module';
 import { countTokens, parseWithDiagnostics, serializeIR } from '@kernlang/core';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
-import { dirname, join, relative } from 'path';
+import { dirname, join, relative, sep } from 'path';
 import { Project } from 'ts-morph';
 // This module compiles to ESM (`type: "module"`), so the runtime has no `require`.
 // `@kernlang/review-python` is an optional peer — we load it on demand with a
 // createRequire shim. Without this shim the dynamic load throws
 // `ReferenceError: require is not defined`, the catch swallows the error, and
-// every Python file falls into the "missing-python-support" info fallback —
-// silently disabling the fullstack wedge rules on any cross-stack repo.
+// Python files use a precise optional mapper when present, then degrade to the
+// built-in fallback extractor so fullstack wedge rules still run in npm installs
+// that do not ship @kernlang/review-python.
 const moduleRequire = createRequire(import.meta.url);
+function optionalPackageSpecifier(scope, name) {
+    return `${scope}/${name}`;
+}
+function optionalLocalSpecifier(...parts) {
+    return parts.join('/');
+}
+function requireOptionalModule(specifier) {
+    return moduleRequire(specifier);
+}
 import { buildCallGraph } from './call-graph.js';
 import { runConceptRules } from './concept-rules/index.js';
 import { structuralDiff } from './differ.js';
 import { runTSCDiagnostics } from './external-tools.js';
 import { buildFileContextMap } from './file-context.js';
-import { classifyFileRole } from './file-role.js';
+import { classifyFileRole, classifyFileRoleByPath } from './file-role.js';
 import { resolveImportGraph } from './graph.js';
 import { createInMemoryProject, findTsConfig, inferFromSourceFile } from './inferrer.js';
 import { flattenIR, lintKernIR } from './kern-lint.js';
 import { extractTsConcepts } from './mappers/ts-concepts.js';
 import { mineNorms } from './norm-miner.js';
 import { synthesizeObligations } from './obligations.js';
+import { canonicalize } from './path-canonical.js';
+import { findProjectRoot, getProjectContext, isPathIgnored, isReviewable, } from './project-context.js';
 import { buildPublicApiMap, expandPublicApiThroughReExports } from './public-api.js';
+import { extractPythonConceptsFallback } from './python-fallback.js';
 import { runQualityRules } from './quality-rules.js';
 import { assignDefaultConfidence, calculateStats, sortAndDedup, sortFindings } from './reporter.js';
 import { debugDetail, ReviewHealthBuilder } from './review-health.js';
 import { loadBuiltinNativeRules, loadNativeRules } from './rule-loader.js';
+import { applyOverlapCalibration, applyRoleAwareConfidence, applyRuleQualityCalibration } from './rule-quality.js';
 import { lintConfidenceGraph, lintMultiFileConfidenceGraph } from './rules/confidence.js';
 import { crossFileAsyncRule, deadExportRule } from './rules/dead-code.js';
 import { runFastapiConceptRules } from './rules/fastapi.js';
@@ -57,14 +71,84 @@ import { buildConfidenceGraph, computeConfidenceSummary, serializeGraph } from '
 import { applySuppression } from './suppression/index.js';
 import { analyzeTaint, analyzeTaintCrossFile, crossFileTaintToFindings, taintToFindings } from './taint.js';
 import { createFingerprint } from './types.js';
+const TYPESCRIPT_CONCEPT_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+let cachedPythonExtractor;
+function loadPythonConceptExtractor() {
+    if (cachedPythonExtractor)
+        return cachedPythonExtractor;
+    const failures = [];
+    const candidates = [
+        optionalPackageSpecifier('@kernlang', 'review-python'),
+        optionalLocalSpecifier('..', '..', 'review-python', 'dist', 'index.js'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const mod = requireOptionalModule(candidate);
+            if (typeof mod.extractPythonConcepts === 'function') {
+                cachedPythonExtractor = { extractor: mod.extractPythonConcepts, usingFallback: false };
+                return cachedPythonExtractor;
+            }
+            failures.push(`${candidate}: extractPythonConcepts export missing`);
+        }
+        catch (err) {
+            failures.push(`${candidate}: ${err.message}`);
+        }
+    }
+    cachedPythonExtractor = {
+        extractor: extractPythonConceptsFallback,
+        usingFallback: true,
+        failureDetail: failures.join('\n'),
+    };
+    return cachedPythonExtractor;
+}
+function extensionOf(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    return dot === -1 ? '' : filePath.slice(dot);
+}
+function isTypeScriptConceptFile(filePath) {
+    return TYPESCRIPT_CONCEPT_EXTENSIONS.has(extensionOf(filePath));
+}
+function isConceptMap(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.filePath === 'string' && Array.isArray(candidate.nodes) && Array.isArray(candidate.edges);
+}
+function normalizeExternalConcepts(externalConcepts) {
+    const normalized = new Map();
+    if (!externalConcepts)
+        return normalized;
+    for (const [key, value] of externalConcepts) {
+        if (!isConceptMap(value))
+            continue;
+        normalized.set(key, value);
+    }
+    return normalized;
+}
+function extractConceptsFromSource(source, filePath, health, tsProject) {
+    if (isTypeScriptConceptFile(filePath)) {
+        const project = tsProject ?? createInMemoryProject();
+        const sf = project.createSourceFile(filePath, source, { overwrite: true });
+        return extractTsConcepts(sf, filePath);
+    }
+    if (filePath.endsWith('.py')) {
+        const pythonExtractor = loadPythonConceptExtractor();
+        if (pythonExtractor.usingFallback) {
+            health?.noteKind('concept-extraction', 'fallback', 'Using built-in Python fallback extractor — install/fix @kernlang/review-python for tree-sitter precision', debugDetail(pythonExtractor.failureDetail));
+        }
+        return pythonExtractor.extractor(source, filePath);
+    }
+    return undefined;
+}
 export { buildCallGraph } from './call-graph.js';
 export { runConceptRules } from './concept-rules/index.js';
 // Confidence layer
 export { buildConfidenceGraph, buildMultiFileConfidenceGraph, computeConfidenceSummary, parseConfidence, propagateConfidence, resolveBaseConfidence, serializeGraph, } from './confidence.js';
 export { structuralDiff } from './differ.js';
+export { evaluateReviewReports, formatReviewEvalSummary, normalizeReviewEvalManifest, summarizeReviewEvalResults, } from './eval.js';
 export { linkToNodes, runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths } from './external-tools.js';
 export { buildFileContextMap, clearFileContextCache } from './file-context.js';
-export { classifyFileRole } from './file-role.js';
+export { classifyFileRole, classifyFileRoleByPath } from './file-role.js';
 export { resolveImportGraph } from './graph.js';
 export { findTsConfig, inferFromFile, inferFromSource } from './inferrer.js';
 // KERN-IR lint pipeline (ground layer)
@@ -76,10 +160,12 @@ export { extractTsConcepts } from './mappers/ts-concepts.js';
 // Norm mining + obligations
 export { mineNorms } from './norm-miner.js';
 export { obligationsFromNorms, obligationsFromStructure, synthesizeObligations } from './obligations.js';
+export { applyReviewPolicyDefaults, getReviewPolicyProfile, inferReviewPolicy, } from './policy.js';
 export { buildPublicApiMap, EMPTY_PUBLIC_API, expandPublicApiThroughReExports, isPublicApi, resolvePackageEntryFiles, resolveSpecifierToSrc, } from './public-api.js';
 export { runQualityRules } from './quality-rules.js';
 export { assignDefaultConfidence, calculateStats, checkEnforcement, dedup, formatEnforcement, formatReport, formatReportJSON, formatSARIF, formatSARIFWithMetadata, formatSARIFWithSuppressions, formatSummary, sortAndDedup, sortFindings, } from './reporter.js';
 export { debugDetail, ReviewHealthBuilder } from './review-health.js';
+export { applyRuleQualityCalibration, applyRuleSupersession, getRuleQualityProfile, isRulePromotedForCi, validateRuleQualityRegistry, } from './rule-quality.js';
 export { CONFIDENCE_RULES, lintConfidenceGraph, lintMultiFileConfidenceGraph } from './rules/confidence.js';
 export { actionMissingIdempotent, assumeLowTrust, branchNonExhaustive, collectUnbounded, expectRangeInverted, GROUND_LAYER_RULES, guardWithoutElse, reasonWithoutBasis, } from './rules/ground-layer.js';
 export { getRuleRegistry } from './rules/index.js';
@@ -92,6 +178,7 @@ export { computeSemanticDiff, computeSemanticDiffFromSource, formatSemanticDiff,
 export { applySuppression, configDirectives, isConceptRule, parseDirectives } from './suppression/index.js';
 // Taint tracking (Phase 2 + cross-file)
 export { analyzeTaint, analyzeTaintCrossFile, buildExportMap, buildImportMap, crossFileTaintToFindings, isSanitizerSufficient, taintToFindings, } from './taint.js';
+export { buildReviewTelemetry, formatReviewTelemetrySummary, parseReviewTelemetryJsonl, readReviewTelemetrySnapshots, summarizeReviewTelemetry, writeReviewTelemetrySnapshot, } from './telemetry.js';
 export { detectTemplates } from './template-detector.js';
 export { createFingerprint } from './types.js';
 // Cache (Phase 0)
@@ -251,32 +338,16 @@ export function extractConceptsForGraph(filePaths) {
     // is not cheap; on a whole-repo cache-prime (hundreds of files) the
     // per-file alloc adds real latency we don't want on a push webhook.
     let tsProject = null;
-    let extractPythonConcepts;
     for (const filePath of filePaths) {
+        if (!isReviewableFile(filePath) || !existsSync(filePath))
+            continue;
         try {
             const source = readFileSync(filePath, 'utf-8');
-            if (filePath.endsWith('.ts') ||
-                filePath.endsWith('.tsx') ||
-                filePath.endsWith('.mts') ||
-                filePath.endsWith('.cts')) {
-                if (!tsProject)
-                    tsProject = createInMemoryProject();
-                const sf = tsProject.createSourceFile(filePath, source);
-                out.set(filePath, extractTsConcepts(sf, filePath));
-            }
-            else if (filePath.endsWith('.py')) {
-                if (extractPythonConcepts === undefined) {
-                    try {
-                        extractPythonConcepts = moduleRequire('@kernlang/review-python').extractPythonConcepts;
-                    }
-                    catch {
-                        extractPythonConcepts = null;
-                    }
-                }
-                if (extractPythonConcepts) {
-                    out.set(filePath, extractPythonConcepts(source, filePath));
-                }
-            }
+            if (isTypeScriptConceptFile(filePath) && !tsProject)
+                tsProject = createInMemoryProject();
+            const concepts = extractConceptsFromSource(source, filePath, undefined, tsProject ?? undefined);
+            if (concepts)
+                out.set(filePath, concepts);
         }
         catch {
             // Best-effort — caller sees which files made it into the map.
@@ -460,7 +531,7 @@ function reviewSourceInternal(source, filePath, config, project, sourceFile) {
     // Phase 6: Concept extraction + concept rules (universal, cross-language)
     const emptyConcepts = { filePath, language: 'typescript', nodes: [], edges: [], extractorVersion: '0' };
     const concepts = safePhase('concepts', () => extractTsConcepts(sourceFile, filePath), emptyConcepts);
-    allFindings.push(...safePhase('concept-rules', () => runConceptRules(concepts, filePath), []));
+    allFindings.push(...safePhase('concept-rules', () => runConceptRules(concepts, filePath, undefined, undefined, config), []));
     // Phase 7: KERN-IR lint (ground layer + confidence rules on inferred nodes)
     const irNodes = inferred.map((r) => r.node);
     const groundFindings = safePhase('ground-lint', () => lintKernIR(irNodes, GROUND_LAYER_RULES), []);
@@ -510,8 +581,18 @@ function reviewSourceInternal(source, filePath, config, project, sourceFile) {
     }
     // Merge, dedup, sort — single shared utility
     const dedupedFindings = sortAndDedup(allFindings);
-    // Assign calibrated confidence scores to all findings
+    // Assign calibrated confidence scores to all findings.
+    // Order matters: assign-defaults → role-aware → overlap → rule-quality. The
+    // rule-quality pass flips the per-finding `calibrated` flag last so that
+    // graph-mode rerun on a union of findings does not compound multipliers.
     assignDefaultConfidence(dedupedFindings);
+    applyRoleAwareConfidence(dedupedFindings, fileRole, config);
+    const projectRoot = findProjectRoot(dirname(filePath));
+    if (projectRoot) {
+        const projectCtx = getProjectContext(projectRoot);
+        applyOverlapCalibration(dedupedFindings, projectCtx.external, config);
+    }
+    applyRuleQualityCalibration(dedupedFindings, config);
     // Apply suppression (inline comments + config disabledRules)
     const suppression = applySuppression(dedupedFindings, source, filePath, config, config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
@@ -653,6 +734,8 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
     });
     const dedupedFindings = sortAndDedup(allFindings);
     assignDefaultConfidence(dedupedFindings);
+    applyRoleAwareConfidence(dedupedFindings, classifyFileRoleByPath(filePath), _config);
+    applyRuleQualityCalibration(dedupedFindings, _config);
     const suppression = applySuppression(dedupedFindings, source, filePath, _config, _config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
     const kernTokens = countTokens(source);
@@ -683,11 +766,14 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
     const totalLines = source.split('\n').length;
     // Python: concept extraction + concept rules only
     let conceptFindings = [];
+    const health = new ReviewHealthBuilder();
     try {
-        // Dynamic import — @kernlang/review-python is optional
-        const { extractPythonConcepts } = moduleRequire('@kernlang/review-python');
-        const concepts = extractPythonConcepts(source, filePath);
-        conceptFindings = runConceptRules(concepts, filePath);
+        const pythonExtractor = loadPythonConceptExtractor();
+        if (pythonExtractor.usingFallback) {
+            health.noteKind('concept-extraction', 'fallback', 'Using built-in Python fallback extractor — install/fix @kernlang/review-python for tree-sitter precision', debugDetail(pythonExtractor.failureDetail));
+        }
+        const concepts = pythonExtractor.extractor(source, filePath);
+        conceptFindings = runConceptRules(concepts, filePath, undefined, undefined, config);
         if (config?.target === 'fastapi') {
             conceptFindings.push(...runFastapiConceptRules(concepts, filePath, source));
         }
@@ -704,30 +790,33 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
     }
     catch (err) {
         if (process.env.KERN_DEBUG)
-            console.error(`python mapper load failed: ${err.message}`);
-        // @kernlang/review-python not installed — skip concept extraction
+            console.error(`python concept extraction failed: ${err.message}`);
         conceptFindings = [
             {
                 source: 'kern',
-                ruleId: 'missing-python-support',
+                ruleId: 'python-concept-extraction-failed',
                 severity: 'info',
                 category: 'structure',
-                message: 'Install @kernlang/review-python for Python concept analysis',
+                message: 'Python concept extraction failed — Python findings may be incomplete',
                 primarySpan: { file: filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
-                fingerprint: 'missing-python-0',
+                fingerprint: 'python-concept-extraction-failed-0',
             },
         ];
     }
     const dedupedFindings = sortAndDedup(conceptFindings);
     assignDefaultConfidence(dedupedFindings);
+    applyRoleAwareConfidence(dedupedFindings, classifyFileRoleByPath(filePath), config);
+    applyRuleQualityCalibration(dedupedFindings, config);
     const suppression = applySuppression(dedupedFindings, source, filePath, config, config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
+    const reviewHealth = health.build();
     return {
         filePath,
         inferred: [],
         templateMatches: [],
         findings,
         ...(suppression.suppressed.length > 0 ? { suppressedFindings: sortAndDedup(suppression.suppressed) } : {}),
+        ...(reviewHealth ? { health: reviewHealth } : {}),
         stats: {
             totalLines,
             coveredLines: 0,
@@ -741,10 +830,15 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
 }
 /**
  * Review all .ts/.tsx/.py files in a directory.
+ *
+ * Honors the project's .gitignore by skipping untracked-and-ignored files —
+ * tracked artifacts are always reviewed even when their directory matches
+ * .gitignore, so published `dist/*.gen.ts` and similar do not slip through.
  */
 export function reviewDirectory(dirPath, recursive = false, config) {
     const reports = [];
-    const files = collectReviewableFiles(dirPath, recursive);
+    const ctx = getProjectContext(dirPath);
+    const files = collectReviewableFiles(dirPath, recursive, ctx);
     for (const file of files) {
         try {
             reports.push(reviewFile(file, config));
@@ -760,7 +854,7 @@ export function reviewDirectory(dirPath, recursive = false, config) {
  * Entry files get normal findings, upstream dependencies get origin='upstream'.
  */
 export function reviewGraph(entryFiles, config, graphOptions) {
-    const graph = resolveImportGraph(entryFiles, graphOptions);
+    const graph = graphOptions?.precomputedGraph ?? resolveImportGraph(entryFiles, graphOptions);
     const entrySet = new Set(graph.entryFiles);
     const reports = [];
     // Graph-wide subsystem status — one entry per (subsystem, kind) across the whole run.
@@ -860,35 +954,13 @@ export function reviewGraph(entryFiles, config, graphOptions) {
     // Cross-file concept analysis — re-run concept rules with full graph context
     // This fixes false positives where guards are in middleware files and effects in handlers
     const allConcepts = new Map();
-    // Cache the optional Python mapper: require() it once per graph run instead
-    // of per-file, and remember if it's absent so we don't pay the throw cost.
-    let extractPythonConcepts;
     for (const report of reports) {
         const filePath = report.filePath;
         try {
             const source = readFileSync(filePath, 'utf-8');
-            if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
-                const project = createInMemoryProject();
-                const sf = project.createSourceFile(filePath, source);
-                allConcepts.set(filePath, extractTsConcepts(sf, filePath));
-            }
-            else if (filePath.endsWith('.py')) {
-                // Python concept seeding is what powers the fullstack wedge rules
-                // (contract-drift, untyped-api-response, tainted-across-wire) in graph
-                // mode. Without this branch, `allConcepts` only contained TS entries
-                // and the rules silently found nothing on cross-stack repos.
-                if (extractPythonConcepts === undefined) {
-                    try {
-                        extractPythonConcepts = moduleRequire('@kernlang/review-python').extractPythonConcepts;
-                    }
-                    catch {
-                        extractPythonConcepts = null;
-                    }
-                }
-                if (extractPythonConcepts) {
-                    allConcepts.set(filePath, extractPythonConcepts(source, filePath));
-                }
-            }
+            const concepts = extractConceptsFromSource(source, filePath, graphHealth);
+            if (concepts)
+                allConcepts.set(filePath, concepts);
         }
         catch (err) {
             // Per-file failure — record once at graph level (builder dedupes), then move on.
@@ -918,7 +990,7 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         if (config.externalConcepts.size > MAX_EXTERNAL_CONCEPTS) {
             throw new Error(`reviewGraph: externalConcepts size ${config.externalConcepts.size} exceeds cap ${MAX_EXTERNAL_CONCEPTS}`);
         }
-        for (const [path, cm] of config.externalConcepts) {
+        for (const [path, cm] of normalizeExternalConcepts(config.externalConcepts)) {
             if (!allConcepts.has(path))
                 allConcepts.set(path, cm);
         }
@@ -927,10 +999,15 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         // Concept rule IDs to replace (remove per-file findings, add cross-file ones)
         const CONCEPT_RULE_IDS = new Set([
             'boundary-mutation',
+            'auth-propagation-drift',
             'ignored-error',
             'missing-response-model',
+            'mutation-without-idempotency',
+            'request-validation-drift',
             'sync-handler-does-io',
+            'unbounded-collection-query',
             'unguarded-effect',
+            'unhandled-api-error-shape',
             'unrecovered-effect',
         ]);
         for (const report of reports) {
@@ -940,7 +1017,7 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             // Remove per-file concept findings (they were run without cross-file context)
             report.findings = report.findings.filter((f) => !CONCEPT_RULE_IDS.has(f.ruleId));
             // Re-run concept rules with cross-file context
-            const crossFileConceptFindings = runConceptRules(concepts, report.filePath, allConcepts, graphImports);
+            const crossFileConceptFindings = runConceptRules(concepts, report.filePath, allConcepts, graphImports, graphConfig);
             report.findings.push(...crossFileConceptFindings);
         }
     }
@@ -982,7 +1059,12 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             });
             for (const gf of graph.files) {
                 try {
-                    cgProject.addSourceFileAtPath(gf.path);
+                    // Seed cgProject with CANONICAL paths so its internal SourceFile
+                    // store collapses pnpm/symlink duplicates (red-team #9). This pairs
+                    // with graph.ts feeding canonical paths to its own ts-morph project,
+                    // so all subsequent ts-morph lookups (here AND in buildCallGraph)
+                    // run through the same canonical key space.
+                    cgProject.addSourceFileAtPath(gf.canonicalPath);
                 }
                 catch {
                     /* skip unresolvable */
@@ -993,13 +1075,99 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         // Build the public-API map once per run — package.json walk is the heavy bit.
         // Then propagate through re-export chains so curated barrels (Agon-style:
         // `export { foo } from './worker.js'`) carry public-API status upstream.
-        const basePublicApi = buildPublicApiMap(graph.files.map((gf) => gf.path), config?.publicApi);
-        const publicApi = expandPublicApiThroughReExports(basePublicApi, (path) => cgProject?.getSourceFile(path));
+        // Pass canonical paths so the resulting `entryFiles` set keys match the
+        // canonical paths that cgProject (and therefore callGraph.functions[i]
+        // .filePath) uses. Otherwise red-team #9 sneaks back in: the call graph
+        // sees `/private/var/...` while the public-API map contains `/var/...`,
+        // and isPublicApi() misses every entry.
+        const basePublicApi = buildPublicApiMap(graph.files.map((gf) => gf.canonicalPath), config?.publicApi);
+        // Step 8: seeded files (Next.js conventions, package.json entries) may
+        // legitimately live outside the BFS-walked graph — for example a lazy
+        // route file beyond `maxDepth`, or a barrel re-exporting a helper that
+        // no eager import in the graph reaches. Without this on-demand load,
+        // expandPublicApiThroughReExports would silently drop those entries
+        // (sourceFileFor returns undefined → loop skips). Loading on demand
+        // costs only the seed entries we actually need, no extra graph work.
+        const sourceFileFor = (path) => {
+            if (!cgProject)
+                return undefined;
+            // Lookup must use canonical too — callers from buildPublicApiMap or
+            // expandPublicApiThroughReExports may hand us a path captured in its
+            // symlink form. Without canonicalisation this would miss a file that
+            // cgProject has stored under its realpath.
+            const canonical = canonicalize(path);
+            const known = cgProject.getSourceFile(canonical);
+            if (known)
+                return known;
+            try {
+                return cgProject.addSourceFileAtPath(canonical);
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const publicApi = expandPublicApiThroughReExports(basePublicApi, sourceFileFor);
+        // Step 10: blockers are passed alongside publicApi so dead-export's
+        // step 9b cap+trail logic can consume them. Producer 1 (unresolved
+        // named re-export with relative specifier) is wired in graph.ts and
+        // rides on `graph.blockers`; Producer 2 (non-literal dynamic import)
+        // is telemetry-only and surfaces via the unmappedDynamicImports counter
+        // below. Empty list is a valid "no blockers detected" state — the rule
+        // short-circuits without any change to existing semantics.
+        const reachabilityBlockers = graph.blockers ?? [];
+        // canonicalToDisplay maps canonical paths back to caller-facing forms
+        // so findings emitted by the rules carry user-friendly paths even
+        // though the rules themselves match against canonical fn.filePath.
+        const canonicalToDisplay = new Map();
+        for (const gf of graph.files) {
+            canonicalToDisplay.set(gf.canonicalPath, gf.path);
+        }
         for (const report of reports) {
-            const deadExportFindings = deadExportRule(callGraph, report.filePath, publicApi);
-            report.findings.push(...deadExportFindings);
-            const asyncFindings = crossFileAsyncRule(callGraph, report.filePath);
-            report.findings.push(...asyncFindings);
+            // The rules iterate callGraph.functions whose filePath is canonical
+            // (cgProject seeded canonical → ts-morph getFilePath returns canonical).
+            // report.filePath is the user-facing display form for diagnostics —
+            // canonicalise at this boundary so the rule's `fn.filePath !== filePath`
+            // filter matches.
+            const ruleFilePath = canonicalize(report.filePath);
+            const deadExportFindings = deadExportRule(callGraph, ruleFilePath, publicApi, reachabilityBlockers);
+            const asyncFindings = crossFileAsyncRule(callGraph, ruleFilePath);
+            // Map canonical paths in finding spans back to display so the user
+            // sees `/var/...` not `/private/var/...` (and pnpm symlink paths
+            // are expressed in their workspace-relative form).
+            for (const f of [...deadExportFindings, ...asyncFindings]) {
+                const display = canonicalToDisplay.get(f.primarySpan.file);
+                if (display)
+                    f.primarySpan.file = display;
+                if (f.relatedSpans) {
+                    for (const rs of f.relatedSpans) {
+                        const rsDisplay = canonicalToDisplay.get(rs.file);
+                        if (rsDisplay)
+                            rs.file = rsDisplay;
+                    }
+                }
+            }
+            report.findings.push(...deadExportFindings, ...asyncFindings);
+        }
+        // Surface graph-traversal telemetry. Two independent failure modes feed
+        // a SINGLE health note here because ReviewHealthBuilder dedupes by
+        // `(subsystem, kind)` — emitting two `'call-graph' / 'fallback'` notes
+        // would silently drop the second one (Codex review caught this).
+        //   • Producer 2: non-literal `import(expr)` — dead-export findings on
+        //     those files may include FPs the cap mechanism cannot reach (no
+        //     target file/exportName to attach a blocker to).
+        //   • Malformed static imports — previously a silent catch swallowed
+        //     these; now counted and surfaced. KERN_DEBUG logs each.
+        const unmappedDyn = graph.unmappedDynamicImports ?? 0;
+        const malformed = graph.malformedImports ?? 0;
+        if (unmappedDyn > 0 || malformed > 0) {
+            const parts = [];
+            if (unmappedDyn > 0) {
+                parts.push(`${unmappedDyn} non-literal dynamic import(s) could not be traced — dead-export findings in those files may include false positives that cannot be capped`);
+            }
+            if (malformed > 0) {
+                parts.push(`${malformed} static import declaration(s) could not be read by ts-morph — set KERN_DEBUG to surface the underlying errors`);
+            }
+            graphHealth.noteKind('call-graph', 'fallback', `${parts.join('; ')}.`);
         }
     }
     catch (err) {
@@ -1014,6 +1182,8 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         try {
             const source = readFileSync(report.filePath, 'utf-8');
             const unsuppressedCandidates = [...report.findings, ...(report.suppressedFindings ?? [])];
+            assignDefaultConfidence(unsuppressedCandidates);
+            applyRuleQualityCalibration(unsuppressedCandidates, config);
             const suppression = applySuppression(sortAndDedup(unsuppressedCandidates), source, report.filePath, config, config?.strict ?? false);
             report.findings = sortAndDedup(suppression.findings);
             report.suppressedFindings = suppression.suppressed.length > 0 ? sortAndDedup(suppression.suppressed) : undefined;
@@ -1022,6 +1192,35 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             report.findings = sortAndDedup(report.findings);
         }
     }
+    // Universal canonical → display remap. Multiple graph-aware rules
+    // (use-client-drilled-too-high, missing-use-client, server-hook,
+    // next-client-api-in-server, …) emit findings whose `relatedSpans`
+    // reference cross-file paths sourced from cgProject SourceFiles —
+    // those paths are canonical (red-team #9 fix). Walk every finding
+    // once and translate canonical paths back to the caller-facing
+    // display via the graph's display index. Cheap: O(findings * spans)
+    // with a pre-built Map; symmetric across all rules without each one
+    // needing to know about the canonicalisation invariant.
+    const canonicalToDisplayFinal = new Map();
+    for (const gf of graph.files) {
+        canonicalToDisplayFinal.set(gf.canonicalPath, gf.path);
+    }
+    if (canonicalToDisplayFinal.size > 0) {
+        for (const report of reports) {
+            for (const f of report.findings) {
+                const displayPrimary = canonicalToDisplayFinal.get(f.primarySpan.file);
+                if (displayPrimary)
+                    f.primarySpan.file = displayPrimary;
+                if (f.relatedSpans) {
+                    for (const rs of f.relatedSpans) {
+                        const display = canonicalToDisplayFinal.get(rs.file);
+                        if (display)
+                            rs.file = display;
+                    }
+                }
+            }
+        }
+    }
     // Merge graph-level health into every report. Each report may already carry per-file health
     // (e.g. fs-project fallback); fold those entries into the graph builder so every report sees
     // the complete, deduped picture before we emit.
@@ -1035,35 +1234,54 @@ export function reviewGraph(entryFiles, config, graphOptions) {
     }
     return reports;
 }
-function collectReviewableFiles(dirPath, recursive) {
+function collectReviewableFiles(dirPath, recursive, ctx) {
     const files = [];
+    // Hardcoded skips for directories that are never useful to descend into,
+    // even if a tracked file lives inside them. ProjectContext.isReviewable
+    // handles the gitignore-vs-tracked logic for files we DO descend into.
+    const HARD_SKIP_DIRS = new Set(['node_modules', '__pycache__', '.venv', 'venv']);
     for (const entry of readdirSync(dirPath)) {
         const full = join(dirPath, entry);
         const stat = statSync(full);
-        if (stat.isDirectory() &&
-            recursive &&
-            !entry.startsWith('.') &&
-            entry !== 'node_modules' &&
-            entry !== 'dist' &&
-            entry !== '__pycache__' &&
-            entry !== '.venv' &&
-            entry !== 'venv') {
-            files.push(...collectReviewableFiles(full, true));
+        if (stat.isDirectory()) {
+            if (!recursive)
+                continue;
+            if (entry.startsWith('.') || HARD_SKIP_DIRS.has(entry))
+                continue;
+            // Honor .gitignore at the directory level only if NO tracked file lives
+            // inside it (cheap check via path prefix on the tracked set).
+            if (ctx && isPathIgnored(full, ctx) && !directoryHasTrackedDescendant(full, ctx))
+                continue;
+            files.push(...collectReviewableFiles(full, true, ctx));
+            continue;
         }
-        else if (stat.isFile() &&
-            (entry.endsWith('.ts') || entry.endsWith('.tsx')) &&
+        if (!stat.isFile())
+            continue;
+        const isReviewableExt = ((entry.endsWith('.ts') || entry.endsWith('.tsx')) &&
             !entry.endsWith('.d.ts') &&
             !entry.endsWith('.test.ts') &&
-            !entry.endsWith('.test.tsx')) {
-            files.push(full);
-        }
-        else if (stat.isFile() && entry.endsWith('.py') && !entry.startsWith('test_') && !entry.endsWith('_test.py')) {
-            files.push(full);
-        }
-        else if (stat.isFile() && entry.endsWith('.kern')) {
-            files.push(full);
-        }
+            !entry.endsWith('.test.tsx')) ||
+            (entry.endsWith('.py') && !entry.startsWith('test_') && !entry.endsWith('_test.py')) ||
+            entry.endsWith('.kern');
+        if (!isReviewableExt)
+            continue;
+        // Skip-list: gitignored AND not tracked. Tracked-but-gitignored files
+        // (e.g. checked-in dist/*.gen.ts) remain reviewable — Phase 1 red-team #4.
+        if (ctx && !isReviewable(full, ctx))
+            continue;
+        files.push(full);
     }
     return files;
 }
+function directoryHasTrackedDescendant(dirAbsPath, ctx) {
+    const rel = relative(ctx.root, dirAbsPath).split(sep).join('/');
+    if (!rel || rel.startsWith('..'))
+        return false;
+    const prefix = rel.endsWith('/') ? rel : `${rel}/`;
+    for (const tracked of ctx.gitTrackedFiles) {
+        if (tracked.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=index.js.map