gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/ingestion/languages/csharp/scope-resolver.js

@@ -0,0 +1,63 @@
+/**
+ * C# `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
+ * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
+ *
+ * Second migration after Python — see `pythonScopeResolver` for the
+ * canonical shape.
+ */
+import { SupportedLanguages } from '../../../../_shared/index.js';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import { csharpProvider } from '../csharp.js';
+import { csharpArityCompatibility, csharpMergeBindings, resolveCsharpImportTarget, } from './index.js';
+import { populateCsharpNamespaceSiblings } from './namespace-siblings.js';
+import { unwrapCsharpCollectionAccessor } from './accessor-unwrap.js';
+const csharpScopeResolver = {
+    language: SupportedLanguages.CSharp,
+    languageProvider: csharpProvider,
+    importEdgeReason: 'csharp-scope: using',
+    resolveImportTarget: (targetRaw, fromFile, allFilePaths) => {
+        const ws = { fromFile, allFilePaths };
+        // `WorkspaceIndex` is an opaque `unknown` placeholder in the
+        // shared contract, so `ws` passes structurally without a cast.
+        return resolveCsharpImportTarget({ kind: 'namespace', localName: '_', importedName: '_', targetRaw }, ws);
+    },
+    // C# shadowing: local > using > using static. The per-scope id is
+    // unused by the C# implementation (shadowing is computed purely
+    // from the binding tier), so we don't need to synthesize a Scope.
+    mergeBindings: (existing, incoming) => [...csharpMergeBindings([...existing, ...incoming])],
+    // Adapter: csharpArityCompatibility uses (def, callsite); the
+    // contract is (callsite, def).
+    arityCompatibility: (callsite, def) => csharpArityCompatibility(def, callsite),
+    buildMro: (graph, parsedFiles, nodeLookup) => buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+    populateOwners: (parsed) => populateClassOwnedMembers(parsed),
+    // C# uses `base` for super-class dispatch, not `super`. Match as a
+    // plain identifier (no `()` call like Python's `super(...)`) — `base`
+    // is a keyword-like receiver, not a callable.
+    isSuperReceiver: (text) => text.trim() === 'base',
+    // Same-namespace cross-file visibility — C# makes every type
+    // declared in `namespace X` visible to other files declaring the
+    // same namespace, without any `using` directive. See
+    // `namespace-siblings.ts` for the implementation.
+    populateNamespaceSiblings: populateCsharpNamespaceSiblings,
+    // C# is statically typed — type information is reliable. Field-
+    // fallback heuristic stays off (the type-binding layer already
+    // produces precise owner types); return-type propagation on is fine
+    // since signatures are authoritative.
+    fieldFallbackOnMethodLookup: false,
+    propagatesReturnTypesAcrossImports: true,
+    // `data.Values` / `data.Keys` on Dictionary-like receivers unwrap
+    // to the value / key element type. Other languages use method-call
+    // syntax for the same access and leave this hook undefined.
+    unwrapCollectionAccessor: unwrapCsharpCollectionAccessor,
+    // C# matches legacy DAG by collapsing member-call CALLS edges to
+    // `(caller, target)` — multiple `g.Greet(...)` sites from Main
+    // yield ONE edge, not one per site.
+    collapseMemberCallsByCallerTarget: true,
+    // C# hoists method return-type bindings to the enclosing Module
+    // scope so `propagateImportedReturnTypes` can mirror them across
+    // files. The compound-receiver walker needs to walk up from the
+    // class scope to find them; see the contract field for rationale.
+    hoistTypeBindingsToModule: true,
+};
+export { csharpScopeResolver };

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

