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): layers group the docs tree without a page to hang it off (#1171)

Swati Ahuja8d52ff7ce661
diff --git a/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py b/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py
index 2e9fed723..7cb32634b 100644
--- a/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py
+++ b/packages/cli/src/repowise/cli/commands/generate_cmd/scope.py
@@ -10,7 +10,6 @@ from __future__ import annotations
from repowise.core.generation.scope import (
ScopePlan,
- _layer_membership,
_ranked_ids_to_seed,
_selection_inputs,
build_cost_plans,
@@ -23,7 +22,6 @@ from repowise.core.generation.scope import (
__all__ = [
"ScopePlan",
- "_layer_membership",
"_ranked_ids_to_seed",
"_selection_inputs",
"build_cost_plans",
diff --git a/packages/core/src/repowise/core/generation/cascade.py b/packages/core/src/repowise/core/generation/cascade.py
index 5d8c69c2f..aa55494cf 100644
--- a/packages/core/src/repowise/core/generation/cascade.py
+++ b/packages/core/src/repowise/core/generation/cascade.py
@@ -1,8 +1,8 @@
"""Cascade policy for scoped generation.
Regenerating a file page makes the pages that summarize it drift: its module
-page, the cycle (SCC) pages it belongs to, its architectural layer page, and
-the repo-wide overview / architecture / onboarding pages. Backlinks on other
+page, the cycle (SCC) pages it belongs to, and the repo-wide overview and
+onboarding pages. Backlinks on other
pages that point at it also go stale. The healer ``backfill_related_pages``
repairs backlinks LLM-free after any run; this module decides what to do about
the *content* of the dependent pages.
@@ -11,12 +11,12 @@ Three policies, chosen by the user:
* ``none`` — generate exactly what was asked; mark every structural dependent
stale (truthful, free, instant).
-* ``dependents`` — also regenerate the module, SCC and layer pages that
- contain a seeded file; mark the repo-wide pages stale.
+* ``dependents`` — also regenerate the module and SCC pages that contain a
+ seeded file; mark the repo-wide pages stale.
* ``full`` — also regenerate the repo-wide pages. Nothing is left stale.
-The dependent set is computed structurally from the selection graph and KG
-layer membership, so it is exact rather than a heuristic cascade.
+The dependent set is computed structurally from the selection graph, so it is
+exact rather than a heuristic cascade.
"""
from __future__ import annotations
@@ -36,26 +36,26 @@ _FILE_PAGE_PREFIX = "file_page:"
class PageDependencies:
"""Which container pages each file page rolls up into.
- Built once per run from the in-memory selection and KG layers. All values
- are page ids (``module_page:...``, ``scc_page:...``, ``layer_page:...``),
- ready to drop straight into an ``only_page_ids`` set.
+ Built once per run from the in-memory selection. All values are page ids
+ (``module_page:...``, ``scc_page:...``), ready to drop straight into an
+ ``only_page_ids`` set.
+
+ Layers used to appear here as a third container. They no longer have pages
+ of their own, so a file rolls up into nothing at that altitude and there is
+ nothing to regenerate when it changes.
"""
module_page_of: dict[str, str] = field(default_factory=dict)
scc_pages_of: dict[str, tuple[str, ...]] = field(default_factory=dict)
- layer_page_of: dict[str, str] = field(default_factory=dict)
repo_wide_ids: tuple[str, ...] = ()
def containers_of(self, file_path: str) -> set[str]:
- """Module + SCC + layer page ids that summarize *file_path*."""
+ """Module + SCC page ids that summarize *file_path*."""
ids: set[str] = set()
mod = self.module_page_of.get(file_path)
if mod:
ids.add(mod)
ids.update(self.scc_pages_of.get(file_path, ()))
- layer = self.layer_page_of.get(file_path)
- if layer:
- ids.add(layer)
return ids
@@ -76,7 +76,6 @@ def build_page_dependencies(
*,
module_groups: Iterable[Any],
scc_groups: Iterable[tuple[str, Iterable[str]]],
- layer_page_of: dict[str, str] | None = None,
repo_wide_ids: Iterable[str] = (),
) -> PageDependencies:
"""Invert the selection groups into per-file container page ids.
@@ -84,8 +83,6 @@ def build_page_dependencies(
``module_groups`` are duck-typed selection ``ModuleGroup`` objects (``.key``
+ ``.file_paths``); ``scc_groups`` are ``(scc_id, files)`` pairs, exactly as
:class:`~repowise.core.generation.selection.Selection` carries them.
- ``layer_page_of`` maps a file path to its ``layer_page:<id>`` (from KG layer
- membership; empty when the repo has no KG).
"""
module_page_of: dict[str, str] = {}
for group in module_groups:
@@ -102,7 +99,6 @@ def build_page_dependencies(
return PageDependencies(
module_page_of=module_page_of,
scc_pages_of={p: tuple(v) for p, v in scc_pages_of.items()},
- layer_page_of=dict(layer_page_of or {}),
repo_wide_ids=tuple(repo_wide_ids),
)
@@ -119,7 +115,7 @@ def expand_cascade(
) -> CascadeResult:
"""Expand *seed_ids* into the pages to generate and the pages to mark stale.
- The container set (module/SCC/layer pages of the seeded files) and the
+ The container set (module/SCC pages of the seeded files) and the
repo-wide set are the two rings of fallout. ``none`` regenerates neither and
marks both stale; ``dependents`` regenerates the containers and marks
repo-wide stale; ``full`` regenerates both and marks nothing.
diff --git a/packages/core/src/repowise/core/generation/context/__init__.py b/packages/core/src/repowise/core/generation/context/__init__.py
index 86d932007..04ec90785 100644
--- a/packages/core/src/repowise/core/generation/context/__init__.py
+++ b/packages/core/src/repowise/core/generation/context/__init__.py
@@ -14,7 +14,6 @@ from .contexts import (
ArchitectureDiagramContext,
FilePageContext,
InfraPageContext,
- LayerPageContext,
ModulePageContext,
RepoOverviewContext,
SccPageContext,
@@ -28,7 +27,6 @@ __all__ = [
"ContextAssembler",
"FilePageContext",
"InfraPageContext",
- "LayerPageContext",
"ModulePageContext",
"RepoOverviewContext",
"SccPageContext",
diff --git a/packages/core/src/repowise/core/generation/context/contexts.py b/packages/core/src/repowise/core/generation/context/contexts.py
index 47662b98b..0a85be3af 100644
--- a/packages/core/src/repowise/core/generation/context/contexts.py
+++ b/packages/core/src/repowise/core/generation/context/contexts.py
@@ -53,8 +53,8 @@ class FilePageContext:
decision_records: list[dict] = field(default_factory=list)
# KG layer context (populated when knowledge graph available)
kg_layer_name: str = ""
- # Stable slug id of the layer (``layer:<slug>``) — used to join a file
- # page to its layer page; ``kg_layer_name`` is the mutable display label.
+ # Stable slug id of the layer (``layer:<slug>``) — the key the docs tree
+ # groups on; ``kg_layer_name`` is the mutable display label, never a key.
kg_layer_id: str = ""
kg_layer_description: str = ""
kg_layer_role: str = ""
@@ -83,7 +83,7 @@ class SymbolSpotlightContext:
class ModulePageContext:
# The page's display title. A concept group spans several directories and
# is named for what it does, so this is prose ("Ingestion Pipeline") and
- # not a path. Same split as LayerPageContext's layer_name/layer_id: what
+ # not a path. Same split as the layer name/id pair on a file page: what
# the reader sees is separate from what the page is keyed by, and only the
# key is stable across regenerations.
title: str
@@ -139,25 +139,6 @@ class ModulePageContext:
top_owners: list[dict] = field(default_factory=list)
-@dataclass
-class LayerPageContext:
- layer_name: str
- layer_description: str
- file_count: int
- # Stable slug id (``layer:<slug>``) — the layer page's target_path and
- # page_id derive from this, never from the mutable ``layer_name``.
- layer_id: str = ""
- key_files: list[dict] = field(default_factory=list)
- deps_out: list[dict] = field(default_factory=list)
- deps_in: list[dict] = field(default_factory=list)
- tour_steps: list[dict] = field(default_factory=list)
- entry_points: list[str] = field(default_factory=list)
- edge_connectors: list[str] = field(default_factory=list)
- # Deterministic per-layer architecture diagram (mermaid source), embedded
- # into the page after generation. Empty when the KG can't produce one.
- diagram_mermaid: str = ""
-
-
@dataclass
class SccPageContext:
scc_id: str
diff --git a/packages/core/src/repowise/core/generation/context_assembler.py b/packages/core/src/repowise/core/generation/context_assembler.py
index 85988da27..1d70ae200 100644
--- a/packages/core/src/repowise/core/generation/context_assembler.py
+++ b/packages/core/src/repowise/core/generation/context_assembler.py
@@ -18,7 +18,6 @@ from .context import (
ContextAssembler,
FilePageContext,
InfraPageContext,
- LayerPageContext,
ModulePageContext,
RepoOverviewContext,
SccPageContext,
@@ -33,7 +32,6 @@ __all__ = [
"ContextAssembler",
"FilePageContext",
"InfraPageContext",
- "LayerPageContext",
"ModulePageContext",
"RepoOverviewContext",
"SccPageContext",
diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.py
index 2374b6a69..45ecb93fc 100644
--- a/packages/core/src/repowise/core/generation/page_generator/levels.py
+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py
@@ -15,7 +15,6 @@ import structlog
from repowise.core.ids import is_external
-from ...analysis.knowledge_graph import _slugify
from .. import onboarding as _onboarding
from ..context_assembler import FilePageContext
from ..models import compute_page_id
@@ -274,87 +273,6 @@ def build_level4_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
return coros
-def build_level5_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
- """Level 5 (layer_page): one page per KG layer with >= 3 files."""
- gen = run.gen
- coros: list[tuple[str, Any]] = []
- if not run.kg_ctx.available:
- return coros
-
- from ..architecture_mermaid import ArchitectureMermaidBuilder
- from ..context_assembler import LayerPageContext
-
- min_layer_files = 3
-
- # One builder per run: indexes the graph once, then draws each layer.
- diagram_builder = ArchitectureMermaidBuilder(run.kg_ctx)
-
- for layer in run.kg_ctx.get_layers():
- node_ids = layer.get("nodeIds", [])
- file_paths = [nid[5:] for nid in node_ids if nid.startswith("file:")]
- if len(file_paths) < min_layer_files:
- continue
-
- layer_name = layer.get("name", "")
- # Key the page by the layer's STABLE slug id (``layer:<slug>``), not its
- # display name: the LLM layer-name enrichment rewrites ``name`` after
- # generation, so a name-keyed page would no longer join to its KG layer.
- # ``id`` is derived from the deterministic heuristic name at curation
- # time and never changes under enrichment.
- layer_id = layer.get("id", "") or f"layer:{_slugify(layer_name)}"
- page_id = compute_page_id("layer_page", layer_id)
- if not run._emit(page_id):
- continue
-
- key_files: list[dict] = []
- entry_points: list[str] = []
- edge_connectors: list[str] = []
- tour_steps_seen: set[int] = set()
- tour_steps: list[dict] = []
-
- ranked = sorted(
- file_paths,
- key=lambda p: run.pagerank.get(p, 0.0),
- reverse=True,
- )
- for fp in ranked[:10]:
- fc = run.kg_ctx.get_file_context(fp)
- entry: dict = {
- "path": fp,
- "role": fc.role if fc else "internal",
- "summary": (run.completed_page_summaries.get(fp) or "")[:200],
- }
- key_files.append(entry)
- if fc:
- if fc.role == "entry_point":
- entry_points.append(fp)
- elif fc.role == "edge_connector":
- edge_connectors.append(fp)
- if fc.tour_step and fc.tour_step["order"] not in tour_steps_seen:
- tour_steps_seen.add(fc.tour_step["order"])
- tour_steps.append(fc.tour_step)
-
- deps_out, deps_in = run.kg_ctx.get_inter_layer_edges(layer)
- tour_steps.sort(key=lambda s: s["order"])
-
- ctx = LayerPageContext(
- layer_name=layer_name,
- layer_id=layer_id,
- layer_description=layer.get("description", ""),
- file_count=len(file_paths),
- key_files=key_files,
- deps_out=deps_out,
- deps_in=deps_in,
- tour_steps=tour_steps,
- entry_points=entry_points,
- edge_connectors=edge_connectors,
- diagram_mermaid=diagram_builder.layer(layer) or "",
- )
- coros.append((page_id, gen.generate_layer_page(ctx)))
-
- return coros
-
-
def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
"""Level 6 (repo_overview).
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index 112bfedb9..6ba5032ff 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -436,13 +436,6 @@ class _GenerationRun:
return
counts = self.selection.counts()
- layer_page_count = 0
- if self.kg_ctx.available:
- layer_page_count = sum(
- 1
- for layer in self.kg_ctx.get_layers()
- if len([n for n in layer.get("nodeIds", []) if n.startswith("file:")]) >= 3
- )
# Level-8 onboarding pages (the non-promoted slots) also emit, and
# were previously omitted here, which made the progress total read
# lower than the pages actually generated (issue #922: "43 of 41").
@@ -462,7 +455,6 @@ class _GenerationRun:
+ counts["file_page"]
+ counts["scc_page"]
+ counts["module_page"]
- + layer_page_count
+ int(self.selection.emit_repo_overview)
+ counts["infra_page"]
+ onboarding_page_count
@@ -707,11 +699,12 @@ class _GenerationRun:
# Level 4 (module_page).
all_pages.extend(await self.run_level(_levels.build_level4_coros(self), 4))
- # Level 5 (layer_page) — one page per KG layer.
- all_pages.extend(await self.run_level(_levels.build_level5_coros(self), 5))
-
- # Levels 6 (repo_overview + architecture_diagram), 7 (infra_page),
- # and 8 (onboarding) share no data dependencies — run merged.
+ # Level 5 was one page per KG layer. Those pages retired: the layer a
+ # page belongs to is stamped on the page itself, so the docs tree can
+ # group by it without a page to hang the group off.
+ #
+ # Levels 6 (repo_overview), 7 (infra_page), and 8 (onboarding) share
+ # no data dependencies — run merged.
final = (
_levels.build_level6_coros(self)
+ _levels.build_level7_coros(self)
diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.py
index b2f173787..985ec5cb0 100644
--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py
+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py
@@ -18,7 +18,7 @@ from repowise.core.ingestion.models import ParsedFile, RepoStructure
from .. import onboarding as _onboarding
from ..architecture_mermaid import embed_mermaid
-from ..context_assembler import FilePageContext, LayerPageContext
+from ..context_assembler import FilePageContext
from ..models import (
GENERATION_LEVELS,
STUB_FALLBACK_ERROR,
@@ -465,16 +465,6 @@ class PerTypeGenerationMixin:
if slot is not None:
page.metadata["onboarding_slot"] = slot
- async def generate_layer_page(
- self,
- ctx: LayerPageContext,
- ) -> GeneratedPage:
- # target_path = the layer's STABLE slug id (the renderer reads it off
- # ctx), so the page key survives a rename of ``layer_name``. The title
- # still uses the display name. The template embeds ctx.diagram_mermaid
- # itself, so there is no separate embed_mermaid step on this path.
- return self._structural_layer_page(ctx, f"Layer: {ctx.layer_name}")
-
async def generate_infra_page(
self,
parsed: ParsedFile,
diff --git a/packages/core/src/repowise/core/generation/page_generator/structural.py b/packages/core/src/repowise/core/generation/page_generator/structural.py
index 7f6797d02..19c7fbee8 100644
--- a/packages/core/src/repowise/core/generation/page_generator/structural.py
+++ b/packages/core/src/repowise/core/generation/page_generator/structural.py
@@ -3,7 +3,7 @@
Two different jobs share this machinery, and telling them apart matters:
**Sole renderers.** ``file_page``, ``symbol_spotlight``, ``api_contract``,
-``infra_page``, ``scc_page`` and ``layer_page`` state facts a parser knows
+``infra_page`` and ``scc_page`` state facts a parser knows
exactly: symbols, signatures, imports, dependents, cycle membership, git
history. A model adds nothing to that and introduces staleness, so these have
one renderer and no model path at all. Their templates sit at
@@ -432,15 +432,6 @@ class StructuralRenderMixin:
decouple_ranking=_rank_cycle_participants(ctx),
)
- def _structural_layer_page(self, ctx: Any, title: str) -> GeneratedPage:
- return self._structural_page(
- page_type="layer_page",
- target_path=ctx.layer_id,
- title=title,
- template="layer_page.j2",
- ctx=ctx,
- )
-
def _structural_api_contract(
self, ctx: Any, file_path: str, title: str, subject_hash: str = ""
) -> GeneratedPage:
diff --git a/packages/core/src/repowise/core/generation/page_tree.py b/packages/core/src/repowise/core/generation/page_tree.py
index 387e577cf..83844f7b4 100644
--- a/packages/core/src/repowise/core/generation/page_tree.py
+++ b/packages/core/src/repowise/core/generation/page_tree.py
@@ -15,18 +15,26 @@ The shape follows what the readers were already doing:
repo overview
onboarding pages (canonical reading order)
- architecture diagram
- layer pages (dependency order from the layer spine)
- module pages (grouped under their dominant layer)
- file pages (under the nearest module, by member or path)
- api contracts, infra pages
- symbol spotlights (under the file they document)
- cycle pages
+ module pages (stamped with the layer they belong to)
+ file pages (under the nearest module, by member or path)
+ api contracts, infra pages
+ symbol spotlights (under the file they document)
+ cycle pages (stamped with the layer they belong to)
anything unplaced
-A rung only appears when the pages for it exist. A repo indexed without a
-curated knowledge graph has no layer pages, so its modules sit directly under
-the overview and the tree is two levels shallower.
+A rung only appears when the pages for it exist.
+
+Layers are the one grouping that is *not* a rung here. They used to be: a
+module said it belonged to the Analysis layer by being parented onto the
+Analysis layer page, which forced eleven near-identical pages to exist purely
+to hold the structure. Those pages retired, so the layer is recorded on each
+module and cycle page instead (``layer_id`` for joining, ``layer_name`` for
+display) and a reader-facing tree builds the layer rows from that — the same
+way the Onboarding folder is built from a slot stamped on its members.
+
+Indexes written before the retirement still hold layer pages. Those are placed
+under the overview like any other page, so an old store rebuilds without
+losing rows.
Everything is ordered by a total sort key, never by dict insertion, because a
tree that reshuffles between two runs of the same commit is the same defect as
@@ -78,6 +86,65 @@ _TYPE_RANK: dict[str, int] = {
_UNRANKED = len(_TYPE_RANK)
+# Page types a reader-facing tree groups into layer rows. Their layer comes
+# from the provenance :func:`assign_page_tree` stamps on them, not from a
+# parent page, so nothing fails when it is missing — the page just falls out
+# of its group. :func:`measure_layer_grouping` is what makes that visible.
+GROUPED_PAGE_TYPES: frozenset[str] = frozenset({"module_page", "scc_page"})
+
+
+@dataclass(frozen=True)
+class LayerGroupingReport:
+ """How far layer provenance reached across one run's pages.
+
+ ``grouped`` and ``ungrouped`` are counted over :data:`GROUPED_PAGE_TYPES`
+ only. Read ``measured`` before reading ``grouped``: a run that produced no
+ groupable page at all has a zero that says nothing, which is the opposite
+ fact from "every groupable page was left ungrouped".
+ """
+
+ grouped: int = 0
+ ungrouped: int = 0
+
+ @property
+ def total(self) -> int:
+ return self.grouped + self.ungrouped
+
+ @property
+ def measured(self) -> bool:
+ return self.total > 0
+
+ def summary_line(self) -> str:
+ """One line fit for a report table, honest about the not-run case."""
+ if not self.measured:
+ return "not computed (no groupable pages)"
+ if not self.ungrouped:
+ return f"all {self.total} pages carry a layer"
+ return f"{self.ungrouped} of {self.total} pages carry no layer"
+
+
+def measure_layer_grouping(
+ pages: Iterable[GeneratedPage] | Iterable[TreeNode],
+) -> LayerGroupingReport:
+ """Count how many groupable pages carry a resolved layer id.
+
+ Call after :func:`assign_page_tree`, which is what stamps them. An empty
+ string counts as ungrouped: the stamper writes nothing when the layer could
+ not be resolved, so a blank id means something else wrote it.
+ """
+ grouped = 0
+ ungrouped = 0
+ for page in pages:
+ if page.page_type not in GROUPED_PAGE_TYPES:
+ continue
+ layer_id = page.metadata.get("layer_id")
+ if isinstance(layer_id, str) and layer_id:
+ grouped += 1
+ else:
+ ungrouped += 1
+ return LayerGroupingReport(grouped=grouped, ungrouped=ungrouped)
+
+
def _onboarding_rank(page: GeneratedPage) -> int:
"""Position of an onboarding page in the canonical reading order."""
from .onboarding.slots import ONBOARDING_ORDER
diff --git a/packages/core/src/repowise/core/generation/report.py b/packages/core/src/repowise/core/generation/report.py
index 4231a7822..0f636cf2a 100644
--- a/packages/core/src/repowise/core/generation/report.py
+++ b/packages/core/src/repowise/core/generation/report.py
@@ -10,6 +10,7 @@ from dataclasses import dataclass, field
from .models import GeneratedPage
from .page_overlap import OverlapReport, measure_orientation_overlap
+from .page_tree import LayerGroupingReport, measure_layer_grouping
@dataclass
@@ -31,6 +32,11 @@ class GenerationReport:
# ``comparable`` before reading ``flagged`` — an empty ``flagged`` on a
# run that compared nothing is not a clean result.
orientation_overlap: OverlapReport = field(default_factory=OverlapReport)
+ # How far layer provenance reached across this run's pages. Layers have no
+ # pages of their own, so the docs tree groups by this metadata and nothing
+ # raises when it is missing — the wiki just comes out flat. Read
+ # ``measured`` before reading the counts.
+ layer_grouping: LayerGroupingReport = field(default_factory=LayerGroupingReport)
@classmethod
def from_pages(
@@ -57,6 +63,7 @@ class GenerationReport:
hallucination_warning_count=hal_count,
self_repaired_page_count=repair_count,
orientation_overlap=measure_orientation_overlap(pages),
+ layer_grouping=measure_layer_grouping(pages),
)
@property
@@ -113,6 +120,14 @@ def render_report(report: GenerationReport, console: object) -> None:
overlap_text = f"[yellow]{overlap_text}[/yellow]"
table.add_row("Orientation overlap", overlap_text)
+ # Always shown, for the same reason as the row above: a hidden zero would
+ # make "nothing was groupable" read as "everything grouped".
+ grouping = report.layer_grouping
+ grouping_text = grouping.summary_line()
+ if grouping.ungrouped:
+ grouping_text = f"[yellow]{grouping_text}[/yellow]"
+ table.add_row("Layer grouping", grouping_text)
+
console.print(table) # type: ignore[union-attr]
for pair in overlap.flagged:
diff --git a/packages/core/src/repowise/core/generation/scope.py b/packages/core/src/repowise/core/generation/scope.py
index 93d97a2eb..f64444255 100644
--- a/packages/core/src/repowise/core/generation/scope.py
+++ b/packages/core/src/repowise/core/generation/scope.py
@@ -36,11 +36,15 @@ from repowise.core.generation.selection import Selection, SelectionInputs, selec
# Page types that describe the whole repository (as opposed to one file/module).
_REPO_WIDE_TYPES = frozenset({"repo_overview", "onboarding"})
-# Structural pages the coverage budget does not rank: layer pages come from KG
-# membership and onboarding is curated, so init emits every one of them at every
-# coverage. A ranked run includes the unwritten ones rather than leaving holes in
-# the navigation. (repo_overview / architecture come from the Selection itself.)
-_STRUCTURAL_PAGE_TYPES = frozenset({"layer_page", "onboarding"})
+# Structural pages the coverage budget does not rank: onboarding is curated, so
+# init emits every one of them at every coverage. A ranked run includes the
+# unwritten ones rather than leaving holes in the navigation. (repo_overview
+# comes from the Selection itself.)
+#
+# Layer pages used to sit here too. They are retired — nothing emits one — so
+# seeding an unwritten one would ask generation for a page it will not produce,
+# and the run would report it missing every time.
+_STRUCTURAL_PAGE_TYPES = frozenset({"onboarding"})
@dataclass(frozen=True)
@@ -82,22 +86,6 @@ def load_page_records(pages: list[Any]) -> list[PageRecord]:
return records
-def _layer_membership(kg_ctx: Any) -> dict[str, str]:
- """Map each file path to its ``layer_page:<id>`` from KG layer membership."""
- out: dict[str, str] = {}
- if not (kg_ctx and getattr(kg_ctx, "available", False)):
- return out
- from repowise.core.analysis.knowledge_graph import _slugify
-
- for layer in kg_ctx.get_layers():
- layer_id = layer.get("id") or f"layer:{_slugify(layer.get('name', ''))}"
- page_id = compute_page_id("layer_page", layer_id)
- for nid in layer.get("nodeIds", []):
- if isinstance(nid, str) and nid.startswith("file:"):
- out.setdefault(nid[5:], page_id)
- return out
-
-
def _selection_inputs(
*,
parsed_files: list[Any],
@@ -166,7 +154,6 @@ def build_dependencies(
return build_page_dependencies(
module_groups=selection.module_groups,
scc_groups=selection.scc_groups,
- layer_page_of=_layer_membership(kg_ctx),
repo_wide_ids=repo_wide_ids,
)
diff --git a/packages/core/src/repowise/core/generation/templates/layer_page.j2 b/packages/core/src/repowise/core/generation/templates/layer_page.j2
deleted file mode 100644
index 152d174a2..000000000
--- a/packages/core/src/repowise/core/generation/templates/layer_page.j2
+++ /dev/null
@@ -1,69 +0,0 @@
-{#- Deterministic (no-LLM) architectural layer page.
-
- The per-layer mermaid diagram is already built structurally by
- ArchitectureMermaidBuilder, so on this path it is simply embedded
- inline rather than spliced in after generation.
--#}
-# Layer: {{ ctx.layer_name }}
-
-{% if ctx.layer_description %}{{ ctx.layer_description }}
-
-{% endif %}**Files:** {{ ctx.file_count }}{% if ctx.entry_points %} | **Entry points:** {{ ctx.entry_points | length }}{% endif %}{% if ctx.edge_connectors %} | **Edge connectors:** {{ ctx.edge_connectors | length }}{% endif %}
-
-## Overview
-
-{% set _in = ctx.deps_in | length %}{% set _out = ctx.deps_out | length -%}
-This layer holds {{ ctx.file_count }} file{{ "s" if ctx.file_count != 1 else "" }}.
-{%- if _in and _out %} It is called by {{ _in }} layer{{ "s" if _in != 1 else "" }} and calls into {{ _out }}, so it sits mid-stack: work flows in from above and out to the layers below.
-{%- elif _out %} It calls into {{ _out }} layer{{ "s" if _out != 1 else "" }} and nothing in this repository imports it, which puts it at the top of the stack.
-{%- elif _in %} {{ _in }} layer{{ "s" if _in != 1 else "" }} import{{ "s" if _in == 1 else "" }} it and it imports none itself, which makes it foundational.
-{%- else %} It has no resolved inter-layer edges, so it stands on its own.
-{%- endif %}
-
-{% if ctx.diagram_mermaid %}
-## Architecture
-
-```mermaid
-{{ ctx.diagram_mermaid }}
-```
-{% endif %}
-
-{% if ctx.entry_points %}
-## Entry points
-{% for ep in ctx.entry_points %}
-- `{{ ep }}`
-{% endfor %}
-{% endif %}
-
-{% if ctx.key_files %}
-## Key files
-{% for kf in ctx.key_files %}
-- `{{ kf.path }}`{% if kf.role %} *({{ kf.role }})*{% endif %}{% if kf.summary %}: {{ kf.summary | oneline }}{% endif %}
-{% endfor %}
-{% endif %}
-
-{% if ctx.edge_connectors %}
-## Edge connectors
-Files where this layer meets the outside world.
-{% for ec in ctx.edge_connectors %}
-- `{{ ec }}`
-{% endfor %}
-{% endif %}
-
-{% if ctx.deps_in or ctx.deps_out %}
-## Neighbouring layers
-{% for d in ctx.deps_in %}
-- **{{ d.source_layer }}** imports this layer ({{ d.edge_count }} edge{{ "s" if d.edge_count != 1 else "" }})
-{% endfor %}
-{% for d in ctx.deps_out %}
-- This layer imports **{{ d.target_layer }}** ({{ d.edge_count }} edge{{ "s" if d.edge_count != 1 else "" }})
-{% endfor %}
-{% endif %}
-
-{% if ctx.tour_steps %}
-## On the guided tour
-{% for s in ctx.tour_steps %}
-- {% if s.order %}Step {{ s.order }}: {% endif %}{{ s.title }}{% if s.description %}. {{ s.description | oneline }}{% endif %}
-{% endfor %}
-{% endif %}
-{% include "_footer.j2" %}
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 51b2e62be..8a04732c4 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -798,13 +798,15 @@ async def run_pipeline(
has_code_to_group = any(
not getattr(p.file_info, "is_test", False) for p in (parsed_files or [])
)
- kg_layers_present = bool(
- knowledge_graph_result is not None and knowledge_graph_result.layers
- )
if produced_module_page or not has_code_to_group:
authoritative_page_types.add("module_page")
- if kg_layers_present:
- authoritative_page_types.add("layer_page")
+ # Layer pages are retired: no run emits one and no failure mode can
+ # make a run emit one, so every completed run is authoritative for the
+ # type and the sweep retires the rows a pre-retirement index left
+ # behind. Unconditional, unlike the types above, because "emitted
+ # zero" here has exactly one cause. Their ids keep resolving through
+ # the redirect table, so retiring the rows breaks no inbound link.
+ authoritative_page_types.add("layer_page")
# A deterministic run takes every candidate rather than a budgeted
# slice, so an SCC page missing from its output means the cycle is
# gone, not that it lost a budget fight. That makes the run
diff --git a/tests/unit/cli/test_generate_chooser.py b/tests/unit/cli/test_generate_chooser.py
index a04af5b31..0e16634de 100644
--- a/tests/unit/cli/test_generate_chooser.py
+++ b/tests/unit/cli/test_generate_chooser.py
@@ -48,7 +48,7 @@ def test_choose_cascade_skips_prompt_when_outcome_is_identical() -> None:
# No containers and no repo-wide pages: every cascade mode generates exactly
# the seed, so the choice cannot change the outcome and must not prompt.
deps = build_page_dependencies(
- module_groups=[], scc_groups=[], layer_page_of={}, repo_wide_ids=()
+ module_groups=[], scc_groups=[], repo_wide_ids=()
)
console = _RecordingConsole()
mode = choose_cascade(console, {"file_page:a.py"}, deps, default="none")
@@ -63,7 +63,6 @@ def test_choose_cascade_prompts_when_modes_diverge(monkeypatch) -> None:
deps = build_page_dependencies(
module_groups=[_MG("src", ("a.py",))],
scc_groups=[],
- layer_page_of={},
repo_wide_ids=("repo_overview:demo",),
)
asked: dict[str, object] = {}
@@ -87,7 +86,7 @@ def _run(records, deps):
def test_run_interactive_chooser_returns_cascade_when_unwritten() -> None:
records = [PageRecord("module_page:src", "module_page", "src", is_template=True)]
deps = build_page_dependencies(
- module_groups=[], scc_groups=[], layer_page_of={}, repo_wide_ids=()
+ module_groups=[], scc_groups=[], repo_wide_ids=()
)
choice = _run(records, deps)
assert choice is not None
@@ -99,7 +98,7 @@ def test_run_interactive_chooser_returns_cascade_when_unwritten() -> None:
def test_run_interactive_chooser_bails_when_nothing_unwritten() -> None:
records = [PageRecord("module_page:src", "module_page", "src", is_template=False)]
deps = build_page_dependencies(
- module_groups=[], scc_groups=[], layer_page_of={}, repo_wide_ids=()
+ module_groups=[], scc_groups=[], repo_wide_ids=()
)
# Guard fires before the cascade step: every page is already written.
assert _run(records, deps) is None
diff --git a/tests/unit/cli/test_generate_scope.py b/tests/unit/cli/test_generate_scope.py
index ca8f7ed0c..b914d0421 100644
--- a/tests/unit/cli/test_generate_scope.py
+++ b/tests/unit/cli/test_generate_scope.py
@@ -79,7 +79,6 @@ def test_resolve_scope_unwritten_with_cascade_none() -> None:
deps = build_page_dependencies(
module_groups=[_MG("src", ("src/a.py", "src/b.py"))],
scc_groups=[],
- layer_page_of={},
repo_wide_ids=("repo_overview:demo",),
)
plan = resolve_scope(
@@ -151,10 +150,14 @@ def test_ranked_ids_to_seed_keeps_unwritten_and_adds_structural() -> None:
PageRecord("onboarding:map", "onboarding", "map", is_template=False),
]
# Ranked picks both file pages; the written one (b.py) must drop, and the
- # unwritten structural pages (layer + one onboarding) must be pulled in even
- # though the ranked set never named them.
+ # unwritten onboarding page must be pulled in even though the ranked set
+ # never named it.
+ #
+ # The stored layer page is unwritten too, and stays out: layer pages are
+ # retired, so seeding one would ask generation for a page it will not
+ # produce and the run would report it missing every time.
seed = _ranked_ids_to_seed({"file_page:a.py", "file_page:b.py"}, records)
- assert seed == {"file_page:a.py", "layer_page:core", "onboarding:tour"}
+ assert seed == {"file_page:a.py", "onboarding:tour"}
def test_ranked_ids_to_seed_drops_ids_with_no_page() -> None:
@@ -171,7 +174,7 @@ def test_resolve_scope_uses_ranked_seed_verbatim() -> None:
PageRecord("file_page:b.py", "file_page", "b.py", is_template=True),
]
deps = build_page_dependencies(
- module_groups=[], scc_groups=[], layer_page_of={}, repo_wide_ids=()
+ module_groups=[], scc_groups=[], repo_wide_ids=()
)
# An all-selecting intent would pick both; the ranked seed overrides it.
plan = resolve_scope(
diff --git a/tests/unit/generation/test_cascade.py b/tests/unit/generation/test_cascade.py
index 0c136dc29..52cb9a538 100644
--- a/tests/unit/generation/test_cascade.py
+++ b/tests/unit/generation/test_cascade.py
@@ -22,7 +22,6 @@ def _deps():
return build_page_dependencies(
module_groups=[_MG("src", ("src/a.py", "src/b.py"))],
scc_groups=[("scc-abc", ["src/a.py", "src/c.py"])],
- layer_page_of={"src/a.py": "layer_page:layer:core"},
repo_wide_ids=(
"repo_overview:demo",
"architecture_diagram:demo",
@@ -31,12 +30,11 @@ def _deps():
)
-def test_containers_of_collects_module_scc_layer() -> None:
+def test_containers_of_collects_module_and_scc() -> None:
deps = _deps()
assert deps.containers_of("src/a.py") == {
"module_page:src",
"scc_page:scc-abc",
- "layer_page:layer:core",
}
# b.py is only in the module.
assert deps.containers_of("src/b.py") == {"module_page:src"}
@@ -49,7 +47,6 @@ def test_cascade_none_marks_dependents_stale_generates_only_seed() -> None:
assert result.stale_ids == {
"module_page:src",
"scc_page:scc-abc",
- "layer_page:layer:core",
"repo_overview:demo",
"architecture_diagram:demo",
"onboarding:guided-tour",
@@ -63,7 +60,6 @@ def test_cascade_dependents_regenerates_containers_marks_repo_wide_stale() -> No
"file_page:src/a.py",
"module_page:src",
"scc_page:scc-abc",
- "layer_page:layer:core",
}
assert result.stale_ids == {
"repo_overview:demo",
@@ -79,7 +75,6 @@ def test_cascade_full_regenerates_everything_marks_nothing() -> None:
"file_page:src/a.py",
"module_page:src",
"scc_page:scc-abc",
- "layer_page:layer:core",
"repo_overview:demo",
"architecture_diagram:demo",
"onboarding:guided-tour",
diff --git a/tests/unit/generation/test_deterministic_templates.py b/tests/unit/generation/test_deterministic_templates.py
index 610a1a3fe..46f46710b 100644
--- a/tests/unit/generation/test_deterministic_templates.py
+++ b/tests/unit/generation/test_deterministic_templates.py
@@ -11,7 +11,7 @@ from __future__ import annotations
import pytest
-from repowise.core.generation.context_assembler import ContextAssembler, LayerPageContext
+from repowise.core.generation.context_assembler import ApiContractContext, ContextAssembler
from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.onboarding.subkinds.active_landscape import (
ActiveLandscapeContext,
@@ -40,53 +40,6 @@ def generator() -> PageGenerator:
return PageGenerator(TemplateProvider(), ContextAssembler(config), config)
-def test_layer_page_renders(generator):
- ctx = LayerPageContext(
- layer_name="Ingestion",
- layer_id="layer:ingestion",
- layer_description="Parses source files into ASTs.",
- file_count=7,
- key_files=[{"path": "src/parse.py", "role": "entry_point", "summary": "Parses files."}],
- deps_out=[{"target_layer": "Storage", "edge_count": 4}],
- deps_in=[{"source_layer": "CLI", "edge_count": 2}],
- # Exactly the shape KnowledgeGraphContext.get_file_context builds
- # (order/title/description). Inventing a shape here is how the first
- # version of this template shipped with a field that never exists.
- tour_steps=[{"order": 1, "title": "Parsing", "description": "Where parsing starts."}],
- entry_points=["src/parse.py"],
- edge_connectors=["src/io.py"],
- diagram_mermaid="flowchart LR\n a --> b",
- )
- page = generator._structural_layer_page(ctx, "Layer: Ingestion")
-
- assert page.page_id == "layer_page:layer:ingestion"
- assert page.provider_name == "template"
- assert page.input_tokens == 0
- assert "```mermaid" in page.content
- assert "flowchart LR" in page.content
- assert "**Storage**" in page.content
- assert "**CLI**" in page.content
- # Sits between two layers, so the overview should say so rather than
- # calling it foundational or top-of-stack.
- assert "mid-stack" in page.content
- assert "Step 1: Parsing. Where parsing starts." in page.content
- assert "Built from the code itself" in page.content
-
-
-def test_layer_page_without_diagram_renders(generator):
- """A layer with no KG diagram must still produce a usable page."""
- ctx = LayerPageContext(
- layer_name="Utilities",
- layer_id="layer:utilities",
- layer_description="",
- file_count=3,
- )
- page = generator._structural_layer_page(ctx, "Layer: Utilities")
-
- assert "```mermaid" not in page.content
- assert "stands on its own" in page.content
-
-
def _onboarding_spec(slot: str, template: str):
from repowise.core.generation.onboarding.registry import SubkindSpec
@@ -217,28 +170,24 @@ def test_symbol_spotlight_tolerates_missing_kind(generator):
def test_multiline_summaries_stay_inside_their_list_item(generator):
"""A raw newline in a bullet ends the markdown list, dumping the rest as
- body text. Page summaries are routinely multi-paragraph, so every text
- field folded into a list item runs through the oneline filter."""
- ctx = LayerPageContext(
- layer_name="Core",
- layer_id="layer:core",
- layer_description="",
- file_count=3,
- key_files=[
- {
- "path": "a.py",
- "role": "internal",
- "summary": "First line.\n\nSecond paragraph that would break the list.",
- },
- {"path": "b.py", "role": "internal", "summary": "Short."},
+ body text. Parsed signatures routinely carry newlines, so every text field
+ folded into a list item runs through the oneline filter."""
+ ctx = ApiContractContext(
+ file_path="api/routes.py",
+ language="python",
+ raw_content="",
+ endpoints=[
+ "def create(\n self,\n payload: dict,\n) -> Response",
+ "def delete(self, id: str) -> None",
],
+ schemas=[],
)
- page = generator._structural_layer_page(ctx, "Layer: Core")
+ page = generator._structural_api_contract(ctx, "api/routes.py", "API Contract: api/routes.py")
- body = page.content.split("## Key files", 1)[1]
+ body = page.content.split("## Operations", 1)[1]
bullets = [ln for ln in body.splitlines() if ln.startswith("- ")]
assert len(bullets) == 2, f"list broke apart: {bullets}"
- assert "First line. Second paragraph" in bullets[0]
+ assert "def create( self, payload: dict, ) -> Response" in bullets[0]
def test_summary_skips_the_stats_line():
diff --git a/tests/unit/generation/test_layer_pages.py b/tests/unit/generation/test_layer_pages.py
index f01d599a1..31ac5f88f 100644
--- a/tests/unit/generation/test_layer_pages.py
+++ b/tests/unit/generation/test_layer_pages.py
@@ -1,448 +1,264 @@
-"""Tests for layer_page generation (Phase 7)."""
+"""Layer pages are retired; the grouping they carried is not.
-from __future__ import annotations
-
-import json
-from pathlib import Path
+Every layer page opened with the same sentence, differing in two integers, and
+every pair of them scored as the worst duplication in the wiki. What the pages
+were actually load-bearing for was structure: the docs tree said "this module
+belongs to the Analysis layer" by parenting the module onto the Analysis layer
+*page*, so the only way to keep the grouping was to keep the pages.
-import pytest
+The grouping now lives on the pages that are grouped — each carries the id and
+display name of its layer — so nothing has to emit a page for a reader-facing
+tree to build layer rows.
-from repowise.core.generation.context_assembler import LayerPageContext
-from repowise.core.generation.models import GENERATION_LEVELS, PageType
+The page type stays registered on purpose. Indexes written before this change
+hold ``layer_page`` rows, and a stored page whose type the serving layer does
+not know is a broken page for every one of them. New ids are not minted; old
+ones still render, and an inbound link to one still resolves.
+"""
-# ---------------------------------------------------------------------------
-# Model tests
-# ---------------------------------------------------------------------------
+from __future__ import annotations
+from pathlib import Path
-class TestLayerPageModel:
- def test_layer_page_in_page_type(self):
+from repowise.core.cost_estimator.estimator import (
+ STRUCTURAL_PAGE_TYPES as COST_STRUCTURAL_PAGE_TYPES,
+)
+from repowise.core.generation.models import (
+ GENERATION_LEVELS,
+ STRUCTURALLY_KEYED_PAGE_TYPES,
+ PageType,
+)
+from repowise.core.generation.page_redirects import repo_wide_successor_type
+from repowise.core.generation.page_tree import TreeNode, assign_page_tree
+
+_TEMPLATE_DIR = (
+ Path(__file__).resolve().parents[3]
+ / "packages"
+ / "core"
+ / "src"
+ / "repowise"
+ / "core"
+ / "generation"
+ / "templates"
+)
+
+
+class TestLayerPageStaysRegistered:
+ """A stored layer page has to keep rendering and keep resolving."""
+
+ def test_layer_page_is_still_a_page_type(self):
assert "layer_page" in PageType.__args__
- def test_layer_page_generation_level(self):
+ def test_layer_page_still_has_a_generation_level(self):
assert GENERATION_LEVELS["layer_page"] == 5
- def test_layer_page_after_module_before_overview(self):
- assert GENERATION_LEVELS["layer_page"] > GENERATION_LEVELS["module_page"]
- assert GENERATION_LEVELS["layer_page"] < GENERATION_LEVELS["repo_overview"]
+ def test_layer_page_is_still_structurally_keyed(self):
+ assert "layer_page" in STRUCTURALLY_KEYED_PAGE_TYPES
+ def test_layer_page_still_costs_nothing(self):
+ """A stored layer page was rendered from structure, never prompted.
-# ---------------------------------------------------------------------------
-# LayerPageContext tests
-# ---------------------------------------------------------------------------
+ Dropping it from the cost table would price historical telemetry as if
+ a model had written one.
+ """
+ assert "layer_page" in COST_STRUCTURAL_PAGE_TYPES
+ def test_a_retired_layer_id_hands_off_to_the_overview(self):
+ assert repo_wide_successor_type("layer_page:layer:core") == "repo_overview"
-class TestLayerPageContext:
- def test_basic_construction(self):
- ctx = LayerPageContext(
- layer_name="Core Pipeline",
- layer_description="Central data processing",
- file_count=10,
- )
- assert ctx.layer_name == "Core Pipeline"
- assert ctx.file_count == 10
- assert ctx.key_files == []
- assert ctx.deps_out == []
- assert ctx.deps_in == []
- assert ctx.tour_steps == []
-
- def test_full_construction(self):
- ctx = LayerPageContext(
- layer_name="Core",
- layer_description="Core logic",
- file_count=5,
- key_files=[{"path": "src/core.py", "role": "edge_connector", "summary": "Core module"}],
- deps_out=[{"target_layer": "API", "edge_count": 3}],
- deps_in=[{"source_layer": "CLI", "edge_count": 1}],
- tour_steps=[{"order": 1, "title": "Core", "description": "Explore core"}],
- entry_points=["src/main.py"],
- edge_connectors=["src/core.py"],
- )
- assert len(ctx.key_files) == 1
- assert ctx.key_files[0]["path"] == "src/core.py"
- assert len(ctx.deps_out) == 1
- assert len(ctx.deps_in) == 1
- assert len(ctx.tour_steps) == 1
- assert len(ctx.entry_points) == 1
- assert len(ctx.edge_connectors) == 1
+class TestNothingEmitsALayerPage:
+ def test_the_generator_has_no_layer_page_method(self):
+ from repowise.core.generation.page_generator import PageGenerator
-# ---------------------------------------------------------------------------
-# Template rendering tests
-# ---------------------------------------------------------------------------
+ assert not hasattr(PageGenerator, "generate_layer_page")
+ assert not hasattr(PageGenerator, "_structural_layer_page")
+ def test_there_is_no_layer_page_template(self):
+ assert not (_TEMPLATE_DIR / "layer_page.j2").exists()
-class TestLayerPageTemplate:
- @pytest.fixture
- def jinja_env(self):
- from jinja2 import Environment, FileSystemLoader
+ def test_there_is_no_layer_page_context(self):
+ from repowise.core.generation import context_assembler
- from repowise.core.generation.page_generator.structural import (
- as_markdown,
- oneline,
- signature,
- )
+ assert not hasattr(context_assembler, "LayerPageContext")
- template_dir = (
- Path(__file__).resolve().parents[3]
- / "packages"
- / "core"
- / "src"
- / "repowise"
- / "core"
- / "generation"
- / "templates"
- )
- env = Environment(loader=FileSystemLoader(str(template_dir)))
- # The filters PageGenerator registers; the structural template renders
- # page content rather than a prompt and depends on them.
- env.filters["oneline"] = oneline
- env.filters["as_markdown"] = as_markdown
- env.filters["signature"] = signature
- return env
-
- def test_renders_layer_name(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="Core Pipeline",
- layer_description="Handles data processing",
- file_count=8,
- )
- rendered = tmpl.render(ctx=ctx)
- assert "Core Pipeline" in rendered
- assert "**Files:** 8" in rendered
- assert "Handles data processing" in rendered
-
- def test_renders_key_files(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="Core",
- layer_description="",
- file_count=5,
- key_files=[
- {"path": "src/core.py", "role": "edge_connector", "summary": "Core module"},
- {"path": "src/utils.py", "role": "internal", "summary": ""},
- ],
- )
- rendered = tmpl.render(ctx=ctx)
- assert "## Key files" in rendered
- assert "`src/core.py`" in rendered
- assert "*(edge_connector)*" in rendered
- assert "`src/utils.py`" in rendered
-
- def test_renders_inter_layer_deps(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="Core",
- layer_description="",
- file_count=5,
- deps_out=[{"target_layer": "Persistence", "edge_count": 4}],
- deps_in=[{"source_layer": "CLI", "edge_count": 2}],
- )
- rendered = tmpl.render(ctx=ctx)
- assert "## Neighbouring layers" in rendered
- assert "**Persistence**" in rendered
- assert "4 edges" in rendered
- assert "**CLI**" in rendered
- assert "2 edges" in rendered
-
- def test_renders_tour_steps(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="Core",
- layer_description="",
- file_count=5,
- tour_steps=[
- {"order": 2, "title": "Core Logic", "description": "Dive into the core."},
- ],
- )
- rendered = tmpl.render(ctx=ctx)
- assert "## On the guided tour" in rendered
- assert "Step 2: Core Logic" in rendered
-
- def test_renders_entry_points_and_connectors(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="CLI",
- layer_description="",
- file_count=3,
- entry_points=["src/main.py"],
- edge_connectors=["src/api.py"],
- )
- rendered = tmpl.render(ctx=ctx)
- assert "## Entry points" in rendered
- assert "`src/main.py`" in rendered
- assert "## Edge connectors" in rendered
- assert "`src/api.py`" in rendered
-
- def test_no_optional_sections_when_empty(self, jinja_env):
- tmpl = jinja_env.get_template("layer_page.j2")
- ctx = LayerPageContext(
- layer_name="Tiny",
- layer_description="",
- file_count=3,
- )
- rendered = tmpl.render(ctx=ctx)
- assert "highest-importance files" not in rendered
- assert "## Inter-Layer Dependencies" not in rendered
- assert "## Codebase Tour References" not in rendered
- assert "## Entry Points\n" not in rendered
- assert "## Edge Connectors\n" not in rendered
-
-
-# ---------------------------------------------------------------------------
-# System prompt tests
-# ---------------------------------------------------------------------------
-
-
-class TestLayerPagePrompt:
- def test_layer_pages_have_no_prompt(self):
- """A layer page is layer name, top files, dependencies, entry points
- and a diagram the builder draws. All of that is known exactly, so
- there is one renderer and nothing to prompt."""
- from repowise.core.generation.page_generator.prompts import SYSTEM_PROMPTS
-
- assert "layer_page" not in SYSTEM_PROMPTS
-
-
-# ---------------------------------------------------------------------------
-# build_level5_coros tests
-# ---------------------------------------------------------------------------
-
-
-class TestBuildLevel5Coros:
- def _make_run(self, tmp_path, layers, nodes=None, edges=None, tour=None):
- """Build a minimal mock _GenerationRun with KG context."""
- from unittest.mock import MagicMock
-
- from repowise.core.generation.kg_context import KnowledgeGraphContext
-
- if nodes is None:
- nodes = []
- for layer in layers:
- for nid in layer.get("nodeIds", []):
- if nid.startswith("file:"):
- fp = nid[5:]
- nodes.append({"id": nid, "filePath": fp})
-
- kg = {
- "nodes": nodes,
- "edges": edges or [],
- "layers": layers,
- "tour": tour or [],
- }
- # Create files on disk for tour validation
- for node in nodes:
- fp = node.get("filePath", "")
- if fp:
- full = tmp_path / fp
- full.parent.mkdir(parents=True, exist_ok=True)
- full.touch()
-
- kg_path = tmp_path / ".repowise" / "knowledge-graph.json"
- kg_path.parent.mkdir(exist_ok=True)
- kg_path.write_text(json.dumps(kg))
-
- run = MagicMock()
- run.kg_ctx = KnowledgeGraphContext(kg_path)
- run.pagerank = {}
- run.completed_page_summaries = {}
- run.completed_ids = set()
- run.only_page_ids = None
- # Emission now flows through the real _emit gate, so the mock must use
- # its real logic (completed_ids + only_page_ids) rather than a truthy
- # auto-mock that would emit everything.
- from repowise.core.generation.page_generator.orchestrate import _GenerationRun
-
- run._emit = lambda pid: _GenerationRun._emit(run, pid)
- run.gen = MagicMock()
- return run
-
- def test_generates_for_layer_with_enough_files(self, tmp_path):
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- layers = [
- {
- "id": "layer:core",
- "name": "Core",
- "description": "Core logic",
- "nodeIds": ["file:a.py", "file:b.py", "file:c.py"],
- },
- ]
- run = self._make_run(tmp_path, layers)
- coros = build_level5_coros(run)
- assert len(coros) == 1
- # Page keyed by the layer's stable slug id, not its display name.
- assert coros[0][0] == "layer_page:layer:core"
-
- def test_layer_context_carries_diagram_when_modules_exist(self, tmp_path):
- from unittest.mock import MagicMock
-
- from repowise.core.generation.kg_context import KnowledgeGraphContext
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- files_a = [f"core/a/f{i}.py" for i in range(4)]
- files_b = [f"core/b/f{i}.py" for i in range(3)]
- nodes = [{"id": f"file:{f}", "filePath": f} for f in files_a + files_b]
- edges = [
- {"source": f"file:{files_a[0]}", "target": f"file:{files_b[0]}", "type": "imports"}
- ]
- layers = [
- {
- "id": "layer:core",
- "name": "Core",
- "description": "",
- "nodeIds": [f"file:{f}" for f in files_a + files_b],
- }
- ]
- modules = [
- {
- "id": "module:core-a",
- "name": "core/a",
- "path": "core/a",
- "layerId": "layer:core",
- "nodeIds": [f"file:{f}" for f in files_a],
- },
- {
- "id": "module:core-b",
- "name": "core/b",
- "path": "core/b",
- "layerId": "layer:core",
- "nodeIds": [f"file:{f}" for f in files_b],
- },
- ]
- kg = {"nodes": nodes, "edges": edges, "layers": layers, "modules": modules, "tour": []}
- for n in nodes:
- full = tmp_path / n["filePath"]
- full.parent.mkdir(parents=True, exist_ok=True)
- full.touch()
- kg_path = tmp_path / ".repowise" / "knowledge-graph.json"
- kg_path.parent.mkdir(exist_ok=True)
- kg_path.write_text(json.dumps(kg))
-
- run = MagicMock()
- run.kg_ctx = KnowledgeGraphContext(kg_path)
- run.pagerank = {}
- run.completed_page_summaries = {}
- run.completed_ids = set()
- run.gen = MagicMock()
-
- coros = build_level5_coros(run)
- assert len(coros) == 1
- ctx = run.gen.generate_layer_page.call_args.args[0]
- assert ctx.diagram_mermaid.startswith("flowchart TD")
- assert "core/a" in ctx.diagram_mermaid
-
- def test_skips_small_layers(self, tmp_path):
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- layers = [
- {"id": "layer:tiny", "name": "Tiny", "nodeIds": ["file:a.py", "file:b.py"]},
- ]
- run = self._make_run(tmp_path, layers)
- coros = build_level5_coros(run)
- assert len(coros) == 0
+ def test_there_is_no_level_5_builder(self):
+ from repowise.core.generation.page_generator import levels
- def test_no_layers_no_coros(self, tmp_path):
- from repowise.core.generation.page_generator.levels import build_level5_coros
+ assert not hasattr(levels, "build_level5_coros")
- run = self._make_run(tmp_path, [])
- coros = build_level5_coros(run)
- assert len(coros) == 0
+ def test_a_layer_page_id_is_never_seeded_by_scope_resolution(self):
+ """Scope adds unwritten structural pages so a coverage upgrade fills
+ the navigation. A page type nothing writes can never be filled, so
+ seeding one would ask generation for a page it will not produce."""
+ from repowise.core.generation.scope import _STRUCTURAL_PAGE_TYPES
- def test_no_kg_returns_empty(self):
- from unittest.mock import MagicMock
+ assert "layer_page" not in _STRUCTURAL_PAGE_TYPES
- from repowise.core.generation.kg_context import KnowledgeGraphContext
- from repowise.core.generation.page_generator.levels import build_level5_coros
- run = MagicMock()
- run.kg_ctx = KnowledgeGraphContext(None)
- coros = build_level5_coros(run)
- assert coros == []
+class TestGroupingSurvivesWithoutTheirPages:
+ """The trap: the tree used to derive its layer set from the layer pages."""
- def test_skips_completed_layers(self, tmp_path):
- from repowise.core.generation.page_generator.levels import build_level5_coros
+ @staticmethod
+ 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),
+ )
- layers = [
- {
- "id": "layer:core",
- "name": "Core",
- "nodeIds": ["file:a.py", "file:b.py", "file:c.py"],
- },
- ]
- run = self._make_run(tmp_path, layers)
- run.completed_ids = {"layer_page:layer:core"}
- coros = build_level5_coros(run)
- assert len(coros) == 0
-
- def test_multiple_layers(self, tmp_path):
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- layers = [
- {
- "id": "layer:core",
- "name": "Core",
- "nodeIds": ["file:a.py", "file:b.py", "file:c.py"],
- },
- {
- "id": "layer:api",
- "name": "API",
- "nodeIds": ["file:d.py", "file:e.py", "file:f.py", "file:g.py"],
- },
- {"id": "layer:tiny", "name": "Tiny", "nodeIds": ["file:h.py"]},
- ]
- run = self._make_run(tmp_path, layers)
- coros = build_level5_coros(run)
- assert len(coros) == 2
- page_ids = {c[0] for c in coros}
- assert "layer_page:layer:core" in page_ids
- assert "layer_page:layer:api" in page_ids
-
- def test_page_key_uses_slug_not_display_name(self, tmp_path):
- """The page key derives from the stable slug id, never the mutable
- display name — a layer named "Task Queue Core" with id ``layer:queue``
- is keyed by ``layer:queue`` so an LLM rename can't churn the key."""
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- layers = [
- {
- "id": "layer:queue",
- "name": "Task Queue Core",
- "nodeIds": ["file:a.py", "file:b.py", "file:c.py"],
- },
+ def _repo(self) -> list[TreeNode]:
+ node = self._node
+ 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(
+ "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"],
+ ),
]
- run = self._make_run(tmp_path, layers)
- coros = build_level5_coros(run)
- assert len(coros) == 1
- assert coros[0][0] == "layer_page:layer:queue"
+ def test_every_module_is_stamped_when_no_layer_page_exists(self):
+ nodes = self._repo()
+ assert not any(n.page_type == "layer_page" for n in nodes)
+ assign_page_tree(nodes, ["layer:analysis"])
+ module = next(n for n in nodes if n.page_id == "module_page:core/analysis")
+ assert module.metadata["layer_id"] == "layer:analysis"
+ assert module.metadata["layer_name"] == "Analysis"
+
+ def test_every_cycle_is_stamped_when_no_layer_page_exists(self):
+ nodes = self._repo()
+ assign_page_tree(nodes, ["layer:analysis"])
+ cycle = next(n for n in nodes if n.page_id == "scc_page:cycle-1")
+ assert cycle.metadata["layer_id"] == "layer:analysis"
+ assert cycle.metadata["layer_name"] == "Analysis"
+
+ def test_members_parent_onto_the_overview_not_a_missing_page(self):
+ nodes = self._repo()
+ assign_page_tree(nodes, ["layer:analysis"])
+ for page_id in ("module_page:core/analysis", "scc_page:cycle-1"):
+ node = next(n for n in nodes if n.page_id == page_id)
+ assert node.parent_page_id == "repo_overview:demo"
+
+ def test_a_stored_layer_page_still_gets_a_place_in_the_tree(self):
+ """An index written before the retirement is rebuilt from its store."""
+ nodes = [
+ *self._repo(),
+ self._node("layer_page:layer:analysis", "layer_page", "layer:analysis"),
+ ]
+ assign_page_tree(nodes, ["layer:analysis"])
+ stored = next(n for n in nodes if n.page_id == "layer_page:layer:analysis")
+ assert stored.parent_page_id == "repo_overview:demo"
+ assert stored.section_number is not None
+
+
+class TestTheRunCountsWhatGroupingReached:
+ """Losing the grouping is now a silent failure unless something counts it.
+
+ With the pages gone, nothing errors when provenance fails to land: the
+ tree still builds, every page still has a parent, and the reader simply
+ gets a flat wiki. So the run counts the pages that carry a layer against
+ the pages that were supposed to, and reports it.
+ """
+
+ @staticmethod
+ def _page(page_id: str, page_type: str, **metadata):
+ from datetime import UTC, datetime
+
+ from repowise.core.generation.models import GeneratedPage
+
+ now = datetime.now(UTC)
+ return GeneratedPage(
+ page_id=page_id,
+ page_type=page_type,
+ title=page_id,
+ content="",
+ source_hash="",
+ model_name="",
+ provider_name="template",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=0,
+ target_path=page_id.split(":", 1)[1],
+ created_at=now,
+ updated_at=now,
+ metadata=dict(metadata),
+ )
-# ---------------------------------------------------------------------------
-# Slug identity stability under enrichment
-# ---------------------------------------------------------------------------
-
-
-class TestLayerIdStability:
- def test_enrichment_renames_name_not_id_so_page_key_is_stable(self, tmp_path):
- """The LLM layer-name enrichment mutates ``name`` only; the slug ``id``
- — and therefore the layer page key — is unchanged across the rename."""
- from repowise.core.generation.page_generator.levels import build_level5_coros
-
- node_ids = ["file:a.py", "file:b.py", "file:c.py"]
+ def test_counts_stamped_and_unstamped_members(self):
+ from repowise.core.generation.page_tree import measure_layer_grouping
+
+ report = measure_layer_grouping(
+ [
+ self._page("module_page:a", "module_page", layer_id="layer:core"),
+ self._page("scc_page:c1", "scc_page", layer_id="layer:core"),
+ self._page("module_page:b", "module_page"),
+ # Not grouped under a layer row, so not counted either way.
+ self._page("file_page:a.py", "file_page", layer_id="layer:core"),
+ self._page("repo_overview:demo", "repo_overview"),
+ ]
+ )
+ assert report.grouped == 2
+ assert report.ungrouped == 1
+ assert report.total == 3
+
+ def test_nothing_to_group_is_not_a_clean_result(self):
+ """A run with no groupable page proves nothing about the grouping."""
+ from repowise.core.generation.page_tree import measure_layer_grouping
+
+ report = measure_layer_grouping([self._page("repo_overview:demo", "repo_overview")])
+ assert report.total == 0
+ assert not report.measured
+ assert "not computed" in report.summary_line()
+
+ def test_a_blank_layer_id_does_not_count_as_grouped(self):
+ from repowise.core.generation.page_tree import measure_layer_grouping
+
+ report = measure_layer_grouping([self._page("module_page:a", "module_page", layer_id="")])
+ assert report.grouped == 0
+ assert report.ungrouped == 1
+
+ def test_the_generation_report_carries_the_count(self):
+ from repowise.core.generation.report import GenerationReport
+
+ report = GenerationReport.from_pages(
+ [
+ self._page("module_page:a", "module_page", layer_id="layer:core"),
+ self._page("module_page:b", "module_page"),
+ ]
+ )
+ assert report.layer_grouping.grouped == 1
+ assert report.layer_grouping.ungrouped == 1
- def key_for(name: str) -> str:
- layers = [{"id": "layer:queue", "name": name, "nodeIds": node_ids}]
- run = self._make_run(tmp_path, layers)
- coros = build_level5_coros(run)
- assert len(coros) == 1
- return coros[0][0]
+ def test_the_rendered_report_always_shows_the_row(self):
+ """Hiding it on a zero would make "not measured" look like "all fine"."""
+ from rich.console import Console
- # Heuristic name -> page key.
- before = key_for("Application")
- # Enrichment rewrites the display name; id (and key) must not move.
- after = key_for("Task Queue Core")
- assert before == after == "layer_page:layer:queue"
+ from repowise.core.generation.report import GenerationReport, render_report
- # Reuse the level-5 fixture harness verbatim.
- _make_run = TestBuildLevel5Coros._make_run
+ console = Console(record=True, width=200)
+ render_report(GenerationReport.from_pages([]), console)
+ assert "Layer grouping" in console.export_text()
diff --git a/tests/unit/generation/test_page_generator.py b/tests/unit/generation/test_page_generator.py
index 570ce0767..f200e6568 100644
--- a/tests/unit/generation/test_page_generator.py
+++ b/tests/unit/generation/test_page_generator.py
@@ -650,12 +650,15 @@ async def test_generate_all_uses_in_memory_kg_modules_without_artifact_file():
async def test_generate_all_builds_kg_ctx_from_in_memory_kg_data():
- """Layer pages must generate on a FRESH init via the in-memory KG.
+ """A fresh init reads its layers from the in-memory KG, not from disk.
kg_ctx previously only read knowledge-graph.json, which is written during
- persistence — after generation — so first-run wikis silently had zero
- layer pages (caught live: fresh repowise wiki had 37 module pages and no
- Architecture layers).
+ persistence — after generation — so first-run wikis silently had no layer
+ information at all (caught live: fresh repowise wiki had 37 module pages
+ and no Architecture layers).
+
+ Layers no longer get pages of their own, so the observable result is the
+ provenance stamped on the pages they group.
"""
config = GenerationConfig(
max_tokens=256,
@@ -720,6 +723,12 @@ async def test_generate_all_builds_kg_ctx_from_in_memory_kg_data():
kg_data=kg_data,
)
- layer_pages = [p for p in pages if p.page_type == "layer_page"]
- assert layer_pages, "no layer pages generated from in-memory KG"
- assert any("Service" in p.title for p in layer_pages)
+ assert not [p for p in pages if p.page_type == "layer_page"], (
+ "layer pages are retired; nothing should emit one"
+ )
+ # The KG layer still reached generation: every file page carries it, and
+ # the module page over those files inherits it from them.
+ file_pages = [p for p in pages if p.page_type == "file_page"]
+ assert file_pages, "no file pages generated from in-memory KG"
+ assert {p.metadata.get("layer_id") for p in file_pages} == {"layer:service"}
+ assert {p.metadata.get("layer_name") for p in file_pages} == {"Service"}
diff --git a/tests/unit/server/test_generate.py b/tests/unit/server/test_generate.py
index 09bfb07a0..003d4af29 100644
--- a/tests/unit/server/test_generate.py
+++ b/tests/unit/server/test_generate.py
@@ -260,7 +260,7 @@ def _fake_rehydrated(template_ids: list[str]) -> RehydratedRepo:
for pid in template_ids
]
deps = build_page_dependencies(
- module_groups=[], scc_groups=[], layer_page_of={}, repo_wide_ids=[]
+ module_groups=[], scc_groups=[], repo_wide_ids=[]
)
return RehydratedRepo(
graph_builder=MagicMock(),