@kernlang/review 3.2.3 → 3.3.5

package/dist/index.js

@@ -10,7 +10,8 @@
  */
 import { countTokens, parseWithDiagnostics, serializeIR } from '@kernlang/core';
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
-import { join, relative } from 'path';
+import { dirname, join, relative } from 'path';
+import { Project } from 'ts-morph';
 import { buildCallGraph } from './call-graph.js';
 import { runConceptRules } from './concept-rules/index.js';
 import { structuralDiff } from './differ.js';
@@ -18,19 +19,22 @@ import { runTSCDiagnostics } from './external-tools.js';
 import { buildFileContextMap } from './file-context.js';
 import { classifyFileRole } from './file-role.js';
 import { resolveImportGraph } from './graph.js';
-import { createInMemoryProject, inferFromSourceFile } from './inferrer.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 { buildPublicApiMap, expandPublicApiThroughReExports } from './public-api.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 { lintConfidenceGraph } from './rules/confidence.js';
+import { lintConfidenceGraph, lintMultiFileConfidenceGraph } from './rules/confidence.js';
 import { crossFileAsyncRule, deadExportRule } from './rules/dead-code.js';
 import { runFastapiConceptRules } from './rules/fastapi.js';
 import { GROUND_LAYER_RULES } from './rules/ground-layer.js';
-import { KERN_SOURCE_RULES, lintKernSourceIR } from './rules/kern-source.js';
+import { KERN_SOURCE_RULES, lintKernSourceIR, missingConfidence } from './rules/kern-source.js';
+import { lintKernSourceCrossFile } from './rules/kern-source-cross-file.js';
 import { detectTemplates } from './template-detector.js';
 // Load native .kern rules once at module init
 // Guard: import.meta.url is undefined when bundled as CJS (e.g. esbuild for VS Code worker)
@@ -54,7 +58,7 @@ export { linkToNodes, runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths }
 export { buildFileContextMap, clearFileContextCache } from './file-context.js';
 export { classifyFileRole } from './file-role.js';
 export { resolveImportGraph } from './graph.js';
-export { inferFromFile, inferFromSource } from './inferrer.js';
+export { findTsConfig, inferFromFile, inferFromSource } from './inferrer.js';
 // KERN-IR lint pipeline (ground layer)
 export { flattenIR, lintKernIR } from './kern-lint.js';
 // LLM bridge (Phase 3)