@@ -0,0 +1,53 @@
+/**
+ * Trivial / no-op-ish hooks for the C# provider. Kept together because
+ * each is a few lines and they share a common theme: they make the
+ * provider's choice explicit rather than relying on "absence == default"
+ * so reviewers don't have to re-derive the analysis.
+ */
+import type { CaptureMatch, ParsedImport, Scope, ScopeId, ScopeTree, TypeRef } from '../../../../_shared/index.js';
+/** C# has block scope, but the central extractor's "innermost enclosing
+ *  scope" default already handles it correctly: class-body declarations
+ *  attach to the innermost Class scope, method-body declarations attach
+ *  to the innermost Function scope, and namespace-body declarations
+ *  attach to the innermost Namespace scope (which the scope query emits
+ *  for both `namespace X { }` and `namespace X;` forms).
+ *
+ *  Exception: **method return-type bindings** (`@type-binding.return`)
+ *  must hoist all the way to the Module scope. The default auto-hoist
+ *  in the central extractor only promotes one level (Function → its
+ *  parent). For C# methods the parent is always a Class, so without
+ *  this override the return binding gets stuck at the Class scope,
+ *  where it's invisible to:
+ *    - chain-follow's parent-chain walk in `followChainPostFinalize`
+ *      (tests: `var u = GetUser(); u.Save()` single-file);
+ *    - cross-file `propagateImportedReturnTypes`, which reads only
+ *      `sourceModule.typeBindings`.
+ *  Walking to Module restores both paths. */
+export declare function csharpBindingScopeFor(decl: CaptureMatch, innermost: Scope, tree: ScopeTree): ScopeId | null;
+/** `using` inside `namespace X { }` binds to that namespace's scope (its
+ *  types are visible only within that namespace's members). File-level
+ *  `using` delegates to the module default. Class-body `using` is not
+ *  legal C# — defensively handle it by attaching to the class if it
+ *  ever slips through.
+ *
+ *  `global using X;` (C# 10+) at the compilation_unit level is treated
+ *  as a file-scoped using for Unit 2's purposes; cross-file propagation
+ *  will be addressed if Unit 7's parity gate flags it. */
+export declare function csharpImportOwningScope(_imp: ParsedImport, innermost: Scope, _tree: ScopeTree): ScopeId | null;
+/** Look up `this` or `base` in the function scope's type bindings.
+ *
+ *  `this` and `base` are synthesized as type bindings on instance
+ *  methods during capture emission (`receiver-binding.ts`) — `this`
+ *  for every method inside a class/struct/record/interface body, and
+ *  `base` additionally for methods of a class-like type with an
+ *  explicit `base_list`. This hook therefore returns a non-null
+ *  `TypeRef` for instance-method bodies.
+ *
+ *  Returns `null` for:
+ *    - static methods (no `this` synthesized)
+ *    - free functions / module-level code (no enclosing class)
+ *    - non-Function scopes
+ *
+ *  Matches `pythonReceiverBinding`'s shape so the two provider
+ *  wirings stay symmetric. */
+export declare function csharpReceiverBinding(functionScope: Scope): TypeRef | null;

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

