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.

fix(docs-tree): stop an unclaimed module from posing as a layer (#1187)

Swati Ahujae9d6920ec248
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsx
index 30fb8f4a6..16899a959 100644
--- a/packages/ui/__tests__/docs/docs-tree.test.tsx
+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx
@@ -544,8 +544,17 @@ describe("DocsTree", () => {
const layer = labels.find((l) => l.includes("Alpha API")) ?? "";
expect(layer).not.toBe("");
expect(layer).not.toMatch(/^\d/);
- // And the unclaimed module next to it does not show its global number.
- const stray = labels.find((l) => l.includes("odd/bits")) ?? "";
+ // The row holding the modules no layer claimed is a grouping row too, so
+ // it has no number of its own either. (The unclaimed module itself is no
+ // longer on the top rung under a declared spine — it sits inside this row.
+ // The case where it does reach the top rung, on a repo with no spine at
+ // all, is covered by the test above.)
+ const unlayeredRow = labels.find((l) => l.includes("Modules with no layer")) ?? "";
+ expect(unlayeredRow).not.toBe("");
+ expect(unlayeredRow).not.toMatch(/^\d/);
+ // And it does not show its global number once opened, either.
+ fireEvent.click(screen.getByText("Modules with no layer (1)"));
+ const stray = rowLabels().find((l) => l.includes("odd/bits")) ?? "";
expect(stray).not.toBe("");
expect(stray).not.toMatch(/^\d/);
});
@@ -587,7 +596,10 @@ describe("DocsTree", () => {
);
expect(warn).toHaveBeenCalled();
expect(warn.mock.calls.flat().join(" ")).toContain("layer");
- // The pages are still shown — a missing grouping never hides a page.
+ // The pages are still shown — a missing grouping never hides a page. An
+ // unstamped module now waits in the trailing group rather than posing as a
+ // layer on the top rung, so it takes one click to reach.
+ fireEvent.click(screen.getByText("Modules with no layer (1)"));
expect(screen.getByText("api/routes")).toBeInTheDocument();
warn.mockRestore();
});
@@ -631,6 +643,138 @@ describe("DocsTree", () => {
expect(warn.mock.calls.flat().join(" ")).toContain("layer:ghost");
// Off-spine layers sort last rather than disappearing.
expect(indexOfRow("Alpha API")).toBeLessThan(indexOfRow("Ghost"));
+ // Without this the spy outlives the case and every later test that reads
+ // console.warn sees this call too.
+ warn.mockRestore();
+ });
+
+ it("keeps an unstamped module off the top rung, in a trailing group of its own", () => {
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: SPINE_IDS }),
+ // Listed first and named so the alphabet would put it at the very
+ // top: an implementation that leaves it at depth 0 cannot pass.
+ stampedModule("module_page:aaa/config", "Module: aaa/config", {}, 1),
+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {
+ layer_id: "layer:runtime",
+ layer_name: "Zebra Runtime",
+ }, 2),
+ stampedModule("module_page:api/routes", "Module: api/routes", {
+ layer_id: "layer:api",
+ layer_name: "Alpha API",
+ }, 3),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ // Not a sibling of the layer rows, where it would be styled as one.
+ expect(screen.queryByText("aaa/config")).not.toBeInTheDocument();
+ // The trailing row says what it is, and does not read like a layer.
+ const group = screen.getByText("Modules with no layer (1)");
+ // After every layer row, and before the bottom folder.
+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("Modules with no layer"));
+ expect(indexOfRow("Alpha API")).toBeLessThan(indexOfRow("Modules with no layer"));
+ // Collapsed on load — only layer keys join the default-expanded set.
+ fireEvent.click(group);
+ expect(screen.getByText("aaa/config")).toBeInTheDocument();
+ });
+
+ it("moves only the unstamped module, leaving a stamped one under its layer", () => {
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: SPINE_IDS }),
+ stampedModule("module_page:aaa/config", "Module: aaa/config", {}, 1),
+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {
+ layer_id: "layer:runtime",
+ layer_name: "Zebra Runtime",
+ }, 2),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ // Both grouping rows start closed, so open them to see where their members
+ // landed.
+ fireEvent.click(screen.getByText("Zebra Runtime"));
+ fireEvent.click(screen.getByText("Modules with no layer (1)"));
+ // The stamped module reads under its layer; the unstamped one reads under
+ // the trailing group, which sits below every layer.
+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("runtime/engine"));
+ expect(indexOfRow("runtime/engine")).toBeLessThan(indexOfRow("Modules with no layer"));
+ expect(indexOfRow("Modules with no layer")).toBeLessThan(indexOfRow("aaa/config"));
+ });
+
+ it("leaves the onboarding chapters on the top rung, ahead of the layers", () => {
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: SPINE_IDS }),
+ ONBOARDING,
+ stampedModule("module_page:aaa/config", "Module: aaa/config", {}, 4),
+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {
+ layer_id: "layer:runtime",
+ layer_name: "Zebra Runtime",
+ }, 5),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ // Only the module was moved — the chapter is not swept into the group.
+ expect(screen.getByText("Modules with no layer (1)")).toBeInTheDocument();
+ expect(indexOfRow("Getting Started")).toBeLessThan(indexOfRow("Zebra Runtime"));
+ expect(indexOfRow("Getting Started")).toBeLessThan(indexOfRow("Modules with no layer"));
+ });
+
+ it("warns about an unstamped module by name, and not about the chapters", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: SPINE_IDS }),
+ ONBOARDING,
+ stampedModule("module_page:aaa/config", "Module: aaa/config", {}, 4),
+ stampedModule("module_page:runtime/engine", "Module: runtime/engine", {
+ layer_id: "layer:runtime",
+ layer_name: "Zebra Runtime",
+ }, 5),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ const said = warn.mock.calls.flat().join(" ");
+ expect(warn).toHaveBeenCalled();
+ expect(said).toContain("aaa/config");
+ // The chapter legitimately belongs on the top rung — complaining about it
+ // would make the warning noise on every healthy repo.
+ expect(said).not.toContain("getting_started");
+ warn.mockRestore();
+ });
+
+ it("changes nothing on a repo that declares no layer spine at all", () => {
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot(),
+ ONBOARDING,
+ stampedModule("module_page:aaa/config", "Module: aaa/config", {}, 4),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ // With no spine there is nothing for a module to be missing from: it keeps
+ // its place, no trailing group appears, and nobody complains.
+ expect(screen.queryByText(/Modules with no layer/)).not.toBeInTheDocument();
+ expect(screen.getByText("aaa/config")).toBeInTheDocument();
+ expect(indexOfRow("Getting Started")).toBeLessThan(indexOfRow("aaa/config"));
+ expect(warn).not.toHaveBeenCalled();
+ warn.mockRestore();
});
it("points a layer row at the knowledge graph, where its diagram lives", () => {
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index 3272da98b..ecf7fc8d3 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -35,6 +35,10 @@ const ONBOARDING_DIR_KEY = "@onboarding";
// 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}`;
+// And for the row holding the modules no layer claimed. Deliberately not a
+// layerDirKey: this row is not a layer, and the key is what keeps it out of
+// the default-expanded set (which only ever gets stamped layers' keys).
+const UNLAYERED_MODULES_KEY = "@group:unlayered-modules";
// 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";
@@ -374,11 +378,23 @@ function compareSiblings(a: DocPageSummary, b: DocPageSummary): number {
* 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.
+ *
+ * The same goes one module at a time: a single module the layers do not claim
+ * is invisible among dozens that are, so it is named here rather than left to
+ * be spotted in the tree.
*/
function reportLayerGrouping(
grouping: ReturnType<typeof groupPagesByLayer>,
spine: readonly string[],
+ unlayeredModules: readonly DocPageSummary[],
): void {
+ if (spine.length > 0 && unlayeredModules.length > 0) {
+ console.warn(
+ `[docs-tree] ${unlayeredModules.length} module pages carry no layer stamp, so they are ` +
+ "listed in a group of their own rather than inside a layer: " +
+ unlayeredModules.map((p) => p.target_path || p.title).join(", "),
+ );
+ }
if (spine.length > 0 && grouping.stamped === 0) {
console.warn(
`[docs-tree] the repository overview names ${spine.length} layers, but not one page ` +
@@ -485,11 +501,25 @@ function buildStoredTree(
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)));
+ // A module whose dominant layer came out empty gets no stamp, and left on
+ // the top rung it is drawn exactly like a layer row — one module wearing
+ // the weight of a whole architectural layer. Set those aside for a plainly
+ // named row below the layers. Only when a spine exists: with no layers to
+ // be missing from, there is nothing to say and nothing to move.
+ const unlayeredModules =
+ spine.length > 0
+ ? grouping.ungrouped.filter((p) => p.page_type === "module_page")
+ : [];
+ reportLayerGrouping(grouping, spine, unlayeredModules);
+ // The rest 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.
+ const unlayered = new Set(unlayeredModules.map((p) => p.id));
+ top.push(
+ ...grouping.ungrouped
+ .filter((child) => !unlayered.has(child.id))
+ .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
@@ -513,6 +543,16 @@ function buildStoredTree(
: {}),
});
}
+ // After the real layers, and named for what it is rather than as if it
+ // were one more of them.
+ if (unlayeredModules.length > 0) {
+ top.push({
+ name: `Modules with no layer (${unlayeredModules.length})`,
+ path: UNLAYERED_MODULES_KEY,
+ isDir: true,
+ children: unlayeredModules.map((child) => toNode(child, root)),
+ });
+ }
}
// Concept pages the walk never reached. Grouped by type rather than dropped: