@codragraph/cli 1.6.2

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;
+}

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;