gitnexus 1.6.3-rc.9 → 1.6.3

package/dist/core/ingestion/import-target-adapter.js

@@ -0,0 +1,95 @@
+/**
+ * Bridge between CLI-package per-language `ImportResolverFn`s and the
+ * shared `FinalizeHooks.resolveImportTarget` contract
+ * (RFC §5.2; Ring 2 PKG #922).
+ *
+ * The shared finalize algorithm (#915) asks one question:
+ *
+ *     resolveImportTarget(targetRaw, fromFile, workspaceIndex): string | null
+ *
+ * The CLI already has 16 language-specific resolvers satisfying a
+ * richer signature:
+ *
+ *     ImportResolverFn(rawImportPath, filePath, resolveCtx): ImportResult
+ *
+ * This module builds a dispatch adapter — one FinalizeHook implementation
+ * that looks up the file's language from its path and delegates to the
+ * right per-language resolver. Callers package per-language resolvers +
+ * a shared `ResolveCtx` into an opaque `ImportTargetWorkspace` and pass
+ * it as `workspaceIndex` to `finalizeScopeModel`.
+ *
+ * ## What's deliberately NOT here
+ *
+ *   - **Re-implementation of any per-language resolver.** We wrap the
+ *     existing `importResolver` field on each `LanguageProvider` — the
+ *     same code path the legacy DAG uses today.
+ *   - **Dynamic-import handling.** The shared finalize algorithm short-
+ *     circuits `ParsedImport { kind: 'dynamic-unresolved' }` before
+ *     calling `resolveImportTarget`, so the adapter never sees those.
+ *   - **`importPathPreprocessor`.** Preprocessing belongs inside the
+ *     provider's `interpretImport` hook (which writes the final
+ *     `ParsedImport.targetRaw`). By the time finalize passes a
+ *     `targetRaw` to this adapter, it is the string the provider wants
+ *     resolved verbatim.
+ */
+import { getLanguageFromFilename, } from '../../_shared/index.js';
+/**
+ * Build the workspace index from a map of language → provider. Providers
+ * whose `importResolver` is absent are silently skipped (no language will
+ * ever hit that branch at dispatch time).
+ *
+ * The `resolveCtx` is shared across all languages. Callers assemble it
+ * once per run (the existing pipeline already does this for the legacy
+ * DAG) and hand it to both the legacy resolution path and this factory.
+ */
+export function buildImportTargetWorkspace(providers, resolveCtx) {
+    const perLanguage = new Map();
+    for (const [lang, provider] of providers) {
+        if (provider.importResolver === undefined)
+            continue;
+        perLanguage.set(lang, { resolver: provider.importResolver, ctx: resolveCtx });
+    }
+    return { perLanguage };
+}
+/**
+ * The FinalizeHooks-compatible implementation. Dispatches on `fromFile`'s
+ * extension → per-language resolver. Returns the first resolved file,
+ * or `null` if the resolver returns `null` or doesn't know about the
+ * language.
+ *
+ * Picks the first entry of `files[]` for both `'files'` and `'package'`
+ * result kinds — the legacy pipeline uses the whole array, but the
+ * shared `finalize()` hook contract is single-file. If the workspace
+ * later needs richer semantics (split-target packages), this is the
+ * single site to extend.
+ */
+export function resolveImportTargetAcrossLanguages(targetRaw, fromFile, workspaceIndex) {
+    const workspace = workspaceIndex;
+    if (workspace === undefined || workspace.perLanguage === undefined)
+        return null;
+    const lang = getLanguageFromFilename(fromFile);
+    if (lang === null)
+        return null;
+    const entry = workspace.perLanguage.get(lang);
+    if (entry === undefined)
+        return null;
+    let result;
+    try {
+        result = entry.resolver(targetRaw, fromFile, entry.ctx);
+    }
+    catch {
+        // Existing resolvers can throw on malformed inputs (e.g., Python
+        // relative paths above the workspace root). Swallow — the shared
+        // algorithm treats a null here as `linkStatus: 'unresolved'`, which
+        // is the right fallback.
+        return null;
+    }
+    if (result === null)
+        return null;
+    // Both `files` and `package` variants expose a `files` array; the
+    // package variant also carries `dirSuffix` which we ignore at the
+    // FinalizeHook boundary (single-file contract). Legacy consumers
+    // continue to see the full result via `importResolver` directly.
+    const first = result.files[0];
+    return first ?? null;
+}

package/dist/core/ingestion/language-provider.d.ts

@@ -8,7 +8,7 @@
  * The providers table in `languages/index.ts` uses `satisfies Record<SupportedLanguages, LanguageProvider>`
  * so adding a language to the enum without creating a provider is a compiler error.
  */