@@ -64,8 +68,10 @@ export { extractTsConcepts } from './mappers/ts-concepts.js';
 // Norm mining + obligations
 export { mineNorms } from './norm-miner.js';
 export { obligationsFromNorms, obligationsFromStructure, synthesizeObligations } from './obligations.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, formatSARIFWithSuppressions, formatSummary, sortAndDedup, sortFindings, } from './reporter.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 { 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';
@@ -87,27 +93,155 @@ export { checkSpec, checkSpecFiles, extractImplRoutes, extractSpecContracts, mat
 export { clearReviewCache };
 /** Shared filesystem-backed Project for type-aware analysis (reused across reviewFile calls) */
 let _fsProject;
-function getOrCreateFsProject() {
+let _fsProjectTsConfig;
+let _fsProjectTsConfigMtimeMs;
+function getOrCreateFsProject(tsConfigFilePath) {
+    // Rebuild when either the tsconfig path OR its contents change. Watch-mode users who edit
+    // compilerOptions in place would otherwise keep running with the stale Project's resolver even
+    // though the cache key (which hashes tsconfig content) correctly invalidates — the two must stay
+    // consistent or findings lag a process restart behind.
+    let currentMtime;
+    if (tsConfigFilePath) {
+        try {
+            currentMtime = statSync(tsConfigFilePath).mtimeMs;
+        }
+        catch {
+            // Unreadable tsconfig — fall through; we'll still attempt construction and let ts-morph surface the error.
+        }
+    }
+    if (_fsProject && (_fsProjectTsConfig !== tsConfigFilePath || _fsProjectTsConfigMtimeMs !== currentMtime)) {
+        _fsProject = undefined;
+    }
     if (!_fsProject) {
-        const { Project } = require('ts-morph');
         _fsProject = new Project({
-            compilerOptions: {
-                strict: true,
-                target: 99 /* Latest */,
-                module: 99 /* ESNext */,
-                moduleResolution: 100 /* Bundler */,
-                skipLibCheck: true,
-                noEmit: true,
-            },
-            useInMemoryFileSystem: false,
+            tsConfigFilePath,
             skipAddingFilesFromTsConfig: true,
+            useInMemoryFileSystem: false,
+            // When a tsconfig is loaded, let it own compilerOptions (jsx/paths/lib/allowJs come from there).
+            // When no tsconfig, ship permissive defaults so .tsx files don't emit phantom ts17004 errors.
+            compilerOptions: tsConfigFilePath
+                ? undefined
+                : {
+                    strict: true,
+                    target: 99 /* Latest */,
+                    module: 99 /* ESNext */,
+                    moduleResolution: 100 /* Bundler */,
+                    jsx: 4 /* Preserve */,
+                    allowJs: true,
+                    esModuleInterop: true,
+                    allowSyntheticDefaultImports: true,
+                    skipLibCheck: true,
+                    noEmit: true,
+                },
         });
+        _fsProjectTsConfig = tsConfigFilePath;
+        _fsProjectTsConfigMtimeMs = currentMtime;
     }
     return _fsProject;
 }
 /** Reset the shared project (for tests / watch mode) */
 export function resetFsProject() {
     _fsProject = undefined;
+    _fsProjectTsConfig = undefined;
+    _fsProjectTsConfigMtimeMs = undefined;
+    _fsProjectSourceMtimes.clear();
+}
+/**
+ * Refresh stale source files in the shared fs Project from disk.
+ *
+ * The singleton caches every source file it has ever loaded — including transitive imports
+ * followed by cross-file taint and call-graph analysis. In a long-running process (watch mode,
+ * IDE extension, repeated CLI invocations) those cached ASTs go stale whenever the underlying
+ * file changes on disk outside our own `replaceWithText` path. Cross-file findings would then
+ * reflect the OLD imported source, not the current one.
+ *
+ * This helper is the lightweight counterpart to resetFsProject(): instead of throwing the
+ * whole Project away, it stat-checks each loaded source file and calls ts-morph's
+ * refreshFromFileSystemSync only on the ones whose mtime moved. Use it between reviews in
+ * watch-mode callers. One-shot CLI runs don't need it — the process exits before stale
+ * reads matter.
+ *
+ * Returns the number of source files actually refreshed, so callers can log "reloaded N
+ * files" or decide not to re-review when the count is zero.
+ */
+export function refreshFsProjectFromDisk() {
+    if (!_fsProject)
+        return 0;
+    let refreshed = 0;
+    for (const sf of _fsProject.getSourceFiles()) {
+        const path = sf.getFilePath();
+        let diskMtime;
+        try {
+            diskMtime = statSync(path).mtimeMs;
+        }
+        catch {
+            // File deleted on disk since it was loaded — skip. ts-morph will raise on next access.
+            continue;
+        }
+        const lastKnown = _fsProjectSourceMtimes.get(path);
+        if (lastKnown === diskMtime)
+            continue;
+        try {
+            sf.refreshFromFileSystemSync();
+            _fsProjectSourceMtimes.set(path, diskMtime);
+            refreshed++;
+        }
+        catch {
+            // Refresh can fail for unreadable/unparseable files — leave the stale copy rather than
+            // hard-crashing the review. The next resetFsProject() call will clear it either way.
+        }
+    }
+    return refreshed;
+}
+/** Per-file mtimes tracked for the shared fs Project — see refreshFsProjectFromDisk. */
+const _fsProjectSourceMtimes = new Map();
+/** True when the file is codegen output — detected via common path patterns or a @generated header. */
+export function isGeneratedFile(filePath, source) {
+    // Path heuristic — covers /generated/, /__generated__/, /.generated/ anywhere in the path.
+    if (/[/\\](?:generated|__generated__|\.generated)[/\\]/i.test(filePath))
+        return true;
+    // Leading `// @generated` or `/* @generated */` header — the standard convention enforced by many codegens.
+    if (source && /^\s*(?:\/\/|\/\*)\s*@generated\b/m.test(source.slice(0, 500)))
+        return true;
+    return false;
+}
+/** Extensions the review engine analyzes. Anything else (.md, .json, .yaml, .patch, binaries) returns an empty report at the entry point, so callers that blindly feed changed-file lists (e.g. kern-guard on a PR diff) don't surface noise findings on docs/config files. */
+const REVIEWABLE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.kern',
+    '.py',
+    '.vue',
+]);
+export function isReviewableFile(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    if (dot === -1)
+        return false;
+    const ext = filePath.slice(dot);
+    return REVIEWABLE_EXTENSIONS.has(ext);
+}
+function emptyReport(filePath) {
+    return {
+        filePath,
+        inferred: [],
+        templateMatches: [],
+        findings: [],
+        stats: {
+            totalLines: 0,
+            coveredLines: 0,
+            coveragePct: 0,
+            totalTsTokens: 0,
+            totalKernTokens: 0,
+            reductionPct: 0,
+            constructCount: 0,
+        },
+    };
 }
 /**
  * Review a single file. Auto-detects language from extension.
@@ -115,24 +249,53 @@ export function resetFsProject() {
  * Supports: .ts, .tsx, .py, .kern
  */
 export function reviewFile(filePath, config) {
+    if (!isReviewableFile(filePath))
+        return emptyReport(filePath);
     const source = readFileSync(filePath, 'utf-8');
+    // Resolve the effective tsconfig up-front so both the cache key and the ts-morph Project see the
+    // same path. If we only discovered it later inside reviewSourceWithProject, adding or changing the
+    // nearest tsconfig without editing the source would serve stale cached findings.
+    const effectiveConfig = config?.tsConfigFilePath || filePath.endsWith('.kern') || filePath.endsWith('.py')
+        ? config
+        : { ...(config ?? {}), tsConfigFilePath: findTsConfig(dirname(filePath)) };
     let key;
-    if (config?.noCache !== true) {
-        key = computeCacheKey(source, config || {}, filePath);
+    if (effectiveConfig?.noCache !== true) {
+        key = computeCacheKey(source, effectiveConfig || {}, filePath);
         const cached = reviewCache.get(key);
         if (cached)
             return cached;
     }
     let report;
     if (filePath.endsWith('.kern')) {
-        report = reviewKernSource(source, filePath, config);
+        report = reviewKernSource(source, filePath, effectiveConfig);
     }
     else if (filePath.endsWith('.py')) {
-        report = reviewPythonSource(source, filePath, config);
+        report = reviewPythonSource(source, filePath, effectiveConfig);
     }
-    else {
+    else if (/\.(ts|tsx|js|jsx|mts|cts|mjs|cjs)$/.test(filePath)) {
         // Use filesystem-backed project for real files (enables TypeChecker)
-        report = reviewSourceWithProject(source, filePath, config);
+        report = reviewSourceWithProject(source, filePath, effectiveConfig);
+    }
+    else {
+        // Non-source file (markdown, JSON, patch, yaml, etc.) — skip review entirely
+        return {
+            filePath,
+            inferred: [],
+            templateMatches: [],
+            findings: [],
+            stats: {
+                totalLines: source.split('\n').length,
+                coveredLines: 0,
+                coveragePct: 0,
+                totalTsTokens: 0,
+                totalKernTokens: 0,
+                reductionPct: 0,
+                constructCount: 0,
+            },
+        };
+    }
+    if (isGeneratedFile(filePath, source)) {
+        report.generated = true;
     }
     if (key) {
         reviewCache.set(key, report);
@@ -145,7 +308,11 @@ export function reviewFile(filePath, config) {
  */
 function reviewSourceWithProject(source, filePath, config) {
     try {
-        const fsProject = getOrCreateFsProject();
+        // Prefer explicit override from caller; otherwise discover the nearest tsconfig from this file's directory.
+        // Discovering per-file (not cwd) lets monorepo reviews pick up the per-package tsconfig with real paths/jsx,
+        // instead of the root solution-style tsconfig that only lists `references`.
+        const tsConfigFilePath = config?.tsConfigFilePath ?? findTsConfig(dirname(filePath));
+        const fsProject = getOrCreateFsProject(tsConfigFilePath);
         // Add or update the file in the project
         let sf = fsProject.getSourceFile(filePath);
         if (sf) {
@@ -154,11 +321,29 @@ function reviewSourceWithProject(source, filePath, config) {
         else {
             sf = fsProject.addSourceFileAtPath(filePath);
         }
+        // Track the disk mtime we just synced with — refreshFsProjectFromDisk uses this to decide
+        // whether the cached AST has drifted from disk on later calls. Best-effort: if stat fails
+        // we simply don't record a mtime (refresh will unconditionally refresh such files later).
+        try {
+            _fsProjectSourceMtimes.set(filePath, statSync(filePath).mtimeMs);
+        }
+        catch {
+            // File may have been deleted between read and stat; leave mtime unrecorded.
+        }
         return reviewSourceInternal(source, filePath, config, fsProject, sf);
     }
-    catch {
-        // Fallback to in-memory project if fs project fails
-        return reviewSource(source, filePath, config);
+    catch (err) {
+        // Fs project failed — fall back to in-memory project, but record the degradation on the
+        // report so callers can tell this file was reviewed without full type resolution.
+        const report = reviewSource(source, filePath, config);
+        const health = new ReviewHealthBuilder();
+        for (const e of report.health?.entries ?? [])
+            health.note(e);
+        health.noteKind('fs-project', 'fallback', 'Fell back to in-memory ts-morph project — cross-module type resolution is limited for this file', debugDetail(err));
+        if (process.env.KERN_DEBUG)
+            console.error('fs-project failure, using in-memory fallback:', err.message);
+        report.health = health.build();
+        return report;
     }
 }
 /**
@@ -166,6 +351,8 @@ function reviewSourceWithProject(source, filePath, config) {
  * For file-from-disk review with type resolution, use reviewFile() instead.
  */
 export function reviewSource(source, filePath = 'input.ts', config) {
+    if (!isReviewableFile(filePath))
+        return emptyReport(filePath);
     const project = createInMemoryProject();
     const sourceFile = project.createSourceFile(filePath, source);
     return reviewSourceInternal(source, filePath, config, project, sourceFile);
@@ -204,8 +391,12 @@ function reviewSourceInternal(source, filePath, config, project, sourceFile) {
     }, []));
     // Phase 3: Template detection (config-aware)
     const templateMatches = safePhase('templates', () => detectTemplates(sourceFile, config), []);
-    // Phase 4: Structural diff → unified findings
-    allFindings.push(...safePhase('diff', () => structuralDiff(source, inferred, filePath), []));
+    // Phase 4: Structural diff → unified findings.
+    // `extra-code` and `inconsistent-pattern` are only meaningful on runtime source; on codegen/barrel/test/example
+    // files they produce noise (e.g. entire barrel flagged as extra-code). Keep other diff findings regardless.
+    const diffFindings = safePhase('diff', () => structuralDiff(source, inferred, filePath), []);
+    const diffNoiseRules = new Set(['extra-code', 'inconsistent-pattern']);
+    allFindings.push(...(fileRole === 'runtime' ? diffFindings : diffFindings.filter((f) => !diffNoiseRules.has(f.ruleId))));
     // Phase 5: Quality rules → unified findings (receives fileRole)
     allFindings.push(...safePhase('quality', () => runQualityRules(sourceFile, inferred, templateMatches, config, fileRole, project), []));
     // Phase 6: Concept extraction + concept rules (universal, cross-language)
@@ -241,8 +432,15 @@ function reviewSourceInternal(source, filePath, config, project, sourceFile) {
         }
         allFindings.push(...nativeFindings);
     }
-    // Phase 8: TSC diagnostics — native TypeScript compiler errors
-    allFindings.push(...safePhase('tsc', () => runTSCDiagnostics(project), []));
+    // Phase 8: TSC diagnostics — native TypeScript compiler errors.
+    // runTSCDiagnostics returns findings for every file in the shared Project, so filter down to
+    // just the file we're reviewing — otherwise findings-for-project-file leaks into unrelated reports.
+    // ts-morph normalizes filePaths (absolute, posix separators) while callers may pass relative paths,
+    // so compare against the sourceFile's own normalized path rather than the raw argument.
+    // downgradeProjectLoadingErrors: we injected this file ad-hoc into a Project that carries the
+    // host tsconfig, so TS6059/TS6307 are our noise, not the user's bug.
+    const normalizedCurrentPath = sourceFile.getFilePath();
+    allFindings.push(...safePhase('tsc', () => runTSCDiagnostics(project, { downgradeProjectLoadingErrors: true }), []).filter((f) => f.primarySpan.file === normalizedCurrentPath || f.primarySpan.file === filePath));
     // Build confidence graph if any nodes have confidence props
     let confidenceGraph;
     let confidenceSummary;
@@ -266,6 +464,7 @@ function reviewSourceInternal(source, filePath, config, project, sourceFile) {
         inferred,
         templateMatches,
         findings,
+        ...(suppression.suppressed.length > 0 ? { suppressedFindings: sortAndDedup(suppression.suppressed) } : {}),
         stats,
         ...(confidenceGraph ? { confidenceGraph } : {}),
         ...(confidenceSummary ? { confidenceSummary } : {}),
@@ -333,8 +532,13 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
                 f.primarySpan.file = filePath;
         }
         allFindings.push(...confFindings);
-        // File-aware .kern review rules on flattened IR nodes
-        const kernSourceFindings = safePhase('kern-source-lint', () => lintKernSourceIR(flatNodes, filePath, KERN_SOURCE_RULES), []);
+        // File-aware .kern review rules on flattened IR nodes.
+        // missing-confidence fires only when the user opts into confidence annotations — defaulting
+        // it on produced noise for every .kern file that didn't use the feature (see Agon kern-guard run, 2026-04-19).
+        const kernSourceRules = _config?.requireConfidenceAnnotations
+            ? KERN_SOURCE_RULES
+            : KERN_SOURCE_RULES.filter((r) => r !== missingConfidence);
+        const kernSourceFindings = safePhase('kern-source-lint', () => lintKernSourceIR(flatNodes, filePath, kernSourceRules), []);
         allFindings.push(...kernSourceFindings);
         // Native .kern rules (built-in + custom)
         const rulesToRunKern = [...NATIVE_RULES];
@@ -399,6 +603,7 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         inferred,
         templateMatches: [],
         findings,
+        ...(suppression.suppressed.length > 0 ? { suppressedFindings: sortAndDedup(suppression.suppressed) } : {}),
         stats: {
             totalLines,
             coveredLines: totalLines,
@@ -462,6 +667,7 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
         inferred: [],
         templateMatches: [],
         findings,
+        ...(suppression.suppressed.length > 0 ? { suppressedFindings: sortAndDedup(suppression.suppressed) } : {}),
         stats: {
             totalLines,
             coveredLines: 0,
@@ -497,9 +703,13 @@ export function reviewGraph(entryFiles, config, graphOptions) {
     const graph = resolveImportGraph(entryFiles, graphOptions);
     const entrySet = new Set(graph.entryFiles);
     const reports = [];
+    // Graph-wide subsystem status — one entry per (subsystem, kind) across the whole run.
+    // Attached to every report on return so any single ReviewReport is self-describing.
+    const graphHealth = new ReviewHealthBuilder();
     // Build file context map — every file gets import chain awareness
     const fileContextMap = buildFileContextMap(graph);
-    const graphConfig = { ...config, fileContextMap };
+    const graphFileMap = new Map(graph.files.map((gf) => [gf.path, gf]));
+    const graphConfig = { ...config, fileContextMap, graphFileMap };
     for (const gf of graph.files) {
         if (!existsSync(gf.path))
             continue;
@@ -518,8 +728,14 @@ export function reviewGraph(entryFiles, config, graphOptions) {
                     }
                 }
             }
+            for (const f of report.suppressedFindings ?? []) {
+                f.origin = isEntry ? 'changed' : 'upstream';
+                f.distance = gf.distance;
+            }
             // Re-sort after severity mutations
             sortFindings(report.findings);
+            if (report.suppressedFindings)
+                sortFindings(report.suppressedFindings);
             reports.push(report);
         }
         catch (err) {
@@ -535,7 +751,7 @@ export function reviewGraph(entryFiles, config, graphOptions) {
     for (const gf of graph.files) {
         graphImports.set(gf.path, gf.imports);
     }
-    const crossFileResults = analyzeTaintCrossFile(inferredPerFile, graphImports);
+    const crossFileResults = analyzeTaintCrossFile(inferredPerFile, graphImports, graph);
     if (crossFileResults.length > 0) {
         const crossFileFindings = crossFileTaintToFindings(crossFileResults);
         // Add cross-file findings to the caller's report, then re-run suppression
@@ -555,6 +771,32 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             }
         }
     }
+    // Cross-file confidence analysis for KERN IR nodes across the reviewed graph.
+    const confidenceFileMap = new Map();
+    for (const report of reports) {
+        if (!report.filePath.endsWith('.kern'))
+            continue;
+        const nodes = report.inferred.map((r) => r.node);
+        if (nodes.length > 0) {
+            confidenceFileMap.set(report.filePath, nodes);
+        }
+    }
+    if (confidenceFileMap.size > 1) {
+        const crossFileConfidenceFindings = lintMultiFileConfidenceGraph(confidenceFileMap);
+        for (const finding of crossFileConfidenceFindings) {
+            const targetReport = reports.find((r) => r.filePath === finding.primarySpan.file);
+            if (targetReport) {
+                targetReport.findings.push(finding);
+            }
+        }
+    }
+    const crossFileKernFindings = lintKernSourceCrossFile(reports);
+    for (const finding of crossFileKernFindings) {
+        const targetReport = reports.find((r) => r.filePath === finding.primarySpan.file);
+        if (targetReport) {
+            targetReport.findings.push(finding);
+        }
+    }
     // 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();
@@ -568,8 +810,11 @@ export function reviewGraph(entryFiles, config, graphOptions) {
                 allConcepts.set(filePath, extractTsConcepts(sf, filePath));
             }
         }
-        catch {
-            // Skip files that fail concept extraction
+        catch (err) {
+            // Per-file failure — record once at graph level (builder dedupes), then move on.
+            graphHealth.noteKind('concept-extraction', 'fallback', 'One or more files failed concept extraction — boundary/effect rules may be incomplete', debugDetail(err));
+            if (process.env.KERN_DEBUG)
+                console.error(`concept extraction failed for ${filePath}:`, err.message);
         }
     }
     if (allConcepts.size > 0) {
@@ -602,11 +847,25 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         // Use provided project, or build one with all graph files loaded
         let cgProject = graphOptions?.project;
         if (!cgProject) {
-            const { Project } = require('ts-morph');
+            // Fall back to discovering from the first graph file when the caller didn't supply a tsconfig.
+            const cgTsConfig = graphOptions?.tsConfigFilePath ?? (graph.files[0] ? findTsConfig(dirname(graph.files[0].path)) : undefined);
             cgProject = new Project({
-                compilerOptions: { strict: true, target: 99, module: 99, moduleResolution: 100, skipLibCheck: true },
-                useInMemoryFileSystem: false,
+                tsConfigFilePath: cgTsConfig,
                 skipAddingFilesFromTsConfig: true,
+                useInMemoryFileSystem: false,
+                compilerOptions: cgTsConfig
+                    ? undefined
+                    : {
+                        strict: true,
+                        target: 99,
+                        module: 99,
+                        moduleResolution: 100,
+                        jsx: 4 /* Preserve */,
+                        allowJs: true,
+                        esModuleInterop: true,
+                        allowSyntheticDefaultImports: true,
+                        skipLibCheck: true,
+                    },
             });
             for (const gf of graph.files) {
                 try {
@@ -618,27 +877,49 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             }
         }
         const callGraph = buildCallGraph(graph, cgProject);
+        // 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));
         for (const report of reports) {
-            const deadExportFindings = deadExportRule(callGraph, report.filePath);
+            const deadExportFindings = deadExportRule(callGraph, report.filePath, publicApi);
             report.findings.push(...deadExportFindings);
             const asyncFindings = crossFileAsyncRule(callGraph, report.filePath);
             report.findings.push(...asyncFindings);
         }
     }
-    catch {
-        // Call graph build failure should not crash the review pipeline
+    catch (err) {
+        // Call graph build failure must not crash the review pipeline — surface the failure on
+        // health so dead-export / cross-file-async rules aren't silently missing from the report.
+        graphHealth.noteKind('call-graph', 'error', 'Call graph build failed — dead exports and cross-file async checks are unavailable', debugDetail(err));
+        if (process.env.KERN_DEBUG)
+            console.error('call graph build error:', err.message);
     }
     // Re-run suppression + dedup on all reports (cross-file findings were injected after initial suppression)
     for (const report of reports) {
         try {
             const source = readFileSync(report.filePath, 'utf-8');
-            const suppression = applySuppression(report.findings, source, report.filePath, config, config?.strict ?? false);
+            const unsuppressedCandidates = [...report.findings, ...(report.suppressedFindings ?? [])];
+            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;
         }
         catch {
             report.findings = sortAndDedup(report.findings);
         }
     }
+    // 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.
+    for (const report of reports) {
+        const merged = new ReviewHealthBuilder();
+        for (const e of report.health?.entries ?? [])
+            merged.note(e);
+        for (const e of graphHealth.build()?.entries ?? [])
+            merged.note(e);
+        report.health = merged.build();
+    }
     return reports;
 }
 function collectReviewableFiles(dirPath, recursive) {
@@ -656,16 +937,17 @@ function collectReviewableFiles(dirPath, recursive) {
             entry !== 'venv') {
             files.push(...collectReviewableFiles(full, true));
         }
-        else if ((entry.endsWith('.ts') || entry.endsWith('.tsx')) &&
+        else if (stat.isFile() &&
+            (entry.endsWith('.ts') || entry.endsWith('.tsx')) &&
             !entry.endsWith('.d.ts') &&
             !entry.endsWith('.test.ts') &&
             !entry.endsWith('.test.tsx')) {
             files.push(full);
         }
-        else if (entry.endsWith('.py') && !entry.startsWith('test_') && !entry.endsWith('_test.py')) {
+        else if (stat.isFile() && entry.endsWith('.py') && !entry.startsWith('test_') && !entry.endsWith('_test.py')) {
             files.push(full);
         }
-        else if (entry.endsWith('.kern')) {
+        else if (stat.isFile() && entry.endsWith('.kern')) {
             files.push(full);
         }
     }