cgraphx 2.0.2 → 2.0.3

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

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPythonParser = getPythonParser;
+exports.getPythonScopeQuery = getPythonScopeQuery;
+const tree_sitter_1 = __importDefault(require("tree-sitter"));
+const node_module_1 = require("node:module");
+// 懒加载(spec §7/§13):tree-sitter-python 移至 devDependencies,生产 --omit=dev 不装。
+// 首次用到时按需 require + 缓存;失败 → null,该语言降级为结构层收录,不阻断 analyze。
+const _require = (0, node_module_1.createRequire)(__filename);
+let _pythonGrammar;
+const loadPythonGrammar = () => {
+    if (_pythonGrammar !== undefined)
+        return _pythonGrammar;
+    try {
+        _pythonGrammar = _require('tree-sitter-python');
+    }
+    catch {
+        _pythonGrammar = null;
+    }
+    return _pythonGrammar;
+};
+const PYTHON_SCOPE_QUERY = `
+;; Scopes
+(module) @scope.module
+(class_definition) @scope.class
+(function_definition) @scope.function
+(lambda) @scope.function
+
+;; Declarations
+(class_definition
+  name: (identifier) @declaration.name) @declaration.class
+
+(function_definition
+  name: (identifier) @declaration.name) @declaration.function
+
+;; Lambda bindings (\`f = lambda x: x\`). The \`@declaration.function\` anchor
+;; sits on the INNER lambda so its range aligns with \`(lambda) @scope.function\`
+;; above; otherwise the def is owned by the module scope and calls inside the
+;; lambda lose caller attribution. Mirrors the TypeScript arrow patterns (#2687).
+(expression_statement
+  (assignment
+    left: (identifier) @declaration.name
+    right: (lambda) @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
+
+;; Decorators — simple @decorator
+(decorator
+  (identifier) @reference.name) @reference.call.free
+
+;; Decorators — @obj.decorator (single attribute, identifier receiver)
+(decorator
+  (attribute
+    object: (identifier) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
+;; Decorators — @a.b.decorator (nested attributes)
+(decorator
+  (attribute
+    object: (attribute) @reference.receiver
+    attribute: (identifier) @reference.name)) @reference.call.member
+
+;; 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;
+function getPythonParser() {
+    if (_parser === null) {
+        const grammar = loadPythonGrammar();
+        if (grammar === null) {
+            throw new Error('tree-sitter-python grammar unavailable — install it (devDependency) or the language degrades to structure-layer capture.');
+        }
+        _parser = new tree_sitter_1.default();
+        _parser.setLanguage(grammar);
+    }
+    return _parser;
+}
+function getPythonScopeQuery() {
+    if (_query === null) {
+        const grammar = loadPythonGrammar();
+        if (grammar === null) {
+            throw new Error('tree-sitter-python grammar unavailable — install it (devDependency) or the language degrades to structure-layer capture.');
+        }
+        _query = new tree_sitter_1.default.Query(grammar, PYTHON_SCOPE_QUERY);
+    }
+    return _query;
+}

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

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Synthesize implicit receiver and constructor-assigned field type bindings
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeReceiverTypeBinding = synthesizeReceiverTypeBinding;
+exports.synthesizeConstructorFieldTypeBindings = synthesizeConstructorFieldTypeBindings;
+const ast_helpers_js_1 = require("../../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'`.
+ */
+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': (0, ast_helpers_js_1.nodeToCapture)('@type-binding.cls', first),
+            '@type-binding.name': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.name', first, firstName),
+            '@type-binding.type': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.type', first, className),
+        };
+    }
+    return {
+        '@type-binding.self': (0, ast_helpers_js_1.nodeToCapture)('@type-binding.self', first),
+        '@type-binding.name': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.name', first, firstName),
+        '@type-binding.type': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.type', first, className),
+    };
+}
+/**
+ * The class name of a direct constructor call — `Outer()` — or `undefined` for
+ * anything else. Python has no `new`, so a call is the only syntactic
+ * construction form, and a call to a plain name is the shape every other
+ * language spells `= new X()`.
+ *
+ * BARE NAMES ONLY. A dotted callee (`models.User()`, `f.Alpha()`) is refused.
+ * The first cut of #2807 returned the callee's full dotted text, on the theory
+ * that a dotted name resolves through `QualifiedNameIndex` the way the
+ * module-level `u = models.User()` capture in `query.ts` does. Measured on a
+ * fixture carrying both shapes, that arm produced no correct edge and did
+ * produce wrong ones:
+ *
+ *   - `self.svc = f.Alpha()`, where `Alpha` is a METHOD on an unrelated object
+ *     and `Alpha` is also a class elsewhere: the dotted lookup matches the
+ *     TRAILING segment against a same-named class, so `self.svc.ping()` emitted
+ *     a FABRICATED edge to `Alpha.ping`. The root does not have to be a
+ *     parameter — a module-level `shared_factory.Alpha()` fabricates the same
+ *     way — so no test on the root's binding form contains this.
+ *   - `self.u = models.User()`, the shape the arm was written FOR, emitted no
+ *     edge with the arm or without it. An instance field's binding lands in
+ *     CLASS scope, which never reaches the namespace split that makes the
+ *     module-level local form resolve.
+ *
+ * Accepted cost, stated plainly: `self.u = models.User()` still does not type
+ * its field. It did not before this narrowing either, so nothing that worked is
+ * given up — and declining to bind is the doctrine `compound-receiver.ts`
+ * states, that a confidently WRONG owner is strictly worse than a missing edge.
+ * Re-enabling dotted callees is a RESOLUTION-side change (teach the field path
+ * the namespace split that #2826/#2828 is reworking); redoing it here could
+ * only re-open the trailing-segment fabrication.
+ *
+ * This is also why the tier tie-break below can stay last-write-wins: the
+ * displacement it used to suffer — `self.conn = Outer()` then
+ * `self.conn = Registry.get()`, where the second, dotted, non-type candidate
+ * overwrote the real constructor binding at the shared weakest tier and left
+ * the field untyped — cannot arise once a dotted callee yields no candidate at
+ * all. The weakest tier now ranks only REAL constructions against each other,
+ * where the last write in `__init__` genuinely is the live one.
+ */
+function constructorCallTypeName(right, receiverName) {
+    if (right === null || right.type !== 'call')
+        return undefined;
+    const callee = right.childForFieldName('function');
+    if (callee === null)
+        return undefined;
+    // An `attribute` callee is the dotted path refused above; `self.p =
+    // self.build()` is one instance of it, and a method call is not a
+    // construction.
+    if (callee.type !== 'identifier')
+        return undefined;
+    const text = callee.text.trim();
+    if (text.length === 0)
+        return undefined;
+    // `self.p = self()` invokes the instance's own `__call__`. It is a call to a
+    // bare name, but that name is the receiver, not a type.
+    if (text === receiverName)
+        return undefined;
+    return text;
+}
+/**
+ * Synthesize class-scope field bindings for the common Python constructor
+ * injection patterns:
+ *
+ *   def __init__(self, service: Service):
+ *       self.service = service        # from the PARAMETER's annotation
+ *       self.cache: Cache = build()   # from the FIELD's own annotation
+ *       self.outer = Outer()          # from the CONSTRUCTOR called (#2807)
+ *
+ * The three tiers rank in that order — an explicit field annotation beats a
+ * parameter annotation, which beats a construction. Anything else is still
+ * refused: the receiver resolver needs positive evidence, not a name-only
+ * guess from an arbitrary RHS.
+ */
+function synthesizeConstructorFieldTypeBindings(fnNode) {
+    if (fnNode.childForFieldName('name')?.text !== '__init__')
+        return [];
+    if (findEnclosingClassDefinition(fnNode) === null)
+        return [];
+    if (hasDecorator(fnNode, 'staticmethod') || hasDecorator(fnNode, 'classmethod'))
+        return [];
+    const receiver = synthesizeReceiverTypeBinding(fnNode);
+    const receiverName = receiver?.['@type-binding.self']?.text;
+    if (receiverName === undefined)
+        return [];
+    const parameters = fnNode.childForFieldName('parameters');
+    const body = fnNode.childForFieldName('body');
+    if (parameters === null || body === null)
+        return [];
+    const parameterTypes = new Map();
+    for (let i = 0; i < parameters.namedChildCount; i++) {
+        const parameter = parameters.namedChild(i);
+        if (parameter === null)
+            continue;
+        const name = firstParameterName(parameter);
+        const annotation = parameter.childForFieldName('type');
+        if (name !== null && annotation !== null)
+            parameterTypes.set(name, annotation.text);
+    }
+    // Three evidence tiers for one field, strongest first. A later assignment of
+    // the SAME tier still wins (last write in `__init__` is the live one), but a
+    // weaker one never displaces a stronger: `self.x: Outer = make()` keeps its
+    // annotation even if a later branch does `self.x = Other()`.
+    //
+    // Same-tier last-write-wins is only sound because `constructorCallTypeName`
+    // admits nothing but real constructions into the weakest tier — see the note
+    // there on the `self.conn = Registry.get()` displacement it used to allow.
+    const TIER_EXPLICIT = 2;
+    const TIER_PARAMETER = 1;
+    const TIER_CONSTRUCTOR = 0;
+    const candidates = new Map();
+    const stack = [body];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node !== body &&
+            (node.type === 'function_definition' ||
+                node.type === 'lambda' ||
+                node.type === 'class_definition' ||
+                node.type === 'if_statement' ||
+                node.type === 'for_statement' ||
+                node.type === 'while_statement' ||
+                node.type === 'try_statement' ||
+                node.type === 'match_statement')) {
+            continue;
+        }
+        if (node.type === 'assignment') {
+            const left = node.childForFieldName('left');
+            const right = node.childForFieldName('right');
+            if (left?.type === 'attribute') {
+                const object = left.childForFieldName('object');
+                const field = left.childForFieldName('attribute');
+                if (object?.type === 'identifier' && object.text === receiverName && field !== null) {
+                    const explicitType = node.childForFieldName('type');
+                    const parameterType = right?.type === 'identifier' ? parameterTypes.get(right.text) : undefined;
+                    // `self.x = Outer()` — the type comes from the CONSTRUCTOR being
+                    // called (#2807). This is not the "arbitrary unannotated RHS" the
+                    // header warns against: a call to a name that resolves to a class is
+                    // the same positive evidence every other language reads from
+                    // `= new X()`, and without it an unannotated instance field could
+                    // never act as a call receiver at all. Weakest of the three tiers, so
+                    // an explicit annotation or a parameter annotation still wins.
+                    const constructedType = explicitType === null && parameterType === undefined
+                        ? constructorCallTypeName(right, receiverName)
+                        : undefined;
+                    const typeName = explicitType?.text ?? parameterType ?? constructedType;
+                    if (typeName !== undefined) {
+                        const explicit = explicitType !== null;
+                        const inferredFromConstructor = constructedType !== undefined;
+                        const tier = explicit
+                            ? TIER_EXPLICIT
+                            : inferredFromConstructor
+                                ? TIER_CONSTRUCTOR
+                                : TIER_PARAMETER;
+                        const existing = candidates.get(field.text);
+                        if (existing === undefined || tier >= existing.tier) {
+                            candidates.set(field.text, {
+                                tier,
+                                match: {
+                                    '@type-binding.name': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.name', field, field.text),
+                                    '@type-binding.type': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.type', explicitType ?? right ?? field, typeName),
+                                    // The marker that tells `interpretPythonTypeBinding` which
+                                    // tier this is; an explicit annotation carries neither and
+                                    // reads as `annotation`.
+                                    ...(explicit
+                                        ? {}
+                                        : inferredFromConstructor
+                                            ? {
+                                                '@type-binding.constructor': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.constructor', right ?? field, '1'),
+                                            }
+                                            : {
+                                                '@type-binding.parameter': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.parameter', right ?? field, '1'),
+                                            }),
+                                    '@type-binding.instance-field': (0, ast_helpers_js_1.syntheticCapture)('@type-binding.instance-field', node, '1'),
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // Push in reverse so the LIFO walk visits source order. That keeps Map
+        // insertion order (and therefore emitted capture order) deterministic.
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child !== null)
+                stack.push(child);
+        }
+    }
+    return [...candidates.values()].map(({ match }) => match);
+}