code-auditor-mcp 3.4.11 → 3.4.13

package/dist/pipeline.js

@@ -9,134 +9,174 @@
  *
  * Stage position IS the dependency declaration — no topological sort needed.
  */
-import { readFile } from 'fs/promises';
+import { readFile, stat } from 'fs/promises';
+import { readFileSync } from 'fs';
 import path from 'path';
 import { performance } from 'perf_hooks';
-import { AuditAbortedError, } from './types.js';
+import { AuditAbortedError, MAX_ORPHAN_SOURCE_BYTES, } from './types.js';
+import { RULE_REGISTRY } from './analyzers/ruleRegistry.js';
+import { resetRuleTiming, getRuleTimingSortedDesc } from './analyzers/ruleTiming.js';
 import { LanguageRegistry } from './languages/LanguageRegistry.js';
 import { discoverFiles } from './utils/fileDiscovery.js';
 import { resolvePathProfile } from './config/pathProfiles.js';
 import { validateFactsDependencies } from './pipelineTypes.js';
 // ── Stage 1: Traverse + Parse ──────────────────────────────────────────────
-async function runStage1(config) {
-    const t0 = performance.now();
-    let readMs = 0;
-    let parseMs = 0;
-    // Discover files (or use explicit)
+/**
+ * Stream files one-at-a-time into stage 2 so per-file memory can be freed
+ * before the next file is parsed.
+ *
+ * File discovery is eager (separate from parsing) so the total count is
+ * available for progress reporting throughout the parse + visit loop.
+ *
+ * @returns generator (yields tuples), total file count, and a closure to
+ *          retrieve aggregate parse/read timing after the generator completes.
+ */
+function runStage1(config) {
+    // ── Eager discovery (same as before) ─────────────────────────────────
     const projectRoot = config.projectRoot;
     let files;
     if (config.explicitFiles !== undefined) {
         files = config.explicitFiles;
     }
     else {
-        files = await discoverFiles(projectRoot, {
-            excludeDirs: ['node_modules', '.next', 'dist', 'build', '.git', 'coverage', '.turbo'],
-        });
+        // discovery runs lazily inside the generator below
     }
     // Group by language adapter
     const registry = LanguageRegistry.getInstance();
-    const groups = new Map();
-    const orphans = [];
-    for (const file of files) {
-        const adapter = registry.getAdapterForFile(file);
-        if (adapter) {
-            const list = groups.get(adapter) ?? [];
-            list.push(file);
-            groups.set(adapter, list);
-        }
-        else {
-            orphans.push(file);
-        }
-    }
-    // Parse each file once
-    const tuples = [];
+    let total;
     let parsed = 0;
-    for (const [adapter, adapterFiles] of groups) {
-        for (const file of adapterFiles) {
-            // Check abort
-            if (config.abortSignal?.aborted) {
-                throw new AuditAbortedError('Audit aborted during stage 1');
+    let readMs = 0;
+    let parseMs = 0;
+    // Spec 32 — files that failed to parse (or be read) during stage 1, with the
+    // reason. A non-empty list means the audit was incomplete; surfaced in coverage
+    // and forces a non-zero exit so a plausible-but-wrong report is never silent.
+    const unparsedFiles = [];
+    async function* generate() {
+        // Lazy file discovery (only if not explicit)
+        const fileList = files ?? await discoverFiles(projectRoot, {
+            excludeDirs: ['node_modules', '.next', 'dist', 'build', '.git', 'coverage', '.turbo'],
+        });
+        total = fileList.length;
+        const groups = new Map();
+        const orphans = [];
+        for (const file of fileList) {
+            const adapter = registry.getAdapterForFile(file);
+            if (adapter) {
+                const list = groups.get(adapter) ?? [];
+                list.push(file);
+                groups.set(adapter, list);
+            }
+            else {
+                orphans.push(file);
             }
+        }
+        // Parse each file and yield immediately
+        for (const [adapter, adapterFiles] of groups) {
+            for (const file of adapterFiles) {
+                if (config.abortSignal?.aborted) {
+                    throw new AuditAbortedError('Audit aborted during stage 1');
+                }
+                try {
+                    const r0 = performance.now();
+                    const content = await readFile(file, 'utf-8');
+                    readMs += performance.now() - r0;
+                    const p0 = performance.now();
+                    const ast = await adapter.parse(file, content);
+                    parseMs += performance.now() - p0;
+                    parsed++;
+                    yield {
+                        kind: 'parsed',
+                        file,
+                        ast,
+                        adapter,
+                        sourceCode: content,
+                    };
+                }
+                catch (err) {
+                    // Spec 32 — a parse failure (including a WASM abort that survived
+                    // parseWithRecovery) must never be silent: record it so it lands in
+                    // coverage and forces a non-zero exit.
+                    unparsedFiles.push({ filePath: file, reason: err?.message ?? String(err) });
+                    if (config.progressCallback) {
+                        config.progressCallback({
+                            current: parsed,
+                            total,
+                            analyzer: 'pipeline',
+                            phase: 'stage1',
+                            file,
+                            message: `Skipped: ${err.message}`,
+                        });
+                    }
+                }
+            }
+        }
+        // Orphan files (no LanguageAdapter)
+        for (const file of orphans) {
             try {
+                // Spec 31 — oversized orphan .sql dumps are not materialized into a
+                // source string; the schema-sql visitor streams them on demand (and
+                // skips them entirely when they contain no DDL). Restricted to .sql:
+                // JSON/CSS orphans must still be materialized — their visitors parse
+                // the content, and an empty source would silently change behavior for
+                // large-but-valid files (e.g. a multi-MB audit-report.json).
+                const st = await stat(file);
+                if (file.endsWith('.sql') && st.size > MAX_ORPHAN_SOURCE_BYTES) {
+                    parsed++;
+                    yield {
+                        kind: 'raw',
+                        file,
+                        ast: null,
+                        adapter: null,
+                        sourceCode: '',
+                    };
+                    continue;
+                }
                 const r0 = performance.now();
                 const content = await readFile(file, 'utf-8');
                 readMs += performance.now() - r0;
-                const p0 = performance.now();
-                const ast = await adapter.parse(file, content);
-                parseMs += performance.now() - p0;
-                tuples.push({
-                    kind: 'parsed',
+                parsed++;
+                yield {
+                    kind: 'raw',
                     file,
-                    ast,
-                    adapter,
+                    ast: null,
+                    adapter: null,
                     sourceCode: content,
-                });
-                parsed++;
+                };
             }
             catch (err) {
-                // File read/parse errors — skip this file
-                // Individual files that fail to parse don't abort the entire run
+                unparsedFiles.push({ filePath: file, reason: `read error: ${err?.message ?? String(err)}` });
                 if (config.progressCallback) {
                     config.progressCallback({
-                        current: parsed,
-                        total: files.length,
+                        current: orphans.indexOf(file),
+                        total: orphans.length,
                         analyzer: 'pipeline',
                         phase: 'stage1',
                         file,
-                        message: `Skipped: ${err.message}`,
+                        message: `Raw file skipped (read error): ${err.message}`,
                     });
                 }
             }
         }
-    }
-    // Include orphan files as raw tuples — no LanguageAdapter available,
-    // but visitors that consume raw files can read sourceCode directly.
-    for (const file of orphans) {
-        try {
-            const r0 = performance.now();
-            const content = await readFile(file, 'utf-8');
-            readMs += performance.now() - r0;
-            tuples.push({
-                kind: 'raw',
-                file,
-                ast: null,
-                adapter: null,
-                sourceCode: content,
+        const orphanIncluded = fileList.filter(f => !registry.getAdapterForFile(f)).length;
+        if (orphanIncluded > 0 && config.progressCallback) {
+            config.progressCallback({
+                current: orphanIncluded,
+                total: orphanIncluded,
+                analyzer: 'pipeline',
+                phase: 'stage1',
+                message: `${orphanIncluded} file(s) included as raw (no language adapter)`,
             });
         }
-        catch (err) {
-            if (config.progressCallback) {
-                config.progressCallback({
-                    current: orphans.indexOf(file),
-                    total: orphans.length,
-                    analyzer: 'pipeline',
-                    phase: 'stage1',
-                    file,
-                    message: `Raw file skipped (read error): ${err.message}`,
-                });
-            }
-        }
     }
-    const orphanIncluded = tuples.filter(t => t.kind === 'raw').length;
-    if (orphanIncluded > 0 && config.progressCallback) {
-        config.progressCallback({
-            current: orphanIncluded,
-            total: orphanIncluded,
-            analyzer: 'pipeline',
-            phase: 'stage1',
-            message: `${orphanIncluded} file(s) included as raw (no language adapter)`,
-        });
-    }
-    const duration = performance.now() - t0;
     return {
-        tuples,
-        fileCount: tuples.length,
-        parseDurationMs: duration,
-        readDurationMs: readMs,
+        generator: generate(),
+        get fileCount() { return total; },
+        getUnparsedFiles: () => unparsedFiles,
+        getTiming: () => ({ parseDurationMs: parseMs, readDurationMs: readMs }),
     };
 }
 // ── Stage 2: Per-file visitors ─────────────────────────────────────────────
-async function runStage2(tuples, visitors, config) {
+export async function runStage2(tuples, visitors, config, totalFiles) {
     const t0 = performance.now();
     const visitorResults = new Map();
     const allFacts = new Map();
@@ -160,109 +200,112 @@ async function runStage2(tuples, visitors, config) {
     const infra = rawConfig['_infra'] ?? {};
     const pathProfiles = infra['pathProfiles'];
     const severityOverrides = infra['severityOverrides'] ?? {};
-    // Iterate tuples
-    for (let i = 0; i < tuples.length; i++) {
-        const tuple = tuples[i];
+    // Stream tuples from stage 1
+    let i = 0;
+    for await (const tuple of tuples) {
         // Check abort
         if (config.abortSignal?.aborted) {
             throw new AuditAbortedError('Audit aborted during stage 2');
         }
-        // Progress
-        if (config.progressCallback && i % 10 === 0) {
-            config.progressCallback({
-                current: i,
-                total: tuples.length,
-                analyzer: 'pipeline',
-                phase: 'stage2',
-                file: tuple.file,
-            });
-        }
-        // Resolve path profiles for this file (non-analyzer-specific)
-        let fileInfra = infra;
-        let fileProfileNames = [];
-        let fileSeverityCap;
-        if (pathProfiles && pathProfiles.length > 0) {
-            const resolved = resolvePathProfile(tuple.file, projectRoot, pathProfiles);
-            if (Object.keys(resolved.overrides).length > 0) {
-                fileInfra = { ...infra, ...resolved.overrides };
-            }
-            fileProfileNames = resolved.matchedProfileNames;
-            fileSeverityCap = resolved.severityCap;
-        }
-        // Fan out to all visitors for this file — filter by declared extensions
-        const fileExt = path.extname(tuple.file);
-        for (const visitor of visitors) {
-            // Dispatch check: backward-compat visitors see only parsed tuples.
-            // Visitors that declare extensions see only tuples whose extension they consume.
-            if (visitor.extensions) {
-                if (!visitor.extensions.includes(fileExt))
-                    continue;
+        try {
+            // Progress
+            if (config.progressCallback && i % 10 === 0) {
+                config.progressCallback({
+                    current: i,
+                    total: totalFiles,
+                    analyzer: 'pipeline',
+                    phase: 'stage2',
+                    file: tuple.file,
+                });
             }
-            else {
-                // No extensions declared → parsed tuples only (backward compat)
-                if (tuple.kind !== 'parsed')
-                    continue;
+            // Resolve path profiles for this file (non-analyzer-specific)
+            let fileInfra = infra;
+            let fileProfileNames = [];
+            let fileGateExcluded;
+            if (pathProfiles && pathProfiles.length > 0) {
+                const resolved = resolvePathProfile(tuple.file, projectRoot, pathProfiles);
+                if (Object.keys(resolved.overrides).length > 0) {
+                    fileInfra = { ...infra, ...resolved.overrides };
+                }
+                fileProfileNames = resolved.matchedProfileNames;
+                fileGateExcluded = resolved.excludeFromGate;
             }
-            const visitorConfig = { ...(rawConfig[visitor.name] ?? {}), ...fileInfra };
-            const visitorContext = {
-                projectRoot,
-                filePath: tuple.file,
-                config: visitorConfig,
-                abortSignal: config.abortSignal,
-            };
-            try {
-                const v0 = performance.now();
-                const result = await visitor.visit(tuple.ast, tuple.adapter, visitorContext, tuple.sourceCode);
-                const vMs = performance.now() - v0;
-                // Accumulate timing
-                timingMap.set(visitor.name, (timingMap.get(visitor.name) ?? 0) + vMs);
-                // Attach profile, severity overrides, analyzer name
-                const severityOrder = ['suggestion', 'warning', 'critical'];
-                const processedViolations = result.violations
-                    .map((v) => ({
-                    ...v,
-                    profile: fileProfileNames.length > 0
-                        ? fileProfileNames[fileProfileNames.length - 1]
-                        : v.profile,
-                    severity: (severityOverrides[v.rule] ?? v.severity),
-                }))
-                    // Filter out violations whose severity was overridden to 'off' (Spec-11 R5)
-                    .filter((v) => v.severity !== 'off')
-                    // Apply severity cap from path profiles (Spec-20)
-                    // Applied AFTER severityOverrides so path-level caps beat global promotions
-                    .map((v) => {
-                    if (fileSeverityCap) {
-                        const capIndex = severityOrder.indexOf(fileSeverityCap);
-                        if (capIndex >= 0 && severityOrder.indexOf(v.severity) > capIndex) {
-                            return { ...v, severity: fileSeverityCap };
-                        }
-                    }
-                    return v;
-                });
-                // Accumulate violations
-                const ar = visitorResults.get(visitor.name);
-                ar.violations.push(...processedViolations);
-                const prevFiles = ar.status.status === 'visitor-ran' ? ar.status.filesProcessed : 0;
-                ar.status = {
-                    status: 'visitor-ran',
-                    filesProcessed: prevFiles + 1,
+            // Fan out to all visitors for this file — filter by declared extensions
+            const fileExt = path.extname(tuple.file);
+            for (const visitor of visitors) {
+                // Dispatch check: backward-compat visitors see only parsed tuples.
+                // Visitors that declare extensions see only tuples whose extension they consume.
+                if (visitor.extensions) {
+                    if (!visitor.extensions.includes(fileExt))
+                        continue;
+                }
+                else {
+                    // No extensions declared → parsed tuples only (backward compat)
+                    if (tuple.kind !== 'parsed')
+                        continue;
+                }
+                const visitorConfig = { ...(rawConfig[visitor.name] ?? {}), ...fileInfra };
+                const visitorContext = {
+                    projectRoot,
+                    filePath: tuple.file,
+                    config: visitorConfig,
+                    abortSignal: config.abortSignal,
                 };
-                // Accumulate facts
-                if (result.facts && Object.keys(result.facts).length > 0) {
-                    const existing = allFacts.get(visitor.name) ?? {};
-                    allFacts.set(visitor.name, { ...existing, ...result.facts });
+                try {
+                    const v0 = performance.now();
+                    const result = await visitor.visit(tuple.ast, tuple.adapter, visitorContext, tuple.sourceCode);
+                    const vMs = performance.now() - v0;
+                    // Accumulate timing
+                    timingMap.set(visitor.name, (timingMap.get(visitor.name) ?? 0) + vMs);
+                    // Attach profile, severity overrides, analyzer name, and gate exclusion
+                    // (Spec 36 R4). Severity is left untouched — a path profile excludes a
+                    // file from the blocking gate, it never softens a finding within it.
+                    const processedViolations = result.violations
+                        .map((v) => ({
+                        ...v,
+                        profile: fileProfileNames.length > 0
+                            ? fileProfileNames[fileProfileNames.length - 1]
+                            : v.profile,
+                        severity: (severityOverrides[v.rule] ?? v.severity),
+                        ...(fileGateExcluded ? { gateExcluded: true } : {}),
+                    }))
+                        // Filter out violations whose severity was overridden to 'off' (Spec-11 R5)
+                        .filter((v) => v.severity !== 'off');
+                    // Accumulate violations
+                    const ar = visitorResults.get(visitor.name);
+                    ar.violations.push(...processedViolations);
+                    const prevFiles = ar.status.status === 'visitor-ran' ? ar.status.filesProcessed : 0;
+                    ar.status = {
+                        status: 'visitor-ran',
+                        filesProcessed: prevFiles + 1,
+                    };
+                    // Accumulate facts
+                    if (result.facts && Object.keys(result.facts).length > 0) {
+                        const existing = allFacts.get(visitor.name) ?? {};
+                        allFacts.set(visitor.name, { ...existing, ...result.facts });
+                    }
+                    // Collect index facts
+                    if (result.indexFacts && result.indexFacts.length > 0) {
+                        indexFacts.push(...result.indexFacts);
+                    }
                 }
-                // Collect index facts
-                if (result.indexFacts && result.indexFacts.length > 0) {
-                    indexFacts.push(...result.indexFacts);
+                catch (err) {
+                    // Visitor error on this file — collect but don't abort
+                    const errs = errors.get(visitor.name);
+                    errs.push({ file: tuple.file, error: err.message });
                 }
             }
-            catch (err) {
-                // Visitor error on this file — collect but don't abort
-                const errs = errors.get(visitor.name);
-                errs.push({ file: tuple.file, error: err.message });
-            }
         }
+        finally {
+            // Free per-file memory on every exit path (Spec 32 Fix 3): reclaim the WASM
+            // tree + drop the source string, even if a visitor or path-profile resolve
+            // throws. A leaked tree keeps the Emscripten arena pinned at its high-water
+            // mark and is the trigger for the Aborted() ceiling.
+            const ast = tuple.ast;
+            ast?.dispose?.();
+            tuple.sourceCode = '';
+        }
+        i++;
     }
     // Finalize results
     const totalDuration = performance.now() - t0;
@@ -295,7 +338,7 @@ async function runStage2(tuples, visitors, config) {
         allFacts,
         indexFacts,
         visitorDurationMs: timingMap,
-        fileCount: tuples.length,
+        fileCount: i,
     };
 }
 // ── Stage 3: Corpus reducers ───────────────────────────────────────────────
@@ -314,24 +357,47 @@ async function runStage3(allFacts, reducers, config, indexHandle) {
         }
         // Per-reducer namespaced config: analyzer namespace + infrastructure
         const reducerConfig = { ...(rawConfig[reducer.name] ?? {}), ...infra };
+        // On-demand source reader: reducers pull file text lazily via readFileSync
+        // instead of retaining every file's source as a fact through stage 4.
+        const readSource = (filePath) => {
+            try {
+                return readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                return undefined;
+            }
+        };
         const reducerContext = {
             projectRoot: config.projectRoot,
             config: reducerConfig,
             indexHandle,
             abortSignal: config.abortSignal,
+            readSource,
         };
         try {
             const r0 = performance.now();
             const result = await reducer.reduce(factsObj, reducerContext);
             const rMs = performance.now() - r0;
-            reducerResults.set(reducer.name, {
-                violations: result.violations,
-                status: { status: 'reducer-ran', factsConsumed: result.factsConsumed ?? factsConsumed },
-                executionTime: rMs,
-                analyzerName: reducer.name,
-            });
-            if (result.facts && Object.keys(result.facts).length > 0) {
-                reducerFacts.set(reducer.name, result.facts);
+            // Allow reducers to signal notRun (e.g. invariants auto-disabled when no
+            // rules are configured). The reducer sets notRunReason in its result.
+            if (result.notRunReason) {
+                reducerResults.set(reducer.name, {
+                    violations: [],
+                    status: { status: 'notRun', reason: result.notRunReason },
+                    executionTime: rMs,
+                    analyzerName: reducer.name,
+                });
+            }
+            else {
+                reducerResults.set(reducer.name, {
+                    violations: result.violations,
+                    status: { status: 'reducer-ran', factsConsumed: result.factsConsumed ?? factsConsumed },
+                    executionTime: rMs,
+                    analyzerName: reducer.name,
+                });
+                if (result.facts && Object.keys(result.facts).length > 0) {
+                    reducerFacts.set(reducer.name, result.facts);
+                }
             }
         }
         catch (err) {
@@ -377,12 +443,23 @@ async function runStage4(allFacts, derivedReducers, config, indexHandle) {
             const r0 = performance.now();
             const result = await dr.reduce(allFacts, reducerContext);
             const rMs = performance.now() - r0;
-            derivedResults.set(dr.name, {
-                violations: result.violations,
-                status: { status: 'reducer-ran', factsConsumed: result.factsConsumed ?? factsConsumed },
-                executionTime: rMs,
-                analyzerName: dr.name,
-            });
+            // Allow derived reducers to signal notRun (same mechanism as Stage 3)
+            if (result.notRunReason) {
+                derivedResults.set(dr.name, {
+                    violations: [],
+                    status: { status: 'notRun', reason: result.notRunReason },
+                    executionTime: rMs,
+                    analyzerName: dr.name,
+                });
+            }
+            else {
+                derivedResults.set(dr.name, {
+                    violations: result.violations,
+                    status: { status: 'reducer-ran', factsConsumed: result.factsConsumed ?? factsConsumed },
+                    executionTime: rMs,
+                    analyzerName: dr.name,
+                });
+            }
         }
         catch (err) {
             derivedResults.set(dr.name, {
@@ -416,26 +493,39 @@ export async function runPipeline(config, indexHandle) {
     const visitors = config.visitors ?? [];
     const reducers = config.reducers ?? [];
     const derivedReducers = config.derivedReducers ?? [];
+    // Spec 38 R2 — per-rule timing accumulator is module-global (spans stages 2+3),
+    // so reset it at pipeline entry to avoid cross-run contamination.
+    resetRuleTiming();
     // ── Validate facts dependencies ──────────────────────────────────────────
     const depErrors = validateFactsDependencies(visitors, reducers, derivedReducers);
     if (depErrors.length > 0) {
         throw new Error(`Pipeline facts dependency errors:\n${depErrors.map((e) => `  - ${e}`).join('\n')}`);
     }
-    // ── Stage 1: Traverse + Parse ────────────────────────────────────────────
-    const stage1 = await runStage1(config);
-    stageTiming['stage1-parse'] = stage1.parseDurationMs;
+    // ── Stage 1 setup: eager file discovery, lazy parse stream ──────────────
+    const s1 = runStage1(config);
     if (config.progressCallback) {
         config.progressCallback({
-            current: stage1.fileCount,
-            total: stage1.fileCount,
+            current: 0,
+            total: s1.fileCount,
             analyzer: 'pipeline',
             phase: 'stage1-complete',
-            message: `${stage1.fileCount} files parsed in ${stage1.parseDurationMs.toFixed(0)}ms`,
+            message: `${s1.fileCount} files discovered`,
         });
     }
-    // ── Stage 2: Per-file visitors ───────────────────────────────────────────
-    const stage2 = await runStage2(stage1.tuples, visitors, config);
-    stageTiming['stage2-visitors'] = performance.now() - totalT0 - stage1.parseDurationMs;
+    // ── Stage 2: Stream parse + per-file visitors ────────────────────────────
+    // The generator lazily reads/parses files as stage 2 consumes them.
+    // Stage 1 parse time is accumulated inside the generator closure and
+    // retrieved via getTiming() after the stream exhausts.
+    const streamT0 = performance.now();
+    const stage2 = await runStage2(s1.generator, visitors, config, s1.fileCount);
+    const { parseDurationMs, readDurationMs } = s1.getTiming();
+    // Streaming interleaves parse + visit per file, so there is no clean
+    // "stage 1 then stage 2" wall-clock split. Report honest figures instead:
+    // two CPU accumulators (measured inside the generator) plus one combined
+    // wall-clock for the whole parse+visit stream.
+    stageTiming['parse-cpu'] = parseDurationMs;
+    stageTiming['read-cpu'] = readDurationMs;
+    stageTiming['stream-parse-visit'] = performance.now() - streamT0;
     if (config.progressCallback) {
         config.progressCallback({
             current: stage2.fileCount,
@@ -505,15 +595,49 @@ export async function runPipeline(config, indexHandle) {
             });
         }
     }
+    // Spec 33 Item 14 — per-rule input presence, computed once from the merged
+    // facts + index tables, then used to promote zero-violation rules.
+    const inputPresence = computeInputPresence(combinedFacts, indexHandle);
+    // Spec 27 — build per-rule coverage from completed pipeline results
+    const coverage = buildCoverageReport(analyzerResults, config, inputPresence);
+    // Spec 29: Extract table catalog from schema reducer facts for metadata
+    const schemaFacts = combinedFacts['schema'];
+    const tableCatalog = schemaFacts?.tableCatalog;
+    // Spec 31: surface oversized orphan files skipped by stage-1 streaming.
+    // The schema-sql visitor marks them with `skipped: true`; here they are lifted
+    // into metadata so a skipped file is visible in coverage without adding a
+    // violation (which would break the exact baseline counts).
+    const schemaSqlFacts = stage2.allFacts.get('schema-sql');
+    const skippedFiles = [];
+    if (schemaSqlFacts) {
+        for (const [filePath, fact] of Object.entries(schemaSqlFacts)) {
+            const f = fact;
+            if (f.skipped) {
+                skippedFiles.push({ filePath, bytes: f.bytes ?? 0, reason: 'oversized-orphan-no-ddl' });
+            }
+        }
+    }
     const totalDuration = performance.now() - totalT0;
+    // Spec 32: files that failed to parse (or be read) in stage 1. Surfaced in
+    // coverage and used by the CLI to force a non-zero exit — a run that silently
+    // skipped files must never report as clean.
+    const unparsedFiles = s1.getUnparsedFiles();
+    // Spec 38 R2 — surface per-rule timing, slowest first, only when opt-in.
+    const ruleTiming = getRuleTimingSortedDesc();
     return {
         analyzerResults,
         metadata: {
             auditDuration: totalDuration,
-            filesAnalyzed: stage1.fileCount,
+            filesAnalyzed: s1.fileCount,
             stageTiming,
             scoped: config.isScoped,
             diagnostics,
+            coverage,
+            inputPresence,
+            tableCatalog,
+            ...(skippedFiles.length > 0 && { skippedFiles }),
+            ...(unparsedFiles.length > 0 && { unparsedFiles }),
+            ...(ruleTiming.length > 0 && { ruleTiming }),
         },
         indexFacts: stage2.indexFacts,
     };
@@ -617,4 +741,204 @@ export function isVisitorStatus(status) {
 export function isReducerStatus(status) {
     return status.status === 'reducer-ran';
 }
+// ── Coverage reporting (Spec 27) ────────────────────────────────────────────
+/**
+ * Spec 33 Item 14 — snapshot which rule-input sources are present this run.
+ *
+ *   - `factKeys`: visitor/reducer names whose merged facts (stage 2 + stage 3)
+ *     are non-empty. A reducer reading e.g. `function-index` facts has input
+ *     only when that key is present.
+ *   - `indexTables`: index tables (referenced by a rule's `input`) that held
+ *     ≥1 row when coverage was built. Non-existent tables are skipped.
+ */
+function computeInputPresence(combinedFacts, indexHandle) {
+    const factKeys = [];
+    for (const [name, facts] of Object.entries(combinedFacts)) {
+        if (facts && typeof facts === 'object' && Object.keys(facts).length > 0) {
+            factKeys.push(name);
+        }
+    }
+    const indexTables = [];
+    if (indexHandle) {
+        const candidates = new Set();
+        for (const entry of Object.values(RULE_REGISTRY)) {
+            for (const source of entry.input ?? []) {
+                if (source !== 'files')
+                    candidates.add(source);
+            }
+        }
+        for (const table of candidates) {
+            try {
+                if (indexHandle.tableHasRows(table))
+                    indexTables.push(table);
+            }
+            catch {
+                // Table doesn't exist (e.g. a fact-key name) — not an index table.
+            }
+        }
+    }
+    return { factKeys, indexTables };
+}
+/**
+ * Build a per-rule coverage report from completed pipeline results.
+ *
+ * Iterates every rule in the canonical {@link RULE_REGISTRY}, cross-references
+ * with the analyzer-results map to derive a {@link RuleCoverageState} per rule:
+ *
+ * | Analyzer status                        | Rule state      | Reason                          |
+ * |----------------------------------------|-----------------|---------------------------------|
+ * | notRun                                 | `notApplicable` | `notRun.reason`                 |
+ * | visitor-ran, filesProcessed === 0      | `notApplicable` | "no matching source files"      |
+ * | reducer-ran, factsConsumed === 0       | `notApplicable` | "no facts consumed from upstream visitors" |
+ * | analyzer ran with input, count > 0     | `fired`         | (none)                          |
+ * | analyzer ran with input, count === 0   | `clean`/`notApplicable` | per-rule input mapping    |
+ *
+ * Spec 33 Item 14: zero-violation rules are promoted from `unassessed` to
+ * `clean` (mapped input present) or `notApplicable` (mapped input absent). Only
+ * rules with no `input` mapping (non-pipeline analyzers) remain `unassessed`.
+ *
+ * Rules whose analyzer was not enabled in `config` are omitted entirely
+ * (they were not part of this run — distinct from `notRun`).
+ */
+export function buildCoverageReport(analyzerResults, config, inputPresence) {
+    const coverage = [];
+    for (const [ruleId, entry] of Object.entries(RULE_REGISTRY)) {
+        const { analyzer: analyzerName, field } = entry;
+        // Skip rules whose analyzer wasn't configured for this run
+        if (!(analyzerName in (config.config ?? {}))) {
+            continue;
+        }
+        const result = analyzerResults[analyzerName];
+        // Analyzer not in results → notRun-equivalent
+        if (!result) {
+            coverage.push({
+                ruleId,
+                analyzer: analyzerName,
+                state: 'notApplicable',
+                count: 0,
+                reason: `analyzer "${analyzerName}" not in results`,
+            });
+            continue;
+        }
+        const status = result.status;
+        // notRun: all rules notApplicable
+        if (status.status !== 'visitor-ran' && status.status !== 'reducer-ran') {
+            const reason = status.reason;
+            coverage.push({
+                ruleId,
+                analyzer: analyzerName,
+                state: 'notApplicable',
+                count: 0,
+                reason,
+            });
+            continue;
+        }
+        // Visitor with zero input files
+        if (isVisitorStatus(status) && getFilesProcessed(status) === 0) {
+            coverage.push({
+                ruleId,
+                analyzer: analyzerName,
+                state: 'notApplicable',
+                count: 0,
+                reason: 'no matching source files',
+            });
+            continue;
+        }
+        // Reducer with zero facts consumed
+        if (isReducerStatus(status) && getFactsConsumed(status) === 0) {
+            coverage.push({
+                ruleId,
+                analyzer: analyzerName,
+                state: 'notApplicable',
+                count: 0,
+                reason: 'no facts consumed from upstream visitors',
+            });
+            continue;
+        }
+        // Check per-rule config gate (explicitly disabled by config)
+        if (entry.configGate) {
+            const analyzerNs = (config.config ?? {})[analyzerName];
+            const gateValue = analyzerNs?.[entry.configGate];
+            if (gateValue === false) {
+                coverage.push({
+                    ruleId,
+                    analyzer: analyzerName,
+                    state: 'notApplicable',
+                    count: 0,
+                    reason: `disabled by config (${analyzerName}.${entry.configGate}: false)`,
+                });
+                continue;
+            }
+        }
+        // Analyzer ran with input — count violations for this rule
+        const violations = (result.violations ?? []).filter((v) => {
+            if (field === 'type')
+                return v.type === ruleId;
+            if (field === 'contractType')
+                return v.contractType === ruleId;
+            if (field === 'principle')
+                return v.principle === ruleId;
+            if (field === 'violationType')
+                return v.violationType === ruleId;
+            if (field === 'ruleId')
+                return v.ruleId === ruleId;
+            return v.rule === ruleId;
+        });
+        const count = violations.length;
+        if (count > 0) {
+            coverage.push({
+                ruleId,
+                analyzer: analyzerName,
+                state: 'fired',
+                count,
+            });
+            continue;
+        }
+        // Spec 33 Item 14 — zero-violation rules are now promoted from `unassessed`
+        // to `clean`/`notApplicable` based on whether the rule's mapped input was
+        // present this run. Rules with no mapping (non-pipeline analyzers) stay
+        // `unassessed`.
+        coverage.push(resolveZeroViolationState(ruleId, analyzerName, entry.input, inputPresence));
+    }
+    return coverage;
+}
+/**
+ * Spec 33 Item 14 — classify a zero-violation rule by its declared input.
+ *
+ *   - No `input` mapping → `unassessed` (input provenance unknown; non-pipeline
+ *     analyzers only).
+ *   - Any input source present → `clean` (the analyzer ran over the rule's real
+ *     input and found nothing to flag).
+ *   - All input sources absent → `notApplicable` (the input this rule reads was
+ *     never produced this run).
+ *
+ * An input source is "present" when it is the literal `'files'` (always present
+ * at this branch — earlier checks already excluded empty-input analyzers), a
+ * fact-key in {@link InputPresence.factKeys}, or an index table in
+ * {@link InputPresence.indexTables}.
+ */
+function resolveZeroViolationState(ruleId, analyzerName, input, inputPresence) {
+    if (!input || input.length === 0) {
+        return {
+            ruleId,
+            analyzer: analyzerName,
+            state: 'unassessed',
+            count: 0,
+            reason: 'applicability not assessed (no per-rule input mapping)',
+        };
+    }
+    const factKeys = new Set(inputPresence?.factKeys ?? []);
+    const indexTables = new Set(inputPresence?.indexTables ?? []);
+    const anyPresent = input.some((source) => source === 'files' || factKeys.has(source) || indexTables.has(source));
+    if (anyPresent) {
+        return { ruleId, analyzer: analyzerName, state: 'clean', count: 0 };
+    }
+    return {
+        ruleId,
+        analyzer: analyzerName,
+        state: 'notApplicable',
+        count: 0,
+        reason: `rule input absent (none of: ${input.join(', ')})`,
+    };
+}
 //# sourceMappingURL=pipeline.js.map