@kernlang/review 3.1.6 → 3.1.7

package/dist/index.js

@@ -8,25 +8,30 @@
  *
  * v2: Unified ReviewFinding pipeline. All findings merged into single array.
  */
-import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
-import { relative, join } from 'path';
-import { parseWithDiagnostics, countTokens, serializeIR } from '@kernlang/core';
-import { inferFromSourceFile, createInMemoryProject } from './inferrer.js';
-import { resolveImportGraph } from './graph.js';
-import { detectTemplates } from './template-detector.js';
+import { countTokens, parseWithDiagnostics, serializeIR } from '@kernlang/core';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import { buildCallGraph } from './call-graph.js';
+import { runConceptRules } from './concept-rules/index.js';
 import { structuralDiff } from './differ.js';
-import { runQualityRules } from './quality-rules.js';
-import { calculateStats, sortAndDedup, sortFindings } from './reporter.js';
-import { classifyFileRole } from './file-role.js';
 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 { flattenIR, lintKernIR } from './kern-lint.js';
 import { extractTsConcepts } from './mappers/ts-concepts.js';
-import { runConceptRules } from './concept-rules/index.js';
-import { lintConfidenceGraph } from './rules/confidence.js';
-import { lintKernIR, flattenIR } from './kern-lint.js';
+import { mineNorms } from './norm-miner.js';
+import { synthesizeObligations } from './obligations.js';
+import { runQualityRules } from './quality-rules.js';
+import { assignDefaultConfidence, calculateStats, sortAndDedup, sortFindings } from './reporter.js';
 import { loadBuiltinNativeRules, loadNativeRules } from './rule-loader.js';
-import { lintKernSourceIR, KERN_SOURCE_RULES } from './rules/kern-source.js';
-import { GROUND_LAYER_RULES } from './rules/ground-layer.js';
+import { lintConfidenceGraph } 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 { 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)
 let NATIVE_RULES = [];
