gitnexus 1.6.3 → 1.6.4-rc.10

package/dist/core/ingestion/languages/csharp/namespace-siblings.js

@@ -11,17 +11,18 @@
  * field-chain resolution fails at `findClassBindingInScope('User')`
  * in the Service.cs scope chain.
  *
- * Implementation: after the finalize pass populates `indexes.bindings`
- * (from explicit `using` directives), walk each file's tree-sitter
- * AST for `namespace_declaration` / `file_scoped_namespace_declaration`
- * and `using_directive` nodes. The orchestrator hands us its
- * `treeCache` so files already parsed by `extractParsedFile` are
- * re-used instead of re-parsed — `ParsedFile`'s underlying tree is
- * the single source of truth. Group classes by namespace, and inject
- * cross-file sibling classes into each Namespace scope's finalized
- * bindings with `origin: 'namespace'` — a tier below `local` so a
- * local declaration still shadows a cross-file sibling with the same
- * name.
+ * Implementation: after the finalize pass populates immutable
+ * `indexes.bindings` (from explicit `using` directives), walk each
+ * file's tree-sitter AST for `namespace_declaration` /
+ * `file_scoped_namespace_declaration` and `using_directive` nodes.
+ * The orchestrator hands us its `treeCache` so files already parsed
+ * by `extractParsedFile` are re-used instead of re-parsed —
+ * `ParsedFile`'s underlying tree is the single source of truth.
+ * Group classes by namespace, and append cross-file sibling classes
+ * into each Namespace scope's `bindingAugmentations` bucket with
+ * `origin: 'namespace'`. Finalized bindings remain first in
+ * `lookupBindingsAt`, and local lexical `Scope.bindings` remains the
+ * first-tier shadowing channel.
  *
  * The tree-sitter walk is authoritative: it sees `global using static`,
  * aliased `using static X = Y.Z;`, attributed namespace declarations,
@@ -30,13 +31,17 @@
  * coincidences).
  */
 import { getCsharpParser } from './query.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
 /** Build a structural view of a C# file by walking the tree-sitter
  *  AST. Prefers `cachedTree` (handed in via `treeCache`) so we don't
  *  re-parse files the orchestrator already parsed for `extractParsedFile`;
  *  falls back to a fresh parse on cache miss. Parser singleton is
  *  shared across calls. */
 function extractFileStructure(content, cachedTree) {
-    const tree = cachedTree ?? getCsharpParser().parse(content);
+    const tree = cachedTree ??
+        getCsharpParser().parse(content, undefined, {
+            bufferSize: getTreeSitterBufferSize(content),
+        });
     const namespaces = [];
     const usingStaticPaths = [];
     const visit = (node) => {
@@ -81,8 +86,8 @@ function extractFileStructure(content, cachedTree) {
     return { namespaces, usingStaticPaths };
 }
 /**
- * Mutate `indexes.bindings` in-place, adding cross-file sibling class
- * defs to each Namespace scope. Class-like defs (Class / Interface /
+ * Append cross-file sibling class defs to each Namespace scope's
+ * `bindingAugmentations` bucket. Class-like defs (Class / Interface /
  * Struct / Record / Enum) are visible cross-file; method / field
  * members are not.
  */
@@ -161,12 +166,15 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
             }
         }
     }
-    // Inject cross-file siblings into each namespace scope's finalized
-    // bindings. `indexes.bindings` is typed `ReadonlyMap<ScopeId, ...>`
-    // but is a plain Map at runtime; mutating here is the established
-    // pattern (see `propagateImportedReturnTypes` which does the same
-    // for module-scope typeBindings).
-    const finalized = indexes.bindings;
+    // Inject cross-file siblings into each namespace scope's
+    // post-finalize augmentation channel (per I8). The
+    // `indexes.bindingAugmentations` map is the dedicated mutable
+    // append-only buffer for post-finalize hooks: inner `BindingRef[]`
+    // arrays here are NEVER frozen (unlike `indexes.bindings`, which
+    // `materializeBindings` freezes). Walkers consult both channels
+    // via `lookupBindingsAt`; we never need to consult or mutate
+    // `indexes.bindings`.
+    const augmentations = indexes.bindingAugmentations;
     // Cross-namespace type-binding propagation: for each file, mirror
     // method return-type bindings from same-namespace sibling files and
     // from files in namespaces the importer `using`s, into the