-import type { SupportedLanguages, MroStrategy, Capture, CaptureMatch, BindingRef, TypeRef, Scope, ScopeId, ScopeKind, ScopeTree, ParsedImport, ParsedTypeBinding, SymbolDefinition, Callsite, WorkspaceIndex } from '../../_shared/index.js';
+import type { SupportedLanguages, MroStrategy, CaptureMatch, BindingRef, TypeRef, Scope, ScopeId, ScopeKind, ScopeTree, ParsedImport, ParsedTypeBinding, SymbolDefinition, Callsite, WorkspaceIndex } from '../../_shared/index.js';
 import type { LanguageTypeConfig } from './type-extractors/types.js';
 import type { CallRouter } from './call-routing.js';
 import type { CallExtractor, DispatchDecision, ImplicitReceiverOverride, ReceiverEnriched } from './call-types.js';
@@ -223,19 +223,46 @@ interface LanguageProviderConfig {
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;
     /**
-     * Emit scope captures from raw source. Tree-sitter-based providers run a
-     * `scopes.scm` query; standalone providers (COBOL) emit captures from a
-     * regex tagger. The return shape is parser-agnostic: the central
-     * `ScopeExtractor` consumes `Capture[]` without knowing which parser
-     * produced them.
+     * Emit scope captures from raw source, **pre-grouped per tree-sitter
+     * query match**. Tree-sitter-based providers run a scope query
+     * (embedded as a string constant in each language's `query.ts`) and
+     * emit one `CaptureMatch` per query match; standalone providers
+     * (COBOL) emit matches from a regex tagger. The return shape is
+     * parser-agnostic: the central `ScopeExtractor` consumes
+     * `CaptureMatch[]` without knowing which parser produced them.
+     *
+     * **Pre-grouping is the provider's job.** The extractor expects each
+     * `CaptureMatch` to correspond to one logical match — e.g., an import
+     * statement match carries `@import.statement` + `@import.source` +
+     * `@import.name` keyed under their capture names. Providers MUST
+     * preserve the tree-sitter match boundaries so the extractor's topic
+     * routing (scope / declaration / import / type-binding / reference)
+     * lands on coherent records.
      *
      * Required for any provider participating in scope-based resolution.
-     * Providers that have not yet migrated continue to run through the legacy
-     * DAG path (feature-flagged per `REGISTRY_PRIMARY_<LANG>`).
+     * Providers that have not yet migrated continue to run through the
+     * legacy DAG path (feature-flagged per `REGISTRY_PRIMARY_<LANG>`).
+     *
+     * **Sync return.** Tree-sitter query execution and COBOL's regex
+     * tagger are both synchronous; no current or foreseeable provider
+     * needs async work inside this hook. The sync signature lets
+     * `parse-worker.ts` (#920) invoke it inline in its already-sync
+     * per-file loop without cascading `async` through the batch pipeline.
      *
      * Default: undefined (language continues to use legacy DAG).
      */
-    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => Promise<readonly Capture[]>;
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string, 
+    /**
+     * Optional pre-parsed tree-sitter Tree the caller has already
+     * produced (e.g. from the parse phase's AST cache). When supplied,
+     * the provider SHOULD skip its own `parser.parse(sourceText)` and
+     * run its capture query against the supplied tree directly. Typed
+     * as `unknown` here to avoid leaking the tree-sitter dependency
+     * into the provider contract — the provider casts at use site.
+     * Cache miss (parameter omitted or undefined) is always safe and
+     * MUST trigger a fresh parse.
+     */
+    cachedTree?: unknown) => readonly CaptureMatch[];
     /**
      * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
      * The central finalize algorithm resolves `ParsedImport.targetRaw` to a
@@ -273,18 +300,6 @@ interface LanguageProviderConfig {
      * suffix — `@scope.function` → `'Function'`, etc.).
      */
     readonly resolveScopeKind?: (captures: CaptureMatch) => ScopeKind | null;
-    /**
-     * Should this scope capture materialize as a real `Scope` node? Return
-     * `false` to skip scope creation while still emitting declarations that
-     * would have gone inside (they attach to the enclosing real scope).
-     *
-     * Example: Python `if`/`for`/`while` bodies capture as `@scope.block` but
-     * Python has no block scope — hook returns `false` and child declarations
-     * lift to the enclosing function/module.
-     *
-     * Default: undefined (treated as `true` — always create).
-     */
-    readonly shouldCreateScope?: (captures: CaptureMatch) => boolean;
     /**
      * Override where a declaration's name becomes visible. By default the name
      * is bound in the innermost enclosing scope; return a different `ScopeId`
@@ -367,18 +382,6 @@ interface LanguageProviderConfig {
      * else treats as `'free'`).
      */
     readonly classifyCallForm?: (captures: CaptureMatch, enclosingScope: Scope) => 'free' | 'member' | 'constructor' | 'index';
