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
"""Tests for the topology-driven guided tour (generation.tour)."""
from __future__ import annotations
from dataclasses import dataclass
from repowise.core.generation.tour import (
DEFAULT_MAX_STOPS,
build_tour,
score_entry_points,
select_hotspot_stop,
tour_landmark_paths,
)
@dataclass
class _FI:
path: str
is_entry_point: bool = False
language: str = "python"
is_application_main: bool = False
@dataclass
class _PF:
file_info: _FI
def _repo(paths_entry: dict[str, bool]) -> list[_PF]:
return [_PF(_FI(path=p, is_entry_point=e)) for p, e in paths_entry.items()]
# ---------------------------------------------------------------------------
# Entry-point scoring
# ---------------------------------------------------------------------------
def test_score_entry_points_rewards_entry_flag_and_filename():
files = _repo({"src/main.py": True, "src/helpers/util.py": False})
pr = {"src/main.py": 0.9, "src/helpers/util.py": 0.1}
scored = score_entry_points(files, pr)
ranked = [p for _, p in scored]
assert ranked[0] == "src/main.py" # entry flag + main filename + shallow
def test_score_entry_points_puts_a_declared_entry_above_every_guess():
# Fineract: a sample's shallow, central ``Main.java`` scores every guess
# (flag, stem, depth, PageRank) and still follows the Spring Boot main.
main = "lib/Main.java"
app = "provider/src/main/java/org/acme/ServerApplication.java"
files = [
_PF(_FI(path=main, is_entry_point=True, language="java")),
_PF(_FI(path=app, is_entry_point=True, language="java", is_application_main=True)),
]
scored = score_entry_points(files, {main: 0.9, app: 0.0})
assert [p for _, p in scored] == [app, main]
def test_score_entry_points_excludes_zero_score():
files = _repo({"deep/nested/pkg/thing.py": False})
pr = {"deep/nested/pkg/thing.py": 0.0}
assert score_entry_points(files, pr) == []
def test_score_entry_points_withholds_stem_bonus_from_docs():
# docs/index.md has an entry-style stem but is markdown — it must never
# outrank a real main.py. Ingestion stopped flagging it once candidacy
# moved there, so ``is_entry_point=True`` below is what an older index
# hands over, which is exactly the input the scorer still has to defend
# against.
files = [
_PF(_FI(path="docs/index.md", language="markdown", is_entry_point=True)),
_PF(_FI(path="src/main.py")),
]
pr = {"docs/index.md": 0.9, "src/main.py": 0.5}
scored = {p: s for s, p in score_entry_points(files, pr)}
assert scored["src/main.py"] >= 3.0
assert scored.get("docs/index.md", 0.0) < 3.0
def test_score_entry_points_withholds_bonus_from_deep_glue_leaf():
# A deeply-nested resolver index.py defines real symbols (not a barrel) but
# dispatches; it must not earn the entry bonuses that would seed the walk
# and label it "an entry point". Flagged by hand: ingestion no longer sets
# the flag here either, so this pins the scorer against an older index.
files = [
_PF(_FI(path="core/ingestion/resolvers/dotnet/index.py", is_entry_point=True)),
_PF(_FI(path="src/main.py")),
]
pr = {"core/ingestion/resolvers/dotnet/index.py": 0.9, "src/main.py": 0.5}
scored = {p: s for s, p in score_entry_points(files, pr)}
assert scored["src/main.py"] >= 3.0
assert scored.get("core/ingestion/resolvers/dotnet/index.py", 0.0) < 3.0
# ---------------------------------------------------------------------------
# Hotspot stop selection
# ---------------------------------------------------------------------------
def test_select_hotspot_stop_picks_highest_commit_count():
candidates = ["a/orchestrator.py", "b/walker.py", "c/quiet.py"]
commits = {"a/orchestrator.py": 36, "b/walker.py": 17, "c/quiet.py": 0}
assert select_hotspot_stop(candidates, commits) == "a/orchestrator.py"
def test_select_hotspot_stop_returns_none_without_activity():
# No git history (the fixture matrix): nothing qualifies, tour unchanged.
assert select_hotspot_stop(["a/x.py", "b/y.py"], {}) is None
assert select_hotspot_stop(["a/x.py"], {"a/x.py": 0}) is None
def test_select_hotspot_stop_is_deterministic_on_ties():
commits = {"z/a.py": 5, "a/b.py": 5}
assert select_hotspot_stop(["z/a.py", "a/b.py"], commits) == "a/b.py"
# ---------------------------------------------------------------------------
# Landmarks
# ---------------------------------------------------------------------------
def test_tour_landmark_paths_is_bounded():
files = _repo({f"src/app_{i}.py": True for i in range(20)})
pr = {f"src/app_{i}.py": 1.0 - i * 0.01 for i in range(20)}
landmarks = tour_landmark_paths(files, pr, max_landmarks=3)
assert len(landmarks) == 3
# ---------------------------------------------------------------------------
# build_tour
# ---------------------------------------------------------------------------
def test_build_tour_only_references_documented_pages():
files = _repo({"main.py": True, "a.py": False, "b.py": False, "undocumented.py": False})
pr = {"main.py": 0.9, "a.py": 0.5, "b.py": 0.3, "undocumented.py": 0.2}
edges = [("main.py", "a.py"), ("a.py", "b.py"), ("main.py", "undocumented.py")]
documented = {"main.py", "a.py", "b.py"} # undocumented.py NOT selected
stops = build_tour(
files, pr, edges, file_page_paths=documented, repo_name="myrepo"
)
targets = {s.target_path for s in stops}
assert "undocumented.py" not in targets
assert "myrepo" in targets # overview opens the tour
def test_build_tour_orders_by_bfs_depth():
files = _repo({"main.py": True, "a.py": False, "b.py": False})
pr = {"main.py": 0.9, "a.py": 0.5, "b.py": 0.3}
edges = [("main.py", "a.py"), ("a.py", "b.py")]
stops = build_tour(files, pr, edges, file_page_paths={"main.py", "a.py", "b.py"})
code_stops = [s for s in stops if s.kind == "code"]
order = [s.target_path for s in code_stops]
assert order == ["main.py", "a.py", "b.py"]
assert [s.depth for s in code_stops] == [0, 1, 2]
def test_build_tour_weaves_infra_last():
files = _repo({"main.py": True, "a.py": False})
pr = {"main.py": 0.9, "a.py": 0.5, "Dockerfile": 0.1}
edges = [("main.py", "a.py")]
stops = build_tour(
files,
pr,
edges,
file_page_paths={"main.py", "a.py"},
infra_paths={"Dockerfile"},
repo_name="r",
)
assert stops[-1].kind == "infra"
assert stops[-1].target_path == "Dockerfile"
def test_build_tour_unreached_files_get_honest_reasons():
# disconnected.py is never reached from the entry point — its reason must
# not claim it was "reached N imports deep".
files = _repo({"main.py": True, "a.py": False, "disconnected.py": False})
pr = {"main.py": 0.9, "a.py": 0.5, "disconnected.py": 0.1}
edges = [("main.py", "a.py")]
stops = build_tour(
files, pr, edges, file_page_paths={"main.py", "a.py", "disconnected.py"}
)
by_path = {s.target_path: s for s in stops}
assert "Off the import path" in by_path["disconnected.py"].reason
assert "Reached" not in by_path["disconnected.py"].reason
assert "Directly used" in by_path["a.py"].reason # reached ones unchanged
def test_score_entry_points_withholds_entry_bonuses_from_examples():
# examples/*/main.go are entries by *name* only — the library itself
# must outrank them.
files = [
_PF(_FI(path="_examples/hello-world/main.go", is_entry_point=True)),
_PF(_FI(path="cmd/app/main.go", is_entry_point=True)),
]
pr = {"_examples/hello-world/main.go": 0.9, "cmd/app/main.go": 0.5}
scored = {p: s for s, p in score_entry_points(files, pr)}
assert scored["cmd/app/main.go"] >= 3.0
assert scored.get("_examples/hello-world/main.go", 0.0) < 3.0
def test_score_entry_points_withholds_entry_bonuses_from_test_files():
# tests/testserver/server.py has an entry-style stem, but a test fixture
# must never seed the onboarding walk.
files = [
_PF(_FI(path="tests/testserver/server.py", is_entry_point=True)),
_PF(_FI(path="src/pkg/models.py")),
]
pr = {"tests/testserver/server.py": 0.9, "src/pkg/models.py": 0.5}
scored = {p: s for s, p in score_entry_points(files, pr)}
assert scored.get("tests/testserver/server.py", 0.0) < 3.0
def test_build_tour_seedless_repo_reasons_do_not_overclaim():
# A flat library with no entry-style file: steps must not reference
# entry points that don't exist.
files = _repo({"src/pkg/models.py": False, "src/pkg/cookies.py": False})
pr = {"src/pkg/models.py": 0.8, "src/pkg/cookies.py": 0.6}
stops = build_tour(
files, pr, [], file_page_paths={"src/pkg/models.py", "src/pkg/cookies.py"}
)
for s in stops:
assert "An entry point" not in s.reason
# the offending phrase referenced entry points that don't exist;
# evidence-free parked files now say "Off the import paths walked
# above" instead, which references only the walk itself
assert "from the entry points" not in s.reason
def test_build_tour_seedless_anchor_is_a_code_file():
# The fallback anchor must skip docs/config — a CLAUDE.md at the root
# outscores deep code files but cannot anchor an import walk.
files = [
_PF(_FI(path=".claude/CLAUDE.md", language="markdown")),
_PF(_FI(path="src/pkg/api.py")),
_PF(_FI(path="src/pkg/models.py")),
]
pr = {".claude/CLAUDE.md": 0.9, "src/pkg/api.py": 0.5, "src/pkg/models.py": 0.4}
edges = [("src/pkg/api.py", "src/pkg/models.py")]
documented = {".claude/CLAUDE.md", "src/pkg/api.py", "src/pkg/models.py"}
stops = build_tour(files, pr, edges, file_page_paths=documented)
anchor = next(s for s in stops if s.depth == 0 and s.kind == "code")
assert anchor.target_path == "src/pkg/api.py"
def test_build_tour_respects_max_stops():
files = _repo({f"f{i}.py": (i == 0) for i in range(50)})
pr = {f"f{i}.py": 1.0 - i * 0.01 for i in range(50)}
edges = [(f"f{i}.py", f"f{i+1}.py") for i in range(49)]
documented = {f"f{i}.py" for i in range(50)}
stops = build_tour(files, pr, edges, file_page_paths=documented, repo_name="r")
assert len(stops) <= DEFAULT_MAX_STOPS
def test_score_entry_points_withholds_bonuses_from_api_contracts_and_infra():
# Schema/data languages (graphql, proto, sql, openapi) and
# infra wiring (shell, terraform, dockerfile) never earn entry bonuses,
# however entry-like their stems are. Ingestion withholds the flag from
# all four now; these fixtures set it by hand, so the scorer stays correct
# on rows written before that landed.
files = [
_PF(_FI(path="index.graphql", language="graphql", is_entry_point=True)),
_PF(_FI(path="main.sql", language="sql", is_entry_point=True)),
_PF(_FI(path="run.sh", language="shell", is_entry_point=True)),
_PF(_FI(path="main.tf", language="terraform", is_entry_point=True)),
_PF(_FI(path="src/main.py")),
]
pr = {p.file_info.path: 0.5 for p in files}
scored = {p: s for s, p in score_entry_points(files, pr)}
assert scored["src/main.py"] >= 3.0
for path in ("index.graphql", "main.sql", "run.sh", "main.tf"):
assert scored.get(path, 0.0) < 3.0, path
def test_build_tour_anchor_reasons_never_claim_entry_points():
# Anchor-seeded walks (no genuine entries) must not say "the entry
# points above" — there are none.
files = [
_PF(_FI(path="src/core.py")),
_PF(_FI(path="src/helper.py")),
_PF(_FI(path="src/deep.py")),
]
pr = {"src/core.py": 0.5, "src/helper.py": 0.3, "src/deep.py": 0.2}
edges = [("src/core.py", "src/helper.py"), ("src/helper.py", "src/deep.py")]
documented = {"src/core.py", "src/helper.py", "src/deep.py"}
stops = build_tour(files, pr, edges, file_page_paths=documented)
for s in stops:
assert "entry point" not in s.reason or s.depth == 0, s.reason
anchor = next(s for s in stops if s.depth == 0)
assert "anchor" in anchor.reason
d1 = next(s for s in stops if s.depth == 1)
assert "anchor" in d1.reason and "entry points" not in d1.reason
def test_build_tour_unreached_non_code_files_take_no_slot():
# D-037 watch item: sparse-mode walks filled their budget with
# CHANGELOG.md / *.toml "not on the resolved import paths" slots.
# Unreached documents and config can never be on an import path —
# they are not worth a step that displaces code.
files = [
_PF(_FI(path="lib/init.lua", language="luau", is_entry_point=True)),
_PF(_FI(path="lib/util.lua", language="luau")),
_PF(_FI(path="CHANGELOG.md", language="markdown")),
_PF(_FI(path="wally.toml", language="toml")),
]
pr = {p: 0.25 for p in ("lib/init.lua", "lib/util.lua", "CHANGELOG.md", "wally.toml")}
edges = [("lib/init.lua", "lib/util.lua")]
documented = {"lib/init.lua", "lib/util.lua", "CHANGELOG.md", "wally.toml"}
stops = build_tour(files, pr, edges, file_page_paths=documented, graph_mode="sparse")
paths = {s.target_path for s in stops}
assert "CHANGELOG.md" not in paths
assert "wally.toml" not in paths
assert {"lib/init.lua", "lib/util.lua"} <= paths
def test_build_tour_reached_config_keeps_its_slot():
# A config file genuinely on an import path (TS importing data.json)
# keeps its step — only *unreached* non-code is exempt from parking.
files = [
_PF(_FI(path="src/index.ts", language="typescript", is_entry_point=True)),
_PF(_FI(path="src/config.json", language="json")),
]
pr = {"src/index.ts": 0.6, "src/config.json": 0.4}
edges = [("src/index.ts", "src/config.json")]
documented = {"src/index.ts", "src/config.json"}
stops = build_tour(files, pr, edges, file_page_paths=documented)
assert "src/config.json" in {s.target_path for s in stops}
# ---------------------------------------------------------------------------
# Wiring-stub entry co-anchor
# ---------------------------------------------------------------------------
def _stub_entry_repo():
"""An OTP-style library: the only entry is a supervision stub whose
forward BFS reaches nothing, while a hub file's imports fan out wide."""
paths = {
"lib/app/application.ex": True, # wiring stub — no outgoing imports
"lib/encode.ex": False,
"lib/codegen.ex": False,
"lib/fragment.ex": False,
"lib/decoder.ex": False,
"lib/helpers.ex": False,
"lib/sigil.ex": False,
"lib/jason.ex": False,
}
files = [_PF(_FI(path=p, is_entry_point=e, language="elixir")) for p, e in paths.items()]
edges = [
("lib/encode.ex", "lib/codegen.ex"),
("lib/encode.ex", "lib/fragment.ex"),
("lib/encode.ex", "lib/jason.ex"),
("lib/codegen.ex", "lib/decoder.ex"),
]
pr = dict.fromkeys(paths, 0.1)
return files, pr, edges, set(paths)
def test_wiring_stub_entry_gets_a_co_anchor():
files, pr, edges, documented = _stub_entry_repo()
stops = build_tour(files, pr, edges, file_page_paths=documented)
by_path = {s.target_path: s for s in stops}
# the entry keeps its step and wording
assert "An entry point" in by_path["lib/app/application.ex"].reason
# the widest-fanout file co-anchors at depth 0 with anchor wording
anchor = by_path["lib/encode.ex"]
assert anchor.depth == 0
assert "entry point above only wires" in anchor.reason
# the walk actually proceeds through the anchor's imports
assert by_path["lib/codegen.ex"].depth == 1
assert "anchor above" in by_path["lib/codegen.ex"].reason
assert by_path["lib/decoder.ex"].depth == 2
def test_entry_with_real_reach_gets_no_co_anchor():
paths = {
"src/main.py": True,
"src/a.py": False,
"src/b.py": False,
"src/c.py": False,
"src/hub.py": False,
"src/d.py": False,
"src/e.py": False,
"src/f.py": False,
}
files = _repo(paths)
edges = [
("src/main.py", "src/a.py"),
("src/a.py", "src/b.py"),
("src/b.py", "src/c.py"),
# a hub with wide fanout that must NOT displace the real entry walk
("src/hub.py", "src/d.py"),
("src/hub.py", "src/e.py"),
("src/hub.py", "src/f.py"),
]
pr = dict.fromkeys(paths, 0.1)
stops = build_tour(files, pr, edges, file_page_paths=set(paths))
by_path = {s.target_path: s for s in stops}
assert "An entry point" in by_path["src/main.py"].reason
assert "only wires" not in " ".join(s.reason for s in stops)
# ---------------------------------------------------------------------------
# Manifests never park
# ---------------------------------------------------------------------------
def test_unreached_manifest_never_parks():
paths = {
"lib/core.ex": False,
"lib/util.ex": False,
"mix.exs": False,
"project.clj": False,
}
files = [_PF(_FI(path=p, is_entry_point=False, language="elixir")) for p in paths]
edges = [("lib/core.ex", "lib/util.ex")]
pr = dict.fromkeys(paths, 0.1)
stops = build_tour(files, pr, edges, file_page_paths=set(paths))
visited = {s.target_path for s in stops}
assert "mix.exs" not in visited
assert "project.clj" not in visited