@@ -0,0 +1,76 @@
+/**
+ * Trivial / no-op-ish hooks for the C# provider. Kept together because
+ * each is a few lines and they share a common theme: they make the
+ * provider's choice explicit rather than relying on "absence == default"
+ * so reviewers don't have to re-derive the analysis.
+ */
+// ─── bindingScopeFor ──────────────────────────────────────────────────────
+/** C# has block scope, but the central extractor's "innermost enclosing
+ *  scope" default already handles it correctly: class-body declarations
+ *  attach to the innermost Class scope, method-body declarations attach
+ *  to the innermost Function scope, and namespace-body declarations
+ *  attach to the innermost Namespace scope (which the scope query emits
+ *  for both `namespace X { }` and `namespace X;` forms).
+ *
+ *  Exception: **method return-type bindings** (`@type-binding.return`)
+ *  must hoist all the way to the Module scope. The default auto-hoist
+ *  in the central extractor only promotes one level (Function → its
+ *  parent). For C# methods the parent is always a Class, so without
+ *  this override the return binding gets stuck at the Class scope,
+ *  where it's invisible to:
+ *    - chain-follow's parent-chain walk in `followChainPostFinalize`
+ *      (tests: `var u = GetUser(); u.Save()` single-file);
+ *    - cross-file `propagateImportedReturnTypes`, which reads only
+ *      `sourceModule.typeBindings`.
+ *  Walking to Module restores both paths. */
+export function csharpBindingScopeFor(decl, innermost, tree) {
+    if (decl['@type-binding.return'] !== undefined) {
+        let cur = innermost;
+        while (cur !== undefined && cur.kind !== 'Module') {
+            const parentId = cur.parent ?? null;
+            if (parentId === null)
+                break;
+            cur = tree.getScope(parentId);
+        }
+        if (cur !== undefined && cur.kind === 'Module')
+            return cur.id;
+    }
+    return null;
+}
+// ─── importOwningScope ────────────────────────────────────────────────────
+/** `using` inside `namespace X { }` binds to that namespace's scope (its
+ *  types are visible only within that namespace's members). File-level
+ *  `using` delegates to the module default. Class-body `using` is not
+ *  legal C# — defensively handle it by attaching to the class if it
+ *  ever slips through.
+ *
+ *  `global using X;` (C# 10+) at the compilation_unit level is treated
+ *  as a file-scoped using for Unit 2's purposes; cross-file propagation
+ *  will be addressed if Unit 7's parity gate flags it. */
+export function csharpImportOwningScope(_imp, innermost, _tree) {
+    if (innermost.kind === 'Namespace' || innermost.kind === 'Class' || innermost.kind === 'Function')
+        return innermost.id;
+    return null;
+}
+// ─── receiverBinding ──────────────────────────────────────────────────────
+/** Look up `this` or `base` in the function scope's type bindings.
+ *
+ *  `this` and `base` are synthesized as type bindings on instance
+ *  methods during capture emission (`receiver-binding.ts`) — `this`
+ *  for every method inside a class/struct/record/interface body, and
+ *  `base` additionally for methods of a class-like type with an
+ *  explicit `base_list`. This hook therefore returns a non-null
+ *  `TypeRef` for instance-method bodies.
+ *
+ *  Returns `null` for:
+ *    - static methods (no `this` synthesized)
+ *    - free functions / module-level code (no enclosing class)
+ *    - non-Function scopes
+ *
+ *  Matches `pythonReceiverBinding`'s shape so the two provider
+ *  wirings stay symmetric. */
+export function csharpReceiverBinding(functionScope) {
+    if (functionScope.kind !== 'Function')
+        return null;
+    return functionScope.typeBindings.get('this') ?? functionScope.typeBindings.get('base') ?? null;
+}

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

