arceus-s 1.6.4

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';

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

@@ -0,0 +1,35 @@
+/**
+ * Capture-match → semantic-shape interpreters for TypeScript.
+ *
+ * Two pure functions, both consumed by the central scope extractor:
+ *
+ *   - `interpretTsImport`      → `ParsedImport`
+ *   - `interpretTsTypeBinding` → `ParsedTypeBinding`  (wired in Unit 6)
+ *
+ * The import matches arrive pre-decomposed by `emitTsScopeCaptures`
+ * (one imported name per match, with synthesized
+ * `@import.kind/source/name/alias` markers — see `import-decomposer.ts`).
+ * The type-binding matches arrive straight from the raw query captures —
+ * each `@type-binding.*` anchor carries `@type-binding.name` +
+ * `@type-binding.type`.
+ */
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from '../../../../_shared/index.js';
+export declare function interpretTsImport(captures: CaptureMatch): ParsedImport | null;
+/**
+ * Interpret a `@type-binding.*` capture-match into a `ParsedTypeBinding`.
+ *
+ * TypeScript-specific strips:
+ *
+ *   - Trailing `?` on optional parameters: `(u?: User)` → `User`
+ *   - `Promise<User>` / `Array<User>` / `ReadonlyArray<User>` / `Readonly<User>`
+ *     → `User`  (wrappers that are transparent to chain propagation)
+ *   - Single-arg `List<User>` / `Iterable<User>` / `Iterator<User>` —
+ *     mirrors Python/C#'s generic-collection strip for for-of loops
+ *   - Trailing `[]` on array types: `User[]` → `User`
+ *   - Nullable unions: `User | null` / `User | undefined` / `null | User`
+ *     → `User`
+ *   - Dotted qualifiers: `models.User` → `User`  (unless the suffix is
+ *     a known collection accessor we'd want to preserve — none apply
+ *     to TS today, since TS uses `.values()` / `.keys()` call syntax)
+ */
+export declare function interpretTsTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null;

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

