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.

feat(generation): stamp layer provenance on the pages a layer groups (#1165)

Swati Ahuja4f1b227d330d
diff --git a/packages/core/src/repowise/core/generation/page_tree.py b/packages/core/src/repowise/core/generation/page_tree.py
index 40d9f6092..387e577cf 100644
--- a/packages/core/src/repowise/core/generation/page_tree.py
+++ b/packages/core/src/repowise/core/generation/page_tree.py
@@ -194,14 +194,37 @@ def assign_page_tree(
# A file's layer comes from the provenance stamped on it at generation
# time. Keyed on layer_id, never the display name, which drifts.
layer_of_file: dict[str, str] = {}
+ # Display name per layer id, borrowed from the files that carry both. The
+ # id is a slug and turning it back into a name is lossy, so the curated
+ # name is read rather than derived.
+ layer_name_by_id: dict[str, str] = {}
for page in by_type.get("file_page", []):
lid = page.metadata.get("layer_id")
if isinstance(lid, str) and lid:
layer_of_file[page.target_path] = lid
+ name = page.metadata.get("layer_name")
+ if isinstance(name, str) and name:
+ layer_name_by_id.setdefault(lid, name)
def layer_parent(layer_id: str) -> str | None:
return f"layer_page:{layer_id}" if layer_id in layer_ids else root_id
+ def stamp_layer(page: TreeNode, layer_id: str) -> None:
+ """Record which layer a page belongs to, on the page itself.
+
+ A reader-facing tree groups by this rather than by parenting the page
+ onto a layer page, so the grouping survives those pages not existing.
+ Nothing is stamped when the layer could not be resolved: absent is
+ honest, whereas a placeholder id would collect unrelated pages under
+ one heading.
+ """
+ if not layer_id:
+ return
+ page.metadata["layer_id"] = layer_id
+ name = layer_name_by_id.get(layer_id)
+ if name:
+ page.metadata["layer_name"] = name
+
# --- Modules sit under their dominant layer ----------------------------
module_paths: list[str] = []
# Which module claims each file. A module's target_path is a directory
@@ -271,7 +294,9 @@ def assign_page_tree(
)
borrowed.extend(m for m in child_members if isinstance(m, str))
members = borrowed
- page.parent_page_id = layer_parent(_dominant_layer(members, layer_of_file))
+ module_layer = _dominant_layer(members, layer_of_file)
+ stamp_layer(page, module_layer)
+ page.parent_page_id = layer_parent(module_layer)
# A spotlight belongs to the file it documents: "path/to/file.py::Symbol".
# The file's own page may not exist: selection can spotlight a symbol in a
@@ -291,7 +316,9 @@ def assign_page_tree(
for page in by_type.get("scc_page", []):
members = page.metadata.get("files") or page.metadata.get("file_paths") or []
members = [m for m in members if isinstance(m, str)]
- page.parent_page_id = layer_parent(_dominant_layer(members, layer_of_file))
+ scc_layer = _dominant_layer(members, layer_of_file)
+ stamp_layer(page, scc_layer)
+ page.parent_page_id = layer_parent(scc_layer)
for page in by_type.get("layer_page", []):
page.parent_page_id = root_id
diff --git a/tests/unit/generation/test_layer_grouping_metadata.py b/tests/unit/generation/test_layer_grouping_metadata.py
new file mode 100644
index 000000000..570eeb8d2
--- /dev/null
+++ b/tests/unit/generation/test_layer_grouping_metadata.py
@@ -0,0 +1,119 @@
+"""Layers group the docs tree without needing a page to hang it off.
+
+The tree used to express "this module belongs to the Analysis layer" by
+parenting the module onto the *Analysis layer page*. That made a reading page
+carry a structural job: the only way to keep the grouping was to keep eleven
+pages whose whole content was a restatement of the same template, and which
+scored as near-duplicates of each other.
+
+The grouping moves onto the pages that are grouped. Every page that belongs to
+a layer carries that layer's id and display name, so a reader-facing tree can
+build the layer rows itself — the same way the Onboarding folder is already
+built from a slot stamped on its members rather than from a page.
+
+``layer_id`` is the join key and is always a stable slug; ``layer_name`` is
+display text and may drift, so nothing keys on it.
+"""
+
+from __future__ import annotations
+
+from repowise.core.generation.page_tree import TreeNode, assign_page_tree
+
+
+def _node(page_id: str, page_type: str, target_path: str, **metadata) -> TreeNode:
+ return TreeNode(
+ page_id=page_id,
+ page_type=page_type,
+ target_path=target_path,
+ metadata=dict(metadata),
+ )
+
+
+def _repo() -> list[TreeNode]:
+ """An overview, two layers' worth of files, a module and a cycle."""
+ return [
+ _node("repo_overview:demo", "repo_overview", "demo"),
+ _node(
+ "file_page:core/analysis/health.py",
+ "file_page",
+ "core/analysis/health.py",
+ layer_id="layer:analysis",
+ layer_name="Analysis",
+ ),
+ _node(
+ "file_page:core/analysis/risk.py",
+ "file_page",
+ "core/analysis/risk.py",
+ layer_id="layer:analysis",
+ layer_name="Analysis",
+ ),
+ _node(
+ "file_page:core/ingestion/walker.py",
+ "file_page",
+ "core/ingestion/walker.py",
+ layer_id="layer:ingestion",
+ layer_name="Ingestion",
+ ),
+ _node(
+ "module_page:core/analysis",
+ "module_page",
+ "core/analysis",
+ file_paths=["core/analysis/health.py", "core/analysis/risk.py"],
+ ),
+ _node(
+ "scc_page:cycle-1",
+ "scc_page",
+ "cycle-1",
+ files=["core/analysis/health.py", "core/analysis/risk.py"],
+ ),
+ ]
+
+
+def _by_id(nodes: list[TreeNode]) -> dict[str, TreeNode]:
+ return {n.page_id: n for n in nodes}
+
+
+class TestLayerProvenanceReachesGroupedPages:
+ def test_module_carries_the_layer_it_belongs_to(self):
+ nodes = _repo()
+ assign_page_tree(nodes, ["layer:ingestion", "layer:analysis"])
+ module = _by_id(nodes)["module_page:core/analysis"]
+ assert module.metadata["layer_id"] == "layer:analysis"
+ assert module.metadata["layer_name"] == "Analysis"
+
+ def test_cycle_carries_the_layer_it_belongs_to(self):
+ nodes = _repo()
+ assign_page_tree(nodes, ["layer:ingestion", "layer:analysis"])
+ cycle = _by_id(nodes)["scc_page:cycle-1"]
+ assert cycle.metadata["layer_id"] == "layer:analysis"
+ assert cycle.metadata["layer_name"] == "Analysis"
+
+ def test_display_name_comes_from_the_files_not_the_slug(self):
+ """The slug is derived and lossy; the name is the one the KG curated."""
+ nodes = _repo()
+ for n in nodes:
+ if n.metadata.get("layer_id") == "layer:analysis":
+ n.metadata["layer_name"] = "Analysis & Scoring"
+ assign_page_tree(nodes, ["layer:analysis"])
+ module = _by_id(nodes)["module_page:core/analysis"]
+ assert module.metadata["layer_name"] == "Analysis & Scoring"
+
+ def test_a_page_with_no_resolvable_layer_is_not_stamped(self):
+ """Absent is honest; a made-up layer id would group pages wrongly."""
+ nodes = [
+ _node("repo_overview:demo", "repo_overview", "demo"),
+ _node("module_page:misc", "module_page", "misc", file_paths=["misc/a.py"]),
+ ]
+ assign_page_tree(nodes, [])
+ module = _by_id(nodes)["module_page:misc"]
+ assert "layer_id" not in module.metadata
+
+ def test_grouping_does_not_depend_on_a_layer_page_existing(self):
+ """The whole point: no layer_page in the set, grouping still resolves."""
+ nodes = _repo()
+ assert not any(n.page_type == "layer_page" for n in nodes)
+ assign_page_tree(nodes, ["layer:analysis"])
+ module = _by_id(nodes)["module_page:core/analysis"]
+ assert module.metadata["layer_id"] == "layer:analysis"
+ # And it parents onto the overview rather than a page that is not there.
+ assert module.parent_page_id == "repo_overview:demo"