code-auditor-mcp 3.4.17 → 3.5.0

package/dist/pipelineAdapters.js

@@ -18,6 +18,7 @@
 import { createHash } from 'crypto';
 import path from 'path';
 import { RULE_REGISTRY } from './analyzers/ruleRegistry.js';
+import { TYPESCRIPT_EXTENSIONS, JAVASCRIPT_EXTENSIONS, getLanguageFromPath } from './utils/fileDiscovery.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';
@@ -130,23 +131,6 @@ export function createDocumentationVisitor() {
 // to mine — even on a cold run with no prior `index sync`.
 // The function_calls table is rebuilt post-pipeline after functions rows have
 // their auto-increment IDs assigned.
-function getLanguageFromPath(filePath) {
-    const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
-    switch (ext) {
-        case '.ts':
-        case '.tsx':
-        case '.mts':
-        case '.cts':
-            return 'typescript';
-        case '.js':
-        case '.jsx':
-        case '.mjs':
-        case '.cjs':
-            return 'javascript';
-        default:
-            return 'unknown';
-    }
-}
 function computeContentHash(body, signature) {
     const normalized = (body ?? '').replace(/\s+/g, ' ').trim() + '|' + (signature ?? '').trim();
     return createHash('sha256').update(normalized).digest('hex');
@@ -479,18 +463,23 @@ export function createReactVisitor() {
                 return [];
             const violations = [];
             try {
-                const { checkCircularDependencies, checkErrorBoundaryUsage, checkRawElements, } = await import('./analyzers/reactAnalyzer.js');
+                const { checkCircularDependencies, checkErrorBoundaryUsage, checkRawElements, DEFAULT_REACT_CONFIG, } = await import('./analyzers/reactAnalyzer.js');
+                // Merge with defaults — mirrors the visitor's
+                // `{ ...DEFAULT_REACT_CONFIG, ...context.config }` so a partial config
+                // still yields every required field, and so the `react.*` flags set in
+                // .codeauditor.json reach the cross-component checks.
+                const cfg = { ...DEFAULT_REACT_CONFIG, ...(config ?? {}) };
                 // Build component tree and check for circular dependencies
                 const { buildComponentTree } = await import('./componentScanner.js');
                 const tree = buildComponentTree(scanResults);
                 violations.push(...checkCircularDependencies(tree));
                 // Check for missing error boundaries
-                if (config.requireErrorBoundaries !== false) {
+                if (cfg.requireErrorBoundaries !== false) {
                     violations.push(...checkErrorBoundaryUsage(scanResults));
                 }
                 // Check for raw element usage (Spec 10 R4)
-                if (config.rawElementCheck !== false) {
-                    violations.push(...checkRawElements(scanResults, config));
+                if (cfg.rawElementCheck !== false) {
+                    violations.push(...checkRawElements(scanResults, cfg));
                 }
             }
             catch {
@@ -535,6 +524,145 @@ export function createStylesCssVisitor() {
         category: 'style',
     };
 }
+/**
+ * Styles source visitor — extracts CSS-in-JS declarations and class usage from
+ * the TS/JS ASTs stage 1 already parsed. This replaces the re-parse the style
+ * indexer used to do (adapter.parse on every TS/JS file): stage 1 parses every
+ * TS/JS file for the other visitors regardless, so a second parse here only
+ * duplicated the ~55ms that remained in the scoped short-circuit gate.
+ *
+ * Extraction is unconditional — the visitor runs on every in-scope TS/JS file,
+ * emitting a fact (with a content hash) even when it yields no declarations.
+ * The reducer uses that fact to (a) drop stale rows for files that *lost* their
+ * styles and (b) skip re-writing files whose stored rows are already current.
+ */
+export function createStylesSourceVisitor() {
+    return {
+        name: 'styles-source',
+        stage: 'visitor',
+        extensions: [...TYPESCRIPT_EXTENSIONS, ...JAVASCRIPT_EXTENSIONS],
+        getRuleIds: () => [],
+        async visit(ast, adapter, context, sourceCode) {
+            // Lazy-load to avoid circular dependency issues at module load time.
+            const { extractDeclarations } = await import('./styles/styleExtractor.js');
+            const { extractClassUsage } = await import('./styles/styleIndexer.js');
+            const { loadTailwindConfig } = await import('./styles/tailwindConfigLoader.js');
+            const tsAst = ast;
+            const tsAdapter = adapter;
+            const filePath = context.filePath;
+            // Memoized per projectRoot (the style-index sync already called it this
+            // run), so this is a cache hit — never a re-walk of the project tree.
+            const tailwindTokens = loadTailwindConfig(context.projectRoot).tokens;
+            const declarations = extractDeclarations(filePath, tsAdapter, sourceCode, tsAst, tailwindTokens);
+            const classUsage = extractClassUsage(filePath, sourceCode);
+            const contentHash = createHash('sha256').update(sourceCode).digest('hex');
+            return {
+                violations: [],
+                facts: {
+                    [filePath]: { declarations, classUsage, contentHash },
+                },
+            };
+        },
+        defaultConfig: {},
+        description: 'Extracts CSS-in-JS declarations and class usage from TS/JS ASTs',
+        category: 'style',
+    };
+}
+/**
+ * Insert TS/JS CSS-in-JS facts (from the styles-source visitor) into the
+ * style_* tables. Mirrors the TS/JS branch the style indexer used to run
+ * (Spec 10), but with the parse removed — stage 1 already parsed these files.
+ *
+ * The content-hash skip is a DB-WRITE guard, not a parse guard: stage 1 parses
+ * every TS/JS file regardless and extraction is unconditional here, so the hash
+ * exists only to avoid re-writing a file whose stored rows are already current.
+ * This is the intended semantics — do not "restore" it back to a parse-time skip.
+ *
+ * Returns true when any file contributed a declaration or class-usage row (the
+ * scoped short-circuit signal, equivalent to the old `contributingFiles`).
+ */
+function insertSourceStyleFacts(indexHandle, sourceFacts, isScoped) {
+    if (!sourceFacts)
+        return false;
+    const entries = Object.entries(sourceFacts);
+    if (entries.length === 0)
+        return false;
+    const rawDb = indexHandle.rawDb;
+    const stmts = rawDb
+        ? {
+            getHash: rawDb.prepare('SELECT content_hash FROM style_declarations WHERE file_path = ? LIMIT 1'),
+            delDecl: rawDb.prepare('DELETE FROM style_declarations WHERE file_path = ?'),
+            delUsage: rawDb.prepare('DELETE FROM style_class_usage WHERE file_path = ?'),
+            delTok: rawDb.prepare('DELETE FROM style_tokens WHERE file_path = ?'),
+            delUnread: rawDb.prepare('DELETE FROM style_unread_sources WHERE file_path = ?'),
+            delClass: rawDb.prepare('DELETE FROM style_defined_classes WHERE file_path = ?'),
+            insDecl: rawDb.prepare('INSERT INTO style_declarations (property, raw_value, normalized_value, mechanism, file_path, line, context, variant_context, token_ref, content_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'),
+            insClass: rawDb.prepare('INSERT OR IGNORE INTO style_defined_classes (class_name, file_path) VALUES (?, ?)'),
+            insUsage: rawDb.prepare('INSERT INTO style_class_usage (class_name, file_path, line, mechanism, unresolvable) VALUES (?, ?, ?, ?, ?)'),
+        }
+        : null;
+    let contributed = false;
+    const insertOne = (filePath, facts) => {
+        if (facts.declarations.length > 0 || facts.classUsage.length > 0)
+            contributed = true;
+        // Full-run content-hash skip: leave already-current rows untouched. Scoped
+        // runs always re-write, matching the old style indexer's `if (!scoped)` guard.
+        if (!isScoped) {
+            const stored = stmts
+                ? stmts.getHash.get(filePath)
+                : indexHandle.query('SELECT content_hash FROM style_declarations WHERE file_path = ? LIMIT 1', [filePath])[0];
+            if (stored?.content_hash === facts.contentHash)
+                return;
+        }
+        // Delete stale rows — all five tables, mirroring the old deleteFileEntries
+        // so a file that *lost* its styles also loses its stale unread-sources row.
+        if (stmts) {
+            stmts.delDecl.run(filePath);
+            stmts.delUsage.run(filePath);
+            stmts.delTok.run(filePath);
+            stmts.delUnread.run(filePath);
+            stmts.delClass.run(filePath);
+        }
+        else {
+            indexHandle.run('DELETE FROM style_declarations WHERE file_path = ?', [filePath]);
+            indexHandle.run('DELETE FROM style_class_usage WHERE file_path = ?', [filePath]);
+            indexHandle.run('DELETE FROM style_tokens WHERE file_path = ?', [filePath]);
+            indexHandle.run('DELETE FROM style_unread_sources WHERE file_path = ?', [filePath]);
+            indexHandle.run('DELETE FROM style_defined_classes WHERE file_path = ?', [filePath]);
+        }
+        // Insert declarations (and their defined-class catalog entries).
+        for (const decl of facts.declarations) {
+            if (stmts) {
+                stmts.insDecl.run(decl.property, decl.rawValue, decl.normalizedValue ? JSON.stringify(decl.normalizedValue) : null, decl.mechanism, decl.filePath, decl.line, decl.context, decl.variantContext, decl.tokenRef, facts.contentHash);
+            }
+            else {
+                indexHandle.run('INSERT INTO style_declarations (property, raw_value, normalized_value, mechanism, file_path, line, context, variant_context, token_ref, content_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', [decl.property, decl.rawValue, decl.normalizedValue ? JSON.stringify(decl.normalizedValue) : null, decl.mechanism, decl.filePath, decl.line, decl.context, decl.variantContext, decl.tokenRef, facts.contentHash]);
+            }
+            if (decl.context) {
+                for (const m of decl.context.matchAll(/\.([a-zA-Z0-9_-]+)/g)) {
+                    if (stmts)
+                        stmts.insClass.run(m[1], decl.filePath);
+                    else
+                        indexHandle.run('INSERT OR IGNORE INTO style_defined_classes (class_name, file_path) VALUES (?, ?)', [m[1], decl.filePath]);
+                }
+            }
+        }
+        // Insert class usage.
+        for (const cu of facts.classUsage) {
+            if (stmts)
+                stmts.insUsage.run(cu.className, cu.filePath, cu.line, cu.mechanism, cu.unresolvable ? 1 : 0);
+            else
+                indexHandle.run('INSERT INTO style_class_usage (class_name, file_path, line, mechanism, unresolvable) VALUES (?, ?, ?, ?, ?)', [cu.className, cu.filePath, cu.line, cu.mechanism, cu.unresolvable ? 1 : 0]);
+        }
+    };
+    if (stmts)
+        rawDb.transaction(() => { for (const [fp, f] of entries)
+            insertOne(fp, f); })();
+    else
+        for (const [fp, f] of entries)
+            insertOne(fp, f);
+    return contributed;
+}
 /**
  * Styles reducer — runs all style detectors on existing style_* tables.
  * Uses the analyzer.analyze([]) pattern: passes an empty file list so the
@@ -553,32 +681,114 @@ export function createStylesReducer() {
         async reduce(_allFacts, context) {
             if (!context.indexHandle)
                 return { violations: [], facts: {} };
+            const indexHandle = context.indexHandle;
             try {
                 // ── Insert CSS visitor facts into style_* tables ──────────────────────
                 const cssFacts = _allFacts['styles-css'];
+                // ── Source (TS/JS CSS-in-JS) visitor facts ───────────────────────────
+                const sourceFacts = _allFacts['styles-source'];
+                // ── Insert source facts, then decide whether to short-circuit ────────
+                // The short-circuit fires when a scoped (changed/path-filtered) run has no
+                // style-bearing work: no in-scope .css/.scss facts, no TS/JS file that
+                // contributed a declaration/class-usage, and no markup file the style sync
+                // contributed. Skipping the full-corpus query + O(n²) detectors removes the
+                // ~590ms styles-reducer cost from the scoped gate.
+                //
+                // Source facts are inserted BEFORE the short-circuit so a scoped file that
+                // *lost* its styles still has its stale rows dropped (the insertion always
+                // runs; the analyzer is what gets skipped). `styles-*` facts are `{}` (empty
+                // object) when nothing matched (pipeline.ts seeds every visitor with an empty
+                // object), so test key-count rather than truthiness. `styleContributingFiles`
+                // is `undefined` when the style sync did not run — reducers must NOT
+                // short-circuit on `undefined`.
+                const hasCssFacts = !!cssFacts && Object.keys(cssFacts).length > 0;
+                const styleSyncContributedNothing = Array.isArray(context.styleContributingFiles) &&
+                    context.styleContributingFiles.length === 0;
+                const sourceContributed = insertSourceStyleFacts(indexHandle, sourceFacts, context.isScoped ?? false);
                 if (cssFacts) {
-                    const run = context.indexHandle.run.bind(context.indexHandle);
-                    for (const [filePath, facts] of Object.entries(cssFacts)) {
-                        // Delete old entries for this file (replaces the styleIndexer path)
-                        run('DELETE FROM style_declarations WHERE file_path = ?', [filePath]);
-                        run('DELETE FROM style_tokens WHERE file_path = ?', [filePath]);
-                        run('DELETE FROM style_class_usage WHERE file_path = ?', [filePath]);
-                        // Compute content hash for the file
-                        const contentStr = JSON.stringify({ declarations: facts.declarations.length, tokens: facts.tokens.length, classUsage: facts.classUsage.length });
-                        const contentHash = createHash('sha256').update(contentStr).digest('hex').slice(0, 16);
-                        // Insert declarations
-                        for (const decl of facts.declarations) {
-                            run('INSERT INTO style_declarations (property, raw_value, normalized_value, mechanism, file_path, line, context, variant_context, token_ref, content_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', [decl.property, decl.rawValue, JSON.stringify(decl.normalizedValue), decl.mechanism, decl.filePath, decl.line, decl.context, decl.variantContext, decl.tokenRef, contentHash]);
+                    // Prepare each statement once and run the whole re-insertion in a
+                    // single transaction. The prior code went through `indexHandle.run`,
+                    // which re-`prepare()`s the SQL on every call AND auto-commits per
+                    // statement — measured at 345ms for 5 files / ~13k declarations on
+                    // recall-protocol. Prepare-once + one transaction collapses that.
+                    const rawDb = context.indexHandle.rawDb;
+                    const stmts = rawDb
+                        ? {
+                            delDecl: rawDb.prepare('DELETE FROM style_declarations WHERE file_path = ?'),
+                            delTok: rawDb.prepare('DELETE FROM style_tokens WHERE file_path = ?'),
+                            delUsage: rawDb.prepare('DELETE FROM style_class_usage WHERE file_path = ?'),
+                            delClass: rawDb.prepare('DELETE FROM style_defined_classes WHERE file_path = ?'),
+                            insDecl: rawDb.prepare('INSERT INTO style_declarations (property, raw_value, normalized_value, mechanism, file_path, line, context, variant_context, token_ref, content_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'),
+                            insClass: rawDb.prepare('INSERT OR IGNORE INTO style_defined_classes (class_name, file_path) VALUES (?, ?)'),
+                            insTok: rawDb.prepare('INSERT INTO style_tokens (name, value, file_path, mechanism) VALUES (?, ?, ?, ?)'),
+                            insUsage: rawDb.prepare('INSERT INTO style_class_usage (class_name, file_path, line, mechanism, unresolvable) VALUES (?, ?, ?, ?, ?)'),
                         }
-                        // Insert tokens
-                        for (const tok of facts.tokens) {
-                            run('INSERT INTO style_tokens (name, value, file_path, mechanism) VALUES (?, ?, ?, ?)', [tok.name, tok.value, tok.filePath, tok.mechanism]);
-                        }
-                        // Insert class usage
-                        for (const cu of facts.classUsage) {
-                            run('INSERT INTO style_class_usage (class_name, file_path, line, mechanism, unresolvable) VALUES (?, ?, ?, ?, ?)', [cu.className, cu.filePath, cu.line, cu.mechanism, cu.unresolvable ? 1 : 0]);
+                        : null;
+                    const insertAll = () => {
+                        for (const [filePath, facts] of Object.entries(cssFacts)) {
+                            // Delete old entries for this file (replaces the styleIndexer path)
+                            if (stmts) {
+                                stmts.delDecl.run(filePath);
+                                stmts.delTok.run(filePath);
+                                stmts.delUsage.run(filePath);
+                                stmts.delClass.run(filePath);
+                            }
+                            else {
+                                indexHandle.run('DELETE FROM style_declarations WHERE file_path = ?', [filePath]);
+                                indexHandle.run('DELETE FROM style_tokens WHERE file_path = ?', [filePath]);
+                                indexHandle.run('DELETE FROM style_class_usage WHERE file_path = ?', [filePath]);
+                                indexHandle.run('DELETE FROM style_defined_classes WHERE file_path = ?', [filePath]);
+                            }
+                            // Compute content hash for the file
+                            const contentStr = JSON.stringify({ declarations: facts.declarations.length, tokens: facts.tokens.length, classUsage: facts.classUsage.length });
+                            const contentHash = createHash('sha256').update(contentStr).digest('hex').slice(0, 16);
+                            // Insert declarations
+                            for (const decl of facts.declarations) {
+                                if (stmts) {
+                                    stmts.insDecl.run(decl.property, decl.rawValue, JSON.stringify(decl.normalizedValue), decl.mechanism, decl.filePath, decl.line, decl.context, decl.variantContext, decl.tokenRef, contentHash);
+                                }
+                                else {
+                                    indexHandle.run('INSERT INTO style_declarations (property, raw_value, normalized_value, mechanism, file_path, line, context, variant_context, token_ref, content_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', [decl.property, decl.rawValue, JSON.stringify(decl.normalizedValue), decl.mechanism, decl.filePath, decl.line, decl.context, decl.variantContext, decl.tokenRef, contentHash]);
+                                }
+                                // Populate the defined-class catalog (Spec 45) from any class
+                                // selectors in the rule's context so styles/undefined-class can
+                                // resolve names via `style_defined_classes` instead of a
+                                // full-corpus regex scan over every declaration.
+                                if (decl.context) {
+                                    for (const m of decl.context.matchAll(/\.([a-zA-Z0-9_-]+)/g)) {
+                                        if (stmts)
+                                            stmts.insClass.run(m[1], decl.filePath);
+                                        else
+                                            indexHandle.run('INSERT OR IGNORE INTO style_defined_classes (class_name, file_path) VALUES (?, ?)', [m[1], decl.filePath]);
+                                    }
+                                }
+                            }
+                            // Insert tokens
+                            for (const tok of facts.tokens) {
+                                if (stmts)
+                                    stmts.insTok.run(tok.name, tok.value, tok.filePath, tok.mechanism);
+                                else
+                                    indexHandle.run('INSERT INTO style_tokens (name, value, file_path, mechanism) VALUES (?, ?, ?, ?)', [tok.name, tok.value, tok.filePath, tok.mechanism]);
+                            }
+                            // Insert class usage
+                            for (const cu of facts.classUsage) {
+                                if (stmts)
+                                    stmts.insUsage.run(cu.className, cu.filePath, cu.line, cu.mechanism, cu.unresolvable ? 1 : 0);
+                                else
+                                    indexHandle.run('INSERT INTO style_class_usage (class_name, file_path, line, mechanism, unresolvable) VALUES (?, ?, ?, ?, ?)', [cu.className, cu.filePath, cu.line, cu.mechanism, cu.unresolvable ? 1 : 0]);
+                            }
                         }
-                    }
+                    };
+                    if (rawDb)
+                        rawDb.transaction(insertAll)();
+                    else
+                        insertAll();
+                }
+                // Short-circuit on non-style-bearing scoped runs — the source and CSS
+                // facts above are already written (so stale rows are dropped); only the
+                // analyzer is skipped when nothing style-bearing changed.
+                if (context.isScoped && !hasCssFacts && !sourceContributed && styleSyncContributedNothing) {
+                    return { violations: [], facts: {} };
                 }
                 // ── Run the analyzer (queries the now-populated style_* tables) ───────
                 const { UniversalStylesAnalyzer } = await import('./analyzers/universal/UniversalStylesAnalyzer.js');
@@ -623,7 +833,12 @@ 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, readSource: context.readSource, exportsMap };
+                // Scoped/diff audits: thread the in-scope file set so the analyzer scopes
+                // its function/file queries to only the changed files. `_infra.files` are
+                // absolute; `functions.file_path` is also absolute (function-index visitor
+                // stores `context.filePath`), so the IN clause matches directly.
+                const scopedFiles = context.isScoped ? (context.config.files ?? []) : undefined;
+                const config = { ...context.config, indexHandle: context.indexHandle, projectRoot: context.projectRoot, readSource: context.readSource, exportsMap, scopedFiles, isScoped: context.isScoped };
                 const result = await analyzer.analyze([], config);
                 // Count the INPUT the conventions analyzer reads (the function index the
                 // function-index visitor populated), not the derived `conventions` table it
@@ -661,7 +876,11 @@ export function createCrossDomainReducer() {
             try {
                 const { CrossDomainAnalyzer } = await import('./analyzers/crossDomain/CrossDomainAnalyzer.js');
                 const analyzer = new CrossDomainAnalyzer();
-                const config = { ...context.config, indexHandle: context.indexHandle, projectRoot: context.projectRoot };
+                // Thread the in-scope file set (absolute, from _infra.files) so detectors
+                // anchor to changed files on diff audits; full audits keep the root-LIKE
+                // scope (resolveFileScope falls back when isScoped is false).
+                const scopedFiles = context.isScoped ? (context.config.files ?? []) : undefined;
+                const config = { ...context.config, indexHandle: context.indexHandle, projectRoot: context.projectRoot, scopedFiles, isScoped: context.isScoped };
                 const result = await analyzer.analyze([], config);
                 // Count DB rows consumed across primary cross-domain tables
                 let factsConsumed = 0;
@@ -689,6 +908,543 @@ export function createCrossDomainReducer() {
         category: 'architecture',
     };
 }
+// ── Cross-language entity extraction + Stage-4 reducers ──────────────────────
+//
+// The three cross-language analyzers (SchemaValidator, APIContractAnalyzer,
+// DependencyGraphBuilder) are corpus-wide: they compare schemas/endpoints/cycles
+// across files and languages. They run as Stage-4 derived reducers over a single
+// shared entity-extraction visitor, so each analyzer's rule IDs map to its own
+// result row (coverage resolves by RULE_REGISTRY analyzer name — one reducer per
+// analyzer, not one reducer fanning out to three names).
+//
+// Scope-awareness ("Stage 4, and measure the gate"): the corpus-wide graph/cycle
+// work is only meaningful on a full audit. On a scoped/diff run each reducer
+// short-circuits with `notRunReason` BEFORE any corpus-wide work — the gate is in
+// the design, not retrofitted after the budget blows. This is the shape that made
+// the styles reducer 587ms; it must never run over a partial corpus.
+// ── Raw-node helpers (tree-sitter raw nodes are `any` here — strict is off) ──
+function clRawField(raw, field) {
+    return typeof raw?.childForFieldName === 'function' ? raw.childForFieldName(field) : null;
+}
+function clRawNamedChild(raw, type) {
+    return raw?.namedChildren?.find((c) => c.type === type) ?? null;
+}
+/** A function body node — `statement_block` (TS/JS) or `block` (Go). */
+function clRawBody(raw) {
+    return raw?.namedChildren?.find((c) => c.type === 'statement_block' || c.type === 'block') ?? null;
+}
+function clSignatureText(raw, sourceCode) {
+    if (!raw)
+        return '';
+    const body = clRawBody(raw);
+    const end = body ? body.startIndex : raw.endIndex;
+    return sourceCode.slice(raw.startIndex, end).trim();
+}
+function clBodyText(raw, sourceCode) {
+    const body = clRawBody(raw);
+    return body ? sourceCode.slice(body.startIndex, body.endIndex) : '';
+}
+/** Prefer the `name` field (works across TS + Go), fall back to identifier children. */
+function clNodeName(raw) {
+    const field = clRawField(raw, 'name');
+    if (field?.text)
+        return field.text;
+    const id = clRawNamedChild(raw, 'identifier') ?? clRawNamedChild(raw, 'property_identifier');
+    return id?.text;
+}
+function clEntityId(filePath, type, name, line) {
+    return `${filePath}::${type}::${name}::${line}`;
+}
+function clIsExportedGo(name) {
+    return name.length > 0 && name[0] === name[0].toUpperCase();
+}
+/** Collect callee names from a function's body (TS `call_expression` / Go `call_expression`). */
+function clCollectCallees(raw) {
+    const names = new Set();
+    const walk = (node) => {
+        if (!node)
+            return;
+        if (node.type === 'call_expression') {
+            const fn = typeof node.childForFieldName === 'function'
+                ? node.childForFieldName('function')
+                : null;
+            const callee = fn ?? node.namedChildren?.[0];
+            const text = callee?.text?.trim();
+            if (text && /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(text)) {
+                names.add(text);
+            }
+        }
+        for (const child of node.namedChildren ?? [])
+            walk(child);
+    };
+    walk(raw);
+    return [...names];
+}
+function clMakeFunction(filePath, lang, name, line, signature, purpose, params, callees, exported, complexity) {
+    return {
+        id: clEntityId(filePath, 'function', name, line),
+        name,
+        language: lang,
+        file: filePath,
+        type: 'function',
+        signature,
+        parameters: params,
+        startLine: line,
+        visibility: exported ? 'public' : 'private',
+        complexity,
+        calls: [],
+        calledBy: [],
+        purpose,
+        context: '',
+        searchTokens: [name.toLowerCase()],
+        metadata: { callees },
+    };
+}
+// ── TS/JS extraction ─────────────────────────────────────────────────────────
+function clExtractTSParams(raw) {
+    const params = [];
+    const formal = clRawNamedChild(raw, 'formal_parameters');
+    for (const p of formal?.namedChildren ?? []) {
+        if (p.type !== 'required_parameter' && p.type !== 'optional_parameter')
+            continue;
+        const name = clRawField(p, 'name')?.text ?? clRawNamedChild(p, 'identifier')?.text;
+        if (!name)
+            continue;
+        const type = clRawField(p, 'type')?.text?.trim();
+        params.push({ name, type, optional: p.type === 'optional_parameter', language: 'typescript' });
+    }
+    return params;
+}
+function clExtractTSInterfaceParams(raw) {
+    const params = [];
+    const walk = (node) => {
+        if (!node)
+            return;
+        if (node.type === 'property_signature') {
+            const name = clRawField(node, 'name')?.text ?? clRawNamedChild(node, 'property_identifier')?.text;
+            if (!name)
+                return;
+            const type = clRawField(node, 'type')?.text?.trim();
+            const optional = node.children?.some((c) => c.type === '?') ?? false;
+            params.push({ name, type, optional, language: 'typescript' });
+        }
+        for (const child of node.namedChildren ?? [])
+            walk(child);
+    };
+    walk(raw);
+    return params;
+}
+function clExtractTSEntities(root, filePath, sourceCode, lang, out) {
+    walkAST(root, (node) => {
+        const raw = node.raw;
+        if (node.type === 'function_declaration' || node.type === 'method_definition') {
+            const name = clNodeName(raw);
+            if (!name)
+                return;
+            let displayName = name;
+            if (node.type === 'method_definition') {
+                let p = raw?.parent;
+                while (p) {
+                    if (p.type === 'class_declaration') {
+                        const cn = clNodeName(p);
+                        if (cn)
+                            displayName = `${cn}.${name}`;
+                        break;
+                    }
+                    p = p.parent;
+                }
+            }
+            const line = (raw?.startPosition?.row ?? 0) + 1;
+            out.push(clMakeFunction(filePath, lang, displayName, line, clSignatureText(raw, sourceCode) || raw?.text || '', clBodyText(raw, sourceCode), clExtractTSParams(raw), clCollectCallees(raw), isExported(node), calculateComplexity(node)));
+            return;
+        }
+        if (node.type === 'variable_declarator') {
+            const arrow = clRawNamedChild(raw, 'arrow_function');
+            if (!arrow)
+                return;
+            const name = clRawNamedChild(raw, 'identifier')?.text;
+            if (!name)
+                return;
+            const line = (raw?.startPosition?.row ?? 0) + 1;
+            out.push(clMakeFunction(filePath, lang, name, line, clSignatureText(arrow, sourceCode) || arrow?.text || '', clBodyText(arrow, sourceCode), [], clCollectCallees(arrow), isExported(node), calculateComplexity(node)));
+            return;
+        }
+        if (node.type === 'interface_declaration') {
+            const name = clNodeName(raw);
+            if (!name)
+                return;
+            const line = (raw?.startPosition?.row ?? 0) + 1;
+            out.push({
+                id: clEntityId(filePath, 'interface', name, line),
+                name,
+                language: lang,
+                file: filePath,
+                type: 'interface',
+                signature: raw?.text ?? '',
+                parameters: clExtractTSInterfaceParams(raw),
+                startLine: line,
+                visibility: isExported(node) ? 'public' : 'private',
+                calls: [],
+                calledBy: [],
+                purpose: '',
+                context: '',
+                searchTokens: [name.toLowerCase()],
+                metadata: {},
+            });
+            return;
+        }
+    });
+}
+// ── Go extraction ────────────────────────────────────────────────────────────
+function clGoReceiverType(receiver) {
+    for (const child of receiver?.namedChildren ?? []) {
+        if (child.type === 'parameter_declaration') {
+            const typeNode = clRawField(child, 'type');
+            if (typeNode)
+                return typeNode.text.replace(/^\*/, '');
+        }
+    }
+    return undefined;
+}
+function clExtractGoParams(raw) {
+    const params = [];
+    const paramList = clRawField(raw, 'parameters');
+    for (const p of paramList?.namedChildren ?? []) {
+        if (p.type !== 'parameter_declaration')
+            continue;
+        const name = clRawField(p, 'name')?.text ?? clRawField(p, 'type')?.text;
+        const type = clRawField(p, 'type')?.text?.trim();
+        if (!name && !type)
+            continue;
+        params.push({ name: name ?? type ?? '<unknown>', type, optional: false, language: 'go' });
+    }
+    return params;
+}
+function clExtractGoStructFields(structNode) {
+    const fields = [];
+    for (const f of structNode?.namedChildren ?? []) {
+        if (f.type !== 'field_declaration')
+            continue;
+        const name = clRawField(f, 'name')?.text;
+        if (!name)
+            continue;
+        const type = clRawField(f, 'type')?.text?.trim();
+        const tag = clRawField(f, 'tag')?.text;
+        fields.push({ name, type, isExported: clIsExportedGo(name), tag });
+    }
+    return fields;
+}
+function clExtractGoEntities(root, filePath, sourceCode, out) {
+    walkAST(root, (node) => {
+        const raw = node.raw;
+        if (node.type === 'function_declaration') {
+            const name = clNodeName(raw);
+            if (!name)
+                return;
+            const receiver = clRawField(raw, 'receiver');
+            const receiverType = receiver ? clGoReceiverType(receiver) : undefined;
+            const displayName = receiverType ? `${receiverType}.${name}` : name;
+            const line = (raw?.startPosition?.row ?? 0) + 1;
+            out.push(clMakeFunction(filePath, 'go', displayName, line, clSignatureText(raw, sourceCode) || raw?.text || '', clBodyText(raw, sourceCode), clExtractGoParams(raw), clCollectCallees(raw), clIsExportedGo(name), calculateComplexity(node)));
+            return;
+        }
+        if (node.type === 'type_declaration') {
+            for (const spec of raw?.namedChildren ?? []) {
+                if (spec.type !== 'type_spec')
+                    continue;
+                const name = clRawField(spec, 'name')?.text;
+                if (!name)
+                    continue;
+                const typeNode = clRawField(spec, 'type');
+                const line = (spec?.startPosition?.row ?? 0) + 1;
+                if (typeNode?.type === 'struct_type') {
+                    out.push({
+                        id: clEntityId(filePath, 'struct', name, line),
+                        name,
+                        language: 'go',
+                        file: filePath,
+                        type: 'struct',
+                        signature: spec?.text ?? '',
+                        parameters: [],
+                        startLine: line,
+                        visibility: clIsExportedGo(name) ? 'public' : 'private',
+                        calls: [],
+                        calledBy: [],
+                        purpose: '',
+                        context: '',
+                        searchTokens: [name.toLowerCase()],
+                        metadata: { fields: clExtractGoStructFields(typeNode) },
+                    });
+                }
+                else if (typeNode?.type === 'interface_type') {
+                    out.push({
+                        id: clEntityId(filePath, 'interface', name, line),
+                        name,
+                        language: 'go',
+                        file: filePath,
+                        type: 'interface',
+                        signature: spec?.text ?? '',
+                        parameters: [],
+                        startLine: line,
+                        visibility: clIsExportedGo(name) ? 'public' : 'private',
+                        calls: [],
+                        calledBy: [],
+                        purpose: '',
+                        context: '',
+                        searchTokens: [name.toLowerCase()],
+                        metadata: {},
+                    });
+                }
+            }
+            return;
+        }
+    });
+}
+// ── Shared entity visitor (Stage 2) ──────────────────────────────────────────
+export function createCrossLanguageEntityVisitor() {
+    return {
+        name: 'cross-language-entities',
+        stage: 'visitor',
+        extensions: ['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs', '.go'],
+        getRuleIds: () => [],
+        async visit(ast, _adapter, context, sourceCode) {
+            const filePath = context.filePath;
+            if (!filePath)
+                return { violations: [], facts: {} };
+            const lang = getLanguageFromPath(filePath);
+            if (lang === 'unknown')
+                return { violations: [], facts: {} };
+            const root = ast.root;
+            const entities = [];
+            if (lang === 'go') {
+                clExtractGoEntities(root, filePath, sourceCode, entities);
+            }
+            else {
+                clExtractTSEntities(root, filePath, sourceCode, lang, entities);
+            }
+            return {
+                violations: [],
+                facts: { [filePath]: { entities } },
+            };
+        },
+        defaultConfig: {},
+        description: 'Extracts cross-language entities (functions, structs, interfaces) for the cross-language analyzers',
+        category: 'infrastructure',
+    };
+}
+// ── Shared flatten + reference building ──────────────────────────────────────
+function clFlattenEntities(allFacts) {
+    const facts = allFacts['cross-language-entities'];
+    if (!facts)
+        return [];
+    const entities = [];
+    for (const data of Object.values(facts)) {
+        if (data?.entities)
+            entities.push(...data.entities);
+    }
+    return entities;
+}
+/**
+ * Build `calls` cross-references by resolving each entity's extracted callee
+ * names against the corpus entity name index. Library calls (fetch, map, …)
+ * resolve to nothing and are dropped — only real intra-corpus call edges become
+ * references.
+ */
+function clBuildReferences(entities) {
+    const byName = new Map();
+    for (const e of entities) {
+        const key = e.name.toLowerCase();
+        const list = byName.get(key) ?? [];
+        list.push(e);
+        byName.set(key, list);
+    }
+    const refs = [];
+    for (const e of entities) {
+        const callees = e.metadata?.callees ?? [];
+        const eDir = e.file.split('/').slice(0, -1).join('/');
+        for (const callee of callees) {
+            const name = (callee.split('.').pop() ?? callee).toLowerCase();
+            const others = (byName.get(name) ?? []).filter((t) => t.id !== e.id);
+            if (others.length === 0)
+                continue;
+            // A bare call-expression name (`log`) can collide with many entities
+            // across the corpus. Resolving it to *every* entity of that name
+            // fabricates a dense graph (125k edges / 5.9k false cycles on a ~7.8k
+            // node corpus) that corrupts cycle/hub/coupling detection. Narrow the
+            // resolution to an unambiguous match — same file, then same directory,
+            // then a unique global match — and drop the edge when the name is still
+            // ambiguous: a missing edge is safer than a fabricated one for
+            // structural analysis.
+            const sameFile = others.filter((t) => t.file === e.file);
+            const sameDir = sameFile.length === 0
+                ? others.filter((t) => t.file.split('/').slice(0, -1).join('/') === eDir)
+                : [];
+            const uniqueGlobal = others.length === 1 ? others : [];
+            const chosen = sameFile.length === 1
+                ? sameFile
+                : sameDir.length === 1
+                    ? sameDir
+                    : uniqueGlobal;
+            for (const t of chosen) {
+                refs.push({
+                    sourceId: e.id,
+                    targetId: t.id,
+                    type: 'calls',
+                    sourceLanguage: e.language,
+                    targetLanguage: t.language,
+                    confidence: 0.7,
+                });
+            }
+        }
+    }
+    return refs;
+}
+// ── schema-validator reducer (Stage 4) ───────────────────────────────────────
+export function createSchemaValidatorReducer() {
+    return {
+        name: 'schema-validator',
+        stage: 'derivedReducer',
+        consumes: ['cross-language-entities'],
+        getRuleIds: () => getRuleIdsFor('schema-validator'),
+        async reduce(allFacts, context) {
+            if (context.isScoped) {
+                return {
+                    violations: [],
+                    facts: {},
+                    notRunReason: 'schema-validator requires a full-corpus audit (cross-language schema comparison is unavailable on scoped/diff runs)',
+                };
+            }
+            const entities = clFlattenEntities(allFacts);
+            if (entities.length === 0)
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            try {
+                const { SchemaValidator, extractSchemas, countCrossLanguagePairs } = await import('./analyzers/cross-language/SchemaValidator.js');
+                const schemas = extractSchemas(entities);
+                // A zero here would otherwise surface as `clean` in coverage — which
+                // reads as "compared everything and found no mismatch" when the truth
+                // is "there is nothing to compare". Distinguish the two: no schemas at
+                // all, or schemas all in one language, is `notApplicable`, not `clean`.
+                if (schemas.length === 0) {
+                    return { violations: [], facts: {}, notRunReason: 'no schema definitions found (no interfaces/structs to compare)' };
+                }
+                if (countCrossLanguagePairs(schemas) === 0) {
+                    return { violations: [], facts: {}, notRunReason: 'no cross-language pairs found (schema comparison requires ≥2 languages)' };
+                }
+                const validator = new SchemaValidator();
+                const violations = await validator.validateSchemas(schemas);
+                return { violations, facts: {}, factsConsumed: schemas.length };
+            }
+            catch (e) {
+                console.error('[schema-validator reducer] error:', e.message);
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            }
+        },
+        defaultConfig: {},
+        description: 'Validates schema consistency across language boundaries (TS interfaces vs Go structs)',
+        category: 'cross-language',
+    };
+}
+// ── api-contract reducer (Stage 4) ───────────────────────────────────────────
+export function createAPIContractReducer() {
+    return {
+        name: 'api-contract',
+        stage: 'derivedReducer',
+        consumes: ['cross-language-entities'],
+        getRuleIds: () => getRuleIdsFor('api-contract'),
+        async reduce(allFacts, context) {
+            if (context.isScoped) {
+                return {
+                    violations: [],
+                    facts: {},
+                    notRunReason: 'api-contract requires a full-corpus audit (cross-language API comparison is unavailable on scoped/diff runs)',
+                };
+            }
+            const entities = clFlattenEntities(allFacts);
+            if (entities.length === 0)
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            try {
+                const { APIContractAnalyzer, extractEndpoints, extractAPICalls } = await import('./analyzers/cross-language/APIContractAnalyzer.js');
+                const endpoints = extractEndpoints(entities);
+                const calls = extractAPICalls(entities);
+                const analyzer = new APIContractAnalyzer();
+                const violations = await analyzer.analyzeContracts(endpoints, calls);
+                return { violations, facts: {}, factsConsumed: endpoints.length + calls.length };
+            }
+            catch (e) {
+                console.error('[api-contract reducer] error:', e.message);
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            }
+        },
+        defaultConfig: {},
+        description: 'Validates API contracts between frontend calls and backend endpoints across languages',
+        category: 'cross-language',
+    };
+}
+// ── dependency-graph reducer (Stage 4) ───────────────────────────────────────
+export function createDependencyGraphReducer() {
+    return {
+        name: 'dependency-graph',
+        stage: 'derivedReducer',
+        consumes: ['cross-language-entities'],
+        getRuleIds: () => getRuleIdsFor('dependency-graph'),
+        async reduce(allFacts, context) {
+            if (context.isScoped) {
+                return {
+                    violations: [],
+                    facts: {},
+                    notRunReason: 'dependency-graph requires a full-corpus audit (cycle/SCC/hub/orphan detection is unavailable on scoped/diff runs)',
+                };
+            }
+            const entities = clFlattenEntities(allFacts);
+            if (entities.length === 0)
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            try {
+                const { DependencyGraphBuilder } = await import('./analyzers/cross-language/DependencyGraphBuilder.js');
+                const builder = new DependencyGraphBuilder({ includeTestFiles: false });
+                const references = clBuildReferences(entities);
+                const graph = await builder.buildGraph(entities, references);
+                const health = await builder.analyzeDependencyHealth(graph);
+                const idToEntity = new Map(entities.map((e) => [e.id, e]));
+                const violations = [];
+                for (const issue of health.issues) {
+                    const anchor = issue.affectedNodes.map((id) => idToEntity.get(id)).find(Boolean);
+                    violations.push({
+                        file: anchor?.file ?? '(unknown)',
+                        line: anchor?.startLine ?? 0,
+                        severity: issue.severity,
+                        message: issue.description,
+                        rule: issue.type,
+                        type: issue.type, // dependency-graph rules match on field: 'type'
+                        analyzer: 'dependency-graph',
+                        category: 'cross-language-dependency',
+                        details: issue.details,
+                    });
+                }
+                for (const s of health.suggestions) {
+                    violations.push({
+                        file: '(multiple)',
+                        line: 0,
+                        severity: s.priority === 'low' ? 'suggestion' : 'warning',
+                        message: s.description,
+                        rule: s.type,
+                        type: s.type,
+                        analyzer: 'dependency-graph',
+                        category: 'cross-language-dependency',
+                        details: s.affectedNodes ? { affectedNodes: s.affectedNodes } : undefined,
+                    });
+                }
+                return { violations, facts: {}, factsConsumed: entities.length };
+            }
+            catch (e) {
+                console.error('[dependency-graph reducer] error:', e.message);
+                return { violations: [], facts: {}, factsConsumed: 0 };
+            }
+        },
+        defaultConfig: {},
+        description: 'Builds a cross-language dependency graph and detects cycles, hubs, orphans, and tight coupling',
+        category: 'cross-language',
+    };
+}
 // ── Invariants reducer (stage 3) ──────────────────────────────────────────────
 /**
  * Invariants reducer — enforces user-defined invariant rules from .codeauditor.json.
@@ -748,7 +1504,7 @@ export function createInvariantsReducer() {
                         }
                     }
                 }
-                const result = await analyzeInvariants(files, { ...context.config, readSource: context.readSource, knownFiles, fileData }, { projectRoot: context.projectRoot, indexHandle: context.indexHandle });
+                const result = await analyzeInvariants(files, { ...context.config, readSource: context.readSource, knownFiles, fileData, isScoped: context.isScoped }, { projectRoot: context.projectRoot, indexHandle: context.indexHandle });
                 return {
                     violations: result.violations ?? [],
                     facts: {},