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): 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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;