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

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[];