gitnexus 1.6.3-rc.8 → 1.6.3

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

@@ -0,0 +1,21 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing `resolvePythonImportInternal` (PEP-328
+ * relative resolution + standard suffix matching). The `WorkspaceIndex`
+ * is opaque at this layer; consumers wire a `PythonResolveContext`
+ * shape carrying `fromFile` + `allFilePaths`.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import type { ParsedImport, WorkspaceIndex } from '../../../../_shared/index.js';
+export interface PythonResolveContext {
+    readonly fromFile: string;
+    /** Mutable `Set` because the legacy `resolvePythonImportInternal`
+     *  chain downstream is typed to accept `Set<string>`. Callers that
+     *  only hold a `ReadonlySet` should copy via `new Set(...)` at the
+     *  adapter boundary. */
+    readonly allFilePaths: Set<string>;
+}
+export declare function resolvePythonImportTarget(parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex): string | null;

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

@@ -0,0 +1,99 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Delegates to the existing `resolvePythonImportInternal` (PEP-328
+ * relative resolution + standard suffix matching). The `WorkspaceIndex`
+ * is opaque at this layer; consumers wire a `PythonResolveContext`
+ * shape carrying `fromFile` + `allFilePaths`.
+ *
+ * Returning `null` lets the finalize algorithm mark the edge as
+ * `linkStatus: 'unresolved'`.
+ */
+import { resolvePythonImportInternal } from '../../import-resolvers/python.js';
+export function resolvePythonImportTarget(parsedImport, workspaceIndex) {
+    // WorkspaceIndex is `unknown` in the shared contract (Ring 1
+    // placeholder). The scope-resolution orchestrator hands us a
+    // PythonResolveContext-shaped object; narrow structurally rather
+    // than via a cast chain so unexpected shapes return null cleanly.
+    const ctx = workspaceIndex;
+    if (ctx === undefined ||
+        typeof ctx.fromFile !== 'string' ||
+        !(ctx.allFilePaths instanceof Set)) {
+        return null;
+    }
+    if (parsedImport.kind === 'dynamic-unresolved')
+        return null;
+    if (parsedImport.targetRaw === null || parsedImport.targetRaw === '')
+        return null;
+    // PEP-328 relative + single-segment proximity bare imports.
+    const internal = resolvePythonImportInternal(ctx.fromFile, parsedImport.targetRaw, ctx.allFilePaths);
+    if (internal !== null)
+        return internal;
+    // PEP-328: unresolved relative imports must NOT fall through to suffix
+    // matching. Mirrors `pythonImportStrategy` in `configs/python.ts`.
+    if (parsedImport.targetRaw.startsWith('.'))
+        return null;
+    // External dotted imports like `django.apps` must not fall through to
+    // generic suffix matching when the repo has unrelated local files such
+    // as `accounts/apps.py`. Mirrors `pythonImportStrategy`'s
+    // `hasRepoCandidate` check: only suffix-match if the leading segment
+    // looks like a local package/module somewhere in-repo.
+    const pathLike = parsedImport.targetRaw.replace(/\./g, '/');
+    if (pathLike.includes('/')) {
+        const [leadingSegment] = pathLike.split('/').filter(Boolean);
+        if (!leadingSegment || !hasRepoCandidate(leadingSegment, ctx.allFilePaths)) {
+            return null;
+        }
+    }
+    // Multi-segment absolute resolve: try exact paths first, then suffix
+    // match in nested repos. Using direct `Set.has` + `endsWith` instead of
+    // `suffixResolve`'s shared helper because that helper requires a
+    // pre-built `SuffixIndex` to disambiguate ties — without one it falls
+    // back to an O(files) scan that silently picks the wrong file when
+    // the last segment collides across directories (e.g. `accounts.models`
+    // matching `billing/models.py` when both files exist).
+    return resolveAbsoluteFromFiles(pathLike, ctx.allFilePaths);
+}
+/**
+ * Resolve `package/sub/module` style paths (already dot-flattened) to a
+ * concrete file in `allFilePaths`. Tries the exact path first, then the
+ * `__init__.py` variant, then a suffix match for nested layouts.
+ * Returns the original (un-normalized) path from the set.
+ */
+function resolveAbsoluteFromFiles(pathLike, allFilePaths) {
+    const directFile = `${pathLike}.py`;
+    const directPkg = `${pathLike}/__init__.py`;
+    const suffixFile = `/${directFile}`;
+    const suffixPkg = `/${directPkg}`;
+    let suffixMatch = null;
+    for (const raw of allFilePaths) {
+        const f = raw.replace(/\\/g, '/');
+        if (f === directFile || f === directPkg)
+            return raw;
+        if (suffixMatch === null && (f.endsWith(suffixFile) || f.endsWith(suffixPkg))) {
+            suffixMatch = raw;
+        }
+    }
+    return suffixMatch;
+}
+/**
+ * Does the repo contain a module/package named `leadingSegment` at the top
+ * level? Used to guard against false-positive suffix matches on external
+ * dotted imports (e.g. `django.apps` matching a local `accounts/apps.py`).
+ *
+ * Checks, in order: `<segment>.py` root file, `<segment>/__init__.py`
+ * regular package, or any `<segment>/**.py` file (namespace package).
+ */
+function hasRepoCandidate(leadingSegment, allFilePaths) {
+    const prefix = `${leadingSegment}/`;
+    const rootFile = `${leadingSegment}.py`;
+    const initFile = `${leadingSegment}/__init__.py`;
+    for (const raw of allFilePaths) {
+        const f = raw.replace(/\\/g, '/');
+        if (f === rootFile || f === initFile)
+            return true;
+        if (f.startsWith(prefix) && f.endsWith('.py'))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Python scope-resolution hooks (RFC #909 Ring 3, RFC §5).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules — that keeps the per-hook organization an
+ * implementation detail we can refactor without touching the provider
+ * wiring.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`                — tree-sitter query string + lazy parser/query singletons
+ *   - `ast-utils.ts`            — generic `SyntaxNode` helpers
+ *   - `import-decomposer.ts`    — `import a, b` / `from m import x, y` → one match per name
+ *   - `receiver-binding.ts`     — synthesize `self`/`cls` type bindings on methods
+ *   - `captures.ts`             — `emitPythonScopeCaptures` (top-level orchestrator)
+ *   - `cache-stats.ts`          — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ *   - `interpret.ts`            — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `merge-bindings.ts`       — Python LEGB precedence
+ *   - `arity.ts`                — Python arity check (`*args`, `**kwargs`, defaults)
+ *   - `import-target.ts`        — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *   - `simple-hooks.ts`         — small/no-op hooks made explicit
+ *
+ * ## Known limitations
+ *
+ * The Python registry-primary path intentionally does NOT resolve the
+ * following. Each is a conscious trade-off at migration time; lifting any
+ * of them is tracked as a separate follow-up rather than silently
+ * "maybe-resolving" and emitting low-confidence edges.
+ *
+ *   1. **Dynamic attribute access** — `getattr(obj, 'name')` and
+ *      `setattr` bind at runtime. We emit no edge; the call site
+ *      surfaces as an unresolved reference.
+ *   2. **Dynamic imports** — `importlib.import_module(...)` and
+ *      `__import__(...)` are not followed. Static `import x` and
+ *      `from m import x` are fully resolved.
+ *   3. **Metaclass-driven dispatch** — C3 linearization drives MRO
+ *      (see `mro-processor.ts`), but method resolution that depends
+ *      on `__getattribute__` overrides or metaclass `__call__`
+ *      remains unresolved.
+ *   4. **Union / Optional type hints** — `def f(x: Union[A, B])` or
+ *      `x: Optional[A]`: `arity.ts` validates parameter count only;
+ *      receiver-binding and field-type resolution pick the first arm
+ *      and emit a single edge rather than branching. `List[T]` /
+ *      `Dict[K, V]` strip the outer generic for receiver typing (see
+ *      `interpret.ts`).
+ *   5. **Decorators that rewrite signatures** — `@dataclass`,
+ *      `@property`, `@classmethod`, `@staticmethod` are recognized
+ *      by `receiver-binding.ts`. Arbitrary decorators (e.g.
+ *      `functools.wraps`, custom retry wrappers) preserve the wrapped
+ *      function's declared signature; a decorator that returns a
+ *      different callable is followed only through the declared
+ *      return type.
+ *   6. **`typing.TYPE_CHECKING`-guarded imports** — treated like any
+ *      other `import` for reference resolution. We do not distinguish
+ *      runtime-visible from type-checker-only imports; this is
+ *      intentional (type-only imports are still structurally valid
+ *      type references).
+ *   7. **`*args` / `**kwargs` type flow-through** — `arity.ts`
+ *      accepts any call count when a variadic is present, but no
+ *      type information flows through the variadic into the callee
+ *      body. Receiver-binding still works for explicit parameters.
+ *   8. **`super()` outside a method with a literal class binding** —
+ *      resolved for the standard `class Child(Parent): def m(self):
+ *      super().m()` pattern. Zero-arg `super()` inside a nested
+ *      function, a `functools.wraps`-rewrapped method, or a call
+ *      site where the enclosing class can't be statically determined
+ *      is left unresolved.
+ *
+ * Shadow-harness corpus parity is the authoritative signal for which
+ * of these matter in practice. The CI parity gate blocks any PR that
+ * regresses either the legacy or registry-primary run of
+ * `test/integration/resolvers/python.test.ts`.
+ */
+export { emitPythonScopeCaptures } from './captures.js';
+export { getPythonCaptureCacheStats, resetPythonCaptureCacheStats } from './cache-stats.js';
+export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.js';
+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';

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

@@ -0,0 +1,80 @@
+/**
+ * Python scope-resolution hooks (RFC #909 Ring 3, RFC §5).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules — that keeps the per-hook organization an
+ * implementation detail we can refactor without touching the provider
+ * wiring.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`                — tree-sitter query string + lazy parser/query singletons
+ *   - `ast-utils.ts`            — generic `SyntaxNode` helpers
+ *   - `import-decomposer.ts`    — `import a, b` / `from m import x, y` → one match per name
+ *   - `receiver-binding.ts`     — synthesize `self`/`cls` type bindings on methods
+ *   - `captures.ts`             — `emitPythonScopeCaptures` (top-level orchestrator)
+ *   - `cache-stats.ts`          — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ *   - `interpret.ts`            — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `merge-bindings.ts`       — Python LEGB precedence
+ *   - `arity.ts`                — Python arity check (`*args`, `**kwargs`, defaults)
+ *   - `import-target.ts`        — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *   - `simple-hooks.ts`         — small/no-op hooks made explicit
+ *
+ * ## Known limitations
+ *
+ * The Python registry-primary path intentionally does NOT resolve the
+ * following. Each is a conscious trade-off at migration time; lifting any
+ * of them is tracked as a separate follow-up rather than silently
+ * "maybe-resolving" and emitting low-confidence edges.
+ *
+ *   1. **Dynamic attribute access** — `getattr(obj, 'name')` and
+ *      `setattr` bind at runtime. We emit no edge; the call site
+ *      surfaces as an unresolved reference.
+ *   2. **Dynamic imports** — `importlib.import_module(...)` and
+ *      `__import__(...)` are not followed. Static `import x` and
+ *      `from m import x` are fully resolved.
+ *   3. **Metaclass-driven dispatch** — C3 linearization drives MRO
+ *      (see `mro-processor.ts`), but method resolution that depends
+ *      on `__getattribute__` overrides or metaclass `__call__`
+ *      remains unresolved.
+ *   4. **Union / Optional type hints** — `def f(x: Union[A, B])` or
+ *      `x: Optional[A]`: `arity.ts` validates parameter count only;
+ *      receiver-binding and field-type resolution pick the first arm
+ *      and emit a single edge rather than branching. `List[T]` /
+ *      `Dict[K, V]` strip the outer generic for receiver typing (see
+ *      `interpret.ts`).
+ *   5. **Decorators that rewrite signatures** — `@dataclass`,
+ *      `@property`, `@classmethod`, `@staticmethod` are recognized
+ *      by `receiver-binding.ts`. Arbitrary decorators (e.g.
+ *      `functools.wraps`, custom retry wrappers) preserve the wrapped
+ *      function's declared signature; a decorator that returns a
+ *      different callable is followed only through the declared
+ *      return type.
+ *   6. **`typing.TYPE_CHECKING`-guarded imports** — treated like any
+ *      other `import` for reference resolution. We do not distinguish
+ *      runtime-visible from type-checker-only imports; this is
+ *      intentional (type-only imports are still structurally valid
+ *      type references).
+ *   7. **`*args` / `**kwargs` type flow-through** — `arity.ts`
+ *      accepts any call count when a variadic is present, but no
+ *      type information flows through the variadic into the callee
+ *      body. Receiver-binding still works for explicit parameters.
+ *   8. **`super()` outside a method with a literal class binding** —
+ *      resolved for the standard `class Child(Parent): def m(self):
+ *      super().m()` pattern. Zero-arg `super()` inside a nested
+ *      function, a `functools.wraps`-rewrapped method, or a call
+ *      site where the enclosing class can't be statically determined
+ *      is left unresolved.
+ *
+ * Shadow-harness corpus parity is the authoritative signal for which
+ * of these matter in practice. The CI parity gate blocks any PR that
+ * regresses either the legacy or registry-primary run of
+ * `test/integration/resolvers/python.test.ts`.
+ */
+export { emitPythonScopeCaptures } from './captures.js';
+export { getPythonCaptureCacheStats, resetPythonCaptureCacheStats } from './cache-stats.js';
+export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.js';
+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';

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

@@ -0,0 +1,15 @@
+/**
+ * Capture-match → semantic-shape interpreters.
+ *
+ * Two pure functions, both consumed by the central scope extractor:
+ *
+ *   - `interpretPythonImport`     → `ParsedImport`
+ *   - `interpretPythonTypeBinding` → `ParsedTypeBinding`
+ *
+ * The matches arrive pre-decomposed by `emitPythonScopeCaptures`
+ * (one imported name per match; synthesized `self`/`cls` markers
+ * already attached) so these functions are straight-line tag readers.
+ */
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from '../../../../_shared/index.js';
+export declare function interpretPythonImport(captures: CaptureMatch): ParsedImport | null;
+export declare function interpretPythonTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null;

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

@@ -0,0 +1,191 @@
+/**
+ * Capture-match → semantic-shape interpreters.
+ *
+ * Two pure functions, both consumed by the central scope extractor:
+ *
+ *   - `interpretPythonImport`     → `ParsedImport`
+ *   - `interpretPythonTypeBinding` → `ParsedTypeBinding`
+ *
+ * The matches arrive pre-decomposed by `emitPythonScopeCaptures`
+ * (one imported name per match; synthesized `self`/`cls` markers
+ * already attached) so these functions are straight-line tag readers.
+ */
+// ─── interpretImport ──────────────────────────────────────────────────────
+export function interpretPythonImport(captures) {
+    // Markers attached by `splitImportStatement` (import-decomposer.ts):
+    //   `@import.kind`  : 'plain' | 'aliased' | 'from' | 'from-alias' | 'wildcard' | 'dynamic'
+    //   `@import.name`  : the imported symbol name (or module name for plain imports)
+    //   `@import.alias` : the local alias name (for `as` forms)
+    //   `@import.source`: the module path (always present except for `dynamic`)
+    const kindCap = captures['@import.kind'];
+    const nameCap = captures['@import.name'];
+    const aliasCap = captures['@import.alias'];
+    const sourceCap = captures['@import.source'];
+    const kind = kindCap?.text;
+    if (kind === undefined)
+        return null;
+    switch (kind) {
+        case 'plain': {
+            // `import numpy`
+            if (sourceCap === undefined)
+                return null;
+            return {
+                kind: 'namespace',
+                localName: sourceCap.text.split('.')[0], // `import a.b.c` exposes `a`
+                importedName: sourceCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'aliased': {
+            // `import numpy as np`
+            if (sourceCap === undefined || aliasCap === undefined)
+                return null;
+            return {
+                kind: 'namespace',
+                localName: aliasCap.text,
+                importedName: sourceCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'from': {
+            // `from m import x`
+            if (sourceCap === undefined || nameCap === undefined)
+                return null;
+            return {
+                kind: 'named',
+                localName: nameCap.text,
+                importedName: nameCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'from-alias': {
+            // `from m import x as y`
+            if (sourceCap === undefined || nameCap === undefined || aliasCap === undefined)
+                return null;
+            return {
+                kind: 'alias',
+                localName: aliasCap.text,
+                importedName: nameCap.text,
+                alias: aliasCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'wildcard': {
+            // `from m import *`
+            if (sourceCap === undefined)
+                return null;
+            return { kind: 'wildcard', targetRaw: sourceCap.text };
+        }
+        case 'dynamic': {
+            // `importlib.import_module(...)` — preserved for diagnostics.
+            return {
+                kind: 'dynamic-unresolved',
+                localName: '',
+                targetRaw: sourceCap?.text ?? null,
+            };
+        }
+        default:
+            return null;
+    }
+}
+// ─── interpretTypeBinding ─────────────────────────────────────────────────
+export function interpretPythonTypeBinding(captures) {
+    // Synthesized `self` / `cls` captures carry `@type-binding.name` and
+    // `@type-binding.type` directly — same shape as parameter annotations,
+    // source differs.
+    const nameCap = captures['@type-binding.name'];
+    const typeCap = captures['@type-binding.type'];
+    if (nameCap === undefined || typeCap === undefined)
+        return null;
+    // Strip surrounding quotes for PEP 484 forward references:
+    // `def f(x: "User")`.  Then unwrap nullable unions — `User | None`,
+    // `None | User`, `Optional[User]` — to the concrete class name so
+    // receiver-typed resolution treats nullable receivers identically to
+    // non-nullable ones.  Finally strip single-arg generic wrappers so
+    // `list[User]` / `Iterable[User]` behave like `User` for iterable
+    // for-loop chain propagation.
+    const rawType = stripGeneric(stripNullable(stripForwardRefQuotes(typeCap.text.trim())));
+    // Order matters: more specific anchor captures take precedence. `self`
+    // and `cls` are synthesized with their own marker captures; the SCM
+    // anchor topic captures (`@type-binding.parameter`,
+    // `@type-binding.annotation`, `@type-binding.constructor`) distinguish
+    // the variable-annotation and constructor-inferred forms from the
+    // classic parameter annotation.
+    let source = 'parameter-annotation';
+    if (captures['@type-binding.self'] !== undefined)
+        source = 'self';
+    // `cls` is a self-like receiver; share the source label so downstream
+    // `Registry.lookup` Step 2 treats them identically.
+    else if (captures['@type-binding.cls'] !== undefined)
+        source = 'self';
+    else if (captures['@type-binding.constructor'] !== undefined)
+        source = 'constructor-inferred';
+    else if (captures['@type-binding.annotation'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.alias'] !== undefined)
+        source = 'assignment-inferred';
+    else if (captures['@type-binding.return'] !== undefined)
+        source = 'return-annotation';
+    return { boundName: nameCap.text, rawTypeName: rawType, source };
+}
+function stripForwardRefQuotes(text) {
+    if ((text.startsWith('"') && text.endsWith('"')) ||
+        (text.startsWith("'") && text.endsWith("'"))) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+/**
+ * Unwrap a single-arg generic collection wrapper — `list[User]`,
+ * `set[User]`, `Iterable[User]`, `Sequence[User]`, `Iterator[User]`,
+ * `Generator[User, ...]` — to its element type.
+ *
+ * Point: for-loop and cross-file chain propagation need the element
+ * type, not the container. Multi-arg generics (`dict[str, User]`,
+ * `Callable[[int], User]`) are left alone — the element semantics
+ * aren't unambiguous and the scope-chain fallback handles them at
+ * resolution time.
+ */
+function stripGeneric(text) {
+    const single = text.match(/^(?:[A-Za-z_][A-Za-z0-9_]*\.)?(?:list|List|set|Set|tuple|Tuple|Iterable|Iterator|Sequence|Generator|AsyncIterable|AsyncIterator)\[([^,\]]+)\]$/);
+    if (single !== null)
+        return single[1].trim();
+    // dict[K, V] / Dict[K, V] / Mapping[K, V] — strip to value type V.
+    // For-loop destructuring of `for k, v in d.items()` binds `v` to
+    // `d`; the chain-follow then unwraps the dict annotation to V.
+    // Single-key dict `dict[K]` is not legal Python, so two args is the
+    // only shape worth handling. Match a top-level K up to the first
+    // comma and a V to the closing bracket; nested generics in V (e.g.
+    // `dict[str, list[User]]`) are left for a downstream strip pass.
+    const dict = text.match(/^(?:[A-Za-z_][A-Za-z0-9_]*\.)?(?:dict|Dict|Mapping|MutableMapping|OrderedDict|DefaultDict)\[[^,\]]+,\s*([^\]]+)\]$/);
+    if (dict !== null)
+        return dict[1].trim();
+    return text;
+}
+/**
+ * Unwrap nullable type annotations so downstream resolution treats
+ * `User | None`, `None | User`, and `Optional[User]` identically to
+ * `User`. A missing/unknown variant returns the input unchanged.
+ *
+ * This is a syntactic strip, not a semantic parse — it handles the
+ * canonical PEP-604 and `typing.Optional` shapes that cover the
+ * overwhelming majority of real-world Python annotations and punts on
+ * exotic unions (e.g. `User | Error`, which is ambiguous and should not
+ * auto-bind to one arm).
+ */
+function stripNullable(text) {
+    // `Optional[X]` / `typing.Optional[X]` / `t.Optional[X]`
+    const optMatch = text.match(/^(?:[A-Za-z_][A-Za-z0-9_]*\.)?Optional\[(.+)\]$/);
+    if (optMatch !== null)
+        return optMatch[1].trim();
+    // Binary union forms. A three-arm or larger union (`User | None | Error`)
+    // is ambiguous for single-receiver inference, so we leave it alone.
+    const parts = text.split('|').map((p) => p.trim());
+    if (parts.length !== 2)
+        return text;
+    if (parts[0] === 'None')
+        return parts[1];
+    if (parts[1] === 'None')
+        return parts[0];
+    return text;
+}

package/dist/core/ingestion/languages/python/merge-bindings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Python LEGB precedence merge for the `mergeBindings` hook.
+ *
+ * Tier ranking (lower wins in shadowing):
+ *
+ *   - 0: `local` — an `x = …` or `def x` or `class x` in this scope
+ *   - 1: `import` / `namespace` / `reexport` — `from m import x`,
+ *        `import m`, public re-exports
+ *   - 2: `wildcard` — `from m import *`
+ *
+ * Within a surviving tier we de-dup by `DefId`, last-write-wins (Python
+ * semantics: a later assignment replaces an earlier one for lookup
+ * purposes).
+ */
+import type { BindingRef } from '../../../../_shared/index.js';
+export declare function pythonMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[];

package/dist/core/ingestion/languages/python/merge-bindings.js

@@ -0,0 +1,44 @@
+/**
+ * Python LEGB precedence merge for the `mergeBindings` hook.
+ *
+ * Tier ranking (lower wins in shadowing):
+ *
+ *   - 0: `local` — an `x = …` or `def x` or `class x` in this scope
+ *   - 1: `import` / `namespace` / `reexport` — `from m import x`,
+ *        `import m`, public re-exports
+ *   - 2: `wildcard` — `from m import *`
+ *
+ * Within a surviving tier we de-dup by `DefId`, last-write-wins (Python
+ * semantics: a later assignment replaces an earlier one for lookup
+ * purposes).
+ */
+const TIER_LOCAL = 0;
+const TIER_IMPORT = 1;
+const TIER_WILDCARD = 2;
+const TIER_UNKNOWN = 3;
+function tierOf(b) {
+    switch (b.origin) {
+        case 'local':
+            return TIER_LOCAL;
+        case 'reexport':
+        case 'import':
+        case 'namespace':
+            return TIER_IMPORT;
+        case 'wildcard':
+            return TIER_WILDCARD;
+        default:
+            return TIER_UNKNOWN;
+    }
+}
+export function pythonMergeBindings(bindings) {
+    if (bindings.length === 0)
+        return bindings;
+    let bestTier = Number.POSITIVE_INFINITY;
+    for (const b of bindings)
+        bestTier = Math.min(bestTier, tierOf(b));
+    const survivors = bindings.filter((b) => tierOf(b) === bestTier);
+    const seen = new Map();
+    for (const b of survivors)
+        seen.set(b.def.nodeId, b);
+    return [...seen.values()];
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Tree-sitter query for Python scope captures (RFC §5.1).
+ *
+ * Exposes lazy `Parser` and `Query` singletons so callers don't
+ * pay tree-sitter init cost per file.
+ */
+import Parser from 'tree-sitter';
+export declare function getPythonParser(): Parser;
+export declare function getPythonScopeQuery(): Parser.Query;