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 file corpus sits above the layer outline, not under it (#1185)

Swati Ahuja3aed87bba44b
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsx
index 00d3813f3..02ff6ce7a 100644
--- a/packages/ui/__tests__/docs/docs-tree.test.tsx
+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx
@@ -417,6 +417,47 @@ describe("DocsTree", () => {
expect(screen.queryByText("api/routes")).not.toBeInTheDocument();
});
+ it("puts the file corpus above the layers, so it never sinks under the outline", () => {
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: SPINE_IDS }),
+ makePage({
+ id: "onboarding:onboarding/getting_started",
+ page_type: "onboarding",
+ title: "Getting Started",
+ target_path: "onboarding/getting_started",
+ parent_page_id: "repo_overview:demo",
+ display_order: 1,
+ }),
+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {
+ layer_id: "layer:runtime",
+ layer_name: "Zebra Runtime",
+ }),
+ stampedModule("module_page:api/routes", "Module: api/routes", {
+ layer_id: "layer:api",
+ layer_name: "Alpha API",
+ }),
+ makePage({ id: "f1", target_path: "src/foo.ts", title: "foo.ts" }),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ // Orientation first, then the way into the files, then the layer outline.
+ // The corpus is the largest thing in the wiki and the thing most readers
+ // came for; it cannot sit below a list that grows with the repository.
+ const corpus = indexOfRow("Auto-documented files (1)");
+ expect(indexOfRow("Repository Overview: demo")).toBeLessThan(indexOfRow("Getting Started"));
+ expect(indexOfRow("Getting Started")).toBeLessThan(corpus);
+ expect(corpus).toBeLessThan(indexOfRow("Zebra Runtime"));
+ // The layers keep their own order behind it, so this cannot pass on a
+ // build that merely shuffled the top-level rows.
+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("Alpha API"));
+ // Still a deliberate drill-in, not opened on load.
+ expect(screen.queryByText("foo.ts")).not.toBeInTheDocument();
+ });
+
it("labels a layer by its id when no member carries the display name", () => {
render(
<DocsTree
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index 99845104a..cb6a84b02 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -416,6 +416,19 @@ function buildStoredTree(
const spinePages = visible.filter(isSpinePage);
const deterministicPages = visible.filter((p) => !isSpinePage(p));
+ // Every deterministic page in one collapsed folder, held apart from the
+ // concept outline so the distinction is obvious. Its interior reuses the
+ // filesystem builder, so the files stay navigable by directory.
+ const referenceFolder: TreeNode | null =
+ deterministicPages.length > 0
+ ? {
+ name: `Auto-documented files (${deterministicPages.length})`,
+ path: AUTO_ROOT_KEY,
+ isDir: true,
+ children: buildTree(deterministicPages),
+ }
+ : null;
+
const byId = new Map(spinePages.map((p) => [p.id, p]));
const childrenOf = new Map<string, DocPageSummary[]>();
const claimed = new Set<string>();
@@ -477,6 +490,12 @@ function buildStoredTree(
// 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)));
+ // The file corpus sits directly after the orientation chapters, ahead of
+ // the layers. It is the largest thing in the wiki by a wide margin and the
+ // thing most readers arrive wanting, so it cannot be the last row of a list
+ // whose length grows with the repository — one layer opened and it is off
+ // the screen. Collapsed, so it costs a single row to keep it in reach.
+ if (referenceFolder) top.push(referenceFolder);
for (const group of grouping.groups) {
top.push({
name: group.label,
@@ -527,16 +546,10 @@ function buildStoredTree(
});
}
- // Every deterministic page in one collapsed folder at the very bottom, held
- // apart from the concept outline so the distinction is obvious. Its interior
- // reuses the filesystem builder, so the files stay navigable by directory.
- if (deterministicPages.length > 0) {
- top.push({
- name: `Auto-documented files (${deterministicPages.length})`,
- path: AUTO_ROOT_KEY,
- isDir: true,
- children: buildTree(deterministicPages),
- });
+ // A store with no concept root has no orientation to sit behind, so the
+ // folder falls to the bottom rather than opening the tree with it.
+ if (referenceFolder && !top.includes(referenceFolder)) {
+ top.push(referenceFolder);
}
return top;