-    /**
-     * Does a binding at this scope shadow bindings of the same name in outer
-     * scopes? Default: any binding shadows (standard lexical scoping). Return
-     * `false` for transparent-scope edge cases (Python `from x import *`
-     * contexts, JS `var` hoisting quirks, COBOL PARAGRAPH transparency).
-     *
-     * Consulted by `Registry.lookup` Step 1 and by `resolveTypeRef` for
-     * shadowing decisions during the lexical chain walk.
-     *
-     * Default: undefined (treated as `true` — any binding shadows).
-     */
-    readonly shouldShadow?: (scope: Scope, bindings: readonly BindingRef[]) => boolean;
     /**
      * Is this callable definition compatible with the given call-site arity?
      * Language-specific rules: Python `*args`/`**kwargs`/defaults, JS default

package/dist/core/ingestion/languages/csharp/accessor-unwrap.d.ts

@@ -0,0 +1,21 @@
+/**
+ * C# collection-accessor unwrapping.
+ *
+ * When the compound-receiver resolver encounters a trailing
+ * `.Values` / `.Keys` on a dotted member-access chain, it calls the
+ * provider's `unwrapCollectionAccessor` hook to find the element
+ * type. This module supplies the C# implementation — recognizing
+ * Dictionary-family generics and returning the value or key type.
+ *
+ * Other languages (Python, Java, TypeScript) use method-call syntax
+ * for the same access (`.values()` / `.keys()`), which the compound-
+ * receiver's call-expression branch already handles; they leave this
+ * hook undefined.
+ */
+/**
+ * Resolve `data.Values` / `data.Keys` on a Dictionary-like receiver
+ * to its element-type simple name. Returns `undefined` for any
+ * receiver / accessor combination we don't recognize, letting the
+ * compound-receiver pass fall through to the regular field walk.
+ */
+export declare function unwrapCsharpCollectionAccessor(receiverType: string, accessor: string): string | undefined;

package/dist/core/ingestion/languages/csharp/accessor-unwrap.js

@@ -0,0 +1,56 @@
+/**
+ * C# collection-accessor unwrapping.
+ *
+ * When the compound-receiver resolver encounters a trailing
+ * `.Values` / `.Keys` on a dotted member-access chain, it calls the
+ * provider's `unwrapCollectionAccessor` hook to find the element
+ * type. This module supplies the C# implementation — recognizing
+ * Dictionary-family generics and returning the value or key type.
+ *
+ * Other languages (Python, Java, TypeScript) use method-call syntax
+ * for the same access (`.values()` / `.keys()`), which the compound-
+ * receiver's call-expression branch already handles; they leave this
+ * hook undefined.
+ */
+/** Extract (K, V) from `Dictionary<K, V>` / `IDictionary<K, V>` /
+ *  `IReadOnlyDictionary<K, V>` / `SortedDictionary<K, V>` /
+ *  `ConcurrentDictionary<K, V>` / `ImmutableDictionary<K, V>`.
+ *  Returns undefined if the type name doesn't match or the argument
+ *  list isn't exactly two top-level args. */
+function extractDictionaryArgs(rawName) {
+    const match = rawName.match(/^(?:[A-Za-z_][A-Za-z0-9_.]*\.)?(?:Dictionary|IDictionary|IReadOnlyDictionary|SortedDictionary|ConcurrentDictionary|ImmutableDictionary)<(.+)>$/);
+    if (match === null)
+        return undefined;
+    const inner = match[1];
+    // Split on the top-level comma (tolerate nested `<...>`).
+    let depth = 0;
+    let commaIdx = -1;
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === '<')
+            depth++;
+        else if (ch === '>')
+            depth--;
+        else if (ch === ',' && depth === 0) {
+            commaIdx = i;
+            break;
+        }
+    }
+    if (commaIdx === -1)
+        return undefined;
+    return { key: inner.slice(0, commaIdx).trim(), value: inner.slice(commaIdx + 1).trim() };
+}
+/**
+ * Resolve `data.Values` / `data.Keys` on a Dictionary-like receiver
+ * to its element-type simple name. Returns `undefined` for any
+ * receiver / accessor combination we don't recognize, letting the
+ * compound-receiver pass fall through to the regular field walk.
+ */
+export function unwrapCsharpCollectionAccessor(receiverType, accessor) {
+    if (accessor !== 'Values' && accessor !== 'Keys')
+        return undefined;
+    const args = extractDictionaryArgs(receiverType);
+    if (args === undefined)
+        return undefined;
+    return accessor === 'Values' ? args.value : args.key;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Extract C# arity metadata from a method-like tree-sitter node —
+ * `method_declaration`, `constructor_declaration`, `destructor_declaration`,
+ * `operator_declaration`, `conversion_operator_declaration`, or
+ * `local_function_statement`.
+ *
+ * Reuses `csharpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `params` variadic collapses `parameterCount` to `undefined`,
+ *     which `csharpArityCompatibility` then treats as "max unknown" —
+ *     the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - `parameterTypes` collects declared type names (with `ref`/`out`/
+ *     `in` prefix) for overload narrowing; a literal `'params'` marker
+ *     is appended for variadic methods so `csharpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface CsharpArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computeCsharpArityMetadata(fnNode: SyntaxNode): CsharpArityMetadata;
+export {};

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

@@ -0,0 +1,46 @@
+/**
+ * Extract C# arity metadata from a method-like tree-sitter node —
+ * `method_declaration`, `constructor_declaration`, `destructor_declaration`,
+ * `operator_declaration`, `conversion_operator_declaration`, or
+ * `local_function_statement`.
+ *
+ * Reuses `csharpMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - `params` variadic collapses `parameterCount` to `undefined`,
+ *     which `csharpArityCompatibility` then treats as "max unknown" —
+ *     the candidate stays eligible at `argCount >= required`.
+ *   - Defaulted parameters (`= expr`) contribute to `optionalCount`;
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - `parameterTypes` collects declared type names (with `ref`/`out`/
+ *     `in` prefix) for overload narrowing; a literal `'params'` marker
+ *     is appended for variadic methods so `csharpArityCompatibility`
+ *     can detect them without re-reading the AST.
+ */
+import { csharpMethodConfig } from '../../method-extractors/configs/csharp.js';
+export function computeCsharpArityMetadata(fnNode) {
+    const params = csharpMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVariadic = false;
+    let optionalCount = 0;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic)
+            hasVariadic = true;
+        else if (p.isOptional)
+            optionalCount++;
+        if (p.type !== null)
+            types.push(p.type);
+    }
+    if (hasVariadic)
+        types.push('params');
+    const total = params.length;
+    // `params int[] args` declares one formal param but accepts any arg
+    // count ≥ required — mirror Python's treatment of `*args` and leave
+    // `parameterCount` undefined so the registry treats max as unknown.
+    const parameterCount = hasVariadic ? undefined : total;
+    const requiredParameterCount = hasVariadic ? undefined : total - optionalCount;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

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