@@ -268,18 +276,14 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
                 const simpleName = mq.includes('.') ? mq.slice(mq.lastIndexOf('.') + 1) : mq;
                 if (simpleName === '')
                     continue;
-                // Add to `indexes.bindings[moduleScope]` so
-                // `findCallableBindingInScope` picks it up.
-                let scopeBindings = finalized.get(moduleScope.id);
-                if (scopeBindings === undefined) {
-                    scopeBindings = new Map();
-                    finalized.set(moduleScope.id, scopeBindings);
-                }
-                const existing = scopeBindings.get(simpleName) ?? [];
-                if (existing.some((b) => b.def.nodeId === memberDef.nodeId))
+                // Append to the augmentation bucket for the importer's module
+                // scope. `findCallableBindingInScope` reads via
+                // `lookupBindingsAt`, which fans out across `bindings` +
+                // `bindingAugmentations`.
+                const bucketArr = getAugmentationBucket(augmentations, moduleScope.id, simpleName);
+                if (bucketArr.some((b) => b.def.nodeId === memberDef.nodeId))
                     continue;
-                existing.push({ def: memberDef, origin: 'import' });
-                scopeBindings.set(simpleName, existing);
+                bucketArr.push({ def: memberDef, origin: 'import' });
             }
         }
     }
@@ -310,16 +314,10 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
                 const simpleName = q.includes('.') ? q.slice(q.lastIndexOf('.') + 1) : q;
                 if (simpleName === '')
                     continue;
-                let scopeBindings = finalized.get(moduleScope.id);
-                if (scopeBindings === undefined) {
-                    scopeBindings = new Map();
-                    finalized.set(moduleScope.id, scopeBindings);
-                }
-                const existing = scopeBindings.get(simpleName) ?? [];
-                if (existing.some((b) => b.def.nodeId === def.nodeId))
+                const bucketArr = getAugmentationBucket(augmentations, moduleScope.id, simpleName);
+                if (bucketArr.some((b) => b.def.nodeId === def.nodeId))
                     continue;
-                existing.push({ def, origin: 'namespace' });
-                scopeBindings.set(simpleName, existing);
+                bucketArr.push({ def, origin: 'namespace' });
             }
         }
     }
@@ -339,11 +337,6 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
             defsByName.set(key, arr);
         }
         for (const { scopeId, filePath } of bucket.scopes) {
-            let scopeBindings = finalized.get(scopeId);
-            if (scopeBindings === undefined) {
-                scopeBindings = new Map();
-                finalized.set(scopeId, scopeBindings);
-            }
             for (const [name, defs] of defsByName) {
                 // Skip names already present locally — `origin: 'local'` in
                 // scope.bindings would naturally shadow the cross-file
@@ -351,20 +344,39 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
                 const local = bucket.scopes.find((s) => s.filePath === filePath)?.scope.bindings.get(name);
                 if (local !== undefined && local.some((b) => b.origin === 'local'))
                     continue;
-                const existing = scopeBindings.get(name) ?? [];
+                let bucketArr = null;
                 for (const def of defs) {
                     if (def.filePath === filePath)
                         continue; // don't self-reference
-                    if (existing.some((b) => b.def.nodeId === def.nodeId))
+                    if (bucketArr === null)
+                        bucketArr = getAugmentationBucket(augmentations, scopeId, name);
+                    if (bucketArr.some((b) => b.def.nodeId === def.nodeId))
                         continue;
-                    existing.push({ def, origin: 'namespace' });
+                    bucketArr.push({ def, origin: 'namespace' });
                 }
-                if (existing.length > 0)
-                    scopeBindings.set(name, existing);
             }
         }
     }
 }
