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.

refactor: rank the displayed lists before cutting them (#1590)

Swati Ahujad56c9b4e7019
diff --git a/packages/core/src/repowise/core/analysis/pr_blast.py b/packages/core/src/repowise/core/analysis/pr_blast.py
index 2031d3217..0c02edd58 100644
--- a/packages/core/src/repowise/core/analysis/pr_blast.py
+++ b/packages/core/src/repowise/core/analysis/pr_blast.py
@@ -55,7 +55,14 @@ class PRBlastRadiusAnalyzer:
# 2. Transitive affected files
transitive_affected = await self._transitive_affected(changed_files, max_depth)
- all_affected_paths = list(changed_set | {e["path"] for e in transitive_affected})
+ # Sorted, because this list is cut before it is shown. ``test_gaps``
+ # preserves this order and ``get_risk``'s PR directive renders three of
+ # it as ``missing_tests``, the third line an agent is told to read.
+ # A bare set union is hash-ordered, so which three appeared varied
+ # between processes on identical input. The scale is a PR's own changed
+ # files, not the whole affected set — ``directives`` filters to those
+ # before cutting — so this is a handful of paths, reported stably.
+ all_affected_paths = sorted(changed_set | {e["path"] for e in transitive_affected})
# 3. Co-change warnings
cochange_warnings = await self._cochange_warnings(changed_files, changed_set)
@@ -155,7 +162,13 @@ class PRBlastRadiusAnalyzer:
:meth:`_cochange_warnings`.
"""
visited: dict[str, int] = {} # path -> depth at which it was first reached
- frontier = list(set(changed_files))
+ # Sorted, not just deduped. This walk's output is cut twice downstream
+ # — ``will_break`` takes 15 of it, and that is the first field
+ # ``get_risk``'s PR directive tells an agent to read — so the order
+ # inside a depth band decides what an agent is shown. A hash-ordered
+ # seed plus an unordered ``SELECT DISTINCT`` made that order vary
+ # between processes on identical input.
+ frontier = sorted(set(changed_files))
for depth in range(1, max_depth + 1):
if not frontier:
@@ -182,7 +195,12 @@ class PRBlastRadiusAnalyzer:
next_frontier.append(src)
frontier = next_frontier
- return [{"path": p, "depth": d} for p, d in sorted(visited.items(), key=lambda x: x[1])]
+ # Depth first, then path: a sort on depth alone is stable, so files
+ # sharing a depth kept the row order the query happened to return.
+ return [
+ {"path": p, "depth": d}
+ for p, d in sorted(visited.items(), key=lambda item: (item[1], item[0]))
+ ]
async def _cochange_warnings(
self, changed_files: list[str], changed_set: set[str]
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index c75d835bd..e2bffafa0 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -60,6 +60,11 @@ _MAX_TOP_FILES = 20
# public surface.
_MAX_CONCEPT_ROWS = 40
+# The module page's "Class hierarchy" section: how many classes it shows, and
+# how many any one file may contribute so a single dense file cannot fill it.
+_MAX_KEY_CLASSES = 10
+_MAX_CLASSES_PER_FILE = 5
+
# Identifier word splits: a snake_case underscore, or the boundary before a
# capital that starts a new word. The second pattern keeps acronym runs whole —
# ``HTTPAdapter`` is two words, not nine — which matters because the acronym is
@@ -541,12 +546,22 @@ class ContextAssembler:
{"name": name, "file_count": count} for name, count in owner_counts.most_common(3)
]
- # Key classes: collect classes with heritage info from file contexts
+ # Key classes: the classes with heritage info, most central file first.
+ # ``module_page.j2`` renders this under a "Class hierarchy" heading, so
+ # the ten it keeps are the ten a reader is told matter. Taking them in
+ # ``file_contexts`` order meant the first two files with classes filled
+ # the list and every later file contributed nothing, whatever was in
+ # it. The rank is the file's PageRank — the same key ``key_files`` uses
+ # a few lines up, so one module page cannot call two files its most
+ # important — with the path breaking ties, since leaf files share a
+ # PageRank in bulk. Each file's own entries arrive already ranked by
+ # ``extract_heritage``; the per-file cap stays so one dense file cannot
+ # take every slot.
key_classes: list[dict] = []
- for fc in file_contexts:
- for h in fc.heritage[:5]: # cap per file
+ for fc in sorted(file_contexts, key=lambda fc: (-fc.pagerank_score, fc.file_path)):
+ for h in fc.heritage[:_MAX_CLASSES_PER_FILE]:
key_classes.append(h)
- key_classes = key_classes[:10] # cap total
+ key_classes = key_classes[:_MAX_KEY_CLASSES]
# Where the page's files actually live: the directories that hold one
# directly, not every ancestor of every file, so the list reads as the
diff --git a/packages/core/src/repowise/core/generation/context/graph_intelligence.py b/packages/core/src/repowise/core/generation/context/graph_intelligence.py
index a9e69af52..1d2db2f3a 100644
--- a/packages/core/src/repowise/core/generation/context/graph_intelligence.py
+++ b/packages/core/src/repowise/core/generation/context/graph_intelligence.py
@@ -8,6 +8,11 @@ from __future__ import annotations
from typing import Any
+#: How many entries each extractor returns. Both were bare literals at the
+#: ``return``; naming them lets a caller and a test say which cut it means.
+MAX_CALL_ENTRIES = 15
+MAX_HERITAGE_ENTRIES = 10
+
def build_symbol_index(graph: Any) -> dict[str, list[tuple[Any, dict]]]:
"""Bucket symbol nodes by ``file_path`` in one pass over the graph.
@@ -16,7 +21,10 @@ def build_symbol_index(graph: Any) -> dict[str, list[tuple[Any, dict]]]:
graph node per file — O(files x nodes) across a generation run. Callers
that assemble context for many files build this index once and pass it
in; per-file extraction becomes a dict lookup. Buckets preserve the
- graph's node iteration order, so results are byte-identical to the scan.
+ graph's node iteration order, so results are byte-identical to the scan —
+ and that is still the reason, not the ranking the extractors now apply:
+ neither sort key is total (heritage ignores ``kind``, the call dedup
+ collapses on names alone), so ties fall back to input order.
"""
index: dict[str, list[tuple[Any, dict]]] = {}
try:
@@ -80,7 +88,19 @@ def extract_call_graph(
)
except Exception:
pass
- # Deduplicate and cap
+ # Rank, then deduplicate, then cap. The cut used to keep whichever 15 the
+ # graph happened to yield first, so a file's most confident call edges
+ # could be dropped in favour of arbitrary ones. ``confidence`` is already
+ # on every entry — it is the resolver's own certainty that this call is
+ # real — so the entries it is least sure about are the ones to lose.
+ # Ranking before the dedup also means a pair kept once is kept at its
+ # highest confidence rather than at whichever copy came first.
+ #
+ # Worth knowing before this is quoted as a user-facing fix: the caller
+ # stores this on ``FilePageContext.call_graph``, and **no template, prompt
+ # or reader consumes that field**. This is one line on the module's public
+ # surface, not a change anyone can see today.
+ entries.sort(key=lambda e: (-float(e.get("confidence") or 0.0), e["caller"], e["callee"]))
seen: set[str] = set()
unique: list[dict] = []
for e in entries:
@@ -88,7 +108,7 @@ def extract_call_graph(
if key not in seen:
seen.add(key)
unique.append(e)
- return unique[:15]
+ return unique[:MAX_CALL_ENTRIES]
def extract_heritage(
@@ -98,6 +118,12 @@ def extract_heritage(
) -> list[dict]:
"""Extract extends/implements edges for symbols in this file."""
entries: list[dict] = []
+ # Parallel to ``entries``: the confidence this cut ranks on. Kept beside
+ # the dicts rather than inside them because no caller reads it — the
+ # module page ranks these by the *file's* PageRank when it merges several
+ # files' lists — and a key nothing consumes is a key someone later has to
+ # work out the purpose of.
+ scores: list[float] = []
try:
for node, data in _file_symbol_nodes(file_path, graph, symbol_index):
for _, target, edata in graph.out_edges(node, data=True):
@@ -112,6 +138,7 @@ def extract_heritage(
"parent_file": tdata.get("file_path", ""),
}
)
+ scores.append(float(edata.get("confidence") or 0.0))
for source, _, edata in graph.in_edges(node, data=True):
etype = edata.get("edge_type", "")
if etype in ("extends", "implements"):
@@ -124,9 +151,21 @@ def extract_heritage(
"child_file": sdata.get("file_path", ""),
}
)
+ scores.append(float(edata.get("confidence") or 0.0))
except Exception:
pass
- return entries[:10]
+ # Same cut as ``extract_call_graph``, same reason to rank it. The resolver
+ # scores an inheritance edge it matched inside the file well above one it
+ # guessed from a bare name — across the corpus ``extends`` carries 6,726
+ # edges at 0.5 against 5,135 at 0.95 — so the guesses are what a full list
+ # should lose. Names break ties, which ``kind`` deliberately does not join:
+ # two entries alike in confidence, child and parent are the same
+ # relationship reported from both ends.
+ ranked = sorted(
+ zip(scores, entries, strict=True),
+ key=lambda pair: (-pair[0], pair[1]["child"], pair[1]["parent"]),
+ )
+ return [entry for _score, entry in ranked[:MAX_HERITAGE_ENTRIES]]
def extract_community_meta(file_path: str, graph: Any) -> tuple[str, float]:
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/active_landscape.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/active_landscape.py
index 14919b048..ea112fe96 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/active_landscape.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/active_landscape.py
@@ -93,10 +93,10 @@ def _build(signals: OnboardingSignals) -> ActiveLandscapeContext | None:
for path, meta in git_meta_map.items()
if int(meta.get("commit_count_90d", 0) or 0) > 0
]
- hot_files_all.sort(
- key=lambda h: (h.commit_count_90d, -h.age_days),
- reverse=True,
- )
+ # Path last, so the key is total. Files tied on both churn and age fell
+ # back to ``git_meta_map`` insertion order, and this list is cut twice —
+ # at ``_TOP_HOT_FILES`` here and at 15 after the dead-code walk below.
+ hot_files_all.sort(key=lambda h: (-h.commit_count_90d, h.age_days, h.path))
hot_files = hot_files_all[:_TOP_HOT_FILES]
# Roll up to directories.
@@ -125,11 +125,16 @@ def _build(signals: OnboardingSignals) -> ActiveLandscapeContext | None:
# Dead-code findings inside the top hot files only — keeps the prompt
# focused on actionable, recent overlap rather than the full report.
- hot_paths = {h.path for h in hot_files}
+ # Walked in ``hot_files`` order — the churn ranking computed above — because
+ # this list is cut to 15 below. Collecting through a ``set`` of the paths
+ # replaced that ranking with a hash order, so the fifteen findings the page
+ # kept were fifteen arbitrary ones of the hot set rather than the fifteen
+ # in the files moving most, and a second process could keep a different
+ # fifteen from identical data.
dead_code_in_hot: list[dict] = []
- for path in hot_paths:
- for finding in signals.dead_code_by_file.get(path, []):
- dead_code_in_hot.append({"file_path": path, **finding})
+ for hot in hot_files:
+ for finding in signals.dead_code_by_file.get(hot.path, []):
+ dead_code_in_hot.append({"file_path": hot.path, **finding})
stable_file_count = sum(
1 for meta in git_meta_map.values() if bool(meta.get("is_stable", False))
diff --git a/packages/core/src/repowise/core/persistence/crud/graph.py b/packages/core/src/repowise/core/persistence/crud/graph.py
index de339985a..8d826f06e 100644
--- a/packages/core/src/repowise/core/persistence/crud/graph.py
+++ b/packages/core/src/repowise/core/persistence/crud/graph.py
@@ -559,7 +559,36 @@ async def get_graph_edges_for_node(
edge_types:
Optional filter, e.g. ``["calls"]`` or ``["extends", "implements"]``.
limit:
- Max edges per direction.
+ Max edges per direction. **The cut is ranked**: rows come back most
+ confident first, ties broken on the other endpoint's id. Without an
+ ``ORDER BY`` the survivors were whichever rows the table handed over,
+ so a node with more adjacent edges than *limit* could return its
+ containment rows and none of its real calls — the failure
+ ``routers/files.py`` documents at its own call site rather than fixing
+ here. What the consumers do afterwards is the argument for ranking at
+ this end: ``mcp_server/_graph_utils`` and ``tool_symbol`` drop anything
+ below 0.5, so an unranked cut can hand them 50 rows and leave them
+ nothing; and ``routers/symbols`` and ``routers/graph/intelligence``
+ **sort by confidence after** the cut, which presented a
+ confident-looking order over an arbitrary subset — ranking was already
+ the contract there, applied one step too late.
+
+ On SQLite the unranked form was not arbitrary in practice: the rows
+ arrive in index order, which is stable but is promised by no query
+ planner and by no other backend. Deterministic, and still the wrong
+ rows.
+
+ **It costs something, on one direction only.** ``graph_edges`` is
+ indexed on ``(repository_id, source_node_id, target_node_id,
+ edge_type)``, so the *callees* branch seeks and then sorts a narrow
+ match set, while the *callers* branch filters on ``target_node_id``,
+ which that index cannot serve — it scanned before and now also builds a
+ temp b-tree, losing the early exit the bare ``LIMIT`` gave it. Measured
+ on django's 120k-edge index: the hottest node (1,525 inbound edges)
+ goes 10.9 ms to 38.2 ms; a low-degree node is unchanged at ~37 ms
+ because it was already scanning. The fix is an index on
+ ``(repository_id, target_node_id)``, which is a migration and is not
+ this change.
"""
results: list[GraphEdge] = []
@@ -570,7 +599,9 @@ async def get_graph_edges_for_node(
)
if edge_types:
q = q.where(GraphEdge.edge_type.in_(edge_types))
- q = q.limit(limit)
+ q = q.order_by(
+ GraphEdge.confidence.desc(), GraphEdge.source_node_id, GraphEdge.edge_type
+ ).limit(limit)
res = await session.execute(q)
results.extend(res.scalars().all())
@@ -581,7 +612,9 @@ async def get_graph_edges_for_node(
)
if edge_types:
q = q.where(GraphEdge.edge_type.in_(edge_types))
- q = q.limit(limit)
+ q = q.order_by(
+ GraphEdge.confidence.desc(), GraphEdge.target_node_id, GraphEdge.edge_type
+ ).limit(limit)
res = await session.execute(q)
results.extend(res.scalars().all())
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 90c1cad70..5e1807055 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
@@ -54,6 +54,12 @@ from repowise.server.mcp_server.tool_context.kg import (
)
from repowise.server.mcp_server.tool_risk.assessment import fix_annotation
+#: How many users of a symbol the card carries. The asymmetry is recorded, not
+#: explained: the sibling ``imported_by`` on a file target carries no cap at
+#: all, and nothing in the code or its history says whether that is a decision
+#: or an omission. This constant only names the cut that already existed.
+_MAX_USED_BY = 20
+
# 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
@@ -787,16 +793,38 @@ 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.
+ # 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.
res = await session.execute(
- select(GraphEdge).where(
+ select(GraphEdge.source_node_id, GraphNode.pagerank)
+ .outerjoin(
+ GraphNode,
+ (GraphNode.repository_id == GraphEdge.repository_id)
+ & (GraphNode.node_id == GraphEdge.source_node_id),
+ )
+ .where(
GraphEdge.repository_id == repo_id,
GraphEdge.target_node_id == sym.file_path,
GraphEdge.edge_type.notin_(NON_DEPENDENCY_EDGE_TYPES),
)
)
- edges = res.scalars().all()
- docs["used_by"] = filter_path_list([e.source_node_id for e in edges], exclude_spec)[:20]
+ 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
+ docs["used_by"] = filter_path_list(
+ sorted(best_rank, key=lambda p: (-best_rank[p], p)), exclude_spec
+ )[:_MAX_USED_BY]
# Candidates
if len(sym_matches) > 1: # type: ignore[possibly-undefined]
docs["candidates"] = filter_dicts_by_key(
diff --git a/packages/server/src/repowise/server/routers/files.py b/packages/server/src/repowise/server/routers/files.py
index 8fcd9e210..ccd65676c 100644
--- a/packages/server/src/repowise/server/routers/files.py
+++ b/packages/server/src/repowise/server/routers/files.py
@@ -292,9 +292,17 @@ async def file_detail(
meta = parse_community_meta(node)
# Dependencies only. Unfiltered, this served the file's own `defines`
# edges as "dependencies", so a file depended on its own functions —
- # and since the limit is per direction and the query has no ORDER BY,
- # a file with more symbols than the limit could return containment
- # rows and none of its real imports.
+ # and since the limit is per direction, a file with more symbols than
+ # the limit could return containment rows and none of its real
+ # imports. The type filter is what fixed that; the ranked cut inside
+ # ``get_graph_edges_for_node`` is what keeps the rows it returns —
+ # 40 per direction, so up to 80 — from being an arbitrary window.
+ # Both halves are then shown 20 at a time in that order. Most of what
+ # the ranking buys *here* is determinism rather than importance: 97.5%
+ # of the edge types this filter admits carry confidence 1.0, so on the
+ # 2,271 over-cap nodes in the corpus where the kept set moves, only
+ # 23% move because of confidence and the rest because of the path
+ # tiebreak.
edges = await crud.get_graph_edges_for_node(
session,
repo_id,
diff --git a/tests/unit/generation/test_ranked_truncation.py b/tests/unit/generation/test_ranked_truncation.py
new file mode 100644
index 000000000..1e7222172
--- /dev/null
+++ b/tests/unit/generation/test_ranked_truncation.py
@@ -0,0 +1,203 @@
+"""The four displayed lists that are cut to a fixed length are ranked first.
+
+Every assertion here is over a population **larger than the cap**, because
+that is the only regime where the defect exists: below the cap a list is
+complete whatever order it is in, and a test built on three items would pass
+against the unranked code it was written to outlaw. The fixtures are
+deliberately built so the item that must survive is the one the old
+iteration-order cut would have dropped — inserted last, so a first-N-encountered
+cut cannot keep it by accident.
+
+The architectural half — "nobody adds a fifth unranked slice" — is
+``tests/unit/test_no_unranked_truncation.py``.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+import pytest
+
+from repowise.core.generation.context.graph_intelligence import (
+ MAX_CALL_ENTRIES,
+ MAX_HERITAGE_ENTRIES,
+ build_symbol_index,
+ extract_call_graph,
+ extract_heritage,
+)
+
+
+def _graph_with_calls(n: int, *, target_file: str = "src/hub.py") -> nx.DiGraph:
+ """One file whose symbol is called by *n* others, weakest callers first.
+
+ The single high-confidence caller is added **last**, so it is outside any
+ prefix of the insertion order that the cap would have kept.
+ """
+ graph = nx.DiGraph()
+ graph.add_node(
+ f"{target_file}::hub",
+ node_type="symbol",
+ file_path=target_file,
+ name="hub",
+ kind="function",
+ )
+ for i in range(n):
+ caller = f"src/weak{i:03d}.py::caller{i:03d}"
+ graph.add_node(
+ caller,
+ node_type="symbol",
+ file_path=f"src/weak{i:03d}.py",
+ name=f"caller{i:03d}",
+ kind="function",
+ )
+ graph.add_edge(caller, f"{target_file}::hub", edge_type="calls", confidence=0.5)
+ graph.add_node(
+ "src/strong.py::the_real_caller",
+ node_type="symbol",
+ file_path="src/strong.py",
+ name="the_real_caller",
+ kind="function",
+ )
+ graph.add_edge(
+ "src/strong.py::the_real_caller",
+ f"{target_file}::hub",
+ edge_type="calls",
+ confidence=0.95,
+ )
+ return graph
+
+
+def test_the_most_confident_call_survives_the_cut() -> None:
+ graph = _graph_with_calls(MAX_CALL_ENTRIES + 10)
+
+ entries = extract_call_graph("src/hub.py", graph)
+
+ assert len(entries) == MAX_CALL_ENTRIES
+ assert "the_real_caller" in {e["caller"] for e in entries}
+ assert [e["confidence"] for e in entries] == sorted(
+ (e["confidence"] for e in entries), reverse=True
+ )
+
+
+def test_a_call_list_under_the_cap_keeps_every_entry() -> None:
+ """Ranking reorders; it must not drop anything that used to fit."""
+ graph = _graph_with_calls(3)
+
+ entries = extract_call_graph("src/hub.py", graph)
+
+ assert len(entries) == 4
+ assert "the_real_caller" in {e["caller"] for e in entries}
+
+
+def test_the_call_cut_is_the_same_from_either_extraction_path() -> None:
+ """``test_symbol_index.py`` asserts this too, on a graph below the cap.
+
+ Kept because the interesting regime is above it: the index and the scan
+ now agree on which 15 survive, not merely on a list short enough that no
+ cut happened.
+ """
+ graph = _graph_with_calls(MAX_CALL_ENTRIES + 10)
+
+ assert extract_call_graph("src/hub.py", graph, build_symbol_index(graph)) == (
+ extract_call_graph("src/hub.py", graph)
+ )
+
+
+def _graph_with_heritage(n: int, *, target_file: str = "src/base.py") -> nx.DiGraph:
+ """*n* guessed subclasses of one base, plus one resolved subclass, last."""
+ graph = nx.DiGraph()
+ graph.add_node(
+ f"{target_file}::Base",
+ node_type="symbol",
+ file_path=target_file,
+ name="Base",
+ kind="class",
+ )
+ for i in range(n):
+ child = f"src/guess{i:03d}.py::Guess{i:03d}"
+ graph.add_node(
+ child,
+ node_type="symbol",
+ file_path=f"src/guess{i:03d}.py",
+ name=f"Guess{i:03d}",
+ kind="class",
+ )
+ graph.add_edge(child, f"{target_file}::Base", edge_type="extends", confidence=0.5)
+ graph.add_node(
+ "src/real.py::ResolvedChild",
+ node_type="symbol",
+ file_path="src/real.py",
+ name="ResolvedChild",
+ kind="class",
+ )
+ graph.add_edge(
+ "src/real.py::ResolvedChild",
+ f"{target_file}::Base",
+ edge_type="extends",
+ confidence=0.95,
+ )
+ return graph
+
+
+def test_the_resolved_subclass_survives_the_heritage_cut() -> None:
+ graph = _graph_with_heritage(MAX_HERITAGE_ENTRIES + 10)
+
+ entries = extract_heritage("src/base.py", graph)
+
+ assert len(entries) == MAX_HERITAGE_ENTRIES
+ # First, not merely present: the score is not on the entry to assert on,
+ # so position is what says the ranking ran. Every other edge in the
+ # fixture is a 0.5 guess, and this one is the 0.95 resolution.
+ assert entries[0]["child"] == "ResolvedChild"
+
+
+def test_heritage_entries_do_not_carry_the_score_they_were_ranked_on() -> None:
+ """The rank is internal, and the entry shape is unchanged by this phase.
+
+ A first cut put ``confidence`` on the returned dicts and justified it as
+ "the caller re-ranks these" — the caller (``assemble_module_page``) ranks
+ by the *file's* PageRank and never reads it, and nothing else in
+ ``packages/`` does either. Pinned so the speculative key does not return.
+ """
+ graph = _graph_with_heritage(2)
+
+ entries = extract_heritage("src/base.py", graph)
+ assert entries
+ for entry in entries:
+ assert set(entry) <= {"child", "parent", "kind", "parent_file", "child_file"}
+
+
+def test_equal_confidence_is_broken_deterministically_not_by_graph_order() -> None:
+ """Same edges, opposite insertion order, same answer.
+
+ ``tests/integration/test_generation_determinism.py`` builds a repo twice
+ with the graph reversed for this reason; below the page level it is this
+ tiebreak that has to hold.
+ """
+ pairs = [(f"src/m{i}.py::C{i}", f"C{i}") for i in range(MAX_HERITAGE_ENTRIES + 5)]
+
+ def build(order: list[tuple[str, str]]) -> list[dict]:
+ graph = nx.DiGraph()
+ graph.add_node(
+ "src/base.py::Base",
+ node_type="symbol",
+ file_path="src/base.py",
+ name="Base",
+ kind="class",
+ )
+ for node_id, name in order:
+ graph.add_node(
+ node_id,
+ node_type="symbol",
+ file_path=node_id.split("::")[0],
+ name=name,
+ kind="class",
+ )
+ graph.add_edge(node_id, "src/base.py::Base", edge_type="extends", confidence=0.9)
+ return extract_heritage("src/base.py", graph)
+
+ assert build(pairs) == build(list(reversed(pairs)))
+
+
[email protected]("extractor", [extract_call_graph, extract_heritage])
+def test_a_file_with_no_symbols_is_still_empty(extractor) -> None:
+ assert extractor("src/nothing.py", nx.DiGraph()) == []
diff --git a/tests/unit/server/mcp/test_used_by_ranking.py b/tests/unit/server/mcp/test_used_by_ranking.py
new file mode 100644
index 000000000..c657938a5
--- /dev/null
+++ b/tests/unit/server/mcp/test_used_by_ranking.py
@@ -0,0 +1,164 @@
+"""``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.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+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"
+_NOISE = 25
+
+
+async def repository(session, populated_db) -> Repository:
+ return await session.get(Repository, populated_db)
+
+
+async def many_users(session, populated_db) -> str:
+ """``_NOISE`` peripheral importers, 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
+ serves this join through the ``(repository_id, node_id)`` unique index, so
+ the "unordered" query comes back in path order and a hub whose path sorts
+ early survives a cut that is not ranking anything. Named to sort last, and
+ inserted last, so neither path order nor insertion order can keep it: only
+ 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.)
+ """
+ rid = populated_db
+ for i in range(_NOISE):
+ path = f"src/leaf/leaf{i:03d}.py"
+ session.add(
+ GraphNode(
+ id=f"gn-leaf-{i}",
+ repository_id=rid,
+ node_id=path,
+ node_type="file",
+ language="python",
+ symbol_count=1,
+ is_test=False,
+ is_entry_point=False,
+ # Rising with the name, so path order and rank order disagree
+ # on every pair. Equal ranks would let an alphabetical list
+ # satisfy "descending by PageRank" for free.
+ pagerank=0.001 * (i + 1),
+ betweenness=0.0,
+ community_id=1,
+ )
+ )
+ session.add(
+ GraphEdge(
+ id=f"ge-leaf-{i}",
+ repository_id=rid,
+ source_node_id=path,
+ target_node_id=_FILE,
+ edge_type="imports",
+ imported_names_json='["AuthService"]',
+ )
+ )
+ session.add(
+ GraphNode(
+ id="gn-hub",
+ repository_id=rid,
+ node_id="src/zz_hub.py",
+ node_type="file",
+ language="python",
+ symbol_count=9,
+ is_test=False,
+ is_entry_point=True,
+ pagerank=0.9,
+ betweenness=0.5,
+ community_id=1,
+ )
+ )
+ session.add(
+ 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"]',
+ )
+ )
+ 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_the_most_central_user_survives_the_cut(session, repository, many_users) -> None:
+ used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
+
+ assert len(used_by) == _MAX_USED_BY
+ assert used_by[0] == "src/zz_hub.py"
+
+
+async def test_used_by_is_ordered_by_centrality(session, repository, many_users) -> None:
+ """Not just "the hub is in there" — the whole list is a ranking."""
+ used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
+
+ ranks = {}
+ for path in used_by:
+ node = await session.execute(
+ GraphNode.__table__.select().where(GraphNode.node_id == path)
+ )
+ row = node.first()
+ ranks[path] = row.pagerank if row else 0.0
+ 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.
+
+ The base fixture has two importers of this file, which is the population
+ every other test in this directory runs on.
+ """
+ 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_one_user_joined_by_two_edge_types_is_listed_once(
+ 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.
+ """
+ session.add(
+ GraphEdge(
+ id="ge-dup",
+ repository_id=populated_db,
+ source_node_id="src/auth/middleware.py",
+ target_node_id=_FILE,
+ edge_type="calls",
+ imported_names_json="[]",
+ )
+ )
+ await session.commit()
+
+ used_by = (await _card(session, repository, "AuthService"))["docs"]["used_by"]
+
+ assert used_by.count("src/auth/middleware.py") == 1
diff --git a/tests/unit/test_no_unranked_truncation.py b/tests/unit/test_no_unranked_truncation.py
new file mode 100644
index 000000000..8e9e66d21
--- /dev/null
+++ b/tests/unit/test_no_unranked_truncation.py
@@ -0,0 +1,179 @@
+"""The lists P9 ranked stay ranked (the architecture half of P9).
+
+An architecture check, not a behaviour one. The behaviour lives in
+``tests/unit/generation/test_ranked_truncation.py`` and
+``tests/unit/server/mcp/test_used_by_ranking.py``, which catch a *wrong*
+order; this catches the ranking being **deleted** — the sort disappearing in a
+refactor and leaving the cut behind, which is how all seven sites got here.
+Every one of them was executed by tests that asserted nothing about it, so
+removing the ranking would have been green.
+
+**The first version of this file was vacuous on half its entries, and the way
+it failed is the reason it now looks like this.** It walked each registered
+function's AST for any call named ``sorted``/``sort``/``order_by`` and passed
+if one existed anywhere in the body. ``assemble_module_page`` is 164 lines and
+holds seven such calls; ``_resolve_one_target`` is 898 lines and holds five.
+Deleting the P9 sort in either would have left this green. Worse,
+``active_landscape``'s fix *removed* a ``set`` rather than adding a sort, so
+that entry could not have failed for any edit to the code it named. So the
+check now pins the ranking **expression**, not the presence of ranking.
+
+That trades one weakness for another and the trade is deliberate: a snippet
+check breaks on reformatting. When it does, the fix is to update the snippet
+after confirming the ranking still happens — not to delete the entry. The
+failure message says so, because a guard whose failure is confusing gets
+deleted rather than read.
+
+Why not a general "find every unranked slice" checker: the question is
+undecidable from the AST. A list can be ranked three frames up, by a SQL
+``ORDER BY``, or by a caller's contract, and a checker that flagged every
+``[:N]`` would drown six real sites in the ~200 legitimate slices under
+``packages/`` — string truncation, batch sizes, log samples. The census that
+found these is in ``local-stash/structural-debt/PROGRESS.md``.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+import pytest
+
+_PACKAGES = pathlib.Path(__file__).resolve().parents[2] / "packages"
+
+
+class Cut:
+ """One ranked truncation: what must be there, and what must not come back."""
+
+ def __init__(self, site: str, rel: str, requires: str, why: str, forbids: str = "") -> None:
+ self.site = site
+ self.rel = rel
+ self.requires = requires
+ self.why = why
+ #: The exact shape that shipped, where removing the fix would restore a
+ #: recognisable idiom rather than just deleting a line.
+ self.forbids = forbids
+
+ def __repr__(self) -> str: # pytest node id
+ return self.site
+
+
+_CUTS = [
+ Cut(
+ "extract_call_graph",
+ "core/src/repowise/core/generation/context/graph_intelligence.py",
+ 'entries.sort(key=lambda e: (-float(e.get("confidence") or 0.0), e["caller"], e["callee"]))',
+ "confidence, before MAX_CALL_ENTRIES",
+ forbids="unique[:15]",
+ ),
+ Cut(
+ "extract_heritage",
+ "core/src/repowise/core/generation/context/graph_intelligence.py",
+ "zip(scores, entries, strict=True)",
+ "confidence, before MAX_HERITAGE_ENTRIES",
+ forbids="entries[:10]",
+ ),
+ Cut(
+ "assemble_module_page.key_classes",
+ "core/src/repowise/core/generation/context/assembler.py",
+ "for fc in sorted(file_contexts, key=lambda fc: (-fc.pagerank_score, fc.file_path)):",
+ "the file's PageRank, before _MAX_KEY_CLASSES",
+ forbids="for fc in file_contexts:\n for h in fc.heritage",
+ ),
+ Cut(
+ "get_graph_edges_for_node.callers",
+ "core/src/repowise/core/persistence/crud/graph.py",
+ "GraphEdge.confidence.desc(), GraphEdge.source_node_id, GraphEdge.edge_type",
+ "edge confidence, before `limit`",
+ ),
+ Cut(
+ "get_graph_edges_for_node.callees",
+ "core/src/repowise/core/persistence/crud/graph.py",
+ "GraphEdge.confidence.desc(), GraphEdge.target_node_id, GraphEdge.edge_type",
+ "edge confidence, before `limit`",
+ ),
+ Cut(
+ "pr_blast.all_affected_paths",
+ "core/src/repowise/core/analysis/pr_blast.py",
+ "all_affected_paths = sorted(changed_set | {e[\"path\"] for e in transitive_affected})",
+ "path order, before test_gaps is cut to 3 as missing_tests",
+ forbids="all_affected_paths = list(changed_set |",
+ ),
+ Cut(
+ "pr_blast._transitive_affected",
+ "core/src/repowise/core/analysis/pr_blast.py",
+ "key=lambda item: (item[1], item[0])",
+ "depth then path, before will_break takes 15",
+ forbids="frontier = list(set(changed_files))",
+ ),
+ Cut(
+ "active_landscape.dead_code_in_hot",
+ "core/src/repowise/core/generation/onboarding/subkinds/active_landscape.py",
+ "for hot in hot_files:",
+ "the churn ranking itself, before the cut to 15",
+ # The defect was not a missing sort but a ranking discarded by a set.
+ forbids="hot_paths = {h.path for h in hot_files}",
+ ),
+ Cut(
+ "used_by",
+ "server/src/repowise/server/mcp_server/tool_context/targets.py",
+ "sorted(best_rank, key=lambda p: (-best_rank[p], p))",
+ "the source file's PageRank, before _MAX_USED_BY",
+ ),
+]
+
+
+def _text(rel: str) -> str:
+ path = _PACKAGES / rel
+ assert path.is_file(), f"{rel} moved; update the registry in {__file__}"
+ return path.read_text(encoding="utf-8")
+
+
[email protected]("cut", _CUTS, ids=repr)
+def test_the_cut_is_still_ranked(cut: Cut) -> None:
+ assert cut.requires in _text(cut.rel), (
+ f"{cut.site} truncates a displayed list and the expression that ranks "
+ f"it is gone. It must rank by {cut.why}.\n\nExpected to find:\n"
+ f" {cut.requires}\n\nIf the ranking still happens and only the "
+ "formatting moved, update this entry. If the cut itself is gone, "
+ "delete the entry. Do not delete it to make this pass."
+ )
+
+
[email protected]("cut", [c for c in _CUTS if c.forbids], ids=repr)
+def test_the_shape_that_shipped_does_not_come_back(cut: Cut) -> None:
+ """The unranked idiom itself, not just the absence of a sort.
+
+ Two of these are the whole check: ``active_landscape``'s fix removed a
+ ``set`` and added no sort, and ``pr_blast``'s frontier was a bare
+ ``list(set(...))`` — neither leaves a ranking call for a presence test to
+ find, so only the retired shape distinguishes fixed from reverted.
+ """
+ assert cut.forbids not in _text(cut.rel), (
+ f"{cut.site} is back to the unranked shape `{cut.forbids}`, which "
+ f"cuts a displayed list without ranking it by {cut.why}."
+ )
+
+
+def test_the_graph_extractors_cut_at_a_named_constant() -> None:
+ """No bare literal back at the ``return``.
+
+ The literals are what made the two cuts invisible: they read as an
+ implementation detail rather than as a contract a test could hold. Pinned
+ at the return lines rather than by searching the file for ``[:10]``, which
+ would fail on any unrelated future slice.
+ """
+ text = _text("core/src/repowise/core/generation/context/graph_intelligence.py")
+ assert "MAX_CALL_ENTRIES = 15" in text
+ assert "MAX_HERITAGE_ENTRIES = 10" in text
+ assert "return unique[:MAX_CALL_ENTRIES]" in text
+ assert "ranked[:MAX_HERITAGE_ENTRIES]" in text
+
+
+def test_every_registered_file_exists() -> None:
+ """Registry rot: an entry naming a file that has moved passes silently.
+
+ ``_text`` asserts, so this only fails when a path is stale — which is the
+ state in which every other test here becomes an error rather than a check.
+ """
+ for cut in _CUTS:
+ assert (_PACKAGES / cut.rel).is_file(), f"{cut.site}: {cut.rel} is gone"