@@ -0,0 +1,23 @@
+/**
+ * C# arity check, accommodating `params` variadic and default parameters.
+ *
+ * The `def` metadata we care about (synthesized by `arity-metadata.ts`):
+ *   - `parameterCount`         — total formal parameters; `undefined`
+ *                                when the method has `params T[]` variadic.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and `params` variadic).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'params'` when the method is
+ *                                variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `params` (then any `argCount >= required`).
+ *   - `'incompatible'` — argCount is below required, OR above max with no variadic.
+ *   - `'unknown'`      — metadata is absent / incomplete.
+ *
+ * `'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 csharpArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,37 @@
+/**
+ * C# arity check, accommodating `params` variadic and default parameters.
+ *
+ * The `def` metadata we care about (synthesized by `arity-metadata.ts`):
+ *   - `parameterCount`         — total formal parameters; `undefined`
+ *                                when the method has `params T[]` variadic.
+ *   - `requiredParameterCount` — min required (excludes defaulted params
+ *                                and `params` variadic).
+ *   - `parameterTypes`         — declared type strings; contains the
+ *                                literal `'params'` when the method is
+ *                                variadic.
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `params` (then any `argCount >= required`).
+ *   - `'incompatible'` — argCount is below required, OR above max with no variadic.
+ *   - `'unknown'`      — metadata is absent / incomplete.
+ *
+ * `'incompatible'` is a soft signal in `Registry.lookup` (penalized but
+ * still considered when no compatible candidate exists), per RFC §4.
+ */
+export function csharpArityCompatibility(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';
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === 'params' || t.startsWith('params '));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (C# mirror of `languages/python/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getCsharpCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetCsharpCaptureCacheStats(): void;

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

@@ -0,0 +1,26 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (C# mirror of `languages/python/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+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 getCsharpCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetCsharpCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `emitScopeCaptures` for C#.
+ *
+ * Drives the C# scope query against tree-sitter-c-sharp and groups raw
+ * matches into `CaptureMatch[]` for the central extractor. Layers one
+ * synthesized stream on top today:
+ *
+ *   1. **Decomposed using directives** — each `using_directive` is
+ *      re-emitted with `@import.kind/source/name/alias` markers so
+ *      `interpretCsharpImport` can recover the ParsedImport shape
+ *      without re-parsing raw text (see `import-decomposer.ts`).
+ *
+ * Receiver-binding synthesis (`this` / `base` type anchors) and arity
+ * metadata synthesis (Unit 5) layer on top later.
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitCsharpScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];