@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cpg/language-parser-walk.js

@@ -0,0 +1,917 @@
+'use strict';
+// Single source of truth for the per-language symbol/edge tree-walking
+// logic. Called from BOTH the inline (production) parse path and the
+// jest-only worker_thread path in language-parser.ts / language-parser-worker.js,
+// so the two paths are guaranteed to produce byte-identical results — there
+// is no second copy of this logic anywhere to drift out of sync.
+// @implements A-SPEC-121.6
+// Table-driven per-language node-type config that drives the single shared
+// lexical symbol walk below (walkSymbols). Adding a new language is meant to
+// be exactly one entry here — the walk itself should not need to change.
+//
+// Fields:
+//   classTypes          node types that open a class scope; the class's name
+//                        is read via childForFieldName('name'); entering one
+//                        sets `enclosingClass` to that name for its children.
+//   funcTypes            function/method node types whose "is this a method"
+//                        status depends on lexical context (see
+//                        funcIsMethodInClass) rather than the node type
+//                        itself.
+//   methodTypes          node types that are ALWAYS a method when lexically
+//                        inside a class (e.g. TypeScript's method_definition,
+//                        which is also used for object-literal methods —
+//                        those have no enclosing class and are skipped so we
+//                        don't emit spurious unqualified method symbols).
+//   funcIsMethodInClass  when true, a funcTypes node lexically inside a class
+//                        becomes a method (qualified `Class.name`); when
+//                        false (as for TypeScript, which has a dedicated
+//                        methodTypes node type instead), a funcTypes node is
+//                        always a plain function regardless of context.
+//                        This flag also controls the nested-def reset rule:
+//                        recursing into a funcTypes node resets
+//                        enclosingClass to null for its children ONLY when
+//                        funcIsMethodInClass is true — i.e. only for
+//                        languages (like Python) where a nested def's
+//                        method-ness is context-sensitive, so a def nested
+//                        inside another def must not be mistaken for a method
+//                        of the outer class. Languages with a dedicated
+//                        methodTypes node (TypeScript) don't reset here,
+//                        matching their original (pre-refactor) behavior.
+const LANG_CONFIG = {
+    typescript: {
+        classTypes: ['class_declaration'],
+        funcTypes: ['function_declaration'],
+        methodTypes: ['method_definition'],
+        funcIsMethodInClass: false,
+    },
+    python: {
+        classTypes: ['class_definition'],
+        funcTypes: ['function_definition'],
+        methodTypes: [],
+        funcIsMethodInClass: true,
+    },
+    // @implements A-SPEC-121.6
+    // C# is lexical, like TypeScript: class/struct/interface/record all open a
+    // class-like scope (all have a `name` field), and method_declaration is
+    // ALWAYS a method node type — never a plain function, never context-
+    // sensitive — so funcTypes stays empty and funcIsMethodInClass is false,
+    // mirroring the typescript shape rather than python's.
+    csharp: {
+        classTypes: ['class_declaration', 'struct_declaration', 'interface_declaration', 'record_declaration'],
+        funcTypes: [],
+        methodTypes: ['method_declaration'],
+        funcIsMethodInClass: false,
+    },
+    // @implements A-SPEC-121.6
+    // Java is lexical, like C#: class/interface/enum/record all open a
+    // class-like scope (all have a `name` field), and method_declaration is
+    // ALWAYS a method node type — never a plain function, never context-
+    // sensitive — so funcTypes stays empty and funcIsMethodInClass is false,
+    // mirroring the csharp shape.
+    java: {
+        classTypes: ['class_declaration', 'interface_declaration', 'enum_declaration', 'record_declaration'],
+        funcTypes: [],
+        methodTypes: ['method_declaration'],
+        funcIsMethodInClass: false,
+    },
+};
+// tsx shares the exact same node-type vocabulary as typescript.
+LANG_CONFIG.tsx = LANG_CONFIG.typescript;
+// One shared lexical walk driven entirely by LANG_CONFIG. Reproduces, node
+// for node, both the original TypeScript walk (method_definition is always a
+// method node, skipped when it has no enclosing class — the object-literal-
+// method case) and the original Python walk (function_definition is a method
+// only when lexically inside a class, and recursing into ANY def resets
+// enclosingClass to null for its children, so a def nested inside a def is
+// never mistaken for a method of the outer class).
+function walkSymbols(tree, config) {
+    const out = [];
+    const visit = (node, enclosingClass) => {
+        const type = node.type;
+        if (config.classTypes.includes(type)) {
+            const nameNode = node.childForFieldName('name');
+            const name = nameNode ? nameNode.text : undefined;
+            if (name) {
+                out.push({
+                    name,
+                    kind: 'class',
+                    qualifiedName: name,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+            const childClass = name || enclosingClass;
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), childClass);
+            return;
+        }
+        if (config.funcTypes.includes(type)) {
+            const nameNode = node.childForFieldName('name');
+            const name = nameNode ? nameNode.text : undefined;
+            if (name) {
+                const isMethod = config.funcIsMethodInClass && !!enclosingClass;
+                const kind = isMethod ? 'method' : 'function';
+                const qualifiedName = isMethod ? `${enclosingClass}.${name}` : name;
+                out.push({
+                    name,
+                    kind,
+                    qualifiedName,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+            // Nested-def reset rule (see funcIsMethodInClass doc above): only
+            // context-sensitive languages (Python) reset enclosingClass to null
+            // here; languages with a dedicated methodTypes node (TypeScript) carry
+            // enclosingClass through unchanged, matching original behavior.
+            const childEnclosing = config.funcIsMethodInClass ? null : enclosingClass;
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), childEnclosing);
+            return;
+        }
+        if (config.methodTypes.includes(type)) {
+            const nameNode = node.childForFieldName('name');
+            if (nameNode) {
+                const name = nameNode.text;
+                // Only emit method symbols for genuine class members
+                // (enclosingClass !== null). Skip object-literal methods, which have
+                // no enclosing class, to avoid spurious unqualified method symbols.
+                if (enclosingClass) {
+                    out.push({
+                        name,
+                        kind: 'method',
+                        qualifiedName: `${enclosingClass}.${name}`,
+                        startLine: node.startPosition.row + 1,
+                        endLine: node.endPosition.row + 1,
+                    });
+                }
+            }
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), enclosingClass);
+            return;
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i), enclosingClass);
+    };
+    visit(tree.rootNode, null);
+    return out;
+}
+// @implements A-SPEC-121.6
+// Go is NOT lexical the way TypeScript/Python/C#/Java are: Go has no class
+// construct at all, and a method's qualifying "owner" is its RECEIVER TYPE
+// (`func (t T) M(){}` -> `T.M`), not lexical nesting inside a class-like
+// scope. Reusing walkSymbols'/LANG_CONFIG's enclosingClass model would be
+// actively wrong for Go (there is nothing to lexically nest into), so Go
+// gets its own dedicated walker instead of a LANG_CONFIG table entry.
+function walkGoSymbols(tree) {
+    const out = [];
+    // Descend through a receiver's (possibly pointer, possibly generic) type to
+    // the underlying type name, e.g. `(t T)` -> 'T', `(p *T)` -> 'T',
+    // `(t T[V])` -> 'T', `(p *T[V])` -> 'T' (Go 1.18+ generic receivers). The
+    // qualifying name is always the bare type name — never '*T', never 'T[V]' —
+    // so an RTM `T.Method` lookup resolves regardless of pointer/generic form.
+    const receiverTypeName = (methodDeclNode) => {
+        const receiver = methodDeclNode.childForFieldName('receiver');
+        if (!receiver)
+            return undefined;
+        const paramDecl = receiver.namedChild(0);
+        if (!paramDecl)
+            return undefined;
+        let typeNode = paramDecl.childForFieldName('type');
+        if (!typeNode)
+            return undefined;
+        if (typeNode.type === 'pointer_type')
+            typeNode = typeNode.namedChild(0);
+        // generic_type is `BaseType[TypeArgs]`; its first named child is the base
+        // type_identifier. Unwrap it so `T[V]` qualifies as `T`.
+        if (typeNode && typeNode.type === 'generic_type')
+            typeNode = typeNode.namedChild(0);
+        return typeNode ? typeNode.text : undefined;
+    };
+    const visit = (node) => {
+        const type = node.type;
+        if (type === 'function_declaration') {
+            const nameNode = node.childForFieldName('name');
+            if (nameNode) {
+                out.push({
+                    name: nameNode.text,
+                    kind: 'function',
+                    qualifiedName: nameNode.text,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+        }
+        else if (type === 'type_declaration') {
+            // A type_declaration can group multiple type_spec nodes (`type ( A
+            // struct{}; B struct{} )`); each spec is emitted with its OWN line
+            // range, not the enclosing type_declaration's.
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const spec = node.namedChild(i);
+                // `type_spec` = a normal named type (`type T struct{}`, `type C float64`);
+                // `type_alias` = the `=` alias form (`type Alias = int`). Both name a
+                // type and are emitted as a class-kind symbol; only these two node
+                // types carry a type name here.
+                if (spec.type !== 'type_spec' && spec.type !== 'type_alias')
+                    continue;
+                const nameNode = spec.childForFieldName('name');
+                if (nameNode) {
+                    out.push({
+                        name: nameNode.text,
+                        kind: 'class',
+                        qualifiedName: nameNode.text,
+                        startLine: spec.startPosition.row + 1,
+                        endLine: spec.endPosition.row + 1,
+                    });
+                }
+            }
+        }
+        else if (type === 'method_declaration') {
+            const nameNode = node.childForFieldName('name');
+            const recvType = receiverTypeName(node);
+            if (nameNode && recvType) {
+                out.push({
+                    name: nameNode.text,
+                    kind: 'method',
+                    qualifiedName: `${recvType}.${nameNode.text}`,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(tree.rootNode);
+    return out;
+}
+// @implements A-SPEC-121.6
+// Rust, like Go, is NOT lexical the way TypeScript/Python/C#/Java are — but
+// unlike Go, it uses the IMPL-BLOCK method model: a method is a plain
+// `function_item` (the SAME node type as a top-level function) that happens
+// to be lexically nested inside an `impl_item`, and it is qualified by the
+// impl's TARGET TYPE (`impl S { fn m(&self){} }` -> `S.m`), not by a receiver
+// parameter the way Go methods are. `impl_item` itself never emits a class
+// symbol — it only opens a qualifying scope for the function_items nested
+// inside it — so this needs its own dedicated walker rather than a
+// LANG_CONFIG entry (walkSymbols' enclosingClass model assumes the "class"
+// node itself is the thing being named, which is exactly backwards for
+// impl_item: the impl names a type it is NOT a definition of).
+function walkRustSymbols(tree) {
+    const out = [];
+    // The `type` field of an impl_item names the type being implemented for
+    // (present on both `impl S {...}` and `impl T for S {...}` — the `trait`
+    // field, `T`, is deliberately ignored for qualification purposes: methods
+    // in a trait impl are qualified by the IMPLEMENTING type, not the trait).
+    // A generic impl's type field is a `generic_type` (`G<X>`) whose first
+    // named child is the base `type_identifier`; unwrap it so `G<X>` qualifies
+    // as bare `G`, mirroring walkGoSymbols' receiver generic_type unwrap.
+    const implTargetTypeName = (implNode) => {
+        let typeNode = implNode.childForFieldName('type');
+        if (!typeNode)
+            return undefined;
+        while (typeNode && typeNode.type !== 'type_identifier' && typeNode.namedChildCount > 0) {
+            // Unwrap to the bare type_identifier. For a module-path-qualified target
+            // (`scoped_type_identifier`, e.g. `a::S` / `crate::Foo`) the actual type
+            // is the LAST named child (`S`/`Foo`), not the first (which is the path
+            // segment `a`/`crate`). For `generic_type` (`G<X>` -> `G`),
+            // `reference_type` (`&S` -> `S`) and other wrappers the base is the first
+            // named child. Taking the first child on a scoped_type_identifier would
+            // drop qualification entirely (return undefined -> method mis-emitted as
+            // a bare unqualified function).
+            typeNode =
+                typeNode.type === 'scoped_type_identifier'
+                    ? typeNode.namedChild(typeNode.namedChildCount - 1)
+                    : typeNode.namedChild(0);
+        }
+        return typeNode && typeNode.type === 'type_identifier' ? typeNode.text : undefined;
+    };
+    const visit = (node, enclosingImplType) => {
+        const type = node.type;
+        if (type === 'struct_item' || type === 'enum_item' || type === 'trait_item') {
+            const nameNode = node.childForFieldName('name');
+            const name = nameNode ? nameNode.text : undefined;
+            if (name) {
+                out.push({
+                    name,
+                    kind: 'class',
+                    qualifiedName: name,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+            // A trait's DEFAULT-body methods (`trait T{ fn d(&self){} }`) are
+            // function_item nodes lexically nested directly inside the trait, with
+            // no enclosing impl_item — so trait_item must ALSO open a qualifying
+            // scope for its children, exactly like impl_item, or a default method
+            // would wrongly surface as an unqualified top-level function. Harmless
+            // for struct_item/enum_item, which never have function_item children
+            // directly (Rust has no inline-method syntax on structs/enums — only
+            // via a separate impl block, which sets its own qualifier regardless).
+            const childImplType = name || enclosingImplType;
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), childImplType);
+            return;
+        }
+        if (type === 'impl_item') {
+            // impl_item does NOT emit a class symbol of its own — it only opens a
+            // qualifying scope (the target type name) for its function_item
+            // children.
+            const implType = implTargetTypeName(node);
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), implType);
+            return;
+        }
+        if (type === 'function_item') {
+            const nameNode = node.childForFieldName('name');
+            const name = nameNode ? nameNode.text : undefined;
+            if (name) {
+                const isMethod = !!enclosingImplType;
+                out.push({
+                    name,
+                    kind: isMethod ? 'method' : 'function',
+                    qualifiedName: isMethod ? `${enclosingImplType}.${name}` : name,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+            // A function nested inside this function_item's body (a local fn) is
+            // never itself a method, regardless of whether THIS function_item was
+            // one — reset enclosingImplType to undefined for its children.
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), undefined);
+            return;
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i), enclosingImplType);
+    };
+    visit(tree.rootNode, undefined);
+    return out;
+}
+// @implements A-SPEC-121.6
+// C++ IS lexical (member functions live inside class_specifier/struct_specifier,
+// like TypeScript/Python/C#/Java) — but unlike those, the function's NAME is
+// never a direct `name` field on the definition node itself. A
+// `function_definition`'s name lives inside a `declarator` chain
+// (function_declarator -> identifier/field_identifier/qualified_identifier),
+// so walkSymbols' `childForFieldName('name')` model does not apply and C++
+// needs its own dedicated walker rather than a LANG_CONFIG entry.
+function walkCppSymbols(tree) {
+    const out = [];
+    // Descend through a function_declarator's `declarator` field to the
+    // underlying name node, unwrapping pointer/reference-returning-function
+    // wrappers (`int* foo()` / `int& foo()` parse the declarator as
+    // pointer_declarator/reference_declarator wrapping the function_declarator,
+    // or vice versa depending on nesting) until an identifier/field_identifier/
+    // qualified_identifier is reached, or giving up (undefined) if none is found.
+    const resolveDeclaratorName = (declNode) => {
+        let n = declNode;
+        while (n) {
+            if (n.type === 'identifier' || n.type === 'field_identifier' || n.type === 'qualified_identifier') {
+                return n;
+            }
+            if (n.type === 'function_declarator' || n.type === 'pointer_declarator' || n.type === 'reference_declarator') {
+                // `reference_declarator` (a reference-return function/method like
+                // `int& bar()` or `C& operator=(...)`) has NO named `declarator` field
+                // in tree-sitter-cpp — its wrapped declarator is its first named child.
+                // Falling back to namedChild(0) recovers the name instead of silently
+                // dropping the whole symbol. function_declarator/pointer_declarator do
+                // expose the `declarator` field, so this fallback only fires when the
+                // field is absent.
+                const next = n.childForFieldName('declarator') || n.namedChild(0);
+                if (!next || next === n)
+                    return undefined;
+                n = next;
+                continue;
+            }
+            return undefined;
+        }
+        return undefined;
+    };
+    const visit = (node, enclosingClass) => {
+        const type = node.type;
+        if (type === 'class_specifier' || type === 'struct_specifier') {
+            const nameNode = node.childForFieldName('name');
+            const name = nameNode ? nameNode.text : undefined;
+            if (name) {
+                out.push({
+                    name,
+                    kind: 'class',
+                    qualifiedName: name,
+                    startLine: node.startPosition.row + 1,
+                    endLine: node.endPosition.row + 1,
+                });
+            }
+            const childClass = name || enclosingClass;
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), childClass);
+            return;
+        }
+        if (type === 'function_definition') {
+            // The declarator field of a function_definition is a function_declarator
+            // (possibly wrapped in pointer_declarator/reference_declarator for a
+            // pointer/reference return type, e.g. `int* foo(){}` / `int& foo(){}`);
+            // resolveDeclaratorName unwraps those wrappers uniformly, drilling down
+            // to the innermost identifier/field_identifier/qualified_identifier.
+            const declarator = node.childForFieldName('declarator');
+            const nameNode = declarator ? resolveDeclaratorName(declarator) : undefined;
+            if (nameNode) {
+                const startLine = node.startPosition.row + 1;
+                const endLine = node.endPosition.row + 1;
+                if (nameNode.type === 'qualified_identifier') {
+                    // Out-of-line member definition, e.g. `void C::outOfLine(){}` or a
+                    // multi-segment `A::B::m` — the qualifying CLASS is always the
+                    // segment immediately before the LAST '::'; the method name is the
+                    // final segment.
+                    const segments = nameNode.text.split('::');
+                    const name = segments[segments.length - 1];
+                    const cls = segments.length > 1 ? segments[segments.length - 2] : undefined;
+                    if (name && cls) {
+                        out.push({
+                            name,
+                            kind: 'method',
+                            qualifiedName: `${cls}.${name}`,
+                            startLine,
+                            endLine,
+                        });
+                    }
+                }
+                else {
+                    // identifier -> plain function, unless lexically inside a class
+                    // (which shouldn't normally happen for a bare identifier declarator,
+                    // but is handled defensively); field_identifier -> always a member
+                    // function (only appears inside a class/struct body).
+                    const name = nameNode.text;
+                    const isMethod = nameNode.type === 'field_identifier' || !!enclosingClass;
+                    const kind = isMethod ? 'method' : 'function';
+                    const qualifiedName = isMethod && enclosingClass ? `${enclosingClass}.${name}` : name;
+                    out.push({ name, kind, qualifiedName, startLine, endLine });
+                }
+            }
+            // A function nested inside this function's body is never itself a
+            // method of the outer enclosing class merely by lexical accident, but
+            // C++ has no local function/class definitions inside a function body
+            // in the way Python does — recurse with enclosingClass unchanged is
+            // harmless here since function bodies can't contain further
+            // function_definition/class_specifier nodes at the top level we care
+            // about. Recurse into children (e.g. lambda bodies) preserving context.
+            for (let i = 0; i < node.childCount; i++)
+                visit(node.child(i), enclosingClass);
+            return;
+        }
+        // namespace_definition is deliberately NOT a class-like scope: a
+        // function_definition lexically inside a namespace is still a plain
+        // top-level FUNCTION (not qualified by the namespace) — so no special
+        // handling is needed here; it just falls through to the generic recurse
+        // below with enclosingClass unchanged (namespaces don't open a class scope).
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i), enclosingClass);
+    };
+    visit(tree.rootNode, undefined);
+    return out;
+}
+function extractSymbolsFromTree(tree, lang = 'typescript') {
+    if (lang === 'go')
+        return walkGoSymbols(tree);
+    if (lang === 'rust')
+        return walkRustSymbols(tree);
+    if (lang === 'cpp')
+        return walkCppSymbols(tree);
+    const config = LANG_CONFIG[lang] || LANG_CONFIG.typescript;
+    return walkSymbols(tree, config);
+}
+// @implements A-SPEC-136
+// Per-language call-edge extraction table, measured against the installed grammars. Adding a language
+// is one row here — the same table-driven shape symbol extraction already uses (LANG_CONFIG). The
+// shared walkEdges below reads it. `callTypes` is the call-node type; `calleeField` is the field
+// holding the callee (an identifier, or a member/selector node that walkEdges unwraps to its last
+// identifier segment); `scopeTypes` are the class/function nodes whose `name` builds the enclosing
+// qualified path (so a method's edges resolve to `Class.method`, matching the symbol walk).
+const EDGE_CONFIG = {
+    go: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_declaration', 'method_declaration'] },
+    rust: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_item'] },
+    java: { callTypes: ['method_invocation'], calleeField: 'name', scopeTypes: ['class_declaration', 'method_declaration'] },
+    csharp: { callTypes: ['invocation_expression'], calleeField: 'function', scopeTypes: ['class_declaration', 'method_declaration'] },
+    cpp: { callTypes: ['call_expression'], calleeField: 'function', scopeTypes: ['function_definition'] },
+};
+// The callee's bare name: a plain identifier is itself; a member/selector/scoped/field node
+// (`o.m`, `self.c`, `mod::f`, `this.C`) unwraps to its LAST identifier segment — the method name.
+// The receiver's type is never inferred (precision over recall); addCallEdges decides ambiguity.
+function calleeNameOf(node) {
+    if (!node)
+        return null;
+    if (node.type === 'identifier' || node.type === 'field_identifier')
+        return node.text;
+    // member/selector/scoped access: the last named child that is an identifier is the method name.
+    let last = null;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const c = node.namedChild(i);
+        if (c.type === 'identifier' || c.type === 'field_identifier')
+            last = c.text;
+    }
+    return last;
+}
+// @implements A-SPEC-136
+// The shared table-driven edge walk. `from` is the enclosing definition's QUALIFIED name (so it
+// matches the symbol node id and can be resolved), `to` is the bare callee name. A call the config
+// cannot read emits nothing — never a guessed edge.
+function walkEdges(tree, cfg) {
+    const out = [];
+    const scope = new Set(cfg.scopeTypes);
+    const callTypes = new Set(cfg.callTypes);
+    // A scope node's name. Most languages expose a `name` field; C++ nests it inside the declarator
+    // chain (function_definition → function_declarator → identifier), so fall back to descending
+    // `declarator` fields to the first identifier — otherwise a C++ function's edges would qualify to
+    // `<module>` and never resolve to its bare symbol name.
+    const scopeName = (n) => {
+        const nm = n.childForFieldName('name');
+        if (nm)
+            return nm.text;
+        let d = n.childForFieldName('declarator');
+        for (let hops = 0; d && hops < 5; hops++) {
+            if (d.type === 'identifier' || d.type === 'field_identifier')
+                return d.text;
+            if (d.type === 'qualified_identifier' || d.type === 'scoped_identifier')
+                return calleeNameOf(d); // last segment
+            d = d.childForFieldName('declarator');
+        }
+        return null;
+    };
+    const enclosing = (node) => {
+        const parts = [];
+        let n = node.parent;
+        while (n) {
+            if (scope.has(n.type)) {
+                const nm = scopeName(n);
+                if (nm)
+                    parts.unshift(nm);
+            }
+            n = n.parent;
+        }
+        return parts.length ? parts.join('.') : '<module>';
+    };
+    const visit = (node) => {
+        if (callTypes.has(node.type)) {
+            const callee = calleeNameOf(node.childForFieldName(cfg.calleeField));
+            if (callee)
+                out.push({ from: enclosing(node), to: callee, rel: 'calls' });
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(tree.rootNode);
+    return out;
+}
+function extractEdgesFromTree(tree, lang = 'typescript') {
+    // @implements A-SPEC-136
+    // Call edges ARE wired end-to-end: CpgScanner.scan populates ScannedFile.edges from here,
+    // addCallEdges resolves bare callee names to graph edges (precision-over-recall), and impactedBy
+    // traverses `callersOf`. TS/JS/Python have bespoke walks (kept for their import handling); the
+    // other five are table-driven (EDGE_CONFIG + walkEdges). See the CodeEdge comment in
+    // language-parser.ts.
+    if (lang === 'python')
+        return walkPythonEdges(tree);
+    if (EDGE_CONFIG[lang])
+        return walkEdges(tree, EDGE_CONFIG[lang]);
+    // TS/JS family: the original walk below (its import_statement handling is TS-grammar-specific).
+    if (lang !== 'typescript' && lang !== 'tsx')
+        return [];
+    const out = [];
+    // QUALIFIED, to match extractSymbolsFromTree: a method inside `class Foo` is `Foo.method`, which is
+    // the name the symbol walk emitted and therefore the only name a graph node can be resolved from.
+    // Returning the bare method name here would make every method's outgoing edges unresolvable.
+    const enclosingFn = (node) => {
+        const parts = [];
+        let n = node.parent;
+        while (n) {
+            if (n.type === 'function_declaration' || n.type === 'method_definition' || n.type === 'class_declaration') {
+                const nm = n.childForFieldName('name');
+                if (nm)
+                    parts.unshift(nm.text);
+            }
+            n = n.parent;
+        }
+        return parts.length ? parts.join('.') : '<module>';
+    };
+    const visit = (node) => {
+        if (node.type === 'import_statement') {
+            const src = node.childForFieldName('source') ?? (node.namedChildren && node.namedChildren.find((c) => c.type === 'string'));
+            if (src)
+                out.push({ from: '<module>', to: src.text.replace(/['"]/g, ''), rel: 'imports' });
+        }
+        else if (node.type === 'call_expression') {
+            const fn = node.childForFieldName('function');
+            if (fn && (fn.type === 'identifier' || fn.type === 'member_expression')) {
+                const property = fn.childForFieldName && fn.childForFieldName('property');
+                const callee = fn.type === 'identifier' ? fn.text : (property ? property.text : fn.text);
+                out.push({ from: enclosingFn(node), to: callee, rel: 'calls' });
+            }
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(tree.rootNode);
+    return out;
+}
+/**
+ * Python call/import edges.
+ *
+ * Mirrors the TS walk's contract exactly: `from` is the enclosing definition's QUALIFIED name (so it
+ * matches what extractSymbolsFromTree emitted for the same node and can be resolved to a graph node
+ * id), `to` is the bare callee name for calls and the module path for imports.
+ *
+ * PRECISION OVER RECALL, per the target architecture's D-CPG principle. Only forms whose target is
+ * syntactically evident are emitted: a direct `f()` or `obj.m()` call, and an `import x` /
+ * `from x import y`. Dynamic dispatch (`getattr(o, name)()`), `importlib.import_module(var)` and
+ * string-keyed registries produce NOTHING rather than a guessed edge — a wrong edge is worse than a
+ * missing one, because the missing one shows up as an unanchored gap while the wrong one silently
+ * corrupts every impact answer that traverses it.
+ */
+function walkPythonEdges(tree) {
+    const out = [];
+    // Qualified enclosing name: `Class.method` for a def inside a class, matching the symbol walk.
+    const enclosing = (node) => {
+        const parts = [];
+        let n = node.parent;
+        while (n) {
+            if (n.type === 'function_definition' || n.type === 'class_definition') {
+                const nm = n.childForFieldName('name');
+                if (nm)
+                    parts.unshift(nm.text);
+            }
+            n = n.parent;
+        }
+        return parts.length ? parts.join('.') : '<module>';
+    };
+    const moduleName = (n) => {
+        if (!n)
+            return '';
+        if (n.type === 'aliased_import') {
+            const nm = n.childForFieldName('name');
+            return nm ? nm.text : '';
+        }
+        return n.text;
+    };
+    const visit = (node) => {
+        if (node.type === 'import_statement') {
+            for (const c of node.namedChildren ?? []) {
+                const m = moduleName(c);
+                if (m)
+                    out.push({ from: '<module>', to: m, rel: 'imports' });
+            }
+        }
+        else if (node.type === 'import_from_statement') {
+            const m = moduleName(node.childForFieldName('module_name'));
+            if (m)
+                out.push({ from: '<module>', to: m, rel: 'imports' });
+        }
+        else if (node.type === 'call') {
+            const fn = node.childForFieldName('function');
+            if (fn && (fn.type === 'identifier' || fn.type === 'attribute')) {
+                // `obj.method()` -> `method`, matching the TS walk which takes the member expression's
+                // property. The receiver is not resolvable without type inference, which is out of scope.
+                const attr = fn.childForFieldName && fn.childForFieldName('attribute');
+                const callee = fn.type === 'identifier' ? fn.text : (attr ? attr.text : fn.text);
+                if (callee)
+                    out.push({ from: enclosing(node), to: callee, rel: 'calls' });
+            }
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(tree.rootNode);
+    return out;
+}
+// @implements A-SPEC-131
+// The ONE parse form both the inline and worker paths use. node-tree-sitter's parse(string) throws
+// 'Invalid argument' above 32,767 chars (measured: handlers.ts at 37,289 chars — silently dropped
+// from the graph for the project's entire history). An explicit bufferSize removes the cliff.
+//
+// MEASURED CONTRACT (adversarial-review sweep, 2026-08-06): the requirement is
+// bufferSize >= the input's UTF-16 LENGTH — not its UTF-8 byte length. handlers.ts (37,289 units)
+// fails at 32,768 and parses at 65,536; a 200K-unit Korean-heavy source fails at 65,536 regardless
+// of its ~2.9x UTF-8 expansion; a 600K-unit source parses with bufferSize below its byte length.
+// So `length * 2` over-provisions by design and NO input can re-introduce the cliff. Verified
+// tree-identical to string parsing on small input, and error-free on the previously-throwing file.
+function parseWithBuffer(parser, code) {
+    return parser.parse(code, undefined, { bufferSize: Math.max(1024 * 1024, code.length * 2 + 16) });
+}
+// @implements A-SPEC-140.1
+// Data-flow FACTS — the four kinds a def-use fixpoint needs, and nothing more. This layer performs
+// no analysis: it reports what the tree literally says, tagged with the enclosing function's
+// qualified name so the facts join the call graph produced by extractEdgesFromTree.
+//
+// The identity scheme is deliberately the SAME as the TS/JS edge walk's `enclosingFn` — a fact whose
+// `fn` did not match an edge's `from` would make every inter-procedural hop silently unresolvable,
+// which reads as "clean" rather than "not analysed". A test pins the two against each other.
+const DF_SCOPE_TYPES = new Set(['function_declaration', 'method_definition', 'class_declaration']);
+const DF_FUNC_TYPES = new Set([
+    'function_declaration', 'method_definition', 'function_expression', 'arrow_function', 'function',
+]);
+const EXPR_MAX = 200;
+// An expression as STRUCTURE, not text: `{ text, refs, callees }`.
+//
+// Text alone forces the propagation pass to ask "does this mention a tainted variable?" lexically,
+// and two ordinary lines break that: `const note = "raw user input";` falsely taints `note` because
+// the literal contains the word, and `exec(sanitize(raw))` looks tainted because the argument text
+// contains `raw` even though it was sanitized inline. Both are precisely the false positives REQ-140
+// exists to remove, so the structure is recovered HERE, from the tree, once.
+//
+// `refs` are the identifiers READ: a property name after a dot is not a read (`req.body.cmd` reads
+// only `req`), and a callee is not a read. `callees` are the invoked names, by the same last-segment
+// rule the edge walk uses. Both are deduped and in first-appearance order, which makes them
+// deterministic and diffable.
+function exprOf(node) {
+    const refs = [], callees = [];
+    const seenRef = new Set(), seenCallee = new Set();
+    if (!node)
+        return { text: '', refs, callees };
+    const addRef = (name) => { if (name && !seenRef.has(name)) {
+        seenRef.add(name);
+        refs.push(name);
+    } };
+    const addCallee = (name) => { if (name && !seenCallee.has(name)) {
+        seenCallee.add(name);
+        callees.push(name);
+    } };
+    const visit = (n) => {
+        if (n.type === 'call_expression') {
+            const fnNode = n.childForFieldName('function');
+            if (fnNode) {
+                if (fnNode.type === 'identifier') {
+                    addCallee(fnNode.text);
+                }
+                else if (fnNode.type === 'member_expression') {
+                    const prop = fnNode.childForFieldName('property');
+                    addCallee(prop ? prop.text : null);
+                    // The RECEIVER is genuinely read (`o.m(x)` reads `o`), so descend into the object side
+                    // only — descending into the whole member_expression would re-add the method name.
+                    const obj = fnNode.childForFieldName('object');
+                    if (obj)
+                        visit(obj);
+                }
+                else {
+                    visit(fnNode); // computed/complex callee: no name to record, but its parts are read
+                }
+            }
+            const args = n.childForFieldName('arguments');
+            if (args)
+                for (let i = 0; i < args.childCount; i++)
+                    visit(args.child(i));
+            return; // children handled explicitly above
+        }
+        if (n.type === 'member_expression') {
+            const obj = n.childForFieldName('object');
+            if (obj)
+                visit(obj);
+            // The `property` side is a name in the object, not a variable in scope — never a read.
+            // A COMPUTED index (`o[k]`) is a real read of `k`, and the grammar gives it as a
+            // subscript_expression, which falls through to the generic recursion below instead.
+            return;
+        }
+        if (n.type === 'identifier' || n.type === 'shorthand_property_identifier')
+            addRef(n.text);
+        for (let i = 0; i < n.childCount; i++)
+            visit(n.child(i));
+    };
+    visit(node);
+    return { text: node.text.trim().slice(0, EXPR_MAX), refs, callees };
+}
+// Which languages have a data-flow extractor. A language absent here yields `undefined` — NOT an
+// empty fact set, which a caller would be entitled to read as "analysed and found nothing".
+const DATAFLOW_LANGS = new Set(['typescript', 'tsx']);
+function extractDataFlowFromTree(tree, lang = 'typescript') {
+    if (!DATAFLOW_LANGS.has(lang))
+        return undefined;
+    const defs = [], calls = [], params = [], returns = [];
+    // Qualified enclosing name, identical in construction to the TS edge walk's enclosingFn.
+    const enclosing = (node) => {
+        const parts = [];
+        let n = node.parent;
+        while (n) {
+            if (DF_SCOPE_TYPES.has(n.type)) {
+                const nm = n.childForFieldName('name');
+                if (nm)
+                    parts.unshift(nm.text);
+            }
+            n = n.parent;
+        }
+        return parts.length ? parts.join('.') : '<module>';
+    };
+    // A function node's own qualified name, or null when it has none — `enclosing` walks from the
+    // PARENT, so a function's parameters (which live inside the function node) must be attributed to
+    // the function itself.
+    //
+    // An ANONYMOUS function (arrow, function expression) yields null and therefore emits NO parameter
+    // facts. Measured why: attributing them to the enclosing scope collapsed three distinct top-level
+    // arrows onto `{fn:'<module>', index:0}` with three different names — not a missing fact but a
+    // meaningless one, and `<module>` has no parameters. Losing the hop is a disclosed false negative;
+    // inventing an owner is the kind of wrong fact this walk exists to avoid.
+    //
+    // NAMED LIMIT, MEASURED. Counting function nodes: 88.6% of this repo's own src (2452/2767) and
+    // 83.1% of `reference/`'s OSS TS (4093/4927) are anonymous. Most of that is inline callbacks,
+    // which need no parameter binding — the subset that actually costs coverage is a function BOUND
+    // TO A NAME (`const f = (a) => {}`), and that is 248 in src and 14 in reference. So in this
+    // repository roughly 44% of name-callable functions (248 of 563) contribute no parameter facts.
+    //
+    // Naming such a function from its declarator would need the CALL walk to agree — a call inside
+    // that arrow is attributed to `<module>` today, so taint entering `f` still could not reach
+    // anything `f` calls. A half-fix would raise the fact count while leaving the hop broken, which
+    // reads as coverage that does not exist. The real fix is one identity-scheme change shared by
+    // both walks (A-SPEC-136 territory, and it would improve impact analysis too, which suffers the
+    // same collapse). The two schemes staying identical is the invariant that lets facts join the
+    // graph at all, so they move together or not at all.
+    const selfName = (fnNode) => {
+        const nm = fnNode.childForFieldName('name');
+        if (!nm)
+            return null;
+        const outer = enclosing(fnNode);
+        return outer === '<module>' ? nm.text : `${outer}.${nm.text}`;
+    };
+    const visit = (node) => {
+        if (node.type === 'variable_declarator') {
+            const nm = node.childForFieldName('name');
+            const val = node.childForFieldName('value');
+            // Only a bare identifier target: a destructuring pattern binds several names through a
+            // structure this layer does not model, so it yields no def rather than a guessed one.
+            if (nm && nm.type === 'identifier' && val) {
+                defs.push({ fn: enclosing(node), name: nm.text, expr: exprOf(val), line: node.startPosition.row + 1 });
+            }
+        }
+        else if (node.type === 'assignment_expression') {
+            const left = node.childForFieldName('left');
+            const right = node.childForFieldName('right');
+            if (left && left.type === 'identifier' && right) {
+                defs.push({ fn: enclosing(node), name: left.text, expr: exprOf(right), line: node.startPosition.row + 1 });
+            }
+        }
+        else if (node.type === 'call_expression') {
+            const fn = node.childForFieldName('function');
+            if (fn && (fn.type === 'identifier' || fn.type === 'member_expression')) {
+                const property = fn.childForFieldName && fn.childForFieldName('property');
+                const callee = fn.type === 'identifier' ? fn.text : (property ? property.text : null);
+                if (callee) {
+                    // ORDERED argument texts. Position is what binds an argument to a parameter, so this list
+                    // is never sorted, deduped, or filtered — a dropped element would shift every later
+                    // binding onto the wrong slot.
+                    const argsNode = node.childForFieldName('arguments');
+                    const args = [];
+                    if (argsNode) {
+                        for (let i = 0; i < argsNode.namedChildCount; i++) {
+                            const a = argsNode.namedChild(i);
+                            if (a.type === 'comment')
+                                continue;
+                            args.push(exprOf(a));
+                        }
+                    }
+                    calls.push({ fn: enclosing(node), callee, args, line: node.startPosition.row + 1 });
+                }
+            }
+        }
+        else if (DF_FUNC_TYPES.has(node.type)) {
+            const ps = node.childForFieldName('parameters');
+            const owner = selfName(node);
+            if (ps && owner) {
+                for (let i = 0; i < ps.namedChildCount; i++) {
+                    const p = ps.namedChild(i);
+                    if (p.type === 'comment')
+                        continue;
+                    // The parameter's bare identifier. `x`, `x: T`, `x = d` and `x: T = d` all expose one;
+                    // a destructuring or rest pattern does not, and is SKIPPED — but its POSITION still
+                    // consumes an index, or every later parameter would bind one slot too early.
+                    const name = paramIdentifier(p);
+                    if (name)
+                        params.push({ fn: owner, index: i, name });
+                }
+            }
+        }
+        else if (node.type === 'return_statement') {
+            // A bare `return;` has no named child and carries no value — no fact.
+            const val = node.namedChildCount > 0 ? node.namedChild(0) : null;
+            if (val && val.type !== 'comment') {
+                returns.push({ fn: enclosing(node), expr: exprOf(val), line: node.startPosition.row + 1 });
+            }
+        }
+        for (let i = 0; i < node.childCount; i++)
+            visit(node.child(i));
+    };
+    visit(tree.rootNode);
+    return { defs, calls, params, returns };
+}
+// The bare identifier a parameter binds, or null when the parameter binds through a pattern this
+// layer does not model. Never returns the pattern's text: naming `{a, b}` as `a` would bind taint to
+// a variable that does not exist at that position.
+function paramIdentifier(p) {
+    if (p.type === 'identifier')
+        return p.text;
+    // required_parameter / optional_parameter (TS) wrap the binding in a `pattern` field.
+    const pat = p.childForFieldName && p.childForFieldName('pattern');
+    if (pat && pat.type === 'identifier')
+        return pat.text;
+    // `x = default` in plain JS: assignment_pattern with an identifier on the left.
+    const left = p.childForFieldName && p.childForFieldName('left');
+    if (left && left.type === 'identifier')
+        return left.text;
+    return null;
+}
+module.exports = { LANG_CONFIG, DATAFLOW_LANGS, extractSymbolsFromTree, extractEdgesFromTree, extractDataFlowFromTree, walkGoSymbols, walkRustSymbols, walkPythonEdges, parseWithBuffer };