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
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.pyindex 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_iddiff --git a/tests/unit/generation/test_layer_grouping_metadata.py b/tests/unit/generation/test_layer_grouping_metadata.pynew file mode 100644index 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"