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
feat(ui): concept-first docs navigation with one auto-documented folder (#1038)
Raghav Chamadiyaffe0532aa0f0
diff --git a/packages/ui/__tests__/docs/docs-tree.test.tsx b/packages/ui/__tests__/docs/docs-tree.test.tsxindex ccb1b2fc2..e1fdcb8f0 100644--- a/packages/ui/__tests__/docs/docs-tree.test.tsx+++ b/packages/ui/__tests__/docs/docs-tree.test.tsx@@ -107,7 +107,7 @@ function indexOfRow(fragment: string): number {}describe("DocsTree", () => {- it("renders page nodes from the supplied pages array", () => {+ it("renders deterministic pages inside the collapsed Auto-documented folder", () => {render(<DocsTreepages={[@@ -118,6 +118,12 @@ describe("DocsTree", () => {onSelectPage={() => {}}/>,);+ const bucket = screen.getByText("Auto-documented files (2)");+ expect(bucket).toBeInTheDocument();+ // Collapsed by default: the files are a deliberate drill-in, not on load.+ expect(screen.queryByText("foo.ts")).not.toBeInTheDocument();+ fireEvent.click(bucket);+ fireEvent.click(screen.getByText("src"));expect(screen.getByText("foo.ts")).toBeInTheDocument();expect(screen.getByText("bar.ts")).toBeInTheDocument();});@@ -132,6 +138,7 @@ describe("DocsTree", () => {onSelectPage={onSelectPage}/>,);+ fireEvent.click(screen.getByText("Auto-documented files (1)"));fireEvent.click(screen.getByText("x.ts"));expect(onSelectPage).toHaveBeenCalledWith(target);});@@ -176,17 +183,16 @@ describe("DocsTree", () => {expect(rowLabels().some((l) => l.startsWith("3") && l.includes("Alpha API"))).toBe(true);});- it("nests modules under their stored layer and files under their module", () => {+ it("opens the layer spine by default and keeps files out of the outline", () => {render(<DocsTree pages={SPINE} selectedPageId={null} onSelectPage={() => {}} />,);- // The module is not visible until its layer is expanded.- expect(screen.queryByText("runtime/engine")).not.toBeInTheDocument();- fireEvent.click(screen.getByText("Zebra Runtime"));- fireEvent.click(screen.getByText("runtime/engine"));- // Named relative to its module, so files with the same basename in- // different resolver directories stay distinguishable.- expect(screen.getByText("resolvers/dotnet/index.py")).toBeInTheDocument();+ // Layer is open on load, so its concept title reads as a clean leaf in the+ // outline — no file rows beside it.+ expect(screen.getByText("runtime/engine")).toBeInTheDocument();+ expect(screen.queryByText("resolvers/dotnet/index.py")).not.toBeInTheDocument();+ // The file lives in the single Auto-documented folder at the bottom.+ expect(screen.getByText("Auto-documented files (1)")).toBeInTheDocument();});it("hides tombstoned pages, which the tree deliberately leaves unplaced", () => {@@ -208,7 +214,7 @@ describe("DocsTree", () => {expect(screen.queryByText("deleted.py")).not.toBeInTheDocument();});- it("keeps pages the stored tree does not reach, grouped by type", () => {+ it("keeps unreached concept pages grouped by type, files go to the bottom folder", () => {// A store whose tree has not been rebuilt: every parent is null. Nothing// may disappear just because it has no recorded place.render(@@ -226,24 +232,37 @@ describe("DocsTree", () => {onSelectPage={() => {}}/>,);+ // The unplaced concept page is grouped by type so it never vanishes.expect(screen.getByText("Module (1)")).toBeInTheDocument();- expect(screen.getByText("File (1)")).toBeInTheDocument();- expect(screen.getByText("a.ts")).toBeInTheDocument();- expect(screen.getByText("src")).toBeInTheDocument();+ // The file page is not a stray group; it lives in the one bottom folder.+ expect(screen.getByText("Auto-documented files (1)")).toBeInTheDocument();+ expect(screen.queryByText("File (1)")).not.toBeInTheDocument();});- it("survives a parent cycle instead of dropping the pages in it", () => {- const a = makePage({ id: "a", target_path: "a.ts", title: "a.ts", parent_page_id: "b" });- const b = makePage({ id: "b", target_path: "b.ts", title: "b.ts", parent_page_id: "a" });+ it("survives a concept parent cycle instead of dropping the pages in it", () => {+ const a = makePage({+ id: "a",+ page_type: "module_page",+ target_path: "a",+ title: "Module: a",+ parent_page_id: "b",+ });+ const b = makePage({+ id: "b",+ page_type: "module_page",+ target_path: "b",+ title: "Module: b",+ parent_page_id: "a",+ });render(<DocsTree pages={[...SPINE, a, b]} selectedPageId={null} onSelectPage={() => {}} />,);- expect(screen.getByText("File (2)")).toBeInTheDocument();+ expect(screen.getByText("Module (2)")).toBeInTheDocument();});- it("collapses a long run of leaves so it cannot bury the spine", () => {- // This repo's own overview carries 53 cycle pages and 55 loose file pages- // as direct children; listed inline they push the layers out of sight.+ it("routes structural pages to the bottom folder, never the concept outline", () => {+ // This repo's own overview carries dozens of cycle and loose file pages as+ // direct children; listed inline they push the layers out of sight.const cycles = Array.from({ length: 20 }, (_, i) =>makePage({id: `scc_page:${i}`,@@ -262,17 +281,18 @@ describe("DocsTree", () => {onSelectPage={() => {}}/>,);- expect(screen.getByText("SCC (20)")).toBeInTheDocument();- // Collapsed, and still after the layers it used to bury.+ // Cycles are deterministic: they never appear in the outline, and they join+ // every other file page in the one bottom folder (20 cycles + 1 SPINE file).expect(screen.queryByText("scc-0")).not.toBeInTheDocument();- expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("SCC (20)"));- // The layers themselves are never bucketed — they have children, so they- // are the hierarchy rather than a list.+ expect(screen.getByText("Auto-documented files (21)")).toBeInTheDocument();+ // The bottom folder sits after the concept spine.+ expect(indexOfRow("Zebra Runtime")).toBeLessThan(indexOfRow("Auto-documented files"));+ // The layers themselves are the spine, always shown.expect(screen.getByText("Zebra Runtime")).toBeInTheDocument();expect(screen.getByText("Alpha API")).toBeInTheDocument();});- it("leaves a short run of leaves inline", () => {+ it("routes even a few structural pages to the bottom folder, collapsed", () => {const few = Array.from({ length: 3 }, (_, i) =>makePage({id: `infra_page:${i}`,@@ -286,13 +306,18 @@ describe("DocsTree", () => {render(<DocsTree pages={[...SPINE, ...few]} selectedPageId={null} onSelectPage={() => {}} />,);- expect(screen.queryByText(/^Infra \(/)).not.toBeInTheDocument();+ // 3 infra pages + 1 SPINE file, all in the single collapsed folder.+ expect(screen.getByText("Auto-documented files (4)")).toBeInTheDocument();+ expect(screen.queryByText("infra-0.yml")).not.toBeInTheDocument();+ // Drill in: bottom folder -> deploy directory -> file.+ fireEvent.click(screen.getByText("Auto-documented files (4)"));+ fireEvent.click(screen.getByText("deploy"));expect(screen.getByText("infra-0.yml")).toBeInTheDocument();});- it("places file pages under their module, never in a provenance bucket", () => {- // Every page renders from one place now: file pages sit under their module- // in the tree, with no separate "Auto-documented" group to partition into.+ it("lifts a concept's file pages to the bottom folder, leaving the concept a clean leaf", () => {+ // The concept stays a pure title in the outline; its files move wholesale+ // into the single bottom folder rather than sitting beside it.const file = (id: string, path: string) =>makePage({id,@@ -308,9 +333,10 @@ describe("DocsTree", () => {onSelectPage={() => {}}/>,);- expect(screen.queryByText(/Auto-documented/)).not.toBeInTheDocument();- fireEvent.click(screen.getByText("Zebra Runtime"));- fireEvent.click(screen.getByText("runtime/engine"));- expect(screen.getByText("a.py")).toBeInTheDocument();+ // Concept visible as a leaf in the outline; its files are not beside it.+ expect(screen.getByText("runtime/engine")).toBeInTheDocument();+ expect(screen.queryByText("a.py")).not.toBeInTheDocument();+ // Both files are in the single bottom folder.+ expect(screen.getByText("Auto-documented files (2)")).toBeInTheDocument();});});diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsxindex 25920b176..2fee0265c 100644--- a/packages/ui/src/docs/docs-reader.tsx+++ b/packages/ui/src/docs/docs-reader.tsx@@ -320,8 +320,9 @@ function DocsReaderBody({{page.title}</h1>- {/* One calm metadata line: type + module + layer + freshness +- version + model — every metadata fact stated once, here. */}+ {/* One calm metadata line: type + module + layer + freshness. The+ generation provenance (version, tokens, model) lives in the+ right rail so the page opens on its content, not its receipt. */}<div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 text-[10px] text-[var(--color-text-tertiary)] mb-6"><span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 uppercase tracking-wider">{getPageTypeLabel(page.page_type)}@@ -354,16 +355,6 @@ function DocsReaderBody({<Clock className="h-3 w-3" />{formatRelativeTime(page.updated_at)}</span>- <span>v{page.version}</span>- <span className="font-mono">- {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out- </span>- {page.model_name && (- <span className="flex items-center gap-1 font-mono">- <Cpu className="h-3 w-3" />- {page.model_name}- </span>- )}</div>{/* Low-confidence flag */}@@ -523,6 +514,28 @@ function DocsReaderBody({)}</div>)}+ {/* Generation provenance — moved off the title row so the page+ opens on its content. Model, cost and version answer "how was+ this made", which is a rail question, not a headline. */}+ <div>+ <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">+ Generated+ </p>+ <div className="space-y-1 text-[10px] text-[var(--color-text-tertiary)]">+ {page.model_name && (+ <div className="flex items-center gap-1.5 font-mono">+ <Cpu className="h-3 w-3 shrink-0" />+ <span className="truncate" title={page.model_name}>+ {page.model_name}+ </span>+ </div>+ )}+ <div className="font-mono">+ {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out+ </div>+ <div>v{page.version}</div>+ </div>+ </div>{relatedLinks.length > 0 && (<div><p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsxindex 5c65dddb0..f7aee7c48 100644--- a/packages/ui/src/docs/docs-tree.tsx+++ b/packages/ui/src/docs/docs-tree.tsx@@ -194,9 +194,15 @@ function buildTree(pages: DocPage[]): TreeNode[] {dirNode.page = page;if (RAW_GRAPH_ID.test(dirNode.name)) dirNode.name = displayLabel(page);} else {- // File pages go into their parent directory+ // File pages go into their parent directory, named by their basename.+ // Cycle pages have a synthetic path ("scc-103") that reads as noise, so+ // they use their derived label ("Cycle: generation/page_generator")+ // instead, the same name the concept tree gives them.const parts = targetPath.split("/");- const fileName = parts[parts.length - 1] ?? targetPath;+ const fileName =+ page.page_type === "scc_page"+ ? displayLabel(page)+ : (parts[parts.length - 1] ?? targetPath);const fileNode: TreeNode = {name: fileName,@@ -285,51 +291,25 @@ const typeGroupKey = (parentId: string, pageType: string) =>// whole tree, so leaving them shut would show almost nothing.const STRAY_GROUP_KEYS = ALL_PAGE_TYPES.map((t) => typeGroupKey("", t));-// How many same-type leaves may sit side by side before they are collapsed-// into one row. This repo's overview has 53 cycle pages and 55 loose file-// pages directly beneath it; listed inline they bury the eleven layers that-// are the actual spine. A run of leaves is a list, not a hierarchy, so it gets-// one row. Anything with children of its own is never bucketed — that IS the-// hierarchy, however many of them there are.-const LEAF_RUN_LIMIT = 8;--function groupLeafRuns(parentId: string, nodes: TreeNode[]): TreeNode[] {- const runs = new Map<string, TreeNode[]>();- for (const node of nodes) {- if (node.children.length > 0 || !node.page) continue;- const bucket = runs.get(node.page.page_type);- if (bucket) bucket.push(node);- else runs.set(node.page.page_type, [node]);- }- const bucketed = new Set<string>();- for (const [type, run] of runs) {- if (run.length > LEAF_RUN_LIMIT) for (const n of run) bucketed.add(n.path);- else runs.delete(type);- }- if (bucketed.size === 0) return nodes;-- const out: TreeNode[] = [];- const emitted = new Set<string>();- for (const node of nodes) {- if (!bucketed.has(node.path)) {- out.push(node);- continue;- }- // The bucket takes the position of the first of its run, so the spine- // keeps its stored order rather than having every group shunted to the end.- const type = node.page!.page_type;- if (emitted.has(type)) continue;- emitted.add(type);- const run = runs.get(type)!;- out.push({- name: `${getPageTypeLabel(type)} (${run.length})`,- path: typeGroupKey(parentId, type),- isDir: true,- children: run,- });- }- return out;-}+// The page types that form the navigable concept spine — the model-written+// outline a human reads. Everything else is a deterministic, structural page+// (files, symbols, cycles, API contracts, infra): the per-file reference an+// agent looks things up in. The two are kept as distinct surfaces. Only the+// spine is walked into a hierarchy; every deterministic page goes into one+// collapsed folder at the very bottom, so the outline above it stays clean.+const SPINE_TYPES = new Set([+ "repo_overview",+ "architecture_diagram",+ "layer_page",+ "module_page",+ "onboarding",+]);++const isSpinePage = (page: DocPage) => SPINE_TYPES.has(page.page_type);++// The single bottom folder holding every deterministic page. Namespaced like+// the other synthetic keys so it can never collide with a real page id.+const AUTO_ROOT_KEY = "@group:auto-documented";function compareSiblings(a: DocPage, b: DocPage): number {return (@@ -343,11 +323,17 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {// and its content, but the tree deliberately has no place for it, so it must// be excluded here rather than treated as an unplaced page.const visible = pages.filter((p) => p.freshness_status !== "tombstone");- const byId = new Map(visible.map((p) => [p.id, p]));+ // Two distinct surfaces. The spine is walked into the concept outline; every+ // deterministic page is set aside for the single bottom folder, so a file+ // page never appears in the outline itself.+ const spinePages = visible.filter(isSpinePage);+ const deterministicPages = visible.filter((p) => !isSpinePage(p));++ const byId = new Map(spinePages.map((p) => [p.id, p]));const childrenOf = new Map<string, DocPage[]>();const claimed = new Set<string>();- for (const page of visible) {+ for (const page of spinePages) {const parentId = page.parent_page_id;if (!parentId || parentId === page.id || !byId.has(parentId)) continue;const bucket = childrenOf.get(parentId);@@ -356,10 +342,10 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {claimed.add(page.id);}- // The root is the page nothing claims that other pages hang off. A store- // written before the tree existed has no such page — every parent is null —- // and falls through to the grouped tail below.- const rootCandidates = visible.filter((p) => !claimed.has(p.id) && childrenOf.has(p.id));+ // The root is the concept page nothing claims that other pages hang off. A+ // store written before the tree existed has no such page — every parent is+ // null — and falls through to the grouped tail below.+ const rootCandidates = spinePages.filter((p) => !claimed.has(p.id) && childrenOf.has(p.id));const root =rootCandidates.find((p) => p.page_type === "repo_overview") ?? rootCandidates[0] ?? null;@@ -368,13 +354,10 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {const reached = new Set<string>();function toNode(page: DocPage, parent: DocPage | undefined): TreeNode {reached.add(page.id);- const children = groupLeafRuns(- page.id,- (childrenOf.get(page.id) ?? [])- .filter((c) => !reached.has(c.id))- .sort(compareSiblings)- .map((c) => toNode(c, page)),- );+ const children = (childrenOf.get(page.id) ?? [])+ .filter((c) => !reached.has(c.id))+ .sort(compareSiblings)+ .map((c) => toNode(c, page));return {name: treeLabel(page, parent),path: page.id,@@ -396,22 +379,19 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {children: [],});top.push(- ...groupLeafRuns(- root.id,- (childrenOf.get(root.id) ?? [])- .slice()- .sort(compareSiblings)- .map((child) => toNode(child, root)),- ),+ ...(childrenOf.get(root.id) ?? [])+ .slice()+ .sort(compareSiblings)+ .map((child) => toNode(child, root)),);}- // Pages the walk never reached. Grouped by type rather than dropped: an- // unplaced page is still a page. On a store whose tree has not been built- // yet this grouping IS the tree, which is a fair rendering of a wiki that- // genuinely has no recorded hierarchy.+ // Concept pages the walk never reached. Grouped by type rather than dropped:+ // an unplaced page is still a page. On a store whose tree has not been built+ // yet this grouping IS the outline, a fair rendering of a wiki that genuinely+ // has no recorded hierarchy.const strayByType = new Map<string, DocPage[]>();- for (const page of visible) {+ for (const page of spinePages) {if (reached.has(page.id)) continue;const bucket = strayByType.get(page.page_type);if (bucket) bucket.push(page);@@ -437,6 +417,18 @@ function buildStoredTree(pages: DocPage[]): TreeNode[] {});}+ // 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),+ });+ }+return top;}@@ -672,9 +664,19 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc// 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).+ const hasSpineChild = new Set(+ pages+ .filter((p) => SPINE_TYPES.has(p.page_type) && p.parent_page_id)+ .map((p) => p.parent_page_id as string),+ );for (const page of pages) {- const parts = page.target_path.split("/");- if (parts.length > 1 && parts[0]) dirs.add(parts[0]);+ if (hasSpineChild.has(page.id) && SPINE_TYPES.has(page.page_type)) dirs.add(page.id);}if (typeof window !== "undefined") {try {@@ -721,10 +723,7 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc});};- // Statsconst totalPages = pages.length;- const freshCount = pages.filter((p) => p.freshness_status === "fresh").length;- const needAttention = totalPages - freshCount;const activeFilterCount =(typeFilter !== "all" ? 1 : 0) + (freshnessFilter !== "all" ? 1 : 0);@@ -732,27 +731,6 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc<div className={cn("flex flex-col h-full", className)}>{/* Search + filter bar */}<div className="p-3 space-y-2 border-b border-[var(--color-border-default)]">- {/* View mode: semantic spine vs. raw filesystem */}- <div className="flex items-center gap-1 rounded-md bg-[var(--color-bg-elevated)] p-0.5">- {([- { mode: "domain" as const, label: "By domain", Icon: Network },- { mode: "folder" as const, label: "By folder", Icon: FolderTree },- ]).map(({ mode, label, Icon }) => (- <button- key={mode}- onClick={() => setViewMode(mode)}- className={cn(- "flex flex-1 items-center justify-center gap-1.5 rounded px-2 py-1 text-xs font-medium transition-colors",- viewMode === mode- ? "bg-[var(--color-bg-surface)] text-[var(--color-text-primary)] shadow-sm"- : "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)]",- )}- >- <Icon className="h-3 w-3" />- {label}- </button>- ))}- </div><div className="flex items-center gap-2"><div className="flex-1 flex items-center gap-1.5 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2 py-1.5"><Search className="h-3.5 w-3.5 text-[var(--color-text-tertiary)] shrink-0" />@@ -764,6 +742,21 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: DocclassName="flex-1 bg-transparent text-xs text-[var(--color-text-primary)] placeholder:text-[var(--color-text-tertiary)] outline-none"/></div>+ {/* View switch — domain is the default reading spine; folder is the+ power-user escape hatch, so it rides as a single quiet toggle+ rather than a full-width band. */}+ <button+ onClick={() => setViewMode((m) => (m === "domain" ? "folder" : "domain"))}+ aria-label={viewMode === "domain" ? "Switch to folder view" : "Switch to domain view"}+ title={viewMode === "domain" ? "Folder view" : "Domain view"}+ className="rounded-md p-1.5 text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-elevated)] hover:text-[var(--color-text-secondary)]"+ >+ {viewMode === "domain" ? (+ <FolderTree className="h-3.5 w-3.5" />+ ) : (+ <Network className="h-3.5 w-3.5" />+ )}+ </button><buttononClick={() => setShowFilters((s) => !s)}aria-label="Toggle filters"@@ -834,28 +827,9 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc</div>)}- {/* Stats line — quiet when everything is fresh; dots get a legend the- moment any are shown. */}- <div className="text-[10px] text-[var(--color-text-tertiary)]">- {totalPages} pages- {needAttention === 0 ? (- <span> · all fresh</span>- ) : (- <span className="text-[var(--color-warning)]"> · {needAttention} need attention</span>- )}- {needAttention > 0 && (- <span className="ml-2 inline-flex items-center gap-2">- <span className="inline-flex items-center gap-1">- <span className="h-1.5 w-1.5 rounded-full bg-[var(--color-warning)]" />- stale- </span>- <span className="inline-flex items-center gap-1">- <span className="h-1.5 w-1.5 rounded-full bg-[var(--color-error)]" />- outdated- </span>- </span>- )}- </div>+ {/* Quiet page count. Staleness auditing lives in the Doc-freshness+ view and the Status filter, so the nav header stays calm. */}+ <div className="text-[10px] text-[var(--color-text-tertiary)]">{totalPages} pages</div></div>{/* Tree */}