gitnexus 1.6.3 → 1.6.4-rc.10

package/dist/core/ingestion/languages/typescript/import-decomposer.js

@@ -0,0 +1,371 @@
+/**
+ * Decompose a TypeScript `import_statement` / re-export `export_statement` /
+ * dynamic `call_expression(import)` into one `CaptureMatch` per imported
+ * name.
+ *
+ * Why split here? The `LanguageProvider.interpretImport` contract is
+ * one `ParsedImport` per call. Tree-sitter delivers
+ *
+ *   import D, { X as Y, type Z } from './m'
+ *
+ * as a single `import_statement` match, so without decomposition we'd
+ * lose names. The synthesized markers (`@import.kind` / `@import.name`
+ * / `@import.alias` / `@import.source`) carry everything
+ * `interpretTsImport` needs to recover the `ParsedImport` shape —
+ * see `interpret.ts`.
+ *
+ * Kinds we emit and how `interpret.ts` maps them to `ParsedImport`:
+ *
+ *   - `default`            : `import D from './m'`          → alias (importedName=default)
+ *   - `named`              : `import { X } from './m'`      → named
+ *   - `named-alias`        : `import { X as Y } from './m'` → alias
+ *   - `namespace`          : `import * as N from './m'`     → namespace
+ *   - `reexport`           : `export { X } from './m'`      → reexport
+ *   - `reexport-alias`     : `export { X as Y } from './m'` → reexport (with alias)
+ *   - `reexport-wildcard`  : `export * from './m'`          → wildcard
+ *   - `reexport-namespace` : `export * as ns from './m'`    → namespace (local=ns,imported=source)
+ *   - `dynamic`            : `import('./m')` / `import(x)`  → dynamic-resolved or dynamic-unresolved
+ *
+ * Type-only constructs (`import type { X }`, `import { type X }`,
+ * `export type { X }`) emit the same kinds as runtime forms — at the
+ * TypeScript scope-resolution layer, types and values share the same
+ * lookup; runtime-emission is a downstream concern.
+ *
+ * Side-effect imports (`import './polyfill'`) produce a single match
+ * with `kind: 'side-effect'`. The shared finalize algorithm resolves
+ * the target file and emits a file-level IMPORTS edge, but
+ * materializes no `BindingRef` (matching the legacy DAG, which counts
+ * `import './polyfill'` as a module-reachability dependency only).
+ */
+import { findChild, nodeToCapture, syntheticCapture, } from '../../utils/ast-helpers.js';
+/**
+ * Decompose an import anchor. Handles three node types:
+ *
+ *   - `import_statement`             : all static import forms (incl. side-effect)
+ *   - `export_statement` (w/ source) : re-exports
+ *   - `call_expression` (import fn)  : dynamic `import()`
+ */
+export function splitImportStatement(stmtNode) {
+    if (stmtNode.type === 'import_statement')
+        return splitImport(stmtNode);
+    if (stmtNode.type === 'export_statement')
+        return splitReexport(stmtNode);
+    if (stmtNode.type === 'call_expression')
+        return splitDynamicImport(stmtNode);
+    return [];
+}
+// ─── static imports ─────────────────────────────────────────────────────
+function splitImport(stmtNode) {
+    // `import_statement` shape:
+    //   import_clause? "from" string          (static form with bindings)
+    //   string                                (side-effect `import './m'`)
+    //
+    // The `source` field is the string literal — we strip its surrounding
+    // quotes. An import without an `import_clause` child is side-effect
+    // only and still emits one non-binding match.
+    const source = extractSource(stmtNode);
+    if (source === null)
+        return [];
+    const importClause = findChild(stmtNode, 'import_clause');
+    if (importClause === null) {
+        // `import './polyfill'` — no clause, no local binding. Emit a
+        // side-effect match so the finalize layer still produces a
+        // file-level IMPORTS edge (parity with the legacy DAG).
+        return [
+            buildImportMatch(stmtNode, {
+                kind: 'side-effect',
+                source,
+                name: '',
+                atNode: stmtNode,
+            }),
+        ];
+    }
+    const out = [];
+    // An import_clause can have any combination of:
+    //   - leading identifier  (default import)
+    //   - namespace_import    (* as N)
+    //   - named_imports       ({ X, Y as Z })
+    for (let i = 0; i < importClause.namedChildCount; i++) {
+        const child = importClause.namedChild(i);
+        if (child === null)
+            continue;
+        if (child.type === 'identifier') {
+            // Default import: `import D from './m'`.
+            out.push(buildImportMatch(stmtNode, {
+                kind: 'default',
+                source,
+                name: 'default',
+                alias: child.text,
+                atNode: child,
+            }));
+            continue;
+        }
+        if (child.type === 'namespace_import') {
+            // `* as N` — the identifier child is the local binding.
+            const aliasId = findChild(child, 'identifier');
+            if (aliasId !== null) {
+                out.push(buildImportMatch(stmtNode, {
+                    kind: 'namespace',
+                    source,
+                    name: source,
+                    alias: aliasId.text,
+                    atNode: child,
+                }));
+            }
+            continue;
+        }
+        if (child.type === 'named_imports') {
+            for (let j = 0; j < child.namedChildCount; j++) {
+                const spec = child.namedChild(j);
+                if (spec === null || spec.type !== 'import_specifier')
+                    continue;
+                const decomposed = decomposeNamedSpecifier(spec, source, stmtNode);
+                if (decomposed !== null)
+                    out.push(decomposed);
+            }
+            continue;
+        }
+        // Other children (e.g. `type` keyword token for `import type { ... }`)
+        // are ignored — they carry no per-specifier info; we fold type-only
+        // semantics into the same emitted kinds.
+    }
+    return out;
+}
+/**
+ * Decompose a single `import_specifier` into one match. Handles:
+ *
+ *   - `{ X }`            → named
+ *   - `{ X as Y }`       → named-alias
+ *   - `{ type X }`       → named (type-only; same shape)
+ *   - `{ type X as Y }`  → named-alias (type-only)
+ */
+function decomposeNamedSpecifier(spec, source, stmtNode) {
+    // `import_specifier` layout:
+    //   name: identifier
+    //   alias: identifier?            (only when `as` is present)
+    //   plus an optional `type` keyword token in front (per-specifier type-only)
+    //
+    // tree-sitter-typescript exposes `name` and `alias` as named fields.
+    // If `name` is absent, fail closed rather than guessing positionally:
+    // binding the alias as the imported name would invert the edge.
+    const nameNode = spec.childForFieldName('name');
+    const aliasNode = spec.childForFieldName('alias');
+    if (nameNode === null)
+        return null;
+    const name = nameNode.text;
+    if (aliasNode !== null && aliasNode.startIndex !== nameNode.startIndex) {
+        return buildImportMatch(stmtNode, {
+            kind: 'named-alias',
+            source,
+            name,
+            alias: aliasNode.text,
+            atNode: spec,
+        });
+    }
+    return buildImportMatch(stmtNode, {
+        kind: 'named',
+        source,
+        name,
+        atNode: spec,
+    });
+}
+// ─── re-exports ──────────────────────────────────────────────────────────
+function splitReexport(stmtNode) {
+    // `export_statement` with a `source:` field is a re-export. Forms:
+    //
+    //   export { X, Y as Z } from './m'          → export_clause children
+    //   export * from './m'                      → no clause
+    //   export * as ns from './m'                → namespace_export child
+    //   export type { X } from './m'             → same clause path
+    //
+    // Local `export { X }` (no `from`) is visibility metadata, not an
+    // import; the captures-layer query guards with a `source: (string)`
+    // predicate so we always have a source here — but we defend
+    // structurally anyway.
+    const source = extractSource(stmtNode);
+    if (source === null)
+        return [];
+    const exportClause = findChild(stmtNode, 'export_clause');
+    if (exportClause !== null) {
+        const out = [];
+        for (let i = 0; i < exportClause.namedChildCount; i++) {
+            const spec = exportClause.namedChild(i);
+            if (spec === null || spec.type !== 'export_specifier')
+                continue;
+            const decomposed = decomposeReexportSpecifier(spec, source, stmtNode);
+            if (decomposed !== null)
+                out.push(decomposed);
+        }
+        return out;
+    }
+    // `export * as ns from './m'` — tree-sitter-typescript emits a
+    // `namespace_export` child whose identifier is the local re-export
+    // name. Two facts are emitted:
+    //
+    //   1. An `@import.statement` (kind `reexport-namespace`) so finalize
+    //      knows the barrel imports `./m` as `ns` (binds `ns` locally
+    //      inside the barrel for consumers like `barrel.ts` calling
+    //      `ns.X()`).
+    //   2. A synthetic `@declaration.namespace` so the central
+    //      scope-extractor adds a `Namespace` SymbolDefinition for `ns`
+    //      to the barrel's `localDefs`. Without this, downstream files
+    //      doing `import { ns } from './barrel'` cannot resolve `ns`:
+    //      `findExportByName` and the precomputed re-export closure only
+    //      consult `localDefs` / `reexport` / `wildcard` drafts, never
+    //      `namespace`-kind imports. The synthetic declaration fixes that
+    //      without growing the shared finalizer's surface.
+    const namespaceExport = findChild(stmtNode, 'namespace_export');
+    if (namespaceExport !== null) {
+        const aliasId = findChild(namespaceExport, 'identifier');
+        if (aliasId !== null) {
+            return [
+                buildImportMatch(stmtNode, {
+                    kind: 'reexport-namespace',
+                    source,
+                    name: source,
+                    alias: aliasId.text,
+                    atNode: namespaceExport,
+                }),
+                buildNamespaceDeclarationMatch(namespaceExport, aliasId),
+            ];
+        }
+    }
+    // `export * from './m'` — no clause, no namespace_export. The bare
+    // `*` token is the only remaining marker; we don't need to inspect
+    // it since the shape alone says "wildcard".
+    return [
+        buildImportMatch(stmtNode, {
+            kind: 'reexport-wildcard',
+            source,
+            name: '*',
+            atNode: stmtNode,
+        }),
+    ];
+}
+function decomposeReexportSpecifier(spec, source, stmtNode) {
+    const nameNode = spec.childForFieldName('name');
+    const aliasNode = spec.childForFieldName('alias');
+    if (nameNode === null)
+        return null;
+    const name = nameNode.text;
+    if (aliasNode !== null && aliasNode.startIndex !== nameNode.startIndex) {
+        return buildImportMatch(stmtNode, {
+            kind: 'reexport-alias',
+            source,
+            name,
+            alias: aliasNode.text,
+            atNode: spec,
+        });
+    }
+    return buildImportMatch(stmtNode, {
+        kind: 'reexport',
+        source,
+        name,
+        atNode: spec,
+    });
+}
+// ─── dynamic imports ─────────────────────────────────────────────────────
+function splitDynamicImport(callNode) {
+    // `call_expression` shape for dynamic imports:
+    //   function: (import)                   — named leaf node in tree-sitter-typescript
+    //   arguments: (arguments (string) ...)  — first arg is the path
+    //
+    // When the argument is a string literal, preserve its value. When it's
+    // anything else (variable, template literal, member access), surface
+    // the raw text for diagnostics and let `interpretTsImport` emit
+    // `dynamic-unresolved` with a `targetRaw` hint.
+    const args = callNode.childForFieldName('arguments');
+    if (args === null) {
+        return [
+            buildImportMatch(callNode, {
+                kind: 'dynamic',
+                source: null,
+                name: '',
+                atNode: callNode,
+            }),
+        ];
+    }
+    const firstArg = args.namedChild(0);
+    if (firstArg === null) {
+        return [
+            buildImportMatch(callNode, {
+                kind: 'dynamic',
+                source: null,
+                name: '',
+                atNode: callNode,
+            }),
+        ];
+    }
+    if (firstArg.type === 'string') {
+        const source = stripQuotes(firstArg.text);
+        return [
+            buildImportMatch(callNode, {
+                kind: 'dynamic',
+                source,
+                name: '',
+                atNode: callNode,
+                literalSource: true,
+            }),
+        ];
+    }
+    // Non-literal argument — preserve source text so downstream
+    // diagnostics show what the user wrote.
+    return [
+        buildImportMatch(callNode, {
+            kind: 'dynamic',
+            source: firstArg.text,
+            name: '',
+            atNode: callNode,
+        }),
+    ];
+}
+// ─── helpers ─────────────────────────────────────────────────────────────
+function extractSource(stmtNode) {
+    // Both `import_statement` and `export_statement` expose the module
+    // path through the `source:` field. It's typed as `string` in the
+    // grammar; we strip its surrounding quotes.
+    const sourceField = stmtNode.childForFieldName('source');
+    if (sourceField === null || sourceField.type !== 'string')
+        return null;
+    return stripQuotes(sourceField.text);
+}
+function stripQuotes(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length < 2)
+        return trimmed;
+    const first = trimmed.charAt(0);
+    const last = trimmed.charAt(trimmed.length - 1);
+    if ((first === '"' && last === '"') ||
+        (first === "'" && last === "'") ||
+        (first === '`' && last === '`')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function buildImportMatch(stmtNode, spec) {
+    const m = {
+        '@import.statement': nodeToCapture('@import.statement', stmtNode),
+        '@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
+        '@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
+    };
+    if (spec.source !== null) {
+        m['@import.source'] = syntheticCapture('@import.source', spec.atNode, spec.source);
+    }
+    if (spec.alias !== undefined) {
+        m['@import.alias'] = syntheticCapture('@import.alias', spec.atNode, spec.alias);
+    }
+    if (spec.literalSource === true) {
+        m['@import.literal'] = syntheticCapture('@import.literal', spec.atNode, '');
+    }
+    return m;
+}
+/** Synthesize a `@declaration.namespace` match for `export * as ns from './m'`.
+ *  The central scope-extractor turns this into a `SymbolDefinition` of type
+ *  `Namespace` in the barrel's `localDefs`, which makes `findExportByName`
+ *  resolve `ns` for downstream `import { ns } from './barrel'` consumers. */
+function buildNamespaceDeclarationMatch(namespaceExportNode, aliasId) {
+    return {
+        '@declaration.namespace': nodeToCapture('@declaration.namespace', namespaceExportNode),
+        '@declaration.name': nodeToCapture('@declaration.name', aliasId),
+    };
+}

package/dist/core/ingestion/languages/typescript/import-target.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing standard-strategy resolver
+ * (`resolveImportPath`) so tsconfig path aliases (`@/`, `~/`, …) and
+ * suffix-based resolution follow the same rules as the legacy path.
+ *
+ * The `WorkspaceIndex` is opaque at the shared contract layer; we
+ * narrow it to a TypeScript-shaped context that carries `fromFile` +
+ * the full `allFilePaths` set + the optional `tsconfigPaths` the
+ * resolver reads.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import type { ParsedImport, WorkspaceIndex } from '../../../../_shared/index.js';
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import type { TsconfigPaths } from '../../language-config.js';
+export interface TsResolveContext {
+    readonly fromFile: string;
+    /** Mutable `Set` because the standard resolver consumes `Set<string>`.
+     *  Callers holding a `ReadonlySet` should copy via `new Set(...)`. */
+    readonly allFilePaths: Set<string>;
+    /** Repo file list, normalized (lowercased) for suffix matching. May
+     *  be supplied by the orchestrator; if absent we derive it on the
+     *  fly from `allFilePaths`. */
+    readonly allFileList?: readonly string[];
+    readonly normalizedFileList?: readonly string[];
+    /** Per-call resolution cache to dedupe repeated lookups. */
+    readonly resolveCache?: Map<string, string | null>;
+    /** Parsed tsconfig path-aliases. `null` = no aliases configured. */
+    readonly tsconfigPaths?: TsconfigPaths | null;
+    /** JavaScript vs TypeScript switch — affects the extensions the
+     *  resolver tries. Defaults to TypeScript. */
+    readonly language?: SupportedLanguages.TypeScript | SupportedLanguages.JavaScript;
+}
+export declare function resolveTsImportTarget(parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex): string | null;
+/**
+ * Resolve a raw module-path string to a workspace file path using the
+ * same standard-strategy resolver as the legacy DAG. Operates directly on
+ * the source string without requiring a `ParsedImport`, so the
+ * `ScopeResolver.resolveImportTarget` adapter doesn't need to construct
+ * a fake `ParsedImport` to reach the resolver.
+ *
+ * Returns `null` when:
+ *   - the context is malformed (missing `fromFile` / `allFilePaths`)
+ *   - `targetRaw` is empty
+ *   - the resolver finds no matching file
+ */
+export declare function resolveTsTarget(targetRaw: string, ctx: TsResolveContext): string | null;

package/dist/core/ingestion/languages/typescript/import-target.js

@@ -0,0 +1,61 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing standard-strategy resolver
+ * (`resolveImportPath`) so tsconfig path aliases (`@/`, `~/`, …) and
+ * suffix-based resolution follow the same rules as the legacy path.
+ *
+ * The `WorkspaceIndex` is opaque at the shared contract layer; we
+ * narrow it to a TypeScript-shaped context that carries `fromFile` +
+ * the full `allFilePaths` set + the optional `tsconfigPaths` the
+ * resolver reads.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { resolveImportPath } from '../../import-resolvers/standard.js';
+export function resolveTsImportTarget(parsedImport, workspaceIndex) {
+    const ctx = narrowTsContext(workspaceIndex);
+    if (ctx === null)
+        return null;
+    // Dynamic imports carry `targetRaw` only for diagnostics; when the
+    // expression isn't a string literal we can't resolve a file.
+    // A string-literal dynamic import (`import('./m')`) resolves like a
+    // static import — fall through to the shared path resolver.
+    if (parsedImport.kind === 'dynamic-unresolved' && parsedImport.targetRaw === null)
+        return null;
+    if (parsedImport.targetRaw === null || parsedImport.targetRaw === '')
+        return null;
+    return resolveTsTarget(parsedImport.targetRaw, ctx);
+}
+/**
+ * Resolve a raw module-path string to a workspace file path using the
+ * same standard-strategy resolver as the legacy DAG. Operates directly on
+ * the source string without requiring a `ParsedImport`, so the
+ * `ScopeResolver.resolveImportTarget` adapter doesn't need to construct
+ * a fake `ParsedImport` to reach the resolver.
+ *
+ * Returns `null` when:
+ *   - the context is malformed (missing `fromFile` / `allFilePaths`)
+ *   - `targetRaw` is empty
+ *   - the resolver finds no matching file
+ */
+export function resolveTsTarget(targetRaw, ctx) {
+    if (targetRaw === '')
+        return null;
+    const language = ctx.language ?? SupportedLanguages.TypeScript;
+    const allFileList = ctx.allFileList ?? Array.from(ctx.allFilePaths);
+    const normalizedFileList = ctx.normalizedFileList ?? allFileList.map((f) => f.toLowerCase());
+    const resolveCache = ctx.resolveCache ?? new Map();
+    return resolveImportPath(ctx.fromFile, targetRaw, ctx.allFilePaths, allFileList, normalizedFileList, resolveCache, language, ctx.tsconfigPaths ?? null);
+}
+function narrowTsContext(workspaceIndex) {
+    const ctx = workspaceIndex;
+    if (ctx === undefined ||
+        typeof ctx.fromFile !== 'string' ||
+        !(ctx.allFilePaths instanceof Set)) {
+        return null;
+    }
+    return ctx;
+}

package/dist/core/ingestion/languages/typescript/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * TypeScript scope-resolution hooks (RFC #909 Ring 3, RFC §5).
+ *
+ * Public API barrel. Consumers should import from this file rather
+ * than the individual modules.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`             — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`          — `emitTsScopeCaptures` orchestrator
+ *   - `import-decomposer.ts` — each import/re-export/dynamic-import →
+ *                              ParsedImport-shaped captures
+ *   - `interpret.ts`         — capture-match → `ParsedImport` /
+ *                              `ParsedTypeBinding`
+ *   - `simple-hooks.ts`      — `bindingScopeFor` (var hoisting + return-
+ *                              type hoisting), `importOwningScope`
+ *                              (module/namespace default), `receiverBinding`
+ *                              (`this` lookup on Function scope)
+ *   - `receiver-binding.ts`  — synthesize `this` type-bindings on
+ *                              instance-method entry (methods, interface
+ *                              signatures, class-field arrow functions)
+ *   - `merge-bindings.ts`    — TypeScript declaration merging
+ *                              (value / type / namespace spaces) + LEGB
+ *                              tier shadowing
+ *   - `arity.ts`             — TypeScript arity compatibility (rest,
+ *                              optional, default params)
+ *   - `arity-metadata.ts`    — synthesize arity metadata from
+ *                              declarations; includes generics + array-
+ *                              suffix stripping on parameter types
+ *   - `import-target.ts`     — `(ParsedImport, WorkspaceIndex) → file path`
+ *                              adapter delegating to the shared standard
+ *                              resolver (tsconfig paths, node_modules,
+ *                              relative/extension suffix matching)
+ *   - `cache-stats.ts`       — PROF_SCOPE_RESOLUTION cache hit/miss
+ *                              counters
+ *
+ * ## Known limitations
+ *
+ * The TypeScript registry-primary path intentionally does NOT resolve
+ * the following. Each is a conscious trade-off at migration time.
+ *
+ *   1. **Type-only import / export separation** — `import type { X }`
+ *      and `import { X }` produce the same `ParsedImport` shape today;
+ *      `def.type` on the resolved symbol is the only discriminator.
+ *      Parity with the legacy path is preserved. Tracking in #927.
+ *   2. **Declaration merging for imports** — when `import { Foo }`
+ *      brings in a symbol that is BOTH a class and a namespace in the
+ *      source module, we currently surface a single binding per the
+ *      target `def.type`. Downstream type/value-space lookups still
+ *      work for the primary space; the other space's members resolve
+ *      via the same target (class statics reachable via dotted access).
+ *   3. **Overload narrowing by argument type** — `@reference.parameter-
+ *      types` carries static literal types inferred from the callsite
+ *      (`string`, `number`, `Array`, etc.). Identifier / member-access
+ *      arguments emit empty strings (unknown type); the registry's
+ *      narrowing treats them as any-match. Full control-flow type
+ *      narrowing is out of scope.
+ *   4. **Computed member access** — `obj[key]()` / `obj['method']()`
+ *      is classified as an index-access call; member-call resolution
+ *      falls back to the identifier-indexed branch and matches only
+ *      when the key is a string literal.
+ *   5. **`this` for nested regular functions inside methods** — our
+ *      scope-chain lookup returns the enclosing method's `this`, which
+ *      is technically incorrect at runtime (a non-arrow nested function
+ *      has its own `this` binding). Accepted false-positive; see
+ *      `simple-hooks.ts` docstring.
+ *   6. **`class_expression` receiver types** — `const C = class { }`
+ *      skips `this` synthesis when the expression is anonymous (no
+ *      type name to propagate). `const C = class Named { }` works via
+ *      the class's own `name` field.
+ *   7. **JSX element types** — JSX-specific constructs are ignored by
+ *      the scope query; component references resolve via regular
+ *      identifier / member-expression paths.
+ *   8. **Ambient module declarations** (`declare module '…'`) — parsed
+ *      but not indexed at this layer; same as today's legacy path.
+ *   9. **Intersection types on parameters** (`(a: A & B)`) — treated
+ *      as opaque (no strip); overload narrowing on intersections
+ *      won't match.
+ *  10. **`instanceof` member-expression narrowing** — only bare
+ *      identifiers are narrowed (`user instanceof User`). Member paths
+ *      such as `user.address instanceof Address` remain unresolved.
+ *
+ * Shadow-harness corpus parity on `test/integration/resolvers/
+ * typescript.test.ts` is the authoritative signal for which of these
+ * matter in practice. The CI parity gate blocks any PR that regresses
+ * either the legacy or registry-primary run.
+ */
+export { emitTsScopeCaptures } from './captures.js';
+export { getTypescriptCaptureCacheStats, resetTypescriptCaptureCacheStats } from './cache-stats.js';
+export { interpretTsImport, interpretTsTypeBinding } from './interpret.js';
+export { typescriptMergeBindings } from './merge-bindings.js';
+export { typescriptArityCompatibility } from './arity.js';
+export { resolveTsImportTarget, resolveTsTarget, type TsResolveContext } from './import-target.js';
+export { tsBindingScopeFor, tsImportOwningScope, tsReceiverBinding } from './simple-hooks.js';

package/dist/core/ingestion/languages/typescript/index.js

@@ -0,0 +1,94 @@
+/**
+ * TypeScript scope-resolution hooks (RFC #909 Ring 3, RFC §5).
+ *
+ * Public API barrel. Consumers should import from this file rather
+ * than the individual modules.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`             — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`          — `emitTsScopeCaptures` orchestrator
+ *   - `import-decomposer.ts` — each import/re-export/dynamic-import →
+ *                              ParsedImport-shaped captures
+ *   - `interpret.ts`         — capture-match → `ParsedImport` /
+ *                              `ParsedTypeBinding`
+ *   - `simple-hooks.ts`      — `bindingScopeFor` (var hoisting + return-
+ *                              type hoisting), `importOwningScope`
+ *                              (module/namespace default), `receiverBinding`
+ *                              (`this` lookup on Function scope)
+ *   - `receiver-binding.ts`  — synthesize `this` type-bindings on
+ *                              instance-method entry (methods, interface
+ *                              signatures, class-field arrow functions)
+ *   - `merge-bindings.ts`    — TypeScript declaration merging
+ *                              (value / type / namespace spaces) + LEGB
+ *                              tier shadowing
+ *   - `arity.ts`             — TypeScript arity compatibility (rest,
+ *                              optional, default params)
+ *   - `arity-metadata.ts`    — synthesize arity metadata from
+ *                              declarations; includes generics + array-
+ *                              suffix stripping on parameter types
+ *   - `import-target.ts`     — `(ParsedImport, WorkspaceIndex) → file path`
+ *                              adapter delegating to the shared standard
+ *                              resolver (tsconfig paths, node_modules,
+ *                              relative/extension suffix matching)
+ *   - `cache-stats.ts`       — PROF_SCOPE_RESOLUTION cache hit/miss
+ *                              counters
+ *
+ * ## Known limitations
+ *
+ * The TypeScript registry-primary path intentionally does NOT resolve
+ * the following. Each is a conscious trade-off at migration time.
+ *
+ *   1. **Type-only import / export separation** — `import type { X }`
+ *      and `import { X }` produce the same `ParsedImport` shape today;
+ *      `def.type` on the resolved symbol is the only discriminator.
+ *      Parity with the legacy path is preserved. Tracking in #927.
+ *   2. **Declaration merging for imports** — when `import { Foo }`
+ *      brings in a symbol that is BOTH a class and a namespace in the
+ *      source module, we currently surface a single binding per the
+ *      target `def.type`. Downstream type/value-space lookups still
+ *      work for the primary space; the other space's members resolve
+ *      via the same target (class statics reachable via dotted access).
+ *   3. **Overload narrowing by argument type** — `@reference.parameter-
+ *      types` carries static literal types inferred from the callsite
+ *      (`string`, `number`, `Array`, etc.). Identifier / member-access
+ *      arguments emit empty strings (unknown type); the registry's
+ *      narrowing treats them as any-match. Full control-flow type
+ *      narrowing is out of scope.
+ *   4. **Computed member access** — `obj[key]()` / `obj['method']()`
+ *      is classified as an index-access call; member-call resolution
+ *      falls back to the identifier-indexed branch and matches only
+ *      when the key is a string literal.
+ *   5. **`this` for nested regular functions inside methods** — our
+ *      scope-chain lookup returns the enclosing method's `this`, which
+ *      is technically incorrect at runtime (a non-arrow nested function
+ *      has its own `this` binding). Accepted false-positive; see
+ *      `simple-hooks.ts` docstring.
+ *   6. **`class_expression` receiver types** — `const C = class { }`
+ *      skips `this` synthesis when the expression is anonymous (no
+ *      type name to propagate). `const C = class Named { }` works via
+ *      the class's own `name` field.
+ *   7. **JSX element types** — JSX-specific constructs are ignored by
+ *      the scope query; component references resolve via regular
+ *      identifier / member-expression paths.
+ *   8. **Ambient module declarations** (`declare module '…'`) — parsed
+ *      but not indexed at this layer; same as today's legacy path.
+ *   9. **Intersection types on parameters** (`(a: A & B)`) — treated
+ *      as opaque (no strip); overload narrowing on intersections
+ *      won't match.
+ *  10. **`instanceof` member-expression narrowing** — only bare
+ *      identifiers are narrowed (`user instanceof User`). Member paths
+ *      such as `user.address instanceof Address` remain unresolved.
+ *
+ * Shadow-harness corpus parity on `test/integration/resolvers/
+ * typescript.test.ts` is the authoritative signal for which of these
+ * matter in practice. The CI parity gate blocks any PR that regresses
+ * either the legacy or registry-primary run.
+ */
+export { emitTsScopeCaptures } from './captures.js';
+export { getTypescriptCaptureCacheStats, resetTypescriptCaptureCacheStats } from './cache-stats.js';
+export { interpretTsImport, interpretTsTypeBinding } from './interpret.js';
+export { typescriptMergeBindings } from './merge-bindings.js';
+export { typescriptArityCompatibility } from './arity.js';
+export { resolveTsImportTarget, resolveTsTarget } from './import-target.js';
+export { tsBindingScopeFor, tsImportOwningScope, tsReceiverBinding } from './simple-hooks.js';