feat(resolution): link Python base methods to their overrides (python-override)

[JosefAschauer]

Problem

callers/impact of a Python method override miss every call that binds to the base declaration. In the #2074 repro, QdrantConnection.delete_payload_fields shows 0 callers, even though gc_typed calls it through a DocStoreConnection-typed receiver. A module global holding one of several backends (#2075) binds the same way. At runtime those calls run the override, but no static edge reaches it.

The existing interface-impl and cpp-override synthesis passes bridge this for Java, Kotlin, C#, TS/JS, Swift, Scala, Go, Rust and C++. They don't cover Python.

Fix

A pythonOverrideEdges synthesis pass (synthesizedBy: 'python-override', calls, provenance heuristic, with a label in explore output):

• Each Python override is linked from the nearest declaration of the same name up its extends chain. Python classes often inherit through a base that doesn't redeclare the method (Leaf(Mid(Base))). A branch of the walk stops at its first declaration, so an override of an override links only to its parent.

• Not dispatch, so skipped on either side:

  • class-creation hooks: __init__, __new__, __init_subclass__, __class_getitem__;
  • @staticmethod and @classmethod;
  • properties: @property, cached_property, .setter/.getter/.deleter.

  Python nodes only carry isStatic, so decorators are read from the source lines, including past comment and blank lines.

• Only real supertypes: an extends edge is followed when it was resolved through an import or its base is in the same file. A cross-file bare-name guess (exact-match / fuzzy) is not followed, whatever its confidence. Confidence reflects proximity, not whether the base was guessed.

• No per-base cap: each edge is a real nearest-declaration override, and a cap would drop some silently.

Validation

• __tests__/resolution.test.ts adds 2 cases:

  • direct override, override through a non-redeclaring intermediate base, and override of an override (nearest only);
  • no edge for a constructor, static method, class method (including one with a comment before the def) or property;
  • an unrelated same-name class is not linked, and getCallers of an override reaches the base-typed call site;
  • guessed supertypes at the repo root and under a package path are not followed; an import-resolved base and a same-file base are.

  Every rule was mutation-checked.

• npx tsc --noEmit: clean. resolution, frameworks-integration, extraction, function-ref and ui-flow-api tests: 1014 passed.

• Full suite on Linux (together with fix(resolution): resolve method values on untyped Python module globals (#2074) #2075): 5386 passed, 4 failed. The failures are environmental:

  • bundle-launcher ×2: no zip binary.
  • cli-sync ×2: the host runs Node 26, which prints the unsupported-Node banner.

• Real project (RAGFlow, 5.5k files):

  • 991 python-override edges. The samples I checked were all genuine overrides, e.g. ComponentBase._invoke → each agent tool's _invoke, and LoadConnector.load_credentials → each connector's.
  • impact of QdrantConnection.delete_payload_fields now reaches its base-typed caller.
  • Indexing time is about the same.

• Independent review (Grok): all findings fixed and pinned. Final verdict SHIP.

Not addressed

• Generic bases (class Leaf(Base[str])) produce no extends edge at extraction time, so no override edge is created. This is a pre-existing extraction gap, better handled as a separate change.
• MRO through mixins: a method that only a mixin declares isn't reached from a base-typed call. That's correct, because the call binds to the base's own declaration.

Refs #2074 (the "Related, not addressed here" part). Independent of #2075.

🤖 Generated with Claude Code