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): one breadcrumb, correct reader height, wrapping backlinks (#1156)
Swati Ahuja0d2194c7570b
diff --git a/packages/ui/__tests__/wiki/backlinks-panel.test.tsx b/packages/ui/__tests__/wiki/backlinks-panel.test.tsxnew file mode 100644index 000000000..bc2c01089--- /dev/null+++ b/packages/ui/__tests__/wiki/backlinks-panel.test.tsx@@ -0,0 +1,38 @@+import { describe, expect, it } from "vitest";+import { render, screen } from "@testing-library/react";+import { BacklinksPanel } from "../../src/wiki/backlinks-panel.js";+import type { Backlink } from "../../src/wiki/wiki-links-types.js";++const LONG_TITLE = "File: packages/server/src/repowise/server/routers/overview.py";++function backlink(over: Partial<Backlink> = {}): Backlink {+ return {+ source_page_id: "file_page:a.py",+ source_title: LONG_TITLE,+ source_page_type: "file_page",+ ...over,+ } as Backlink;+}++describe("BacklinksPanel titles", () => {+ it("wraps the title instead of clipping it to one line", () => {+ render(<BacklinksPanel backlinks={[backlink()]} repoId="r1" />);++ const title = screen.getByText(LONG_TITLE);+ // `truncate` is one-line ellipsis. In a ~260px rail it cuts the path at+ // exactly the part that identifies the page, matching the Related list's+ // rule that a title must stay readable.+ expect(title.className).not.toContain("truncate");+ });++ it("names the source page in the link tooltip, not just its kind", () => {+ render(<BacklinksPanel backlinks={[backlink()]} repoId="r1" />);++ expect(screen.getByRole("link")).toHaveAttribute("title", LONG_TITLE);+ });++ it("renders nothing when there are no backlinks", () => {+ const { container } = render(<BacklinksPanel backlinks={[]} repoId="r1" />);+ expect(container).toBeEmptyDOMElement();+ });+});diff --git a/packages/ui/src/wiki/backlinks-panel.tsx b/packages/ui/src/wiki/backlinks-panel.tsxindex 47741e3bd..963a05ffc 100644--- a/packages/ui/src/wiki/backlinks-panel.tsx+++ b/packages/ui/src/wiki/backlinks-panel.tsx@@ -66,13 +66,20 @@ export function BacklinksPanel({{visible.map((bl) => {const Icon = getPageTypeIcon(bl.source_page_type);const href = buildHref(repoId, bl.source_page_id);- const title = getPageTypeLabel(bl.source_page_type);+ // The page's own name, not its kind. The kind is already the icon+ // beside it, and a tooltip reading "File" over a list of files told+ // the reader nothing about which page they were about to open.+ const title = bl.source_title;const children = (<>- <Icon className="h-3 w-3 mt-0.5 shrink-0 text-[var(--color-text-tertiary)]" />- <span className="truncate" title={bl.source_title}>- {bl.source_title}- </span>+ <Icon+ aria-label={getPageTypeLabel(bl.source_page_type)}+ className="h-3 w-3 mt-0.5 shrink-0 text-[var(--color-text-tertiary)]"+ />+ {/* Wraps rather than truncates, like the Related list. In a+ ~260px rail one-line ellipsis cut page titles at the path+ segment that identifies them. */}+ <span className="min-w-0 break-words leading-snug">{bl.source_title}</span></>);return (diff --git a/packages/web/src/app/repos/[id]/docs/docs-reader-shell.test.ts b/packages/web/src/app/repos/[id]/docs/docs-reader-shell.test.tsnew file mode 100644index 000000000..76fe0ea71--- /dev/null+++ b/packages/web/src/app/repos/[id]/docs/docs-reader-shell.test.ts@@ -0,0 +1,21 @@+import { describe, expect, it } from "vitest";+import { DOCS_READER_SHELL_CLASS } from "./docs-reader-shell";++describe("DOCS_READER_SHELL_CLASS", () => {+ it("carries a definite height, which DocsExplorer's h-full resolves against", () => {+ expect(DOCS_READER_SHELL_CLASS).toContain("h-full");+ });++ it("does not ask for the viewport, which overflows past the banners", () => {+ expect(DOCS_READER_SHELL_CLASS).not.toContain("h-screen");+ });++ it("does not lean on flex-1, which is inert under a parent that is not a flex container", () => {+ expect(DOCS_READER_SHELL_CLASS).not.toContain("flex-1");+ });++ it("is a flex column, so the tree and the reader sit side by side inside it", () => {+ expect(DOCS_READER_SHELL_CLASS).toContain("flex");+ expect(DOCS_READER_SHELL_CLASS).toContain("flex-col");+ });+});diff --git a/packages/web/src/app/repos/[id]/docs/docs-reader-shell.ts b/packages/web/src/app/repos/[id]/docs/docs-reader-shell.tsnew file mode 100644index 000000000..1cd79cd59--- /dev/null+++ b/packages/web/src/app/repos/[id]/docs/docs-reader-shell.ts@@ -0,0 +1,23 @@+/**+ * The class list for the box the docs reader lives in.+ *+ * The reader has to be exactly as tall as the space `main` leaves after the+ * bands a repo stacks above the page — the reindex hint, the active-job banner,+ * the upgrade banner — and it has to scroll inside that box rather than grow it.+ * That needs a height with a number behind it, for two reasons:+ *+ * - `flex-1` here would do nothing. This box's parent is the wrapper+ * `PageTransition` renders, which is a flex item of `main` but is not itself a+ * flex container, so a `flex-1` child of it gets no share of anything and+ * falls back to the height of its own content.+ * - `DocsExplorer`'s own root asks for `h-full`, and a percentage height against+ * a parent whose height is `auto` resolves to `auto` as well. With no number+ * here, the tree and the reader below it collapse onto their content.+ *+ * `h-full` supplies the number. The wrapper's height is settled by the flex+ * layout of `main`, so 100% of it is the space actually left over, with the+ * banners already subtracted. `h-screen` was the previous answer and overflowed+ * by exactly the height of whichever banners were showing, pushing the reader's+ * bottom chrome below the fold.+ */+export const DOCS_READER_SHELL_CLASS = "flex h-full flex-col";diff --git a/packages/web/src/app/repos/[id]/docs/page.tsx b/packages/web/src/app/repos/[id]/docs/page.tsxindex 7b11af817..651e52c36 100644--- a/packages/web/src/app/repos/[id]/docs/page.tsx+++ b/packages/web/src/app/repos/[id]/docs/page.tsx@@ -2,6 +2,7 @@import { use } from "react";import { DocsExplorer } from "@/components/docs/docs-explorer";+import { DOCS_READER_SHELL_CLASS } from "./docs-reader-shell";// Thin shell — the DocsHeader, search palette, export menu, and per-page// controls all live in DocsExplorer, which owns the page selection and@@ -14,7 +15,9 @@ export default function DocsPage({const { id: repoId } = use(params);return (- <div className="flex flex-col h-screen">+ // Fill the height `main` actually leaves, not the whole viewport — see+ // docs-reader-shell.ts for why that has to be a definite height.+ <div className={DOCS_READER_SHELL_CLASS}><DocsExplorer repoId={repoId} /></div>);diff --git a/packages/web/src/components/layout/repo-breadcrumb-route.ts b/packages/web/src/components/layout/repo-breadcrumb-route.tsnew file mode 100644index 000000000..4b318fe73--- /dev/null+++ b/packages/web/src/components/layout/repo-breadcrumb-route.ts@@ -0,0 +1,18 @@+/** The docs reader. Every wiki page lives at this one URL, keyed by `?page=`. */+const DOCS_READER = /^\/repos\/[^/]+\/docs\/?$/;++/**+ * Whether the route breadcrumb should render on a given path.+ *+ * The docs reader draws its own breadcrumb from the wiki page tree. The route+ * cannot express that hierarchy — every page sits at the same `/docs` URL — so+ * the route trail there is always the same three crumbs, stacked directly above+ * the reader's. One of the two bars has to go, and the reader's is the one+ * carrying information.+ *+ * Scoped to the reader itself: `/docs/coverage` is an ordinary page with no+ * breadcrumb of its own, and keeps the route trail.+ */+export function showsRouteBreadcrumb(pathname: string): boolean {+ return !DOCS_READER.test(pathname);+}diff --git a/packages/web/src/components/layout/repo-breadcrumb.test.ts b/packages/web/src/components/layout/repo-breadcrumb.test.tsindex 52f56d47f..004c13a25 100644--- a/packages/web/src/components/layout/repo-breadcrumb.test.ts+++ b/packages/web/src/components/layout/repo-breadcrumb.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from "vitest";import { getRepoBreadcrumbSegmentLabel } from "./repo-breadcrumb-label";+import { showsRouteBreadcrumb } from "./repo-breadcrumb-route";describe("getRepoBreadcrumbSegmentLabel", () => {it("keeps configured route segment labels", () => {@@ -17,3 +18,25 @@ describe("getRepoBreadcrumbSegmentLabel", () => {expect(getRepoBreadcrumbSegmentLabel("%E0%A4%A")).toBe("%E0%A4%A");});});++describe("showsRouteBreadcrumb", () => {+ it("stands down on the docs reader, which draws its own trail", () => {+ expect(showsRouteBreadcrumb("/repos/abc/docs")).toBe(false);+ expect(showsRouteBreadcrumb("/repos/abc/docs/")).toBe(false);+ });++ it("still shows on ordinary pages under docs", () => {+ expect(showsRouteBreadcrumb("/repos/abc/docs/coverage")).toBe(true);+ });++ it("shows everywhere else", () => {+ expect(showsRouteBreadcrumb("/repos/abc")).toBe(true);+ expect(showsRouteBreadcrumb("/repos/abc/code-health")).toBe(true);+ expect(showsRouteBreadcrumb("/repos/abc/commits")).toBe(true);+ });++ it("is not fooled by a repo id that ends in the reader's segment", () => {+ expect(showsRouteBreadcrumb("/repos/my-docs/commits")).toBe(true);+ expect(showsRouteBreadcrumb("/repos/abc/docsearch")).toBe(true);+ });+});diff --git a/packages/web/src/components/layout/repo-breadcrumb.tsx b/packages/web/src/components/layout/repo-breadcrumb.tsxindex 673a418e7..b146182ae 100644--- a/packages/web/src/components/layout/repo-breadcrumb.tsx+++ b/packages/web/src/components/layout/repo-breadcrumb.tsx@@ -6,6 +6,7 @@ import { Breadcrumb } from "@repowise-dev/ui/shared/breadcrumb";import type { BreadcrumbSegment } from "@repowise-dev/ui/shared/breadcrumb";import { DocsModeBadge, type DocsMode } from "@repowise-dev/ui/docs/docs-mode-badge";import { getRepoBreadcrumbSegmentLabel } from "./repo-breadcrumb-label";+import { showsRouteBreadcrumb } from "./repo-breadcrumb-route";export function RepoBreadcrumb({repoName,@@ -17,7 +18,13 @@ export function RepoBreadcrumb({}) {const pathname = usePathname();const match = pathname.match(/^\/repos\/([^/]+)(.*)/);- if (!match) return null;+ if (!match) {+ // The layout that renders this only wraps /repos/{id}. Reaching here means+ // the route moved out from under it and every page below lost its trail —+ // say so rather than rendering nothing.+ console.warn(`[breadcrumb] no repo in pathname, rendering no trail: ${pathname}`);+ return null;+ }const repoId = match[1];const rest = match[2]?.replace(/^\//, "").split("/").filter(Boolean) ?? [];@@ -36,7 +43,7 @@ export function RepoBreadcrumb({});}- const showCrumbs = segments.length > 2;+ const showCrumbs = segments.length > 2 && showsRouteBreadcrumb(pathname);const showBadge = docsMode !== "none";// Nothing to show at the repo root with no docs — stay out of the way.if (!showCrumbs && !showBadge) return null;