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
fix(generation): keep concept pages local, never merge unrelated top-level dirs (#1280)
Sergei Iakhnitskiifa15c573bd91
diff --git a/packages/core/src/repowise/core/generation/concept_tree/grouping.py b/packages/core/src/repowise/core/generation/concept_tree/grouping.pyindex 8a5ba8ba0..4f54a9a07 100644--- a/packages/core/src/repowise/core/generation/concept_tree/grouping.py+++ b/packages/core/src/repowise/core/generation/concept_tree/grouping.py@@ -224,6 +224,25 @@ def _target_path(members: Sequence[str], dirs: Sequence[str]) -> str:return "/".join(common)+def _is_local_merge(left: Sequence[str], right: Sequence[str]) -> bool:+ """Whether two runs may form one page without becoming a scattering.++ Local means the union sits under a real shared directory, or both runs are+ root-level files that legitimately co-locate at the repository root. Two runs+ whose only common ancestor is the repository root but that live in different+ top-level directories are the scattering this module's contract promises never+ to emit, and must stay separate pages even when each is thin.++ Deliberately loose: *any* shared directory qualifies, not the same immediate+ parent. Tightening it to same-parent fragments the outline to prevent a+ bleed no reader perceives; the break readers report is the cross-top-level+ one.+ """+ if _target_path([*left, *right], []):+ return True+ return all("/" not in m for m in left) and all("/" not in m for m in right)++class _Partitioner:def __init__(self, params: GroupingParams, layer_of_file: dict[str, str]):self.params = params@@ -279,8 +298,10 @@ class _Partitioner:left = self.visit(child)if not left:continue- if len(pending) + len(left) <= self.params.max_files and self._same_layer(- pending, left+ if (+ len(pending) + len(left) <= self.params.max_files+ and self._same_layer(pending, left)+ and _is_local_merge(pending, left)):pending.extend(left)continue@@ -296,8 +317,10 @@ class _Partitioner:# result still fits.if pending and len(pending) < self.params.min_files and self.groups:last = self.groups[-1]- if len(last.members) + len(pending) <= self.params.max_files and self._same_layer(- last.members, pending+ if (+ len(last.members) + len(pending) <= self.params.max_files+ and self._same_layer(last.members, pending)+ and _is_local_merge(last.members, pending)):merged = self.make(last.members + pending)self.groups[-1] = merged@@ -337,6 +360,8 @@ def _absorb_thin(groups: list[ConceptGroup], part: _Partitioner) -> list[Conceptother = working[j]if other.file_count + group.file_count > params.max_files:continue+ if not _is_local_merge(other.members, group.members):+ continue# A same-layer neighbour is preferred, but a thin group takes# a cross-layer neighbour over standing alone. The layer gate# exists to stop a page spanning two subsystems; it should not@@ -397,6 +422,12 @@ def _assign_targets(groups: list[ConceptGroup]) -> None:for group in sorted(groups, key=lambda g: (-g.file_count, g.structural_key)):owned = _target_path(group.members, group.dirs)candidates = [owned] if owned in group.dirs else []+ # A whole repository under the ceiling is one group spanning several+ # top-level directories — the guard cannot refuse it, there is nothing+ # to merge. Naming it after a member would put the repository under a+ # name describing one corner of it, so it takes the root.+ if not owned and "" not in candidates and len({m.split("/")[0] for m in group.members}) > 1:+ candidates.append("")candidates.extend(d for d in group.dirs if d and d not in candidates)if owned and owned not in candidates:candidates.append(owned)diff --git a/tests/unit/generation/test_concept_grouping.py b/tests/unit/generation/test_concept_grouping.pyindex 6cdfb8e37..a7dfb44a3 100644--- a/tests/unit/generation/test_concept_grouping.py+++ b/tests/unit/generation/test_concept_grouping.py@@ -361,3 +361,116 @@ class TestLayers:first = group_files(files, layer_of_file=layers, params=TINY)[0]second = group_files(list(reversed(files)), layer_of_file=layers, params=TINY)[0]assert first.dominant_layer == second.dominant_layer+++class TestLocality:+ """A group is a subtree or a run of adjacent siblings, never a scattering.++ The partition can leave a directory below the min-files floor, and the walk+ and the absorption pass both look for a neighbour to fold it into. A+ neighbour under a shared parent is a run of adjacent siblings; a neighbour+ whose only common ancestor is the repository root is a different top-level+ subsystem, and merging the two produces a page that describes one directory+ under another's name. These assert the merge is refused in that case even+ though a thin page is the price.+ """++ @staticmethod+ def _one_place(group) -> bool:+ # A group is local when its members share a single top-level directory,+ # or are all root-level files (whose shared directory is the root).+ if all("/" not in m for m in group.members):+ return True+ return len({m.split("/")[0] for m in group.members}) == 1++ def test_thin_unrelated_top_level_dirs_do_not_merge(self):+ # alpha+beta+gamma fit one 6-file page under the ceiling, but share only+ # the repository root; merging them would be a scattering across three+ # subsystems named after one.+ files = _repo({"alpha": 2, "beta": 2, "gamma": 2, "delta": 1})+ groups = group_files(files, params=TINY)+ assert all(self._one_place(g) for g in groups)++ def test_the_scattering_becomes_thin_local_pages_not_one_mislabelled_page(self):+ # The explicit trade: four isolated thin top-level dirs become four thin+ # pages, not one 7-file page titled after whichever sorts first. A thin+ # local page is the intended outcome, per _absorb_thin's own comment.+ files = _repo({"alpha": 2, "beta": 2, "gamma": 2, "delta": 1})+ groups = group_files(files, params=TINY)+ assert {g.target_path for g in groups} == {"alpha", "beta", "gamma", "delta"}+ assert any(g.file_count < TINY.min_files for g in groups)++ def test_a_root_file_is_not_absorbed_into_a_subtree(self):+ # A lone root file shares no directory with a subtree; it stays its own+ # page rather than being folded in and mis-attributed to that subtree.+ # ``zzz/big`` keeps the repo over the ceiling so the root file is a+ # leftover the walk would otherwise merge into ``src/alpha`` (1+3 fits).+ files = _repo({"": 1, "src/alpha": 3, "zzz/big": 5})+ groups = group_files(files, params=TINY)+ assert all(self._one_place(g) for g in groups)+ alpha = next(g for g in groups if "alpha" in g.target_path)+ assert all("/" in m for m in alpha.members)++ def test_root_level_files_are_not_fragmented(self):+ # A rule keyed on a shared *named* directory would refuse these, the+ # root having no name, and five one-file pages would be the result.+ files = _repo({"": 5, "zzz/big": 6})+ root_group = next(+ g for g in group_files(files, params=TINY) if any("/" not in m for m in g.members)+ )+ assert all("/" not in m for m in root_group.members)+ assert root_group.file_count == 5, "the five root files were split apart"++ def test_adjacent_siblings_under_one_parent_still_merge(self):+ # ``src`` holds 8 against a ceiling of 6, so the walk descends and the+ # guard is consulted; under a fitting parent recursion stops above the+ # children and no merge decision is made at all.+ files = _repo({"src/alpha": 2, "src/beta": 3, "src/gamma": 3})+ groups = group_files(files, params=TINY)++ merged = next(g for g in groups if any("/alpha/" in m for m in g.members))+ # Member directories, not the shared top-level: refusing every merge+ # leaves alpha on its own page, which is still under ``src``.+ assert {m.split("/")[1] for m in merged.members} == {"alpha", "beta"}+ assert merged.file_count == 5++ def test_totality_and_determinism_hold_under_the_guard(self):+ files = _repo({"alpha": 2, "beta": 2, "gamma": 2, "delta": 1})++ def sig(groups):+ return [(g.target_path, tuple(g.members)) for g in groups]++ # Reversed input, not a second identical call: two calls in one process+ # share a hash seed and cannot detect an ordering dependence.+ assert sig(group_files(files, params=TINY)) == sig(+ group_files(list(reversed(files)), params=TINY)+ )+ claimed = [m for g in group_files(files, params=TINY) for m in g.members]+ assert sorted(claimed) == sorted(files)+ assert len(claimed) == len(set(claimed))++ def test_a_whole_repository_that_fits_is_named_for_the_root(self):+ """One page for a tiny repository is right; naming it after a member is not.++ A repository under the ceiling comes back as one run, so there is no+ merge to refuse — only a name to choose, and every candidate but the+ root describes one corner of it.+ """+ # Default params, not TINY: params_for(9) allows 14, so this is the+ # shape a real small repository has.+ files = _repo({"cmd/serve": 3, "internal/store": 4, "scripts": 2})+ groups = group_files(files)++ assert len(groups) == 1, "a repository under the ceiling is one page"+ assert groups[0].target_path == "root"++ def test_a_whole_repository_under_one_directory_keeps_that_directory(self):+ """The root name is for a span, not for every one-group repository.++ Files all under one directory have an honest name to keep; without+ this the rescue above would rename every small repository's only page.+ """+ groups = group_files(_repo({"src/app": 6}))++ assert len(groups) == 1+ assert groups[0].target_path == "src/app"diff --git a/tests/unit/generation/test_selection_concept_groups.py b/tests/unit/generation/test_selection_concept_groups.pyindex c0dc1f9ca..de527dad1 100644--- a/tests/unit/generation/test_selection_concept_groups.py+++ b/tests/unit/generation/test_selection_concept_groups.py@@ -320,17 +320,26 @@ def test_display_is_a_name_not_a_bare_path():def test_layer_labels_from_the_kg_reach_the_title():- """The KG layer map is read when present and absent-safe when not."""+ """The KG layer map is read when present and absent-safe when not.++ The rescue only fires on a name too short to say anything, so the fixture is+ a single directory whose path yields one word (``gateway`` -> "Gateway").+ A group that already yields two words needs no prefix and would show the+ feature nothing either way — the earlier fixture only exercised this because+ a grouping bug had swept its files into a one-word "root" page.+ """+ gateway = [f"packages/app/src/gateway/f{i}.py" for i in range(8)]+ paths = gateway + [f"packages/app/src/core/analysis/f{i}.py" for i in range(8)] + ["setup.py"]modules = [{- "id": "module:ui-c4",- "path": "packages/app/src/ui/c4",+ "id": "module:gateway",+ "path": "packages/app/src/gateway","layerId": "layer:presentation",- "nodeIds": [f"file:{p}" for p in _paths() if "/ui/c4/" in p],+ "nodeIds": [f"file:{p}" for p in gateway],}]- with_kg = [g for _, g in _build_module_groups(_inputs(kg_modules=modules)).scored]- without_kg = [g for _, g in _build_module_groups(_inputs()).scored]+ with_kg = [g for _, g in _build_module_groups(_inputs(paths=paths, kg_modules=modules)).scored]+ without_kg = [g for _, g in _build_module_groups(_inputs(paths=paths)).scored]# Membership is unchanged by the layer signal: it steers merging of# adjacent runs, it never forces a split.