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(docs): the tree groups modules under their layer from the members (#1170)
Swati Ahujaeb97dc0ce15b
diff --git a/packages/api-client/src/hosted.test.ts b/packages/api-client/src/hosted.test.tsindex 89da7e7e9..927243933 100644--- a/packages/api-client/src/hosted.test.ts+++ b/packages/api-client/src/hosted.test.ts@@ -7,6 +7,7 @@ import {mapHostedPage,mapHostedRepo,mapHostedSearchResult,+ toPageSummary,} from "./hosted";// ---------------------------------------------------------------------------@@ -145,6 +146,30 @@ describe("mapHostedPage", () => {it("falls back to page_id when the id alias is absent (old snapshots)", () => {expect(mapHostedPage({ page_id: "p1" }, "r").id).toBe("p1");});++ it("promotes the layer stamp so it survives the summary trim", () => {+ // The docs tree groups modules under their layer from this stamp and is+ // drawn from a summary listing, which drops `metadata` wholesale. Left+ // inside the blob the stamp would vanish, and every layer group with it.+ const page = mapHostedPage(+ {+ page_id: "module_page:src/api",+ page_type: "module_page",+ target_path: "src/api",+ metadata: { layer_id: "layer:api", layer_name: "API Surface" },+ },+ "repo-1",+ );+ expect(page.layer_id).toBe("layer:api");+ expect(page.layer_name).toBe("API Surface");+ expect(toPageSummary(page).layer_id).toBe("layer:api");+ });++ it("reports no layer rather than an empty one when nothing stamped it", () => {+ const page = mapHostedPage({ page_id: "p1", metadata: {} }, "r");+ expect(page.layer_id).toBeNull();+ expect(page.layer_name).toBeNull();+ });});describe("mapHostedDeadCodeFinding", () => {diff --git a/packages/api-client/src/hosted.ts b/packages/api-client/src/hosted.tsindex fd62e5366..c0a86da4a 100644--- a/packages/api-client/src/hosted.ts+++ b/packages/api-client/src/hosted.ts@@ -252,6 +252,15 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Pagconst num = (k: string, fallback = 0): number =>typeof raw[k] === "number" ? (raw[k] as number) : fallback;const content = str("content");+ const metadata = (raw.metadata as Record<string, unknown> | undefined) ?? {};+ // The layer stamp gets a field of its own because `toPageSummary` drops the+ // whole metadata blob, and the docs tree groups pages by this stamp off a+ // summary listing. Blank reads as `null`, never "", so "no layer claimed+ // this page" cannot be mistaken for a layer whose name is empty.+ const stamp = (key: string): string | null => {+ const value = metadata[key];+ return typeof value === "string" && value ? value : null;+ };return {id: str("id") || str("page_id"),repository_id: repoId,@@ -270,7 +279,9 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Pagversion: num("version", 1),confidence: num("confidence", 1),freshness_status: str("freshness_status") || "fresh",- metadata: (raw.metadata as Record<string, unknown> | undefined) ?? {},+ metadata,+ layer_id: stamp("layer_id"),+ layer_name: stamp("layer_name"),human_notes: null,created_at: str("created_at"),updated_at: str("updated_at") || str("created_at"),diff --git a/packages/api-client/src/types/pages.ts b/packages/api-client/src/types/pages.tsindex 2c7e68291..81bb4236f 100644--- a/packages/api-client/src/types/pages.ts+++ b/packages/api-client/src/types/pages.ts@@ -32,6 +32,12 @@ export interface PageSummary {* hydrate a few rows of an otherwise summary listing. */content?: string;metadata?: Record<string, unknown>;+ /** Which layer of the architecture spine claims this page, stamped at+ * generation time. Promoted out of `metadata` because a list needs it: the+ * docs tree groups modules under their layer from this stamp, and a listing+ * drops the blob. Absent or `null` means no layer claimed the page. */+ layer_id?: string | null;+ layer_name?: string | null;human_notes: string | null;created_at: string;updated_at: string;diff --git a/packages/server/src/repowise/server/schemas/pages.py b/packages/server/src/repowise/server/schemas/pages.pyindex 65ea79260..0c9fc4328 100644--- a/packages/server/src/repowise/server/schemas/pages.py+++ b/packages/server/src/repowise/server/schemas/pages.py@@ -8,12 +8,45 @@ from datetime import datetimefrom pydantic import BaseModel-def _summary_fields(obj: object) -> dict:+def _layer_stamp(obj: object, metadata: dict | None) -> tuple[str | None, str | None]:+ """Which layer this page belongs to, read off its metadata blob.++ Promoted out of ``metadata`` because a *list* of pages needs it: the docs+ tree groups modules under their layer from this stamp, and it draws itself+ from a summary listing, which drops the blob. Two short strings per row is+ a rounding error next to what the summary saves.++ The caller passes ``metadata`` when it has already parsed it. Otherwise the+ blob is only parsed when its raw text mentions the key at all, so a listing+ of pages that carry no stamp costs a substring scan rather than a decode.+ """+ if metadata is None:+ raw = getattr(obj, "metadata_json", None) or ""+ if "layer_id" not in raw:+ return None, None+ try:+ metadata = json.loads(raw)+ except ValueError:+ # A blob that will not parse is a page we cannot place. Say+ # nothing rather than guess — the tree treats that as "no layer".+ return None, None+ if not isinstance(metadata, dict):+ return None, None+ layer_id = metadata.get("layer_id")+ layer_name = metadata.get("layer_name")+ return (+ layer_id if isinstance(layer_id, str) and layer_id else None,+ layer_name if isinstance(layer_name, str) and layer_name else None,+ )+++def _summary_fields(obj: object, metadata: dict | None = None) -> dict:"""The part of a page row that costs nothing to send.Shared by both response models so a field added to one can never gomissing from the other."""+ layer_id, layer_name = _layer_stamp(obj, metadata)return dict(id=obj.id, # type: ignore[attr-defined]repository_id=obj.repository_id, # type: ignore[attr-defined]@@ -31,6 +64,8 @@ def _summary_fields(obj: object) -> dict:confidence=obj.confidence, # type: ignore[attr-defined]freshness_status=obj.freshness_status, # type: ignore[attr-defined]content_chars=len(obj.content or ""), # type: ignore[attr-defined]+ layer_id=layer_id,+ layer_name=layer_name,human_notes=obj.human_notes, # type: ignore[attr-defined]parent_page_id=obj.parent_page_id, # type: ignore[attr-defined]display_order=obj.display_order, # type: ignore[attr-defined]@@ -69,6 +104,11 @@ class PageSummaryResponse(BaseModel):confidence: floatfreshness_status: strcontent_chars: int+ # Which layer this page belongs to, stamped at generation time. ``None``+ # on a page no layer claimed, and on every page of a repo indexed before+ # layers were stamped — both of which read as "ungrouped", not as an error.+ layer_id: str | None = None+ layer_name: str | None = Nonehuman_notes: str | None = None# Position in the wiki outline. Older rows carry no placement, which reads# as a flat wiki and is what those rows actually describe.@@ -90,10 +130,13 @@ class PageResponse(PageSummaryResponse):@classmethoddef from_orm(cls, obj: object) -> PageResponse:+ # Parsed once and handed down, so a full listing never decodes the same+ # blob twice just to read the layer stamp out of it.+ metadata = json.loads(obj.metadata_json) # type: ignore[attr-defined]return cls(- **_summary_fields(obj),+ **_summary_fields(obj, metadata),content=obj.content, # type: ignore[attr-defined]- metadata=json.loads(obj.metadata_json), # type: ignore[attr-defined]+ metadata=metadata,)diff --git a/packages/types/src/docs.ts b/packages/types/src/docs.tsindex 301150816..ac8aae7a6 100644--- a/packages/types/src/docs.ts+++ b/packages/types/src/docs.ts@@ -48,6 +48,15 @@ export interface DocPageSummary {*/content?: string;metadata?: Record<string, unknown>;+ /**+ * Which layer of the architecture spine this page belongs to, stamped at+ * generation time. Promoted out of `metadata` because a *list* needs it: the+ * docs tree groups modules under their layer from this stamp, and a listing+ * drops the metadata blob. Absent or `null` means no layer claimed the page+ * — a repo with no curated spine, or a page the grouping leaves where it is.+ */+ layer_id?: string | null;+ layer_name?: string | null;human_notes: string | null;/*** Position in the wiki outline, computed once at generation time so everydiff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsxindex e1fdcb8f0..f1e94bc77 100644--- a/packages/ui/__tests__/docs/docs-tree.test.tsx+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx@@ -315,6 +315,209 @@ describe("DocsTree", () => {expect(screen.getByText("infra-0.yml")).toBeInTheDocument();});+ // -------------------------------------------------------------------------+ // Layer grouping from the stamp on the members+ // -------------------------------------------------------------------------+ //+ // The wiki no longer writes a page per layer, so a module cannot be parented+ // onto one. Every module and cycle carries the layer that claims it, and the+ // tree builds the grouping row from that.++ /** A repo whose modules hang straight off the overview, each stamped. */+ const SPINE_IDS = ["layer:runtime", "layer:api"];+ const layeredRoot = (metadata: Record<string, unknown> = {}) =>+ makePage({+ id: "repo_overview:demo",+ page_type: "repo_overview",+ title: "Repository Overview: demo",+ target_path: "demo",+ parent_page_id: null,+ display_order: 0,+ metadata,+ });+ const stampedModule = (+ id: string,+ title: string,+ stamp: { layer_id?: string; layer_name?: string } = {},+ order = 1,+ ) =>+ makePage({+ id,+ page_type: "module_page",+ title,+ target_path: id.replace("module_page:", ""),+ parent_page_id: "repo_overview:demo",+ display_order: order,+ ...stamp,+ });++ it("groups modules under a layer row built from the stamp on the modules", () => {+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: SPINE_IDS }),+ stampedModule("module_page:api/routes", "Module: api/routes", {+ layer_id: "layer:api",+ layer_name: "Alpha API",+ }),+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {+ layer_id: "layer:runtime",+ layer_name: "Zebra Runtime",+ }),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ // The layer row exists even though no page describes the layer.+ expect(screen.getByText("Zebra Runtime")).toBeInTheDocument();+ expect(screen.getByText("Alpha API")).toBeInTheDocument();+ // Ordered by the overview's spine, which disagrees with the alphabet — so+ // this cannot pass on an alphabetical grouping.+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("Alpha API"));+ expect("Zebra Runtime".localeCompare("Alpha API")).toBeGreaterThan(0);+ // Each module reads under its own layer, not beside it.+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("runtime/engine"));+ expect(indexOfRow("runtime/engine")).toBeLessThan(indexOfRow("Alpha API"));+ });++ it("labels a layer by its id when no member carries the display name", () => {+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: ["layer:api"] }),+ stampedModule("module_page:api/routes", "Module: api/routes", {+ layer_id: "layer:api",+ }),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(screen.getByText("layer:api")).toBeInTheDocument();+ });++ it("reads the stamp out of metadata when the row was fetched in full", () => {+ // A hydrated row carries the blob rather than the promoted column.+ const module = makePage({+ id: "module_page:api/routes",+ page_type: "module_page",+ title: "Module: api/routes",+ target_path: "api/routes",+ parent_page_id: "repo_overview:demo",+ metadata: { layer_id: "layer:api", layer_name: "Alpha API" },+ });+ render(+ <DocsTree+ pages={[layeredRoot({ layer_order_ids: ["layer:api"] }), module]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(screen.getByText("Alpha API")).toBeInTheDocument();+ });++ it("warns when the overview names a spine but nothing carries a stamp", () => {+ // A listing that dropped the stamp and a repo with no layers at all look+ // identical in the rendered tree, so the two must not be told apart by+ // eye. The overview declaring a spine is the signal something is wrong.+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: SPINE_IDS }),+ stampedModule("module_page:api/routes", "Module: api/routes"),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(warn).toHaveBeenCalled();+ expect(warn.mock.calls.flat().join(" ")).toContain("layer");+ // The pages are still shown — a missing grouping never hides a page.+ expect(screen.getByText("api/routes")).toBeInTheDocument();+ warn.mockRestore();+ });++ it("stays quiet on a repo that genuinely has no layers", () => {+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ render(+ <DocsTree+ pages={[+ layeredRoot(),+ stampedModule("module_page:api/routes", "Module: api/routes"),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(warn).not.toHaveBeenCalled();+ expect(screen.getByText("api/routes")).toBeInTheDocument();+ warn.mockRestore();+ });++ it("warns about a stamped layer the spine does not list, and still shows it", () => {+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: ["layer:api"] }),+ stampedModule("module_page:api/routes", "Module: api/routes", {+ layer_id: "layer:api",+ layer_name: "Alpha API",+ }),+ stampedModule("module_page:odd/bits", "Module: odd/bits", {+ layer_id: "layer:ghost",+ layer_name: "Ghost",+ }),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(warn.mock.calls.flat().join(" ")).toContain("layer:ghost");+ // Off-spine layers sort last rather than disappearing.+ expect(indexOfRow("Alpha API")).toBeLessThan(indexOfRow("Ghost"));+ });++ it("points a layer row at the knowledge graph, where its diagram lives", () => {+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: ["layer:api"] }),+ stampedModule("module_page:api/routes", "Module: api/routes", {+ layer_id: "layer:api",+ layer_name: "Alpha API",+ }),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ knowledgeGraphHref="/repos/r1/knowledge-graph"+ />,+ );+ const link = screen.getByRole("link", { name: /Alpha API.*knowledge graph/i });+ expect(link).toHaveAttribute("href", "/repos/r1/knowledge-graph");+ });++ it("omits the graph link when the host has no route to offer", () => {+ render(+ <DocsTree+ pages={[+ layeredRoot({ layer_order_ids: ["layer:api"] }),+ stampedModule("module_page:api/routes", "Module: api/routes", {+ layer_id: "layer:api",+ layer_name: "Alpha API",+ }),+ ]}+ selectedPageId={null}+ onSelectPage={() => {}}+ />,+ );+ expect(screen.queryByRole("link")).not.toBeInTheDocument();+ // Selecting the layer row still works — the link is an extra, not the row.+ expect(screen.getByText("Alpha API")).toBeInTheDocument();+ });+it("lifts a concept's file pages to the bottom folder, leaving the concept a clean leaf", () => {// The concept stays a pure title in the outline; its files move wholesale// into the single bottom folder rather than sitting beside it.diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsxindex 78e5fb05b..f587fb285 100644--- a/packages/ui/src/docs/docs-tree.tsx+++ b/packages/ui/src/docs/docs-tree.tsx@@ -22,6 +22,7 @@ import {type OnboardingSlot,} from "../lib/page-types";import { RAW_GRAPH_ID, displayLabel, treeLabel } from "./page-labels";+import { groupPagesByLayer, readLayerOrder, readLayerStamp } from "../lib/layers";import { cn } from "../lib/cn";import { statusBadgeClasses, type FreshnessStatus } from "../lib/confidence";import type { DocPageSummary } from "@repowise-dev/types/docs";@@ -30,6 +31,10 @@ import type { DocPageSummary } from "@repowise-dev/types/docs";// real target_path (which never starts with "@") so directory lookups don't// collide with module paths.const ONBOARDING_DIR_KEY = "@onboarding";+// Same idea for a layer's grouping row. A layer has no page behind it, so the+// row needs a key of its own and it must not look like a page id.+const LAYER_DIR_PREFIX = "@layer:";+const layerDirKey = (layerId: string) => `${LAYER_DIR_PREFIX}${layerId}`;// Tree expansion survives reloads (per-browser, not per-repo — paths rarely// collide across repos and the fallback is just the default expansion).const EXPANDED_DIRS_KEY = "repowise:docs-tree-expanded";@@ -46,6 +51,10 @@ interface TreeNode {children: TreeNode[];/** Dotted outline number from the stored tree ("2.4.1"), when the page has one. */section?: string;+ /** Where the row's "see the picture" link goes, for rows that have one. */+ href?: string;+ /** What that link is for, read out to a screen reader. */+ hrefLabel?: string;}interface DocsTreeProps {@@ -53,6 +62,15 @@ interface DocsTreeProps {selectedPageId: string | null;onSelectPage: (page: DocPageSummary) => void;className?: string;+ /**+ * The host's knowledge-graph route, linked from every layer row.+ *+ * A layer is a grouping of the knowledge graph, and the graph is where its+ * diagram is drawn and explorable — the tree only lists what is in the layer.+ * Optional because the route is the host's to name, and a host that has no+ * such view simply gets a row with no link rather than a dead one.+ */+ knowledgeGraphHref?: string;}// ---------------------------------------------------------------------------@@ -348,7 +366,45 @@ function compareSiblings(a: DocPageSummary, b: DocPageSummary): number {);}-function buildStoredTree(pages: DocPageSummary[]): TreeNode[] {+/**+ * Say out loud when the layer grouping and the repository disagree.+ *+ * A tree with no layer rows has two very different causes: a repository that+ * genuinely has no layers, and a page listing that stopped carrying the stamp+ * the grouping reads. They render identically, so the difference has to be+ * reported rather than looked at. The overview naming a spine while not one+ * page carries a stamp is the signal that it is the second one.+ */+function reportLayerGrouping(+ grouping: ReturnType<typeof groupPagesByLayer>,+ spine: readonly string[],+): void {+ if (spine.length > 0 && grouping.stamped === 0) {+ console.warn(+ `[docs-tree] the repository overview names ${spine.length} layers, but not one page ` ++ "carries a layer stamp, so the outline is flat. Check that the page listing still " ++ "serves layer_id.",+ );+ }+ if (spine.length === 0 && grouping.stamped > 0) {+ console.warn(+ `[docs-tree] ${grouping.stamped} pages name a layer, but the repository overview ` ++ "records no layer order. Grouping by name, which says nothing about which layer " ++ "depends on which.",+ );+ }+ if (spine.length > 0 && grouping.offSpine.length > 0) {+ console.warn(+ `[docs-tree] ${grouping.offSpine.length} layers are stamped on pages but absent from ` ++ `the overview's spine, so they sort last: ${grouping.offSpine.join(", ")}`,+ );+ }+}++function buildStoredTree(+ pages: DocPageSummary[],+ knowledgeGraphHref?: string,+): TreeNode[] {// A tombstoned page documents a file that no longer exists. It keeps its row// and its content, but the tree deliberately has no place for it, so it must// be excluded here rather than treated as an unplaced page.@@ -408,12 +464,36 @@ function buildStoredTree(pages: DocPageSummary[]): TreeNode[] {page: root,children: [],});- top.push(- ...(childrenOf.get(root.id) ?? [])- .slice()- .sort(compareSiblings)- .map((child) => toNode(child, root)),- );+ // The layers are the top rung of the outline, and they are grouping rows+ // rather than pages: the layer a module belongs to is stamped on the module+ // itself, so the grouping holds whether or not the wiki describes the layer+ // anywhere. On a wiki that does parent modules onto a layer page, no child+ // of the root carries a stamp and this is a no-op.+ const children = (childrenOf.get(root.id) ?? []).slice().sort(compareSiblings);+ const spine = readLayerOrder(root);+ const grouping = groupPagesByLayer(children, spine);+ reportLayerGrouping(grouping, spine);+ // Unclaimed children keep their place ahead of the layers: onboarding+ // chapters and the architecture diagram sort before any module, and that+ // is the order a reader should meet them in.+ top.push(...grouping.ungrouped.map((child) => toNode(child, root)));+ for (const group of grouping.groups) {+ top.push({+ name: group.label,+ path: layerDirKey(group.id),+ isDir: true,+ children: group.pages.map((child) => toNode(child, root)),+ // The tree can only list what a layer holds. The picture of it — which+ // layer sits on which, and what crosses between them — is the+ // knowledge graph, so the row carries a way there.+ ...(knowledgeGraphHref+ ? {+ href: knowledgeGraphHref,+ hrefLabel: `Show ${group.label} in the knowledge graph`,+ }+ : {}),+ });+ }}// Concept pages the walk never reached. Grouped by type rather than dropped:@@ -547,69 +627,90 @@ function TreeItem({const hasChildren = node.children.length > 0;if (node.isDir) {- return (- <div>- <button- onClick={() => {- toggleDir(node.path);- if (node.page) onSelectPage(node.page);- }}- {...(node.page && node.page.title !== node.name ? { title: node.page.title } : {})}+ const row = (+ <button+ onClick={() => {+ toggleDir(node.path);+ if (node.page) onSelectPage(node.page);+ }}+ {...(node.page && node.page.title !== node.name ? { title: node.page.title } : {})}+ className={cn(+ "flex w-full min-w-0 flex-1 items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs transition-colors hover:bg-[var(--color-bg-elevated)]",+ // Top-level sections (layers, the Onboarding folder, the bottom+ // Auto-documented folder) get air above them so each group reads as+ // a distinct block rather than one long list.+ depth === 0 && "mt-2 first:mt-0",+ isSelected+ ? "bg-[var(--color-accent-muted)] text-[var(--color-accent-primary)]"+ : "text-[var(--color-text-secondary)]",+ )}+ style={{ paddingLeft: `${depth * 16 + 8}px` }}+ >+ {hasChildren ? (+ isExpanded ? (+ <ChevronDown className="h-3 w-3 shrink-0 opacity-50" />+ ) : (+ <ChevronRight className="h-3 w-3 shrink-0 opacity-50" />+ )+ ) : (+ <span className="w-3 shrink-0" />+ )}+ <SectionNumber depth={depth} section={node.section} />+ {node.path === ONBOARDING_DIR_KEY ? (+ <Compass className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]" />+ ) : hidesTreeIcon(node.page) ? null : node.page ? (+ // A layer keeps its section icon as the anchor for its group; a+ // concept content dir (a module with children) drops its folder+ // glyph so the outline is not a column of identical icons. The+ // chevron already marks it as expandable.+ <PageIcon+ pageType={node.page.page_type}+ className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]"+ />+ ) : isExpanded ? (+ <FolderOpen className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)] opacity-70" />+ ) : (+ <Folder className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)]" />+ )}+ <spanclassName={cn(- "flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs transition-colors hover:bg-[var(--color-bg-elevated)]",- // Top-level sections (layers, the Onboarding folder, the bottom- // Auto-documented folder) get air above them so each group reads as- // a distinct block rather than one long list.- depth === 0 && "mt-2 first:mt-0",- isSelected- ? "bg-[var(--color-accent-muted)] text-[var(--color-accent-primary)]"- : "text-[var(--color-text-secondary)]",+ // Wraps rather than truncates. A section title cut to+ // "Documentation Generation Engi…" names nothing, and the tree+ // has the vertical room — it is a list of a few dozen concept+ // rows, not a viewport-bound table.+ "min-w-0 text-left font-medium [overflow-wrap:anywhere]",+ // A top-level section is the parent of everything indented under+ // it, so it carries the strongest weight in the tree.+ (node.path === ONBOARDING_DIR_KEY || depth === 0) &&+ "font-semibold text-[var(--color-text-primary)]",)}- style={{ paddingLeft: `${depth * 16 + 8}px` }}>- {hasChildren ? (- isExpanded ? (- <ChevronDown className="h-3 w-3 shrink-0 opacity-50" />- ) : (- <ChevronRight className="h-3 w-3 shrink-0 opacity-50" />- )- ) : (- <span className="w-3 shrink-0" />- )}- <SectionNumber depth={depth} section={node.section} />- {node.path === ONBOARDING_DIR_KEY ? (- <Compass className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]" />- ) : hidesTreeIcon(node.page) ? null : node.page ? (- // A layer keeps its section icon as the anchor for its group; a- // concept content dir (a module with children) drops its folder- // glyph so the outline is not a column of identical icons. The- // chevron already marks it as expandable.- <PageIcon- pageType={node.page.page_type}- className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]"- />- ) : isExpanded ? (- <FolderOpen className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)] opacity-70" />- ) : (- <Folder className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)]" />- )}- <span- className={cn(- // Wraps rather than truncates. A section title cut to- // "Documentation Generation Engi…" names nothing, and the tree- // has the vertical room — it is a list of a few dozen concept- // rows, not a viewport-bound table.- "min-w-0 text-left font-medium [overflow-wrap:anywhere]",- // A top-level section is the parent of everything indented under- // it, so it carries the strongest weight in the tree.- (node.path === ONBOARDING_DIR_KEY || depth === 0) &&- "font-semibold text-[var(--color-text-primary)]",- )}- >- {node.name}- </span>- <RowMarkers page={node.page} showFreshness={showFreshness} />- </button>+ {node.name}+ </span>+ <RowMarkers page={node.page} showFreshness={showFreshness} />+ </button>+ );++ return (+ <div>+ {node.href ? (+ // The row itself expands; the trailing link leaves for the graph.+ // Two separate targets rather than one that guesses which was meant,+ // and an anchor rather than a button so it can be opened in a tab.+ <div className="flex items-center">+ {row}+ <a+ href={node.href}+ aria-label={node.hrefLabel}+ title={node.hrefLabel}+ className="shrink-0 rounded-md p-1.5 text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-elevated)] hover:text-[var(--color-accent-primary)]"+ >+ <Network className="h-3.5 w-3.5" />+ </a>+ </div>+ ) : (+ row+ )}{isExpanded && hasChildren && (<div>@@ -731,7 +832,13 @@ function RowMarkers({type ViewMode = "domain" | "folder";-export function DocsTree({ pages, selectedPageId, onSelectPage, className }: DocsTreeProps) {+export function DocsTree({+ pages,+ selectedPageId,+ onSelectPage,+ className,+ knowledgeGraphHref,+}: DocsTreeProps) {const [search, setSearch] = useState("");const [typeFilter, setTypeFilter] = useState<TypeFilter>("all");const [freshnessFilter, setFreshnessFilter] = useState<FreshnessFilter>("all");@@ -761,6 +868,11 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc);for (const page of pages) {if (hasSpineChild.has(page.id) && SPINE_TYPES.has(page.page_type)) dirs.add(page.id);+ // A layer's grouping row has no page behind it, so the rule above cannot+ // reach it. It opens for the same reason a layer page did: the layers are+ // the top rung, and a shut one hides the whole outline under it.+ const layer = readLayerStamp(page);+ if (layer) dirs.add(layerDirKey(layer.id));}if (typeof window !== "undefined") {try {@@ -790,8 +902,11 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Docconst [showFreshness, setShowFreshness] = useState(false);const tree = useMemo(- () => (viewMode === "domain" ? buildStoredTree(pages) : buildTree(pages)),- [pages, viewMode],+ () =>+ viewMode === "domain"+ ? buildStoredTree(pages, knowledgeGraphHref)+ : buildTree(pages),+ [pages, viewMode, knowledgeGraphHref],);const filteredTree = useMemo(() => filterTree(tree, search, typeFilter, freshnessFilter),diff --git a/packages/ui/src/lib/layers.ts b/packages/ui/src/lib/layers.tsnew file mode 100644index 000000000..1e55a50ab--- /dev/null+++ b/packages/ui/src/lib/layers.ts@@ -0,0 +1,122 @@+// Which layer of the architecture spine a page belongs to, and how to group a+// list of pages by it.+//+// The wiki does not write a page per layer, so a module cannot be parented onto+// one. Instead every module and cycle is stamped at generation time with the+// layer that claims it, and the reader-facing groupings are built from those+// stamps — which means the grouping survives the absence of any layer page.+//+// The order of the layers themselves is a property of the repository, computed+// once from its import graph and recorded on the overview page. It is read from+// there rather than re-derived (or alphabetised, which would put "API" above+// "Runtime" and say something untrue about the dependency direction).++import type { DocPageSummary } from "@repowise-dev/types/docs";++/** The layer id and display name stamped on a page, if any. */+export interface LayerStamp {+ id: string;+ /** Curated display text. Absent on a page stamped before names were kept. */+ name?: string;+}++function text(value: unknown): string | undefined {+ return typeof value === "string" && value ? value : undefined;+}++/**+ * The layer stamp on a page.+ *+ * Read from the promoted columns first, falling back to the metadata blob: a+ * listing serves the columns (the blob is dropped for size), while a row+ * fetched in full carries the blob and a backend older than the columns serves+ * only the blob. `undefined` means no layer claimed this page.+ */+export function readLayerStamp(page: DocPageSummary): LayerStamp | undefined {+ const id = text(page.layer_id) ?? text(page.metadata?.["layer_id"]);+ if (!id) return undefined;+ const name = text(page.layer_name) ?? text(page.metadata?.["layer_name"]);+ return name ? { id, name } : { id };+}++/**+ * The repository's layer spine, top of the dependency order first.+ *+ * Recorded on the overview page at generation time. `layer_order_ids` is the+ * join key; `layer_order` is the older list of display names, kept as a+ * fallback for wikis written before the ids were stored.+ */+export function readLayerOrder(+ page: { metadata?: Record<string, unknown> } | undefined,+): string[] {+ const raw = page?.metadata?.["layer_order_ids"] ?? page?.metadata?.["layer_order"];+ return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === "string") : [];+}++export interface LayerGroup {+ id: string;+ /** What the row is called: the curated name, or the id when none was kept. */+ label: string;+ pages: DocPageSummary[];+}++export interface LayerGrouping {+ /** One per layer that actually claimed a page, in spine order. */+ groups: LayerGroup[];+ /** Pages no layer claimed, in the order they were given. */+ ungrouped: DocPageSummary[];+ /** How many pages carried a stamp at all. */+ stamped: number;+ /** Stamped layer ids the spine does not list, in first-seen order. */+ offSpine: string[];+}++/**+ * Bucket pages by the layer stamped on them, ordered by the given spine.+ *+ * Pure and quiet: it reports what it found (including the ways the inputs+ * disagree) and leaves the complaining to the caller, which knows whether the+ * disagreement is worth a reader's attention.+ *+ * A layer the spine does not list still gets a group — sorted after the ones it+ * does list — because dropping the group would drop the pages in it.+ */+export function groupPagesByLayer(+ pages: readonly DocPageSummary[],+ spine: readonly string[],+): LayerGrouping {+ const rank = new Map(spine.map((id, i) => [id, i]));+ const groups = new Map<string, LayerGroup>();+ const ungrouped: DocPageSummary[] = [];+ const offSpine: string[] = [];+ let stamped = 0;++ for (const page of pages) {+ const layer = readLayerStamp(page);+ if (!layer) {+ ungrouped.push(page);+ continue;+ }+ stamped += 1;+ if (!rank.has(layer.id) && !groups.has(layer.id)) offSpine.push(layer.id);+ const existing = groups.get(layer.id);+ if (existing) {+ existing.pages.push(page);+ // The first member that carries a curated name gets to name the row; the+ // id is only ever a stand-in for one.+ if (existing.label === existing.id && layer.name) existing.label = layer.name;+ } else {+ groups.set(layer.id, { id: layer.id, label: layer.name ?? layer.id, pages: [page] });+ }+ }++ const ordered = [...groups.values()].sort((a, b) => {+ // Off-spine layers sort last, then by label so their order is at least+ // stable rather than dependent on which page happened to come first.+ const ra = rank.get(a.id) ?? Number.MAX_SAFE_INTEGER;+ const rb = rank.get(b.id) ?? Number.MAX_SAFE_INTEGER;+ return ra - rb || a.label.localeCompare(b.label);+ });++ return { groups: ordered, ungrouped, stamped, offSpine };+}diff --git a/packages/ui/src/present/build-present-model.ts b/packages/ui/src/present/build-present-model.tsindex 6c093a523..511e26ea7 100644--- a/packages/ui/src/present/build-present-model.ts+++ b/packages/ui/src/present/build-present-model.ts@@ -12,6 +12,7 @@ import {clampProse,countWords,} from "./split-markdown";+import { readLayerOrder } from "../lib/layers";import type { PresentModel, PresentSlide, PresentStep } from "./types";// Curation caps keep the deck tight and premium on large repos.@@ -44,10 +45,10 @@ export function readTour(overview: DocPage | undefined): TourStop[] {}));}-export function readLayerOrder(overview: DocPage | undefined): string[] {- const raw = overview?.metadata?.["layer_order_ids"] ?? overview?.metadata?.["layer_order"];- return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === "string") : [];-}+// The spine reader lives with the rest of the layer logic — the docs tree+// groups by the same order this deck presents in, and one repository can only+// have one layer order.+export { readLayerOrder } from "../lib/layers";/*** A readable repo name from the overview page title. Titles look likediff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsxindex ae6ac35a9..779dbbe21 100644--- a/packages/web/src/components/docs/docs-explorer.tsx+++ b/packages/web/src/components/docs/docs-explorer.tsx@@ -255,6 +255,9 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {) : (<DocsTreepages={pages}+ // Where a layer row sends a reader after the picture rather than the+ // list: the graph draws the layers and what crosses between them.+ knowledgeGraphHref={`/repos/${repoId}/knowledge-graph`}// The id, not the fetched page: the row should highlight on click,// not once its body has come back.selectedPageId={selectedPageId}diff --git a/tests/unit/server/test_pages.py b/tests/unit/server/test_pages.pyindex 9622cb559..e3054fe5c 100644--- a/tests/unit/server/test_pages.py+++ b/tests/unit/server/test_pages.py@@ -83,6 +83,58 @@ async def test_list_pages_summary_drops_the_heavy_fields(assert row["content_chars"] == len("# Main module\n\nEntry point.")+async def test_list_pages_summary_keeps_the_layer_stamp(+ client: AsyncClient, app+) -> None:+ """Which layer a page belongs to survives the summary trim.++ The docs tree groups modules under their layer from this stamp, and it+ draws itself from a summary listing. Leaving the stamp inside the dropped+ metadata blob would collapse every layer group with nothing to show for+ it, so the two keys are promoted to columns of their own.+ """+ repo = await create_test_repo(client)+ repo_id = repo["id"]+ async with get_session(app.state.session_factory) as session:+ await crud.upsert_page(+ session,+ page_id="module_page:src/api",+ repository_id=repo_id,+ page_type="module_page",+ title="Module: src/api",+ content="body",+ target_path="src/api",+ source_hash="abc123",+ model_name="mock",+ provider_name="mock",+ metadata={"layer_id": "layer:api", "layer_name": "API Surface"},+ )++ resp = await client.get(+ "/api/pages", params={"repo_id": repo_id, "fields": "summary"}+ )+ assert resp.status_code == 200+ row = resp.json()[0]+ assert "metadata" not in row+ assert row["layer_id"] == "layer:api"+ assert row["layer_name"] == "API Surface"+++async def test_list_pages_summary_has_no_layer_stamp_when_unstamped(+ client: AsyncClient, app+) -> None:+ """A page with no layer says so, rather than borrowing someone else's."""+ repo_id, _ = await _create_page(client, app.state.session_factory)+ resp = await client.get(+ "/api/pages", params={"repo_id": repo_id, "fields": "summary"}+ )+ row = resp.json()[0]+ assert row["layer_id"] is None+ assert row["layer_name"] is None++@pytest.mark.asyncioasync def test_list_pages_rejects_unknown_fields(client: AsyncClient, app) -> None:repo_id, _ = await _create_page(client, app.state.session_factory)