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 planner: what the model can and cannot break, and what the validator sees.
The design claim this file exists to hold is narrow and testable: **naming is
the only thing the model decides**. Coverage, membership and page identity come
from the deterministic partition, so a model that skips half the groups, echoes
back ids that were never in the input, or returns nothing at all still leaves a
complete and correctly-identified outline behind.
"""
from __future__ import annotations
import pytest
from repowise.core.generation.concept_tree.grouping import (
GroupingParams,
group_files,
)
from repowise.core.generation.concept_tree.naming import (
build_payload,
decode_response,
deterministic_title,
)
from repowise.core.generation.concept_tree.planner import PlannerInputs, plan_outline
from repowise.core.generation.concept_tree.validation import validate_outline
TINY = GroupingParams(min_files=3, max_files=6)
FILES = [
"src/ingest/reader.py",
"src/ingest/parser.py",
"src/ingest/walker.py",
"src/ingest/cache.py",
"src/render/html.py",
"src/render/markdown.py",
"src/render/theme.py",
"src/render/layout.py",
]
TESTS = {"tests/test_reader.py"}
def _inputs() -> PlannerInputs:
return PlannerInputs(
repo_name="demo",
production_files=list(FILES),
layer_labels={"layer:core": "Core"},
test_files=set(TESTS),
)
class FakeProvider:
"""A provider whose reply is whatever the test needs it to be."""
def __init__(self, content: str):
self.content = content
self.calls: list[str] = []
async def generate(self, *, system_prompt, user_prompt, **kwargs):
self.calls.append(user_prompt)
class R:
content = self.content
return R()
class TestModelCannotBreakStructure:
@pytest.mark.asyncio
async def test_a_model_that_returns_nothing_still_covers_every_file(self):
_outline, report = await plan_outline(
_inputs(), provider=FakeProvider(""), params=TINY, repair=False
)
assert report.coverage == 1.0
assert report.unclaimed_files == []
assert report.ok
@pytest.mark.asyncio
async def test_a_model_that_invents_group_ids_does_not_add_pages(self):
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
data = {
"sections": [
{"title": "Made Up", "groups": ["g99", "gzz"]},
{"title": "Real", "groups": list(index)},
],
"names": {"g99": {"title": "Ghost Page", "scope": "x"}},
}
named, invented = decode_response(data, index)
assert invented == ["g99", "gzz"]
assert len(named) == len(index)
assert "Ghost Page" not in [n.title for n in named]
@pytest.mark.asyncio
async def test_a_model_that_skips_groups_leaves_them_named_anyway(self):
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
first = next(iter(index))
data = {"sections": [], "names": {first: {"title": "Real Title", "scope": "s"}}}
named, _ = decode_response(data, index)
assert len(named) == len(index)
skipped = [n for n in named if n.fallback]
assert skipped, "fixture must leave at least one group unnamed"
assert all(n.title for n in named)
def test_decode_survives_a_non_list_group_field(self):
"""A model asked for a list of ids returned a count instead.
``section.get("groups") or []`` passes a non-empty scalar straight
through to the loop, which raised. Asserted against ``decode_response``
directly, because the planner also wraps this call and a test that only
went through the planner would pass on the safety net alone.
"""
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
named, invented = decode_response(
{"sections": [{"title": "Core", "groups": 3}], "names": {}}, index
)
assert len(named) == len(index)
assert invented == []
def test_decode_ignores_group_ids_that_are_not_scalars(self):
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
named, _ = decode_response(
{"sections": [{"title": "Core", "groups": [{"a": 1}, ["b"], None]}], "names": {}},
index,
)
assert len(named) == len(index)
@pytest.mark.asyncio
async def test_a_non_list_group_field_does_not_crash_the_run(self):
"""The same malformed response, end to end through the planner."""
_outline, report = await plan_outline(
_inputs(),
provider=FakeProvider('{"sections":[{"title":"Core","groups":3}],"names":{}}'),
params=TINY,
repair=False,
)
assert report.coverage == 1.0
assert report.ok
@pytest.mark.asyncio
async def test_junk_types_in_the_response_are_ignored(self):
content = (
'{"sections": {"not": "a list"}, "names": {"g01": ["not", "a", "dict"], "g02": 7}}'
)
outline, report = await plan_outline(
_inputs(), provider=FakeProvider(content), params=TINY, repair=False
)
assert report.coverage == 1.0
assert report.ok
assert all(p.title for p in outline.pages)
@pytest.mark.asyncio
async def test_an_enormous_title_is_bounded(self):
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
gid = next(iter(index))
data = {"sections": [], "names": {gid: {"title": "Wildly " * 400, "scope": "s"}}}
named, _ = decode_response(data, index)
assert all(len(n.title) <= 120 for n in named)
@pytest.mark.asyncio
async def test_a_model_claiming_one_group_twice_places_it_once(self):
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
gid = next(iter(index))
data = {
"sections": [
{"title": "First", "groups": [gid]},
{"title": "Second", "groups": [gid]},
],
"names": {},
}
named, _ = decode_response(data, index)
assert sum(1 for n in named if n.group is index[gid]) == 1
class TestDeterministicPath:
@pytest.mark.asyncio
async def test_no_provider_still_produces_a_valid_outline(self):
outline, report = await plan_outline(_inputs(), provider=None, params=TINY)
assert outline.naming_mode == "deterministic"
assert report.coverage == 1.0
assert report.ok
@pytest.mark.asyncio
async def test_deterministic_mode_ignores_a_provider_that_is_present(self):
provider = FakeProvider('{"sections":[],"names":{}}')
outline, _ = await plan_outline(
_inputs(), provider=provider, deterministic=True, params=TINY
)
assert provider.calls == []
assert outline.naming_mode == "deterministic"
@pytest.mark.asyncio
async def test_the_keyless_tree_has_the_same_shape_as_the_named_one(self):
"""D5: adding a key changes the prose, never the partition."""
keyless, _ = await plan_outline(_inputs(), provider=None, params=TINY)
named, _ = await plan_outline(
_inputs(), provider=FakeProvider(""), params=TINY, repair=False
)
assert sorted(p.structural_key for p in keyless.pages) == sorted(
p.structural_key for p in named.pages
)
def test_deterministic_titles_are_not_bare_directory_names(self):
"""The name of this test is what it must actually assert.
A word-count bound alone would pass on "src ingest", which is the
exact failure the validator's bare-directory check exists to catch.
"""
from repowise.core.generation.concept_tree.validation import (
_is_bare_directory,
)
for group in group_files(FILES, params=TINY):
title = deterministic_title(group)
assert 2 <= len(title.split()) <= 7
assert not _is_bare_directory(title, group.dirs), title
class TestValidator:
def _outline(self):
from repowise.core.generation.concept_tree.models import (
ConceptOutline,
ConceptPage,
ConceptSection,
)
groups = group_files(FILES, params=TINY)
outline = ConceptOutline()
outline.sections.append(
ConceptSection(
title="All",
pages=[
ConceptPage(title=f"Page {i}", scope="s", group=g) for i, g in enumerate(groups)
],
)
)
outline.number_sections()
return outline
def test_a_clean_outline_has_no_hard_failures(self):
report = validate_outline(
self._outline(),
all_files=set(FILES),
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.hard_failures == []
def test_an_invented_member_is_a_hard_failure(self):
outline = self._outline()
outline.pages[0].group.members.append("src/ghost/nowhere.py")
report = validate_outline(
outline,
all_files=set(FILES),
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.invented_paths == ["src/ghost/nowhere.py"]
assert not report.ok
def test_an_unclaimed_file_is_a_hard_failure(self):
report = validate_outline(
self._outline(),
all_files=set(FILES) | {"src/orphan.py"},
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.unclaimed_files == ["src/orphan.py"]
assert not report.ok
def test_two_pages_on_one_target_path_is_a_hard_failure(self):
outline = self._outline()
outline.pages[1].group.target_path = outline.pages[0].group.target_path
report = validate_outline(
outline,
all_files=set(FILES),
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.duplicate_target_paths
assert not report.ok
def test_a_test_file_in_the_tree_is_a_hard_failure(self):
outline = self._outline()
outline.pages[0].group.members.append("tests/test_reader.py")
report = validate_outline(
outline,
all_files=set(FILES) | TESTS,
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.test_paths_included == ["tests/test_reader.py"]
assert not report.ok
def test_a_long_title_is_reported_but_does_not_block(self):
outline = self._outline()
outline.pages[0].title = "A Very Long Title That Runs On And On Forever Indeed"
report = validate_outline(
outline,
all_files=set(FILES),
test_files=TESTS,
max_files_per_page=TINY.max_files,
)
assert report.bad_length_titles
assert report.ok, "title length is taste, not correctness"
class TestPayload:
def test_group_ids_carry_no_path_information(self):
"""A fabricated id must be recognisable as fabricated."""
groups = group_files(FILES, params=TINY)
_payload, index = build_payload(groups)
for gid in index:
assert gid.startswith("g") and gid[1:].isdigit()
def test_filenames_are_sampled_across_every_directory(self):
"""A merged group must not be described by only one of its halves."""
from repowise.core.generation.concept_tree.grouping import ConceptGroup
group = ConceptGroup(
members=[f"src/aaa/a{i}.py" for i in range(6)] + [f"src/zzz/z{i}.py" for i in range(6)],
dirs=["src/aaa", "src/zzz"],
target_path="src/aaa",
)
payload, _ = build_payload([group], max_filenames=4)
names = payload["groups"][0]["names"]
assert any(n.startswith("a") for n in names)
assert any(n.startswith("z") for n in names), names
def test_entry_point_hints_are_ranked_not_alphabetical(self):
"""The hint is truncated to three, so the sort picks which three.
Alphabetical by basename put ``api.ts`` and the two barrels ahead of
``main.py``, and this feeds the prompt that names the group.
"""
from repowise.core.generation.concept_tree.grouping import ConceptGroup
members = [
"src/api.ts",
"src/deep/nested/index.ts",
"src/bootstrap.py",
"src/main.py",
"src/zzz/server.py",
]
group = ConceptGroup(members=members, dirs=["src"], target_path="src")
payload, _ = build_payload([group], entry_points=set(members))
assert payload["groups"][0]["entry_points"] == ["bootstrap.py", "main.py", "server.py"]
def test_entry_point_hints_only_cover_the_group(self):
"""A repo-wide entry set is filtered to this group's own members."""
from repowise.core.generation.concept_tree.grouping import ConceptGroup
group = ConceptGroup(members=["src/main.py"], dirs=["src"], target_path="src")
payload, _ = build_payload(
[group], entry_points={"src/main.py", "other/cli.py"}
)
assert payload["groups"][0]["entry_points"] == ["main.py"]
def test_sibling_directories_are_shown_relative_to_what_they_share(self):
from repowise.core.generation.concept_tree.grouping import ConceptGroup
group = ConceptGroup(
members=["src/git_indexer/a.py", "src/graph/b.py"],
dirs=["src/git_indexer", "src/graph"],
target_path="src/git_indexer",
)
payload, _ = build_payload([group])
assert sorted(payload["groups"][0]["subdirs"]) == ["git_indexer", "graph"]
def test_layer_prefixed_title_does_not_repeat_the_layer_word():
"""A ``docs`` group in a "Docs & Tooling" layer is not "Docs Tooling Docs".
The layer prefix exists to disambiguate a one-word directory name. When
the label already contains that word the prefix adds nothing and the
repetition reads as a generation bug.
"""
from repowise.core.generation.concept_tree.grouping import ConceptGroup
from repowise.core.generation.concept_tree.naming import deterministic_title
group = ConceptGroup(
members=["docs/conf.py", "docs/build.py"],
dirs=["docs"],
target_path="docs",
)
title = deterministic_title(group, "Docs Tooling")
assert title == "Docs Tooling"
assert title.lower().split().count("docs") == 1
def test_a_trailing_number_stays_with_its_word():
"""``c4`` is the C4 model, not a C and a 4.
The camel-case splitter treats a digit run as its own token, which is
right for ``v2Api`` and wrong for every directory whose name ends in a
number. Titles are the one place that leak is visible.
"""
from repowise.core.generation.concept_tree.grouping import ConceptGroup
from repowise.core.generation.concept_tree.naming import deterministic_title
group = ConceptGroup(
members=["src/ui/c4/nodes/a.ts", "src/ui/c4/nodes/b.ts"],
dirs=["src/ui/c4/nodes"],
target_path="src/ui/c4/nodes",
)
assert deterministic_title(group) == "C4 Nodes"
class TestCycleNaming:
"""A cycle page was titled by the hash of its members, which nothing searches for."""
def test_a_cycle_inside_one_subsystem_is_named_for_it(self):
from repowise.core.generation.concept_tree.naming import scc_where
assert (
scc_where(
[
"src/core/ingestion/resolvers/a.py",
"src/core/ingestion/resolvers/b.py",
]
)
== "Ingestion Resolvers"
)
def test_a_cycle_that_crosses_subsystems_names_the_biggest_two(self):
"""Crossing is the interesting thing about it, so the title says so."""
from repowise.core.generation.concept_tree.naming import scc_where
where = scc_where(
[
"tests/a.py",
"tests/b.py",
"tests/c.py",
"packages/x.py",
"packages/y.py",
"docs/d.py",
]
)
assert where == "Tests and Packages"
def test_a_crossing_cycle_breaks_size_ties_on_the_path(self):
"""So the title does not move between runs on an unchanged repository."""
from repowise.core.generation.concept_tree.naming import scc_where
assert scc_where(["zeta/a.py", "alpha/b.py"]) == "Alpha and Zeta"
def test_members_with_no_directory_yield_no_name(self):
"""Better to keep the id than to render a title claiming less than it."""
from repowise.core.generation.concept_tree.naming import scc_where
assert scc_where(["main.py"]) == ""
def test_the_name_is_stable_for_an_unchanged_cycle(self):
from repowise.core.generation.concept_tree.naming import scc_where
members = ["b/x.py", "a/y.py", "a/z.py"]
assert scc_where(sorted(members)) == scc_where(sorted(reversed(members)))
def test_titles_are_unique_across_the_run(self):
"""Several cycles through one subsystem all describe themselves the same."""
from repowise.core.generation.page_generator.levels import _scc_titles
titles = _scc_titles(
[
("scc-aaa", ["src/ingest/resolvers/a.py", "src/ingest/resolvers/b.py"]),
("scc-bbb", ["src/ingest/resolvers/c.py", "src/ingest/resolvers/d.py"]),
("scc-ccc", ["src/store/q.py", "src/store/r.py"]),
]
)
assert len(set(titles.values())) == 3
# The one that keeps the plain name is decided by path order, not by
# input order, so a re-run does not swap them.
assert titles["scc-ccc"] == "Circular Dependency: Store"
def test_a_nameless_cycle_falls_back_to_its_id(self):
from repowise.core.generation.page_generator.levels import _scc_titles
titles = _scc_titles([("scc-aaa", ["main.py"])])
assert titles["scc-aaa"] == "Circular Dependency: scc-aaa"
class TestTruncatedNamingIsVisible:
"""A ceiling hit must be said out loud.
Truncation and a model that simply returned nothing produce the identical
outline — the deterministic fallback — so without this the two are
indistinguishable in a log, and the fixable one looks like the normal one.
"""
class TruncatingProvider:
async def generate(self, *, system_prompt, user_prompt, **kwargs):
class R:
content = '{"names": {"g1": {"title": "Half A' # cut mid-JSON
stop_reason = "max_tokens"
provider_stop_reason = "length"
return R()
@pytest.mark.asyncio
async def test_a_truncated_reply_is_logged(self):
from structlog.testing import capture_logs
with capture_logs() as logs:
_outline, report = await plan_outline(
_inputs(), provider=self.TruncatingProvider(), params=TINY, repair=False
)
events = [entry["event"] for entry in logs]
assert "concept_outline_naming_truncated" in events
# The outline is still complete — this is a visibility fix, not a
# behaviour change.
assert report.coverage == 1.0