Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pyindex 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_, selectfrom sqlalchemy.ext.asyncio import AsyncSessionfrom 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_stepsfrom repowise.core.persistence.decision_graph import get_governing_decisionsfrom 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.pyindex 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.pyindex 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, Repositoryfrom 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.fixtureasync 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 centralfile ``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 — alphabeticalon 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_dbfor 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_BYassert used_by[0] == "src/zz_hub.py"- assert docs["used_by_total"] == _NOISE + 3+ assert docs["used_by_total"] == _NOISE + 1assert docs["used_by_emitted"] == _MAX_USED_BYassert 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