arceus-s 1.6.4

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,195 @@
+/**
+ * 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, ctx.fromFile)) {
+            return null;
+        }
+    }
+    // Multi-segment absolute resolve: try exact paths first, then ancestor
+    // walk (mirrors the single-segment ancestor walk in
+    // `resolvePythonImportInternal`), then a 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, ctx.fromFile);
+}
+/**
+ * Resolve `package/sub/module` style paths (already dot-flattened) to a
+ * concrete file in `allFilePaths`. Tries the exact path first, then walks
+ * ancestors of `fromFile` looking for `<ancestor>/<pathLike>.py` (or
+ * `__init__.py`), then falls back to a suffix match for nested layouts.
+ * Returns the original (un-normalized) path from the set.
+ *
+ * Precedence order:
+ *  1. Workspace-root direct hit (`<pathLike>.py`, `<pathLike>/__init__.py`).
+ *  2. Closest-ancestor match walking up from the importer's directory.
+ *  3. Suffix fallback (deterministic: fewest path segments, then
+ *     lexicographic on the normalized path).
+ *
+ * Root wins over ancestor by construction — if both `services/sync.py` and
+ * `backend/services/sync.py` exist, `backend/routers/cron.py`'s
+ * `from services.sync import X` resolves to the root file. This mirrors
+ * Python's `sys.path` semantics where the project root is searched first.
+ *
+ * The ancestor walk mirrors the single-segment behavior in
+ * `resolvePythonImportInternal`. For `from services.sync import X` in
+ * `backend/routers/cron.py`, walk up: `backend/routers/services/sync.py` →
+ * `backend/services/sync.py` ✓.
+ */
+function resolveAbsoluteFromFiles(pathLike, allFilePaths, fromFile) {
+    const directFile = `${pathLike}.py`;
+    const directPkg = `${pathLike}/__init__.py`;
+    // Direct hit at workspace root.
+    if (allFilePaths.has(directFile))
+        return directFile;
+    if (allFilePaths.has(directPkg))
+        return directPkg;
+    // Ancestor walk — match the single-segment resolver's behavior at
+    // multi-segment granularity. Closest match wins. Stop at `i > 0` because
+    // `i === 0` would re-check the workspace-root candidates already covered
+    // by the direct check above.
+    const importerDir = fromFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+    if (importerDir) {
+        const dirParts = importerDir.split('/').filter(Boolean);
+        for (let i = dirParts.length; i > 0; i--) {
+            const ancestor = dirParts.slice(0, i).join('/');
+            const prefix = `${ancestor}/`;
+            const candidateFile = `${prefix}${directFile}`;
+            const candidatePkg = `${prefix}${directPkg}`;
+            if (allFilePaths.has(candidateFile))
+                return candidateFile;
+            if (allFilePaths.has(candidatePkg))
+                return candidatePkg;
+        }
+    }
+    // Suffix-match fallback (preserved for monorepo/nested-repo layouts
+    // that don't share a directory ancestor with the importer).
+    //
+    // Tie-break order when multiple files match the same suffix:
+    //  1. Fewest path segments (shorter, more canonical paths win — `lib/x.py`
+    //     beats `tooling/extras/x.py`).
+    //  2. Lexicographic order over the normalized path (final stable
+    //     tiebreak independent of file-set insertion order).
+    //
+    // Without an explicit tie-break the previous implementation returned
+    // the first match in `Set` iteration order, which depended on file
+    // ingestion order and produced non-deterministic edges across runs in
+    // multi-directory collision repos.
+    const suffixFile = `/${directFile}`;
+    const suffixPkg = `/${directPkg}`;
+    const matches = [];
+    for (const raw of allFilePaths) {
+        const norm = raw.replace(/\\/g, '/');
+        if (norm.endsWith(suffixFile) || norm.endsWith(suffixPkg)) {
+            matches.push({ raw, norm });
+        }
+    }
+    if (matches.length === 0)
+        return null;
+    if (matches.length === 1)
+        return matches[0].raw;
+    matches.sort((a, b) => {
+        const aDepth = a.norm.split('/').length;
+        const bDepth = b.norm.split('/').length;
+        if (aDepth !== bDepth)
+            return aDepth - bDepth;
+        if (a.norm < b.norm)
+            return -1;
+        if (a.norm > b.norm)
+            return 1;
+        return 0;
+    });
+    return matches[0].raw;
+}
+/**
+ * Does the repo contain a module/package named `leadingSegment` somewhere
+ * the importer can plausibly reach?
+ *
+ * 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:
+ *  1. `SEGMENT.py` root file or `SEGMENT/__init__.py` regular package.
+ *  2. Any `SEGMENT/...py` file at the workspace root (namespace package).
+ *  3. Any `<importer-ancestor>/SEGMENT/...py` file (nested namespace
+ *     package the importer could reach via an ancestor walk, e.g.
+ *     `backend/services/sync.py` from `backend/routers/cron.py`).
+ *
+ * The nested case is bounded to the importer's own ancestors so a
+ * vendored copy of an external package (e.g. `vendor/django/urls.py`)
+ * does not gate-pass external imports like `from django.urls import path`
+ * issued from `app/main.py`. Files inside the vendored tree itself
+ * (importer under `vendor/django/...`) still resolve correctly because
+ * the ancestor walk includes their own parents.
+ */
+function hasRepoCandidate(leadingSegment, allFilePaths, fromFile) {
+    const prefix = `${leadingSegment}/`;
+    const rootFile = `${leadingSegment}.py`;
+    const initFile = `${leadingSegment}/__init__.py`;
+    // Build importer-ancestor prefixes: for `backend/routers/cron.py`,
+    // produces `["backend/routers/services/", "backend/services/"]` for
+    // segment `services` (closest first, root excluded — covered above).
+    const importerDir = fromFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+    const dirParts = importerDir ? importerDir.split('/').filter(Boolean) : [];
+    const ancestorPrefixes = [];
+    for (let i = dirParts.length; i > 0; i--) {
+        ancestorPrefixes.push(`${dirParts.slice(0, i).join('/')}/${leadingSegment}/`);
+    }
+    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;
+        if (f.endsWith('.py')) {
+            for (const ap of ancestorPrefixes) {
+                if (f.startsWith(ap))
+                    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, pythonFunctionDefinitionLabel, 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, pythonFunctionDefinitionLabel, 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;