@codragraph/cli 1.6.2

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;

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

@@ -0,0 +1,267 @@
+/**
+ * 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';
+import Python from 'tree-sitter-python';
+const PYTHON_SCOPE_QUERY = `
+;; Scopes
+(module) @scope.module
+(class_definition) @scope.class
+(function_definition) @scope.function
+
+;; Declarations
+(class_definition
+  name: (identifier) @declaration.name) @declaration.class
+
+(function_definition
+  name: (identifier) @declaration.name) @declaration.function
+
+(assignment
+  left: (identifier) @declaration.name) @declaration.variable
+
+;; Declarations: for-loop target — Python for-statements do NOT introduce
+;; a new scope, so the loop variable binds in the enclosing function/module
+;; scope. We emit it as a Variable declaration so Pass-2 attaches it.
+(for_statement
+  left: (identifier) @declaration.name) @declaration.variable
+
+;; Imports — single anchor per statement; interpretImport decomposes
+(import_statement) @import.statement
+(import_from_statement) @import.statement
+
+;; Type bindings (parameter annotations)
+(typed_parameter
+  (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.parameter
+
+(typed_default_parameter
+  name: (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.parameter
+
+;; Type bindings (constructor-inferred: \`u = User(...)\`)
+;; Listed BEFORE the annotation pattern so \`u: User = find()\` — which
+;; matches BOTH patterns — has the annotation (stronger source) win over
+;; the constructor-inferred guess via the scope-extractor's source-
+;; strength tie-break in pass4CollectTypeBindings.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (identifier) @type-binding.type)) @type-binding.constructor
+
+;; Qualified constructor (\`u = models.User(...)\`). Captures the
+;; attribute node as the type — its \`.text\` is the full dotted path
+;; (\`models.User\`), which \`resolveTypeRef\` resolves via
+;; \`QualifiedNameIndex\` Phase 2.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (attribute) @type-binding.type)) @type-binding.constructor
+
+;; Walrus operator: \`(u := User(...))\`. Python 3.8+ named expression.
+;; Shares the constructor-inferred shape so the binding lands in the
+;; enclosing function/module scope's typeBindings the same way a plain
+;; assignment would.
+(named_expression
+  name: (identifier) @type-binding.name
+  value: (call
+    function: (identifier) @type-binding.type)) @type-binding.constructor
+
+(named_expression
+  name: (identifier) @type-binding.name
+  value: (call
+    function: (attribute) @type-binding.type)) @type-binding.constructor
+
+;; Match-case as-pattern: \`case User() as u:\` → \`u: User\`. The
+;; class_pattern's dotted_name carries the type; the outer as_pattern's
+;; second child is the binding name.
+(as_pattern
+  (case_pattern
+    (class_pattern
+      (dotted_name) @type-binding.type))
+  (identifier) @type-binding.name) @type-binding.constructor
+
+;; Assignment chain: \`alias = user\` — the new name inherits the
+;; RHS-identifier's type. The pattern emits a TypeRef whose rawName is
+;; the RHS identifier's text; the scope-extractor's post-pass follows
+;; the chain so \`alias\` ends up pointing at whatever type \`user\` has.
+(assignment
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+;; For-loop iterable of an already-typed variable:
+;;   def f(users: list[User]):
+;;       for u in users:     # u: users (chained via post-pass)
+;;           u.save()
+;; The chain post-pass resolves \`users\` → its own type \`User\` via
+;; the generic-arg stripping in \`interpret.ts\`.
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+;; For-loop iterable of a free-call result:
+;;   def get_users() -> list[User]: ...
+;;   for u in get_users():   # u: get_users → User via chain follow
+;;       u.save()
+;; Captures the call's function identifier as the rawName. With
+;; \`propagateImportedReturnTypes\`, this works cross-file too.
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (identifier) @type-binding.type)) @type-binding.alias
+
+;; for (i, u) in enumerate(X) — paren-tuple, bind last element to X's
+;; element type. \`enumerate(X)\` yields (int, X-element); the second
+;; pattern var takes X (which the chain-follow then unwraps to its
+;; element type via generic-strip in interpret.ts).
+(for_statement
+  left: (tuple_pattern
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (identifier) @type-binding.type))
+  (#eq? @_enum "enumerate")) @type-binding.alias
+
+;; for i, u in enumerate(X) — pattern_list (no parens) variant.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (identifier) @type-binding.type))
+  (#eq? @_enum "enumerate")) @type-binding.alias
+
+;; for k, v in d.items() — bind v to d. The chain-follow unwraps d's
+;; dict[K, V] annotation to V via the dict-aware stripGeneric in
+;; interpret.ts. Covers both pattern_list and tuple_pattern shapes.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_items))
+  (#eq? @_items "items")) @type-binding.alias
+
+(for_statement
+  left: (tuple_pattern
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_items))
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for i, (k, v) in enumerate(d.items()) — nested tuple destructuring.
+;; Bind v (last id of the nested tuple) to d (the dict).
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (tuple_pattern
+      (identifier)
+      (identifier) @type-binding.name))
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (call
+        function: (attribute
+          object: (identifier) @type-binding.type
+          attribute: (identifier) @_items))))
+  (#eq? @_enum "enumerate")
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for i, k, v in enumerate(d.items()) — 3-var flat destructuring of
+;; the (i, (k,v)) tuple emitted by enumerate over items(). Bind v
+;; (last id) to d.
+(for_statement
+  left: (pattern_list
+    (identifier)
+    (identifier)
+    (identifier) @type-binding.name)
+  right: (call
+    function: (identifier) @_enum
+    arguments: (argument_list
+      (call
+        function: (attribute
+          object: (identifier) @type-binding.type
+          attribute: (identifier) @_items))))
+  (#eq? @_enum "enumerate")
+  (#eq? @_items "items")) @type-binding.alias
+
+;; for u in self.X — heuristic: bind u to X (the attribute name).
+;; The chain-follow then resolves X via the enclosing method's
+;; parameter typeBinding, supporting fixtures that reference
+;; \`self.X\` as a stand-in for a parameter X (matches legacy DAG
+;; behavior).
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (attribute
+    object: (identifier) @_self
+    attribute: (identifier) @type-binding.type)
+  (#eq? @_self "self")) @type-binding.alias
+
+;; for v in d.values() — bind v to d (dict-strip yields value type).
+(for_statement
+  left: (identifier) @type-binding.name
+  right: (call
+    function: (attribute
+      object: (identifier) @type-binding.type
+      attribute: (identifier) @_values))
+  (#eq? @_values "values")) @type-binding.alias
+
+;; Type bindings (variable annotations: \`u: User\` / \`u: User = x\`)
+(assignment
+  left: (identifier) @type-binding.name
+  type: (type) @type-binding.type) @type-binding.annotation
+
+;; Return-type annotation: \`def get_user() -> User:\` binds the
+;; FUNCTION'S NAME to its return type in the enclosing scope. Combined
+;; with the constructor-inferred + chain-follow path, \`u = get_user()\`
+;; then resolves \`u: User\` cross-call. The Python provider hoists the
+;; binding via \`pythonBindingScopeFor\` to the function's parent scope
+;; so callers in module/class scope see it.
+(function_definition
+  name: (identifier) @type-binding.name
+  return_type: (type) @type-binding.type) @type-binding.return
+
+;; References — calls
+(call
+  function: (identifier) @reference.name) @reference.call.free
+
+(call
+  function: (attribute
+    object: (_) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
+;; References — attribute writes: \`obj.name = "x"\` emits a write
+;; ACCESSES edge from the enclosing function to the field on obj's
+;; class. The receiver-bound emit pass resolves obj → its class and
+;; \`name\` → the field def via the existing typeref-receiver path.
+(assignment
+  left: (attribute
+    object: (_) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.write.member
+`;
+let _parser = null;
+let _query = null;
+export function getPythonParser() {
+    if (_parser === null) {
+        _parser = new Parser();
+        _parser.setLanguage(Python);
+    }
+    return _parser;
+}
+export function getPythonScopeQuery() {
+    if (_query === null) {
+        _query = new Parser.Query(Python, PYTHON_SCOPE_QUERY);
+    }
+    return _query;
+}

package/dist/core/ingestion/languages/python/receiver-binding.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Synthesize `@type-binding.self` / `@type-binding.cls` captures for
+ * methods.
+ *
+ * Tree-sitter can't easily express "the first parameter of a function
+ * defined directly inside a class body" via a single static query.
+ * Doing this in code keeps the embedded scope query declarative and
+ * lets us encode the `@classmethod` / `@staticmethod` decorator
+ * awareness that Python's runtime depends on.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+/**
+ * Build a `@type-binding.self` (instance method) or `@type-binding.cls`
+ * (`@classmethod`) match for `fnNode`, or `null` if `fnNode` is not a
+ * method, is `@staticmethod`, or has no parameters.
+ *
+ * The caller is responsible for guaranteeing `fnNode.type ===
+ * 'function_definition'`.
+ */
+export declare function synthesizeReceiverTypeBinding(fnNode: SyntaxNode): CaptureMatch | null;