@@ -36,46 +41,77 @@ try {
 catch {
     // CJS bundle — native .kern rules not available, regex rules still work
 }
-import { buildConfidenceGraph, serializeGraph, computeConfidenceSummary } from './confidence.js';
-import { analyzeTaint, taintToFindings, analyzeTaintCrossFile, crossFileTaintToFindings } from './taint.js';
+import { buildConfidenceGraph, computeConfidenceSummary, serializeGraph } from './confidence.js';
 import { applySuppression } from './suppression/index.js';
+import { analyzeTaint, analyzeTaintCrossFile, crossFileTaintToFindings, taintToFindings } from './taint.js';
 import { createFingerprint } from './types.js';
-export { resolveImportGraph } from './graph.js';
-export { createFingerprint } from './types.js';
-export { inferFromSource, inferFromFile } from './inferrer.js';
-export { classifyFileRole } from './file-role.js';
-export { detectTemplates } from './template-detector.js';
+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 { linkToNodes, runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths } from './external-tools.js';
+export { buildFileContextMap, clearFileContextCache } from './file-context.js';
+export { classifyFileRole } from './file-role.js';
+export { resolveImportGraph } from './graph.js';
+export { inferFromFile, inferFromSource } from './inferrer.js';
+// KERN-IR lint pipeline (ground layer)
+export { flattenIR, lintKernIR } from './kern-lint.js';
+// LLM bridge (Phase 3)
+export { buildReviewInstructions, isLLMAvailable, runLLMReview } from './llm-bridge.js';
+export { buildLLMPrompt, exportKernIR, parseLLMResponse } from './llm-review.js';
+export { extractTsConcepts } from './mappers/ts-concepts.js';
+// Norm mining + obligations
+export { mineNorms } from './norm-miner.js';
+export { obligationsFromNorms, obligationsFromStructure, synthesizeObligations } from './obligations.js';
 export { runQualityRules } from './quality-rules.js';
+export { assignDefaultConfidence, calculateStats, checkEnforcement, dedup, formatEnforcement, formatReport, formatReportJSON, formatSARIF, formatSARIFWithSuppressions, formatSummary, sortAndDedup, sortFindings, } from './reporter.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';
-export { calculateStats, formatReport, formatReportJSON, formatSARIF, formatSARIFWithSuppressions, formatSummary, checkEnforcement, formatEnforcement, dedup, sortAndDedup, sortFindings } from './reporter.js';
-export { exportKernIR, buildLLMPrompt, parseLLMResponse } from './llm-review.js';
-export { runESLint, runTSCDiagnostics, runTSCDiagnosticsFromPaths, linkToNodes } from './external-tools.js';
-export { extractTsConcepts } from './mappers/ts-concepts.js';
-export { runConceptRules } from './concept-rules/index.js';
-// Suppression
-export { applySuppression, parseDirectives, configDirectives, isConceptRule } from './suppression/index.js';
-// KERN-IR lint pipeline (ground layer)
-export { lintKernIR, flattenIR } from './kern-lint.js';
-export { GROUND_LAYER_RULES } from './rules/ground-layer.js';
-export { lintKernSourceIR, KERN_SOURCE_RULES, undefinedReference, typeModelMismatch, unusedState, handlerHeavy, missingConfidence } from './rules/kern-source.js';
-export { guardWithoutElse, actionMissingIdempotent, branchNonExhaustive, collectUnbounded, reasonWithoutBasis, assumeLowTrust, expectRangeInverted, } from './rules/ground-layer.js';
-// Confidence layer
-export { parseConfidence, buildConfidenceGraph, buildMultiFileConfidenceGraph, propagateConfidence, resolveBaseConfidence, serializeGraph, computeConfidenceSummary, } from './confidence.js';
-export { lintConfidenceGraph, lintMultiFileConfidenceGraph, CONFIDENCE_RULES } from './rules/confidence.js';
+export { handlerHeavy, KERN_SOURCE_RULES, lintKernSourceIR, missingConfidence, typeModelMismatch, undefinedReference, unusedState, } from './rules/kern-source.js';
 // ReDoS detection (reusable by rule compilers)
 export { isReDoSVulnerable } from './rules/security-v3.js';
+// Semantic diff
+export { computeSemanticDiff, computeSemanticDiffFromSource, formatSemanticDiff, getOldFileContent, semanticChangesToFindings, } from './semantic-diff.js';
+// Suppression
+export { applySuppression, configDirectives, isConceptRule, parseDirectives } from './suppression/index.js';
 // Taint tracking (Phase 2 + cross-file)
-export { analyzeTaint, taintToFindings, analyzeTaintCrossFile, crossFileTaintToFindings, buildExportMap, buildImportMap, isSanitizerSufficient } from './taint.js';
-// LLM bridge (Phase 3)
-export { runLLMReview, isLLMAvailable } from './llm-bridge.js';
+export { analyzeTaint, analyzeTaintCrossFile, buildExportMap, buildImportMap, crossFileTaintToFindings, isSanitizerSufficient, taintToFindings, } from './taint.js';
+export { detectTemplates } from './template-detector.js';
+export { createFingerprint } from './types.js';
 // Cache (Phase 0)
-import { computeCacheKey, reviewCache, clearReviewCache } from './cache.js';
-export { clearReviewCache };
+import { clearReviewCache, computeCacheKey, reviewCache } from './cache.js';
 // Spec checker — .kern contract vs .ts implementation
-export { checkSpec, checkSpecFiles, extractSpecContracts, extractImplRoutes, matchRoutes, verifyRouteContract, specViolationsToFindings } from './spec-checker.js';
+export { checkSpec, checkSpecFiles, extractImplRoutes, extractSpecContracts, matchRoutes, specViolationsToFindings, verifyRouteContract, } from './spec-checker.js';
+export { clearReviewCache };
+/** Shared filesystem-backed Project for type-aware analysis (reused across reviewFile calls) */
+let _fsProject;
+function getOrCreateFsProject() {
+    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,
+            skipAddingFilesFromTsConfig: true,
+        });
+    }
+    return _fsProject;
+}
+/** Reset the shared project (for tests / watch mode) */
+export function resetFsProject() {
+    _fsProject = undefined;
+}
 /**
  * Review a single file. Auto-detects language from extension.
+ * Uses a filesystem-backed ts-morph Project for type-aware analysis.
  * Supports: .ts, .tsx, .py, .kern
  */
 export function reviewFile(filePath, config) {
@@ -95,7 +131,8 @@ export function reviewFile(filePath, config) {
         report = reviewPythonSource(source, filePath, config);
     }
     else {
-        report = reviewSource(source, filePath, config);
+        // Use filesystem-backed project for real files (enables TypeChecker)
+        report = reviewSourceWithProject(source, filePath, config);
     }
     if (key) {
         reviewCache.set(key, report);
@@ -103,13 +140,41 @@ export function reviewFile(filePath, config) {
     return report;
 }
 /**
- * Review TypeScript source code (string).
+ * Review TypeScript source with a filesystem-backed project.
+ * The fs project enables .getReturnType() to resolve types from node_modules.
+ */
+function reviewSourceWithProject(source, filePath, config) {
+    try {
+        const fsProject = getOrCreateFsProject();
+        // Add or update the file in the project
+        let sf = fsProject.getSourceFile(filePath);
+        if (sf) {
+            sf.replaceWithText(source);
+        }
+        else {
+            sf = fsProject.addSourceFileAtPath(filePath);
+        }
+        return reviewSourceInternal(source, filePath, config, fsProject, sf);
+    }
+    catch {
+        // Fallback to in-memory project if fs project fails
+        return reviewSource(source, filePath, config);
+    }
+}
+/**
+ * Review TypeScript source code (string). Uses in-memory project (no type resolution).
+ * For file-from-disk review with type resolution, use reviewFile() instead.
  */
 export function reviewSource(source, filePath = 'input.ts', config) {
-    const totalLines = source.split('\n').length;
-    // ── Shared context: single AST parse, shared across all phases ──
     const project = createInMemoryProject();
     const sourceFile = project.createSourceFile(filePath, source);
+    return reviewSourceInternal(source, filePath, config, project, sourceFile);
+}
+/**
+ * Internal review implementation — shared between reviewSource (in-memory) and reviewFile (filesystem).
+ */
+function reviewSourceInternal(source, filePath, config, project, sourceFile) {
+    const totalLines = source.split('\n').length;
     const fileRole = classifyFileRole(sourceFile, filePath);
     // Helper: run a phase safely, collect findings even if a phase throws
     const allFindings = [];
@@ -119,7 +184,10 @@ export function reviewSource(source, filePath = 'input.ts', config) {
         }
         catch (err) {
             allFindings.push({
-                source: 'kern', ruleId: 'internal-error', severity: 'info', category: 'structure',
+                source: 'kern',
+                ruleId: 'internal-error',
+                severity: 'info',
+                category: 'structure',
                 message: `Review phase '${name}' failed: ${err.message}`,
                 primarySpan: { file: filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
                 fingerprint: createFingerprint('internal-error', 1, name.charCodeAt(0)),
@@ -139,13 +207,13 @@ export function reviewSource(source, filePath = 'input.ts', config) {
     // Phase 4: Structural diff → unified findings
     allFindings.push(...safePhase('diff', () => structuralDiff(source, inferred, filePath), []));
     // Phase 5: Quality rules → unified findings (receives fileRole)
-    allFindings.push(...safePhase('quality', () => runQualityRules(sourceFile, inferred, templateMatches, config, fileRole), []));
+    allFindings.push(...safePhase('quality', () => runQualityRules(sourceFile, inferred, templateMatches, config, fileRole, project), []));
     // 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), []));
     // Phase 7: KERN-IR lint (ground layer + confidence rules on inferred nodes)
-    const irNodes = inferred.map(r => r.node);
+    const irNodes = inferred.map((r) => r.node);
     const groundFindings = safePhase('ground-lint', () => lintKernIR(irNodes, GROUND_LAYER_RULES), []);
     for (const f of groundFindings) {
         if (!f.primarySpan.file)
@@ -161,7 +229,7 @@ export function reviewSource(source, filePath = 'input.ts', config) {
     // Phase 7b: Native .kern rules (built-in + custom)
     const rulesToRun = [...NATIVE_RULES];
     if (config?.rulesDirs && config.rulesDirs.length > 0) {
-        const builtinIds = new Set(NATIVE_RULES.map(r => r.ruleId).filter(Boolean));
+        const builtinIds = new Set(NATIVE_RULES.map((r) => r.ruleId).filter(Boolean));
         const customRules = loadNativeRules(config.rulesDirs, builtinIds);
         rulesToRun.push(...customRules);
     }
@@ -178,7 +246,7 @@ export function reviewSource(source, filePath = 'input.ts', config) {
     // Build confidence graph if any nodes have confidence props
     let confidenceGraph;
     let confidenceSummary;
-    const hasConfidence = irNodes.some(n => n.props?.confidence !== undefined);
+    const hasConfidence = irNodes.some((n) => n.props?.confidence !== undefined);
     if (hasConfidence) {
         const graph = buildConfidenceGraph(irNodes);
         confidenceGraph = serializeGraph(graph);
@@ -186,6 +254,8 @@ export function reviewSource(source, filePath = 'input.ts', config) {
     }
     // Merge, dedup, sort — single shared utility
     const dedupedFindings = sortAndDedup(allFindings);
+    // Assign calibrated confidence scores to all findings
+    assignDefaultConfidence(dedupedFindings);
     // Apply suppression (inline comments + config disabledRules)
     const suppression = applySuppression(dedupedFindings, source, filePath, config, config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
@@ -215,7 +285,10 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         }
         catch (err) {
             allFindings.push({
-                source: 'kern', ruleId: 'internal-error', severity: 'info', category: 'structure',
+                source: 'kern',
+                ruleId: 'internal-error',
+                severity: 'info',
+                category: 'structure',
                 message: `Review phase '${name}' failed: ${err.message}`,
                 primarySpan: { file: filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
                 fingerprint: createFingerprint('internal-error', 1, name.charCodeAt(0)),
@@ -224,9 +297,12 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         }
     }
     // Parse .kern → IR tree + structured diagnostics
-    const { root, diagnostics: parseDiags } = safePhase('parse', () => parseWithDiagnostics(source), { root: { type: 'document' }, diagnostics: [] });
+    const { root, diagnostics: parseDiags } = safePhase('parse', () => parseWithDiagnostics(source), {
+        root: { type: 'document' },
+        diagnostics: [],
+    });
     // Map parse diagnostics → ReviewFindings (severity capped at 'warning' unless --strict-parse is enabled)
-    const hasParseErrors = parseDiags.some(d => d.severity === 'error');
+    const hasParseErrors = parseDiags.some((d) => d.severity === 'error');
     for (const d of parseDiags) {
         allFindings.push({
             source: 'kern',
@@ -240,7 +316,7 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         });
     }
     // Flatten IR tree for rule consumption
-    const flatNodes = flattenIR(root).filter(n => n.type !== 'document');
+    const flatNodes = flattenIR(root).filter((n) => n.type !== 'document');
     // Skip structural lint when parse has errors — partial tree causes cascading false positives
     if (!hasParseErrors) {
         // Ground-layer rules on IR nodes
@@ -263,7 +339,7 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         // Native .kern rules (built-in + custom)
         const rulesToRunKern = [...NATIVE_RULES];
         if (_config?.rulesDirs && _config.rulesDirs.length > 0) {
-            const builtinIds = new Set(NATIVE_RULES.map(r => r.ruleId).filter(Boolean));
+            const builtinIds = new Set(NATIVE_RULES.map((r) => r.ruleId).filter(Boolean));
             const customRules = loadNativeRules(_config.rulesDirs, builtinIds);
             rulesToRunKern.push(...customRules);
         }
@@ -279,7 +355,7 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
     // Confidence graph
     let confidenceGraph;
     let confidenceSummary;
-    if (flatNodes.some(n => n.props?.confidence !== undefined)) {
+    if (flatNodes.some((n) => n.props?.confidence !== undefined)) {
         const graph = buildConfidenceGraph(flatNodes);
         confidenceGraph = serializeGraph(graph);
         confidenceSummary = computeConfidenceSummary(graph);
@@ -297,10 +373,15 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
             promptAlias: `N${i + 1}`,
             startLine: line,
             endLine,
-            sourceSpans: [{
-                    file: filePath, startLine: line, startCol: node.loc?.col ?? 1,
-                    endLine, endCol: node.loc?.endCol ?? 1,
-                }],
+            sourceSpans: [
+                {
+                    file: filePath,
+                    startLine: line,
+                    startCol: node.loc?.col ?? 1,
+                    endLine,
+                    endCol: node.loc?.endCol ?? 1,
+                },
+            ],
             summary: `${node.type}${name !== node.type ? ` ${name}` : ''}`,
             confidence: 'high',
             confidencePct: 100,
@@ -309,6 +390,7 @@ export function reviewKernSource(source, filePath = 'input.kern', _config) {
         };
     });
     const dedupedFindings = sortAndDedup(allFindings);
+    assignDefaultConfidence(dedupedFindings);
     const suppression = applySuppression(dedupedFindings, source, filePath, _config, _config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
     const kernTokens = countTokens(source);
@@ -349,7 +431,7 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
         // Native .kern rules with concept matching (built-in + custom)
         const rulesToRunPy = [...NATIVE_RULES];
         if (config?.rulesDirs && config.rulesDirs.length > 0) {
-            const builtinIds = new Set(NATIVE_RULES.map(r => r.ruleId).filter(Boolean));
+            const builtinIds = new Set(NATIVE_RULES.map((r) => r.ruleId).filter(Boolean));
             const customRules = loadNativeRules(config.rulesDirs, builtinIds);
             rulesToRunPy.push(...customRules);
         }
@@ -359,7 +441,8 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
     }
     catch (_err) {
         // @kernlang/review-python not installed — skip concept extraction
-        conceptFindings = [{
+        conceptFindings = [
+            {
                 source: 'kern',
                 ruleId: 'missing-python-support',
                 severity: 'info',
@@ -367,9 +450,11 @@ export function reviewPythonSource(source, filePath = 'input.py', config) {
                 message: 'Install @kernlang/review-python for Python concept analysis',
                 primarySpan: { file: filePath, startLine: 1, startCol: 1, endLine: 1, endCol: 1 },
                 fingerprint: 'missing-python-0',
-            }];
+            },
+        ];
     }
     const dedupedFindings = sortAndDedup(conceptFindings);
+    assignDefaultConfidence(dedupedFindings);
     const suppression = applySuppression(dedupedFindings, source, filePath, config, config?.strict ?? false);
     const findings = sortAndDedup(suppression.findings);
     return {
@@ -412,11 +497,14 @@ export function reviewGraph(entryFiles, config, graphOptions) {
     const graph = resolveImportGraph(entryFiles, graphOptions);
     const entrySet = new Set(graph.entryFiles);
     const reports = [];
+    // Build file context map — every file gets import chain awareness
+    const fileContextMap = buildFileContextMap(graph);
+    const graphConfig = { ...config, fileContextMap };
     for (const gf of graph.files) {
         if (!existsSync(gf.path))
             continue;
         try {
-            const report = reviewFile(gf.path, config);
+            const report = reviewFile(gf.path, graphConfig);
             const isEntry = entrySet.has(gf.path);
             // Tag every finding with provenance
             for (const f of report.findings) {
@@ -452,11 +540,20 @@ export function reviewGraph(entryFiles, config, graphOptions) {
         const crossFileFindings = crossFileTaintToFindings(crossFileResults);
         // Add cross-file findings to the caller's report, then re-run suppression
         for (const f of crossFileFindings) {
-            const callerReport = reports.find(r => r.filePath === f.primarySpan.file);
+            const callerReport = reports.find((r) => r.filePath === f.primarySpan.file);
             if (callerReport) {
                 callerReport.findings.push(f);
             }
         }
+        // Attach raw cross-file taint results for structured output
+        for (const result of crossFileResults) {
+            const callerReport = reports.find((r) => r.filePath === result.callerFile);
+            if (callerReport) {
+                if (!callerReport.crossFileTaint)
+                    callerReport.crossFileTaint = [];
+                callerReport.crossFileTaint.push(result);
+            }
+        }
     }
     // 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
@@ -483,71 +580,53 @@ export function reviewGraph(entryFiles, config, graphOptions) {
             if (!concepts)
                 continue;
             // Remove per-file concept findings (they were run without cross-file context)
-            report.findings = report.findings.filter(f => !CONCEPT_RULE_IDS.has(f.ruleId));
+            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);
             report.findings.push(...crossFileConceptFindings);
         }
     }
-    // ── Post-filter: suppress server-hook / missing-use-client false positives ──
-    // In graph mode, if ALL importers of a file are within a client boundary
-    // ('use client' — recursively), hooks and event handlers are safe on the client.
-    if (config?.target === 'nextjs') {
-        const NEXTJS_CLIENT_RULES = new Set(['server-hook', 'missing-use-client']);
-        const hasNextjsFindings = reports.some(r => r.findings.some(f => NEXTJS_CLIENT_RULES.has(f.ruleId)));
-        if (hasNextjsFindings) {
-            const importedByMap = new Map();
+    // Note: server-hook / missing-use-client client boundary suppression is now handled
+    // by FileContext in the rules themselves (ctx.fileContext.isClientBoundary).
+    // ── Norm mining + proof obligations ──
+    if (allConcepts.size > 0) {
+        const normViolations = mineNorms(allConcepts);
+        for (const report of reports) {
+            const obligations = synthesizeObligations(allConcepts, fileContextMap, report.filePath, normViolations);
+            // Attach obligations to the report (as metadata, not findings — they're for the LLM reviewer)
+            report.obligations = obligations;
+        }
+    }
+    // ── Call graph analysis: dead exports + cross-file async ──
+    try {
+        // Use provided project, or build one with all graph files loaded
+        let cgProject = graphOptions?.project;
+        if (!cgProject) {
+            const { Project } = require('ts-morph');
+            cgProject = new Project({
+                compilerOptions: { strict: true, target: 99, module: 99, moduleResolution: 100, skipLibCheck: true },
+                useInMemoryFileSystem: false,
+                skipAddingFilesFromTsConfig: true,
+            });
             for (const gf of graph.files) {
-                importedByMap.set(gf.path, gf.importedBy);
-            }
-            const useClientCache = new Map();
-            function hasUseClient(fp) {
-                let r = useClientCache.get(fp);
-                if (r !== undefined)
-                    return r;
                 try {
-                    const src = readFileSync(fp, 'utf-8');
-                    r = /^['"]use client['"];?\s*$/m.test(src.substring(0, 200));
+                    cgProject.addSourceFileAtPath(gf.path);
                 }
                 catch {
-                    r = false;
-                }
-                useClientCache.set(fp, r);
-                return r;
-            }
-            const boundaryCache = new Map();
-            function isWithinClientBoundary(fp, visiting) {
-                if (hasUseClient(fp))
-                    return true;
-                const c = boundaryCache.get(fp);
-                if (c !== undefined)
-                    return c;
-                // Entry files without 'use client' are server components by definition
-                if (entrySet.has(fp)) {
-                    boundaryCache.set(fp, false);
-                    return false;
-                }
-                if (visiting.has(fp))
-                    return true; // cycle — optimistic
-                const importers = importedByMap.get(fp);
-                if (!importers || importers.length === 0) {
-                    boundaryCache.set(fp, false);
-                    return false;
-                }
-                visiting.add(fp);
-                const ok = importers.every(i => isWithinClientBoundary(i, visiting));
-                visiting.delete(fp);
-                boundaryCache.set(fp, ok);
-                return ok;
-            }
-            for (const report of reports) {
-                if (!report.findings.some(f => NEXTJS_CLIENT_RULES.has(f.ruleId)))
-                    continue;
-                if (isWithinClientBoundary(report.filePath, new Set())) {
-                    report.findings = report.findings.filter(f => !NEXTJS_CLIENT_RULES.has(f.ruleId));
+                    /* skip unresolvable */
                 }
             }
         }
+        const callGraph = buildCallGraph(graph, cgProject);
+        for (const report of reports) {
+            const deadExportFindings = deadExportRule(callGraph, report.filePath);
+            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
     }
     // Re-run suppression + dedup on all reports (cross-file findings were injected after initial suppression)
     for (const report of reports) {
@@ -567,10 +646,20 @@ function collectReviewableFiles(dirPath, recursive) {
     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') {
+        if (stat.isDirectory() &&
+            recursive &&
+            !entry.startsWith('.') &&
+            entry !== 'node_modules' &&
+            entry !== 'dist' &&
+            entry !== '__pycache__' &&
+            entry !== '.venv' &&
+            entry !== 'venv') {
             files.push(...collectReviewableFiles(full, true));
         }
-        else if ((entry.endsWith('.ts') || entry.endsWith('.tsx')) && !entry.endsWith('.d.ts') && !entry.endsWith('.test.ts') && !entry.endsWith('.test.tsx')) {
+        else if ((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')) {