code-auditor-mcp 3.4.11 → 3.4.13

package/dist/pipelineAdapters.js

@@ -21,7 +21,9 @@ import { RULE_REGISTRY } from './analyzers/ruleRegistry.js';
 import { walkAST, isExported, getLineAndColumn, calculateComplexity, getFunctionBody, } from './languages/adapterBridge.js';
 import { buildImportMap, extractFunctionCalls, } from './utils/dependencyExtractor.js';
 import { isReactComponent, detectComponentType, getComponentName, } from './utils/reactDetection.js';
-import { ALL_EXTENSIONS } from './utils/fileDiscovery.js';
+import { findTableReferences, checkNamingConventions, checkQueryPatterns, checkSQLInjection, getNearestTableSuggestions, } from './analyzers/universal/schema/codeAnalysis.js';
+import { passesFileGate, extractTablesFromRegistry, } from './analyzers/universal/schema/discovery.js';
+import { applyMigrationOps } from './analyzers/universal/schema/migrations.js';
 // ── Rule ID helpers ──────────────────────────────────────────────────────────
 function getRuleIdsFor(name) {
     return Object.entries(RULE_REGISTRY)
@@ -37,29 +39,6 @@ function lazySingleton(loader) {
         return promise;
     };
 }
-// ── File-sources infrastructure visitor ──────────────────────────────────────
-/**
- * Infrastructure visitor that records every file's source code so Stage 3
- * reducers can access it without calling readFileSync(). Always registered;
- * declares all known extensions so it covers both parsed and raw tuples.
- */
-export function createFileSourcesVisitor() {
-    return {
-        name: 'file-sources',
-        stage: 'visitor',
-        extensions: ALL_EXTENSIONS,
-        getRuleIds: () => [],
-        async visit(_ast, _adapter, context, sourceCode) {
-            return {
-                violations: [],
-                facts: { [context.filePath]: sourceCode },
-            };
-        },
-        defaultConfig: {},
-        description: 'Records every file source for Stage 3 reducers (infrastructure)',
-        category: 'infrastructure',
-    };
-}
 // ── SOLID visitor ────────────────────────────────────────────────────────────
 export function createSolidVisitor() {
     const getAnalyzer = lazySingleton(() => import('./analyzers/universal/UniversalSOLIDAnalyzer.js').then((m) => new m.UniversalSOLIDAnalyzer()));
@@ -521,16 +500,14 @@ export function createReactVisitor() {
 // ── Styles CSS visitor (Spec 26 Phase 2) ───────────────────────────────────────
 /**
  * Styles CSS visitor — extracts declarations, tokens, and class usage from
- * tree-sitter-css parsed ASTs. Replaces the regex-based CSS extraction in
- * styleExtractor.ts for .css files only.
- *
- * tree-sitter-css is NOT an SCSS grammar — .scss files stay on the regex path.
+ * tree-sitter-css and tree-sitter-scss parsed ASTs. Replaces the regex-based
+ * CSS/SCSS extraction in styleExtractor.ts for .css and .scss files.
  */
 export function createStylesCssVisitor() {
     return {
         name: 'styles-css',
         stage: 'visitor',
-        extensions: ['.css'],
+        extensions: ['.css', '.scss'],
         getRuleIds: () => [],
         async visit(ast, adapter, context, sourceCode) {
             // Lazy-load to avoid circular dependency issues at module load time
@@ -550,7 +527,7 @@ export function createStylesCssVisitor() {
             };
         },
         defaultConfig: {},
-        description: 'Extracts CSS declarations from tree-sitter-css ASTs (.css only)',
+        description: 'Extracts CSS declarations from tree-sitter ASTs (.css and .scss)',
         category: 'style',
     };
 }
@@ -635,11 +612,6 @@ export function createConventionsReducer() {
             try {
                 const { UniversalConventionsAnalyzer } = await import('./analyzers/universal/UniversalConventionsAnalyzer.js');
                 const analyzer = new UniversalConventionsAnalyzer();
-                // Extract per-file source map from the file-sources infrastructure visitor
-                const fileSources = _allFacts['file-sources'];
-                const sourceMap = fileSources
-                    ? new Map(Object.entries(fileSources))
-                    : undefined;
                 // B2: Build exports map from function-index visitor facts (AST-extracted)
                 const functionIndexFacts = _allFacts['function-index'];
                 const exportsMap = functionIndexFacts
@@ -647,7 +619,7 @@ export function createConventionsReducer() {
                         .filter(([, data]) => data?.exports?.length)
                         .map(([filePath, data]) => [filePath, data.exports]))
                     : undefined;
-                const config = { ...context.config, indexHandle: context.indexHandle, projectRoot: context.projectRoot, sourceMap, exportsMap };
+                const config = { ...context.config, indexHandle: context.indexHandle, projectRoot: context.projectRoot, readSource: context.readSource, exportsMap };
                 const result = await analyzer.analyze([], config);
                 const factsConsumed = context.indexHandle.count('conventions');
                 return { violations: result.violations ?? [], facts: {}, factsConsumed };
@@ -717,17 +689,22 @@ export function createInvariantsReducer() {
         getRuleIds: () => getRuleIdsFor('invariants'),
         async reduce(_allFacts, context) {
             try {
+                // Auto-disable when no rules are configured — signal notRun to the
+                // pipeline so coverage reports invariants rules as notApplicable with
+                // an accurate reason (Spec 05 R3.1, Spec 27 criterion 5).
+                const rules = context.config.rules;
+                if (!rules || (Array.isArray(rules) && rules.length === 0)) {
+                    return {
+                        violations: [],
+                        facts: {},
+                        notRunReason: 'invariants disabled — no rules configured',
+                    };
+                }
                 const { analyzeInvariants } = await import('./analyzers/invariantsAnalyzer.js');
                 // Full file list is in _infra.files (merged into context.config via pipeline)
                 const files = context.config.files ?? [];
-                // Extract per-file source map from the file-sources infrastructure visitor
-                const fileSources = _allFacts['file-sources'];
-                const sourceMap = fileSources
-                    ? new Map(Object.entries(fileSources))
-                    : undefined;
-                const knownFiles = sourceMap
-                    ? new Set(sourceMap.keys())
-                    : undefined;
+                // Absolute paths — format-equivalent to the old sourceMap.keys().
+                const knownFiles = new Set(files);
                 // B1: Build fileData from the function-index visitor's AST-extracted
                 // imports/exports — replaces regex-based extractImports/extractExportedSymbols
                 const functionIndexFacts = _allFacts['function-index'];
@@ -757,7 +734,7 @@ export function createInvariantsReducer() {
                         }
                     }
                 }
-                const result = await analyzeInvariants(files, { ...context.config, sourceMap, knownFiles, fileData }, { projectRoot: context.projectRoot, indexHandle: context.indexHandle });
+                const result = await analyzeInvariants(files, { ...context.config, readSource: context.readSource, knownFiles, fileData }, { projectRoot: context.projectRoot, indexHandle: context.indexHandle });
                 return {
                     violations: result.violations ?? [],
                     facts: {},
@@ -783,23 +760,32 @@ async function _getProvenanceModule() {
     return _provenanceModule;
 }
 /**
- * Schema SQL visitor (.sql files) — extracts raw DDL source for the Stage 3
- * reducer to replay into the known-tables catalog.
+ * Schema SQL visitor (.sql files) — extracts ordered DDL operations for the
+ * Stage 3 reducer to replay into the known-tables catalog. Emits the parsed
+ * ops, not raw source, so the reducer retains only state transitions.
  */
 export function createSchemaSqlVisitor() {
+    const getMigrationExtractor = lazySingleton(() => import('./analyzers/universal/UniversalSchemaAnalyzer.js'));
     return {
         name: 'schema-sql',
         stage: 'visitor',
         extensions: ['.sql'],
         getRuleIds: () => [],
         async visit(_ast, _adapter, context, sourceCode) {
+            const { extractMigrationOpsFromFile } = await getMigrationExtractor();
+            const { ops, skipped, bytes } = await extractMigrationOpsFromFile(context.filePath, sourceCode);
             return {
                 violations: [],
-                facts: { [context.filePath]: { ddlSource: sourceCode } },
+                facts: {
+                    [context.filePath]: {
+                        ddlOps: ops,
+                        ...(skipped && { skipped: true, bytes }),
+                    },
+                },
             };
         },
         defaultConfig: {},
-        description: 'Captures SQL DDL source for known-table catalog',
+        description: 'Extracts SQL DDL operations for known-table catalog',
         category: 'database',
     };
 }
@@ -811,6 +797,7 @@ export function createSchemaCodeVisitor() {
     const getAnalyzer = lazySingleton(() => import('./analyzers/universal/UniversalSchemaAnalyzer.js').then((m) => ({
         analyzer: new m.UniversalSchemaAnalyzer(),
         defaults: m.DEFAULT_SCHEMA_CONFIG,
+        parseMigrationOps: m.parseMigrationOps,
     })));
     return {
         name: 'schema-code',
@@ -818,16 +805,34 @@ export function createSchemaCodeVisitor() {
         extensions: ['.ts', '.tsx', '.js', '.jsx'],
         getRuleIds: () => getRuleIdsFor('schema'),
         async visit(ast, adapter, context, sourceCode) {
-            const { analyzer: a, defaults } = await getAnalyzer();
+            const { analyzer: a, defaults, parseMigrationOps } = await getAnalyzer();
             const pm = await _getProvenanceModule();
             const violations = [];
             const indexFacts = [];
-            // Extract ORM table names (Drizzle) from source
+            // Pipeline config for this analyzer (moved before table extraction, needed
+            // by the table-source registry and provenance context).
+            const schemaConfig = (context.config ?? {});
+            // Spec 29 R2: Extract ORM table names via declarative table-source registry.
+            // Adding an ORM is now a config entry, not code.  Falls back to Drizzle
+            // entries when no user-specified tableSources are configured.
             const ormTables = [];
-            const drizzleRe = /(?:pgTable|mysqlTable|sqliteTable)\s*\(\s*['"]([^'"]+)['"]/g;
-            let dm;
-            while ((dm = drizzleRe.exec(sourceCode)) !== null) {
-                ormTables.push(dm[1]);
+            const tableProvenances = [];
+            const tableSources = schemaConfig.tableSources ?? [
+                { kind: 'callee', name: 'pgTable', arg: 0, description: 'Drizzle PostgreSQL table' },
+                { kind: 'callee', name: 'mysqlTable', arg: 0, description: 'Drizzle MySQL table' },
+                { kind: 'callee', name: 'sqliteTable', arg: 0, description: 'Drizzle SQLite table' },
+            ];
+            if (tableSources.length > 0) {
+                const registered = extractTablesFromRegistry(tableSources, {
+                    ast: ast,
+                    adapter: adapter,
+                    sourceCode,
+                    filePath: context.filePath,
+                });
+                for (const { table, source } of registered) {
+                    ormTables.push(table);
+                    tableProvenances.push({ table, source });
+                }
             }
             // Extract DDL from sql.exec(...) string literals inside Durable Object classes.
             // These are CREATE TABLE / DROP TABLE statements at runtime that migration
@@ -848,19 +853,19 @@ export function createSchemaCodeVisitor() {
                     doDDL.push(sql);
             }
             // Build provenance context for this file — defaults from DEFAULT_SCHEMA_CONFIG
-            const schemaConfig = (context.config ?? {});
             const detectionMode = schemaConfig.detection?.mode ?? 'hybrid';
             const provenanceContext = pm.buildProvenanceContext(ast, adapter, sourceCode, {
                 mode: detectionMode,
                 dbReceiverNames: schemaConfig.dbReceiverNames ?? defaults.dbReceiverNames,
                 dbBindingNames: schemaConfig.dbBindingNames ?? defaults.dbBindingNames,
                 dbCallMethods: schemaConfig.dbCallMethods ?? defaults.dbCallMethods,
+                dbWrapperNames: schemaConfig.dbWrapperNames ?? defaults.dbWrapperNames,
             });
             // File gate — skip files without DB usage
-            if (!a.passesFileGate(context.filePath, sourceCode, schemaConfig, provenanceContext)) {
-                const facts = { [context.filePath]: { tableRefs: [], ormTables } };
+            if (!passesFileGate(context.filePath, sourceCode, schemaConfig, provenanceContext)) {
+                const facts = { [context.filePath]: { tableRefs: [], ormTables, tableProvenance: tableProvenances } };
                 if (doDDL.length > 0)
-                    facts[context.filePath].ddlSource = doDDL.join(';\n');
+                    facts[context.filePath].ddlOps = parseMigrationOps(doDDL.join(';\n'));
                 return { violations: [], facts };
             }
             // Build known-tables set from schemas config (pre-pipeline + DB-loaded schemas)
@@ -875,7 +880,7 @@ export function createSchemaCodeVisitor() {
                 }
             }
             // Find table references (per-file, uses allTables for short-id false-positive filtering)
-            const tableRefs = a.findTableReferences(ast, adapter, sourceCode, schemaConfig, provenanceContext, allTables);
+            const tableRefs = findTableReferences(ast, adapter, sourceCode, { config: schemaConfig, provenanceContext, allTables });
             // Record schema usage → emit as indexFacts via the shared instance
             a.recordTableUsage(ast, adapter, context.filePath, tableRefs);
             const pending = a.getPendingSchemaRecords();
@@ -901,14 +906,14 @@ export function createSchemaCodeVisitor() {
             }
             // Check naming conventions
             if (schemaConfig.checkNamingConventions !== false) {
-                violations.push(...a.checkNamingConventions(tableRefs, context.filePath));
+                violations.push(...checkNamingConventions(tableRefs, context.filePath));
             }
             // Check query patterns
             if (schemaConfig.validateQueryPatterns !== false) {
-                violations.push(...a.checkQueryPatterns(ast, adapter, sourceCode, schemaConfig));
+                violations.push(...checkQueryPatterns(ast, adapter, sourceCode, schemaConfig));
             }
             // Check SQL injection
-            violations.push(...a.checkSQLInjection(ast, adapter, sourceCode));
+            violations.push(...checkSQLInjection(ast, adapter, sourceCode));
             // Emit facts for the Stage 3 reducer
             const fileFacts = {
                 tableRefs: tableRefs.map((r) => ({
@@ -919,9 +924,10 @@ export function createSchemaCodeVisitor() {
                     context: r.context,
                 })),
                 ormTables,
+                tableProvenance: tableProvenances,
             };
             if (doDDL.length > 0)
-                fileFacts.ddlSource = doDDL.join(';\n');
+                fileFacts.ddlOps = parseMigrationOps(doDDL.join(';\n'));
             return {
                 violations,
                 facts: { [context.filePath]: fileFacts },
@@ -947,7 +953,23 @@ export function createSchemaPrismaVisitor() {
             const modelRe = /model\s+(\w+)\s*\{/g;
             let m;
             while ((m = modelRe.exec(sourceCode)) !== null) {
-                models.push(m[1]);
+                const modelName = m[1];
+                // Scope @@map to this model's block by matching braces.
+                // Depth starts at 1 for the opening { already consumed by the regex.
+                const blockStart = m.index + m[0].length;
+                let depth = 1;
+                let blockEnd = blockStart;
+                for (; blockEnd < sourceCode.length && depth > 0; blockEnd++) {
+                    if (sourceCode[blockEnd] === '{')
+                        depth++;
+                    else if (sourceCode[blockEnd] === '}')
+                        depth--;
+                }
+                const blockContent = sourceCode.slice(blockStart, blockEnd - 1);
+                // @@map (block-level, double @) renames the table. @map (single @)
+                // is field-level — column rename — and must not be treated as a table name.
+                const mapMatch = blockContent.match(/@@map\s*\(\s*"([^"]+)"\s*\)/);
+                models.push(mapMatch ? mapMatch[1] : modelName);
             }
             return {
                 violations: [],
@@ -968,17 +990,13 @@ export function createSchemaJsonVisitor() {
         stage: 'visitor',
         extensions: ['.json'],
         getRuleIds: () => [],
-        async visit(_ast, _adapter, context, sourceCode) {
-            let parsed = null;
-            try {
-                parsed = JSON.parse(sourceCode);
-            }
-            catch {
-                // Invalid JSON — skip
-            }
+        async visit(_ast, _adapter, context, _sourceCode) {
+            // Emit only a lightweight marker — the Stage 3 reducer reads and parses
+            // each JSON file on demand via context.readSource, so parsed objects are
+            // transient rather than retained in allFacts through stage 4.
             return {
                 violations: [],
-                facts: { [context.filePath]: { jsonParsed: parsed, jsonRaw: sourceCode } },
+                facts: { [context.filePath]: { isJson: true } },
             };
         },
         defaultConfig: {},
@@ -996,6 +1014,7 @@ export function createSchemaReducer() {
     const getAnalyzer = lazySingleton(() => import('./analyzers/universal/UniversalSchemaAnalyzer.js').then((m) => ({
         analyzer: new m.UniversalSchemaAnalyzer(),
         defaults: m.DEFAULT_SCHEMA_CONFIG,
+        analyzeJsonSchemas: m.analyzeJsonSchemas,
     })));
     return {
         name: 'schema',
@@ -1003,7 +1022,7 @@ export function createSchemaReducer() {
         consumes: [],
         getRuleIds: () => getRuleIdsFor('schema'),
         async reduce(allFacts, context) {
-            const { analyzer: a } = await getAnalyzer();
+            const { analyzer: a, analyzeJsonSchemas } = await getAnalyzer();
             const violations = [];
             const schemaConfig = (context.config ?? {});
             // allFacts is keyed by visitor name, each value is { [filePath]: { ...per-file facts } }
@@ -1021,11 +1040,12 @@ export function createSchemaReducer() {
             };
             // ── 1. Build known-tables catalog ──────────────────────────────────────
             const knownTables = new Set();
-            // 1a. SQL DDL replay — collect all .sql file facts, sort by numeric prefix, replay
+            const tableProvenances = new Map(); // table name → origins
+            // 1a. SQL DDL replay — collect all DDL facts, sort by numeric prefix, replay
             const sqlFiles = [];
             for (const [filePath, fact] of perFile()) {
-                if ('ddlSource' in fact) {
-                    sqlFiles.push({ filePath, source: fact.ddlSource });
+                if ('ddlOps' in fact) {
+                    sqlFiles.push({ filePath, ops: fact.ddlOps });
                 }
             }
             // Sort by numeric prefix in basename: "009_something" < "0010_rename"
@@ -1043,19 +1063,38 @@ export function createSchemaReducer() {
                 return a.filePath.localeCompare(b.filePath);
             });
             for (const sqlFile of sqlFiles) {
-                a.processMigrationSource(sqlFile.source, knownTables);
+                const before = new Set(knownTables);
+                applyMigrationOps(sqlFile.ops, knownTables);
+                // Record provenance for newly created tables
+                for (const table of knownTables) {
+                    if (!before.has(table)) {
+                        const sources = tableProvenances.get(table) ?? [];
+                        sources.push({ table, tier: 'sql-migration', sourceFile: sqlFile.filePath, description: 'SQL migration' });
+                        tableProvenances.set(table, sources);
+                    }
+                }
             }
-            // 1b. ORM tables from code files
-            for (const [, fact] of perFile()) {
+            // 1b. ORM tables from code files — with provenance from the table-source registry
+            for (const [filePath, fact] of perFile()) {
                 const ormTables = fact.ormTables ?? [];
                 for (const t of ormTables)
                     knownTables.add(t);
+                const provenances = fact.tableProvenance ?? [];
+                for (const p of provenances) {
+                    const sources = tableProvenances.get(p.table) ?? [];
+                    sources.push(p.source);
+                    tableProvenances.set(p.table, sources);
+                }
             }
             // 1c. Prisma models
-            for (const [, fact] of perFile()) {
+            for (const [filePath, fact] of perFile()) {
                 const prismaModels = fact.prismaModels ?? [];
-                for (const m of prismaModels)
+                for (const m of prismaModels) {
                     knownTables.add(m);
+                    const sources = tableProvenances.get(m) ?? [];
+                    sources.push({ table: m, tier: 'prisma-model', sourceFile: filePath, description: 'Prisma model' });
+                    tableProvenances.set(m, sources);
+                }
             }
             // ── 2. Unknown-table detection ────────────────────────────────────────
             //
@@ -1074,8 +1113,25 @@ export function createSchemaReducer() {
             // never enter the catalog (table refs are for checking, not building).
             // Merge external tables from config (bonus, not required).
             const externalKnownTables = schemaConfig.knownTables ?? [];
-            for (const t of externalKnownTables)
+            for (const t of externalKnownTables) {
                 knownTables.add(t);
+                const sources = tableProvenances.get(t) ?? [];
+                sources.push({ table: t, tier: 'external-config', description: 'External configuration' });
+                tableProvenances.set(t, sources);
+            }
+            // Also read the documented schemas config (structured {name, tables} objects).
+            // The standalone UniversalSchemaAnalyzer.analyze() path reads schemas; the
+            // pipeline reducer must read it too, otherwise configuring only schemas
+            // silently triggers fail-open (knownTables.size === 0).
+            const externalSchemas = schemaConfig.schemas ?? [];
+            for (const schema of externalSchemas) {
+                for (const table of schema.tables) {
+                    knownTables.add(table.name);
+                    const sources = tableProvenances.get(table.name) ?? [];
+                    sources.push({ table: table.name, tier: 'external-config', description: `Schema: ${schema.name}` });
+                    tableProvenances.set(table.name, sources);
+                }
+            }
             if (knownTables.size > 0) {
                 // Collect all table references across all files
                 const allTableRefs = [];
@@ -1089,10 +1145,11 @@ export function createSchemaReducer() {
                 const unknownRefs = allTableRefs.filter(ref => !knownTables.has(ref.table));
                 if (unknownRefs.length / Math.max(knownTables.size, 1) <= 10) {
                     for (const ref of unknownRefs) {
-                        const suggestions = a.getNearestTableSuggestions(ref.table, knownTables, 2);
+                        const suggestions = getNearestTableSuggestions(ref.table, knownTables, 2);
                         const msg = suggestions.length > 0
                             ? `Reference to unknown table '${ref.table}' (${ref.type}). Did you mean: ${suggestions.join(', ')}?`
                             : `Reference to unknown table '${ref.table}' (${ref.type})`;
+                        const suggestionNames = suggestions.map((s) => s.replace(/^'|'$/g, ''));
                         violations.push({
                             file: ref.file,
                             line: ref.line,
@@ -1102,6 +1159,15 @@ export function createSchemaReducer() {
                             rule: 'unknown-table',
                             analyzer: 'schema',
                             symbol: ref.table,
+                            resolution: {
+                                action: suggestionNames.length > 0 ? 'use-known-table' : 'register-or-fix-table',
+                                summary: suggestionNames.length > 0
+                                    ? `Rename the table reference '${ref.table}' to the nearest known table: ${suggestions.join(', ')}.`
+                                    : `The table '${ref.table}' is not in the known catalog — register it, or fix the reference to a known table.`,
+                                symbols: suggestionNames.length > 0 ? suggestionNames : [ref.table],
+                                files: [ref.file],
+                                lines: [ref.line],
+                            },
                         });
                     }
                 }
@@ -1109,32 +1175,41 @@ export function createSchemaReducer() {
             // ── 3. JSON schema validation ──────────────────────────────────────────
             if (schemaConfig.validateJsonSchemas !== false) {
                 try {
-                    // Build content Map from json facts for the refactored analyzeJsonSchemas
-                    const jsonContents = new Map();
-                    let jsonFactCount = 0;
+                    // Collect JSON file paths from the lightweight visitor markers, then
+                    // parse each on demand so parsed objects never survive past this loop.
+                    const jsonFiles = [];
                     for (const [filePath, fact] of perFile()) {
-                        if ('jsonParsed' in fact) {
-                            jsonFactCount++;
-                            const raw = (fact.jsonParsed ?? null);
-                            // parsed is the result of JSON.parse: null on failure, or the
-                            // deserialized value. Only accept objects as usable parsed content.
-                            const parsed = raw !== null && typeof raw === 'object' ? raw : null;
-                            jsonContents.set(filePath, {
-                                parsed,
-                                raw: (fact.jsonRaw ?? fact.sourceCode ?? ''),
-                            });
+                        if ('isJson' in fact) {
+                            jsonFiles.push(filePath);
                         }
                     }
-                    const jsonResult = a.analyzeJsonSchemas(jsonContents, schemaConfig);
+                    const readJson = (filePath) => {
+                        const raw = context.readSource?.(filePath);
+                        if (raw === undefined)
+                            return null;
+                        try {
+                            const parsed = JSON.parse(raw);
+                            return parsed !== null && typeof parsed === 'object' ? parsed : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    };
+                    const jsonResult = analyzeJsonSchemas(jsonFiles, readJson, schemaConfig);
                     violations.push(...(jsonResult?.violations ?? []));
                 }
                 catch (e) {
                     // JSON schema validation is best-effort (non-fatal)
                 }
             }
+            // ── 4. Build table catalog for metadata ───────────────────────────────
+            const catalogEntries = [];
+            for (const [table, sources] of tableProvenances) {
+                catalogEntries.push({ table, sources });
+            }
             return {
                 violations,
-                facts: {},
+                facts: { tableCatalog: catalogEntries },
                 factsConsumed: [...perFile()].length,
             };
         },