+/** Get-or-create a mutable inner bucket inside the `bindingAugmentations`
+ *  channel. The inner arrays here are mutable by contract (see
+ *  `ScopeResolutionIndexes.bindingAugmentations` doc + scope-resolver I8);
+ *  callers may `push` directly. Allocating the outer/inner Maps lazily
+ *  keeps the augmentation footprint zero for files with no cross-file
+ *  fanout. */
+function getAugmentationBucket(augmentations, scopeId, name) {
+    let scopeBindings = augmentations.get(scopeId);
+    if (scopeBindings === undefined) {
+        scopeBindings = new Map();
+        augmentations.set(scopeId, scopeBindings);
+    }
+    let bucketArr = scopeBindings.get(name);
+    if (bucketArr === undefined) {
+        bucketArr = [];
+        scopeBindings.set(name, bucketArr);
+    }
+    return bucketArr;
+}
 function isTypeDef(def) {
     return (def.type === 'Class' ||
         def.type === 'Interface' ||

package/dist/core/ingestion/languages/python/captures.js

@@ -21,6 +21,8 @@ import { getPythonParser, getPythonScopeQuery } from './query.js';
 import { synthesizeReceiverTypeBinding } from './receiver-binding.js';
 import { computePythonArityMetadata } from './arity-metadata.js';
 import { recordCacheHit, recordCacheMiss } from './cache-stats.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { pythonFunctionDefinitionLabel } from './simple-hooks.js';
 export function emitPythonScopeCaptures(sourceText, _filePath, cachedTree) {
     // Skip the parse when the caller (parse phase's ASTCache) already
     // produced a Tree for this source. Cache miss = re-parse, same as
@@ -29,7 +31,9 @@ export function emitPythonScopeCaptures(sourceText, _filePath, cachedTree) {
     // here at the use site.
     let tree = cachedTree;
     if (tree === undefined) {
-        tree = getPythonParser().parse(sourceText);
+        tree = getPythonParser().parse(sourceText, undefined, {
+            bufferSize: getTreeSitterBufferSize(sourceText),
+        });
         recordCacheMiss();
     }
     else {
@@ -83,6 +87,10 @@ export function emitPythonScopeCaptures(sourceText, _filePath, cachedTree) {
             const anchorCap = grouped['@declaration.function'];
             const fnNode = findNodeAtRange(tree.rootNode, anchorCap.range, 'function_definition');
             if (fnNode !== null) {
+                if (pythonFunctionDefinitionLabel(fnNode, 'Function') === 'Method') {
+                    delete grouped['@declaration.function'];
+                    grouped['@declaration.method'] = { ...anchorCap, name: '@declaration.method' };
+                }
                 const arity = computePythonArityMetadata(fnNode);
                 if (arity.parameterCount !== undefined) {
                     grouped['@declaration.parameter-count'] = syntheticCapture('@declaration.parameter-count', fnNode, String(arity.parameterCount));

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

@@ -77,4 +77,4 @@ export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.j
 export { pythonMergeBindings } from './merge-bindings.js';
 export { pythonArityCompatibility } from './arity.js';
 export { resolvePythonImportTarget, type PythonResolveContext } from './import-target.js';
-export { pythonBindingScopeFor, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';
+export { pythonBindingScopeFor, pythonFunctionDefinitionLabel, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';

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

@@ -77,4 +77,4 @@ export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.j
 export { pythonMergeBindings } from './merge-bindings.js';
 export { pythonArityCompatibility } from './arity.js';
 export { resolvePythonImportTarget } from './import-target.js';
-export { pythonBindingScopeFor, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';
+export { pythonBindingScopeFor, pythonFunctionDefinitionLabel, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';

package/dist/core/ingestion/languages/python/simple-hooks.d.ts

@@ -5,7 +5,9 @@
  * "absence == default") so reviewers don't have to re-derive the
  * analysis.
  */
-import type { CaptureMatch, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+import type { CaptureMatch, NodeLabel, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+import type { SyntaxNode } from 'tree-sitter';
+export declare function pythonFunctionDefinitionLabel(functionNode: SyntaxNode, defaultLabel: NodeLabel): NodeLabel;
 /** Python has no block scope, so the central extractor's "innermost
  *  enclosing scope" default is already correct: `for x in …` creates
  *  `x` in the enclosing function/module scope (because we never emit a

package/dist/core/ingestion/languages/python/simple-hooks.js

@@ -5,6 +5,14 @@
  * "absence == default") so reviewers don't have to re-derive the
  * analysis.
  */
+import { findAncestorBeforeBoundary, FUNCTION_NODE_TYPES } from '../../utils/ast-helpers.js';
+const PYTHON_METHOD_CONTAINER_TYPES = new Set(['class_definition']);
+export function pythonFunctionDefinitionLabel(functionNode, defaultLabel) {
+    if (defaultLabel !== 'Function')
+        return defaultLabel;
+    const ancestor = findAncestorBeforeBoundary(functionNode, PYTHON_METHOD_CONTAINER_TYPES, FUNCTION_NODE_TYPES);
+    return ancestor === null ? 'Function' : 'Method';
+}
 // ─── bindingScopeFor ──────────────────────────────────────────────────────
 /** Python has no block scope, so the central extractor's "innermost
  *  enclosing scope" default is already correct: `for x in …` creates

package/dist/core/ingestion/languages/python.js

@@ -28,7 +28,7 @@ import { pythonVariableConfig } from '../variable-extractors/configs/python.js';
 import { createCallExtractor } from '../call-extractors/generic.js';
 import { pythonCallConfig } from '../call-extractors/configs/python.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
-import { emitPythonScopeCaptures, interpretPythonImport, interpretPythonTypeBinding, pythonArityCompatibility, pythonBindingScopeFor, pythonImportOwningScope, pythonMergeBindings, pythonReceiverBinding, resolvePythonImportTarget, } from './python/index.js';
+import { emitPythonScopeCaptures, pythonFunctionDefinitionLabel, interpretPythonImport, interpretPythonTypeBinding, pythonArityCompatibility, pythonBindingScopeFor, pythonImportOwningScope, pythonMergeBindings, pythonReceiverBinding, resolvePythonImportTarget, } from './python/index.js';
 const BUILT_INS = new Set([
     'print',
     'len',
@@ -75,6 +75,7 @@ export const pythonProvider = defineLanguage({
     classExtractor: createClassExtractor(pythonClassConfig),
     heritageExtractor: createHeritageExtractor(SupportedLanguages.Python),
     builtInNames: BUILT_INS,
+    labelOverride: pythonFunctionDefinitionLabel,
     // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
     // Python is the first migration. See ./python/index.ts for the
     // full per-hook rationale and the canonical capture vocabulary in

package/dist/core/ingestion/languages/typescript/arity-metadata.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Extract TypeScript arity metadata from a method-like tree-sitter node —
+ * `method_definition`, `method_signature`, `abstract_method_signature`,
+ * `function_declaration`, `generator_function_declaration`, or
+ * `function_signature` (overload signature).
+ *
+ * Reuses `typescriptMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - Rest parameters (`...args: T[]`) collapse `parameterCount` to
+ *     `undefined`, which `typescriptArityCompatibility` treats as
+ *     "max unknown" — the candidate stays eligible at
+ *     `argCount >= required` (mirrors Python `*args` / C# `params`).
+ *   - Optional (`p?: T`) and defaulted (`p: T = …`) parameters both
+ *     contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - `parameterTypes` collects declared type-annotation text for
+ *     overload narrowing; TypeScript supports function overloading
+ *     (`function f(x: string); function f(x: number); function f(x) {}`),
+ *     so populated types let the registry disambiguate same-arity
+ *     siblings by declared types.
+ *   - A literal `'params'` marker is appended for variadic methods so
+ *     `typescriptArityCompatibility` can detect rest params without
+ *     re-reading the AST.
+ *
+ * ## Generics stripping
+ *
+ * TypeScript parameter types frequently contain generic instantiations
+ * (`User<string>`, `Array<User>`, `Promise<User[]>`). For overload
+ * narrowing by declared type, we want the "head" name — `User`,
+ * `Array`, `Promise` — so `arity-metadata` applies a light strip to
+ * each `parameterTypes[i]`:
+ *
+ *   - `Foo<Bar>`          → `Foo`
+ *   - `Foo<Bar, Baz>`     → `Foo`
+ *   - `Foo[]`             → `Foo`
+ *   - `Foo<Bar>[]`        → `Foo`
+ *   - `Foo<Bar<Baz>>`     → `Foo`   (greedy — strip the outermost once)
+ *   - plain `Foo`         → `Foo`
+ *
+ * We do NOT strip unions / intersections at this layer — those stay
+ * intact because the registry's overload narrowing is a string
+ * equality check; union types shouldn't match anything and we prefer
+ * "unknown" to "accidental match". `undefined` / `null` in unions
+ * (TS strict mode) is handled by `interpret.ts`'s `stripNullableUnion`
+ * when the name would be consumed as a receiver type — that path is
+ * separate from this arity-metadata path.
+ *
+ * Generic type parameters on the function itself (`function f<T>(x: T)`)
+ * do NOT enter here — the method extractor reads the `parameters`
+ * field only, which contains value parameters, not type parameters.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface TsArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computeTsArityMetadata(fnNode: SyntaxNode): TsArityMetadata;
+export {};

package/dist/core/ingestion/languages/typescript/arity-metadata.js

@@ -0,0 +1,103 @@
+/**
+ * Extract TypeScript arity metadata from a method-like tree-sitter node —
+ * `method_definition`, `method_signature`, `abstract_method_signature`,
+ * `function_declaration`, `generator_function_declaration`, or
+ * `function_signature` (overload signature).
+ *
+ * Reuses `typescriptMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - Rest parameters (`...args: T[]`) collapse `parameterCount` to
+ *     `undefined`, which `typescriptArityCompatibility` treats as
+ *     "max unknown" — the candidate stays eligible at
+ *     `argCount >= required` (mirrors Python `*args` / C# `params`).
+ *   - Optional (`p?: T`) and defaulted (`p: T = …`) parameters both
+ *     contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - `parameterTypes` collects declared type-annotation text for
+ *     overload narrowing; TypeScript supports function overloading
+ *     (`function f(x: string); function f(x: number); function f(x) {}`),
+ *     so populated types let the registry disambiguate same-arity
+ *     siblings by declared types.
+ *   - A literal `'params'` marker is appended for variadic methods so
+ *     `typescriptArityCompatibility` can detect rest params without
+ *     re-reading the AST.
+ *
+ * ## Generics stripping
+ *
+ * TypeScript parameter types frequently contain generic instantiations
+ * (`User<string>`, `Array<User>`, `Promise<User[]>`). For overload
+ * narrowing by declared type, we want the "head" name — `User`,
+ * `Array`, `Promise` — so `arity-metadata` applies a light strip to
+ * each `parameterTypes[i]`:
+ *
+ *   - `Foo<Bar>`          → `Foo`
+ *   - `Foo<Bar, Baz>`     → `Foo`
+ *   - `Foo[]`             → `Foo`
+ *   - `Foo<Bar>[]`        → `Foo`
+ *   - `Foo<Bar<Baz>>`     → `Foo`   (greedy — strip the outermost once)
+ *   - plain `Foo`         → `Foo`
+ *
+ * We do NOT strip unions / intersections at this layer — those stay
+ * intact because the registry's overload narrowing is a string
+ * equality check; union types shouldn't match anything and we prefer
+ * "unknown" to "accidental match". `undefined` / `null` in unions
+ * (TS strict mode) is handled by `interpret.ts`'s `stripNullableUnion`
+ * when the name would be consumed as a receiver type — that path is
+ * separate from this arity-metadata path.
+ *
+ * Generic type parameters on the function itself (`function f<T>(x: T)`)
+ * do NOT enter here — the method extractor reads the `parameters`
+ * field only, which contains value parameters, not type parameters.
+ */
+import { typescriptMethodConfig } from '../../method-extractors/configs/typescript-javascript.js';
+export function computeTsArityMetadata(fnNode) {
+    const params = typescriptMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasRest = false;
+    let optionalCount = 0;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic)
+            hasRest = true;
+        else if (p.isOptional)
+            optionalCount++;
+        const t = p.type !== null && p.type !== undefined ? stripGenericsAndArraySuffix(p.type) : '';
+        types.push(t);
+    }
+    if (hasRest)
+        types.push('params');
+    const total = params.length;
+    const parameterCount = hasRest ? undefined : total;
+    const requiredParameterCount = hasRest ? undefined : total - optionalCount;
+    // Only emit parameterTypes when at least one param carries a non-
+    // empty type name. An array of all empty strings adds noise to the
+    // registry without aiding narrowing — callers treat absence as
+    // "types unknown".
+    const hasAnyType = types.some((t) => t !== '' && t !== 'params');
+    const parameterTypes = hasAnyType || hasRest ? (types.length > 0 ? types : undefined) : undefined;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes,
+    };
+}
+/**
+ * Light generic + array-suffix strip used only for registry overload
+ * narrowing. See file-level JSDoc for the exact transformation table.
+ *
+ * Handles nesting greedily at the outermost level:
+ *   `Foo<Bar<Baz>>[]` — strip `[]` → `Foo<Bar<Baz>>`, then strip
+ *   outermost `<>` → `Foo`.
+ */
+function stripGenericsAndArraySuffix(raw) {
+    let t = raw.trim();
+    // Repeatedly peel trailing `[]` pairs, then peel the outermost `<…>`
+    // block once. We don't loop the `<>` peel since nesting is rare and
+    // the head name is already reached after one peel.
+    while (t.endsWith('[]'))
+        t = t.slice(0, -2).trim();
+    const lt = t.indexOf('<');
+    if (lt > 0 && t.endsWith('>')) {
+        t = t.slice(0, lt).trim();
+    }
+    return t;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * TypeScript arity check, accommodating rest parameters and optional
+ * (`p?: T`) / defaulted (`p: T = …`) parameters.
+ *
+ * TypeScript-specific semantics vs C#:
+ *
+ *   - **Optional** — `p?: T` collapses to `isOptional` in the extractor
+ *     and contributes to `optionalCount`, so `requiredParameterCount`
+ *     excludes it. Same wire shape as a default-valued parameter.
+ *   - **Rest** — `...args: T[]` makes `parameterCount` undefined (max
+ *     unknown) and `parameterTypes` carries a literal `'params'` marker
+ *     so this hook can detect variadic calls without re-reading the AST
+ *     (mirrors the C# convention for cross-language consistency).
+ *   - **Generics** — function-level generic type parameters (`<T, U>`)
+ *     do NOT count toward arity; the method-extractor reads the
+ *     `parameters` field and ignores `type_parameters`, so generic
+ *     count never enters the metadata.
+ *
+ * The metadata shape (`parameterCount`, `requiredParameterCount`,
+ * `parameterTypes`) is synthesized by `arity-metadata.ts` and stored
+ * on `SymbolDefinition`. This file consumes that metadata.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <=
+ *                        parameterCount`, OR the def has rest params
+ *                        (any `argCount >= required`).
+ *   - `'incompatible'` — argCount is below required, OR above max with
+ *                        no rest params.
+ *   - `'unknown'`      — metadata is absent / incomplete (treated as
+ *                        neutral by the registry).
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized
+ * but still considered when no compatible candidate exists), per
+ * RFC §4.
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function typescriptArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,54 @@
+/**
+ * TypeScript arity check, accommodating rest parameters and optional
+ * (`p?: T`) / defaulted (`p: T = …`) parameters.
+ *
+ * TypeScript-specific semantics vs C#:
+ *
+ *   - **Optional** — `p?: T` collapses to `isOptional` in the extractor
+ *     and contributes to `optionalCount`, so `requiredParameterCount`
+ *     excludes it. Same wire shape as a default-valued parameter.
+ *   - **Rest** — `...args: T[]` makes `parameterCount` undefined (max
+ *     unknown) and `parameterTypes` carries a literal `'params'` marker
+ *     so this hook can detect variadic calls without re-reading the AST
+ *     (mirrors the C# convention for cross-language consistency).
+ *   - **Generics** — function-level generic type parameters (`<T, U>`)
+ *     do NOT count toward arity; the method-extractor reads the
+ *     `parameters` field and ignores `type_parameters`, so generic
+ *     count never enters the metadata.
+ *
+ * The metadata shape (`parameterCount`, `requiredParameterCount`,
+ * `parameterTypes`) is synthesized by `arity-metadata.ts` and stored
+ * on `SymbolDefinition`. This file consumes that metadata.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <=
+ *                        parameterCount`, OR the def has rest params
+ *                        (any `argCount >= required`).
+ *   - `'incompatible'` — argCount is below required, OR above max with
+ *                        no rest params.
+ *   - `'unknown'`      — metadata is absent / incomplete (treated as
+ *                        neutral by the registry).
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized
+ * but still considered when no compatible candidate exists), per
+ * RFC §4.
+ */
+export function typescriptArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    // Variadic detection: the `arity-metadata` synthesizer appends the
+    // literal `'params'` marker to `parameterTypes` when the def has a
+    // rest parameter, to avoid re-parsing the AST here.
+    const hasRest = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === 'params' || t.startsWith('params '));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasRest)
+        return 'incompatible';
+    return 'compatible';
+}

package/dist/core/ingestion/languages/typescript/cache-stats.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dev-mode counters for the TypeScript cross-phase scope-captures parse cache.
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. In production the module-level `PROF`
+ * constant is `false` and V8 folds every increment site into dead code, so the
+ * hot path in `captures.ts` stays branch-free.
+ *
+ * Extracted from `captures.ts` so the production hot-path module doesn't carry
+ * a module-global counter and its reset/export surface.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getTypescriptCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetTypescriptCaptureCacheStats(): void;

package/dist/core/ingestion/languages/typescript/cache-stats.js

@@ -0,0 +1,28 @@
+/**
+ * Dev-mode counters for the TypeScript cross-phase scope-captures parse cache.
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. In production the module-level `PROF`
+ * constant is `false` and V8 folds every increment site into dead code, so the
+ * hot path in `captures.ts` stays branch-free.
+ *
+ * Extracted from `captures.ts` so the production hot-path module doesn't carry
+ * a module-global counter and its reset/export surface.
+ */
+const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+let CACHE_HITS = 0;
+let CACHE_MISSES = 0;
+export function recordCacheHit() {
+    if (PROF)
+        CACHE_HITS++;
+}
+export function recordCacheMiss() {
+    if (PROF)
+        CACHE_MISSES++;
+}
+export function getTypescriptCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetTypescriptCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * `emitScopeCaptures` for TypeScript.
+ *
+ * Drives the TypeScript scope query against tree-sitter-typescript and groups
+ * raw matches into `CaptureMatch[]` for the central extractor. Layers
+ * synthesized streams on top:
+ *
+ *   1. **Import decomposition** — each `import_statement` / re-export is
+ *      re-emitted with `@import.kind/source/name/alias/typeOnly` markers so
+ *      `interpretTsImport` can recover the `ParsedImport` shape without
+ *      re-parsing raw text (see `import-decomposer.ts`). Unit 2 adds this;
+ *      until then, raw `@import.statement` matches flow through as-is.
+ *   2. **Dynamic imports** — `import('./m')` is re-emitted as a
+ *      decomposed `@import.statement` with `@import.kind=dynamic` so the
+ *      central extractor treats it uniformly with static imports.
+ *   3. **Function-decl arity metadata** (Unit 5) — `@declaration.parameter-count`
+ *      / `@declaration.required-parameter-count` / `@declaration.parameter-types`
+ *      synthesized onto function-like declarations so the registry can narrow
+ *      overloads.
+ *   4. **Callsite arity metadata** (Unit 5) — `@reference.arity` /
+ *      `@reference.parameter-types` on every callsite.
+ *   5. **Receiver-binding synthesis** (Unit 3) — `this` type anchors on
+ *      instance methods, with arrow-function lexical-this walk-up.
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitTsScopeCaptures(sourceText: string, filePath: string, cachedTree?: unknown): readonly CaptureMatch[];