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.

docs(graph): sync resolution origin vocabulary (#2400)

Tal38bf3c51f7a4
diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
index 4fb28d207..1d269d4fb 100644
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -510,14 +510,14 @@ meaning is easy to get wrong:
**Call resolution** is handled by the `CallResolver` module (`ingestion/call_resolver.py`),
which runs after the static import graph is built. Every edge it emits is stamped
-with a `ResolutionOrigin`, a closed vocabulary of 29 values in
+with a `ResolutionOrigin`, a closed vocabulary of 39 values in
`ingestion/models.py`, each carrying exactly one confidence, so the origin
distribution and the confidence histogram are two views of the same data. The
span runs from `same_file` and `self_scope` at 0.95, through import- and
package-scoped origins at 0.88–0.90, down to `global_unique` at 0.50, a
repo-wide name match, which the source comments label as a guess.
-Twelve of the 29 are **receiver-typing** origins: they resolve a call on a
+Twelve of the 39 are **receiver-typing** origins: they resolve a call on a
variable by reading the variable's declaration (a local, a parameter, an
enclosing class's field, or a type a framework decorator imposed), then resolving
the method on that type. Registered for Java, C#, Python, Go, Kotlin and Swift.
diff --git a/docs/architecture/graph-algorithms.md b/docs/architecture/graph-algorithms.md
index c8c946653..83089e97a 100644
--- a/docs/architecture/graph-algorithms.md
+++ b/docs/architecture/graph-algorithms.md
@@ -26,7 +26,7 @@ Symbol-level edges (all carry a `confidence` score from 0.0 to 1.0):
|-----------|--------|---------|
| `defines` | GraphBuilder `add_file()` | `login.py` defines `validate_token` |
| `has_method` | GraphBuilder `add_file()` | `AuthService` has_method `login` |
-| `calls` | `CallResolver` (29 named resolution origins, each with a fixed confidence) | `validate_token` calls `hash_password` |
+| `calls` | `CallResolver` (39 named resolution origins, each with a fixed confidence) | `validate_token` calls `hash_password` |
| `dispatches_to` | Heritage pass | base `Handler.run` dispatches_to `JsonHandler.run` |
| `references` | `@reference.name` captures | a dispatch table names `on_signal` without calling it |
| `framework_binds` | Framework handlers | a pytest fixture binds to the test that requests it |
diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.md
index b07f13e4b..2946ec26e 100644
--- a/docs/architecture/language-support.md
+++ b/docs/architecture/language-support.md
@@ -463,11 +463,11 @@ The tiers, highest evidence first:
| Confidence | Origins | Evidence |
|:---:|---|---|
| 0.95 | `same_file`, `self_scope`, `enclosing_class` | The callee is in this file, or on the caller's own class |
-| 0.93 | `receiver_same_file`, `receiver_typed_same_file`, `receiver_field_same_file`, `receiver_framework_same_file` | The receiver names a type declared in this file |
-| 0.90 | `same_package`, `import_scoped`, `receiver_same_package`, the three `*_same_package` typed variants, `self_inherited`, `enclosing_inherited` | A sibling file needing no import, or an explicit import |
-| 0.88 | `package_alias`, `module_alias`, `crate_root`, `receiver_import`, the three `*_import` typed variants | The receiver resolved through an imported file |
+| 0.93 | `receiver_same_file`, `receiver_typed_same_file`, `receiver_field_same_file`, `receiver_framework_same_file`, `scoped_name`, `receiver_extension_same_file`, `receiver_chain_same_file`, `return_type_same_file` | The receiver or returned type names a class in this file, every chained field stays in this file, or the call names its class directly |
+| 0.90 | `same_package`, `import_scoped`, `receiver_same_package`, `receiver_typed_same_package`, `receiver_field_same_package`, `receiver_framework_same_package`, `return_type_same_package`, `self_inherited`, `enclosing_inherited` | A sibling file needing no import, an explicit import, or one unambiguous ancestor |
+| 0.88 | `package_alias`, `module_alias`, `crate_root`, `receiver_import`, `receiver_typed_import`, `receiver_field_import`, `receiver_framework_import`, `receiver_extension_import`, `receiver_chain_import`, `return_type_import` | The receiver, chained field, returned type, or target resolved through an imported file or scoped alias |
| 0.85 | `import_merged`, `same_target` | In *some* imported file, or some sibling translation unit; which one is unattributed |
-| 0.75 | `receiver_global`, the three `*_global` typed variants | The `(class, method)` pair exists somewhere in the repo |
+| 0.75 | `receiver_global`, `receiver_typed_global`, `receiver_field_global`, `receiver_framework_global`, `receiver_extension_global`, `return_type_global` | The `(class, method)` pair exists somewhere in the repo |
| 0.50 | `global_unique` | The name is unique repo-wide. **A guess** |
The typed variants come in three parallel families of four, one per *scope*,
diff --git a/docs/layers/GRAPH.md b/docs/layers/GRAPH.md
index bc225479b..fc62bfb9a 100644
--- a/docs/layers/GRAPH.md
+++ b/docs/layers/GRAPH.md
@@ -10,7 +10,7 @@ that **every edge carries its own evidence**.
<p>
<img src="https://img.shields.io/badge/17-edge_types-3178C6?style=flat-square&labelColor=0A0A0A" alt="17 edge types" />
- <img src="https://img.shields.io/badge/29-resolution_origins-059669?style=flat-square&labelColor=0A0A0A" alt="29 resolution origins" />
+ <img src="https://img.shields.io/badge/39-resolution_origins-059669?style=flat-square&labelColor=0A0A0A" alt="39 resolution origins" />
<img src="https://img.shields.io/badge/26-languages-F59520?style=flat-square&labelColor=0A0A0A" alt="26 languages" />
<img src="https://img.shields.io/badge/22-framework_detectors-7F52FF?style=flat-square&labelColor=0A0A0A" alt="22 framework detectors" />
<img src="https://img.shields.io/badge/0-LLM_calls-1E293B?style=flat-square&labelColor=0A0A0A" alt="zero LLM calls" />
@@ -92,7 +92,7 @@ the call was there.
**Stage two: resolution.** Given a captured site, work out what the name points
at. `repo.save(draft)` hands you the name `save` and a receiver spelled `repo`,
and the job is to turn that into one declaration in one file. This is where the
-29 origins below live, and it is the `user.save()` problem from the section
+39 origins below live, and it is the `user.save()` problem from the section
above.
| | fails when | costs you | how you find out |
@@ -243,7 +243,7 @@ filter, and two of them silently counted co-change edges as imports.
## Every edge says how it got there
Each `calls` edge is stamped with a **resolution origin**: the named strategy
-that produced it. There are 29, drawn from a closed vocabulary, and each one
+that produced it. There are 39, drawn from a closed vocabulary, and each one
carries exactly one confidence.
| Confidence | Origin | What was actually established |
@@ -273,7 +273,7 @@ call site.
## Typing the receiver
-Twelve of the 29 origins exist to answer the `user.save()` question properly.
+Twelve of the 39 origins exist to answer the `user.save()` question properly.
Rather than matching a bare method name, repowise reads the receiver's
**declaration** and resolves the method on that type.
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 7cbc47851..2e430ee41 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -47,7 +47,7 @@ and symbol nodes (functions, classes, methods). 26 languages parse to a full
AST; see [`LANGUAGE_SUPPORT.md`](LANGUAGE_SUPPORT.md) for per-language tiers.
A **confidence-scored call resolver** handles import aliases, barrel
-re-exports and namespace imports. Every `calls` edge is stamped with one of 29
+re-exports and namespace imports. Every `calls` edge is stamped with one of 39
named resolution origins (`ResolutionOrigin` in `ingestion/models.py`), each
carrying a fixed confidence from 0.95 (`same_file`) down to 0.50
(`global_unique`, a repo-wide name match, labelled as the guess it is). That
diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.md
index d83b88511..9d2654887 100644
--- a/docs/layers/LANGUAGE_SUPPORT.md
+++ b/docs/layers/LANGUAGE_SUPPORT.md
@@ -132,12 +132,45 @@ vocabulary, and every origin has exactly one confidence:
|--------|:---:|---|
| `same_file` | 0.95 | Defined in the calling file. A certainty |
| `self_scope` | 0.95 | `self` / `this`, a method on the caller's own class |
+| `enclosing_class` | 0.95 | A bare call bound to the caller's own class |
+| `receiver_same_file` | 0.93 | The receiver names a class in the calling file |
+| `receiver_typed_same_file` | 0.93 | The receiver's declared type is a class in this file |
+| `receiver_field_same_file` | 0.93 | The receiver is a field whose type is a class in this file |
+| `receiver_framework_same_file` | 0.93 | A framework decorator retyped the receiver to a class in this file |
+| `scoped_name` | 0.93 | The call names its class directly, and that class declares the method |
+| `receiver_extension_same_file` | 0.93 | An extension method in this file extends the receiver's type |
+| `receiver_chain_same_file` | 0.93 | Every hop of a chained field receiver resolves within this file |
+| `return_type_same_file` | 0.93 | The inner call's declared return type is a class in this file |
+| `same_package` | 0.90 | The target is in a sibling file that needs no import |
| `import_scoped` | 0.90 | The name was imported from the file that defines it |
+| `receiver_same_package` | 0.90 | The receiver is a class in the same package |
+| `receiver_typed_same_package` | 0.90 | The receiver's declared type is a class in the same package |
+| `receiver_field_same_package` | 0.90 | The receiver is a field whose type is a class in the same package |
+| `receiver_framework_same_package` | 0.90 | A framework decorator retyped the receiver to a class in the same package |
+| `return_type_same_package` | 0.90 | The inner call's declared return type is a class in the same package |
+| `self_inherited` | 0.90 | `self` / `this` names a method declared by one ancestor |
+| `enclosing_inherited` | 0.90 | A bare call names a method declared by one ancestor |
+| `package_alias` | 0.88 | The call is qualified by a package the repo declares |
+| `module_alias` | 0.88 | The receiver is an imported module |
+| `crate_root` | 0.88 | The reference is scoped to its Rust crate |
+| `receiver_import` | 0.88 | The receiver's class was found in an imported file |
| `receiver_typed_import` | 0.88 | The receiver's type was read off its declaration, then found in an imported file |
+| `receiver_field_import` | 0.88 | The receiver is a field whose type was found in an imported file |
+| `receiver_framework_import` | 0.88 | A framework decorator retyped the receiver to a class in an imported file |
+| `receiver_extension_import` | 0.88 | An imported file extends the receiver's type with this method |
+| `receiver_chain_import` | 0.88 | A chained field receiver resolves through an imported type at its weakest hop |
+| `return_type_import` | 0.88 | The inner call's declared return type was found in an imported file |
+| `import_merged` | 0.85 | The name is in one of the imported files, but the file is unattributed |
+| `same_target` | 0.85 | The target is a sibling translation unit in the same build target |
| `receiver_global` | 0.75 | The `(class, method)` pair exists *somewhere* in the repo |
+| `receiver_typed_global` | 0.75 | The inferred type and method pair exists somewhere in the repo |
+| `receiver_field_global` | 0.75 | The field's type and method pair exists somewhere in the repo |
+| `receiver_framework_global` | 0.75 | The framework type and method pair exists somewhere in the repo |
+| `receiver_extension_global` | 0.75 | One extension method in the repo extends this type with this name |
+| `return_type_global` | 0.75 | The returned type and method pair exists somewhere in the repo |
| `global_unique` | 0.50 | The name is unique repo-wide. **A guess, and labelled as one** |
-That is six of 29. You can filter a graph by confidence, and both
+That is the complete vocabulary of 39. You can filter a graph by confidence, and both
the MCP tools and the web UI surface which origin produced an edge, so an agent
reading an execution flow can tell a fact from an inference instead of treating
both as source.
diff --git a/tests/unit/ingestion/test_edge_type_vocabulary.py b/tests/unit/ingestion/test_edge_type_vocabulary.py
index fd337423a..e4bbb17ef 100644
--- a/tests/unit/ingestion/test_edge_type_vocabulary.py
+++ b/tests/unit/ingestion/test_edge_type_vocabulary.py
@@ -38,6 +38,7 @@ from __future__ import annotations
import ast
import pathlib
+import re
import pytest
@@ -406,6 +407,31 @@ def test_each_resolution_origin_carries_one_confidence() -> None:
)
+def test_graph_docs_origin_badge_matches_vocabulary() -> None:
+ from repowise.core.ingestion.models import RESOLUTION_ORIGIN_VALUES
+
+ root = pathlib.Path(__file__).resolve().parents[3]
+ graph_doc = (root / "docs/layers/GRAPH.md").read_text(encoding="utf-8")
+ match = re.search(r"badge/(\d+)-resolution_origins-", graph_doc)
+
+ assert match is not None, "GRAPH.md resolution-origin badge is missing"
+ assert int(match.group(1)) == len(RESOLUTION_ORIGIN_VALUES)
+
+
+def test_language_support_origin_table_matches_vocabulary() -> None:
+ from repowise.core.ingestion.models import RESOLUTION_ORIGIN_VALUES
+
+ root = pathlib.Path(__file__).resolve().parents[3]
+ text = (root / "docs/layers/LANGUAGE_SUPPORT.md").read_text(encoding="utf-8")
+ section = text.split("### Every call edge says how it was resolved", 1)[1]
+ table, remainder = section.split("That is the complete vocabulary of ", 1)
+ names = re.findall(r"^\| `([a-z_]+)` \|", table, re.MULTILINE)
+
+ assert len(names) == len(set(names)), "origin table has duplicate rows"
+ assert set(names) == RESOLUTION_ORIGIN_VALUES
+ assert int(remainder.split(".", 1)[0]) == len(RESOLUTION_ORIGIN_VALUES)
+
+
@pytest.mark.parametrize("phantom", ["has_property", "method_overrides", "dynamic"])
def test_the_removed_phantoms_stay_removed(phantom: str) -> None:
"""Each measured at 0 rows across 42 local indexes with no producer in the tree.