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.

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.md
index 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 from
sits one click from the treemap and the health map, which both paint the
canonical 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 the
diff --git a/packages/ui/__tests__/docs/docs-reader-file-door.test.tsx b/packages/ui/__tests__/docs/docs-reader-file-door.test.tsx
new file mode 100644
index 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.tsx
index 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.json
index 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.tsx
index 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.tsx
index 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.tsx
index 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>&rarr;</span>
+ </LinkComponent>
+ )}
</div>
{/* What this page was written from. The rail carried this as
diff --git a/packages/ui/src/files/file-doc-tab.tsx b/packages/ui/src/files/file-doc-tab.tsx
index 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 the
score and is on screen from whichever tab you arrive on. Repeating it
here 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.tsx
index 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
+ <A
href={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
+ <A
href={`${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
+ <A
href={`${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.tsx
index 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
+ <A
href={`${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
+ <A
href={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}&times;
</span>
- </a>
+ </A>
</li>
))}
</ul>
diff --git a/packages/ui/src/files/file-overview-tab.tsx b/packages/ui/src/files/file-overview-tab.tsx
index 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
+ <A
key={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 }: FileOverviewTabP
nodes={data.graph.dependents.slice(0, 5).map((n) => n.node_id)}
fileHref={fileHref}
symbolHref={symbolHref}
+ LinkComponent={LinkComponent}
/>
<NeighborColumn
label="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
+ <A
href={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.tsx
index 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 }: FilePageHead
return (
<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>&rarr;</span>
+ </A>
+ )}
+ </div>
{/* `break-all`, never an ellipsis: a path is the identity of this page
and rule 6 puts no truncation in the primary column. The directory
is set quieter than the leaf so a deep path still reads as one
diff --git a/packages/ui/src/files/file-page-panels.tsx b/packages/ui/src/files/file-page-panels.tsx
index 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: (
<FileDecisionsTab
decisions={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.tsx
index 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({
<RowActions
actions={[
{ 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.ts
deleted file mode 100644
index 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.tsx
deleted file mode 100644
index 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.tsx
index 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.tsx
index 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: (
<FileHealthPanel
repoId={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.tsx
index 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 the
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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, G
import { 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.tsx
index 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.tsx
index 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.ts
index 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);
}