Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(graph): type a call receiver a framework decorator retyped (#1684)

Raghav Chamadiya3594ba75547b
diff --git a/packages/core/src/repowise/core/ingestion/call_resolver.py b/packages/core/src/repowise/core/ingestion/call_resolver.py
index 736136123..fea5cc1a2 100644
--- a/packages/core/src/repowise/core/ingestion/call_resolver.py
+++ b/packages/core/src/repowise/core/ingestion/call_resolver.py
@@ -32,9 +32,13 @@ from typing import Any
import structlog
from .languages.receiver_types import (
+ FRAMEWORK_DECORATOR_LANGUAGES,
IMPLICIT_FIELD_LANGUAGES,
RECEIVER_TYPE_LANGUAGES,
Declaration,
+ framework_decorated_type,
+ names_in_span,
+ scan_bindings,
scan_declarations,
types_by_class,
types_in_span,
@@ -232,8 +236,13 @@ class CallResolver:
self._symbol_spans: dict[str, dict[str, tuple[int, int]]] = {}
self._body_types: dict[tuple[str, str], dict[str, str | None]] = {}
self._field_types: dict[str, dict[str, dict[str, str | None]]] = {}
+ self._bindings: dict[str, tuple[tuple[int, str], ...]] = {}
+ self._bound_names: dict[tuple[str, str], frozenset[str]] = {}
+ # {file: {name: type}} — module-level defs a framework decorator retyped.
+ self._framework_types: dict[str, dict[str, str]] = {}
self._external_names: dict[str, frozenset[str]] = {}
self._method_name_set: frozenset[str] | None = None
+ self._framework_name_set: frozenset[str] | None = None
# Barrel re-export origins: {barrel_file: {name: origin_file}}
self._barrel_origins: dict[str, dict[str, str]] = defaultdict(dict)
@@ -1245,14 +1254,28 @@ class CallResolver:
# type". Only a name the body never mentions reaches class scope.
body_types = self._declared_types_in(file_path, caller_id, language)
type_name = body_types.get(receiver_name)
- from_field = (
- receiver_name not in body_types and language in IMPLICIT_FIELD_LANGUAGES
- )
+ unbound = receiver_name not in body_types
+ from_field = unbound and language in IMPLICIT_FIELD_LANGUAGES
if from_field:
class_id = caller_id.rpartition("::")[0]
type_name = (
self._field_types_in(file_path, language).get(class_id, {}).get(receiver_name)
)
+ # Third scope: a module-level def a framework decorator turned into an
+ # instance. Neither of the two above can see it — it is not in the body
+ # and not a field.
+ from_framework = (
+ type_name is None and unbound and language in FRAMEWORK_DECORATOR_LANGUAGES
+ )
+ if from_framework:
+ # The type lookup is a dict hit and the shadowing scan reads the
+ # whole file, so the cheap half decides first: only a receiver this
+ # scope would actually answer for is worth scanning a body for.
+ type_name = self._framework_type_of(file_path, receiver_name, language)
+ if type_name is not None and receiver_name in self._bound_names_in(
+ file_path, caller_id, language
+ ):
+ return None
if type_name is None:
return None
@@ -1260,6 +1283,8 @@ class CallResolver:
if found is None:
return None
sym_id, tier = found
+ if from_framework:
+ return self._framework_typed_call(caller_id, sym_id, tier, call.line)
if from_field:
return self._field_typed_call(caller_id, sym_id, tier, call.line)
return self._body_typed_call(caller_id, sym_id, tier, call.line)
@@ -1288,6 +1313,18 @@ class CallResolver:
return ResolvedCall(caller_id, sym_id, 0.88, line, "receiver_field_import")
return ResolvedCall(caller_id, sym_id, 0.75, line, "receiver_field_global")
+ def _framework_typed_call(
+ self, caller_id: str, sym_id: str, tier: str, line: int
+ ) -> ResolvedCall:
+ """Stamp an edge whose receiver was typed by a framework decorator."""
+ if tier == "same_file":
+ return ResolvedCall(caller_id, sym_id, 0.93, line, "receiver_framework_same_file")
+ if tier == "same_package":
+ return ResolvedCall(caller_id, sym_id, 0.90, line, "receiver_framework_same_package")
+ if tier == "import":
+ return ResolvedCall(caller_id, sym_id, 0.88, line, "receiver_framework_import")
+ return ResolvedCall(caller_id, sym_id, 0.75, line, "receiver_framework_global")
+
def _method_names(self) -> frozenset[str]:
"""Every name declared as a method of some class, built once."""
if self._method_name_set is None:
@@ -1367,6 +1404,96 @@ class CallResolver:
self._field_types[file_path] = by_class
return by_class
+ def _bound_names_in(
+ self, file_path: str, caller_id: str, language: str
+ ) -> frozenset[str]:
+ """Every name the calling body binds, however it was bound."""
+ key = (file_path, caller_id)
+ names = self._bound_names.get(key)
+ if names is None:
+ span = self._spans_for(file_path).get(caller_id)
+ if span is None:
+ names = frozenset()
+ else:
+ names = names_in_span(self._bindings_for(file_path, language), *span)
+ if len(self._bound_names) >= _BODY_TYPE_CACHE_ENTRIES:
+ self._bound_names.clear()
+ self._bound_names[key] = names
+ return names
+
+ def _bindings_for(self, file_path: str, language: str) -> tuple[tuple[int, str], ...]:
+ """Every name one file binds, scanned once however many bodies ask."""
+ found = self._bindings.get(file_path)
+ if found is None:
+ found = scan_bindings(self._text_of(file_path), language)
+ if len(self._bindings) >= _SOURCE_CACHE_FILES:
+ self._bindings.clear()
+ self._bindings[file_path] = found
+ return found
+
+ def _framework_names(self, language: str) -> frozenset[str]:
+ """Every name a framework decorator retypes anywhere in the repo."""
+ if self._framework_name_set is None:
+ found: set[str] = set()
+ for parsed in self._parsed_files.values():
+ if parsed.file_info.language != language:
+ continue
+ for symbol in parsed.symbols:
+ if (
+ symbol.kind in _FUNCTION_KINDS
+ and not symbol.parent_name
+ and framework_decorated_type(symbol.decorators, language)
+ ):
+ found.add(symbol.name)
+ self._framework_name_set = frozenset(found)
+ return self._framework_name_set
+
+ def _framework_types_in(self, file_path: str, language: str) -> dict[str, str]:
+ """``{name: type}`` for one file's module-level decorated defs."""
+ types = self._framework_types.get(file_path)
+ if types is None:
+ parsed = self._parsed_files.get(file_path)
+ types = {}
+ for symbol in parsed.symbols if parsed else ():
+ if symbol.kind not in _FUNCTION_KINDS or symbol.parent_name:
+ continue
+ type_name = framework_decorated_type(symbol.decorators, language)
+ if type_name is not None:
+ types[symbol.name] = type_name
+ # Uncapped, unlike the source-text caches: this holds names read off
+ # already-resident symbols, and is empty for all but a few files.
+ self._framework_types[file_path] = types
+ return types
+
+ def _framework_type_of(
+ self, file_path: str, receiver_name: str, language: str
+ ) -> str | None:
+ """The framework type of *receiver_name*, where this file can see it.
+
+ Declared here, or imported here by name. A decorated def in a file the
+ caller never imports is not this receiver, and reaching for it would be
+ the bare-name match this tier exists to avoid.
+ """
+ # One pass over the repo's symbols answers for every call site that
+ # names nothing decorated, which is all of them in a repo that uses no
+ # framework in the table. Without it every unresolved member call pays
+ # a per-file symbol walk and three dict lookups: 15% of django's build
+ # for a repo that gains no edge at all.
+ if receiver_name not in self._framework_names(language):
+ return None
+
+ own = self._framework_types_in(file_path, language).get(receiver_name)
+ if own is not None:
+ return own
+
+ bound = self._import_names.get(file_path, {}).get(receiver_name)
+ if bound is None or bound.startswith("external:"):
+ return None
+ binding = self._import_bindings.get(file_path, {}).get(receiver_name)
+ exported = (binding.exported_name if binding else None) or receiver_name
+ declaring = self._barrel_origins.get(bound, {}).get(exported) or bound
+ return self._framework_types_in(declaring, language).get(exported)
+
def _declarations_for(self, file_path: str, language: str) -> tuple[Declaration, ...]:
"""Every declaration in one file, scanned once however many bodies ask."""
found = self._declarations.get(file_path)
diff --git a/packages/core/src/repowise/core/ingestion/languages/receiver_types.py b/packages/core/src/repowise/core/ingestion/languages/receiver_types.py
index 6eaaf0452..1f581c3c9 100644
--- a/packages/core/src/repowise/core/ingestion/languages/receiver_types.py
+++ b/packages/core/src/repowise/core/ingestion/languages/receiver_types.py
@@ -19,8 +19,11 @@ the expensive half; ``types_in_span`` and ``types_by_class`` narrow the result
and are nearly free. Scanning per body instead would re-read every line that
two spans share, and a class body contains all of its methods'.
-Adding a language means adding its shapes to ``_LANGUAGE_PATTERNS`` and
-nothing else; a language absent from it is excluded by construction.
+Adding a language means adding its shapes to ``_LANGUAGE_PATTERNS``; a
+language absent from it is excluded by construction. Two smaller tables sit
+beside it: ``_FRAMEWORK_DECORATOR_TYPES``, for a decorator that changes what
+the symbol it wraps is, and ``_PY_BINDINGS``, which says only that a name is
+taken -- a refusal rather than a type.
"""
from __future__ import annotations
@@ -166,6 +169,104 @@ RECEIVER_TYPE_LANGUAGES = frozenset(_LANGUAGE_PATTERNS)
# answer, and consulting it could only bind a bare local name to a field.
IMPLICIT_FIELD_LANGUAGES = frozenset({"csharp", "java"})
+# A decorator that changes what the symbol it wraps *is*: `@shared_task` leaves
+# no function behind, so `add.s(...)` is a method call and `(Task, s)` a
+# checkable pair. A table, not an inference — the decorator lives in the
+# framework, which an application imports rather than vendors. Ceiling: an entry
+# earns nothing unless the repo also declares the type.
+_FRAMEWORK_DECORATOR_TYPES: dict[str, tuple[tuple[re.Pattern[str], str], ...]] = {
+ "python": (
+ # celery: `@task`, `@shared_task`, `@app.task`, `@celery.task`, bare or
+ # called with arguments. The qualifier is optional and must end in a
+ # dot, which is what keeps `@mytask` and `@task_group` out.
+ (re.compile(r"@(?:[\w.]+\.)?(?:shared_task|task)\b"), "Task"),
+ ),
+}
+
+FRAMEWORK_DECORATOR_LANGUAGES = frozenset(_FRAMEWORK_DECORATOR_TYPES)
+
+# Every shape that binds a name in a Python body, whatever its value. The
+# framework scope must refuse a name the body rebinds: `fail = signature(...)`
+# leaves `fail` a Signature, and the CapWords-only scan above cannot see it.
+# Over-matching is safe here — refusing only ever costs an edge.
+
+# A comma-separated target list: every name in `a, b[0], c.d = ...` and in
+# `for a, b in ...`. Read whole and split by the caller, so a subscript or an
+# attribute in any position cannot hide the bare names beside it.
+_TARGETS = r"[\w.\[\]]+(?:\s*,\s*[\w.\[\]]+)*"
+
+_PY_TARGET_LISTS = (
+ # An assignment, plain or augmented, at the start of a statement.
+ re.compile(
+ rf"(?m)^[ \t]*(?P<lhs>{_TARGETS})\s*(?::[^=\n]*)?"
+ r"(?:[-+*/%|&^@]|//|\*\*|>>|<<)?=(?!=)"
+ ),
+ # A `for` target, statement or comprehension.
+ re.compile(rf"\bfor\s+(?P<lhs>{_TARGETS})\s+in\b"),
+)
+
+_PY_BINDINGS = (
+ # `with ... as n`, `except ... as n`, `import x as n`.
+ re.compile(r"\bas\s+(?P<name>[a-z_]\w*)\b"),
+ re.compile(r"\b(?P<name>[a-z_]\w*)\s*:="),
+ re.compile(r"\b(?:global|nonlocal)\s+(?P<name>[a-z_]\w*)"),
+ # A parameter of any `def` or `lambda` in the span, the enclosing one
+ # included: its signature line is the first line of its own span.
+ re.compile(r"\b(?:def\s+\w+\s*\(|lambda\s+)[^)\n:]*?\b(?P<name>[a-z_]\w*)\s*(?=[,=)\n:])"),
+)
+
+# A plain `import` inside a body is deliberately absent: it names the same
+# module symbol this scope resolves against, and refusing it cost 3 correct
+# edges on celery (`from .tasks import ping`, then `ping.delay()`).
+
+_PY_IDENTIFIER = re.compile(r"^[a-z_]\w*$")
+
+
+def scan_bindings(text: str, language: str) -> tuple[tuple[int, str], ...]:
+ """Every ``(line, name)`` *text* binds, in line order."""
+ if language != "python":
+ return ()
+ cleaned = _DOCSTRING.sub(lambda m: "\n" * m.group(0).count("\n"), text)
+ cleaned = _HASH_COMMENT.sub("", cleaned)
+ starts = [0, *(newline.end() for newline in _NEWLINE.finditer(cleaned))]
+ found: set[tuple[int, str]] = set()
+
+ for pattern in _PY_TARGET_LISTS:
+ for match in pattern.finditer(cleaned):
+ line = bisect_right(starts, match.start("lhs"))
+ for target in match.group("lhs").split(","):
+ # `self.x = ...` and `d[k] = ...` bind no bare name.
+ name = target.strip()
+ if _PY_IDENTIFIER.match(name):
+ found.add((line, name))
+
+ for pattern in _PY_BINDINGS:
+ for match in pattern.finditer(cleaned):
+ found.add((bisect_right(starts, match.start("name")), match.group("name")))
+ return tuple(sorted(found))
+
+
+def names_in_span(
+ bindings: tuple[tuple[int, str], ...],
+ start_line: int,
+ end_line: int,
+) -> frozenset[str]:
+ """Every name bound inside one function body."""
+ first = bisect_left(bindings, start_line, key=lambda b: b[0])
+ return frozenset(name for line, name in bindings[first:] if line <= end_line)
+
+
+def framework_decorated_type(decorators: Iterable[str], language: str) -> str | None:
+ """The type a framework decorator turns the symbol it wraps into."""
+ entries = _FRAMEWORK_DECORATOR_TYPES.get(language)
+ if not entries:
+ return None
+ for decorator in decorators:
+ for pattern, type_name in entries:
+ if pattern.match(decorator):
+ return type_name
+ return None
+
_LANGUAGE_COMMENTS: dict[str, re.Pattern[str]] = {
"csharp": _LINE_COMMENT,
"go": _LINE_COMMENT,
diff --git a/packages/core/src/repowise/core/ingestion/models.py b/packages/core/src/repowise/core/ingestion/models.py
index 4caca4a9e..1897eb878 100644
--- a/packages/core/src/repowise/core/ingestion/models.py
+++ b/packages/core/src/repowise/core/ingestion/models.py
@@ -377,6 +377,13 @@ ResolutionOrigin = Literal[
"receiver_field_same_package", # 0.90 (JVM)
"receiver_field_import", # 0.88
"receiver_field_global", # 0.75
+ # The same four scopes once more, for a receiver a framework decorator
+ # retyped — `@shared_task def add` is a `Task`, so `add.s()` is `Task::s`.
+ # Separate because the evidence is a decorator table, not a declaration.
+ "receiver_framework_same_file", # 0.93
+ "receiver_framework_same_package", # 0.90
+ "receiver_framework_import", # 0.88
+ "receiver_framework_global", # 0.75
# 0.90 — the caller's own class does not declare the method but exactly one
# of its ancestors does. Below the two same-class origins because the walk
# compares no signature and reads no visibility, so it can reach a method
diff --git a/packages/types/src/graph.ts b/packages/types/src/graph.ts
index 0b6b6fe9b..643a5ae5c 100644
--- a/packages/types/src/graph.ts
+++ b/packages/types/src/graph.ts
@@ -267,6 +267,10 @@ export type ResolutionOrigin =
| "receiver_field_same_package"
| "receiver_field_import"
| "receiver_field_global"
+ | "receiver_framework_same_file"
+ | "receiver_framework_same_package"
+ | "receiver_framework_import"
+ | "receiver_framework_global"
| "self_inherited"
| "enclosing_inherited";
diff --git a/packages/ui/__tests__/graph/edge-provenance.test.ts b/packages/ui/__tests__/graph/edge-provenance.test.ts
index 29198c2ee..08950747d 100644
--- a/packages/ui/__tests__/graph/edge-provenance.test.ts
+++ b/packages/ui/__tests__/graph/edge-provenance.test.ts
@@ -46,6 +46,10 @@ const ALL_ORIGINS: ResolutionOrigin[] = [
"receiver_field_same_package",
"receiver_field_import",
"receiver_field_global",
+ "receiver_framework_same_file",
+ "receiver_framework_same_package",
+ "receiver_framework_import",
+ "receiver_framework_global",
"self_inherited",
"enclosing_inherited",
];
@@ -94,12 +98,13 @@ describe("originDescriptor", () => {
});
describe("isNameMatch", () => {
- it("marks exactly the four origins that rest on a name alone", () => {
+ it("marks exactly the origins that rest on a name alone", () => {
const marked = ALL_ORIGINS.filter(isNameMatch);
expect(marked.sort()).toEqual(
[
"global_unique",
"receiver_field_global",
+ "receiver_framework_global",
"receiver_global",
"receiver_typed_global",
].sort(),
diff --git a/packages/ui/src/graph/edge-provenance.ts b/packages/ui/src/graph/edge-provenance.ts
index 6088ed033..74f000d41 100644
--- a/packages/ui/src/graph/edge-provenance.ts
+++ b/packages/ui/src/graph/edge-provenance.ts
@@ -61,6 +61,11 @@ const ORIGINS = {
because: "the receiver is a field whose type is a class in this file",
tier: "direct",
},
+ receiver_framework_same_file: {
+ label: "Framework type, same file",
+ because: "a framework decorator retyped the receiver, and that class is in this file",
+ tier: "direct",
+ },
// --- scoped: an import, a package, a module, a supertype ---------------
same_package: {
@@ -128,6 +133,16 @@ const ORIGINS = {
because: "the receiver is a field whose type was found in an imported file",
tier: "scoped",
},
+ receiver_framework_same_package: {
+ label: "Framework type, same package",
+ because: "a framework decorator retyped the receiver, and that class is in the same package",
+ tier: "scoped",
+ },
+ receiver_framework_import: {
+ label: "Framework type, imported",
+ because: "a framework decorator retyped the receiver, and that class was found in an imported file",
+ tier: "scoped",
+ },
self_inherited: {
label: "Inherited",
because: "the caller's class does not declare it but one ancestor does",
@@ -155,6 +170,11 @@ const ORIGINS = {
because: "the field's type and method pair exists somewhere in the repo",
tier: "name_match",
},
+ receiver_framework_global: {
+ label: "Name match",
+ because: "the framework type and method pair exists somewhere in the repo",
+ tier: "name_match",
+ },
global_unique: {
label: "Name match",
because: "the name is unique across the repo, so nothing else could match",