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(files): give the file page doors in and out (#1622)
Raghav Chamadiyace65dd97f405
diff --git a/packages/ui/COMPONENT_CONTRACTS.md b/packages/ui/COMPONENT_CONTRACTS.mdindex 8a20ae255..d7cecaf42 100644--- a/packages/ui/COMPONENT_CONTRACTS.md+++ b/packages/ui/COMPONENT_CONTRACTS.md@@ -930,6 +930,49 @@ Bands come from `bandForScore` (`@repowise-dev/types/health`), never fromsits one click from the treemap and the health map, which both paint thecanonical three.+**The doors, and who owns each end.** The page had thirty surfaces linking+into it and almost nothing linking out, and the docs surface — the one that+knows a page documents *this exact path* — linked to it zero times.++- `FilePageHeader` takes `wikiHref`. It used to live in the Doc tab, which+ made the only link to the wiki reachable only from the tab that already+ renders the wiki. Pass it **only when a page exists** — this route already+ knows, and the reader's missing-page reply is for someone who typed the id,+ not for a link the product offered. It reads "Read in Docs", naming the+ surface the nav names: "Documentation" is the tab forty pixels below it, and+ two controls with near enough one name, one staying and one leaving, is the+ two-verbs-one-subject problem relocated rather than fixed.+- `DocsReader` takes `buildFileHref`, and renders the door only for a+ `file_page`. `page.target_path` is the repo-relative path the file route+ takes, so nothing parses an id. Optional, so a host with no file route+ (the VS Code webview) renders no door rather than a broken one.+- `buildFilePanels` forwards `LinkComponent` to Overview, History, Decisions+ and Dependencies. **This does not move the hydration boundary**: a+ `next/link` element *rendered from* a server component is still server+ markup. An `onClick` would not be — that is what would drag a body back+ into the client bundle.+- Because those cross-file links are soft navigations now, the shell's+ `key` on the file path is load-bearing rather than defensive. Without it a+ file → file click keeps React's tab state at the same tree position and+ strands the active tab out of sync with the URL.++Route builders are `fileEntityPath`, `symbolEntityPath`, `filePageId` and+`docsPagePath` from `shared/entity`. `filePageId` exists because the+`"file_page:<path>"` id has to agree with a backend primary key and was+spelled out at five call sites; `pageHref` derives its parse prefix from the+builder so the two cannot drift. The docs surface reads `?page=`, never+`?file=` — three surfaces shipped a `?file=` link that nothing read, which+meant they silently opened the repo overview and looked like they had worked.++Repointing them at `?page=` puts real traffic on ids that resolve to nothing,+because page selection is budgeted and most files have no page. So+`DocsReader` takes `missingPageId` and answers by naming the page that is+missing, instead of the "Select a page, choose one from the tree" prompt meant+for a reader who asked for nothing. `docs-explorer` sets it only once the+fetch has settled, or the line flashes over a request about to succeed. It+deliberately does **not** fall back to the overview: a reader who asked about+one file must not silently land in another file's prose.+### `dashboard/attention-panel` — `AttentionPanel`Categorised list of items needing developer attention. Re-exports thediff --git a/packages/ui/__tests__/docs/docs-reader-file-door.test.tsx b/packages/ui/__tests__/docs/docs-reader-file-door.test.tsxnew file mode 100644index 000000000..5cc459edd--- /dev/null+++ b/packages/ui/__tests__/docs/docs-reader-file-door.test.tsx@@ -0,0 +1,143 @@+import { describe, it, expect, beforeAll } from "vitest";+import { render, screen } from "@testing-library/react";+import { DocsReader } from "../../src/docs/docs-reader.js";+import type { DocPage } from "@repowise-dev/types/docs";++/**+ * The way out of a file's documentation and into the file.+ *+ * The docs surface knows exactly which file a page is about — `target_path` on+ * a `file_page` is the repo-relative path the file route takes, and it is the+ * same pair the file endpoint matches on — and yet every href it rendered was a+ * `?page=` wiki link. A reader who finished a file's page and wanted its+ * health, history or dependents had to go back to the tree and start again+ * from the Files index.+ *+ * The door is conditional on three things at once, and each of them is a way+ * to render a link that goes somewhere wrong: the page must be a `file_page`+ * (a module page's `target_path` is a directory), it must carry a path, and+ * the host must have a file route to send it to. A host without one — the VS+ * Code webview — renders no door rather than a broken one.+ */++const DOOR = /Open file page/i;++beforeAll(() => {+ Element.prototype.scrollTo = () => {};+});++function makePage(overrides: Partial<DocPage> = {}): DocPage {+ return {+ id: "file_page:packages/ui/src/files/file-page.tsx",+ repository_id: "r1",+ page_type: "file_page",+ title: "file-page.tsx",+ content: "The shell for the file entity page.",+ target_path: "packages/ui/src/files/file-page.tsx",+ source_hash: "h",+ model_name: "m",+ provider_name: "anthropic",+ input_tokens: 0,+ output_tokens: 0,+ cached_tokens: 0,+ generation_level: 3,+ version: 1,+ confidence: 1,+ freshness_status: "fresh",+ metadata: {},+ created_at: "2026-08-01T00:00:00Z",+ updated_at: "2026-08-01T00:00:00Z",+ ...overrides,+ } as DocPage;+}++function renderReader(+ page: DocPage,+ buildFileHref?: (filePath: string) => string,+) {+ return render(+ <DocsReader+ page={page}+ repoId="r1"+ persona="contributor"+ sidebarOpen={false}+ buildPageHref={(id) => `?page=${id}`}+ buildFileHref={buildFileHref}+ LinkComponent={({ href, children, ...rest }) => (+ <a href={href} {...rest}>+ {children}+ </a>+ )}+ />,+ );+}++describe("DocsReader file-page door", () => {+ it("links a file page at the path the file route takes", () => {+ renderReader(makePage(), (p) => `/repos/r1/files/${p}`);+ const link = screen.getByRole("link", { name: DOOR });+ expect(link.getAttribute("href")).toBe(+ "/repos/r1/files/packages/ui/src/files/file-page.tsx",+ );+ });++ it("renders no door on a module page", () => {+ // `target_path` there is a directory, so the file route would 404 on it.+ renderReader(+ makePage({+ page_type: "module_page",+ target_path: "packages/ui/src/files",+ }),+ (p) => `/repos/r1/files/${p}`,+ );+ expect(screen.queryByRole("link", { name: DOOR })).toBeNull();+ });++ it("renders no door for a host with no file route", () => {+ renderReader(makePage());+ expect(screen.queryByRole("link", { name: DOOR })).toBeNull();+ });+});++describe("DocsReader missing page", () => {+ /**+ * Links into a specific `?page=` arrive from all over the app — the hotspot+ * and symbol row actions, the file card, the command palette, bookmarks —+ * and page selection is budgeted, so most files have no page. The reader+ * used to answer all of those with "Select a page. Choose a file or module+ * from the tree", which is the prompt for someone who asked for nothing, and+ * reads as the link having done nothing at all.+ */+ it("names the page that is missing", () => {+ render(+ <DocsReader+ page={null}+ repoId="r1"+ persona="contributor"+ sidebarOpen={false}+ buildPageHref={(id) => `?page=${id}`}+ missingPageId="file_page:packages/core/src/resolvers/dotnet.py"+ LinkComponent={({ href, children }) => <a href={href}>{children}</a>}+ />,+ );+ // The path, not the id: a `file_page:` prefix on screen is machinery.+ expect(+ screen.getByText("packages/core/src/resolvers/dotnet.py"),+ ).toBeTruthy();+ expect(screen.queryByText("Select a page")).toBeNull();+ });++ it("falls back to the pick-something prompt when nothing was asked for", () => {+ render(+ <DocsReader+ page={null}+ repoId="r1"+ persona="contributor"+ sidebarOpen={false}+ buildPageHref={(id) => `?page=${id}`}+ LinkComponent={({ href, children }) => <a href={href}>{children}</a>}+ />,+ );+ expect(screen.getByText("Select a page")).toBeTruthy();+ });+});diff --git a/packages/ui/__tests__/files/file-page-header.test.tsx b/packages/ui/__tests__/files/file-page-header.test.tsxindex 2a2d71a38..687f82ffe 100644--- a/packages/ui/__tests__/files/file-page-header.test.tsx+++ b/packages/ui/__tests__/files/file-page-header.test.tsx@@ -103,6 +103,41 @@ describe("FilePageHeader marks", () => {});});+describe("FilePageHeader documentation door", () => {+ // This link used to live inside the Doc tab, which made the file page's one+ // way back to the wiki reachable only from the tab that already renders the+ // wiki. In the header it is on screen from Health, Dependencies and the rest.+ it("offers the documentation page when there is one", () => {+ render(+ <FilePageHeader+ data={makeData()}+ linkPrefix="/repos/r1"+ wikiHref="/repos/r1/docs?page=file_page%3Aa.ts"+ />,+ );+ const link = screen.getByRole("link", { name: /Read in Docs/i });+ expect(link.getAttribute("href")).toBe("/repos/r1/docs?page=file_page%3Aa.ts");+ });++ it("names the surface, not the tab", () => {+ // "Documentation" is the tab, forty pixels below this and staying on the+ // page. A door out wearing near enough the same name is two controls for+ // one subject; "Docs" is what the nav calls the place it goes.+ render(+ <FilePageHeader data={makeData()} linkPrefix="/repos/r1" wikiHref="/x" />,+ );+ expect(screen.queryByRole("link", { name: /Documentation/i })).toBeNull();+ });++ it("renders no door when the file has no page", () => {+ // Rule 21. The docs reader replies to a `?page=` it cannot find by naming+ // the missing page, which is a fine answer to a reader who typed it and a+ // poor one to a link this header offered — and here we already know.+ render(<FilePageHeader data={makeData()} linkPrefix="/repos/r1" />);+ expect(screen.queryByRole("link", { name: /Read in Docs/i })).toBeNull();+ });+});+describe("fileTabsFor", () => {it("badges only what there is something to say about", () => {const tabs = fileTabsFor(makeData());diff --git a/packages/ui/package.json b/packages/ui/package.jsonindex 7f144acdd..1931777eb 100644--- a/packages/ui/package.json+++ b/packages/ui/package.json@@ -101,7 +101,6 @@"./shared/virtualized-table": "./src/shared/virtualized-table/index.ts","./shared/context-drawer": "./src/shared/context-drawer/index.ts","./shared/file-card": "./src/shared/file-card/index.ts",- "./shared/related": "./src/shared/related/index.ts","./shared/*": "./src/shared/*.tsx","./hooks": "./src/hooks/index.ts","./ui": "./src/ui/index.ts",diff --git a/packages/ui/src/chat/source-citations.tsx b/packages/ui/src/chat/source-citations.tsxindex 00244337e..2b99735f6 100644--- a/packages/ui/src/chat/source-citations.tsx+++ b/packages/ui/src/chat/source-citations.tsx@@ -3,6 +3,7 @@import { useMemo } from "react";import { ArrowUpRight } from "lucide-react";import { getPageTypeIcon } from "../lib/page-types";+import { filePageId } from "../shared/entity/routes";import type { ChatUIToolCall } from "@repowise-dev/types/chat";export interface SourceReference {@@ -64,7 +65,7 @@ export function extractSources(for (const [target, info] of Object.entries(targets)) {const docs = info.docs as Record<string, unknown> | undefined;if (!docs) continue;- const pageId = (docs.page_id as string) ?? `file_page:${target}`;+ const pageId = (docs.page_id as string) ?? filePageId(target);if (seen.has(pageId)) continue;seen.add(pageId);sources.push({@@ -106,7 +107,7 @@ export function extractSources(for (const d of rows) {const affectedFiles = (d.affected_files as string[]) ?? [];for (const filePath of affectedFiles.slice(0, 3)) {- const pageId = `file_page:${filePath}`;+ const pageId = filePageId(filePath);if (seen.has(pageId)) continue;seen.add(pageId);sources.push({diff --git a/packages/ui/src/coverage/freshness-table.tsx b/packages/ui/src/coverage/freshness-table.tsxindex 30adee15e..ada01a05f 100644--- a/packages/ui/src/coverage/freshness-table.tsx+++ b/packages/ui/src/coverage/freshness-table.tsx@@ -136,10 +136,18 @@ export function FreshnessTable({}renderRow={(page) => {const status = page.freshness_status as FreshnessStatus;+ // No `group` either: the underline was its only consumer. The+ // hover ground stays — on a five-column table it is how you keep+ // your place across the row, and unlike an underline on the path+ // it does not name a target to follow.return (- <tr className="group border-b border-[var(--color-table-divider)] hover:bg-[var(--color-bg-elevated)] transition-colors last:border-0">+ <tr className="border-b border-[var(--color-table-divider)] hover:bg-[var(--color-bg-elevated)] transition-colors last:border-0"><td className="px-4 py-2.5 font-mono text-xs text-[var(--color-text-primary)] min-w-[220px] max-w-[480px]">- <div className="truncate group-hover:underline underline-offset-2" title={page.target_path}>{page.target_path}</div>+ {/* No `group-hover:underline`: the row has no href and no+ onSelect, so the underline promised a navigation that+ could never happen. The row's one verb is Regenerate, in+ the action column. */}+ <div className="truncate" title={page.target_path}>{page.target_path}</div>{(() => { const TypeIcon = getPageTypeIcon(page.page_type); return (<div className="flex items-center gap-1 truncate text-[var(--color-text-tertiary)]" title={page.page_type}><TypeIcon className="h-3 w-3 shrink-0" />diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsxindex 9189d31b4..0a49a8c32 100644--- a/packages/ui/src/docs/docs-reader.tsx+++ b/packages/ui/src/docs/docs-reader.tsx@@ -55,6 +55,15 @@ function stripLeadingTitleHeading(content: string, title: string): string {return lines.join("\n");}+/** The readable half of a page id, for telling someone what they asked for.+ * Ids are `"{page_type}:{target_path}"`, and the path is the part that names+ * anything; a bare `file_page:` prefix on screen is machinery, not an answer. */+function describePageId(pageId: string): string {+ const colon = pageId.indexOf(":");+ const path = colon === -1 ? pageId : pageId.slice(colon + 1);+ return path.trim() || pageId;+}+/** Router-aware anchor — host injects Next.js Link / in-app interception. */export type ReaderLinkComponent = React.ElementType<{href: string;@@ -77,6 +86,24 @@ interface DocsReaderProps {sidebarOpen: boolean;/** ``?page=`` href builder — host owns the route shape. */buildPageHref: (pageId: string) => string;+ /**+ * Href for the source file's own page, given a repo-relative path.+ *+ * The reader is the one surface that knows a page documents a specific file —+ * `page.target_path` on a `file_page` is exactly the path the file route+ * takes — and until this it was the only surface with no link to it at all.+ * Optional so a host without a file route (the VS Code webview) simply+ * renders no door rather than a broken one.+ */+ buildFileHref?: ((filePath: string) => string) | undefined;+ /**+ * The page id that was asked for and could not be fetched.+ *+ * Set it only once the fetch has settled — while it is in flight the host+ * should be passing `isLoading` instead, or the reader flashes "no page for+ * this one" over a request that is about to succeed.+ */+ missingPageId?: string | undefined;/** Router-aware link for in-content + breadcrumb anchors. */LinkComponent: ReaderLinkComponent;/**@@ -104,6 +131,8 @@ export function DocsReader({persona,sidebarOpen,buildPageHref,+ buildFileHref,+ missingPageId,LinkComponent,intelligenceSlot,versionHistorySlot,@@ -127,6 +156,14 @@ export function DocsReader({if (isLoading) return <ReaderSkeleton />;if (!page) {+ // Two different states wearing one screen until now. A reader who opened+ // the surface with nothing selected needs "pick something". A reader who+ // asked for a specific page and did not get it needs to be told that, or+ // the generic prompt reads as the link having done nothing — and links+ // into a specific page arrive from all over the app (row actions, the+ // command palette, bookmarks), each of which can name a page the index+ // never wrote or has since dropped.+ const requested = missingPageId ? describePageId(missingPageId) : null;return (<div className="flex flex-col items-center justify-center h-full gap-4 text-center px-8"><div className="rounded-full bg-[var(--color-bg-elevated)] border border-[var(--color-border-default)] p-4">@@ -134,10 +171,22 @@ export function DocsReader({</div><div className="space-y-1"><h3 className="text-sm font-semibold text-[var(--color-text-primary)]">- Select a page+ {requested ? "No page for this one yet" : "Select a page"}</h3><p className="text-xs text-[var(--color-text-secondary)] max-w-sm">- Choose a file or module from the tree to view its AI-generated documentation.+ {requested ? (+ <>+ Repowise has not written a page for{" "}+ <span className="font-mono text-[var(--color-text-primary)] break-all">+ {requested}+ </span>+ . Page selection is budgeted, so a repository is documented at+ the files that carry its shape. Pick another from the tree, or+ re-run the index with a wider page budget.+ </>+ ) : (+ "Choose a file or module from the tree to read what Repowise wrote about it."+ )}</p></div></div>@@ -154,6 +203,7 @@ export function DocsReader({goToPageId={goToPageId}persona={persona}buildPageHref={buildPageHref}+ buildFileHref={buildFileHref}LinkComponent={LinkComponent}intelligenceSlot={intelligenceSlot}versionHistorySlot={versionHistorySlot}@@ -209,6 +259,7 @@ function DocsReaderBody({goToPageId,persona,buildPageHref,+ buildFileHref,LinkComponent,intelligenceSlot,versionHistorySlot,@@ -222,6 +273,7 @@ function DocsReaderBody({goToPageId: (pageId: string) => void;persona: ReaderPersona;buildPageHref: (pageId: string) => string;+ buildFileHref?: ((filePath: string) => string) | undefined;LinkComponent: ReaderLinkComponent;intelligenceSlot?: React.ReactNode;versionHistorySlot?: React.ReactNode;@@ -305,6 +357,14 @@ function DocsReaderBody({// layer_id, whose value is the stable "layer:<slug>" the layer page is keyed// by. Reconstructing an id from the name never matched once the enrichment// pass had renamed a layer.+ // The source file this page documents, when there is one. `target_path` on a+ // `file_page` is the repo-relative path the file route takes — the same pair+ // the file endpoint matches on — so no id parsing is involved.+ const sourceFileHref =+ page.page_type === "file_page" && page.target_path && buildFileHref+ ? buildFileHref(page.target_path)+ : undefined;+const layerName =typeof page.metadata?.layer_name === "string" ? page.metadata.layer_name : "";const layerId =@@ -449,6 +509,37 @@ function DocsReaderBody({{layerName}</span>))}++ {/* The door out to the code this page is about. The docs surface+ rendered no link to a file page anywhere, on any of its+ screens, so a reader who finished a file's documentation and+ wanted its health, history or dependents had to go back to+ the tree and start again from Files.++ It sits at the end of the provenance row rather than in the+ rail, because the rail is `2xl`-only and this is the one link+ on the page that has to survive a laptop.++ Two things it does not inherit from that row. It sets its own+ `text-xs`, because the row runs at 11px for metadata and this+ is the page's only action — an action smaller than every body+ size on the surface is not one. And it does not take+ `ml-auto`: this row wraps (a long model name beside a module+ pill and a layer pill does it at laptop width), and a flex+ item only right-aligns while it still shares a line, so+ `ml-auto` bought a tidy right edge on wide windows and a link+ stranded alone against the far margin on the widths that+ actually wrap. Inline, after the pills, it reads the same at+ every width. */}+ {sourceFileHref && (+ <LinkComponent+ href={sourceFileHref}+ className="shrink-0 text-xs font-medium text-[var(--color-accent-primary)] hover:underline"+ title={`Health, history and dependents for ${page.target_path}`}+ >+ Open file page <span aria-hidden>→</span>+ </LinkComponent>+ )}</div>{/* What this page was written from. The rail carried this asdiff --git a/packages/ui/src/files/file-doc-tab.tsx b/packages/ui/src/files/file-doc-tab.tsxindex 5d84cc016..0331b868c 100644--- a/packages/ui/src/files/file-doc-tab.tsx+++ b/packages/ui/src/files/file-doc-tab.tsx@@ -8,11 +8,9 @@ interface FileDocTabProps {wikiPage: FileWikiPageRef | null;/** Server-rendered wiki content (the host renders markdown its own way). */docSlot?: ReactNode | undefined;- /** Deep link into the docs reading surface. */- wikiHref?: string | undefined;}-export function FileDocTab({ wikiPage, docSlot, wikiHref }: FileDocTabProps) {+export function FileDocTab({ wikiPage, docSlot }: FileDocTabProps) {if (!wikiPage) {return (<EmptyState@@ -29,26 +27,21 @@ export function FileDocTab({ wikiPage, docSlot, wikiHref }: FileDocTabProps) {{/* The freshness marker lives in the header, where it sits beside thescore and is on screen from whichever tab you arrive on. Repeating ithere would be a badge on a row that already carries one. What is- local to this tab is when the page was written and where to read it- full-width. */}- <div className="flex flex-wrap items-baseline gap-x-4 gap-y-1">- {wikiPage.updated_at && (- <span- className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]"- title={new Date(wikiPage.updated_at).toLocaleString()}- >- Written {formatRelativeTime(wikiPage.updated_at)}- </span>- )}- {wikiHref && (- <a- href={wikiHref}- className="ml-auto text-sm font-medium text-[var(--color-accent-primary)] hover:underline"- >- Open in Documentation <span aria-hidden>→</span>- </a>- )}- </div>+ local to this tab is when the page was written.++ "Open in Documentation" used to sit here too, which made the one link+ out of this page reachable only from the tab that already renders the+ page. It is in the header now, so a reader on Health or Dependencies+ can see it. Leaving a second copy here would be two doors to one+ destination on one screen. */}+ {wikiPage.updated_at && (+ <p+ className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]"+ title={new Date(wikiPage.updated_at).toLocaleString()}+ >+ Written {formatRelativeTime(wikiPage.updated_at)}+ </p>+ )}{wikiPage.human_notes && (<div className="border-l-2 border-[var(--color-accent-primary)] pl-4">diff --git a/packages/ui/src/files/file-graph-tab.tsx b/packages/ui/src/files/file-graph-tab.tsxindex f6bda4c91..651c7fb3e 100644--- a/packages/ui/src/files/file-graph-tab.tsx+++ b/packages/ui/src/files/file-graph-tab.tsx@@ -1,3 +1,4 @@+import type { ElementType } from "react";import { Network } from "lucide-react";import { EmptyState } from "../shared/empty-state";import { truncatePath } from "../lib/format";@@ -13,17 +14,27 @@ interface FileGraphTabProps {fileHref: (path: string) => string;/** Build a symbol-page href for a neighbor symbol node. */symbolHref: (symbolId: string) => string;+ /**+ * Router link. Every href here leaves this page, and a neighbour link is the+ * one that goes file page → file page: a full document load on a surface+ * whose whole point is walking the graph. Defaults to `<a>` so the package+ * stays framework-neutral.+ */+ LinkComponent?: ElementType | undefined;}function NeighborList({neighbors,fileHref,symbolHref,+ LinkComponent = "a",}: {neighbors: FileGraphNeighbor[];fileHref: (path: string) => string;symbolHref: (symbolId: string) => string;+ LinkComponent?: ElementType | undefined;}) {+ const A = LinkComponent;if (neighbors.length === 0) {return <p className="text-sm text-[var(--color-text-tertiary)]">None in the indexed graph.</p>;}@@ -61,12 +72,12 @@ function NeighborList({{isExternalNode ? (<div className="flex items-center gap-3">{row}</div>) : (- <a+ <Ahref={href}className="-mx-2 flex items-center gap-3 rounded px-2 transition-colors hover:bg-[var(--color-bg-elevated)]">{row}- </a>+ </A>)}{n.imported_names.length > 0 && (<p@@ -109,7 +120,9 @@ export function FileGraphTab({linkPrefix,fileHref,symbolHref,+ LinkComponent = "a",}: FileGraphTabProps) {+ const A = LinkComponent;if (!graph) {return (<EmptyState@@ -142,15 +155,20 @@ export function FileGraphTab({</>}action={- <a+ <Ahref={`${linkPrefix}/architecture?view=graph&node=${encodeURIComponent(filePath)}`}className="text-sm font-medium text-[var(--color-accent-primary)] hover:underline">Show in the dependency graph <span aria-hidden>→</span>- </a>+ </A>}>- <NeighborList neighbors={graph.dependents} fileHref={fileHref} symbolHref={symbolHref} />+ <NeighborList+ neighbors={graph.dependents}+ fileHref={fileHref}+ symbolHref={symbolHref}+ LinkComponent={LinkComponent}+ /></FileSection><FileSection@@ -163,15 +181,20 @@ export function FileGraphTab({</>}action={- <a+ <Ahref={`${linkPrefix}/architecture?view=symbols&file=${encodeURIComponent(filePath)}`}className="text-sm font-medium text-[var(--color-accent-primary)] hover:underline">View symbols <span aria-hidden>→</span>- </a>+ </A>}>- <NeighborList neighbors={graph.dependencies} fileHref={fileHref} symbolHref={symbolHref} />+ <NeighborList+ neighbors={graph.dependencies}+ fileHref={fileHref}+ symbolHref={symbolHref}+ LinkComponent={LinkComponent}+ /></FileSection></div>);diff --git a/packages/ui/src/files/file-history-tab.tsx b/packages/ui/src/files/file-history-tab.tsxindex 98896e506..41967b89f 100644--- a/packages/ui/src/files/file-history-tab.tsx+++ b/packages/ui/src/files/file-history-tab.tsx@@ -1,3 +1,4 @@+import type { ElementType } from "react";import { GitBranch } from "lucide-react";import { EmptyState } from "../shared/empty-state";import { CommitCategorySparkline } from "../git/commit-category-sparkline";@@ -20,9 +21,17 @@ interface FileHistoryTabProps {linkPrefix: string;/** Build a file-page href for a co-change partner. */partnerHref: (path: string) => string;+ /** Router link; defaults to `<a>` so the package stays framework-neutral. */+ LinkComponent?: ElementType | undefined;}-export function FileHistoryTab({ git, linkPrefix, partnerHref }: FileHistoryTabProps) {+export function FileHistoryTab({+ git,+ linkPrefix,+ partnerHref,+ LinkComponent = "a",+}: FileHistoryTabProps) {+ const A = LinkComponent;if (!git) {return (<EmptyState@@ -118,7 +127,7 @@ export function FileHistoryTab({ git, linkPrefix, partnerHref }: FileHistoryTabP<ul className="divide-y divide-[var(--color-border-default)] border-y border-[var(--color-border-default)]">{git.significant_commits.slice(0, 8).map((c) => (<li key={c.sha}>- <a+ <Ahref={`${linkPrefix}/commits?commit=${c.sha}`}className="-mx-2 flex items-baseline gap-3 rounded px-2 py-2.5 transition-colors hover:bg-[var(--color-bg-elevated)]">@@ -131,7 +140,7 @@ export function FileHistoryTab({ git, linkPrefix, partnerHref }: FileHistoryTabP<span className="shrink-0 font-mono text-[10px] text-[var(--color-text-tertiary)]">{c.date ? formatRelativeTime(c.date) : ""}</span>- </a>+ </A></li>))}</ul>@@ -203,7 +212,7 @@ export function FileHistoryTab({ git, linkPrefix, partnerHref }: FileHistoryTabP<ul className="divide-y divide-[var(--color-border-default)] border-y border-[var(--color-border-default)]">{git.co_change_partners.slice(0, 8).map((p) => (<li key={p.file_path}>- <a+ <Ahref={partnerHref(p.file_path)}className="-mx-2 flex items-baseline justify-between gap-3 rounded px-2 py-2.5 transition-colors hover:bg-[var(--color-bg-elevated)]">@@ -216,7 +225,7 @@ export function FileHistoryTab({ git, linkPrefix, partnerHref }: FileHistoryTabP<span className="shrink-0 font-mono text-[11px] tabular-nums text-[var(--color-text-tertiary)]">{p.co_change_count}×</span>- </a>+ </A></li>))}</ul>diff --git a/packages/ui/src/files/file-overview-tab.tsx b/packages/ui/src/files/file-overview-tab.tsxindex 1e380e1b2..dbabaf8eb 100644--- a/packages/ui/src/files/file-overview-tab.tsx+++ b/packages/ui/src/files/file-overview-tab.tsx@@ -1,3 +1,4 @@+import type { ElementType } from "react";import { FileQuestion } from "lucide-react";import type { FileDetailResponse } from "@repowise-dev/types/files";import { isExternal, nodeKind } from "@repowise-dev/types";@@ -12,6 +13,8 @@ interface FileOverviewTabProps {symbolHref: (symbolId: string) => string;/** Build a file-page href. */fileHref: (path: string) => string;+ /** Router link; defaults to `<a>` so the package stays framework-neutral. */+ LinkComponent?: ElementType | undefined;}/**@@ -24,7 +27,13 @@ interface FileOverviewTabProps {* `StatRibbon`, which is on screen whichever tab is open; a four-tile grid* repeating them under the tab row was the same five numbers twice.*/-export function FileOverviewTab({ data, symbolHref, fileHref }: FileOverviewTabProps) {+export function FileOverviewTab({+ data,+ symbolHref,+ fileHref,+ LinkComponent = "a",+}: FileOverviewTabProps) {+ const A = LinkComponent;const deadLines = data.dead_code.reduce((s, f) => s + f.lines, 0);// Keyed on the row's own symbol_id, not a rebuilt `${path}::${name}`: some// extractors mint ids from the qualified name, and those would never match.@@ -110,7 +119,7 @@ export function FileOverviewTab({ data, symbolHref, fileHref }: FileOverviewTabP{keySymbols.map((s) => {const fixes = fixesIn(s.symbol_id);return (- <a+ <Akey={s.symbol_id}href={symbolHref(s.symbol_id)}className="inline-flex items-center gap-1.5 rounded border border-[var(--color-border-default)] px-2 py-1 font-mono text-xs text-[var(--color-text-secondary)] transition-colors hover:border-[var(--color-accent-primary)] hover:text-[var(--color-accent-primary)]"@@ -125,7 +134,7 @@ export function FileOverviewTab({ data, symbolHref, fileHref }: FileOverviewTabP{fixes} {fixes === 1 ? "fix" : "fixes"}</span>)}- </a>+ </A>);})}</div>@@ -152,12 +161,14 @@ export function FileOverviewTab({ data, symbolHref, fileHref }: FileOverviewTabPnodes={data.graph.dependents.slice(0, 5).map((n) => n.node_id)}fileHref={fileHref}symbolHref={symbolHref}+ LinkComponent={LinkComponent}/><NeighborColumnlabel="Depends on"nodes={data.graph.dependencies.slice(0, 5).map((n) => n.node_id)}fileHref={fileHref}symbolHref={symbolHref}+ LinkComponent={LinkComponent}/></div></FileSection>@@ -211,12 +222,15 @@ function NeighborColumn({nodes,fileHref,symbolHref,+ LinkComponent = "a",}: {label: string;nodes: string[];fileHref: (path: string) => string;symbolHref: (id: string) => string;+ LinkComponent?: ElementType | undefined;}) {+ const A = LinkComponent;return (<div className="min-w-0"><p className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">@@ -242,13 +256,13 @@ function NeighborColumn({}return (<li key={id} className="min-w-0">- <a+ <Ahref={symbol ? symbolHref(id) : fileHref(id)}className="block truncate font-mono text-xs text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)]"title={id}>{truncatePath(id, 40)}- </a>+ </A></li>);})}diff --git a/packages/ui/src/files/file-page-header.tsx b/packages/ui/src/files/file-page-header.tsxindex 76ae9ea73..6f3581cc9 100644--- a/packages/ui/src/files/file-page-header.tsx+++ b/packages/ui/src/files/file-page-header.tsx@@ -11,6 +11,23 @@ export interface FilePageHeaderProps {data: FileDetailResponse;/** Route prefix for the repo, e.g. `/repos/:id`. */linkPrefix: string;+ /**+ * Deep link into the docs reading surface for this file's page.+ *+ * It lives in the header rather than in the Doc tab, where it used to be the+ * only way to reach the wiki from here: a reader on Health or Dependencies+ * had no idea a documentation page existed, and the one link to it was+ * behind the tab that already shows the page. Omitted when the file has no+ * page: the docs reader tells a reader that the page they asked for was+ * never written, which is a fine answer to a question they asked and a poor+ * one to a link they were offered. Rule 21.+ *+ * Named for the surface the nav names ("Docs"), not for the tab. The tab is+ * "Documentation" and sits forty pixels below this; two controls with near+ * enough the same name, one staying on the page and one leaving it, is the+ * two-verbs-one-subject problem relocated rather than fixed.+ */+ wikiHref?: string | undefined;LinkComponent?: React.ElementType | undefined;}@@ -31,7 +48,12 @@ export interface FilePageHeaderProps {* health map all paint: a 6.9 read one way here and another 200px away on the* map that links to this page.*/-export function FilePageHeader({ data, linkPrefix, LinkComponent }: FilePageHeaderProps) {+export function FilePageHeader({+ data,+ linkPrefix,+ wikiHref,+ LinkComponent,+}: FilePageHeaderProps) {const A = LinkComponent ?? "a";const score = data.health.metric?.score;const dir = data.file_path.slice(0, data.file_path.lastIndexOf("/") + 1);@@ -40,9 +62,23 @@ export function FilePageHeader({ data, linkPrefix, LinkComponent }: FilePageHeadreturn (<header className="flex flex-col gap-6"><div>- <p className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">- File- </p>+ {/* Eyebrow left, the one door out right. The pairing is deliberate:+ both are page-level, neither is about the file's numbers, and+ putting the link here means it is on screen from whichever tab you+ arrive on rather than only from the one that duplicates it. */}+ <div className="flex items-baseline justify-between gap-4">+ <p className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ File+ </p>+ {wikiHref && (+ <A+ href={wikiHref}+ className="shrink-0 text-sm font-medium text-[var(--color-accent-primary)] hover:underline"+ >+ Read in Docs <span aria-hidden>→</span>+ </A>+ )}+ </div>{/* `break-all`, never an ellipsis: a path is the identity of this pageand rule 6 puts no truncation in the primary column. The directoryis set quieter than the leaf so a deep path still reads as onediff --git a/packages/ui/src/files/file-page-panels.tsx b/packages/ui/src/files/file-page-panels.tsxindex 71260fd67..5739c77fb 100644--- a/packages/ui/src/files/file-page-panels.tsx+++ b/packages/ui/src/files/file-page-panels.tsx@@ -20,14 +20,22 @@ export interface BuildFilePanelsOptions {docSlot?: ReactNode;/** Shiki HTML with per-line `data-covered` attributes (Coverage tab). */coverageCodeHtml?: string | undefined;- /** Deep link into the docs reading surface. */- wikiHref?: string | undefined;/*** The Health panel. It is the one tab body that is genuinely interactive, so* the host supplies it already wrapped in whatever client component owns the* triage callback — a function cannot cross a server boundary as a prop.*/healthPanel?: ReactNode;+ /**+ * Router link, forwarded to every tab body that renders one.+ *+ * The tab bodies are server components and stay server components: a+ * `next/link` element rendered *from* a server component is still server+ * markup, so this does not drag any of them back across the hydration+ * boundary the way an `onClick` would. Threading it here rather than letting+ * a body import a router is the same reason the Decisions tab already took+ * it — `packages/ui` must not know what framework mounts it.+ */LinkComponent?: ElementType | undefined;}@@ -53,22 +61,34 @@ export function buildFilePanels({symbolHref,docSlot,coverageCodeHtml,- wikiHref,healthPanel,LinkComponent,}: BuildFilePanelsOptions): Partial<Record<FilePageTab, ReactNode>> {+ const link = LinkComponent ? { LinkComponent } : {};return {- overview: <FileOverviewTab data={data} symbolHref={symbolHref} fileHref={fileHref} />,- doc: <FileDocTab wikiPage={data.wiki_page} docSlot={docSlot} wikiHref={wikiHref} />,+ overview: (+ <FileOverviewTab+ data={data}+ symbolHref={symbolHref}+ fileHref={fileHref}+ {...link}+ />+ ),+ doc: <FileDocTab wikiPage={data.wiki_page} docSlot={docSlot} />,health: healthPanel,history: (- <FileHistoryTab git={data.git} linkPrefix={linkPrefix} partnerHref={fileHref} />+ <FileHistoryTab+ git={data.git}+ linkPrefix={linkPrefix}+ partnerHref={fileHref}+ {...link}+ />),decisions: (<FileDecisionsTabdecisions={data.governing_decisions ?? []}linkPrefix={linkPrefix}- {...(LinkComponent ? { LinkComponent } : {})}+ {...link}/>),graph: (@@ -78,6 +98,7 @@ export function buildFilePanels({linkPrefix={linkPrefix}fileHref={fileHref}symbolHref={symbolHref}+ {...link}/>),coverage: (diff --git a/packages/ui/src/git/hotspot-table.tsx b/packages/ui/src/git/hotspot-table.tsxindex aaa9c6cce..f74565090 100644--- a/packages/ui/src/git/hotspot-table.tsx+++ b/packages/ui/src/git/hotspot-table.tsx@@ -15,6 +15,7 @@ import { summarizeFixHistory } from "../lib/fix-history";import { cn } from "../lib/cn";import { useVirtualRows } from "../shared/virtualized-table";import { clickableRowProps, CLICKABLE_ROW_CLS } from "../shared/responsive-table";+import { docsPagePath, filePageId } from "../shared/entity/routes";import type { Hotspot } from "@repowise-dev/types/git";/**@@ -473,7 +474,13 @@ export function HotspotTable({<RowActionsactions={[{ icon: GitBranch, label: "Graph", href: `${prefix}/architecture?view=graph&node=${encodeURIComponent(h.file_path)}` },- { icon: BookOpen, label: "Docs", href: `${prefix}/docs?file=${encodeURIComponent(h.file_path)}` },+ // `?file=` is read by nothing in the docs+ // surface, so this used to open the repo+ // overview while looking like it had worked.+ // `?page=` is the reader's parameter and takes a+ // wiki page id; a file with no page gets told so+ // by name.+ { icon: BookOpen, label: "Docs", href: docsPagePath(prefix, filePageId(h.file_path)) },{ icon: Radius, label: "Blast Radius", href: `${prefix}/code-health?tab=impact&file=${encodeURIComponent(h.file_path)}` },]}/>diff --git a/packages/ui/src/health/hidden-coupling-list.tsx b/packages/ui/src/health/hidden-coupling-list.tsxindex 4057b4028..a8f9b65ab 100644--- a/packages/ui/src/health/hidden-coupling-list.tsx+++ b/packages/ui/src/health/hidden-coupling-list.tsx@@ -18,8 +18,18 @@ export interface HiddenCouplingFinding {export interface HiddenCouplingListProps {findings: HiddenCouplingFinding[];limit?: number;+ /**+ * Open a path. This is the row's one verb, and it opens the file drawer,+ * which carries the link to the file's own page.+ *+ * There was an `hrefFor` beside it that no consumer ever passed, and that+ * `PairLink` could not have used if one had: it returned the button branch+ * whenever `onSelect` was set, and the only consumer sets it. A prop that+ * cannot fire is rule 21 in prop form, so it is gone rather than wired —+ * wiring it would have put a second verb on a row whose first one already+ * leads to the same file.+ */onSelect?: ((path: string) => void) | undefined;- hrefFor?: ((path: string) => string) | undefined;/** Start collapsed, showing only `collapsedCount` pairs behind a toggle. */collapsible?: boolean;/** Pairs shown while collapsed. */@@ -94,7 +104,6 @@ export function HiddenCouplingList({findings,limit = 15,onSelect,- hrefFor,collapsible = false,collapsedCount = 4,}: HiddenCouplingListProps) {@@ -151,11 +160,11 @@ export function HiddenCouplingList({</span></div><div className="grid grid-cols-1 gap-1 text-xs font-mono">- <PairLink path={row.a} onSelect={onSelect} hrefFor={hrefFor} />+ <PairLink path={row.a} onSelect={onSelect} /><span className="text-[var(--color-text-tertiary)] inline-flex items-center gap-1"><ArrowLeftRight className="h-3 w-3" aria-hidden="true" /></span>- <PairLink path={row.b} onSelect={onSelect} hrefFor={hrefFor} />+ <PairLink path={row.b} onSelect={onSelect} /></div></li>))}@@ -176,13 +185,10 @@ export function HiddenCouplingList({function PairLink({path,onSelect,- hrefFor,}: {path: string;onSelect?: ((path: string) => void) | undefined;- hrefFor?: ((path: string) => string) | undefined;}) {- const href = hrefFor?.(path);if (onSelect) {return (<button@@ -194,15 +200,7 @@ function PairLink({</button>);}- if (href) {- return (- <a- href={href}- className="text-[var(--color-accent-primary)] hover:underline truncate"- >- {path}- </a>- );- }+ // No handler, so no affordance: plain text rather than accent-coloured text+ // that does nothing when clicked.return <span className="text-[var(--color-text-primary)] truncate">{path}</span>;}diff --git a/packages/ui/src/shared/entity/index.ts b/packages/ui/src/shared/entity/index.tsindex f1b030155..693d17463 100644--- a/packages/ui/src/shared/entity/index.ts+++ b/packages/ui/src/shared/entity/index.ts@@ -11,6 +11,8 @@ export {encodeFilePath,fileEntityPath,symbolEntityPath,+ filePageId,+ docsPagePath,ENTITY_KIND_LABEL,} from "./routes";export type {diff --git a/packages/ui/src/shared/entity/routes.ts b/packages/ui/src/shared/entity/routes.tsindex cd9ba5ddc..ee24eec16 100644--- a/packages/ui/src/shared/entity/routes.ts+++ b/packages/ui/src/shared/entity/routes.ts@@ -15,6 +15,24 @@ export function symbolEntityPath(prefix: string, symbolId: string): string {return `${prefix}/symbols/${encodeURIComponent(symbolId)}`;}+/** The wiki page id a file's documentation is stored under.+ *+ * The literal was hardcoded in five places that all had to agree with the+ * backend's `"{page_type}:{target_path}"` primary key, and one of them+ * (`pageHref`) had to parse it back off again. */+export function filePageId(filePath: string): string {+ return `file_page:${filePath}`;+}++/** Canonical route to a wiki page inside the docs reading surface.+ *+ * `/docs?page=` and not `/wiki/<id>`: the docs route keeps the tree and the+ * rail around the page, and the standalone wiki route redirects into it+ * anyway. */+export function docsPagePath(prefix: string, pageId: string): string {+ return `${prefix}/docs?page=${encodeURIComponent(pageId)}`;+}+/*** Resolve the canonical href for an entity. Centralizing this here keeps every* link consistent and makes the route map auditable in one place.diff --git a/packages/ui/src/shared/file-card/file-card.tsx b/packages/ui/src/shared/file-card/file-card.tsxindex 660c85bff..c8631a4f2 100644--- a/packages/ui/src/shared/file-card/file-card.tsx+++ b/packages/ui/src/shared/file-card/file-card.tsx@@ -11,6 +11,7 @@ import {Flame,Users,ExternalLink,+ ArrowUpRight,} from "lucide-react";import { Badge } from "../../ui/badge";import { formatLOC } from "../../lib/format";@@ -240,6 +241,13 @@ export function FileCard({ data, links, hideHeader = false, className }: FileCar{links && Object.values(links).some(Boolean) && (<div className="flex flex-wrap gap-1.5 pt-2 border-t border-[var(--color-border-default)]">+ {/* First, and the only one that leads anywhere this card is a+ summary of. Everything after it is a different surface filtered+ to this path; this one is the file's own page. */}+ {/* Not `FileText`: that icon is already the card's own header mark,+ where it means "this card is about a file". Reusing it on a+ button forty pixels below would make it identify nothing. */}+ {links.file && <LinkButton href={links.file} icon={ArrowUpRight} label="File page" />}{links.graph && <LinkButton href={links.graph} icon={GitBranch} label="Graph" />}{links.docs && <LinkButton href={links.docs} icon={BookOpen} label="Docs" />}{links.symbols && <LinkButton href={links.symbols} icon={Code2} label="Symbols" />}diff --git a/packages/ui/src/shared/file-card/types.ts b/packages/ui/src/shared/file-card/types.tsindex d3b443e99..5da6a6faf 100644--- a/packages/ui/src/shared/file-card/types.ts+++ b/packages/ui/src/shared/file-card/types.ts@@ -98,6 +98,8 @@ export function hotspotToFileCard(h: HotspotLike): FileCardData {}export interface FileCardLinks {+ /** The file's own page — the card is a preview of it, so it leads the row. */+ file?: string;graph?: string;docs?: string;blastRadius?: string;diff --git a/packages/ui/src/shared/related/index.ts b/packages/ui/src/shared/related/index.tsdeleted file mode 100644index 1670db338..000000000--- a/packages/ui/src/shared/related/index.ts+++ /dev/null@@ -1,2 +0,0 @@-export { RelatedAcrossRepowise } from "./related-across-repowise";-export type { RelatedAcrossRepowiseProps, RelatedSection } from "./related-across-repowise";diff --git a/packages/ui/src/shared/related/related-across-repowise.tsx b/packages/ui/src/shared/related/related-across-repowise.tsxdeleted file mode 100644index 2efd088f7..000000000--- a/packages/ui/src/shared/related/related-across-repowise.tsx+++ /dev/null@@ -1,87 +0,0 @@-"use client";--import { useState } from "react";-import { ChevronDown, ChevronRight, Compass } from "lucide-react";--export interface RelatedSection {- id: string;- label: string;- /** Optional count shown as a chip in the header. */- count?: number;- /** Render the body. Lazy so collapsed sections don't pay render cost. */- render: () => React.ReactNode;-}--export interface RelatedAcrossRepowiseProps {- sections: RelatedSection[];- /** Defaults to "Related across Repowise". */- title?: string;- /** Sections to start expanded. Defaults to none. */- defaultExpanded?: string[];-}--/**- * Universal footer attached to every entity page (file, symbol, decision,- * wiki). Renders only sections that the host actually populates — sections- * whose `render()` returns null are filtered out before rendering.- */-export function RelatedAcrossRepowise({- sections,- title = "Related across Repowise",- defaultExpanded = [],-}: RelatedAcrossRepowiseProps) {- const [expanded, setExpanded] = useState<Set<string>>(new Set(defaultExpanded));-- if (sections.length === 0) return null;-- const toggle = (id: string) =>- setExpanded((prev) => {- const next = new Set(prev);- if (next.has(id)) next.delete(id);- else next.add(id);- return next;- });-- return (- <section className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-surface)]">- <header className="flex items-center gap-2 px-4 py-3 border-b border-[var(--color-border-default)]">- <Compass className="h-4 w-4 text-[var(--color-text-tertiary)]" />- <h2 className="text-xs font-medium uppercase tracking-wider text-[var(--color-text-tertiary)]">- {title}- </h2>- </header>- <ul className="divide-y divide-[var(--color-border-default)]">- {sections.map((s) => {- const isOpen = expanded.has(s.id);- return (- <li key={s.id}>- <button- type="button"- onClick={() => toggle(s.id)}- aria-expanded={isOpen}- className="w-full flex items-center gap-2 px-4 py-2.5 text-left hover:bg-[var(--color-bg-elevated)] transition-colors"- >- {isOpen ? (- <ChevronDown className="h-3.5 w-3.5 text-[var(--color-text-tertiary)] shrink-0" />- ) : (- <ChevronRight className="h-3.5 w-3.5 text-[var(--color-text-tertiary)] shrink-0" />- )}- <span className="text-sm text-[var(--color-text-primary)] flex-1">{s.label}</span>- {s.count !== undefined && s.count > 0 && (- <span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 text-[10px] tabular-nums text-[var(--color-text-secondary)]">- {s.count}- </span>- )}- </button>- {isOpen && (- <div className="px-4 pb-3 pt-1 text-sm text-[var(--color-text-secondary)]">- {s.render()}- </div>- )}- </li>- );- })}- </ul>- </section>- );-}diff --git a/packages/ui/src/symbols/symbol-table.tsx b/packages/ui/src/symbols/symbol-table.tsxindex a8e48749c..b75644b05 100644--- a/packages/ui/src/symbols/symbol-table.tsx+++ b/packages/ui/src/symbols/symbol-table.tsx@@ -20,6 +20,7 @@ import { EmptyState } from "../shared/empty-state";import { ResultsFooter } from "../shared/results-footer";import { RowActions } from "../shared/row-actions";import { VirtualizedTable } from "../shared/virtualized-table";+import { docsPagePath, filePageId } from "../shared/entity/routes";import { truncatePath } from "../lib/format";import { cn } from "../lib/cn";import type { CodeSymbol } from "@repowise-dev/types/symbols";@@ -388,7 +389,11 @@ export function SymbolTable({{icon: BookOpen,label: "Docs",- href: `${prefix}/docs?file=${encodeURIComponent(sym.file_path)}`,+ // `?file=` was read by nothing, so this opened the+ // repo overview. `?page=` is the docs reader's+ // parameter and takes a wiki page id; a file with no+ // page gets told so by name.+ href: docsPagePath(prefix, filePageId(sym.file_path)),},]}/>diff --git a/packages/web/src/app/repos/[id]/files/[...path]/page.tsx b/packages/web/src/app/repos/[id]/files/[...path]/page.tsxindex 6ea80c8ee..6d4eff861 100644--- a/packages/web/src/app/repos/[id]/files/[...path]/page.tsx+++ b/packages/web/src/app/repos/[id]/files/[...path]/page.tsx@@ -4,7 +4,11 @@ import Link from "next/link";import { bundledLanguages, getSingletonHighlighter, type BundledLanguage } from "shiki";import { getFileContent, getFileDetail } from "@/lib/api/files";import { WikiMarkdown } from "@repowise-dev/ui/wiki/wiki-markdown";-import { fileEntityPath, symbolEntityPath } from "@repowise-dev/ui/shared/entity";+import {+ docsPagePath,+ fileEntityPath,+ symbolEntityPath,+} from "@repowise-dev/ui/shared/entity";import {asFilePageTab,buildFilePanels,@@ -159,6 +163,14 @@ export default async function FileEntityPage({ params, searchParams }: Props) {refetchTabs.push("coverage");}+ // Only when a page actually exists. The docs reader answers a `?page=` it+ // cannot find by naming the page that is missing, which is the right reply+ // to a reader who typed it and the wrong one to a link this page offered:+ // we already know here whether there is anything to open.+ const wikiHref = detail.wiki_page+ ? docsPagePath(prefix, detail.wiki_page.id)+ : undefined;+const panels = buildFilePanels({data: detail,linkPrefix: prefix,@@ -168,9 +180,6 @@ export default async function FileEntityPage({ params, searchParams }: Props) {? { docSlot: <WikiMarkdown content={detail.wiki_page.content} /> }: {}),coverageCodeHtml,- ...(detail.wiki_page- ? { wikiHref: `${prefix}/docs?page=${encodeURIComponent(detail.wiki_page.id)}` }- : {}),healthPanel: (<FileHealthPanelrepoId={id}@@ -192,7 +201,14 @@ export default async function FileEntityPage({ params, searchParams }: Props) {// same tree position and the active tab strands out of sync with the// URL the new page was rendered for.key={detail.file_path}- header={<FilePageHeader data={detail} linkPrefix={prefix} LinkComponent={Link} />}+ header={+ <FilePageHeader+ data={detail}+ linkPrefix={prefix}+ wikiHref={wikiHref}+ LinkComponent={Link}+ />+ }tabs={tabs}panels={panels}initialTab={initialTab}diff --git a/packages/web/src/app/repos/[id]/refactoring/page.tsx b/packages/web/src/app/repos/[id]/refactoring/page.tsxindex 4727d7a5e..4d82ad536 100644--- a/packages/web/src/app/repos/[id]/refactoring/page.tsx+++ b/packages/web/src/app/repos/[id]/refactoring/page.tsx@@ -65,6 +65,10 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri}, [allPlans, type]);const prefix = `/repos/${repoId}`;+ // `PlanRows` offers a second `line` argument and this deliberately ignores+ // it: the file page renders no line anchors, so appending `#L<n>` would be a+ // fragment that resolves to nothing and leaves the reader at the top of the+ // page wondering what they missed. Honour it here when the page grows them.const fileHref = useCallback((path: string) => fileEntityPath(prefix, path), [prefix]);// The open plan comes from the URL, so a reload or a shared link lands on thediff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsxindex ae6ac35a9..ec192ee34 100644--- a/packages/web/src/components/docs/docs-explorer.tsx+++ b/packages/web/src/components/docs/docs-explorer.tsx@@ -114,8 +114,15 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {if (pageParam) {// Set straight from the URL without waiting for the list: a page id is// enough to fetch it, so the reading column and the tree load side by- // side rather than one behind the other. An id that turns out not to- // exist resolves to the reader's empty state, same as before.+ // side rather than one behind the other.+ //+ // Deliberately no fallback to the overview when the id resolves to+ // nothing. Opening a different page would look like the link worked and+ // put a reader who asked about one file in front of another's prose;+ // the reader says which page was missing instead. Every caller that+ // builds `?page=file_page:<path>` for an arbitrary path — the hotspot+ // and symbol row actions, the file card — depends on that, because page+ // selection is budgeted and most files have no page.setSelectedPageId(pageParam);return;}@@ -299,6 +306,13 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {// Reading-column skeleton while its own page is in flight, and while// the list is still deciding which page to open on.isLoading={pageLoading || (!selectedPageId && isLoading)}+ // The id resolved to nothing. Guarded on `!pageLoading` so the+ // "no page for this one" line cannot flash over a request still in+ // flight, and on `!selectedPage` so it never shows over a page that+ // did land.+ missingPageId={+ selectedPageId && !pageLoading && !selectedPage ? selectedPageId : undefined+ }onSelectPage={handleSelectPage}persona={persona}sidebarOpen={sidebarOpen}diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsxindex f8fa37221..2c788f787 100644--- a/packages/web/src/components/docs/docs-viewer.tsx+++ b/packages/web/src/components/docs/docs-viewer.tsx@@ -8,6 +8,7 @@ import { cn } from "@/lib/utils/cn";import { getGitMetadata } from "@/lib/api/git";import { summarizeFixHistory } from "@repowise-dev/ui/lib/fix-history";import { DocsReader } from "@repowise-dev/ui/docs/docs-reader";+import { docsPagePath, fileEntityPath } from "@repowise-dev/ui/shared/entity";import { isModelWrittenType } from "@repowise-dev/ui/lib/page-types";import { PageGenerateButton } from "./page-generate-button";import { Badge } from "@repowise-dev/ui/ui/badge";@@ -252,6 +253,8 @@ interface DocsViewerProps {sidebarOpen: boolean;/** Called once an inline page upgrade completes so the host refreshes. */onGenerated?: () => void;+ /** A `?page=` id whose fetch settled with nothing. See `DocsReader`. */+ missingPageId?: string | undefined;}/**@@ -269,10 +272,15 @@ export function DocsViewer({persona,sidebarOpen,onGenerated,+ missingPageId,}: DocsViewerProps) {const buildPageHref = useCallback(- (pageId: string) =>- `/repos/${repoId}/docs?page=${encodeURIComponent(pageId)}`,+ (pageId: string) => docsPagePath(`/repos/${repoId}`, pageId),+ [repoId],+ );++ const buildFileHref = useCallback(+ (filePath: string) => fileEntityPath(`/repos/${repoId}`, filePath),[repoId],);@@ -305,6 +313,8 @@ export function DocsViewer({persona={persona}sidebarOpen={sidebarOpen}buildPageHref={buildPageHref}+ buildFileHref={buildFileHref}+ missingPageId={missingPageId}LinkComponent={Link}upgradeSlot={page && isModelWrittenType(page.page_type) ? (diff --git a/packages/web/src/components/files/files-explorer.tsx b/packages/web/src/components/files/files-explorer.tsxindex b8ce0dc37..623b769ff 100644--- a/packages/web/src/components/files/files-explorer.tsx+++ b/packages/web/src/components/files/files-explorer.tsx@@ -5,6 +5,7 @@ import useSWR from "swr";import { AlertTriangle } from "lucide-react";import { Skeleton } from "@repowise-dev/ui/ui/skeleton";import { FilesIndex } from "@repowise-dev/ui/files";+import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import { getFilesIndex } from "@/lib/api/files";export function FilesExplorer({ repoId }: { repoId: string }) {@@ -15,8 +16,7 @@ export function FilesExplorer({ repoId }: { repoId: string }) {);const fileHref = useCallback(- (path: string) =>- `/repos/${repoId}/files/${path.split("/").map(encodeURIComponent).join("/")}`,+ (path: string) => fileEntityPath(`/repos/${repoId}`, path),[repoId],);diff --git a/packages/web/src/components/graph/graph-doc-panel.tsx b/packages/web/src/components/graph/graph-doc-panel.tsxindex e6e4d482e..07f078f9b 100644--- a/packages/web/src/components/graph/graph-doc-panel.tsx+++ b/packages/web/src/components/graph/graph-doc-panel.tsx@@ -1,7 +1,7 @@"use client";import { GraphDocPanel as GraphDocPanelShell } from "@repowise-dev/ui/graph/graph-doc-panel";-import { fileEntityPath } from "@repowise-dev/ui/shared/entity";+import { fileEntityPath, filePageId } from "@repowise-dev/ui/shared/entity";import { usePage } from "@/lib/hooks/use-page";import type { DocPage } from "@repowise-dev/types/docs";@@ -12,7 +12,7 @@ interface GraphDocPanelWrapperProps {}export function GraphDocPanel({ repoId, nodeId, onClose }: GraphDocPanelWrapperProps) {- const pageId = `file_page:${nodeId}`;+ const pageId = filePageId(nodeId);const { page, isLoading, error } = usePage(pageId, repoId);return (diff --git a/packages/web/src/components/search/command-palette.tsx b/packages/web/src/components/search/command-palette.tsxindex b957f882a..c231e0887 100644--- a/packages/web/src/components/search/command-palette.tsx+++ b/packages/web/src/components/search/command-palette.tsx@@ -8,6 +8,7 @@ import { Search, LayoutDashboard, Settings, BookOpen, FileCode, Layers, Link2, Gimport { useSearch } from "@/lib/hooks/use-search";import { truncatePath } from "@repowise-dev/ui/lib/format";import { commandPaletteShortcutIsClaimed } from "@repowise-dev/ui/lib/command-palette-scope";+import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import { getFilesIndex } from "@/lib/api/files";import { repoNavItems } from "@/components/layout/nav-items";import { pageHref } from "@/lib/utils/page-href";@@ -257,12 +258,7 @@ export function CommandPalette({ repos, workspace }: CommandPaletteProps) {key={path}value={`file ${path} ${query}`}onSelect={() =>- navigate(- `/repos/${activeRepo.id}/files/${path- .split("/")- .map(encodeURIComponent)- .join("/")}`,- )+ navigate(fileEntityPath(`/repos/${activeRepo.id}`, path))}className="flex items-center gap-2.5 rounded-md px-3 py-2 text-sm cursor-pointer hover:bg-[var(--color-bg-elevated)] data-[selected=true]:bg-[var(--color-bg-elevated)]">diff --git a/packages/web/src/components/shared/file-card-host.tsx b/packages/web/src/components/shared/file-card-host.tsxindex d08d885d4..c1dd505bc 100644--- a/packages/web/src/components/shared/file-card-host.tsx+++ b/packages/web/src/components/shared/file-card-host.tsx@@ -2,6 +2,11 @@import { useState, useCallback } from "react";import { FileCardDialog } from "@repowise-dev/ui/shared/file-card";+import {+ docsPagePath,+ fileEntityPath,+ filePageId,+} from "@repowise-dev/ui/shared/entity";import type { FileCardData, FileCardLinks } from "@repowise-dev/ui/shared/file-card";/**@@ -22,8 +27,15 @@ export function useFileCardHost(repoId?: string) {customLinks ??(repoId? {+ file: fileEntityPath(`/repos/${repoId}`, next.file_path),graph: `/repos/${repoId}/architecture?view=graph&node=${encodeURIComponent(next.file_path)}`,- docs: `/repos/${repoId}/docs?file=${encodeURIComponent(next.file_path)}`,+ // `?file=` was read by nothing in the docs surface, so this+ // button silently opened the repo overview — a different file's+ // prose, looking exactly like the link had worked. The reader is+ // `?page=`, keyed by the wiki page id. Most files have no page,+ // and that case now says so by name rather than landing the+ // reader somewhere plausible and wrong.+ docs: docsPagePath(`/repos/${repoId}`, filePageId(next.file_path)),symbols: `/repos/${repoId}/architecture?view=symbols&q=${encodeURIComponent(next.file_path)}`,blastRadius: `/repos/${repoId}/code-health?tab=impact&file=${encodeURIComponent(next.file_path)}`,deadCode: `/repos/${repoId}/code-health?tab=dead-code`,diff --git a/packages/web/src/components/zoom/zoom-detail-panel.tsx b/packages/web/src/components/zoom/zoom-detail-panel.tsxindex a5488f4c2..fb6854078 100644--- a/packages/web/src/components/zoom/zoom-detail-panel.tsx+++ b/packages/web/src/components/zoom/zoom-detail-panel.tsx@@ -28,6 +28,7 @@ import {summarizeRelations,} from "@repowise-dev/ui/zoom";import { bandForScore } from "@repowise-dev/types/health";+import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import { healthBandTextColor } from "@repowise-dev/ui/health";interface ZoomDetailPanelProps {@@ -41,11 +42,9 @@ interface ZoomDetailPanelProps {onZoom: (id: string) => void;}-/** Route to a file's own page. Segments are encoded but the slashes are kept so- * the `/files/[...path]` catch-all receives the real path. */+/** Route to a file's own page. */function fileHref(repoId: string, path: string): string {- const encoded = path.split("/").map(encodeURIComponent).join("/");- return `/repos/${repoId}/files/${encoded}`;+ return fileEntityPath(`/repos/${repoId}`, path);}const KIND_LABEL: Record<ZoomNode["kind"], string> = {diff --git a/packages/web/src/lib/utils/page-href.ts b/packages/web/src/lib/utils/page-href.tsindex c2bba9690..07b31b239 100644--- a/packages/web/src/lib/utils/page-href.ts+++ b/packages/web/src/lib/utils/page-href.ts@@ -1,4 +1,8 @@-import { fileEntityPath } from "@repowise-dev/ui/shared/entity";+import { docsPagePath, fileEntityPath, filePageId } from "@repowise-dev/ui/shared/entity";++/** The `file_page:` id prefix, derived from the builder rather than restated,+ * so the parse here cannot drift from the construction there. */+const FILE_PAGE_PREFIX = filePageId("");/*** Resolve the best in-app destination for a wiki page id.@@ -8,8 +12,9 @@ import { fileEntityPath } from "@repowise-dev/ui/shared/entity";* so navigation keeps the tree/reading context.*/export function pageHref(repoId: string, pageId: string): string {- if (pageId.startsWith("file_page:")) {- return fileEntityPath(`/repos/${repoId}`, pageId.slice("file_page:".length));+ const prefix = `/repos/${repoId}`;+ if (pageId.startsWith(FILE_PAGE_PREFIX)) {+ return fileEntityPath(prefix, pageId.slice(FILE_PAGE_PREFIX.length));}- return `/repos/${repoId}/docs?page=${encodeURIComponent(pageId)}`;+ return docsPagePath(prefix, pageId);}