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.

fix(mcp): key get_context's used_by on the symbol, not on its file (#2329)

Raghav Chamadiyaaebfa0f4012b
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index b818cd76f..fcdd18040 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -18,7 +18,10 @@ from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.generation.page_selection import STALE_STATUSES
-from repowise.core.ingestion.models import NON_DEPENDENCY_EDGE_TYPES
+from repowise.core.ingestion.models import (
+ NON_DEPENDENCY_EDGE_TYPES,
+ SYMBOL_USE_EDGE_TYPES,
+)
from repowise.core.persistence.crud import get_kg_layers, get_kg_tour_steps
from repowise.core.persistence.decision_graph import get_governing_decisions
from repowise.core.persistence.models import (
@@ -63,6 +66,10 @@ from repowise.server.mcp_server.tool_risk.assessment import fix_annotation
#: or an omission. This constant only names the cut that already existed.
_MAX_USED_BY = 20
+#: Bound parameters per rank lookup. SQLite's ceiling is 999 before 3.32 and
+#: 32,766 after, and which applies depends on the libsqlite3 linked at runtime.
+_RANK_LOOKUP_CHUNK = 500
+
# Skeleton-by-default is GONE; ``include=["skeleton"]`` still serves it in full.
#
# It was introduced on the claim that "a 1,400-line file's default card costs
@@ -822,19 +829,24 @@ async def _resolve_one_target(
docs["file_summary"] = sym_page.summary or ""
if want_full_doc:
docs["documentation"] = sym_page.content
- # Used by — same requirement as ``imported_by`` above, plus the one
- # ``imported_by`` does not have: this list is cut at
- # ``_MAX_USED_BY`` and the agent never learns what fell off. Left
- # unordered, the survivors were whichever rows the table handed
- # back: on the 42-index corpus 4,743 symbol targets carry more than
- # ``_MAX_USED_BY`` users, and ranking moves the kept set on 4,447 of
- # them, a median of 7 of the 20 and up to all 20. Rank by the source
- # file's PageRank, path breaking ties. Distinct sources, because two
- # files joined by both an import and a call are one user of this
- # symbol — that is a guard, not a fix: the same corpus holds zero
- # duplicate rows, so it costs nothing and prevents nothing today.
+ # Used by: the files that use THIS symbol. Keyed on the symbol's
+ # own node id, because a ``calls`` edge is symbol-to-symbol and
+ # targets a ``path::Name``; keyed on the file path, as it was until
+ # now, it could only match edges into the whole file and answered
+ # "who imports this symbol's file" instead. Positive vocabulary
+ # rather than a negative filter, for the reason #1905 gave the
+ # sibling path in get_risk: an untyped edge must not become a use.
+ #
+ # Sources fold to their file, which keeps one row per using file and
+ # keeps this distinct from ``callers`` (symbol-grained, calls-only,
+ # opt-in). The list is cut at ``_MAX_USED_BY`` and the agent never
+ # learns what fell off, so which twenty survive is the whole of what
+ # it says: on the 42-index corpus ranking moves the kept set on
+ # 4,447 of the 4,743 targets over the cap, a median of 7 of the 20.
+ # Rank by the source file's PageRank, path breaking ties.
+ sym_node_id = getattr(sym, "symbol_id", None) or getattr(sym, "node_id", None)
res = await session.execute(
- select(GraphEdge.source_node_id, GraphNode.pagerank)
+ select(GraphEdge.source_node_id, GraphNode.file_path)
.outerjoin(
GraphNode,
(GraphNode.repository_id == GraphEdge.repository_id)
@@ -842,15 +854,33 @@ async def _resolve_one_target(
)
.where(
GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == sym.file_path,
- GraphEdge.edge_type.notin_(NON_DEPENDENCY_EDGE_TYPES),
+ GraphEdge.target_node_id == sym_node_id,
+ GraphEdge.edge_type.in_(SYMBOL_USE_EDGE_TYPES),
)
)
- best_rank: dict[str, float] = {}
- for source_node_id, pagerank in res.all():
- rank = float(pagerank or 0.0)
- if rank > best_rank.get(source_node_id, -1.0):
- best_rank[source_node_id] = rank
+ # An id the graph no longer holds still names its file, so fall
+ # back to the path half rather than dropping a real user.
+ user_files = {
+ file_path or source_node_id.split("::", 1)[0]
+ for source_node_id, file_path in res.all()
+ }
+ # A same-file caller is a real use, but naming the file already
+ # being read spends a capped row; ``callers`` has it at symbol grain.
+ user_files.discard(sym.file_path)
+ # Looked up by the folded path, not joined above: a source whose
+ # symbol node is missing has no file to join through and would rank
+ # 0.0. Chunked because this binds one parameter per using file.
+ best_rank: dict[str, float] = {p: 0.0 for p in user_files}
+ ordered = sorted(user_files)
+ for start in range(0, len(ordered), _RANK_LOOKUP_CHUNK):
+ rank_rows = await session.execute(
+ select(GraphNode.node_id, GraphNode.pagerank).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.node_id.in_(ordered[start : start + _RANK_LOOKUP_CHUNK]),
+ )
+ )
+ for node_id, pagerank in rank_rows.all():
+ best_rank[node_id] = float(pagerank or 0.0)
used_by = filter_path_list(
sorted(best_rank, key=lambda p: (-best_rank[p], p)), exclude_spec
)
diff --git a/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py b/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py
index e10e97f61..23a045a4b 100644
--- a/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py
+++ b/tests/unit/server/mcp/test_recoverable_caps_wire_contracts.py
@@ -223,9 +223,9 @@ async def test_context_used_by_and_relations_recover_in_one_bounded_query_shape(
GraphEdge(
id=f"sealed-import-{index}",
repository_id=setup_mcp,
- source_node_id=file_id,
- target_node_id="src/auth/service.py",
- edge_type="imports",
+ source_node_id=f"{file_id}::Use{index:03d}",
+ target_node_id="src/auth/service.py::AuthService",
+ edge_type="references",
imported_names_json='["AuthService"]',
created_at=_NOW,
),
diff --git a/tests/unit/server/mcp/test_used_by_ranking.py b/tests/unit/server/mcp/test_used_by_ranking.py
index a93c84ca6..c5350681b 100644
--- a/tests/unit/server/mcp/test_used_by_ranking.py
+++ b/tests/unit/server/mcp/test_used_by_ranking.py
@@ -1,14 +1,16 @@
-"""``get_context``'s ``used_by`` keeps the most central users, not the first 20.
-
-The field is cut at ``_MAX_USED_BY`` and the agent is never told what fell off,
-so which twenty survive is the whole of what this list says. Unordered, they
-were whichever rows the table handed back. On the 42-index corpus 4,743 symbol
-targets have more users than the cap and ranking moves the kept set on 4,447 of
-them, a median of 7 of the 20.
-
-The fixture is deliberately larger than the cap — this defect does not exist
-below it, and the repo's other ``used_by`` coverage runs on two edges, which is
-why nothing caught this.
+"""``get_context``'s ``used_by`` answers for the symbol, and ranks its users.
+
+Two contracts. **What the list is drawn from:** keyed on the symbol's own node
+id, so a ``calls`` edge — symbol-to-symbol, target ``path::Name`` — can appear
+in it. Keyed on the symbol's *file*, as it was until this was fixed, no call
+could ever match.
+
+**Which twenty survive:** the field is cut at ``_MAX_USED_BY`` and the agent is
+never told what fell off, so the kept set is the whole of what it says. On the
+42-index corpus ranking moves that set on 4,447 of the 4,743 targets over the
+cap. The fixture is deliberately larger than the cap, because the defect does
+not exist below it — the repo's other coverage ran on two edges, which is why
+nothing caught it.
"""
from __future__ import annotations
@@ -19,6 +21,7 @@ from repowise.core.persistence.models import GraphEdge, GraphNode, Repository
from repowise.server.mcp_server.tool_context.targets import _MAX_USED_BY, _resolve_one_target
_FILE = "src/auth/service.py"
+_SYMBOL = "src/auth/service.py::AuthService"
_NOISE = 25
@@ -29,7 +32,7 @@ async def repository(session, populated_db) -> Repository:
@pytest.fixture
async def many_users(session, populated_db) -> str:
- """``_NOISE`` peripheral importers, then one central one, added last.
+ """``_NOISE`` peripheral users, then one central one, added last.
``zz_`` is load-bearing. The first cut of this fixture called the central
file ``src/app/hub.py`` and **passed against the unranked code** — SQLite
@@ -40,6 +43,9 @@ async def many_users(session, populated_db) -> str:
the ranking can. (That also says what the old behaviour was — alphabetical
on SQLite, nothing promised on Postgres — which is not the same as random,
and is still the wrong list.)
+
+ Every edge is symbol-to-symbol, which is the shape the graph really emits;
+ the card folds each source back to its file, so the rows stay paths.
"""
rid = populated_db
for i in range(_NOISE):
@@ -66,10 +72,10 @@ async def many_users(session, populated_db) -> str:
GraphEdge(
id=f"ge-leaf-{i}",
repository_id=rid,
- source_node_id=path,
- target_node_id=_FILE,
- edge_type="imports",
- imported_names_json='["AuthService"]',
+ source_node_id=f"{path}::use_auth",
+ target_node_id=_SYMBOL,
+ edge_type="calls",
+ imported_names_json="[]",
)
)
session.add(
@@ -91,29 +97,79 @@ async def many_users(session, populated_db) -> str:
GraphEdge(
id="ge-hub",
repository_id=rid,
- source_node_id="src/zz_hub.py",
- target_node_id=_FILE,
- edge_type="imports",
- imported_names_json='["AuthService"]',
+ source_node_id="src/zz_hub.py::boot",
+ target_node_id=_SYMBOL,
+ edge_type="calls",
+ imported_names_json="[]",
)
)
await session.commit()
return rid
+async def two_users(session, populated_db) -> str:
+ """The base fixture joins these two files to ``service.py`` with ``imports``.
+
+ Those say the file was imported, not that this symbol was used, which is
+ why they no longer answer here.
+ """
+ rid = populated_db
+ for i, source in enumerate(
+ ("src/auth/middleware.py::require_login", "tests/test_service.py::test_login")
+ ):
+ session.add(
+ GraphEdge(
+ id=f"ge-user-{i}",
+ repository_id=rid,
+ source_node_id=source,
+ target_node_id=_SYMBOL,
+ edge_type="calls",
+ imported_names_json="[]",
+ )
+ )
+ await session.commit()
+ return rid
+
+
async def _card(session, repository, target: str) -> dict:
return await _resolve_one_target(
session, repository, target, None, True, exclude_spec=None, repo_root=None
)
+async def test_a_call_into_the_symbol_is_a_user(session, repository, two_users) -> None:
+ """The defect this file exists for: keyed on the file, this list held no calls.
+
+ A ``calls`` edge targets ``path::Name``, so against a bare file path the one
+ relationship the field is named for was the one it could never carry.
+ """
+ used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
+
+ assert set(used_by) == {"src/auth/middleware.py", "tests/test_service.py"}
+
+
+async def test_importing_the_file_is_not_using_the_symbol(session, repository) -> None:
+ """The base fixture's two importers must NOT appear on their own.
+
+ Nothing in the graph says they touched ``AuthService``, and answering as
+ though it did is what made this a restatement of ``imported_by``.
+ """
+ docs = (await _card(session, repository, "AuthService"))["docs"]
+
+ # Present and empty, not absent: the cap writes the key either way.
+ assert docs["used_by"] == []
+ # An empty list is only readable beside what the resolver actually bound.
+ assert "used_by_basis" in docs
+
+
async def test_the_most_central_user_survives_the_cut(session, repository, many_users) -> None:
docs = (await _card(session, repository, "AuthService"))["docs"]
used_by = docs["used_by"]
assert len(used_by) == _MAX_USED_BY
assert used_by[0] == "src/zz_hub.py"
- assert docs["used_by_total"] == _NOISE + 3
+ assert docs["used_by_total"] == _NOISE + 1
assert docs["used_by_emitted"] == _MAX_USED_BY
assert docs["used_by_reduced_reason"] == "construction_cap"
@@ -132,31 +188,41 @@ async def test_used_by_is_ordered_by_centrality(session, repository, many_users)
assert list(ranks.values()) == sorted(ranks.values(), reverse=True)
-async def test_a_user_list_under_the_cap_keeps_everything(session, repository) -> None:
- """Ranking reorders; it must not drop anyone who used to fit.
+async def test_two_symbols_in_one_file_are_one_user(
+ session, repository, two_users, populated_db
+) -> None:
+ """A guard, and now a live one: the query selects edges, the field names files.
- The base fixture has two importers of this file, which is the population
- every other test in this directory runs on.
+ Two calls from one file are one user. Before the rows were folded this could
+ not arise, because a file imported a file at most once.
"""
+ session.add(
+ GraphEdge(
+ id="ge-dup",
+ repository_id=populated_db,
+ source_node_id="src/auth/middleware.py::also_calls",
+ target_node_id=_SYMBOL,
+ edge_type="references",
+ imported_names_json="[]",
+ )
+ )
+ await session.commit()
+
used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
- assert set(used_by) == {"src/auth/middleware.py", "tests/test_service.py"}
+ assert used_by.count("src/auth/middleware.py") == 1
-async def test_one_user_joined_by_two_edge_types_is_listed_once(
+async def test_the_symbols_own_file_is_not_listed_as_its_user(
session, repository, populated_db
) -> None:
- """A guard, not a fix: the measured corpus holds no duplicate row.
-
- It exists because the query selects edges and the field names files, and
- nothing but this test states that those are different quantities.
- """
+ """A same-file caller is a real use, but naming the file being read spends a capped row."""
session.add(
GraphEdge(
- id="ge-dup",
+ id="ge-self",
repository_id=populated_db,
- source_node_id="src/auth/middleware.py",
- target_node_id=_FILE,
+ source_node_id=f"{_FILE}::login",
+ target_node_id=_SYMBOL,
edge_type="calls",
imported_names_json="[]",
)
@@ -165,4 +231,22 @@ async def test_one_user_joined_by_two_edge_types_is_listed_once(
used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
- assert used_by.count("src/auth/middleware.py") == 1
+ assert _FILE not in used_by
+
+
+async def test_ranking_survives_a_chunked_rank_lookup(
+ session, repository, many_users, monkeypatch
+) -> None:
+ """The rank lookup binds one parameter per using file, so it is chunked.
+
+ Shrinking the chunk reaches a boundary without 500 nodes. If one ever
+ dropped or reordered a file, the hub would stop leading.
+ """
+ from repowise.server.mcp_server.tool_context import targets as targets_mod
+
+ monkeypatch.setattr(targets_mod, "_RANK_LOOKUP_CHUNK", 3)
+ docs = (await _card(session, repository, "AuthService"))["docs"]
+
+ assert docs["used_by"][0] == "src/zz_hub.py"
+ assert docs["used_by_total"] == _NOISE + 1
+ assert len(docs["used_by"]) == _MAX_USED_BY