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(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.ts
index 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.ts
index 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): Pag
const 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): Pag
version: 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.ts
index 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.py
index 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 datetime
from 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 go
missing 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: float
freshness_status: str
content_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 = None
human_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):
@classmethod
def 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.ts
index 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 every
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsx
index 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.tsx
index 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)]" />
+ )}
+ <span
className={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 }: Doc
const [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.ts
new file mode 100644
index 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.ts
index 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 like
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index 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) {
) : (
<DocsTree
pages={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.py
index 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.asyncio
async def test_list_pages_rejects_unknown_fields(client: AsyncClient, app) -> None:
repo_id, _ = await _create_page(client, app.state.session_factory)