@@ -0,0 +1,317 @@
+/**
+ * Capture-match → semantic-shape interpreters for TypeScript.
+ *
+ * Two pure functions, both consumed by the central scope extractor:
+ *
+ *   - `interpretTsImport`      → `ParsedImport`
+ *   - `interpretTsTypeBinding` → `ParsedTypeBinding`  (wired in Unit 6)
+ *
+ * The import matches arrive pre-decomposed by `emitTsScopeCaptures`
+ * (one imported name per match, with synthesized
+ * `@import.kind/source/name/alias` markers — see `import-decomposer.ts`).
+ * The type-binding matches arrive straight from the raw query captures —
+ * each `@type-binding.*` anchor carries `@type-binding.name` +
+ * `@type-binding.type`.
+ */
+// ─── interpretImport ──────────────────────────────────────────────────────
+export function interpretTsImport(captures) {
+    // Markers attached by `splitImportStatement` (import-decomposer.ts):
+    //   @import.kind   : one of the kinds documented there
+    //   @import.name   : imported name from the source module
+    //   @import.alias  : local alias name (for default / aliased / namespace forms)
+    //   @import.source : module path (always present except dynamic-unresolved)
+    const kindCap = captures['@import.kind'];
+    const nameCap = captures['@import.name'];
+    const aliasCap = captures['@import.alias'];
+    const sourceCap = captures['@import.source'];
+    const kind = kindCap?.text;
+    if (kind === undefined)
+        return null;
+    switch (kind) {
+        case 'default': {
+            // `import D from './m'` — semantically "alias for the module's
+            // default export". We map to ParsedImport `alias` with
+            // importedName='default' so the finalize algorithm looks up the
+            // target module's `default` export for cross-file resolution.
+            if (sourceCap === undefined || aliasCap === undefined)
+                return null;
+            return {
+                kind: 'alias',
+                localName: aliasCap.text,
+                importedName: 'default',
+                alias: aliasCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'named': {
+            // `import { X } from './m'` (plus type-only forms).
+            if (sourceCap === undefined || nameCap === undefined)
+                return null;
+            return {
+                kind: 'named',
+                localName: nameCap.text,
+                importedName: nameCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'named-alias': {
+            // `import { X as Y } from './m'`.
+            if (sourceCap === undefined || nameCap === undefined || aliasCap === undefined) {
+                return null;
+            }
+            return {
+                kind: 'alias',
+                localName: aliasCap.text,
+                importedName: nameCap.text,
+                alias: aliasCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'namespace': {
+            // `import * as N from './m'` — `N` binds the whole module.
+            if (sourceCap === undefined || aliasCap === undefined)
+                return null;
+            return {
+                kind: 'namespace',
+                localName: aliasCap.text,
+                importedName: sourceCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'reexport': {
+            // `export { X } from './m'`.
+            if (sourceCap === undefined || nameCap === undefined)
+                return null;
+            return {
+                kind: 'reexport',
+                localName: nameCap.text,
+                importedName: nameCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'reexport-alias': {
+            // `export { X as Y } from './m'`.
+            if (sourceCap === undefined || nameCap === undefined || aliasCap === undefined) {
+                return null;
+            }
+            return {
+                kind: 'reexport',
+                localName: aliasCap.text,
+                importedName: nameCap.text,
+                alias: aliasCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'reexport-wildcard': {
+            // `export * from './m'` — no local name, just a blanket passthrough.
+            if (sourceCap === undefined)
+                return null;
+            return { kind: 'wildcard', targetRaw: sourceCap.text };
+        }
+        case 'reexport-namespace': {
+            // `export * as ns from './m'` — creates a local binding `ns`
+            // that exposes the whole module, while also re-exporting it.
+            // Closest ParsedImport fit is `namespace`; the re-export side
+            // of this edge is tracked by the export detector downstream.
+            if (sourceCap === undefined || aliasCap === undefined)
+                return null;
+            return {
+                kind: 'namespace',
+                localName: aliasCap.text,
+                importedName: sourceCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'dynamic': {
+            // `import('./m')` / `import(x)`. The decomposer marks literal-
+            // string arguments with `@import.literal` so we can promote them
+            // to `dynamic-resolved` here — that lets the shared finalizer
+            // produce a file-level IMPORTS edge for lazy-loaded modules.
+            // Non-literal arguments stay `dynamic-unresolved` (target is
+            // runtime-computed and unreachable to the static finalizer).
+            const isLiteral = captures['@import.literal'] !== undefined;
+            if (isLiteral && sourceCap !== undefined) {
+                return { kind: 'dynamic-resolved', targetRaw: sourceCap.text };
+            }
+            return {
+                kind: 'dynamic-unresolved',
+                localName: '',
+                targetRaw: sourceCap?.text ?? null,
+            };
+        }
+        case 'side-effect': {
+            // `import './polyfill'` — bare-source, no local binding. The
+            // finalize layer resolves to a target file and emits a
+            // file-level IMPORTS edge; no `BindingRef` is materialized.
+            if (sourceCap === undefined)
+                return null;
+            return { kind: 'side-effect', targetRaw: sourceCap.text };
+        }
+        default:
+            return null;
+    }
+}
+// ─── interpretTypeBinding ─────────────────────────────────────────────────
+/**
+ * Interpret a `@type-binding.*` capture-match into a `ParsedTypeBinding`.
+ *
+ * TypeScript-specific strips:
+ *
+ *   - Trailing `?` on optional parameters: `(u?: User)` → `User`
+ *   - `Promise<User>` / `Array<User>` / `ReadonlyArray<User>` / `Readonly<User>`
+ *     → `User`  (wrappers that are transparent to chain propagation)
+ *   - Single-arg `List<User>` / `Iterable<User>` / `Iterator<User>` —
+ *     mirrors Python/C#'s generic-collection strip for for-of loops
+ *   - Trailing `[]` on array types: `User[]` → `User`
+ *   - Nullable unions: `User | null` / `User | undefined` / `null | User`
+ *     → `User`
+ *   - Dotted qualifiers: `models.User` → `User`  (unless the suffix is
+ *     a known collection accessor we'd want to preserve — none apply
+ *     to TS today, since TS uses `.values()` / `.keys()` call syntax)
+ */
+export function interpretTsTypeBinding(captures) {
+    const nameCap = captures['@type-binding.name'];
+    const typeCap = captures['@type-binding.type'];
+    if (nameCap === undefined || typeCap === undefined)
+        return null;
+    // Readonly/array/nullable wrappers can stack; apply passes until a
+    // fixed point (bounded by the text length since every strip monotonically
+    // shrinks the string).
+    let prev = '';
+    let rawType = typeCap.text.trim();
+    while (prev !== rawType) {
+        prev = rawType;
+        rawType = stripReadonly(rawType);
+        rawType = stripNullableUnion(rawType);
+        rawType = stripGeneric(rawType);
+        rawType = stripArraySuffix(rawType);
+    }
+    // Destructuring / member-alias / map-tuple / dotted-call-alias bindings
+    // carry receiver paths or sentinel strings that must survive verbatim.
+    // Also preserve dotted member-call callee text (`svc.getUser`) for
+    // `@type-binding.alias` — stripQualifier would reduce it to `getUser`,
+    // breaking compound-receiver's `obj.method()` split.
+    const isDestructured = captures['@type-binding.destructured'] !== undefined;
+    const isMemberAlias = captures['@type-binding.member-alias'] !== undefined;
+    const isMapTupleEntry = captures['@type-binding.map-tuple-entry'] !== undefined;
+    const isInstanceofNarrow = captures['@type-binding.instanceof-narrow'] !== undefined;
+    const isAlias = captures['@type-binding.alias'] !== undefined;
+    const preserveRawTypeName = isDestructured ||
+        isMemberAlias ||
+        isMapTupleEntry ||
+        isInstanceofNarrow ||
+        (isAlias && rawType.includes('.'));
+    if (!preserveRawTypeName) {
+        rawType = stripQualifier(rawType);
+    }
+    // Drop non-discriminating / wildcard types — `as any` / `as unknown`
+    // should not block a more-informative sibling binding (typically the
+    // constructor-inferred capture from the inner `new_expression`). By
+    // returning null here we let the scope-extractor's tie-break select
+    // the next-best binding for the same name.
+    if (UNINFORMATIVE_TYPES.has(rawType))
+        return null;
+    // Anchor captures distinguish the source of the binding. Order
+    // matters: more-specific anchors take precedence. `this` is a
+    // TypeScript-specific receiver synthesized in `receiver-binding.ts`
+    // (Unit 3); treat it as `self` for Registry.lookup parity with
+    // Python/C#.
+    let source = 'parameter-annotation';
+    if (captures['@type-binding.this'] !== undefined)
+        source = 'self';
+    else if (captures['@type-binding.constructor'] !== undefined)
+        source = 'constructor-inferred';
+    else if (captures['@type-binding.assertion'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.annotation'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.member-alias'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.alias'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.return'] !== undefined)
+        source = 'return-annotation';
+    else if (captures['@type-binding.parameter-property'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.destructured'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.map-tuple-entry'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.instanceof-narrow'] !== undefined)
+        source = 'annotation';
+    return { boundName: nameCap.text, rawTypeName: rawType, source };
+}
+/** Types that carry no discriminating information for chain resolution.
+ *  `any` / `unknown` / `object` / `never` / `void` match anything, so a
+ *  sibling capture (e.g. a constructor-inferred type from `new X() as any`)
+ *  is strictly preferable. Empty string emerges from malformed captures
+ *  and is also useless. `null` / `undefined` shouldn't survive
+ *  stripNullableUnion but are listed here for defense-in-depth. */
+const UNINFORMATIVE_TYPES = new Set([
+    '',
+    'any',
+    'unknown',
+    'object',
+    'never',
+    'void',
+    'null',
+    'undefined',
+]);
+/** `readonly User[]` → `User[]`. Applied before stripArraySuffix so
+ *  `readonly User[]` reduces through the same pipeline. */
+function stripReadonly(text) {
+    if (text.startsWith('readonly '))
+        return text.slice('readonly '.length).trim();
+    return text;
+}
+/** `User | null` / `User | undefined` / `null | User | undefined` → `User`.
+ *  Any number of `null` / `undefined` arms may appear; collapse to the
+ *  single remaining discriminating arm. Preserves multi-arm unions
+ *  of real types (`User | Admin`) since the concrete receiver type is
+ *  ambiguous. */
+function stripNullableUnion(text) {
+    const parts = text.split('|').map((p) => p.trim());
+    if (parts.length < 2)
+        return text;
+    const NULLS = new Set(['null', 'undefined']);
+    const nonNull = parts.filter((p) => !NULLS.has(p));
+    if (nonNull.length === 1)
+        return nonNull[0];
+    return text;
+}
+/** Single-arg generic wrappers transparent to receiver-type chain
+ *  propagation: `Promise<X>`, `Array<X>`, `ReadonlyArray<X>`,
+ *  `Readonly<X>`, `Iterable<X>`, `Iterator<X>`, `Set<X>`, `List<X>`,
+ *  `Map<X>` (single-arg form rare but kept for completeness), etc.
+ *  Multi-arg generics (`Map<K, V>`, `Record<K, V>`) are left alone —
+ *  element semantics aren't unambiguous. */
+function stripGeneric(text) {
+    const single = text.match(/^(?:[A-Za-z_][A-Za-z0-9_]*\.)?(?:Promise|Array|ReadonlyArray|Readonly|Iterable|Iterator|AsyncIterable|AsyncIterator|AsyncGenerator|Generator|Set|ReadonlySet|List|Awaited)<([^,<>]+)>$/);
+    if (single !== null)
+        return single[1].trim();
+    return text;
+}
+/** `User[]` / `(User)[]` → `User`. Chained `User[][]` unwraps one
+ *  level at a time per resolve pass. */
+function stripArraySuffix(text) {
+    if (text.endsWith('[]')) {
+        const inner = text.slice(0, -2).trim();
+        // Unwrap a single pair of parentheses introduced for precedence
+        // disambiguation: `(User | Admin)[]` — we leave the union intact
+        // but drop the parens.
+        if (inner.startsWith('(') && inner.endsWith(')')) {
+            return inner.slice(1, -1).trim();
+        }
+        return inner;
+    }
+    return text;
+}
+/** `models.User` → `User`. TS doesn't carry a qualified-suffix exception
+ *  list today — `.values()` / `.keys()` use method-call syntax and are
+ *  resolved via the member-call chain, not via a dotted type. */
+function stripQualifier(text) {
+    const lastDot = text.lastIndexOf('.');
+    if (lastDot === -1)
+        return text;
+    return text.slice(lastDot + 1);
+}

package/dist/core/ingestion/languages/typescript/merge-bindings.d.ts

@@ -0,0 +1,62 @@
+/**
+ * TypeScript declaration-merging + LEGB precedence for the `mergeBindings`
+ * hook.
+ *
+ * TypeScript has a unique wrinkle that Python / C# don't: **declaration
+ * merging**. The same name can legally coexist in several "declaration
+ * spaces" simultaneously:
+ *
+ *   - **value** space — `class X`, `function X`, `const X`, `var X`,
+ *     `let X`, `enum X`, `namespace X` (adds runtime object)
+ *   - **type**  space — `interface X`, `type X`, `class X`, `enum X`
+ *   - **namespace** space — `namespace X`, `class X` (static-accessed
+ *     members are reachable via dotted name)
+ *
+ * Classes and enums are unique in that each declaration occupies both
+ * the value AND type spaces. This lets:
+ *
+ *     class Foo {}
+ *     interface Foo { bar: number; }   // merges additional type members
+ *     namespace Foo { export const X = 1; } // adds static-like value
+ *
+ * all coexist for the same name.
+ *
+ * ## Algorithm
+ *
+ * For each declaration space independently:
+ *   1. Tier bindings by origin (lower wins):
+ *        0 — `local`
+ *        1 — `import` / `namespace` / `reexport`
+ *        2 — `wildcard` (`export * from …`)
+ *   2. Keep only bindings at the best (lowest) tier in that space.
+ *
+ * Then union survivors across spaces and dedupe by `DefId`.
+ *
+ * ## Shadowing examples
+ *
+ *   - `class Foo {}` + `function Foo() {}` in same scope → COMPILE ERROR
+ *     in TS source, but if both reach us with distinct DefIds we keep
+ *     both (value space has two locals at tier 0 — de-dup by nodeId
+ *     preserves both). No worse than C#-style merge.
+ *   - `class Foo {}` (local, value+type) + `import type { Foo } from './a'`
+ *     (tier-1, type-only) → local wins in both type AND value spaces;
+ *     the import is not kept.
+ *   - `interface Foo {}` (local, type-only) + `import { Foo } from './a'`
+ *     (tier-1, value+type) → local wins in type space; import wins in
+ *     value space (local doesn't occupy it). Both kept.
+ *   - `namespace Foo {}` (local, namespace+value) + `class Foo {}` (local,
+ *     value+type) → both at tier 0 in their respective spaces, kept.
+ *
+ * ## Limitations
+ *
+ *   - We classify imports by their `def.type` just like locals. Without
+ *     a space-annotation on `ParsedImport`, `import type { Foo }` looks
+ *     the same as `import { Foo }` at this layer — the parse phase
+ *     decomposer marks type-only imports so the extractor CAN annotate
+ *     `def.type = 'Type'` downstream if desired. Today it doesn't, so
+ *     `import type` imports and value imports fall in the same bucket
+ *     per their target def's NodeLabel. Parity with legacy behavior
+ *     (which also doesn't track type-only separately) is preserved.
+ */
+import type { BindingRef } from '../../../../_shared/index.js';
+export declare function typescriptMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[];

package/dist/core/ingestion/languages/typescript/merge-bindings.js

@@ -0,0 +1,158 @@
+/**
+ * TypeScript declaration-merging + LEGB precedence for the `mergeBindings`
+ * hook.
+ *
+ * TypeScript has a unique wrinkle that Python / C# don't: **declaration
+ * merging**. The same name can legally coexist in several "declaration
+ * spaces" simultaneously:
+ *
+ *   - **value** space — `class X`, `function X`, `const X`, `var X`,
+ *     `let X`, `enum X`, `namespace X` (adds runtime object)
+ *   - **type**  space — `interface X`, `type X`, `class X`, `enum X`
+ *   - **namespace** space — `namespace X`, `class X` (static-accessed
+ *     members are reachable via dotted name)
+ *
+ * Classes and enums are unique in that each declaration occupies both
+ * the value AND type spaces. This lets:
+ *
+ *     class Foo {}
+ *     interface Foo { bar: number; }   // merges additional type members
+ *     namespace Foo { export const X = 1; } // adds static-like value
+ *
+ * all coexist for the same name.
+ *
+ * ## Algorithm
+ *
+ * For each declaration space independently:
+ *   1. Tier bindings by origin (lower wins):
+ *        0 — `local`
+ *        1 — `import` / `namespace` / `reexport`
+ *        2 — `wildcard` (`export * from …`)
+ *   2. Keep only bindings at the best (lowest) tier in that space.
+ *
+ * Then union survivors across spaces and dedupe by `DefId`.
+ *
+ * ## Shadowing examples
+ *
+ *   - `class Foo {}` + `function Foo() {}` in same scope → COMPILE ERROR
+ *     in TS source, but if both reach us with distinct DefIds we keep
+ *     both (value space has two locals at tier 0 — de-dup by nodeId
+ *     preserves both). No worse than C#-style merge.
+ *   - `class Foo {}` (local, value+type) + `import type { Foo } from './a'`
+ *     (tier-1, type-only) → local wins in both type AND value spaces;
+ *     the import is not kept.
+ *   - `interface Foo {}` (local, type-only) + `import { Foo } from './a'`
+ *     (tier-1, value+type) → local wins in type space; import wins in
+ *     value space (local doesn't occupy it). Both kept.
+ *   - `namespace Foo {}` (local, namespace+value) + `class Foo {}` (local,
+ *     value+type) → both at tier 0 in their respective spaces, kept.
+ *
+ * ## Limitations
+ *
+ *   - We classify imports by their `def.type` just like locals. Without
+ *     a space-annotation on `ParsedImport`, `import type { Foo }` looks
+ *     the same as `import { Foo }` at this layer — the parse phase
+ *     decomposer marks type-only imports so the extractor CAN annotate
+ *     `def.type = 'Type'` downstream if desired. Today it doesn't, so
+ *     `import type` imports and value imports fall in the same bucket
+ *     per their target def's NodeLabel. Parity with legacy behavior
+ *     (which also doesn't track type-only separately) is preserved.
+ */
+const TIER_LOCAL = 0;
+const TIER_IMPORT = 1;
+const TIER_WILDCARD = 2;
+const TIER_UNKNOWN = 3;
+function tierOf(b) {
+    switch (b.origin) {
+        case 'local':
+            return TIER_LOCAL;
+        case 'reexport':
+        case 'import':
+        case 'namespace':
+            return TIER_IMPORT;
+        case 'wildcard':
+            return TIER_WILDCARD;
+        default:
+            return TIER_UNKNOWN;
+    }
+}
+/**
+ * Map a `SymbolDefinition.type` (`NodeLabel`) to the set of TypeScript
+ * declaration spaces the binding occupies.
+ *
+ * Unknown / unused labels default to `['value']` — the permissive choice,
+ * matching legacy behavior where everything lives in a single flat bucket.
+ */
+function spacesOf(type) {
+    switch (type) {
+        // value-only
+        case 'Function':
+        case 'Method':
+        case 'Variable':
+        case 'Const':
+        case 'Static':
+        case 'Property':
+        case 'Constructor':
+        case 'Macro':
+            return ['value'];
+        // type-only
+        case 'Interface':
+        case 'Type':
+        case 'TypeAlias':
+        case 'Typedef':
+        case 'Trait':
+        case 'Annotation':
+        case 'Decorator':
+            return ['type'];
+        // dual: value AND type
+        case 'Class':
+        case 'Enum':
+        case 'Struct':
+        case 'Record':
+        case 'Union':
+            return ['value', 'type'];
+        // namespace AND value (namespaces introduce a runtime object AND a
+        // named scope for static-style access)
+        case 'Namespace':
+        case 'Module':
+            return ['namespace', 'value'];
+        // catch-all — treat as value to match legacy permissive behavior
+        default:
+            return ['value'];
+    }
+}
+export function typescriptMergeBindings(bindings) {
+    if (bindings.length === 0)
+        return bindings;
+    // Partition bindings by space. A single binding occupying two spaces
+    // (e.g. a class) is duplicated into both partitions; the final dedupe
+    // by nodeId collapses it back.
+    const perSpace = new Map();
+    for (const b of bindings) {
+        const spaces = spacesOf(b.def.type);
+        for (const s of spaces) {
+            const list = perSpace.get(s);
+            if (list === undefined)
+                perSpace.set(s, [b]);
+            else
+                list.push(b);
+        }
+    }
+    // Within each space, keep only the best-tier bindings.
+    const survivorsSet = new Set();
+    for (const list of perSpace.values()) {
+        let bestTier = Number.POSITIVE_INFINITY;
+        for (const b of list)
+            bestTier = Math.min(bestTier, tierOf(b));
+        for (const b of list) {
+            if (tierOf(b) === bestTier)
+                survivorsSet.add(b);
+        }
+    }
+    // Dedupe by def.nodeId. If the same binding survived in multiple
+    // spaces (e.g. a class in both value + type) we keep a single entry.
+    const seen = new Map();
+    for (const b of survivorsSet)
+        seen.set(b.def.nodeId, b);
+    return [...seen.values()];
+}