Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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[Concept
other = 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.py
index 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.py
index 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.