gitnexus 1.6.4-rc.2 → 1.6.4-rc.21

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()];
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Tree-sitter query for TypeScript scope captures (RFC §5.1).
+ *
+ * Captures the structural skeleton the generic scope-resolution pipeline
+ * consumes: scopes (module/namespace/class/function), declarations (class-
+ * likes, method-likes, properties, variables), imports (one anchor per
+ * statement — decomposed in `import-decomposer.ts`), type bindings
+ * (parameter annotations, variable annotations, constructor inference,
+ * return types), and references (call sites, member writes).
+ *
+ * TypeScript specifics that shape this query:
+ *
+ *   - **Namespaces** (`namespace Foo { }`) use `internal_module` with a
+ *     `namespace` anon keyword + `identifier` or `nested_identifier` name +
+ *     `statement_block` body. Verified via Unit 1 probe.
+ *   - **`this` / `super`** are NAMED nodes `(this)` / `(super)` — unlike
+ *     C#'s `this`/`base` which are anonymous tokens. `(_)` wildcard matches
+ *     them as the receiver child of `member_expression`, so we don't need
+ *     explicit string patterns.
+ *   - **Optional chaining** (`obj?.m()`) still matches the regular
+ *     `member_expression > object: (_) / property: (property_identifier)`
+ *     pattern; the `(optional_chain)` child sits between them but doesn't
+ *     occupy a named field. Same query handles both.
+ *   - **Dynamic imports** (`import('./mod')`) are `call_expression` whose
+ *     `function` field is a named `import` node (not a regular identifier).
+ *     Captured via a dedicated pattern.
+ *   - **Function overloads** — `function f(x:string); function f(x:number);
+ *     function f(x) { … }` emits two `function_signature` nodes plus one
+ *     `function_declaration`. All three emit `@declaration.function`;
+ *     arity metadata synthesis merges parameterTypes.
+ *   - **Parameter properties** (`constructor(public name: string)`) — each
+ *     parameter emits `@declaration.property` on the enclosing class; the
+ *     same identifier also binds as a parameter in the constructor scope
+ *     via the normal `required_parameter` → `@type-binding.parameter` path.
+ *   - **Enum** — dual type+value. Emits `@scope.class` (enum body contains
+ *     member declarations) + `@declaration.enum`. Members are captured as
+ *     `@declaration.property` via the generic property_identifier pattern
+ *     inside enum_body.
+ *
+ * Node types pinned via `scripts/_probe_typescript_grammar.ts`:
+ *   internal_module, namespace_export, namespace_import, import_specifier,
+ *   export_specifier, enum_declaration, type_alias_declaration,
+ *   abstract_class_declaration, abstract_method_signature, method_signature,
+ *   generator_function_declaration, optional_parameter, rest_parameter,
+ *   required_parameter, public_field_definition, private_property_identifier,
+ *   new_expression (constructor field), call_expression with (import) fn.
+ *
+ * Grammar version: tree-sitter-typescript pinned in gitnexus/package.json.
+ *
+ * Exposes lazy `Parser` and `Query` singletons so callers don't pay tree-
+ * sitter init cost per file.
+ */
+import Parser from 'tree-sitter';
+/**
+ * Return the right tree-sitter parser for `filePath` (or the TS parser
+ * when no path is given — the legacy callsite shape).
+ */
+export declare function getTsParser(filePath?: string): Parser;
+/**
+ * Return the right tree-sitter Query (compiled against the same grammar
+ * as the parser). A Query bound to the `typescript` grammar can NOT be
+ * executed against a Tree produced by the `tsx` grammar — tree-sitter
+ * matches by node-type id, and the two grammars have separate id
+ * spaces.
+ */
+export declare function getTsScopeQuery(filePath?: string): Parser.Query;
+/**
+ * Validate that a cached `Tree` was produced by the grammar matching
+ * `filePath` (TSX vs TypeScript). The runtime tree-sitter `Tree` exposes
+ * `getLanguage()` (returning the grammar object the parser was bound
+ * to); the .d.ts is incomplete, so we reach via a cast. Identity
+ * comparison against `TSX_GRAMMAR` / `TS_GRAMMAR` is exact: the same
+ * module instance produces both. If `getLanguage` is unavailable for
+ * any reason, return true to keep behavior backwards-compatible (the
+ * original code never validated grammar at all).
+ */
+export declare function tsCachedTreeMatchesGrammar(tree: unknown, filePath: string): boolean;