cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/core/ingestion/utils/ast-helpers.js

@@ -0,0 +1,1693 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLeadingDocDescriptionExtractor = exports.DOC_BEARING_LABELS = exports.stripBidiAndZeroWidth = exports.SPLIT_SIGNATURE_NODE_TYPES = exports.LOCAL_SCOPE_BODY_NODE_TYPES = exports.PARAMETER_LIST_NODE_TYPES = exports.CALL_ARGUMENT_LIST_TYPES = exports.inferFunctionLabel = exports.CONSTRUCTOR_LABEL_NODE_TYPES = exports.METHOD_LABEL_NODE_TYPES = exports.genericFuncName = exports.findSiblingChild = exports.findEnclosingClassId = exports.isThisMemberAssignmentNode = exports.isCjsDefaultExportAssignment = exports.isPrototypeMemberAssignmentNode = exports.thisAssignmentOwnerName = exports.prototypeAssignmentOwnerName = exports.findMemberAssignmentOwnerInfo = exports.findObjectLiteralBindingInfo = exports.findEnclosingClassInfo = exports.synthesizeJavaTypeIdentity = exports.javaLocalTypeDeclarationContainer = exports.CONTAINER_TYPE_TO_LABEL = exports.MEMBER_OWNER_NODE_TYPES = exports.CLASS_CONTAINER_TYPES = exports.FUNCTION_NODE_TYPES = exports.buildDefinitionPreScan = exports.isValueDefinitionLabel = exports.isSuppressedConcreteTypedefDuplicate = exports.getDefinitionNodeFromCaptures = exports.DEFINITION_CAPTURE_KEYS = exports.isQualifiableScopeLabel = exports.qualifyRustImplTargetByModScope = exports.qualifyByEnclosingModScope = void 0;
+exports.walkNamedTree = walkNamedTree;
+exports.findAncestorBeforeBoundary = findAncestorBeforeBoundary;
+exports.findSplitBodyCallableAncestor = findSplitBodyCallableAncestor;
+exports.getLabelFromCaptures = getLabelFromCaptures;
+exports.findDescendant = findDescendant;
+exports.extractStringContent = extractStringContent;
+exports.findChild = findChild;
+exports.extractLeadingDocComment = extractLeadingDocComment;
+exports.nodeToCapture = nodeToCapture;
+exports.syntheticCapture = syntheticCapture;
+exports.findNodeAtRange = findNodeAtRange;
+exports.nodeIfType = nodeIfType;
+const utils_js_1 = require("../../../lib/utils.js");
+const template_arguments_js_1 = require("./template-arguments.js");
+const qualified_name_js_1 = require("./qualified-name.js");
+const callable_labels_js_1 = require("./callable-labels.js");
+/**
+ * Qualify a name by its enclosing `mod_item` scope, so two same-tail items nested
+ * under different modules get DISTINCT paths (`outer.Inner` vs `other.Inner`).
+ * Walks `mod_item` ancestors (outermost → innermost) and joins them with the
+ * normalized raw text via the shared `splitQualifiedName`. Keyed purely on
+ * tree-sitter node types (no language name), so it is a no-op for every grammar
+ * without such a node.
+ *
+ * TWO callers, with different contracts — read both before widening either:
+ *
+ *  1. The inherent-impl target (`impl Inner { … }`) — the #1982 follow-up to
+ *     #1975, reachable through the {@link qualifyRustImplTargetByModScope} alias
+ *     and mirrored by the inherent-impl branch in `findEnclosingClassInfo` so the
+ *     owner edge and the node id agree byte-for-byte. That caller gates on an
+ *     UNSCOPED `type_identifier`, which is what keeps a SCOPED `impl a::Inner` on
+ *     its full raw text.
+ *
+ *  2. Free items, for module node identity (#2742). That caller gates on the node
+ *     being on neither side of an owner edge (`MEMBER_OWNER_NODE_TYPES`,
+ *     `enclosingClassInfo`) and not inside a callable, because only the id moves
+ *     here — every owner-edge anchor is minted separately and does not follow.
+ *
+ * A name with NO enclosing `mod` is returned verbatim, never normalized: rewriting
+ * a scoped target's separator (`a::Inner` → `a.Inner`) would move its node id away
+ * from the id its owner edge emits, which is how caller 2 first broke caller 1's
+ * #1975 contract. Splitting an unscoped name has always been the identity, so
+ * caller 1 is unaffected either way.
+ */
+const qualifyByEnclosingModScope = (node, rawText) => {
+    const modSegments = [];
+    let current = node.parent;
+    while (current) {
+        if (current.type === 'mod_item') {
+            const nameNode = current.childForFieldName?.('name') ??
+                current.children?.find((c) => c.type === 'identifier');
+            if (nameNode)
+                modSegments.unshift(nameNode.text);
+        }
+        current = current.parent;
+    }
+    // No enclosing `mod`: return the raw text UNTOUCHED. Normalizing here would
+    // rewrite a scoped target's separator (`a::Inner` -> `a.Inner`) and silently
+    // move its node id away from the one the owner edge emits, which is how this
+    // helper first broke the #1975 scoped-impl ownership when it was generalized
+    // beyond unscoped targets. Callers that pass an unscoped name are unaffected,
+    // since splitting one has always been the identity.
+    if (modSegments.length === 0)
+        return rawText;
+    return [...modSegments, ...(0, qualified_name_js_1.splitQualifiedName)(rawText)].filter(Boolean).join('.');
+};
+exports.qualifyByEnclosingModScope = qualifyByEnclosingModScope;
+/**
+ * Impl-target alias of {@link qualifyByEnclosingModScope}, kept as its own name
+ * because the caller gates it on UNSCOPED targets (see the contract above).
+ */
+exports.qualifyRustImplTargetByModScope = exports.qualifyByEnclosingModScope;
+/**
+ * #1991: scope-label predicate that single-sources the `nodeLabel === 'Trait'`
+ * checks in parsing-processor.ts / parse-worker.ts. A Ruby `module` maps to the
+ * `Trait` registry label but is NOT a typeDeclaration, so `extractQualifiedName`
+ * bails on it; these node labels are instead qualified via the scope walk
+ * (`qualifyScopeName`) so same-tail nested modules get distinct ids. Keeping the
+ * literal in one place stops the four hand-maintained copies (two each in the
+ * sequential and worker definition paths) from drifting apart. Pure predicate —
+ * value-identical to the inlined `nodeLabel === 'Trait'`.
+ */
+const isQualifiableScopeLabel = (nodeLabel) => nodeLabel === 'Trait';
+exports.isQualifiableScopeLabel = isQualifiableScopeLabel;
+/**
+ * Ordered list of definition capture keys for tree-sitter query matches.
+ * Used to extract the definition node from a capture map.
+ */
+exports.DEFINITION_CAPTURE_KEYS = [
+    'definition.function',
+    'definition.class',
+    'definition.interface',
+    'definition.method',
+    'definition.struct',
+    'definition.enum',
+    'definition.namespace',
+    'definition.module',
+    'definition.trait',
+    'definition.impl',
+    'definition.type',
+    'definition.const',
+    'definition.static',
+    'definition.variable',
+    'definition.typedef',
+    'definition.macro',
+    'definition.union',
+    'definition.property',
+    'definition.record',
+    'definition.delegate',
+    'definition.annotation',
+    'definition.constructor',
+    'definition.template',
+];
+/** Extract the definition node from a tree-sitter query capture map. */
+const getDefinitionNodeFromCaptures = (captureMap) => {
+    for (const key of exports.DEFINITION_CAPTURE_KEYS) {
+        if (captureMap[key])
+            return captureMap[key];
+    }
+    return null;
+};
+exports.getDefinitionNodeFromCaptures = getDefinitionNodeFromCaptures;
+const nodeRangeKey = (node) => `${node.startPosition.row}:${node.startPosition.column}:${node.endPosition.row}:${node.endPosition.column}`;
+const isConcreteTypedefCapture = (captureMap) => {
+    const definitionNode = (0, exports.getDefinitionNodeFromCaptures)(captureMap);
+    return (definitionNode?.type === 'type_definition' &&
+        (captureMap['definition.struct'] !== undefined || captureMap['definition.enum'] !== undefined));
+};
+const isSuppressedConcreteTypedefDuplicate = (captureMap, concreteTypedefRanges) => {
+    const definitionNode = (0, exports.getDefinitionNodeFromCaptures)(captureMap);
+    return (definitionNode?.type === 'type_definition' &&
+        captureMap['definition.typedef'] !== undefined &&
+        concreteTypedefRanges.has(nodeRangeKey(definitionNode)));
+};
+exports.isSuppressedConcreteTypedefDuplicate = isSuppressedConcreteTypedefDuplicate;
+/**
+ * Graph labels produced by a value capture (`@definition.const` /
+ * `@definition.static` / `@definition.variable`) — a binding that holds a value.
+ *
+ * `Property` is deliberately NOT here. It outranks these: Python matches both
+ * `@definition.property` (annotated) and `@definition.variable` (bare) on one
+ * assignment, and the property must win so a typed class attribute keeps its
+ * `Property` node and its owning `HAS_PROPERTY` edge. `Property` is instead
+ * suppressed only by a *callable* claim — see {@link buildDefinitionNameClaims}.
+ */
+const VALUE_DEFINITION_LABELS = new Set([
+    'Const',
+    'Static',
+    'Variable',
+]);
+/** True when `label` is the kind of node a value capture emits. */
+const isValueDefinitionLabel = (label) => VALUE_DEFINITION_LABELS.has(label);
+exports.isValueDefinitionLabel = isValueDefinitionLabel;
+/**
+ * Pre-scan `matches` for the `${definitionNode.startIndex}:${name}` keys already
+ * claimed by a higher-ranked definition capture, so the parse-worker's duplicate
+ * suppression is order-independent.
+ *
+ * Rank, highest first: callable (`Function`/`Method`/`Constructor`) → `Property`
+ * → value (`Const`/`Static`/`Variable`). A capture is dropped only when a
+ * STRICTLY higher rank claimed the same declaration node and name, so no capture
+ * can suppress itself and no rank can suppress a peer.
+ *
+ * ## Why this exists (#2687)
+ *
+ * `const X = () => {}` matches BOTH `@definition.function` and
+ * `@definition.const` on the same `lexical_declaration`. Only one graph node
+ * should survive — the `Function`, because that is what `CALLS` edges target.
+ * The parse-worker's in-loop dedup intends exactly that, but only the value
+ * branch consults its `processedDefinitionNodes` set, so suppression worked only
+ * if the function match happened to be processed first. It is not: tree-sitter
+ * completes the const pattern at `@name`, while the function pattern must also
+ * match the trailing `(arrow_function)` / `(function_expression)` value, so the
+ * const match is yielded FIRST and the edgeless `Const:` twin escaped.
+ *
+ * Consulting this set makes the outcome independent of match order.
+ *
+ * ## Keying
+ *
+ * Keys are `startIndex:name`, never `startIndex` alone — a multi-name
+ * declaration (`const a = 1, b = () => {}`) shares ONE definition node, and a
+ * bare-index key would wrongly suppress `a`'s legitimate `Const` node.
+ *
+ * Labels come from {@link getLabelFromCaptures}, the same function the main loop
+ * uses, so the pre-scan and the loop can never disagree about what counts as a
+ * value capture — including when a provider's `labelOverride` reclassifies one.
+ * A match that resolves to a value label registers nothing, so a match can never
+ * suppress itself.
+ *
+ * Language-agnostic: keyed off capture names and labels only.
+ *
+ * Also collects the concrete-typedef ranges that suppress the analogous
+ * typedef/struct duplicate, so both suppression sets come from one traversal.
+ */
+const buildDefinitionPreScan = (matches, provider) => {
+    const nonValue = new Set();
+    const callable = new Set();
+    const concreteTypedefRanges = new Set();
+    for (const match of matches) {
+        // ONE capture-map build per match feeds both suppression sets. These used
+        // to be two independent passes over `matches` (each rebuilding this object)
+        // on the hot per-file parse path.
+        const captureMap = {};
+        for (const capture of match.captures) {
+            captureMap[capture.name] = capture.node;
+        }
+        const definitionNode = (0, exports.getDefinitionNodeFromCaptures)(captureMap);
+        if (definitionNode === null)
+            continue;
+        if (isConcreteTypedefCapture(captureMap)) {
+            concreteTypedefRanges.add(nodeRangeKey(definitionNode));
+        }
+        // No `@name` capture means nothing a lower-ranked capture could collide
+        // with — a value or property pattern always binds a name. Checked before
+        // `getLabelFromCaptures` so a nameless match never pays for label
+        // resolution (which can reach a provider's `labelOverride`).
+        const nameNode = captureMap['name'];
+        if (nameNode === undefined)
+            continue;
+        const label = getLabelFromCaptures(captureMap, provider);
+        if (label === null || (0, exports.isValueDefinitionLabel)(label))
+            continue;
+        const key = `${definitionNode.startIndex}:${nameNode.text}`;
+        nonValue.add(key);
+        if ((0, callable_labels_js_1.isOverloadableCallable)(label))
+            callable.add(key);
+    }
+    return { nonValue, callable, concreteTypedefRanges };
+};
+exports.buildDefinitionPreScan = buildDefinitionPreScan;
+/**
+ * Node types that represent function/method definitions across languages.
+ * Used by parent-walk in call-processor, parse-worker, and type-env to detect
+ * enclosing function scope boundaries.
+ *
+ * INVARIANT: This set MUST be a superset of every language's
+ * MethodExtractionConfig.methodNodeTypes. When adding a new node type to a
+ * MethodExtractor config, add it here too — otherwise enclosing-function
+ * resolution will silently miss that node type during parent-walks.
+ */
+exports.FUNCTION_NODE_TYPES = new Set([
+    // TypeScript/JavaScript
+    'function_declaration',
+    'arrow_function',
+    'function_expression',
+    'method_definition',
+    'generator_function_declaration',
+    // Python
+    'function_definition',
+    // Common async variants
+    'async_function_declaration',
+    'async_arrow_function',
+    // Java
+    'method_declaration',
+    'constructor_declaration',
+    'compact_constructor_declaration',
+    'annotation_type_element_declaration',
+    // C/C++
+    // 'function_definition' already included above
+    // Go
+    // 'method_declaration' already included from Java
+    // C#
+    'local_function_statement',
+    // Rust
+    'function_item',
+    'impl_item', // Methods inside impl blocks
+    // PHP
+    'anonymous_function',
+    // Kotlin
+    'lambda_literal',
+    'secondary_constructor', // F48: methodNodeTypes superset invariant
+    // Swift
+    'init_declaration',
+    'deinit_declaration',
+    // Ruby
+    'method', // def foo
+    'singleton_method', // def self.foo
+    // Dart
+    'function_signature',
+    'method_signature',
+]);
+/**
+ * AST node types that represent a class-like container (for HAS_METHOD edge extraction).
+ *
+ * INVARIANT: When a language config adds a new node type to `typeDeclarationNodes`,
+ * that type must also be added here AND to `CONTAINER_TYPE_TO_LABEL` below,
+ * otherwise `findEnclosingClassNode` won't recognize it and methods may get
+ * orphaned HAS_METHOD edges or incorrect labels.
+ */
+exports.CLASS_CONTAINER_TYPES = new Set([
+    'class_declaration',
+    'abstract_class_declaration',
+    'interface_declaration',
+    'struct_declaration',
+    'record_declaration',
+    'class_specifier',
+    'struct_specifier',
+    'impl_item',
+    'trait_item',
+    'struct_item',
+    'enum_item',
+    'class_definition',
+    'trait_declaration',
+    // PHP
+    'enum_declaration',
+    'protocol_declaration',
+    // Dart
+    'mixin_declaration',
+    'extension_declaration',
+    // Ruby
+    'class',
+    'module',
+    'singleton_class', // Ruby: class << self
+    // Kotlin
+    'object_declaration',
+    'companion_object',
+    // Go
+    'struct_type',
+    'interface_type',
+]);
+/**
+ * Node types whose OWN node id must not be re-keyed by an enclosing-scope
+ * qualifier (see {@link qualifyByEnclosingModScope}) unless the owner-edge
+ * anchor moves in the same change.
+ *
+ * These are the containers a member can be declared inside. Their members'
+ * `HAS_METHOD` / `HAS_PROPERTY` edges anchor on `findEnclosingClassInfo().classId`,
+ * which is minted from the container's bare `nameNode.text` further down this
+ * file and only follows a qualified shape when the provider opts in via
+ * `classExtractor.qualifiedNodeId`. So qualifying a container's id alone points
+ * every one of its member edges at a node that does not exist — the edges are
+ * dropped at COPY time and the container silently loses all its members.
+ *
+ * Derived from `CLASS_CONTAINER_TYPES` on purpose: that set is already the
+ * single source of "this node type owns member edges", carries the INVARIANT
+ * note above binding it to `CONTAINER_TYPE_TO_LABEL`, and so a language adding
+ * a container cannot gain a mismatched id shape here without also failing that
+ * invariant. Keyed purely on tree-sitter node types — no language names.
+ */
+exports.MEMBER_OWNER_NODE_TYPES = new Set([
+    ...exports.CLASS_CONTAINER_TYPES,
+    // Rust `union_item` owns a `field_declaration_list` exactly as `struct_item`
+    // does, and its fields ARE captured as `Property`, but it is absent from
+    // `CLASS_CONTAINER_TYPES`, so `findEnclosingClassInfo` does not recognize it as
+    // an owner: union fields carry no `HAS_PROPERTY` edge at all and therefore
+    // cannot dangle. Listed here so the union's own id keeps the same shape as the
+    // struct beside it, and so making it a real owner later starts from a
+    // consistent id rather than having to move one.
+    'union_item',
+]);
+exports.CONTAINER_TYPE_TO_LABEL = {
+    class_declaration: 'Class',
+    abstract_class_declaration: 'Class',
+    interface_declaration: 'Interface',
+    struct_declaration: 'Struct',
+    struct_specifier: 'Struct',
+    class_specifier: 'Class',
+    class_definition: 'Class',
+    impl_item: 'Impl',
+    trait_item: 'Trait',
+    struct_item: 'Struct',
+    enum_item: 'Enum',
+    trait_declaration: 'Trait',
+    enum_declaration: 'Enum',
+    record_declaration: 'Record',
+    protocol_declaration: 'Interface',
+    mixin_declaration: 'Mixin',
+    extension_declaration: 'Class',
+    class: 'Class',
+    // Ruby `module` declarations map to `Trait` so they participate in the
+    // class-like type registry used by `lookupClassByName` / inheritance
+    // resolution. This lets `include` / `extend` / `prepend` mixin heritage
+    // resolve to the providing module. Safe for non-Ruby languages: the only supported
+    // grammar that uses the bare `module` AST node type as a container is
+    // Ruby (Rust uses `mod_item`). Any new language adding a `module` node
+    // type must explicitly reclassify here.
+    module: 'Trait',
+    singleton_class: 'Class', // Ruby: class << self inherits enclosing class name
+    object_declaration: 'Class',
+    companion_object: 'Class',
+    struct_type: 'Struct',
+    interface_type: 'Interface',
+};
+/**
+ * Pre-order walk over a node and all its named descendants, invoking `cb` on
+ * each. Replaces the per-language `visit`/`visitGo`/`visitRust`/`visitSwift`
+ * clones that every language's capture-synthesis walker re-implemented (#1956
+ * tri-review U6).
+ *
+ * Iterates by index with a null guard: `node.namedChild(i)` is typed
+ * `SyntaxNode | null`, and most callers already guarded it. The Go and C#
+ * callers previously iterated `node.namedChildren`; the Go one had no null
+ * guard, so this standardizes them onto the guarded indexed form — a deliberate,
+ * strictly-safer behavior addition (the traversal *sequence* is identical, so
+ * capture output stays byte-identical on well-formed trees; the guard only
+ * matters for a null named child, which the fixture corpus never produces).
+ */
+function walkNamedTree(node, cb) {
+    cb(node);
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null)
+            walkNamedTree(child, cb);
+    }
+}
+/** Return the first matching ancestor unless a boundary ancestor is reached first. */
+function findAncestorBeforeBoundary(node, targetTypes, boundaryTypes) {
+    let current = node.parent;
+    while (current !== null) {
+        if (boundaryTypes.has(current.type))
+            return null;
+        if (targetTypes.has(current.type))
+            return current;
+        current = current.parent;
+    }
+    return null;
+}
+/**
+ * Enclosing callable for grammars that split a callable into a SIGNATURE node
+ * and a SIBLING body, where the callable is therefore never an ancestor of the
+ * code inside it.
+ *
+ * Dart is the case that forced this: `int outer() { … }` parses as
+ * `function_signature` followed by `function_body` as SIBLINGS, so an ancestor
+ * walk from a closure inside the body can never reach `outer`. No membership
+ * set fixes that — the walk is looking in the wrong direction (#2699).
+ *
+ * Deliberately a FALLBACK, used only when the ancestor walk found nothing.
+ *
+ * The sibling must be a BARE SIGNATURE, and that restriction is load-bearing —
+ * "any preceding callable sibling" is WRONG and was caught regressing PHP. In
+ * `<?php function target($x) {…} $handler = function ($x) {…};` the closure is
+ * at FILE level, so the primary ancestor walk correctly finds nothing and this
+ * fallback runs; an unrestricted version then grabs the preceding
+ * `function_definition` and mis-qualifies the file-level `$handler` as
+ * `target.$handler`. A preceding sibling is only an ENCLOSING callable when it
+ * cannot hold its own body — i.e. when the grammar split the body off.
+ *
+ * `SPLIT_SIGNATURE_NODE_TYPES` is exactly that set, and it is derived rather
+ * than listed: `LOCAL_SCOPE_BODY_NODE_TYPES` already filters the bare-signature
+ * types out of `FUNCTION_NODE_TYPES`, so the difference between them IS the
+ * split-signature set. PHP's `function_definition` carries a body and is in
+ * both, so it is excluded; Dart's `function_signature` is in only the former,
+ * so it qualifies.
+ *
+ * Language-neutral by construction — it names no grammar, and any future
+ * signature/body-split language is covered for free.
+ */
+function findSplitBodyCallableAncestor(node, signatureOnlyTypes, boundaryTypes) {
+    let current = node.parent;
+    while (current !== null) {
+        if (boundaryTypes.has(current.type))
+            return null;
+        const prev = current.previousNamedSibling;
+        if (prev !== null &&
+            signatureOnlyTypes.has(prev.type) &&
+            // `current` must be the signature's BODY, not merely the next thing after
+            // it. Without this, valid TypeScript trips the fallback: in
+            //     declare namespace Api {
+            //       function internalHelper(x): number;
+            //       export function send(x): number;
+            //     }
+            // `send`'s `export_statement` is the next sibling of `internalHelper`'s
+            // `function_signature`, so `send` was mis-qualified as
+            // `internalHelper.send@r:c`. TypeScript emits bodyless
+            // function_signature/method_signature for overloads and ambient
+            // declarations, so the split-signature set is NOT Dart-only.
+            //
+            // A body contains statements; a declaration wrapper contains another
+            // signature. Rejecting any `current` that directly holds a signature of
+            // its own separates the two without naming a grammar.
+            !current.namedChildren.some((child) => signatureOnlyTypes.has(child.type))) {
+            return prev;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+// SPLIT_SIGNATURE_NODE_TYPES is defined next to LOCAL_SCOPE_BODY_NODE_TYPES,
+// which it derives from — declaring it here would read it in its temporal dead
+// zone and throw at module load (tsc does NOT catch that; only running does).
+/**
+ * Determine the graph node label from a tree-sitter capture map.
+ * Handles language-specific reclassification via the provider's labelOverride hook
+ * (e.g. C/C++ duplicate skipping, Kotlin Method promotion).
+ * Returns null if the capture should be skipped (import, call, C/C++ duplicate, missing name).
+ */
+function getLabelFromCaptures(captureMap, provider) {
+    if (captureMap['import'] || captureMap['call'])
+        return null;
+    const hasDefaultExportHocNameSeed = captureMap['definition.function'] !== undefined &&
+        (captureMap['hoc'] !== undefined || captureMap['callee'] !== undefined);
+    // Nameless `definition.class` passes through: a class extractor may
+    // synthesize the name (Java anonymous class bodies → `Worker$N`, #2550).
+    // Downstream stays safe — parse-worker skips any nameless definition the
+    // extractor could not name (its `!nameNode && !extractedClassSymbol` gate).
+    if (!captureMap['name'] &&
+        !captureMap['definition.constructor'] &&
+        !captureMap['definition.class'] &&
+        !hasDefaultExportHocNameSeed)
+        return null;
+    if (captureMap['definition.function']) {
+        if (provider.labelOverride) {
+            const override = provider.labelOverride(captureMap['definition.function'], 'Function');
+            if (override !== 'Function')
+                return override;
+        }
+        return 'Function';
+    }
+    if (captureMap['definition.class'])
+        return 'Class';
+    if (captureMap['definition.interface'])
+        return 'Interface';
+    if (captureMap['definition.method'])
+        return 'Method';
+    if (captureMap['definition.struct'])
+        return 'Struct';
+    if (captureMap['definition.enum'])
+        return 'Enum';
+    if (captureMap['definition.namespace'])
+        return 'Namespace';
+    if (captureMap['definition.module']) {
+        // Let providers reclassify module captures (e.g. Ruby remaps `Module`→`Trait`
+        // so mixin heritage resolves through `lookupClassByName`). Returning null
+        // from labelOverride means "skip this symbol"; treat it as a no-op here so
+        // we keep the default label rather than dropping a real definition.
+        if (provider.labelOverride) {
+            const override = provider.labelOverride(captureMap['definition.module'], 'Module');
+            if (override && override !== 'Module')
+                return override;
+        }
+        return 'Module';
+    }
+    if (captureMap['definition.trait'])
+        return 'Trait';
+    if (captureMap['definition.impl'])
+        return 'Impl';
+    if (captureMap['definition.type'])
+        return 'TypeAlias';
+    if (captureMap['definition.const'])
+        return 'Const';
+    if (captureMap['definition.static'])
+        return 'Static';
+    if (captureMap['definition.variable'])
+        return 'Variable';
+    if (captureMap['definition.typedef'])
+        return 'Typedef';
+    if (captureMap['definition.macro'])
+        return 'Macro';
+    if (captureMap['definition.union'])
+        return 'Union';
+    if (captureMap['definition.property'])
+        return 'Property';
+    if (captureMap['definition.record'])
+        return 'Record';
+    if (captureMap['definition.delegate'])
+        return 'Delegate';
+    if (captureMap['definition.annotation'])
+        return 'Annotation';
+    if (captureMap['definition.constructor'])
+        return 'Constructor';
+    if (captureMap['definition.template'])
+        return 'Template';
+    return 'CodeElement';
+}
+/** Walk up AST to find enclosing class/struct/interface/impl, return its ID and name.
+ *  For Go method_declaration nodes, extracts receiver type (e.g. `func (u *User) Save()` → User struct).
+ *
+ *  @param resolveEnclosingOwner  Optional language-specific hook for container remapping.
+ *    When provided and a CLASS_CONTAINER_TYPES node is found, this hook is called:
+ *    - Return a different SyntaxNode to remap the container (e.g., Ruby singleton_class → class).
+ *    - Return `null` to skip this container and keep walking up.
+ *    - Return the input node (identity) to use the container as-is.
+ *    When omitted, the container node is used as-is.
+ *
+ *    INVARIANT: Implementers SHOULD return either `null`, the input node, or
+ *    another CLASS_CONTAINER_TYPES node. Returning a non-container node is
+ *    permitted but discouraged — it will cause the walk to skip the current
+ *    container and continue from the redirected node's parent. The
+ *    `MAX_ENCLOSING_WALK_ITERATIONS` defense-in-depth guard below prevents
+ *    pathological hooks from creating an infinite loop. */
+const MAX_ENCLOSING_WALK_ITERATIONS = 4096;
+/** Named Java declarations that can host, or themselves be, local types. */
+const JAVA_NAMED_TYPE_NODE_LABELS = new Map([
+    ['class_declaration', 'Class'],
+    ['enum_declaration', 'Enum'],
+    ['interface_declaration', 'Interface'],
+    ['record_declaration', 'Record'],
+]);
+const JAVA_ANON_HOST_TYPES = new Set(JAVA_NAMED_TYPE_NODE_LABELS.keys());
+const JAVA_LOCAL_TYPE_CONTAINERS = new Set([
+    'block',
+    'constructor_body',
+    'switch_block_statement_group',
+]);
+/** A legal local type declaration is a class, enum, record, or interface
+ * directly occupying a block-statement position. Annotation interfaces are
+ * deliberately excluded: javac rejects local annotation declarations. */
+const javaLocalTypeDeclarationContainer = (node) => {
+    if (!JAVA_NAMED_TYPE_NODE_LABELS.has(node.type))
+        return null;
+    const parent = node.parent;
+    return parent !== null && JAVA_LOCAL_TYPE_CONTAINERS.has(parent.type) ? parent : null;
+};
+exports.javaLocalTypeDeclarationContainer = javaLocalTypeDeclarationContainer;
+const isJavaLocalTypeNode = (node) => (0, exports.javaLocalTypeDeclarationContainer)(node) !== null;
+/** The two Java anonymous-class-body shapes (#2550/#2555): an
+ *  `object_creation_expression` with a `class_body` child
+ *  (`new Runnable() { ... }`), and an `enum_constant` with a `body:`
+ *  field (`enum E { A { ... } }` — javac's other `E$N` shape). */
+const isJavaAnonymousBodyNode = (node) => (node.type === 'object_creation_expression' &&
+    node.namedChildren?.some((c) => c.type === 'class_body') === true) ||
+    (node.type === 'enum_constant' && node.childForFieldName?.('body')?.type === 'class_body');
+/** Nearest ancestor of `node` that is an enclosing type per JLS 13.1. */
+const nearestJavaEnclosingType = (node) => {
+    let cursor = node.parent;
+    let iterations = 0;
+    while (cursor) {
+        if (++iterations > MAX_ENCLOSING_WALK_ITERATIONS)
+            return null;
+        if (JAVA_ANON_HOST_TYPES.has(cursor.type) || isJavaAnonymousBodyNode(cursor))
+            return cursor;
+        cursor = cursor.parent;
+    }
+    return null;
+};
+/** Parse-tree-bounded memo. Sequence ordinals are built once per tree, avoiding
+ * a host-candidate scan for every extraction/ownership consumer. */
+const javaTypeIdentityMemo = new WeakMap();
+const javaHostKey = (node) => `${node.type}:${node.startIndex}`;
+const javaIdentityCandidatesBelow = (root) => {
+    const seen = new Set();
+    const candidates = [];
+    for (const type of [
+        'object_creation_expression',
+        'enum_constant',
+        ...JAVA_NAMED_TYPE_NODE_LABELS.keys(),
+    ]) {
+        for (const candidate of root.descendantsOfType?.(type) ?? []) {
+            if (!isJavaAnonymousBodyNode(candidate) && !isJavaLocalTypeNode(candidate))
+                continue;
+            const key = javaHostKey(candidate);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            candidates.push(candidate);
+        }
+    }
+    return candidates.sort((left, right) => left.startIndex - right.startIndex);
+};
+const buildJavaTypeIdentityState = (root) => {
+    const ordinalByStart = new Map();
+    const sequenceCounts = new Map();
+    for (const candidate of javaIdentityCandidatesBelow(root)) {
+        const host = nearestJavaEnclosingType(candidate);
+        if (host === null)
+            continue;
+        const isAnonymous = isJavaAnonymousBodyNode(candidate);
+        const bindingName = isAnonymous ? '' : candidate.childForFieldName?.('name')?.text;
+        // Anonymous types deliberately use the empty sequence key; malformed named
+        // declarations must not enter that sequence.
+        if (!isAnonymous && !bindingName)
+            continue;
+        const sequenceKey = `${javaHostKey(host)}:${bindingName}`;
+        const ordinal = (sequenceCounts.get(sequenceKey) ?? 0) + 1;
+        sequenceCounts.set(sequenceKey, ordinal);
+        ordinalByStart.set(candidate.startIndex, ordinal);
+    }
+    return { byStart: new Map(), ordinalByStart };
+};
+const javaTypeIdentityStateFor = (node) => {
+    const tree = node.tree;
+    if (tree === undefined) {
+        const host = nearestJavaEnclosingType(node);
+        return buildJavaTypeIdentityState(host ?? node);
+    }
+    let state = javaTypeIdentityMemo.get(tree);
+    if (state === undefined) {
+        state = buildJavaTypeIdentityState(tree.rootNode ?? node);
+        javaTypeIdentityMemo.set(tree, state);
+    }
+    return state;
+};
+/** Source-type-relative binary name of a Java enclosing type, including
+ * synthesized local/anonymous hosts and named member-type chains. */
+const javaBinaryNameOfType = (node) => {
+    if (isJavaAnonymousBodyNode(node) || isJavaLocalTypeNode(node)) {
+        return (0, exports.synthesizeJavaTypeIdentity)(node)?.name;
+    }
+    if (!JAVA_ANON_HOST_TYPES.has(node.type))
+        return undefined;
+    const simpleName = node.childForFieldName?.('name')?.text;
+    if (simpleName === undefined || simpleName.length === 0)
+        return undefined;
+    const enclosing = nearestJavaEnclosingType(node);
+    if (enclosing === null)
+        return simpleName;
+    const enclosingName = javaBinaryNameOfType(enclosing);
+    return enclosingName === undefined ? undefined : `${enclosingName}$${simpleName}`;
+};
+/**
+ * Authoritative Java local/anonymous type identity.
+ *
+ * JLS 13.1 defines the shape and immediate-host prefix. OpenJDK javac's
+ * Check.localClassName allocates N independently for each
+ * (enclosing binary name, local simple name) pair; anonymous types use the
+ * empty simple name and therefore have their own sequence. Package names are
+ * omitted from this project identity because graph ids already include the
+ * file path.
+ */
+const synthesizeJavaTypeIdentity = (node) => {
+    const localLabel = JAVA_NAMED_TYPE_NODE_LABELS.get(node.type);
+    const isLocal = localLabel !== undefined && isJavaLocalTypeNode(node);
+    const isAnonymous = isJavaAnonymousBodyNode(node);
+    const enclosing = nearestJavaEnclosingType(node);
+    const memberSimpleName = !isLocal && !isAnonymous && localLabel !== undefined
+        ? node.childForFieldName?.('name')?.text
+        : undefined;
+    const synthesizedHostIdentity = memberSimpleName !== undefined && enclosing !== null
+        ? (0, exports.synthesizeJavaTypeIdentity)(enclosing)
+        : undefined;
+    if (!isLocal && !isAnonymous && synthesizedHostIdentity === undefined)
+        return undefined;
+    if (enclosing === null)
+        return undefined;
+    const state = javaTypeIdentityStateFor(node);
+    const cached = state.byStart.get(node.startIndex);
+    if (cached !== undefined)
+        return cached;
+    const prefix = javaBinaryNameOfType(enclosing);
+    if (prefix === undefined)
+        return undefined;
+    if (memberSimpleName !== undefined) {
+        const identity = {
+            name: `${prefix}$${memberSimpleName}`,
+            label: localLabel,
+            bindingName: memberSimpleName,
+        };
+        state.byStart.set(node.startIndex, identity);
+        return identity;
+    }
+    const bindingName = isLocal ? node.childForFieldName?.('name')?.text : undefined;
+    if (isLocal && !bindingName)
+        return undefined;
+    const ordinal = state.ordinalByStart.get(node.startIndex);
+    if (ordinal === undefined)
+        return undefined;
+    const identity = {
+        name: `${prefix}$${ordinal}${bindingName ?? ''}`,
+        label: isAnonymous ? 'Class' : localLabel,
+        ...(bindingName === undefined ? {} : { bindingName }),
+    };
+    state.byStart.set(node.startIndex, identity);
+    return identity;
+};
+exports.synthesizeJavaTypeIdentity = synthesizeJavaTypeIdentity;
+const findEnclosingClassInfo = (node, filePath, resolveEnclosingOwner, 
+/**
+ * Optional (#1978): returns the enclosing type's fully-qualified name
+ * (e.g. "Outer.Inner") for a type-declaration container, or null. Callers
+ * pass `classExtractor.extractQualifiedName` ONLY when the language's
+ * `qualifiedNodeId` flag is on — so when omitted, behavior is byte-identical
+ * to before (qualifiedClassId stays undefined). Used by the standard
+ * class-container branch to compute `qualifiedClassId` from the SAME function
+ * the node-id is built from, guaranteeing owner-id == node-id by construction.
+ */
+getQualifiedOwnerName) => {
+    let current = node.parent;
+    let iterations = 0;
+    // Tracks container nodes already visited via the hook so a misbehaving hook
+    // that keeps redirecting back to the same container cannot loop forever.
+    const visitedContainers = new Set();
+    while (current) {
+        if (++iterations > MAX_ENCLOSING_WALK_ITERATIONS) {
+            // Defense-in-depth: a real source tree has nowhere near this many ancestors.
+            // Bail out rather than hang ingestion.
+            return null;
+        }
+        // Go: method_declaration has a receiver parameter with the struct type
+        if (current.type === 'method_declaration') {
+            const receiver = current.childForFieldName?.('receiver');
+            if (receiver) {
+                const paramDecl = receiver.namedChildren?.find?.((c) => c.type === 'parameter_declaration');
+                if (paramDecl) {
+                    const typeNode = paramDecl.childForFieldName?.('type');
+                    if (typeNode) {
+                        const inner = typeNode.type === 'pointer_type' ? typeNode.firstNamedChild : typeNode;
+                        if (inner && (inner.type === 'type_identifier' || inner.type === 'identifier')) {
+                            return {
+                                classId: (0, utils_js_1.generateId)('Struct', `${filePath}:${inner.text}`),
+                                className: inner.text,
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        // Go: the `type_spec` IS the declared type (`type User struct { ... }`, and
+        // one per member of a grouped `type ( A struct{…}; B struct{…} )` block).
+        //
+        // Matched here rather than on the enclosing `type_declaration` (#2837): this
+        // walk climbs `node.parent`, so it passes THROUGH the containing spec on its
+        // way up from any member, and the structure it already has is the answer.
+        // Keying on the wrapper instead meant picking one spec out of several with
+        // no reference point — which filed every member of a grouped block under its
+        // FIRST struct, so two same-named fields minted one id and first-write-wins
+        // dropped the second.
+        if (current.type === 'type_spec') {
+            const typeBody = current.childForFieldName?.('type');
+            if (typeBody?.type === 'struct_type' || typeBody?.type === 'interface_type') {
+                const nameNode = current.childForFieldName?.('name');
+                if (nameNode) {
+                    const label = typeBody.type === 'struct_type' ? 'Struct' : 'Interface';
+                    return {
+                        classId: (0, utils_js_1.generateId)(label, `${filePath}:${nameNode.text}`),
+                        className: nameNode.text,
+                    };
+                }
+            }
+        }
+        // Java: an anonymous class body owns its members — attribute to the
+        // synthesized `Worker$N`/`E$N` class, not the lexically enclosing
+        // named type (#2550/#2555). Covers both shapes: `new Runnable() { ... }`
+        // and enum constant bodies (`enum E { A { ... } }`). The synthesis
+        // returns undefined for shape-less nodes (plain `new Foo()`, a body-less
+        // enum constant, and every C# `object_creation_expression`), so the
+        // walk continues unchanged for those — including on to
+        // `enum_declaration`, which sits in CLASS_CONTAINER_TYPES below.
+        if (isJavaAnonymousBodyNode(current) || JAVA_ANON_HOST_TYPES.has(current.type)) {
+            const identity = (0, exports.synthesizeJavaTypeIdentity)(current);
+            if (identity !== undefined) {
+                return {
+                    classId: (0, utils_js_1.generateId)(identity.label, `${filePath}:${identity.name}`),
+                    className: identity.name,
+                };
+            }
+        }
+        if (exports.CLASS_CONTAINER_TYPES.has(current.type)) {
+            // Delegate language-specific container remapping to the provider hook.
+            if (resolveEnclosingOwner) {
+                if (visitedContainers.has(current)) {
+                    // We've already asked the hook about this container once — a loop
+                    // would form (e.g., hook redirects to a child node whose parent is
+                    // this same container). Skip and walk up.
+                    current = current.parent;
+                    continue;
+                }
+                visitedContainers.add(current);
+                const resolved = resolveEnclosingOwner(current);
+                if (resolved === null) {
+                    // Provider says skip this container — keep walking up.
+                    current = current.parent;
+                    continue;
+                }
+                if (resolved !== current) {
+                    // Provider remapped to a different node — re-evaluate from there.
+                    current = resolved;
+                    continue;
+                }
+            }
+            // Rust impl_item: for `impl Trait for Struct {}`, pick the type after `for`
+            // NOTE: This impl_item ownership logic is mirrored in
+            // method-extractors/configs/rust.ts (extractOwnerName, metadata only).
+            if (current.type === 'impl_item') {
+                const children = current.children ?? [];
+                const forIdx = children.findIndex((c) => c.text === 'for');
+                if (forIdx !== -1) {
+                    const nameNode = children
+                        .slice(forIdx + 1)
+                        .find((c) => c.type === 'type_identifier' ||
+                        c.type === 'scoped_type_identifier' ||
+                        c.type === 'identifier');
+                    if (nameNode) {
+                        // `for` target keeps its raw text. A scoped path (impl T for a::Inner)
+                        // therefore owns through `a::Inner`, which only resolves once the
+                        // referenced struct is keyed by its qualified path — deferred to #1978.
+                        return {
+                            classId: (0, utils_js_1.generateId)('Struct', `${filePath}:${nameNode.text}`),
+                            className: nameNode.text,
+                        };
+                    }
+                }
+                // Inherent impl target.
+                //   - SCOPED (`impl a::Inner`, scoped_type_identifier): key by FULL text,
+                //     matching the @definition.impl scoped arm (#1975). UNCHANGED.
+                //   - UNSCOPED (`impl Inner`, type_identifier): qualify by the enclosing
+                //     `mod_item` scope (`outer.Inner`) so two same-tail bare impls under
+                //     different mods own through DISTINCT nodes. The Impl-node
+                //     materialization (parsing-processor / parse-worker) mirrors this, so
+                //     the owner id == the Impl node id byte-for-byte (#1982).
+                //   - GENERIC (`impl<T> Inner<T>`, generic_type): the @definition.impl
+                //     node is materialized only when the generic base is a bare
+                //     `type_identifier` (tree-sitter-queries.ts), qualified the same way —
+                //     so drill into the base and mirror that gate, keeping the owner id ==
+                //     the node id byte-for-byte (#1992). A generic over a SCOPED base
+                //     (`impl<T> a::Inner<T>`) materializes NO node, so it must produce NO
+                //     owner (the method orphans — scoped-generic deferred, #1992).
+                const implTarget = children.find((c) => c.type === 'type_identifier' ||
+                    c.type === 'scoped_type_identifier' ||
+                    c.type === 'generic_type');
+                if (implTarget) {
+                    const baseType = implTarget.type === 'generic_type'
+                        ? (implTarget.childForFieldName?.('type') ?? null)
+                        : implTarget;
+                    if (baseType?.type === 'type_identifier') {
+                        // Bare target (`impl Inner` or `impl<T> Inner<T>`): qualify by mod scope.
+                        // #1992 follow-up: qualify `className` too (not just `classId`). The
+                        // method node id is keyed `${className}.${name}`, so a bare tail collapses
+                        // two same-tail bare impls that ALSO share a method name (`a::Inner::m` +
+                        // `b::Inner::m` both → `Inner.m`) onto one Method node (graph addNode is
+                        // first-write-wins). Qualifying className → `a.Inner.m` / `b.Inner.m` keeps
+                        // them distinct. Symmetric: the call-resolution fallback rebuilds the same
+                        // `${className}.${name}` from the same enclosing-impl walk, so def and call
+                        // ids still agree. Owner edge anchors on `classId` (already qualified).
+                        const qualified = (0, exports.qualifyRustImplTargetByModScope)(current, baseType.text);
+                        return {
+                            classId: (0, utils_js_1.generateId)('Impl', `${filePath}:${qualified}`),
+                            className: qualified,
+                        };
+                    }
+                    if (baseType?.type === 'scoped_type_identifier' && implTarget.type !== 'generic_type') {
+                        // Top-level scoped `impl a::Inner`: key by full raw text (#1975).
+                        return {
+                            classId: (0, utils_js_1.generateId)('Impl', `${filePath}:${baseType.text}`),
+                            className: baseType.text,
+                        };
+                    }
+                    // generic-over-scoped (`impl<T> a::Inner<T>`) and any other base: fall
+                    // through with no owner — no @definition.impl node exists, so attributing
+                    // a method to a synthesized id would orphan it against a phantom owner.
+                }
+            }
+            const nameNode = current.childForFieldName?.('name') ??
+                current.children?.find((c) => c.type === 'type_identifier' ||
+                    c.type === 'identifier' ||
+                    c.type === 'name' ||
+                    c.type === 'constant');
+            if (nameNode) {
+                let label = exports.CONTAINER_TYPE_TO_LABEL[current.type] || 'Class';
+                // Kotlin: class_declaration with an anonymous "interface" keyword child
+                // is actually an interface, not a class. Refine the label to match the
+                // node ID generated from the tree-sitter query capture (@definition.interface).
+                if (current.type === 'class_declaration' &&
+                    label === 'Class' &&
+                    current.children?.some((c) => c.type === 'interface')) {
+                    label = 'Interface';
+                }
+                // class_declaration with a `declaration_kind` field collapses several
+                // type kinds onto one node (tree-sitter-swift: class / struct / enum /
+                // extension / actor). The structure query labels struct → Struct and
+                // enum → Enum; refine the owner label to match so a member edge
+                // (HAS_METHOD / HAS_PROPERTY) anchors on the real Enum/Struct node id
+                // rather than a non-existent `Class:` id (F79). Gated on the field
+                // being present, so it is a no-op for grammars whose class_declaration
+                // has no `declaration_kind` field (e.g. Kotlin).
+                if (current.type === 'class_declaration' && label === 'Class') {
+                    const declKind = current.childForFieldName?.('declaration_kind')?.text;
+                    if (declKind === 'struct')
+                        label = 'Struct';
+                    else if (declKind === 'enum')
+                        label = 'Enum';
+                }
+                const templateArguments = (0, template_arguments_js_1.extractTemplateArguments)(nameNode.text);
+                const classIdName = templateArguments !== undefined
+                    ? `${(0, template_arguments_js_1.stripTemplateArguments)(nameNode.text)}${(0, template_arguments_js_1.templateArgumentsIdTag)(templateArguments)}`
+                    : nameNode.text;
+                // #1978: when the language opts into qualified node ids, key the owner
+                // edge by the enclosing type's qualified path (e.g. "Outer.Inner") so it
+                // matches the qualified class node id. Derived from the SAME
+                // extractQualifiedName the node-id uses → agree by construction. Only set
+                // when actually nested (qualified !== simple); top-level types are
+                // unchanged. (Go receiver / Rust impl branches return earlier and are
+                // intentionally untouched here.)
+                const qualifiedOwnerName = getQualifiedOwnerName?.(current, nameNode.text);
+                const qualifiedClassId = qualifiedOwnerName != null && qualifiedOwnerName !== nameNode.text
+                    ? (0, utils_js_1.generateId)(label, `${filePath}:${templateArguments !== undefined
+                        ? `${(0, template_arguments_js_1.stripTemplateArguments)(qualifiedOwnerName)}${(0, template_arguments_js_1.templateArgumentsIdTag)(templateArguments)}`
+                        : qualifiedOwnerName}`)
+                    : undefined;
+                return {
+                    classId: (0, utils_js_1.generateId)(label, `${filePath}:${classIdName}`),
+                    className: nameNode.text,
+                    ...(qualifiedClassId !== undefined ? { qualifiedClassId } : {}),
+                };
+            }
+        }
+        current = current.parent;
+    }
+    return null;
+};
+exports.findEnclosingClassInfo = findEnclosingClassInfo;
+/**
+ * Block-statement AST types that disqualify an object-literal binding from
+ * carrying a HAS_METHOD edge. A `const` declared inside one of these is block-
+ * scoped and cannot be imported, so attributing methods to it would create
+ * false-positive cross-file edges.
+ */
+const BLOCK_SCOPE_BOUNDARY_TYPES = new Set([
+    'statement_block',
+    'if_statement',
+    'else_clause',
+    'for_statement',
+    'for_in_statement',
+    'for_of_statement',
+    'while_statement',
+    'do_statement',
+    'try_statement',
+    'catch_clause',
+    'finally_clause',
+    'switch_statement',
+    'switch_case',
+    'switch_default',
+    'with_statement',
+]);
+/**
+ * Find the file-scope variable that owns an object literal method definition.
+ *
+ * Covers TypeScript/JavaScript shorthand object methods such as:
+ *
+ *   export const service = { async load() {} };
+ *
+ * tree-sitter represents `load` as a `method_definition` inside an `object`,
+ * not inside a class container. Without this fallback, ingestion emits a
+ * top-level `Method` node but no edge from the exported `service` value to
+ * that method, so impact queries cannot discover `service.load`.
+ *
+ * Two-phase walk:
+ *   Phase A walks up from `node` tracking how many `object` ancestors we
+ *     cross. The first `variable_declarator` reached with `objectDepth >= 1`
+ *     is the candidate owner — unless `objectDepth > 1` (the method belongs
+ *     to a nested object literal; we return null rather than misattribute
+ *     to the outer binding). Hitting a function/class container before the
+ *     declarator returns null (catches IIFE-wrapped literals).
+ *   Phase B walks the declarator's own ancestors. Any function or class
+ *     ancestor before reaching `program`/`export_statement` returns null
+ *     (catches `const` declared inside a function body). Any block-statement
+ *     ancestor also returns null (catches block-scoped declarations inside
+ *     top-level `if`/`for`/`try`/etc., which cannot be imported).
+ */
+const findObjectLiteralBindingInfo = (node, filePath) => {
+    // ── Phase A: walk up from node, count `object` ancestors, find declarator
+    let current = node;
+    let objectDepth = 0;
+    let declarator = null;
+    while (current) {
+        if (current.type === 'object') {
+            objectDepth += 1;
+        }
+        if (current.type === 'variable_declarator' && objectDepth >= 1) {
+            if (objectDepth > 1) {
+                // Method belongs to a nested object literal; safe under-approximation.
+                return null;
+            }
+            declarator = current;
+            break;
+        }
+        if (current !== node &&
+            (exports.FUNCTION_NODE_TYPES.has(current.type) || exports.CLASS_CONTAINER_TYPES.has(current.type))) {
+            // Function/class container encountered before owning declarator
+            // (e.g. IIFE-wrapped object literal). Bail out.
+            return null;
+        }
+        current = current.parent;
+    }
+    if (!declarator)
+        return null;
+    // ── Phase B: declarator must live at file scope (program / export_statement)
+    // with no function, class, or block-statement ancestor in between.
+    let anc = declarator.parent;
+    while (anc) {
+        if (anc.type === 'program' || anc.type === 'export_statement') {
+            break;
+        }
+        if (exports.FUNCTION_NODE_TYPES.has(anc.type) || exports.CLASS_CONTAINER_TYPES.has(anc.type)) {
+            return null;
+        }
+        if (BLOCK_SCOPE_BOUNDARY_TYPES.has(anc.type)) {
+            return null;
+        }
+        anc = anc.parent;
+    }
+    const nameNode = declarator.childForFieldName?.('name');
+    if (!nameNode || nameNode.type !== 'identifier')
+        return null;
+    const declaration = declarator.parent;
+    const ownerLabel = declaration?.type === 'variable_declaration' ? 'Variable' : 'Const';
+    return {
+        ownerId: (0, utils_js_1.generateId)(ownerLabel, `${filePath}:${nameNode.text}`),
+    };
+};
+exports.findObjectLiteralBindingInfo = findObjectLiteralBindingInfo;
+/**
+ * Find the owner of a member assigned by `<Owner>.prototype.<member> = fn`
+ * (#2723 follow-up).
+ *
+ * Sibling of {@link findObjectLiteralBindingInfo}: same seam, same return
+ * shape, different syntax. There the owner is the variable the literal is
+ * bound to; here it is the identifier to the left of `.prototype`.
+ *
+ * The owner label is read from the file's own module-scope declaration, so the
+ * edge points at the node that actually exists — `function Foo() {}` is a
+ * `Function` node, `class Foo {}` is a `Class` node. When the file declares no
+ * such name (the constructor lives in another module) no owner is claimed:
+ * a HAS_METHOD edge to a fabricated node is worse than a top-level Method.
+ */
+const findMemberAssignmentOwnerInfo = (node, filePath) => {
+    const ownerName = (0, exports.prototypeAssignmentOwnerName)(node) ?? (0, exports.thisAssignmentOwnerName)(node);
+    if (ownerName === null)
+        return null;
+    const root = node.tree?.rootNode;
+    if (!root)
+        return null;
+    const ownerLabel = prototypeOwnerLabel(root, ownerName);
+    if (ownerLabel === null)
+        return null;
+    return { ownerId: (0, utils_js_1.generateId)(ownerLabel, `${filePath}:${ownerName}`), ownerName };
+};
+exports.findMemberAssignmentOwnerInfo = findMemberAssignmentOwnerInfo;
+/** Right-hand-side node types that make an assignment a callable binding. */
+const CALLABLE_ASSIGNMENT_VALUE_TYPES = new Set([
+    'arrow_function',
+    'function_expression',
+    'generator_function',
+]);
+/**
+ * The receiver name of a `<Owner>.prototype.<member> = <function>` assignment,
+ * or null when `assignment` is not that shape.
+ *
+ * Only a bare identifier owner is accepted. `a.b.prototype.c = …` and
+ * `getClass().prototype.c = …` name an owner this layer cannot resolve to a
+ * definition, so they are left alone rather than attributed to a guess.
+ */
+const prototypeAssignmentOwnerName = (assignment) => {
+    const left = callableAssignmentTarget(assignment);
+    if (left === null)
+        return null;
+    const protoRef = left.childForFieldName('object');
+    if (protoRef === null || protoRef.type !== 'member_expression')
+        return null;
+    if (protoRef.childForFieldName('property')?.text !== 'prototype')
+        return null;
+    const owner = protoRef.childForFieldName('object');
+    if (owner === null || owner.type !== 'identifier')
+        return null;
+    return owner.text;
+};
+exports.prototypeAssignmentOwnerName = prototypeAssignmentOwnerName;
+/** The `member_expression` being assigned a function value, or null. */
+const callableAssignmentTarget = (assignment) => {
+    if (assignment.type !== 'assignment_expression')
+        return null;
+    const right = assignment.childForFieldName('right');
+    if (right === null || !CALLABLE_ASSIGNMENT_VALUE_TYPES.has(right.type))
+        return null;
+    const left = assignment.childForFieldName('left');
+    return left !== null && left.type === 'member_expression' ? left : null;
+};
+/**
+ * The constructor function that owns a `this.member = <function>` assignment,
+ * or null when there is none (module top level, or an owner this layer cannot
+ * name).
+ *
+ * Only a `function_declaration` counts. An `arrow_function` does NOT bind its
+ * own `this` (ECMA-262 gives it `[[ThisMode]] = lexical`), so the walk passes
+ * through arrows to the function that actually binds the receiver — the same
+ * rule `@receiver-owner.this` encodes in the scope queries (#2701). A class
+ * method never reaches here: parse-worker resolves its owner from the
+ * enclosing class container first.
+ */
+const thisAssignmentOwnerName = (assignment) => {
+    const left = callableAssignmentTarget(assignment);
+    if (left === null)
+        return null;
+    if (left.childForFieldName('object')?.type !== 'this')
+        return null;
+    for (let anc = assignment.parent; anc !== null; anc = anc.parent) {
+        if (anc.type === 'arrow_function')
+            continue;
+        if (anc.type === 'function_declaration') {
+            const name = anc.childForFieldName('name');
+            return name !== null && name.type === 'identifier' ? name.text : null;
+        }
+        // Any other receiver-binding form (function_expression, method_definition,
+        // generator) owns the `this` but gives this layer no module-scope name to
+        // point an owner edge at.
+        if (exports.FUNCTION_NODE_TYPES.has(anc.type) || exports.CLASS_CONTAINER_TYPES.has(anc.type))
+            return null;
+    }
+    return null;
+};
+exports.thisAssignmentOwnerName = thisAssignmentOwnerName;
+/**
+ * True when `node` is a `X.prototype.Y = <function>` or `this.Y = <function>`
+ * assignment — i.e. a callable MEMBER rather than a free function.
+ *
+ * Takes the ASSIGNMENT node, because that is what the `@definition.function`
+ * capture is anchored on and therefore what `provider.labelOverride` receives.
+ */
+const isPrototypeMemberAssignmentNode = (node) => (0, exports.prototypeAssignmentOwnerName)(node) !== null || (0, exports.isThisMemberAssignmentNode)(node);
+exports.isPrototypeMemberAssignmentNode = isPrototypeMemberAssignmentNode;
+/**
+ * True when `node` is `module.exports = <anonymous function>` (#2723).
+ *
+ * The whole module IS the callable, so there is no property to take a name
+ * from and the caller supplies a file-derived one. A NAMED function expression
+ * is excluded — its own name is captured directly and is more informative.
+ */
+/**
+ * True when `node` is `module.exports = <function>`, named or anonymous — the
+ * CommonJS default export, where the whole module IS the callable.
+ *
+ * `exports = fn` is deliberately NOT this shape: reassigning the `exports`
+ * binding does not export anything in CommonJS, it only breaks the alias to
+ * `module.exports`.
+ */
+const isCjsDefaultExportAssignment = (node) => {
+    if (node.type !== 'assignment_expression')
+        return false;
+    const right = node.childForFieldName('right');
+    if (right === null || !CALLABLE_ASSIGNMENT_VALUE_TYPES.has(right.type))
+        return false;
+    const left = node.childForFieldName('left');
+    if (left === null || left.type !== 'member_expression')
+        return false;
+    return (left.childForFieldName('object')?.text === 'module' &&
+        left.childForFieldName('property')?.text === 'exports');
+};
+exports.isCjsDefaultExportAssignment = isCjsDefaultExportAssignment;
+/** True when `node` is a `this.Y = <function>` assignment, at any nesting. */
+const isThisMemberAssignmentNode = (node) => {
+    const left = callableAssignmentTarget(node);
+    return left !== null && left.childForFieldName('object')?.type === 'this';
+};
+exports.isThisMemberAssignmentNode = isThisMemberAssignmentNode;
+/**
+ * The label the owner named by {@link prototypeAssignmentOwnerName} carries in
+ * the graph, so the owner edge points at the node that actually exists.
+ * Returns null when the file declares no such module-scope name.
+ */
+const prototypeOwnerLabel = (root, ownerName) => {
+    for (const child of root.namedChildren) {
+        const decl = child.type === 'export_statement' ? child.childForFieldName('declaration') : child;
+        if (decl === null)
+            continue;
+        if (decl.childForFieldName('name')?.text === ownerName) {
+            if (decl.type === 'class_declaration')
+                return 'Class';
+            if (decl.type === 'function_declaration' || decl.type === 'generator_function_declaration')
+                return 'Function';
+        }
+        // `var Foo = function () {}` / `const Foo = () => {}` / `const Foo = class {}`.
+        // The dominant pre-ES6 constructor form, and the population this whole
+        // change targets. Without it `prototypeOwnerLabel` returned null, the
+        // member fell back to an UNQUALIFIED `Method:<file>:<member>` id, and two
+        // constructors defining the same member name in one file collapsed onto a
+        // single node with no owner edges at all (#2729 review F6).
+        if (!VARIABLE_DECLARATION_NODE_TYPES.has(decl.type))
+            continue;
+        for (const declarator of decl.namedChildren) {
+            if (declarator.type !== 'variable_declarator')
+                continue;
+            if (declarator.childForFieldName('name')?.text !== ownerName)
+                continue;
+            const value = declarator.childForFieldName('value');
+            if (value === null)
+                continue;
+            // Only a callable value is claimed. A closure binding reliably emits
+            // `Function:<file>:<name>` (the #2687/#2693 convention), so the owner id
+            // resolves to a node that exists. A class EXPRESSION or a require()-bound
+            // value names an owner whose node label this layer cannot predict —
+            // claim none rather than point an edge at a node that may not exist,
+            // which is the same defect class this fix exists to remove.
+            if (CALLABLE_ASSIGNMENT_VALUE_TYPES.has(value.type))
+                return 'Function';
+        }
+    }
+    return null;
+};
+/** Declaration nodes carrying `variable_declarator` children (JS/TS). */
+const VARIABLE_DECLARATION_NODE_TYPES = new Set([
+    'lexical_declaration',
+    'variable_declaration',
+]);
+/** Convenience wrapper: returns just the class ID string (backward compat). */
+const findEnclosingClassId = (node, filePath) => {
+    return (0, exports.findEnclosingClassInfo)(node, filePath)?.classId ?? null;
+};
+exports.findEnclosingClassId = findEnclosingClassId;
+/**
+ * Find a child of `childType` within a sibling node of `siblingType`.
+ * Used for Kotlin AST traversal where visibility_modifier lives inside a modifiers sibling.
+ */
+const findSiblingChild = (parent, siblingType, childType) => {
+    for (let i = 0; i < parent.childCount; i++) {
+        const sibling = parent.child(i);
+        if (sibling?.type === siblingType) {
+            for (let j = 0; j < sibling.childCount; j++) {
+                const child = sibling.child(j);
+                if (child?.type === childType)
+                    return child;
+            }
+        }
+    }
+    return null;
+};
+exports.findSiblingChild = findSiblingChild;
+/** Generic name extraction from a function-like AST node.
+ *  Tries `node.childForFieldName('name')?.text`, then scans children for
+ *  `identifier` / `property_identifier` / `simple_identifier`.
+ *
+ *  `arrow_function` and `function_expression` (TS/JS) are inherently
+ *  anonymous — they have no `name` field, and their first identifier
+ *  child is a *parameter*, not a function name. Returning a parameter
+ *  identifier here would synthesize phantom Function IDs (e.g. callers
+ *  walking up from a call inside `arr.map(x => fn(x))` would get
+ *  attributed to a non-existent "Function x"). The language's
+ *  `methodExtractor.extractFunctionName` hook is responsible for naming
+ *  these via parent context (variable_declarator, pair, etc.); when it
+ *  declines, the parent walk should continue rather than fall through
+ *  here. See issue #1166. */
+const genericFuncName = (node) => {
+    const nameField = node.childForFieldName?.('name');
+    if (nameField)
+        return nameField.text;
+    if (node.type === 'arrow_function' || node.type === 'function_expression') {
+        return null;
+    }
+    for (let i = 0; i < node.childCount; i++) {
+        const c = node.child(i);
+        if (c?.type === 'identifier' ||
+            c?.type === 'property_identifier' ||
+            c?.type === 'simple_identifier')
+            return c.text;
+    }
+    return null;
+};
+exports.genericFuncName = genericFuncName;
+/** AST node types that represent a method definition (for `inferFunctionLabel`). */
+exports.METHOD_LABEL_NODE_TYPES = new Set([
+    'method_definition',
+    'method_declaration',
+    'method',
+    'singleton_method',
+]);
+/** AST node types that represent a constructor definition (for `inferFunctionLabel`). */
+exports.CONSTRUCTOR_LABEL_NODE_TYPES = new Set([
+    'constructor_declaration',
+    'compact_constructor_declaration',
+]);
+/** Infer node label from AST node type for function-like nodes without a provider hook. */
+const inferFunctionLabel = (nodeType) => exports.METHOD_LABEL_NODE_TYPES.has(nodeType)
+    ? 'Method'
+    : exports.CONSTRUCTOR_LABEL_NODE_TYPES.has(nodeType)
+        ? 'Constructor'
+        : 'Function';
+exports.inferFunctionLabel = inferFunctionLabel;
+/** Argument list node types shared between countCallArguments and call-resolution helpers. */
+exports.CALL_ARGUMENT_LIST_TYPES = new Set(['arguments', 'argument_list', 'value_arguments']);
+/**
+ * Function/method parameter-list node types across grammars. Used to tell a
+ * PARAMETER-property (a constructor parameter that is also a class field, e.g.
+ * TypeScript `constructor(public name: string)`) apart from a function-BODY
+ * local: a property reached through one of these — rather than through the
+ * function's executable body — is a genuine class member, so the
+ * function-local-property guard must NOT strip its owner edge.
+ */
+exports.PARAMETER_LIST_NODE_TYPES = new Set([
+    'formal_parameters', // TypeScript / JavaScript
+    'parameters', // Python / C#
+    'parameter_list', // Java / Go / C / Swift
+    'function_value_parameters', // Kotlin
+    'class_parameters', // Scala-like / future grammars
+]);
+/**
+ * Executable local-scope boundaries for the property-ownership guard
+ * (`isFunctionLocalProperty` in parse-worker.ts). A `Property` capture whose
+ * nearest enclosing scope — walking up before any class container — is one of
+ * these executable bodies is a function-local binding, NOT a class member, so it
+ * must not receive a class `HAS_PROPERTY` owner edge.
+ *
+ * Derived from FUNCTION_NODE_TYPES, with two deliberate adjustments found by the
+ * #1919 review of the original guard:
+ *  - EXCLUDES Dart's bare signature wrappers (`function_signature` /
+ *    `method_signature`). A Dart getter/setter NAME lives under `method_signature`,
+ *    yet it is a class-member declaration, not a local inside an executable body;
+ *    treating the signature as a scope boundary OVER-stripped every Dart class
+ *    accessor's owner edge. (Signatures are Dart-only; no language emits a
+ *    legitimately-function-local Property under one.)
+ *  - INCLUDES accessor + initializer bodies (Kotlin `anonymous_initializer` /
+ *    `getter` / `setter`, Swift `computed_property` / `computed_getter` /
+ *    `computed_setter` / `computed_modify`). Destructuring/locals inside these ARE
+ *    function-local, yet they are absent from FUNCTION_NODE_TYPES; omitting them
+ *    UNDER-stripped and emitted spurious class `HAS_PROPERTY` edges for
+ *    `init {}` / accessor-body destructuring bindings.
+ *
+ * Kept separate from FUNCTION_NODE_TYPES because that set has many other consumers
+ * (e.g. enclosing-callable resolution) where signatures must remain function nodes
+ * and accessor bodies must not.
+ */
+exports.LOCAL_SCOPE_BODY_NODE_TYPES = new Set([...exports.FUNCTION_NODE_TYPES]
+    .filter((t) => t !== 'function_signature' && t !== 'method_signature')
+    .concat([
+    'anonymous_initializer', // Kotlin: init { }
+    'getter', // Kotlin: val x get() { }
+    'setter', // Kotlin: var x set(v) { }
+    'computed_property', // Swift: var x: T { get set }
+    'computed_getter', // Swift: get { }
+    'computed_setter', // Swift: set { }
+    'computed_modify', // Swift: _modify { }
+]));
+/**
+ * Callable node types whose grammar splits the body off into a SIBLING node, so
+ * the callable is never an ancestor of the code inside it (Dart
+ * `function_signature` / `method_signature`).
+ *
+ * Derived, not listed, so it cannot drift from the two sets that define it:
+ * `LOCAL_SCOPE_BODY_NODE_TYPES` is `FUNCTION_NODE_TYPES` minus exactly the bare
+ * signature types, so the difference IS the split-signature set.
+ *
+ * Must stay BELOW `LOCAL_SCOPE_BODY_NODE_TYPES` — reading it earlier hits the
+ * temporal dead zone and throws at module load.
+ */
+exports.SPLIT_SIGNATURE_NODE_TYPES = new Set([...exports.FUNCTION_NODE_TYPES].filter((t) => !exports.LOCAL_SCOPE_BODY_NODE_TYPES.has(t)));
+// ============================================================================
+// Generic AST traversal helpers (shared by parse-worker + php-helpers)
+// ============================================================================
+/** Walk an AST node depth-first, returning the first descendant with the given type. */
+function findDescendant(root, type) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node.type === type)
+            return node;
+        // Push in reverse order so left children are visited first (depth-first)
+        const children = node.children ?? [];
+        for (let i = children.length - 1; i >= 0; i--) {
+            stack.push(children[i]);
+        }
+    }
+    return null;
+}
+/** Extract the text content from a string or encapsed_string AST node. */
+function extractStringContent(node) {
+    if (!node)
+        return null;
+    const content = node.children?.find((c) => c.type === 'string_content');
+    if (content)
+        return content.text;
+    if (node.type === 'string_content')
+        return node.text;
+    return null;
+}
+/** Find the first direct named child of a tree-sitter node matching the given type. */
+function findChild(node, type) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type === type)
+            return child;
+    }
+    return null;
+}
+/** Remove bidi-override and zero-width control characters from attacker-
+ *  influenced repository text before it is exposed through graph descriptions
+ *  or MCP output (#2286). Global `sanitizeUTF8` intentionally remains focused
+ *  on encoding/control-character validity. */
+const stripBidiAndZeroWidth = (text) => Array.from(text)
+    .filter((ch) => {
+    const c = ch.codePointAt(0) ?? 0;
+    // Bidi overrides/isolates (U+202A–202E, U+2066–2069), zero-width
+    // space/joiners (U+200B–200D), and BOM/zero-width-no-break (U+FEFF).
+    return !((c >= 0x202a && c <= 0x202e) ||
+        (c >= 0x2066 && c <= 0x2069) ||
+        (c >= 0x200b && c <= 0x200d) ||
+        c === 0xfeff);
+})
+    .join('');
+exports.stripBidiAndZeroWidth = stripBidiAndZeroWidth;
+/** Normalize a block doc comment body: strip the opening (double-star or
+ *  bang) delimiter, the closing delimiter, and per-line gutter stars, then
+ *  collapse whitespace so tag content stays as searchable words. */
+const normalizeBlockDocComment = (text) => {
+    const inner = (0, exports.stripBidiAndZeroWidth)(text
+        .replace(/^\/\*[*!]/, '')
+        // Close delimiter: tolerate the degenerate empty comment `/**/`, where the
+        // opening strip already consumed the shared `*`, leaving a lone `/`.
+        .replace(/\*?\/\s*$/, '')
+        .replace(/^[ \t]*\*[ \t]?/gm, ' ')
+        .replace(/\s+/g, ' ')
+        .trim());
+    return inner.length > 0 ? inner : undefined;
+};
+/** Default line-comment prefixes treated as documentation: the universal
+ *  triple-slash / bang-slash doc markers (Rust, C#, Dart, Swift, Doxygen).
+ *  Go (`//`) and Ruby (`#`) opt into their conventional markers explicitly. */
+const DEFAULT_LINE_DOC_PREFIXES = ['///', '//!'];
+/** Default block-comment doc openers: Javadoc/JSDoc-style `/**` and Doxygen
+ *  `/*!`. Rust opts out of `/*!` (and `//!`) because those are *inner* docs that
+ *  document the enclosing item, not the following one. */
+const DEFAULT_BLOCK_DOC_PREFIXES = ['/**', '/*!'];
+/** A file-top `/** … *\/` license/copyright/file-overview block has no
+ *  package/import sibling to shield it, so it would otherwise be absorbed as the
+ *  first declaration's description (PR #2286 review). These markers identify such
+ *  headers; they are specific enough not to fire on an ordinary symbol doc that
+ *  merely mentions the word "copyright". `@file`/`@fileoverview` are explicitly
+ *  file-level JSDoc tags, so a block carrying them is not a symbol doc. */
+const FILE_HEADER_MARKER = /SPDX-License-Identifier|@licen[sc]e\b|@fileoverview\b|@file\b|Licen[sc]ed under|copyright\s*(\(c\)|©|\d{4})/i;
+function extractLeadingDocComment(node, opts = {}) {
+    const lineCommentPrefixes = opts.lineCommentPrefixes ?? DEFAULT_LINE_DOC_PREFIXES;
+    const wrapperNodeTypes = opts.wrapperNodeTypes ?? [];
+    const lineDirectivePrefixes = opts.lineDirectivePrefixes ?? [];
+    const blockDocPrefixes = opts.blockDocPrefixes ?? DEFAULT_BLOCK_DOC_PREFIXES;
+    const fromNode = (anchor) => {
+        const prev = anchor.previousNamedSibling;
+        if (!prev)
+            return undefined;
+        // Block doc comment: /** ... */ or /*! ... */
+        if (blockDocPrefixes.some((p) => prev.text.startsWith(p))) {
+            // Skip a file-top license/copyright/overview header (no package/import
+            // sibling shields it from the first declaration). A strict row-adjacency
+            // check is unreliable here — some grammars fold the trailing newline into
+            // the comment node — so match header markers instead.
+            if (FILE_HEADER_MARKER.test(prev.text))
+                return undefined;
+            return normalizeBlockDocComment(prev.text);
+        }
+        // Run of row-adjacent preceding line doc comments (e.g. `///` or `//`).
+        const matchedPrefix = (text) => lineCommentPrefixes.find((prefix) => text.trimStart().startsWith(prefix));
+        const isDirective = (text) => lineDirectivePrefixes.some((prefix) => text.trimStart().startsWith(prefix));
+        const lines = [];
+        let current = prev;
+        let expectedRow = anchor.startPosition.row - 1;
+        while (current) {
+            const text = current.text;
+            const prefix = matchedPrefix(text);
+            if (prefix === undefined || current.startPosition.row !== expectedRow)
+                break;
+            // A build/tool directive or magic comment (e.g. `//go:build`,
+            // `# frozen_string_literal:`) is not documentation: skip it but keep
+            // walking the adjacent run, so a real doc above it is still collected.
+            if (!isDirective(text))
+                lines.unshift(text.trimStart().slice(prefix.length));
+            expectedRow = current.startPosition.row - 1;
+            current = current.previousNamedSibling;
+        }
+        const joined = (0, exports.stripBidiAndZeroWidth)(lines.join(' ').replace(/\s+/g, ' ').trim());
+        return joined.length > 0 ? joined : undefined;
+    };
+    const direct = fromNode(node);
+    if (direct !== undefined)
+        return direct;
+    const parent = node.parent;
+    if (parent && wrapperNodeTypes.includes(parent.type)) {
+        return fromNode(parent);
+    }
+    return undefined;
+}
+/** Node labels that can carry a leading doc comment — callables and type-like
+ *  declarations. Field/property/variable/const doc is intentionally excluded
+ *  (issue #2270 scopes this to method/type documentation). Language-neutral:
+ *  a label a given grammar never emits simply never matches.
+ *
+ *  Bounded to labels that are also in `embeddings/types.ts` `EMBEDDABLE_LABELS`:
+ *  the description is only useful once it reaches the embedding metadata header,
+ *  and the embedding pipeline only queries embeddable labels. Extracting docs
+ *  for a non-embeddable label is a wasted write that never becomes searchable.
+ *  A subset invariant in the unit tests guards against drift. Making currently-
+ *  non-embeddable doc-bearing labels (Module, Delegate, Annotation, and C++
+ *  `Template`) searchable is tracked as a follow-up — it needs an embedding-
+ *  pipeline/schema change beyond this fix. */
+exports.DOC_BEARING_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    'Class',
+    'Interface',
+    'Enum',
+    'Struct',
+    'Trait',
+    'Record',
+    'Union',
+    'Namespace',
+    'TypeAlias',
+    'Macro',
+]);
+/**
+ * Build a `LanguageProvider.descriptionExtractor` that surfaces a definition's
+ * leading doc comment as its `description` (issue #2270). For labels in
+ * {@link DOC_BEARING_LABELS} (which is bounded to embeddable labels) the text
+ * then reaches the embedding metadata header and becomes semantically searchable.
+ *
+ * Language-neutral factory (names no language): guards on
+ * {@link DOC_BEARING_LABELS}; callers pass per-language doc-comment behavior via
+ * {@link LeadingDocCommentOptions} (line prefixes, export-style wrappers, …)
+ * which is threaded straight through to {@link extractLeadingDocComment}.
+ */
+const createLeadingDocDescriptionExtractor = (opts = {}) => {
+    return (nodeLabel, _nodeName, captureMap) => {
+        if (!exports.DOC_BEARING_LABELS.has(nodeLabel))
+            return undefined;
+        const definitionNode = (0, exports.getDefinitionNodeFromCaptures)(captureMap);
+        return definitionNode ? extractLeadingDocComment(definitionNode, opts) : undefined;
+    };
+};
+exports.createLeadingDocDescriptionExtractor = createLeadingDocDescriptionExtractor;
+// ============================================================================
+// Capture + range helpers (formerly python/ast-utils.ts — language-agnostic)
+// ============================================================================
+/** Convert a tree-sitter node to a `Capture` with 1-based line numbers
+ *  (matching RFC §2.1). The tag includes the leading `@`. */
+function nodeToCapture(name, node) {
+    return {
+        name,
+        range: {
+            startLine: node.startPosition.row + 1,
+            startCol: node.startPosition.column,
+            endLine: node.endPosition.row + 1,
+            endCol: node.endPosition.column,
+        },
+        text: node.text,
+    };
+}
+/** Build a `Capture` whose range mirrors `atNode` but whose `text` is
+ *  caller-supplied. Used to synthesize markers that don't have a
+ *  corresponding source token. */
+function syntheticCapture(name, atNode, text) {
+    return {
+        name,
+        range: {
+            startLine: atNode.startPosition.row + 1,
+            startCol: atNode.startPosition.column,
+            endLine: atNode.endPosition.row + 1,
+            endCol: atNode.endPosition.column,
+        },
+        text,
+    };
+}
+function rangeMatches(node, range) {
+    return (node.startPosition.row + 1 === range.startLine &&
+        node.startPosition.column === range.startCol &&
+        node.endPosition.row + 1 === range.endLine &&
+        node.endPosition.column === range.endCol);
+}
+/** Walk a subtree to find a node whose range exactly matches AND whose
+ *  type matches `expectedType` (when given). When multiple nodes share
+ *  the range — e.g., `function_definition` and its inner `block` body
+ *  for a one-liner — the type filter disambiguates.
+ *
+ *  Iterative depth-first-left-to-right via an explicit stack. Children
+ *  are pushed in reverse index order so LIFO pop visits them in source
+ *  order. Prunes branches that can't contain the target range by
+ *  row bounds — same optimization the prior recursive form used, minus
+ *  the early-break since stack-push is cheap. */
+function findNodeAtRange(root, range, expectedType) {
+    const startRow = range.startLine - 1;
+    const endRow = range.endLine - 1;
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (rangeMatches(node, range) && (expectedType === undefined || node.type === expectedType)) {
+            return node;
+        }
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child === null)
+                continue;
+            if (child.endPosition.row < startRow)
+                continue;
+            if (child.startPosition.row > endRow)
+                continue;
+            stack.push(child);
+        }
+    }
+    return null;
+}
+/**
+ * Return the captured node if its type is one of `types`, else null.
+ *
+ * The threaded-node equivalent of `findNodeAtRange(root, capture.range, type)`
+ * for the common case where a tree-sitter query already hands you the matched
+ * node (`c.node`): the captured node IS the node at that range, so a type check
+ * is exact and there is no need to re-walk from the tree root (the
+ * O(matches × rootChildren) hot path #1848 hit). Unlike `findNodeAtRange`, this
+ * does NOT traverse — the caller must already hold the node; for a multi-type
+ * call the node must literally be one of `types` (no fallback search).
+ *
+ * Used by every language's scope-capture path (go/python/ruby/php/rust/csharp).
+ */
+function nodeIfType(node, ...types) {
+    return node !== undefined && types.includes(node.type) ? node : null;
+}