package/dist/core/ingestion/languages/python/receiver-binding.js

@@ -0,0 +1,116 @@
+/**
+ * Synthesize `@type-binding.self` / `@type-binding.cls` captures for
+ * methods.
+ *
+ * Tree-sitter can't easily express "the first parameter of a function
+ * defined directly inside a class body" via a single static query.
+ * Doing this in code keeps the embedded scope query declarative and
+ * lets us encode the `@classmethod` / `@staticmethod` decorator
+ * awareness that Python's runtime depends on.
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+/** Walk up to the enclosing `class_definition`, ignoring the immediate
+ *  `decorated_definition` wrapper. Returns `null` when the function is
+ *  free, lambda-bodied, or nested inside another function. */
+function findEnclosingClassDefinition(node) {
+    let cur = node.parent;
+    while (cur !== null) {
+        if (cur.type === 'class_definition')
+            return cur;
+        if (cur.type === 'function_definition')
+            return null;
+        cur = cur.parent;
+    }
+    return null;
+}
+function classDefinitionName(classNode) {
+    return classNode.childForFieldName('name')?.text ?? null;
+}
+/** Does the function carry a `@<decoratorName>` decorator? Matches both
+ *  bare `@classmethod` and module-qualified `@functools.classmethod`. */
+function hasDecorator(fnNode, decoratorName) {
+    const parent = fnNode.parent;
+    if (parent === null || parent.type !== 'decorated_definition')
+        return false;
+    for (let i = 0; i < parent.namedChildCount; i++) {
+        const child = parent.namedChild(i);
+        if (child === null || child.type !== 'decorator')
+            continue;
+        const text = child.text.replace(/^@/, '').split('(')[0].trim();
+        const tail = text.split('.').pop();
+        if (tail === decoratorName)
+            return true;
+    }
+    return false;
+}
+function firstNamedParameter(parameters) {
+    for (let i = 0; i < parameters.namedChildCount; i++) {
+        const child = parameters.namedChild(i);
+        if (child === null)
+            continue;
+        // Skip `*` / `/` markers.
+        if (child.type === 'positional_separator' || child.type === 'keyword_separator')
+            continue;
+        return child;
+    }
+    return null;
+}
+function firstParameterName(param) {
+    if (param.type === 'identifier')
+        return param.text;
+    // typed_parameter / default_parameter / typed_default_parameter:
+    // first child holds the identifier / pattern.
+    const ident = param.childForFieldName('name') ?? findIdentifierChild(param);
+    return ident?.text ?? null;
+}
+function findIdentifierChild(node) {
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null && child.type === 'identifier')
+            return child;
+    }
+    return null;
+}
+/**
+ * Build a `@type-binding.self` (instance method) or `@type-binding.cls`
+ * (`@classmethod`) match for `fnNode`, or `null` if `fnNode` is not a
+ * method, is `@staticmethod`, or has no parameters.
+ *
+ * The caller is responsible for guaranteeing `fnNode.type ===
+ * 'function_definition'`.
+ */
+export function synthesizeReceiverTypeBinding(fnNode) {
+    const enclosingClass = findEnclosingClassDefinition(fnNode);
+    if (enclosingClass === null)
+        return null;
+    // Skip @staticmethod-decorated methods (no implicit receiver).
+    if (hasDecorator(fnNode, 'staticmethod'))
+        return null;
+    const isClassmethod = hasDecorator(fnNode, 'classmethod');
+    const params = fnNode.childForFieldName('parameters');
+    if (params === null)
+        return null;
+    const first = firstNamedParameter(params);
+    if (first === null)
+        return null;
+    const className = classDefinitionName(enclosingClass);
+    if (className === null)
+        return null;
+    const firstName = firstParameterName(first);
+    if (firstName === null)
+        return null;
+    // Receiver convention: instance methods get `self`, classmethods get `cls`.
+    // We trust the AST literal name (Python convention is strict in practice).
+    if (isClassmethod) {
+        return {
+            '@type-binding.cls': nodeToCapture('@type-binding.cls', first),
+            '@type-binding.name': syntheticCapture('@type-binding.name', first, firstName),
+            '@type-binding.type': syntheticCapture('@type-binding.type', first, className),
+        };
+    }
+    return {
+        '@type-binding.self': nodeToCapture('@type-binding.self', first),
+        '@type-binding.name': syntheticCapture('@type-binding.name', first, firstName),
+        '@type-binding.type': syntheticCapture('@type-binding.type', first, className),
+    };
+}

package/dist/core/ingestion/languages/python/scope-resolver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Python `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed
+ * by the generic `runScopeResolution` orchestrator.
+ *
+ * The provider is a thin wiring object — Python's specific bits
+ * (super recognizer, LEGB merge precedence, Python's relative-import
+ * resolver, the simplified MRO walk) plug into `runScopeResolution`.
+ *
+ * Migration reference: when bringing up the next language
+ * (TypeScript / Java / Kotlin / Ruby), copy this file's structure —
+ * implement the 6 required `ScopeResolver` fields, optionally toggle
+ * the 2 booleans, and register in `scope-resolution/pipeline/registry.ts`.
+ */
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+declare const pythonScopeResolver: ScopeResolver;
+export { pythonScopeResolver };