@@ -24,6 +24,7 @@ import { csharpMethodConfig } from '../method-extractors/configs/csharp.js';
 import { createVariableExtractor } from '../variable-extractors/generic.js';
 import { csharpVariableConfig } from '../variable-extractors/configs/csharp.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { emitCsharpScopeCaptures, interpretCsharpImport, interpretCsharpTypeBinding, csharpBindingScopeFor, csharpImportOwningScope, csharpMergeBindings, csharpReceiverBinding, csharpArityCompatibility, resolveCsharpImportTarget, } from './csharp/index.js';
 const BUILT_INS = new Set([
     'Console',
     'WriteLine',
@@ -135,4 +136,17 @@ export const csharpProvider = defineLanguage({
     classExtractor: createClassExtractor(csharpClassConfig),
     heritageExtractor: createHeritageExtractor(SupportedLanguages.CSharp),
     builtInNames: BUILT_INS,
+    // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
+    // C# is the second migration after Python. See ./csharp/index.ts for
+    // the full per-hook rationale and the canonical capture vocabulary
+    // in ./csharp/query.ts (CSHARP_SCOPE_QUERY constant).
+    emitScopeCaptures: emitCsharpScopeCaptures,
+    interpretImport: interpretCsharpImport,
+    interpretTypeBinding: interpretCsharpTypeBinding,
+    bindingScopeFor: csharpBindingScopeFor,
+    importOwningScope: csharpImportOwningScope,
+    mergeBindings: (_scope, bindings) => csharpMergeBindings(bindings),
+    receiverBinding: csharpReceiverBinding,
+    arityCompatibility: csharpArityCompatibility,
+    resolveImportTarget: resolveCsharpImportTarget,
 });

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

@@ -0,0 +1,24 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+interface PythonArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computePythonArityMetadata(fnNode: SyntaxNode): PythonArityMetadata;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * Extract Python arity metadata from a `function_definition` tree-sitter
+ * node — parameter count, required count, and (where present) a type
+ * list that the existing `pythonArityCompatibility` hook reads.
+ *
+ * Mirrors the legacy `buildMethodProps` conversion so scope-extracted
+ * defs carry the same arity semantics as the parse-worker path:
+ *   - `self` / `cls` are stripped (consumed by `extractPythonParameters`).
+ *   - Defaulted params contribute to `optionalCount`, flipping
+ *     `requiredParameterCount = total − optionalCount`.
+ *   - Variadic (`*args` / `**kwargs`) collapses `parameterCount` to
+ *     `undefined`, which `pythonArityCompatibility` then treats as
+ *     `'unknown'` — keeping the candidate in the registry's lookup set.
+ *   - `parameterTypes` is populated only with real type text, matching
+ *     legacy behavior.
+ */
+import { pythonMethodConfig } from '../../method-extractors/configs/python.js';
+export function computePythonArityMetadata(fnNode) {
+    const params = pythonMethodConfig.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);
+    }
+    const total = params.length;
+    const parameterCount = hasVariadic ? undefined : total;
+    // Unlike legacy `buildMethodProps`, we populate `requiredParameterCount`
+    // whenever the function isn't variadic — even when it equals
+    // `parameterCount`. The scope-resolution registry needs a concrete min
+    // to rule out under-application (e.g. picking `write_audit(x, y)` for
+    // a 1-arg call). Legacy could get away with leaving it undefined
+    // because its call-graph builder had a separate arity pre-filter.
+    const requiredParameterCount = hasVariadic ? undefined : total - optionalCount;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Python arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Python method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def 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 pythonArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,38 @@
+/**
+ * Python arity check, accommodating `*args`, `**kwargs`, and defaults.
+ *
+ * The `def` metadata we care about (set by the existing Python method/
+ * function extractor):
+ *   - `parameterCount`         — total positional + keyword params
+ *   - `requiredParameterCount` — min required (excludes defaults / `*args` / `**kwargs`)
+ *   - `parameterTypes`         — present when types are known; we also use it
+ *                                as a "we have varargs" hint (`'*args'`,
+ *                                `'**kwargs'` literals appear in the array).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — `requiredParameterCount <= argCount <= parameterCount`,
+ *                        OR the def takes `*args` (then any `argCount >= required` ok).
+ *   - `'incompatible'` — argCount is below required, OR above max with no `*args`.
+ *   - `'unknown'`      — def 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 pythonArityCompatibility(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';
+    // Detect varargs/kwargs from parameterTypes if present (the Python
+    // method extractor stores `'*args'`/`'**kwargs'` in this list).
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === '*args' || t === '**kwargs' || t.startsWith('*'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Dev-mode counters for the 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 getPythonCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetPythonCaptureCacheStats(): void;

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

@@ -0,0 +1,28 @@
+/**
+ * Dev-mode counters for the 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 getPythonCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetPythonCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `emitScopeCaptures` for Python.
+ *
+ * Drives the scope query against `tree-sitter-python` and groups raw
+ * matches into `CaptureMatch[]` for the central extractor, then layers
+ * two synthesized streams on top:
+ *
+ *   1. **Per-name import statements** — `import a, b` and
+ *      `from m import x, y` decompose to one match per imported name
+ *      (see `import-decomposer.ts`).
+ *   2. **Receiver type bindings** — each `function_definition` inside a
+ *      class body emits a `@type-binding.self` (or `@type-binding.cls`
+ *      for `@classmethod`) capture so Pass-4 attaches the implicit
+ *      receiver (see `receiver-binding.ts`).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitPythonScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];

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

@@ -0,0 +1,106 @@
+/**
+ * `emitScopeCaptures` for Python.
+ *
+ * Drives the scope query against `tree-sitter-python` and groups raw
+ * matches into `CaptureMatch[]` for the central extractor, then layers
+ * two synthesized streams on top:
+ *
+ *   1. **Per-name import statements** — `import a, b` and
+ *      `from m import x, y` decompose to one match per imported name
+ *      (see `import-decomposer.ts`).
+ *   2. **Receiver type bindings** — each `function_definition` inside a
+ *      class body emits a `@type-binding.self` (or `@type-binding.cls`
+ *      for `@classmethod`) capture so Pass-4 attaches the implicit
+ *      receiver (see `receiver-binding.ts`).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import { findNodeAtRange, nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+import { splitImportStatement } from './import-decomposer.js';
+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';
+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
+    // before. The cachedTree parameter is typed as `unknown` at the
+    // contract layer (see `LanguageProvider.emitScopeCaptures`); cast
+    // here at the use site.
+    let tree = cachedTree;
+    if (tree === undefined) {
+        tree = getPythonParser().parse(sourceText);
+        recordCacheMiss();
+    }
+    else {
+        recordCacheHit();
+    }
+    const rawMatches = getPythonScopeQuery().matches(tree.rootNode);
+    const out = [];
+    for (const m of rawMatches) {
+        // Group captures by their tag name. Tree-sitter strips the leading
+        // `@`; we put it back so the central extractor's prefix lookups
+        // (`@scope.`, `@declaration.`, …) work.
+        const grouped = {};
+        for (const c of m.captures) {
+            const tag = '@' + c.name;
+            grouped[tag] = nodeToCapture(tag, c.node);
+        }
+        if (Object.keys(grouped).length === 0)
+            continue;
+        if (grouped['@import.statement'] !== undefined) {
+            // Decompose multi-name imports. Both `import_statement` and
+            // `import_from_statement` share the matched range, so we try the
+            // `from` form first and fall back to plain.
+            const stmtCapture = grouped['@import.statement'];
+            const stmtNode = findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_from_statement') ??
+                findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement');
+            if (stmtNode !== null) {
+                for (const piece of splitImportStatement(stmtNode))
+                    out.push(piece);
+            }
+            else {
+                // Defensive fallback: emit the raw match.
+                out.push(grouped);
+            }
+            continue;
+        }
+        if (grouped['@scope.function'] !== undefined) {
+            out.push(grouped);
+            const fnNode = findNodeAtRange(tree.rootNode, grouped['@scope.function'].range, 'function_definition');
+            if (fnNode !== null) {
+                const synth = synthesizeReceiverTypeBinding(fnNode);
+                if (synth !== null)
+                    out.push(synth);
+            }
+            continue;
+        }
+        if (grouped['@declaration.function'] !== undefined) {
+            // Synthesize arity captures on the declaration match so the
+            // central scope-extractor picks them up alongside @declaration.name.
+            // The anchor range is the function_definition itself — we resolve
+            // the node and pipe it through the arity helper.
+            const anchorCap = grouped['@declaration.function'];
+            const fnNode = findNodeAtRange(tree.rootNode, anchorCap.range, 'function_definition');
+            if (fnNode !== null) {
+                const arity = computePythonArityMetadata(fnNode);
+                if (arity.parameterCount !== undefined) {
+                    grouped['@declaration.parameter-count'] = syntheticCapture('@declaration.parameter-count', fnNode, String(arity.parameterCount));
+                }
+                if (arity.requiredParameterCount !== undefined) {
+                    grouped['@declaration.required-parameter-count'] = syntheticCapture('@declaration.required-parameter-count', fnNode, String(arity.requiredParameterCount));
+                }
+                if (arity.parameterTypes !== undefined) {
+                    // Serialize as JSON so the consumer can round-trip without
+                    // inventing a quoting convention for type names that may
+                    // contain commas (`Dict[str, int]`).
+                    grouped['@declaration.parameter-types'] = syntheticCapture('@declaration.parameter-types', fnNode, JSON.stringify(arity.parameterTypes));
+                }
+            }
+            out.push(grouped);
+            continue;
+        }
+        out.push(grouped);
+    }
+    return out;
+}

package/dist/core/ingestion/languages/python/import-decomposer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decompose a Python `import_statement` / `import_from_statement` into
+ * one `CaptureMatch` per imported name.
+ *
+ * Why split here? The `LanguageProvider.interpretImport` contract is
+ * one `ParsedImport` per call. Tree-sitter delivers `import a, b as c`
+ * and `from m import x, y, z` as a single match each, so without
+ * decomposition we'd lose names. The synthesized markers
+ * (`@import.kind` / `@import.name` / `@import.alias` / `@import.source`)
+ * carry everything `interpretPythonImport` needs to recover the original
+ * `ParsedImport` shape — see `interpret.ts`.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+export declare function splitImportStatement(stmtNode: SyntaxNode): CaptureMatch[];

package/dist/core/ingestion/languages/python/import-decomposer.js

@@ -0,0 +1,112 @@
+/**
+ * Decompose a Python `import_statement` / `import_from_statement` into
+ * one `CaptureMatch` per imported name.
+ *
+ * Why split here? The `LanguageProvider.interpretImport` contract is
+ * one `ParsedImport` per call. Tree-sitter delivers `import a, b as c`
+ * and `from m import x, y, z` as a single match each, so without
+ * decomposition we'd lose names. The synthesized markers
+ * (`@import.kind` / `@import.name` / `@import.alias` / `@import.source`)
+ * carry everything `interpretPythonImport` needs to recover the original
+ * `ParsedImport` shape — see `interpret.ts`.
+ */
+import { findChild, nodeToCapture, syntheticCapture, } from '../../utils/ast-helpers.js';
+export function splitImportStatement(stmtNode) {
+    if (stmtNode.type === 'import_statement')
+        return splitImportStmt(stmtNode);
+    if (stmtNode.type === 'import_from_statement')
+        return splitImportFromStmt(stmtNode);
+    return [];
+}
+function splitImportStmt(stmtNode) {
+    // `import a, b as c, d.e`
+    const out = [];
+    for (let i = 0; i < stmtNode.namedChildCount; i++) {
+        const child = stmtNode.namedChild(i);
+        if (child === null)
+            continue;
+        if (child.type === 'dotted_name') {
+            out.push(buildImportMatch(stmtNode, {
+                kind: 'plain',
+                source: child.text,
+                name: child.text.split('.')[0],
+                atNode: child,
+            }));
+        }
+        else if (child.type === 'aliased_import') {
+            const dotted = findChild(child, 'dotted_name');
+            const alias = findChild(child, 'identifier');
+            if (dotted !== null && alias !== null) {
+                out.push(buildImportMatch(stmtNode, {
+                    kind: 'aliased',
+                    source: dotted.text,
+                    name: dotted.text,
+                    alias: alias.text,
+                    atNode: child,
+                }));
+            }
+        }
+    }
+    return out;
+}
+function splitImportFromStmt(stmtNode) {
+    // `from m import a, b as c` / `from m import *` / `from . import x`
+    const out = [];
+    const moduleField = stmtNode.childForFieldName('module_name');
+    const moduleText = moduleField?.text ?? '';
+    // Wildcard? tree-sitter-python represents `*` as a `wildcard_import`
+    // child and emits no name children.
+    const wildcardChild = findChild(stmtNode, 'wildcard_import');
+    if (wildcardChild !== null) {
+        out.push(buildImportMatch(stmtNode, {
+            kind: 'wildcard',
+            source: moduleText,
+            name: '*',
+            atNode: wildcardChild,
+        }));
+        return out;
+    }
+    // Names = every dotted_name / aliased_import that isn't the module.
+    for (let i = 0; i < stmtNode.namedChildCount; i++) {
+        const child = stmtNode.namedChild(i);
+        if (child === null)
+            continue;
+        if (moduleField !== null && child.startIndex === moduleField.startIndex)
+            continue;
+        if (child.type === 'dotted_name') {
+            out.push(buildImportMatch(stmtNode, {
+                kind: 'from',
+                source: moduleText,
+                name: child.text,
+                atNode: child,
+            }));
+        }
+        else if (child.type === 'aliased_import') {
+            const dotted = findChild(child, 'dotted_name');
+            const alias = findChild(child, 'identifier');
+            if (dotted !== null && alias !== null) {
+                out.push(buildImportMatch(stmtNode, {
+                    kind: 'from-alias',
+                    source: moduleText,
+                    name: dotted.text,
+                    alias: alias.text,
+                    atNode: child,
+                }));
+            }
+        }
+    }
+    return out;
+}
+function buildImportMatch(stmtNode, spec) {
+    const stmtCap = nodeToCapture('@import.statement', stmtNode);
+    const m = {
+        '@import.statement': stmtCap,
+        '@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
+        '@import.source': syntheticCapture('@import.source', spec.atNode, spec.source),
+        '@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
+    };
+    if (spec.alias !== undefined) {
+        m['@import.alias'] = syntheticCapture('@import.alias', spec.atNode, spec.alias);
+    }
+    return m;
+}