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
"""The overview's execution-flow section, end to end.
``assemble_repo_overview`` reads the traced flows off the graph builder and the
overview templates render them. Every step of that is asserted here because the
section has never appeared on a generated page: the assembler read attribute
names the ``ExecutionFlow`` dataclass does not have, the ``AttributeError`` was
swallowed by a bare ``except``, and the ``{% if ctx.execution_flows %}`` guard
then dropped the section without a word.
"""
from __future__ import annotations
from dataclasses import replace
import networkx as nx
import pytest
from structlog.testing import capture_logs
from repowise.core.analysis.communities import CommunityInfo
from repowise.core.analysis.execution_flows import ExecutionFlow, ExecutionFlowReport
from repowise.core.generation.context_assembler import ContextAssembler
class _Builder:
"""Minimal stand-in for the graph builder's three overview-facing calls."""
def __init__(self, flows, graph=None):
self._flows = flows
# An empty graph resolves no entry point to a file, which is the
# "cannot tell" case: the reachability filter keeps every flow.
self._graph = graph if graph is not None else nx.DiGraph()
def community_info(self):
return []
def graph(self):
return self._graph
def execution_flows(self):
return ExecutionFlowReport(
total_entry_points_scored=len(self._flows),
total_flows=len(self._flows),
flows=list(self._flows),
)
def _flow(entry_point_id: str, score: float, trace: list[str]) -> ExecutionFlow:
return ExecutionFlow(
entry_point_id=entry_point_id,
entry_point_name=entry_point_id.rsplit("::", 1)[-1],
entry_point_score=score,
trace=trace,
depth=len(trace) - 1,
crosses_community=False,
communities_visited=[0],
termination="no_callees",
)
@pytest.fixture
def flows():
return [
_flow("packages/cli/src/repowise/cli/main.py::main", 0.9123, ["a", "b", "c"]),
_flow("packages/server/src/repowise/server/app.py::create_app", 0.4567, ["d", "e"]),
]
def test_overview_context_carries_traced_flows(sample_config, sample_repo_structure, flows):
"""The reason the section never rendered: this list was always empty."""
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows)
)
assert len(ctx.execution_flows) == 2
first = ctx.execution_flows[0]
assert first["entry_point"] == "packages/cli/src/repowise/cli/main.py::main"
assert first["entry_point_name"] == "main"
assert first["score"] == 0.912
assert first["trace_length"] == 3
def test_overview_context_carries_communities(sample_config, sample_repo_structure):
"""``community_info()`` is a dict keyed by community id, not a list."""
class _CommunityBuilder(_Builder):
def community_info(self):
return {
3: CommunityInfo(
community_id=3,
label="cli",
members=["a.py"],
size=1,
cohesion=0.5,
dominant_language="python",
),
7: CommunityInfo(
community_id=7,
label="core",
members=["b.py", "c.py"],
size=2,
cohesion=0.12345,
dominant_language="python",
),
}
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_CommunityBuilder([])
)
assert ctx.communities == [
{"id": 7, "label": "core", "size": 2, "cohesion": 0.12},
{"id": 3, "label": "cli", "size": 1, "cohesion": 0.5},
]
def test_overview_context_ranks_flows_by_score(sample_config, sample_repo_structure):
"""The template renders the first five, so the order is the selection."""
assembler = ContextAssembler(sample_config)
unordered = [
_flow("low.py::f", 0.1, ["a", "b"]),
_flow("high.py::f", 0.9, ["a", "b"]),
_flow("mid.py::f", 0.5, ["a", "b"]),
]
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(unordered)
)
assert [f["entry_point"] for f in ctx.execution_flows] == [
"high.py::f",
"mid.py::f",
"low.py::f",
]
# ---------------------------------------------------------------------------
# a flow entry point nothing can reach is dead code, not a front door
# ---------------------------------------------------------------------------
def _graph_with(files: dict[str, dict], imports: list[tuple[str, str]]) -> nx.DiGraph:
"""A file graph plus one symbol node per file, as the real builder shapes it."""
g = nx.DiGraph()
for path, attrs in files.items():
g.add_node(path, node_type="file", language="python", **attrs)
g.add_node(f"{path}::f", node_type="symbol", file_path=path, name="f")
g.add_edge(path, f"{path}::f", edge_type="defines")
for src, dst in imports:
g.add_edge(src, dst, edge_type="imports")
return g
def test_unreachable_entry_point_is_not_a_flow(sample_config, sample_repo_structure):
"""Zero inbound calls is the strongest positive signal for a flow entry
point and the definition of ``unreachable_file``. The same file was
Primary Execution Flow #1 and dead code on the same index."""
graph = _graph_with(
{
"src/orphan.py": {"is_entry_point": False},
"src/service.py": {"is_entry_point": False},
"src/caller.py": {"is_entry_point": False},
},
imports=[("src/caller.py", "src/service.py")],
)
flows = [_flow("src/orphan.py::f", 0.95, ["a", "b"]), _flow("src/service.py::f", 0.4, ["a"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == ["src/service.py::f"]
def test_conventional_entry_point_survives_having_no_importers(
sample_config, sample_repo_structure
):
"""Nothing imports ``main.py`` either, which is why the dead-code pass
exempts it, and why this filter must too."""
graph = _graph_with({"src/main.py": {"is_entry_point": True}}, imports=[])
flows = [_flow("src/main.py::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == ["src/main.py::f"]
@pytest.mark.parametrize(
"path",
[
"src/features/api/index.ts", # barrel: reached by the names it forwards
"pkg/sub/__init__.py",
"scripts/release.sh", # never-flag glob: CI invokes it by name
"app/dashboard/page.tsx", # never-flag glob: a file-system route
],
)
def test_filter_bails_out_where_dead_code_is_kinder(sample_config, sample_repo_structure, path):
"""The analyzer rescues these from unreachable_file, so the flow stays.
The barrels the shared predicate always rescued. The never-flag globs it
did not: the matcher used to live on the analyzer, so this caller could
not ask and dropped a flow the dead-code pass would never have reported.
"""
graph = _graph_with({path: {"is_entry_point": False}}, imports=[])
flows = [_flow(f"{path}::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == [f"{path}::f"]
@pytest.mark.parametrize(
"path",
[
"internal/scheduler/queue.go", # Go imports name a package
"src/main/java/app/Queue.java",
"src/Queue.kt",
"src/engine/queue.cpp",
"include/engine/queue.h",
],
)
def test_package_granular_languages_are_answered_not_assumed(
sample_config, sample_repo_structure, path
):
"""This caller supplies the package map, so it gets a real answer.
It used to pass ``package_files=None``, which the predicate reads as "not
checked" and resolves to reachable, so a Go / JVM / C-C++ file with no
package sibling and no importer kept its flow while the dead-code pass
reported the same file. The sibling case below is the other half: the map
rescues a real package member rather than blanket-dropping the language.
"""
graph = _graph_with({path: {"is_entry_point": False}}, imports=[])
flows = [_flow(f"{path}::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert ctx.execution_flows == []
@pytest.mark.parametrize("path", ["cmd/app/main.go", "internal/api/service.pb.go"])
def test_never_flag_wins_over_the_package_map(sample_config, sample_repo_structure, path):
"""Precedence, and it is the one thing these two changes could get wrong.
Both arrived in the same change: the never-flag globs moved into the
predicate, and this caller started supplying the package map. A generated
``.pb.go`` in a package with no live sibling is answered "unreachable" by
the map and "exempt" by the globs, so the order of those two checks decides
the flow. The globs run first, matching the analyzer, which has always
treated a never-flag path as reached from outside the graph.
"""
graph = _graph_with({path: {"is_entry_point": False}}, imports=[])
flows = [_flow(f"{path}::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == [f"{path}::f"]
def test_a_live_package_sibling_still_rescues_the_flow(sample_config, sample_repo_structure):
"""The package map is granularity, not a blanket drop.
``queue.go`` has no importer of its own, but ``server.go`` beside it in the
same package does, and a Go import names the package. So the flow stays —
which is the whole reason the map exists rather than a file-level rule.
"""
graph = _graph_with(
{
"internal/scheduler/queue.go": {"is_entry_point": False},
"internal/scheduler/server.go": {"is_entry_point": False},
"cmd/app/main.go": {"is_entry_point": True},
},
imports=[("cmd/app/main.go", "internal/scheduler/server.go")],
)
flows = [_flow("internal/scheduler/queue.go::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == ["internal/scheduler/queue.go::f"]
@pytest.mark.parametrize("attr", ["is_api_contract", "is_never_flag"])
def test_flow_survives_the_rescues_the_analyzer_already_applied(
sample_config, sample_repo_structure, attr
):
"""Both flags live on the graph node, so this caller always had them and
never asked. Sharing the predicate means it does now, and the two passes
stop disagreeing about a published API contract with no importer."""
graph = _graph_with({"src/contract.py": {"is_entry_point": False, attr: True}}, imports=[])
flows = [_flow("src/contract.py::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert [f["entry_point"] for f in ctx.execution_flows] == ["src/contract.py::f"]
def test_self_import_does_not_rescue_a_flow_entry_point(sample_config, sample_repo_structure):
"""A file importing itself is not evidence anything else reaches it."""
graph = _graph_with({"src/orphan.py": {"is_entry_point": False}}, imports=[])
graph.add_edge("src/orphan.py", "src/orphan.py", edge_type="imports")
flows = [_flow("src/orphan.py::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert ctx.execution_flows == []
def test_dropping_a_flow_is_logged(sample_config, sample_repo_structure):
"""An empty section is a fine outcome; a silent one is not."""
graph = _graph_with({"src/orphan.py": {"is_entry_point": False}}, imports=[])
flows = [_flow("src/orphan.py::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
with capture_logs() as logs:
assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
dropped = [e for e in logs if e["event"] == "overview_flows_dropped_unreachable"]
assert len(dropped) == 1
assert dropped[0]["dropped"] == 1
assert dropped[0]["kept"] == 0
def test_co_change_alone_does_not_make_an_entry_point_reachable(
sample_config, sample_repo_structure
):
"""Co-change is a historical association, not a caller."""
graph = _graph_with({"src/orphan.py": {"is_entry_point": False}}, imports=[])
graph.add_node("docs/notes.md", node_type="file", language="markdown")
graph.add_edge("docs/notes.md", "src/orphan.py", edge_type="co_changes")
flows = [_flow("src/orphan.py::f", 0.95, ["a", "b"])]
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows, graph)
)
assert ctx.execution_flows == []
# ---------------------------------------------------------------------------
# barrels are not execution entry points
# ---------------------------------------------------------------------------
def test_barrels_rank_below_real_entry_points(sample_config, sample_repo_structure):
"""``is_entry_point`` is a filename heuristic whose generic stem set
includes ``index``, so a buried re-export barrel arrived indistinguishable
from a front door and could lead the list.
The ranking demotes rather than drops, and that is still its contract: it
orders what it is handed and holds no candidacy rule. Ingestion now drops
deep glue leaves before the flag is set, so the buried paths below no
longer arrive from a current index — this pins the ordering against a
list built by hand, and against rows written by an older index that still
carries them.
"""
# ``sample_repo_structure`` is module-scoped, so mutating it in place leaks
# into every later test in this file.
structure = replace(
sample_repo_structure,
entry_points=[
"src/features/checkout/api/index.ts", # buried re-export leaf
"packages/cli/src/index.ts", # buried, but a real package entry
"src/main.py", # conventional name, shallow
],
)
assembler = ContextAssembler(sample_config)
ctx = assembler.assemble_repo_overview(structure, {}, [], {})
# Conventional name first; nothing lost.
assert ctx.entry_points[0] == "src/main.py"
assert set(ctx.entry_points) == set(structure.entry_points)
def test_overview_context_warns_when_flows_cannot_be_read(sample_config, sample_repo_structure):
"""A builder that raises must say so. This is the failure that hid for a year."""
class _Broken:
def community_info(self):
return []
def execution_flows(self):
raise RuntimeError("graph not built")
assembler = ContextAssembler(sample_config)
with capture_logs() as logs:
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Broken()
)
assert ctx.execution_flows == []
warned = [e for e in logs if e["event"] == "overview_execution_flows_unavailable"]
assert len(warned) == 1
assert warned[0]["error_type"] == "RuntimeError"
assert warned[0]["log_level"] == "warning"
def test_overview_context_no_builder_is_silent(sample_config, sample_repo_structure):
"""No builder is not a failure, so it must not warn."""
assembler = ContextAssembler(sample_config)
with capture_logs() as logs:
ctx = assembler.assemble_repo_overview(sample_repo_structure, {}, [], {})
assert ctx.execution_flows == []
assert [e for e in logs if e["event"].startswith("overview_")] == []
# ---------------------------------------------------------------------------
# rendered output — both templates read the same context key
# ---------------------------------------------------------------------------
@pytest.mark.parametrize("template", ["repo_overview.j2", "stub/repo_overview.j2"])
def test_rendered_overview_names_the_entry_point(
sample_config, sample_repo_structure, flows, template
):
"""Both templates were always correct — they read the context dict, whose
keys never changed. They rendered nothing because the list reaching them
was empty. Asserted on both so a future key rename fails here rather than
quietly emptying the section again."""
from repowise.core.generation.page_generator import PageGenerator
from repowise.core.providers.llm.mock import MockProvider
assembler = ContextAssembler(sample_config)
gen = PageGenerator(MockProvider(), assembler, sample_config)
ctx = assembler.assemble_repo_overview(
sample_repo_structure, {}, [], {}, graph_builder=_Builder(flows)
)
out = gen._render(template, ctx=ctx, repo_git_summary=None)
assert "## Primary Execution Flows" in out
assert "packages/cli/src/repowise/cli/main.py::main" in out
assert "``" not in out.split("## Primary Execution Flows", 1)[1].split("##", 1)[0]
# ---------------------------------------------------------------------------
# the same field names, read by the other consumer
# ---------------------------------------------------------------------------
def test_how_it_works_flow_traces_carry_entry_point_and_score(flows):
"""``_collect_flows`` reads the same dataclass and had the same defect.
Its two ``getattr`` calls carried defaults, so instead of raising it
produced a ``FlowTrace`` with an empty entry point and a zero score for
every flow on every page ever generated.
"""
from types import SimpleNamespace
from repowise.core.generation.onboarding.subkinds.how_it_works import _collect_flows
long_enough = [
_flow("packages/cli/src/repowise/cli/main.py::main", 0.9, ["a", "b", "c", "d"]),
]
signals = SimpleNamespace(
graph_builder=SimpleNamespace(
execution_flows=lambda: ExecutionFlowReport(
total_entry_points_scored=1, total_flows=1, flows=long_enough
)
)
)
traces = _collect_flows(signals)
assert len(traces) == 1
assert traces[0].entry_point == "packages/cli/src/repowise/cli/main.py::main"
assert traces[0].score == pytest.approx(0.9)