Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.tsxindex 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.tsxindex 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],);