cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/languages/typescript/receiver-binding.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * Synthesize `@type-binding.this` captures for TypeScript instance-like
+ * methods.
+ *
+ * Tree-sitter can't cleanly express "the implicit `this` receiver of a
+ * non-static member of a class / interface / abstract class" via a
+ * static `.scm` pattern, so we walk up the AST in code — mirrors
+ * Python's `self` / `cls` and C#'s `this` / `base` synthesis.
+ *
+ * Scope coverage:
+ *
+ *   - `method_definition` inside `class_declaration`,
+ *     `abstract_class_declaration`, or `class_expression` → synthesize
+ *     `this` → enclosing class name.
+ *   - `method_signature` / `abstract_method_signature` inside
+ *     `interface_declaration` or `abstract_class_declaration` →
+ *     synthesize `this` → enclosing type's name (so interface method
+ *     bodies' `this.x` chains resolve via the interface's field
+ *     annotations).
+ *   - `arrow_function` / `function_expression` that is a direct value
+ *     of a `public_field_definition` (class field) — `m = () => {}` —
+ *     synthesize `this` → enclosing class name. These capture `this`
+ *     lexically; without synthesis, their body's `this.foo` wouldn't
+ *     resolve.
+ *
+ * Not synthesized (intentionally):
+ *
+ *   - `static` methods / static fields. `this` in a static context
+ *     refers to the class constructor, not an instance; we leave the
+ *     binding empty and let chain resolution fall through to the
+ *     class's static members lookup.
+ *   - Regular `function_declaration` / `function_expression` at
+ *     module level or in a non-class context. No enclosing type, no
+ *     `this` semantics.
+ *   - Arrow functions nested inside a method body. The scope-chain
+ *     walk in `tsReceiverBinding` finds the outer method's `this`
+ *     naturally, matching TS's lexical-this rule for arrow functions.
+ *
+ * Each synthesized match emits the anchor captures needed by
+ * `interpretTsTypeBinding`:
+ *
+ *   `@type-binding.this`  (source discriminator — interpret maps to 'self')
+ *   `@type-binding.name`  (the literal `'this'`)
+ *   `@type-binding.type`  (the enclosing type's name)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.THIS_REBINDING_BOUNDARY_TYPES = void 0;
+exports.synthesizeTsReceiverBinding = synthesizeTsReceiverBinding;
+const ast_helpers_js_1 = require("../../utils/ast-helpers.js");
+/** Node types that define a TypeScript "type with instance members". */
+const TYPE_DECL_NODE_TYPES = new Set([
+    'class_declaration',
+    'abstract_class_declaration',
+    'class',
+    'interface_declaration',
+]);
+/** Scope function nodes that could be a class method body. */
+const CLASS_MEMBER_FUNCTION_TYPES = new Set([
+    'method_definition',
+    'method_signature',
+    'abstract_method_signature',
+]);
+/** Function-like values that can back a class field (`m = () => {}`). */
+const CLASS_FIELD_FUNCTION_TYPES = new Set(['arrow_function', 'function_expression']);
+/**
+ * Produce zero or one `CaptureMatch` synthesizing `this` for `fnNode`.
+ *
+ *   - `null` — function has no synthetic `this` (free / static /
+ *     not-in-class / no name on enclosing type).
+ *   - One match — anchor on the function body so the synthetic binding
+ *     attaches to the function's scope (not the outer class scope).
+ *
+ * The caller is responsible for passing a `fnNode` whose type is one
+ * of the scope function nodes the scope query emits.
+ */
+function synthesizeTsReceiverBinding(fnNode) {
+    // Classify the function's role.
+    const role = classifyFunctionRole(fnNode);
+    if (role === null)
+        return null;
+    // Static methods / static fields don't have an instance `this`.
+    if (isStaticMember(role.memberNode))
+        return null;
+    // Find enclosing type declaration. Walking past function-like
+    // boundaries is fine — nested local functions inside a method can
+    // still reference outer `this` through the lexical chain, but we
+    // only synthesize on the immediate function body. The resolver's
+    // scope-chain walk reaches ancestor synthesized bindings for nested
+    // arrow functions.
+    const enclosingType = findEnclosingType(role.memberNode);
+    if (enclosingType === null)
+        return null;
+    const typeName = getTypeDeclName(enclosingType);
+    if (typeName === null)
+        return null;
+    // Anchor the synthetic capture on the function body so the binding
+    // lands in the method's scope, not its parent type scope. Method
+    // signatures in interfaces / abstract classes have no body — use
+    // the method node itself as the anchor; scope-extractor attaches
+    // it to the function scope created by the `@scope.function`
+    // anchor at the same range.
+    const anchorNode = fnNode.childForFieldName('body') ?? fnNode;
+    return buildThisBinding(anchorNode, typeName);
+}
+/**
+ * Decide whether `fnNode` participates as a class member. Returns
+ * `null` when the function is not structurally "a class instance
+ * member" — e.g. a free function, a non-method arrow expression, an
+ * arrow inside a method body (those inherit `this` via scope chain
+ * lookup, no synthesis needed).
+ */
+function classifyFunctionRole(fnNode) {
+    if (CLASS_MEMBER_FUNCTION_TYPES.has(fnNode.type)) {
+        return { memberNode: fnNode };
+    }
+    if (CLASS_FIELD_FUNCTION_TYPES.has(fnNode.type)) {
+        // `public_field_definition` represents a class field. Only when
+        // the arrow/function-expression is a DIRECT value of a field do
+        // we treat it as a class method with synthesized `this`.
+        const parent = fnNode.parent;
+        if (parent !== null && parent.type === 'public_field_definition') {
+            const valueField = parent.childForFieldName('value');
+            if (valueField !== null && valueField.startIndex === fnNode.startIndex) {
+                return { memberNode: parent };
+            }
+        }
+    }
+    return null;
+}
+/** Class-body definitions carry an optional `accessibility_modifier` and
+ *  optional `static` keyword as named children. The `static` token is
+ *  usually a plain child of the member node — not a named field — so
+ *  we scan children for a token whose text is exactly `static`. */
+function isStaticMember(memberNode) {
+    for (let i = 0; i < memberNode.childCount; i++) {
+        const c = memberNode.child(i);
+        if (c === null)
+            continue;
+        // `static` can appear as an unnamed token or as a `readonly` /
+        // `static` keyword node depending on grammar version; check text.
+        if (c.text === 'static')
+            return true;
+    }
+    return false;
+}
+/**
+ * Nodes that REBIND `this`, so the walk for an enclosing type must stop at them.
+ *
+ * Without these the walk ran to the top of the file and happily synthesized a binding
+ * from a type that does not own the member. An object-literal method nested in a class
+ * bound `this` to the CLASS:
+ *
+ *     class A { outer() { const o = { inner() { return this.x; } }; return o; } }
+ *
+ * `this` inside `o.inner` is `o`, never `A` — so every `this.…` in such a method
+ * resolved against the wrong type. Only the module-level object literal escaped, because
+ * there was no enclosing class to reach.
+ *
+ * An arrow is deliberately absent: it inherits `this` lexically, so the walk SHOULD pass
+ * through it (that is what makes a class-field arrow `m = () => this.x` resolve).
+ */
+exports.THIS_REBINDING_BOUNDARY_TYPES = new Set([
+    'object', // object literal — `this` is the literal, not any enclosing type
+    'function_declaration',
+    'function_expression',
+    'generator_function',
+    'generator_function_declaration',
+]);
+function findEnclosingType(node) {
+    let cur = node.parent;
+    while (cur !== null) {
+        // Boundary before the type check: a rebinding node between the member and a type
+        // means the type does not own this `this`.
+        if (exports.THIS_REBINDING_BOUNDARY_TYPES.has(cur.type))
+            return null;
+        if (TYPE_DECL_NODE_TYPES.has(cur.type))
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+/** Return the declared name of a class / interface / abstract-class.
+ *  `class_expression` ( `const X = class { … }` ) may lack a name —
+ *  in that case we return `null` and the caller skips synthesis (the
+ *  outer variable's name is the usable handle, but wiring it would
+ *  require a separate walk; defer to a follow-up). */
+function getTypeDeclName(typeNode) {
+    const nameField = typeNode.childForFieldName('name');
+    if (nameField === null)
+        return null;
+    return nameField.text;
+}
+function buildThisBinding(anchorNode, typeText) {
+    const m = {
+        '@type-binding.this': (0, ast_helpers_js_1.nodeToCapture)('@type-binding.this', anchorNode),
+        '@type-binding.name': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.name', anchorNode, 'this'),
+        '@type-binding.type': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.type', anchorNode, typeText),
+    };
+    return m;
+}

package/dist/core/code/engine/core/ingestion/languages/typescript/scope-resolver.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * TypeScript `ScopeResolver` registered in `SCOPE_RESOLVERS` and
+ * consumed by the generic `runScopeResolution` orchestrator
+ * (RFC #909 Ring 3).
+ *
+ * Third migration after Python and C#. Follows the same minimal
+ * wiring-only pattern — per-hook logic lives in the sibling modules
+ * (`arity.ts`, `merge-bindings.ts`, `import-target.ts`, etc.).
+ *
+ * See ./index.ts for the per-module rationale and the full list of
+ * known limitations. The canonical capture vocabulary is pinned in
+ * ./query.ts (TYPESCRIPT_SCOPE_QUERY constant).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typescriptScopeResolver = void 0;
+const index_js_1 = require("../../../../../shared/index.js");
+const utils_js_1 = require("../../../../lib/utils.js");
+const mro_js_1 = require("../../scope-resolution/passes/mro.js");
+const walkers_js_1 = require("../../scope-resolution/scope/walkers.js");
+const node_lookup_js_1 = require("../../scope-resolution/graph-bridge/node-lookup.js");
+const typescript_js_1 = require("../typescript.js");
+const language_config_js_1 = require("../../language-config.js");
+const utils_js_2 = require("../../import-resolvers/utils.js");
+const shared_js_1 = require("../../type-extractors/shared.js");
+const index_js_2 = require("./index.js");
+const nuxt_auto_imports_js_1 = require("./nuxt-auto-imports.js");
+const TYPESCRIPT_TYPE_ONLY_BINDING_TYPES = new Set([
+    'Interface',
+    'Type',
+    'TypeAlias',
+    'Typedef',
+    'Trait',
+    'Annotation',
+    'Decorator',
+]);
+/**
+ * Build a `resolveImportTarget` adapter that memoizes the workspace
+ * file list, the lower-cased file list, and the per-pass `resolveCache`
+ * across every import lookup in a single workspace pass. The
+ * orchestrator passes the same `ReadonlySet` reference for every call
+ * within a pass — we use that identity to detect when the workspace
+ * changes and recompute the derived state lazily.
+ *
+ * Without this memoization, `resolveTsTarget` re-derived
+ * `allFileList` and `normalizedFileList` (both O(N_files)) and threw
+ * away the `resolveCache` on every import — O(N_files × N_imports)
+ * total work for what should be O(N_files + N_imports).
+ */
+function makeTsResolveImportTarget() {
+    let cached = null;
+    return (targetRaw, fromFile, allFilePaths, resolutionConfig) => {
+        if (cached === null || cached.key !== allFilePaths) {
+            const allFileList = Array.from(allFilePaths);
+            const normalizedFileList = allFileList.map((f) => f.toLowerCase());
+            cached = {
+                key: allFilePaths,
+                allFilePaths: new Set(allFilePaths),
+                allFileList,
+                normalizedFileList,
+                index: (0, utils_js_2.buildSuffixIndex)(normalizedFileList, allFileList),
+                resolveCache: new Map(),
+            };
+        }
+        const cfg = resolutionConfig;
+        const ws = {
+            fromFile,
+            allFilePaths: cached.allFilePaths,
+            allFileList: cached.allFileList,
+            normalizedFileList: cached.normalizedFileList,
+            index: cached.index,
+            resolveCache: cached.resolveCache,
+            tsconfigPaths: cfg?.tsconfigPaths ?? null,
+        };
+        return (0, index_js_2.resolveTsTarget)(targetRaw, ws);
+    };
+}
+const typescriptScopeResolver = {
+    // One hook, both routes. TypeScript exposes collection views as METHOD calls
+    // (`.values()`), which the call-expression branch already handles, so the
+    // accessor route yields nothing here — but it is now the same hook rather
+    // than a second one left undefined.
+    elementTypeOf: shared_js_1.indexOnlyElementType,
+    // Construction is keyword-prefixed: `new Service(db).doWork()` (#2708).
+    constructionSyntax: { keyword: 'new' },
+    language: index_js_1.SupportedLanguages.TypeScript,
+    languageProvider: typescript_js_1.typescriptProvider,
+    importEdgeReason: 'typescript-scope: import',
+    resolveImportTarget: makeTsResolveImportTarget(),
+    // Threaded into `resolveImportTarget` so tsconfig path aliases
+    // (`@/services/user`, `~/x`, ...) resolve through the same standard
+    // resolver branch the legacy DAG uses. One I/O round-trip per
+    // workspace pass; the orchestrator awaits this once.
+    // `nuxtAutoImports` is null for non-Nuxt projects (no .nuxt/imports.d.ts),
+    // so this adds zero overhead to ordinary TypeScript repos.
+    loadResolutionConfig: async (repoPath) => ({
+        tsconfigPaths: await (0, language_config_js_1.loadTsconfigPaths)(repoPath),
+        nuxtAutoImports: await (0, nuxt_auto_imports_js_1.loadNuxtAutoImports)(repoPath),
+    }),
+    // TypeScript declaration merging + LEGB: local > import > wildcard,
+    // separated by declaration space (value / type / namespace). The
+    // per-scope id is unused (shadowing is computed from origin + def.type),
+    // so we don't need to synthesize a Scope here.
+    mergeBindings: (existing, incoming) => [...(0, index_js_2.typescriptMergeBindings)([...existing, ...incoming])],
+    // Adapter: typescriptArityCompatibility uses (def, callsite); the
+    // ScopeResolver contract is (callsite, def).
+    arityCompatibility: (callsite, def) => (0, index_js_2.typescriptArityCompatibility)(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => (0, mro_js_1.buildMro)(graph, parsedFiles, nodeLookup, mro_js_1.defaultLinearize),
+    populateOwners: (parsed) => (0, walkers_js_1.populateClassOwnedMembers)(parsed),
+    // TypeScript uses `super` for super-class dispatch as a plain
+    // identifier or as `super()` in constructors. Match both — `super`
+    // on its own (`super.foo`, `super[x]`) and `super(...)` (constructor
+    // chain). This also correctly rejects identifiers that merely
+    // contain the substring `super` (e.g. `superman`).
+    isSuperReceiver: (text) => /^super(\s*\(|\s*\.|\s*\[|\s*$)/.test(text.trim()),
+    // TypeScript is statically typed — field-fallback heuristic off
+    // (the type-binding layer produces precise owner types). Return-
+    // type propagation across imports on (matches the legacy DAG's
+    // behavior: explicit return-type annotations flow across `export`
+    // boundaries and resolve chained member calls).
+    fieldFallbackOnMethodLookup: false,
+    propagatesReturnTypesAcrossImports: true,
+    // TypeScript uses `.values()` / `.keys()` method-call syntax for collection
+    // views -- no property-style accessors like C#'s `Dictionary<K,V>.Values` --
+    // so `elementTypeOf` answers only the `index` route and lets the regular
+    // member-call branch handle the rest.
+    //
+    // `collapseMemberCallsByCallerTarget` left undefined (= false) --
+    // TypeScript legacy DAG emits one edge per call site, so
+    // per-site dedup is the parity target.
+    //
+    // `populateNamespaceSiblings` left undefined -- TypeScript requires
+    // an explicit `import` / namespace augmentation for cross-file
+    // visibility; there's no implicit same-namespace sibling rule
+    // like C#'s.
+    //
+    // `hoistTypeBindingsToModule` -- `tsBindingScopeFor` DOES hoist
+    // method return-type bindings to the enclosing Module scope
+    // (mirrors C#), so enable the walk-up that lets the compound-
+    // receiver resolver find them.
+    hoistTypeBindingsToModule: true,
+    /**
+     * Emit CALLS edges for Nuxt/Nitro auto-imported symbols that are used
+     * without an explicit import statement.
+     *
+     * Nuxt makes composables and server utils available project-wide via its
+     * auto-import system. Because no `import` statement exists, the standard
+     * scope-resolution passes cannot create call-graph edges for these symbols.
+     * This hook recovers those edges after all normal resolution has run.
+     *
+     * For each TypeScript file the hook:
+     *   1. Builds the set of files already explicitly imported (to avoid
+     *      creating duplicate edges for symbols imported conventionally).
+     *   2. Iterates parsed free-call reference sites and checks each against the
+     *      auto-import map selected for the caller's Nuxt/Nitro scope.
+     *   3. For each hit that is not shadowed by a local binding or explicit
+     *      import, emits a CALLS edge from the file's File node to the target
+     *      function node, and an IMPORTS edge from the caller file to the source
+     *      file (once per pair).
+     *
+     * Confidence is 0.75 (below the 0.9 used for fully resolved edges) to
+     * signal that these edges are heuristic rather than type-checked.
+     */
+    emitPostResolutionEdges(graph, parsedFiles, nodeLookup, indexes, ctx) {
+        const cfg = ctx.resolutionConfig;
+        const autoImports = cfg?.nuxtAutoImports;
+        if (!autoImports || !(0, nuxt_auto_imports_js_1.hasNuxtAutoImports)(autoImports))
+            return;
+        // Pre-build a file -> explicit imported local names index so importing one
+        // symbol from a source does not suppress other auto-imported symbols from it.
+        const explicitImportNamesByFile = new Map();
+        for (const [scopeId, edges] of indexes.imports) {
+            const scope = indexes.scopeTree.getScope(scopeId);
+            if (!scope?.filePath)
+                continue;
+            let names = explicitImportNamesByFile.get(scope.filePath);
+            if (!names) {
+                names = new Set();
+                explicitImportNamesByFile.set(scope.filePath, names);
+            }
+            for (const edge of edges) {
+                // Record the local name whether or not the import resolved to a file.
+                // An explicit import of a name — even from an unresolved external
+                // package (`import { useAuto } from '@vueuse/core'`) — is authoritative
+                // shadowing intent and must suppress the auto-import for that name.
+                if (edge.localName)
+                    names.add(edge.localName);
+            }
+        }
+        for (const parsedFile of parsedFiles) {
+            const { filePath } = parsedFile;
+            if (!filePath.endsWith('.ts') && !filePath.endsWith('.tsx'))
+                continue;
+            const fileId = (0, utils_js_1.generateId)('File', filePath);
+            const explicitImports = explicitImportNamesByFile.get(filePath) ?? new Set();
+            // Track (sourceFile) pairs already handled for this caller to avoid
+            // emitting duplicate IMPORTS edges and duplicate CALLS edges per symbol.
+            const emittedImports = new Set();
+            const emittedCalls = new Set();
+            for (const site of parsedFile.referenceSites) {
+                if (site.kind !== 'call' || site.callForm !== 'free')
+                    continue;
+                const localName = site.name;
+                const entry = (0, nuxt_auto_imports_js_1.getNuxtAutoImportEntry)(autoImports, localName, filePath);
+                if (!entry)
+                    continue;
+                const { exportName, sourceFile } = entry;
+                // Skip when the file already binds this name explicitly, when the file
+                // IS the source, or when a lexical same-file binding shadows it.
+                if (explicitImports.has(localName) ||
+                    sourceFile === filePath ||
+                    hasLocalBindingInScopeChain(site.inScope, localName, filePath, indexes)) {
+                    continue;
+                }
+                // Emit one IMPORTS edge per (caller, sourceFile) pair.
+                if (!emittedImports.has(sourceFile)) {
+                    emittedImports.add(sourceFile);
+                    const targetFileId = (0, utils_js_1.generateId)('File', sourceFile);
+                    if (graph.getNode(targetFileId)) {
+                        graph.addRelationship({
+                            id: (0, utils_js_1.generateId)('IMPORTS', `${fileId}->nuxt-auto-import->${targetFileId}`),
+                            sourceId: fileId,
+                            targetId: targetFileId,
+                            type: 'IMPORTS',
+                            confidence: 0.75,
+                            reason: 'nuxt-auto-import-file',
+                        });
+                    }
+                }
+                // Emit one CALLS edge per (caller, symbol) pair.
+                const callKey = `${sourceFile}::${localName}`;
+                if (emittedCalls.has(callKey))
+                    continue;
+                emittedCalls.add(callKey);
+                // Look up the graph node by export name first, fall back to local name.
+                // The fallback handles `default as X` where the function is named X.
+                const targetNodeId = nodeLookup.get((0, node_lookup_js_1.simpleKey)(sourceFile, exportName)) ??
+                    (exportName !== localName ? nodeLookup.get((0, node_lookup_js_1.simpleKey)(sourceFile, localName)) : undefined);
+                if (!targetNodeId || !graph.getNode(targetNodeId))
+                    continue;
+                graph.addRelationship({
+                    id: (0, utils_js_1.generateId)('CALLS', `${fileId}:nuxt-auto-import:${localName}->${targetNodeId}`),
+                    sourceId: fileId,
+                    targetId: targetNodeId,
+                    type: 'CALLS',
+                    confidence: 0.75,
+                    reason: 'nuxt-auto-import',
+                });
+            }
+        }
+    },
+};
+exports.typescriptScopeResolver = typescriptScopeResolver;
+function occupiesTypeScriptValueSpace(type) {
+    return !TYPESCRIPT_TYPE_ONLY_BINDING_TYPES.has(type);
+}
+function hasLocalBindingInScopeChain(scopeId, name, filePath, indexes) {
+    const visited = new Set();
+    let cursor = scopeId;
+    while (cursor !== null && cursor !== undefined && !visited.has(cursor)) {
+        visited.add(cursor);
+        const scope = indexes.scopeTree.getScope(cursor);
+        if (!scope)
+            return false;
+        const localBindings = scope.bindings.get(name);
+        if (localBindings?.some((binding) => binding.origin === 'local' &&
+            binding.def.filePath === filePath &&
+            occupiesTypeScriptValueSpace(binding.def.type))) {
+            return true;
+        }
+        // Type-annotated function parameters — and other value-space type facts
+        // such as `self` and variable annotations — live in `scope.typeBindings`,
+        // not `scope.bindings`. A parameter named like a composable genuinely
+        // shadows the auto-import, and typeBindings never holds a pure type that
+        // belongs to callable space, so a same-file presence check here cannot
+        // over-suppress a legitimate auto-import.
+        //
+        // Residual (known limitation): this catches parameters whose annotation the
+        // TS scope query records as a type-binding (`p: Named`, generics, unions,
+        // predefined, arrays). Function-typed params (`p: () => void`), untyped
+        // params, destructured locals (`const { x } = …`), and catch-clause vars
+        // are captured by NEITHER map — the scope query emits no `@declaration` /
+        // `@type-binding` for them — so those shadow forms still leak an edge.
+        // Closing that needs shared TS scope-query/extractor changes that alter call
+        // resolution beyond Nuxt, so it is deferred to a follow-up rather than fixed
+        // here.
+        if (scope.filePath === filePath && scope.typeBindings.has(name)) {
+            return true;
+        }
+        cursor = scope.parent;
+    }
+    return false;
+}

package/dist/core/code/engine/core/ingestion/languages/typescript/simple-hooks.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Trivial / no-op-ish hooks for the TypeScript provider. Kept together
+ * because each is a few lines and they share a common theme: making
+ * the provider's choice explicit rather than relying on "absence ==
+ * default" so reviewers don't have to re-derive the analysis.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tsBindingScopeFor = tsBindingScopeFor;
+exports.tsImportOwningScope = tsImportOwningScope;
+exports.tsReceiverBinding = tsReceiverBinding;
+const scope_tree_walk_js_1 = require("../../utils/scope-tree-walk.js");
+// ─── bindingScopeFor ──────────────────────────────────────────────────────
+/**
+ * TypeScript/JavaScript has block-scoped `let`/`const` (the innermost
+ * default covers these) but function-scoped `var` — which hoists to
+ * the enclosing **function or module** scope, bypassing intermediate
+ * blocks. JS also function-hoists `function_declaration` to the same
+ * level.
+ *
+ * We distinguish var from let/const by sniffing the `@declaration.variable`
+ * capture's leading keyword. The capture's text begins with the
+ * source-literal keyword (`var ` / `let ` / `const `) because the
+ * anchor is the outer `lexical_declaration` / `variable_declaration`
+ * node — there's no whitespace before the keyword in any well-formed
+ * TS/JS source.
+ *
+ * Additionally hoists **method return-type bindings**
+ * (`@type-binding.return`) all the way to the Module scope, matching
+ * C#: the compound-receiver walker and `propagateImportedReturnTypes`
+ * both read from module-level typeBindings for cross-file chain
+ * propagation.
+ */
+function tsBindingScopeFor(decl, innermost, tree) {
+    // Method return type: hoist to Module (mirrors csharpBindingScopeFor).
+    if (decl['@type-binding.return'] !== undefined) {
+        return (0, scope_tree_walk_js_1.walkToScope)(innermost, tree, 'Module');
+    }
+    // Parameter property (`constructor(public address: Address)`): hoist
+    // to the enclosing Class scope so `user.address` field access
+    // resolves through the class's typeBindings. The regular
+    // @type-binding.parameter binding still fires for the constructor
+    // scope; this one adds a second binding on the class.
+    if (decl['@type-binding.parameter-property'] !== undefined) {
+        return (0, scope_tree_walk_js_1.walkToScope)(innermost, tree, 'Class');
+    }
+    // `this.p = new Outer()` binds the FIELD, not a method-local, so the binding
+    // belongs on the class the way an annotated field's does — that is the only
+    // place `typeOfMemberOnClass` reads. Left on the innermost scope it would sit
+    // on the method's own Function scope and never be found (#2807). Same shape
+    // as the parameter-property branch above.
+    //
+    // Gated on the marker the `this.<field> = new …` pattern emits, never on
+    // `@type-binding.constructor` at large: that capture also fires for
+    // `const o = new Outer()` inside a method, and hoisting THOSE to the class
+    // would take method locals out of their own scope and mistype them.
+    //
+    // This walk is UNCONDITIONAL by design, and stays correct only because the
+    // marker's producers are bounded: the query nests the pattern under
+    // `class_body → method_definition → statement_block`, and `emitTsScopeCaptures`
+    // drops the static-method case. So `this` here provably IS an instance of the
+    // class this lands on, and a Class ancestor always exists — no `walkToScope`
+    // null-fallback onto some unrelated innermost scope. Anything that widens the
+    // marker's producers has to re-establish both, or restore the guard here.
+    if (decl['@type-binding.this-field'] !== undefined) {
+        return (0, scope_tree_walk_js_1.walkToScope)(innermost, tree, 'Class');
+    }
+    // `var` declarations: hoist to nearest enclosing Function or Module.
+    const variable = decl['@declaration.variable'];
+    if (variable !== undefined && isVarDeclaration(variable.text)) {
+        return (0, scope_tree_walk_js_1.walkToScope)(innermost, tree, 'Function', 'Module');
+    }
+    // Function declarations are already anchored at their definition
+    // site via `@scope.function`; hoisting is a no-op for them (JS
+    // function hoisting is about visibility before the definition, not
+    // about placing the binding in a different scope). The scope tree
+    // already attaches their name to the enclosing scope. No override
+    // needed.
+    return null;
+}
+/** `var x = 1;` vs `let x = 1;` / `const x = 1;`. The capture's text
+ *  starts at the outer declaration's `startIndex` in source, which is
+ *  the keyword's first character — no leading whitespace possible. */
+function isVarDeclaration(captureText) {
+    return (captureText.startsWith('var ') ||
+        captureText.startsWith('var\t') ||
+        captureText.startsWith('var\n'));
+}
+// ─── importOwningScope ────────────────────────────────────────────────────
+/**
+ * TypeScript imports are syntactically top-level: `import_statement` is
+ * legal only inside `program` (the module root). `namespace X { … }`
+ * bodies CAN contain imports (`internal_module`), in which case the
+ * import scopes to the namespace. Dynamic `import()` calls appear
+ * inside any scope but their runtime effect is still a module-level
+ * resolution — we attach the `ParsedImport` to the innermost Module /
+ * Namespace scope so the binding is visible through the full subtree.
+ *
+ * Returning `null` delegates to the central default, which walks to
+ * the nearest enclosing `Module`/`Namespace`. That matches our rule,
+ * so we only override when we explicitly need a non-default scope
+ * (we don't).
+ */
+function tsImportOwningScope(_imp, _innermost, _tree) {
+    return null;
+}
+// ─── receiverBinding ──────────────────────────────────────────────────────
+/**
+ * Look up `this` on the function scope's type bindings.
+ *
+ * `this` is synthesized as a type binding on instance-method function
+ * scopes during capture emission (`receiver-binding.ts`). Arrow
+ * functions and nested functions that reference `this` naturally
+ * resolve it via the scope-chain walk — if the arrow function is a
+ * class method (`m = () => {}`), it gets a synthesized `this`; if it
+ * is nested inside a class method, the scope-chain lookup finds the
+ * outer method's `this`. This mirrors TypeScript's lexical-this
+ * semantics for arrow functions.
+ *
+ * Returns `null` for:
+ *   - static methods (no `this` synthesized)
+ *   - free functions / module-level code (no enclosing class-like)
+ *   - non-Function scopes
+ *
+ * Caveat: a non-arrow `function` declaration nested inside a method
+ * DOES see the outer `this` via our scope-chain lookup, even though at
+ * runtime its `this` is independently bound (strict-mode `undefined`,
+ * sloppy `globalThis`). We accept this false-positive — the real-world
+ * pattern that relies on independent `this` inside a nested regular
+ * function inside a class method is extremely rare, and catching it
+ * would require injecting a `this: undefined` shadow on every non-
+ * arrow function scope. Documented as a known limitation in
+ * `index.ts`.
+ */
+function tsReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    return functionScope.typeBindings.get('this') ?? null;
+}