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): a top-level row shows its number only if the run holds (#1186)

Swati Ahuja452f0d2bfda3
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsx
index 02ff6ce7a..30fb8f4a6 100644
--- a/packages/ui/__tests__/docs/docs-tree.test.tsx
+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx
@@ -183,6 +183,37 @@ describe("DocsTree", () => {
expect(rowLabels().some((l) => l.startsWith("3") && l.includes("Alpha API"))).toBe(true);
});
+ it("numbers only the top-level rows that continue the run from 1", () => {
+ // A module no layer claimed keeps the global number generation stamped on
+ // it, so it can land on the top rung as "41" beside onboarding's "1".
+ const unclaimed = makePage({
+ id: "module_page:odd/bits",
+ page_type: "module_page",
+ title: "Module: odd/bits",
+ target_path: "odd/bits",
+ parent_page_id: ROOT.id,
+ display_order: 41,
+ section_number: "41",
+ });
+ render(
+ <DocsTree
+ pages={[...SPINE, unclaimed]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ const labels = rowLabels();
+ // The unbroken run keeps its numbers, so a render-nothing implementation
+ // cannot pass this either.
+ expect(labels.some((l) => l.startsWith("1") && l.includes("Getting Started"))).toBe(true);
+ expect(labels.some((l) => l.startsWith("2") && l.includes("Zebra Runtime"))).toBe(true);
+ expect(labels.some((l) => l.startsWith("3") && l.includes("Alpha API"))).toBe(true);
+ // The row that breaks the run shows no number at all.
+ const stray = labels.find((l) => l.includes("odd/bits")) ?? "";
+ expect(stray).not.toBe("");
+ expect(stray).not.toMatch(/^\d/);
+ });
+
it("opens the layer spine by default and keeps files out of the outline", () => {
render(
<DocsTree pages={SPINE} selectedPageId={null} onSelectPage={() => {}} />,
@@ -474,6 +505,51 @@ describe("DocsTree", () => {
expect(screen.getByText("layer:api")).toBeInTheDocument();
});
+ it("leaves a layer grouping row unnumbered, and the stray beside it too", () => {
+ const onboarding = makePage({
+ id: "onboarding:onboarding/getting_started",
+ page_type: "onboarding",
+ title: "Getting Started",
+ target_path: "onboarding/getting_started",
+ metadata: { subkind: "getting_started" },
+ parent_page_id: "repo_overview:demo",
+ display_order: 1,
+ section_number: "1",
+ });
+ const unclaimed = {
+ ...stampedModule("module_page:odd/bits", "Module: odd/bits", {}, 41),
+ section_number: "41",
+ };
+ render(
+ <DocsTree
+ pages={[
+ layeredRoot({ layer_order_ids: ["layer:api"] }),
+ onboarding,
+ unclaimed,
+ stampedModule(
+ "module_page:api/routes",
+ "Module: api/routes",
+ { layer_id: "layer:api", layer_name: "Alpha API" },
+ 2,
+ ),
+ ]}
+ selectedPageId={null}
+ onSelectPage={() => {}}
+ />,
+ );
+ const labels = rowLabels();
+ // The chapter that starts the run keeps its number.
+ expect(labels.some((l) => l.startsWith("1") && l.includes("Getting Started"))).toBe(true);
+ // A layer is a grouping row, not a page — it has no number to show.
+ 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")) ?? "";
+ expect(stray).not.toBe("");
+ expect(stray).not.toMatch(/^\d/);
+ });
+
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({
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index cb6a84b02..3272da98b 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -610,6 +610,38 @@ function filterTree(
return result;
}
+/**
+ * Keep a top-level row's stored number only while it still reads as a sequence.
+ *
+ * The stored numbers are assigned across the whole outline, but only some of
+ * the numbered pages reach the top rung. The orientation chapters land there
+ * carrying 1-8; a layer's grouping row is not a page and carries no number at
+ * all; and a module no layer claimed keeps its global number, so it arrives at
+ * the top rung stamped "41" and sits next to the "1". Rendered as stored, the
+ * column of numbers skips from 8 to 41 and tells a reader nothing.
+ *
+ * So a row keeps its number only when that number continues the run from 1;
+ * every other top-level row renders none. The visible numbering is then
+ * contiguous or absent, never a jump. Deeper rows are unaffected — they never
+ * render a number in the first place.
+ *
+ * The rule is about the run rather than about which kind of page a row is: if
+ * the outline is later numbered end to end, the numbers come back on their own.
+ */
+function keepContiguousSections(nodes: TreeNode[]): TreeNode[] {
+ let expected = 1;
+ return nodes.map((node) => {
+ if (node.section === String(expected)) {
+ expected += 1;
+ return node;
+ }
+ if (!node.section) return node;
+ const unnumbered: TreeNode = { ...node };
+ delete unnumbered.section;
+ return unnumbered;
+ });
+}
+
// ---------------------------------------------------------------------------
// Tree node component
// ---------------------------------------------------------------------------
@@ -924,8 +956,10 @@ export function DocsTree({
: buildTree(pages),
[pages, viewMode, knowledgeGraphHref],
);
+ // Numbering is decided on what actually renders, after filtering, so the
+ // visible run stays contiguous even when a filter hides a numbered row.
const filteredTree = useMemo(
- () => filterTree(tree, search, typeFilter, freshnessFilter),
+ () => keepContiguousSections(filterTree(tree, search, typeFilter, freshnessFilter)),
[tree, search, typeFilter, freshnessFilter],
);