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
"""Flow-path expansion: connect question-anchored endpoints over the graph.
get_answer's plain 1-hop expansion rescues "right module, wrong file" ranking
misses but cannot reach a far endpoint the question names that retrieval buried
or dropped. ``expand_via_flow_path`` resolves 2+ endpoints (a named symbol's
file, a module named by basename), runs a bounded bidirectional BFS between them
over imports + projected calls edges, and surfaces the files on the path so both
endpoints land in the served top-5.
These lock the mechanism deterministically (no LLM, no synthesis): the far
endpoint is injected when absent and boosted when buried, calls edges are
projected to file granularity, the confidence floor and cross-language guard
hold, and a single-endpoint question is a no-op.
"""
from __future__ import annotations
from datetime import UTC, datetime
from repowise.core.persistence.models import GraphEdge, Page, WikiSymbol
from repowise.server.mcp_server._flow_path import expand_via_flow_path
_NOW = datetime(2026, 3, 19, 12, 0, 0, tzinfo=UTC)
def _page(rid: str, path: str) -> Page:
return Page(
id=f"file_page:{path}",
repository_id=rid,
page_type="file_page",
title=path,
content=f"# {path}",
summary=f"summary of {path}",
target_path=path,
source_hash=path,
model_name="mock",
provider_name="mock",
generation_level=2,
confidence=1.0,
freshness_status="fresh",
metadata_json="{}",
created_at=_NOW,
updated_at=_NOW,
)
def _symbol(rid: str, name: str, file_path: str) -> WikiSymbol:
return WikiSymbol(
id=f"{file_path}::{name}",
repository_id=rid,
file_path=file_path,
symbol_id=f"{file_path}::{name}",
name=name,
qualified_name=name,
kind="function",
signature=f"def {name}()",
start_line=1,
end_line=5,
docstring="",
visibility="public",
is_async=False,
complexity_estimate=1,
language="python",
parent_name=None,
)
def _edge(rid: str, src: str, tgt: str, etype: str, conf: float = 1.0) -> GraphEdge:
return GraphEdge(
id=f"{src}->{tgt}:{etype}",
repository_id=rid,
source_node_id=src,
target_node_id=tgt,
edge_type=etype,
confidence=conf,
)
# Paths kept short but multi-segment so basename-stem matching is exercised.
_ANSWER = "pkg/server/answer.py"
_RETRIEVAL = "pkg/server/retrieval.py"
_CONF = "pkg/server/confidence.py"
async def test_injects_absent_far_endpoint(session, repo_id):
"""A named module endpoint absent from hits is injected onto the path."""
session.add(_page(repo_id, _ANSWER))
session.add(_page(repo_id, _RETRIEVAL))
session.add(_symbol(repo_id, "get_answer", _ANSWER))
session.add(_edge(repo_id, _ANSWER, _RETRIEVAL, "imports"))
await session.commit()
hits = [{"target_path": _ANSWER, "score": 5.0}]
combined, paths = await expand_via_flow_path(
session, repo_id, hits, "how does get_answer use retrieval", {"get_answer"}
)
injected = [h for h in combined if h.get("target_path") == _RETRIEVAL]
assert len(injected) == 1
assert injected[0]["_expanded_from"] == "flow"
assert paths and [_ANSWER, _RETRIEVAL] in paths
async def test_boosts_buried_endpoint_without_duplicating(session, repo_id):
"""A far endpoint already ranked below the cap is boosted, not duplicated."""
session.add(_page(repo_id, _ANSWER))
session.add(_page(repo_id, _RETRIEVAL))
session.add(_symbol(repo_id, "get_answer", _ANSWER))
session.add(_edge(repo_id, _ANSWER, _RETRIEVAL, "imports"))
await session.commit()
hits = [
{"target_path": _ANSWER, "score": 5.0},
{"target_path": _RETRIEVAL, "score": 0.05},
]
combined, _ = await expand_via_flow_path(
session, repo_id, hits, "how does get_answer use retrieval", {"get_answer"}
)
retr = [h for h in combined if h.get("target_path") == _RETRIEVAL]
assert len(retr) == 1 # boosted in place, no duplicate row
assert retr[0]["score"] > 3.0 # 0.7 * 5.0, was 0.05 — now rides into top-5
assert combined[1]["target_path"] == _RETRIEVAL # rose to rank 2
async def test_single_anchor_is_noop(session, repo_id):
"""One resolvable endpoint is a plain 'what is X' — the stage does nothing."""
session.add(_page(repo_id, _ANSWER))
session.add(_symbol(repo_id, "get_answer", _ANSWER))
await session.commit()
hits = [{"target_path": _ANSWER, "score": 5.0}]
combined, paths = await expand_via_flow_path(
session, repo_id, hits, "how does get_answer work", {"get_answer"}
)
assert combined is hits
assert paths == []
async def test_calls_edges_projected_to_files(session, repo_id):
"""An endpoint reachable only via a symbol-level calls edge still connects."""
parser, builder = "pkg/core/parser.py", "pkg/core/builder.py"
session.add(_page(repo_id, parser))
session.add(_page(repo_id, builder))
# No import edge — only a symbol-to-symbol calls edge between the two files.
session.add(_edge(repo_id, f"{parser}::parse", f"{builder}::build", "calls", conf=0.9))
await session.commit()
hits = [{"target_path": parser, "score": 5.0}]
combined, paths = await expand_via_flow_path(
session, repo_id, hits, "how does parser feed builder", set()
)
assert any(h.get("target_path") == builder for h in combined)
assert paths
async def test_low_confidence_call_edge_is_dropped(session, repo_id):
"""A calls edge below the confidence floor is not a traversable path."""
parser, builder = "pkg/core/parser.py", "pkg/core/builder.py"
session.add(_page(repo_id, parser))
session.add(_page(repo_id, builder))
session.add(_edge(repo_id, f"{parser}::parse", f"{builder}::build", "calls", conf=0.2))
await session.commit()
hits = [{"target_path": parser, "score": 5.0}]
combined, paths = await expand_via_flow_path(
session, repo_id, hits, "how does parser feed builder", set()
)
assert paths == []
assert combined is hits
async def test_multi_hop_path_within_depth_cap(session, repo_id):
"""A 3-hop chain between two named endpoints is found (bidirectional BFS)."""
parser, mid1, mid2, builder = (
"pkg/parser.py",
"pkg/resolver.py",
"pkg/planner.py",
"pkg/builder.py",
)
for p in (parser, mid1, mid2, builder):
session.add(_page(repo_id, p))
# Chain parser - resolver - planner - builder (3 hops); parser and builder
# are the named endpoints, the interior is discovered by the search.
session.add(_edge(repo_id, parser, mid1, "imports"))
session.add(_edge(repo_id, mid1, mid2, "imports"))
session.add(_edge(repo_id, mid2, builder, "imports"))
await session.commit()
hits = [{"target_path": parser, "score": 5.0}]
combined, paths = await expand_via_flow_path(
session, repo_id, hits, "how does parser feed the builder", set()
)
assert any(h.get("target_path") == builder for h in combined)
# Undirected search: the path may be reported from either endpoint.
assert paths and paths[0] in ([parser, mid1, mid2, builder], [builder, mid2, mid1, parser])
async def test_cross_language_anchor_dropped(session, repo_id):
"""A same-named file in another language is not an endpoint of a .py flow."""
sym_py = "pkg/server/symbols.py"
sym_ts = "web/src/symbols.ts"
session.add(_page(repo_id, _ANSWER))
session.add(_page(repo_id, sym_py))
session.add(_page(repo_id, sym_ts))
session.add(_symbol(repo_id, "get_answer", _ANSWER))
session.add(_edge(repo_id, _ANSWER, sym_py, "imports"))
await session.commit()
hits = [{"target_path": _ANSWER, "score": 5.0}]
combined, _ = await expand_via_flow_path(
session, repo_id, hits, "how does get_answer build the symbols body", {"get_answer"}
)
paths = {h.get("target_path") for h in combined}
assert sym_py in paths # in-language endpoint injected
assert sym_ts not in paths # off-language same-name match dropped
def test_plumbing_covers_test_material_by_the_shared_rules():
"""Tests bridge unrelated files, so none of them make a flow endpoint.
The substring list this replaced anchored on ``/tests/``, so a repo whose
suite sits at the root had its whole test tree treated as ordinary source
and eligible for injection (#1103).
"""
from repowise.server.mcp_server._flow_path import _is_plumbing
assert _is_plumbing("tests/unit/server/test_flow_path.py") # root-level suite
assert _is_plumbing("myapp/tests.py")
assert _is_plumbing("Foo.Tests/Bar.cs")
assert _is_plumbing("packages/core/tests/conftest.py") # support bridges too
assert _is_plumbing("pkg/server/__init__.py") # re-export glue, unchanged
# Production code that merely spells "test" is a legitimate endpoint.
assert not _is_plumbing("src/analysis/missing_test_signal.py")
assert not _is_plumbing("src/latest/api.py")
# --- determinism -----------------------------------------------------------
#
# Found by the #1510 payload oracle: the same build, same question, same index
# produced `flow_path` with two equal-length paths in opposite orders, one
# ordering per run. Adjacency was a dict of sets and BFS walked it, so which of
# several shortest paths was found moved with the per-process string hash seed —
# and a nondeterministic ordering can be frozen into the answer cache.
def test_adjacency_neighbours_come_back_ordered():
"""Sets dedupe; the walk needs an order, so the dict hands out sorted lists."""
import asyncio
from repowise.server.mcp_server._flow_path import _load_file_adjacency
class _Res:
def all(self):
return [
("a.py", "z.py", "imports", 1.0),
("a.py", "b.py", "imports", 1.0),
("a.py", "m.py", "imports", 1.0),
]
class _Session:
async def execute(self, _stmt):
return _Res()
adj = asyncio.run(_load_file_adjacency(_Session(), "r1"))
assert adj["a.py"] == ["b.py", "m.py", "z.py"]
def test_bfs_breaks_a_shortest_path_tie_the_same_way_every_time():
"""A diamond: two 3-hop routes from `a` to `d`. The ordered walk picks one.
Asserted against the neighbour order rather than "runs twice agree", which a
single process cannot demonstrate — the seed is fixed for its lifetime.
"""
from repowise.server.mcp_server._flow_path import _bfs_path
adj = {
"a.py": ["b.py", "c.py"],
"b.py": ["a.py", "d.py"],
"c.py": ["a.py", "d.py"],
"d.py": ["b.py", "c.py"],
}
assert _bfs_path(adj, "a.py", "d.py", 4) == ["a.py", "b.py", "d.py"]
# The walk is bidirectional and the sides alternate, so on a 2-hop diamond
# it is the BACKWARD frontier that reaches the meeting point first. Flip
# `d`'s neighbours and the chosen route flips with it — which is the point:
# the result follows the walk order, and the walk order is now fixed.
flipped = {**adj, "d.py": ["c.py", "b.py"]}
assert _bfs_path(flipped, "a.py", "d.py", 4) == ["a.py", "c.py", "d.py"]
async def test_the_anchor_cap_keeps_what_retrieval_ranked(session, repo_id):
"""Determinism must not become an alphabetical bias.
Eight anchors against a cap of six. The one file retrieval ranked sorts LAST
alphabetically, so it survives the cap only if rank is what decides.
"""
stems = ["alpha", "beta", "gamma", "delta"]
ranked = "zzz/delta.py"
paths_seeded = [_ANSWER, ranked] + [f"{d}/{s}.py" for s in stems for d in ("aaa", "mmm")]
for path in dict.fromkeys(paths_seeded):
session.add(_page(repo_id, path))
session.add(_symbol(repo_id, "get_answer", _ANSWER))
session.add(_edge(repo_id, _ANSWER, ranked, "imports"))
await session.commit()
hits = [{"target_path": _ANSWER, "score": 5.0}, {"target_path": ranked, "score": 4.0}]
_combined, paths = await expand_via_flow_path(
session,
repo_id,
hits,
"how does get_answer reach alpha beta gamma delta",
{"get_answer"},
)
assert [_ANSWER, ranked] in paths