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 docs tree opens on the shape of the repository, not its contents (#1184)

Swati Ahuja9d97b2e22c73
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsx
index f1e94bc77..00d3813f3 100644
--- a/packages/ui/__tests__/docs/docs-tree.test.tsx
+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx
@@ -376,9 +376,45 @@ describe("DocsTree", () => {
// 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.
+ // Each module reads under its own layer, not beside it. The layers start
+ // closed, so open them to see where their members land.
+ fireEvent.click(screen.getByText("Zebra Runtime"));
+ fireEvent.click(screen.getByText("Alpha API"));
expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("runtime/engine"));
expect(indexOfRow("runtime/engine")).toBeLessThan(indexOfRow("Alpha API"));
+ expect(indexOfRow("Alpha API")).toBeLessThan(indexOfRow("api/routes"));
+ });
+
+ it("starts every layer row closed, and opens one on a click", () => {
+ 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 layers themselves are the first screen: a reader meets the shape of
+ // the repository, not every module in it.
+ expect(screen.getByText("Zebra Runtime")).toBeInTheDocument();
+ expect(screen.getByText("Alpha API")).toBeInTheDocument();
+ expect(screen.queryByText("runtime/engine")).not.toBeInTheDocument();
+ expect(screen.queryByText("api/routes")).not.toBeInTheDocument();
+
+ // One click opens one layer and leaves the other shut — so this cannot
+ // pass on a tree that simply failed to render its modules at all.
+ fireEvent.click(screen.getByText("Zebra Runtime"));
+ expect(screen.getByText("runtime/engine")).toBeInTheDocument();
+ expect(screen.queryByText("api/routes")).not.toBeInTheDocument();
});
it("labels a layer by its id when no member carries the display name", () => {
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index f587fb285..99845104a 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -22,7 +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 { groupPagesByLayer, readLayerOrder } from "../lib/layers";
import { cn } from "../lib/cn";
import { statusBadgeClasses, type FreshnessStatus } from "../lib/confidence";
import type { DocPageSummary } from "@repowise-dev/types/docs";
@@ -855,12 +855,20 @@ export function DocsTree({
// another repo's default-open rows.
const dirs = new Set<string>(STRAY_GROUP_KEYS);
dirs.add(ONBOARDING_DIR_KEY);
- // Domain view: open the section spine (the layers) so the concept titles
- // read as a clean table of contents on load. Everything else starts shut —
- // concept pages, the bottom Auto-documented folder, and the file directories
- // inside it — so the outline is what a reader sees first, with the files a
- // deliberate click away. A spine node opens by default only when it has a
- // spine child of its own (a layer holding concepts).
+ // Domain view: everything starts shut — the layer rows, concept pages, the
+ // bottom Auto-documented folder, and the file directories inside it — so
+ // the first screen is the shape of the repository rather than its contents.
+ //
+ // The layers used to open on load, on the reasoning that a shut one hides
+ // the outline under it. That reasoning inverted once the layers became
+ // grouping rows over every module: opening them all put roughly ninety
+ // near-identically-named module rows on the first screen, which buries the
+ // layer names, the orientation chapters and the file corpus alike. A closed
+ // layer costs one click; an open one costs a reader the whole first screen.
+ //
+ // A concept page that parents other concept pages still opens, so a stored
+ // wiki that predates the grouping rows — where the modules hang off a page
+ // per layer — reads the same as it always did.
const hasSpineChild = new Set(
pages
.filter((p) => SPINE_TYPES.has(p.page_type) && p.parent_page_id)
@@ -868,11 +876,6 @@ export function DocsTree({
);
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 {