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(workspace): open a contract from the table and read what it links to (#1899)

Raghav Chamadiya9a8f2faaa8a9
diff --git a/packages/ui/__tests__/workspace/contract-type-badge.test.tsx b/packages/ui/__tests__/workspace/contract-type-badge.test.tsx
new file mode 100644
index 000000000..955936eec
--- /dev/null
+++ b/packages/ui/__tests__/workspace/contract-type-badge.test.tsx
@@ -0,0 +1,48 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import {
+ ContractTypeBadge,
+ RoleBadge,
+ contractTypeLabel,
+} from "../../src/workspace/contract-type-badge.js";
+
+describe("ContractTypeBadge", () => {
+ it("names every type the extractors emit", () => {
+ expect(contractTypeLabel("http")).toBe("HTTP");
+ expect(contractTypeLabel("grpc")).toBe("gRPC");
+ expect(contractTypeLabel("socket")).toBe("Socket");
+ expect(contractTypeLabel("topic")).toBe("Topic");
+ expect(contractTypeLabel("data")).toBe("Table");
+ // The largest type in a real corpus, and the one that used to fall through
+ // to the raw lowercase string.
+ expect(contractTypeLabel("code")).toBe("Code");
+ });
+
+ it("falls back to the raw value for a type it does not know", () => {
+ render(<ContractTypeBadge type="queue" />);
+ expect(screen.getByText("queue")).toBeInTheDocument();
+ });
+
+ it("spends no ground or hue on the type", () => {
+ // The demotion is the point: a tinted pill per type tiles into stripes
+ // down a table, and following the colour goes nowhere.
+ const { container } = render(<ContractTypeBadge type="http" />);
+ const cls = container.firstElementChild?.className ?? "";
+ expect(cls).not.toMatch(/\bbg-/);
+ expect(cls).not.toMatch(/text-(green|yellow|amber|red|blue|purple|cyan|orange|teal)-/);
+ });
+});
+
+describe("RoleBadge", () => {
+ it("names the side without claiming a health band", () => {
+ const { container } = render(<RoleBadge role="provider" />);
+ expect(screen.getByText("Provider")).toBeInTheDocument();
+ const cls = container.firstElementChild?.className ?? "";
+ expect(cls).not.toMatch(/(green|yellow|amber|red)/);
+ });
+
+ it("treats anything that is not a provider as a consumer", () => {
+ render(<RoleBadge role="consumer" />);
+ expect(screen.getByText("Consumer")).toBeInTheDocument();
+ });
+});
diff --git a/packages/ui/src/workspace/contract-links-table.tsx b/packages/ui/src/workspace/contract-links-table.tsx
index e61c8e4cd..e0efb7f93 100644
--- a/packages/ui/src/workspace/contract-links-table.tsx
+++ b/packages/ui/src/workspace/contract-links-table.tsx
@@ -53,10 +53,10 @@ export function ContractLinksTable({ links }: ContractLinksTableProps) {
<span className="text-xs font-medium text-[var(--color-text-primary)]">
{link.provider_repo}
</span>
- <span
- className="text-xs font-mono text-[var(--color-text-tertiary)] truncate min-w-[140px] max-w-[260px] block"
- title={link.provider_file}
- >
+ {/* No truncation: a path is exactly the string somebody is
+ scanning for, and an ellipsis reports a layout decision as
+ missing content. Wraps instead, as the contracts table does. */}
+ <span className="text-xs font-mono text-[var(--color-text-tertiary)] [overflow-wrap:anywhere]">
{link.provider_file}
</span>
</div>
@@ -66,10 +66,10 @@ export function ContractLinksTable({ links }: ContractLinksTableProps) {
<span className="text-xs font-medium text-[var(--color-text-primary)]">
{link.consumer_repo}
</span>
- <span
- className="text-xs font-mono text-[var(--color-text-tertiary)] truncate min-w-[140px] max-w-[260px] block"
- title={link.consumer_file}
- >
+ {/* No truncation: a path is exactly the string somebody is
+ scanning for, and an ellipsis reports a layout decision as
+ missing content. Wraps instead, as the contracts table does. */}
+ <span className="text-xs font-mono text-[var(--color-text-tertiary)] [overflow-wrap:anywhere]">
{link.consumer_file}
</span>
</div>
diff --git a/packages/ui/src/workspace/contract-type-badge.tsx b/packages/ui/src/workspace/contract-type-badge.tsx
index 4841b01fd..aa4f745d6 100644
--- a/packages/ui/src/workspace/contract-type-badge.tsx
+++ b/packages/ui/src/workspace/contract-type-badge.tsx
@@ -1,42 +1,55 @@
"use client";
-import { cn } from "../lib/cn";
-
-const TYPE_STYLES: Record<string, { bg: string; text: string; label: string }> = {
- http: { bg: "bg-blue-500/10", text: "text-blue-400", label: "HTTP" },
- grpc: { bg: "bg-purple-500/10", text: "text-purple-400", label: "gRPC" },
- socket: { bg: "bg-cyan-500/10", text: "text-cyan-400", label: "Socket" },
- topic: { bg: "bg-orange-500/10", text: "text-orange-400", label: "Topic" },
- data: { bg: "bg-teal-500/10", text: "text-teal-400", label: "Table" },
+/**
+ * Display label per contract type.
+ *
+ * `code` was absent while being the single largest type in the corpus, so
+ * every row of it fell through to the raw lowercase string.
+ */
+const TYPE_LABELS: Record<string, string> = {
+ http: "HTTP",
+ grpc: "gRPC",
+ socket: "Socket",
+ topic: "Topic",
+ data: "Table",
+ code: "Code",
};
+/** The type's display name, or the raw value when a new type appears. */
+export function contractTypeLabel(type: string): string {
+ return TYPE_LABELS[type] ?? type;
+}
+
+/**
+ * The contract's transport, as a word.
+ *
+ * This was a filled pill with a tinted ground per type, which is the shape
+ * `SEVERITY_CHIP` was retired for: a ground, a colour and a border spent on a
+ * token that repeats once per row tile into stripes down a table and outweigh
+ * the contract ids they label. Adding a sixth ground for the largest type
+ * would have made the loudest column the one carrying the least, and following
+ * the colour goes nowhere — the type is what the filter already selects on. A
+ * quiet word says the same thing, and a new type costs nothing.
+ */
export function ContractTypeBadge({ type }: { type: string }) {
- const style = TYPE_STYLES[type] ?? { bg: "bg-gray-500/10", text: "text-gray-400", label: type };
return (
- <span
- className={cn(
- "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium",
- style.bg,
- style.text,
- )}
- >
- {style.label}
- </span>
+ <span className="text-xs text-[var(--color-text-secondary)]">{contractTypeLabel(type)}</span>
);
}
+/**
+ * Which side of the contract a row is.
+ *
+ * Green for provider against amber for consumer broke two rules at once. Those
+ * hues are reserved for readouts that carry a health band, and neither role is
+ * one. And providers outnumber consumers by better than two to one, so the
+ * green was the default state wearing the colour of a verdict — a mark every
+ * row carries says nothing.
+ */
export function RoleBadge({ role }: { role: string }) {
- const isProvider = role === "provider";
return (
- <span
- className={cn(
- "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium",
- isProvider
- ? "bg-green-500/10 text-green-400"
- : "bg-yellow-500/10 text-yellow-400",
- )}
- >
- {isProvider ? "Provider" : "Consumer"}
+ <span className="text-xs text-[var(--color-text-secondary)]">
+ {role === "provider" ? "Provider" : "Consumer"}
</span>
);
}
diff --git a/packages/web/src/app/workspace/contracts/contract-filters.tsx b/packages/web/src/app/workspace/contracts/contract-filters.tsx
index 6eb61eae2..2f2a18da8 100644
--- a/packages/web/src/app/workspace/contracts/contract-filters.tsx
+++ b/packages/web/src/app/workspace/contracts/contract-filters.tsx
@@ -3,15 +3,58 @@
import { useRouter, useSearchParams } from "next/navigation";
import { useCallback, useTransition } from "react";
import { Filter } from "lucide-react";
+import { contractTypeLabel } from "@repowise-dev/ui/workspace/contract-type-badge";
+import { formatNumber } from "@repowise-dev/ui/lib/format";
-const TYPE_OPTIONS = [
- { value: "", label: "All types" },
- { value: "http", label: "HTTP" },
- { value: "grpc", label: "gRPC" },
- { value: "socket", label: "Socket" },
- { value: "topic", label: "Topic" },
- { value: "data", label: "Table" },
-];
+/**
+ * Every type the extractors can emit, in the order the select lists them.
+ * Which of them a workspace actually holds is a separate question — see
+ * `typeOptions`.
+ */
+const ALL_TYPES = ["http", "grpc", "socket", "topic", "data", "code"];
+
+/**
+ * The type options this workspace can act on.
+ *
+ * A control that cannot act must look like it, and three of the five options
+ * this select used to offer could not return a row on any workspace here:
+ * `grpc`, `socket` and `topic` are all zero, while `code` — the single largest
+ * type — had no option at all. The distribution is already on the workspace
+ * payload, so the control is built from it rather than from the vocabulary,
+ * and the count goes on the label so a reader knows what a filter is worth
+ * before spending a click on it.
+ *
+ * `byType` must be the workspace-wide breakdown, not the one on the contracts
+ * response: that one is computed after the filters are applied, so selecting a
+ * type would delete every other option and strand the reader inside it.
+ *
+ * With no breakdown available the full vocabulary comes back rather than an
+ * empty select — an unfiltered list is a worse failure than an option that
+ * returns nothing.
+ */
+function typeOptions(byType: Record<string, number> | null | undefined, selected: string) {
+ const present = byType
+ ? ALL_TYPES.filter((t) => (byType[t] ?? 0) > 0)
+ : ALL_TYPES;
+ // A type the vocabulary does not name still gets an option when the
+ // workspace holds one, so a new extractor is filterable before this list is.
+ const extra = byType
+ ? Object.keys(byType).filter((t) => !ALL_TYPES.includes(t) && byType[t]! > 0)
+ : [];
+ const values = [...present, ...extra];
+ // A type someone linked to directly stays selectable even when the workspace
+ // holds none of it, or the select would render blank against its own URL.
+ if (selected && !values.includes(selected)) values.push(selected);
+ return [
+ { value: "", label: "All types" },
+ ...values.map((value) => ({
+ value,
+ label: byType?.[value]
+ ? `${contractTypeLabel(value)} ${formatNumber(byType[value]!)}`
+ : contractTypeLabel(value),
+ })),
+ ];
+}
const ROLE_OPTIONS = [
{ value: "", label: "All roles" },
@@ -30,10 +73,18 @@ const SELECT_CLASS =
* with the new filter, so a filtered view is linkable and the table's counts
* come from the same request that drew the rows.
*/
-export function ContractFilters({ repos }: { repos: string[] }) {
+export function ContractFilters({
+ repos,
+ byType,
+}: {
+ repos: string[];
+ /** Workspace-wide contracts per type, from `contract_summary`. */
+ byType?: Record<string, number> | null;
+}) {
const router = useRouter();
const params = useSearchParams();
const [pending, startTransition] = useTransition();
+ const types = typeOptions(byType, params.get("type") ?? "");
const set = useCallback(
(key: string, value: string) => {
@@ -64,7 +115,7 @@ export function ContractFilters({ repos }: { repos: string[] }) {
value={params.get("type") ?? ""}
onChange={(e) => set("type", e.target.value)}
>
- {TYPE_OPTIONS.map((o) => (
+ {types.map((o) => (
<option key={o.value} value={o.value}>
{o.label}
</option>
diff --git a/packages/web/src/app/workspace/contracts/contract-href.test.ts b/packages/web/src/app/workspace/contracts/contract-href.test.ts
new file mode 100644
index 000000000..1db715b22
--- /dev/null
+++ b/packages/web/src/app/workspace/contracts/contract-href.test.ts
@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { contractDetailHref } from "./contract-href";
+
+describe("contractDetailHref", () => {
+ it("carries all three parts of the identity", () => {
+ const href = contractDetailHref({
+ repo: "repowise",
+ file_path: "packages/api-client/src/c4.ts",
+ contract_id: "http::GET::/api/graph/{param}/c4/mermaid",
+ });
+ const params = new URLSearchParams(href.split("?")[1]);
+ expect(href.startsWith("/workspace/contracts/detail?")).toBe(true);
+ expect(params.get("repo")).toBe("repowise");
+ expect(params.get("file")).toBe("packages/api-client/src/c4.ts");
+ expect(params.get("id")).toBe("http::GET::/api/graph/{param}/c4/mermaid");
+ });
+
+ it("escapes the slashes and braces a contract id carries", () => {
+ // `id` and `file` both hold characters a path segment would have to escape,
+ // which is why the route takes them as query parameters.
+ const href = contractDetailHref({
+ repo: "backend",
+ file_path: "app/routers/github_app.py",
+ contract_id: "http::GET::/app/installations/{param}",
+ });
+ expect(href).not.toContain("{");
+ expect(new URLSearchParams(href.split("?")[1]).get("id")).toBe(
+ "http::GET::/app/installations/{param}",
+ );
+ });
+
+ it("distinguishes two repos declaring the same contract id", () => {
+ const id = "http::GET::/user";
+ const a = contractDetailHref({ repo: "a", file_path: "x.ts", contract_id: id });
+ const b = contractDetailHref({ repo: "b", file_path: "x.ts", contract_id: id });
+ expect(a).not.toBe(b);
+ });
+});
diff --git a/packages/web/src/app/workspace/contracts/contract-href.ts b/packages/web/src/app/workspace/contracts/contract-href.ts
new file mode 100644
index 000000000..fa00a80db
--- /dev/null
+++ b/packages/web/src/app/workspace/contracts/contract-href.ts
@@ -0,0 +1,24 @@
+/**
+ * The contract detail route, built from the shareable identity.
+ *
+ * `(repo, file, id)` and not `id` alone: several repos declare the same
+ * `http::GET::/user`. Query parameters rather than path segments because both
+ * `file` and `id` carry slashes, which a path segment would have to escape and
+ * the reader would then have to look at.
+ *
+ * Deliberately not keyed on the line. One file can call the same endpoint
+ * twice, and the endpoint answers with the first of them; keying on the line
+ * would rot every saved link the moment somebody adds an import above the call.
+ */
+export function contractDetailHref(contract: {
+ repo: string;
+ file_path: string;
+ contract_id: string;
+}): string {
+ const params = new URLSearchParams({
+ repo: contract.repo,
+ file: contract.file_path,
+ id: contract.contract_id,
+ });
+ return `/workspace/contracts/detail?${params.toString()}`;
+}
diff --git a/packages/web/src/app/workspace/contracts/contracts-table.tsx b/packages/web/src/app/workspace/contracts/contracts-table.tsx
index da326ba23..dbc7828dc 100644
--- a/packages/web/src/app/workspace/contracts/contracts-table.tsx
+++ b/packages/web/src/app/workspace/contracts/contracts-table.tsx
@@ -1,5 +1,6 @@
"use client";
+import { useRouter } from "next/navigation";
import {
ResponsiveTable,
type ResponsiveColumn,
@@ -9,6 +10,7 @@ import {
RoleBadge,
} from "@repowise-dev/ui/workspace/contract-type-badge";
import type { WorkspaceContractEntry } from "@/lib/api/types";
+import { contractDetailHref } from "./contract-href";
type ContractRow = WorkspaceContractEntry & { _key: string };
@@ -68,9 +70,16 @@ const CONTRACT_COLUMNS: ResponsiveColumn<ContractRow>[] = [
];
export function ContractsTable({ contracts }: { contracts: WorkspaceContractEntry[] }) {
+ const router = useRouter();
+
return (
<ResponsiveTable
columns={CONTRACT_COLUMNS}
+ // The row is the verb. No "View" column and no icon cluster: there is
+ // exactly one thing a contract row does, and `ResponsiveTable` already
+ // carries the focus ring and the Enter/Space handling for both the table
+ // and the stacked-card rendering.
+ onRowClick={(c) => router.push(contractDetailHref(c))}
rows={contracts.map((c) => ({
// The contract identity, not the array index: an index renumbers every
// row whenever a filter changes. `line` is part of the key because one
diff --git a/packages/web/src/app/workspace/contracts/detail/contract-body.tsx b/packages/web/src/app/workspace/contracts/detail/contract-body.tsx
new file mode 100644
index 000000000..06075c250
--- /dev/null
+++ b/packages/web/src/app/workspace/contracts/detail/contract-body.tsx
@@ -0,0 +1,662 @@
+import type { ReactNode } from "react";
+import Link from "next/link";
+import type {
+ WorkspaceContractDetail,
+ WorkspaceContractEntry,
+ WorkspaceContractLinkEntry,
+} from "@/lib/api/types";
+import type { ContractSchema, SchemaField } from "@repowise-dev/types/workspace";
+import { contractTypeLabel } from "@repowise-dev/ui/workspace/contract-type-badge";
+import { fileEntityPath } from "@repowise-dev/ui/shared/entity";
+import { formatNumber } from "@repowise-dev/ui/lib/format";
+
+/**
+ * One contract, read top to bottom.
+ *
+ * A reading surface rather than a chrome one, so it takes the reading type
+ * scale. That is also why the sections are written here rather than composed
+ * from `OverviewSection`: that component's heading sits at 16px, which is the
+ * reading body size, and a heading the same size as the text under it is a
+ * bolded paragraph.
+ *
+ * The prose is the part doing the work. Most providers in a workspace this
+ * size have no caller, which is the ordinary condition of an exported symbol
+ * rather than a finding, and no amount of layout says that. Nothing on this
+ * page carries a health band, so nothing on it is green, amber or red.
+ */
+
+interface Props {
+ detail: WorkspaceContractDetail;
+ /** Repo alias to indexed repo id. A never-indexed repo has no entry. */
+ repoIds: Record<string, string>;
+}
+
+export function ContractBody({ detail, repoIds }: Props) {
+ const { contract, links, unmatched_reason: unmatchedReason } = detail;
+ const isProvider = contract.role === "provider";
+ const schema = asSchema(detail.contract_schema);
+
+ return (
+ <div className="mx-auto w-full max-w-[1280px] p-[var(--page-pad)]">
+ <Link
+ href="/workspace/contracts"
+ className="text-xs font-medium text-[var(--color-accent-primary)] hover:underline"
+ >
+ <span aria-hidden>&larr;</span> Contracts
+ </Link>
+
+ <header className="mt-6 flex flex-col gap-3">
+ <p className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+ {contractTypeLabel(contract.contract_type)} contract
+ <span className="mx-2 text-[var(--color-border-hover)]">/</span>
+ {isProvider ? "Provider" : "Consumer"}
+ </p>
+ <h1 className="text-[2rem] font-semibold leading-tight tracking-tight text-[var(--color-text-primary)] [overflow-wrap:anywhere]">
+ {headingFor(contract)}
+ </h1>
+ <p className="max-w-[68ch] text-base leading-relaxed text-[var(--color-text-secondary)] [text-wrap:pretty]">
+ {ledeFor(contract)}
+ </p>
+ </header>
+
+ <Section
+ title={isProvider ? "Declared here" : "Called here"}
+ description={
+ isProvider
+ ? "Where this contract is declared, and how confident extraction is that this is the declaration."
+ : "The call site, and how confident extraction is that it names this contract."
+ }
+ >
+ <Facts>
+ <Fact label="Repository">{contract.repo}</Fact>
+ <Fact label="File">
+ <FileRef
+ repo={contract.repo}
+ path={contract.file_path}
+ line={contract.line}
+ repoIds={repoIds}
+ />
+ </Fact>
+ {contract.service && <Fact label="Service">{contract.service}</Fact>}
+ <Fact label="Symbol">
+ {/* The extractor's own string, dialect prefix included: it is what
+ names the framework that matched, and shortening it would hide
+ the difference between a route declaration and a client call. */}
+ <span className="font-mono text-xs [overflow-wrap:anywhere]">
+ {contract.symbol_name || "—"}
+ </span>
+ </Fact>
+ <Fact label="Confidence">
+ <span className="tabular-nums">{Math.round(contract.confidence * 100)}%</span>
+ </Fact>
+ <Fact label="Contract id">
+ <span className="font-mono text-xs [overflow-wrap:anywhere]">
+ {contract.contract_id}
+ </span>
+ </Fact>
+ </Facts>
+ </Section>
+
+ <LinkSection
+ contract={contract}
+ links={links}
+ unmatchedReason={unmatchedReason}
+ repoIds={repoIds}
+ />
+
+ <SchemaSection contract={contract} schema={schema} />
+
+ <Section
+ title="How it was found"
+ description="What the extractor recorded about this contract. The layer is the part worth reading: an index contract came from the parsed symbol table, a regex one from a text dialect, which is where recall is least certain."
+ >
+ <Facts>
+ {metaEntries(contract.meta).map(([key, value]) => (
+ <Fact key={key} label={metaLabel(key)}>
+ <span className="font-mono text-xs [overflow-wrap:anywhere]">{value}</span>
+ </Fact>
+ ))}
+ {metaEntries(contract.meta).length === 0 && (
+ <Fact label="Detail">
+ <span className="text-[var(--color-text-tertiary)]">
+ The extractor recorded none.
+ </span>
+ </Fact>
+ )}
+ </Facts>
+ </Section>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// The link section, and the states a contract can be in
+// ---------------------------------------------------------------------------
+
+function LinkSection({
+ contract,
+ links,
+ unmatchedReason,
+ repoIds,
+}: {
+ contract: WorkspaceContractEntry;
+ links: WorkspaceContractLinkEntry[];
+ unmatchedReason: string | null;
+ repoIds: Record<string, string>;
+}) {
+ const isProvider = contract.role === "provider";
+
+ if (links.length === 0) {
+ return (
+ <Section
+ title={isProvider ? "No caller found" : unmatchedTitle(unmatchedReason)}
+ description={
+ isProvider
+ ? unlinkedProviderProse(contract)
+ : unmatchedConsumerProse(unmatchedReason, contract)
+ }
+ />
+ );
+ }
+
+ const otherRepos = new Set(links.map((l) => (isProvider ? l.consumer_repo : l.provider_repo)));
+ const sameRepoOnly = otherRepos.size === 1 && otherRepos.has(contract.repo);
+
+ return (
+ <Section
+ title={isProvider ? "Callers" : "Served by"}
+ description={
+ isProvider
+ ? providerLinkedProse(links.length, otherRepos.size, sameRepoOnly, contract.repo)
+ : "This call resolves to the code that serves it. A match joins a call site to a declaration; it does not mean the two were written against a shared schema."
+ }
+ >
+ <LinkTable links={links} side={isProvider ? "consumer" : "provider"} repoIds={repoIds} />
+ </Section>
+ );
+}
+
+function providerLinkedProse(
+ linkCount: number,
+ repoCount: number,
+ sameRepoOnly: boolean,
+ repo: string,
+): string {
+ const one = linkCount === 1;
+ const head = `${countPhrase(linkCount, "call site", "call sites")} resolve${one ? "s" : ""} to this contract`;
+ if (sameRepoOnly) {
+ // Every provider in this state on a real workspace has exactly one caller,
+ // so the singular is the sentence that actually ships.
+ return `${head}, ${one ? `and it is inside ${repo}` : `all of them inside ${repo}`}. A pair is skipped only when the repository and the service are both the same, so ${one ? "that is a call" : "these are calls"} made from a different service in the same repository.`;
+ }
+ return `${head} across ${countPhrase(repoCount, "repository", "repositories")}.`;
+}
+
+/**
+ * The state most contracts on this workspace are in, and the one most likely
+ * to be misread.
+ *
+ * It is the expected condition for a route or an exported symbol in a small
+ * workspace, so it gets a sentence rather than a colour: an unlinked provider
+ * carries no health band, and green, amber and red are reserved for readouts
+ * that do. A reader who correctly inferred a colour here would be taught a
+ * rule that makes them wrong about the next mark they see.
+ */
+function unlinkedProviderProse(contract: WorkspaceContractEntry): string {
+ // A pair is skipped when the repository *and* the service both match, so the
+ // excluded set is not "everything in this repo" unless this declaration sits
+ // outside a service too. Naming the wrong set here would send somebody
+ // looking for a caller the page had told them could not exist.
+ const excluded = contract.service
+ ? `a call made from inside ${contract.repo}/${contract.service}`
+ : `a call made from elsewhere in ${contract.repo} that also sits outside any service`;
+ return `Nothing in this workspace resolves to this contract. Read that as two possibilities rather than one. A call is joined to the code that serves it only when the two do not share both a repository and a service, so ${excluded} is excluded by construction and never appears here. And a call written in a form extraction could not follow looks exactly the same from this side. Neither reading makes this dead code.`;
+}
+
+/**
+ * The heading names the state, not the absence.
+ *
+ * "No provider found" is true of only two of these. A call to a third party
+ * and a call that never leaves its own service both matched nothing on
+ * purpose, and heading them as a failure to find something invites the reader
+ * to go looking for it.
+ */
+function unmatchedTitle(reason: string | null): string {
+ switch (reason) {
+ case "external_host":
+ return "Outside this workspace";
+ case "internal_only":
+ return "Not a cross-repo link";
+ case "unlinked":
+ return "No link formed";
+ default:
+ return "No provider found";
+ }
+}
+
+function unmatchedConsumerProse(reason: string | null, contract: WorkspaceContractEntry): string {
+ const host = typeof contract.meta?.host === "string" ? contract.meta.host : null;
+ switch (reason) {
+ case "external_host":
+ return `This call goes to ${host ?? "a third-party host"}, which is not a service in this workspace. Calls to a literal external host are left out of matching on purpose, so there is nothing here to link it to and nothing to fix.`;
+ case "internal_only":
+ return `The only declarations matching this call live in the same repository and the same service as the call itself, so it never crosses a boundary. Intra-service calls are left out of the link set on purpose: a link is a claim that two services depend on each other.`;
+ case "no_provider":
+ return `Nothing in this workspace declares ${contract.contract_id}. Either it is served by something outside these repositories, or the declaration is written in a form extraction did not recognise.`;
+ case "unlinked":
+ return "A declaration with this id exists in another service, but no link was formed between the two. That is rare, and it points at a gap in the matcher rather than at the code.";
+ default:
+ return "This call matched no declaration, and no reason was recorded for it. Reasons come from the system graph, so a workspace that has not built one reports the count without the explanation.";
+ }
+}
+
+function LinkTable({
+ links,
+ side,
+ repoIds,
+}: {
+ links: WorkspaceContractLinkEntry[];
+ side: "provider" | "consumer";
+ repoIds: Record<string, string>;
+}) {
+ // A local table rather than `ContractLinksTable`: that one leads with the
+ // contract id and its type, and on this page both of those are the heading.
+ // What is left to say is the other side of each link.
+ return (
+ <TableScroll>
+ <table className="w-full border-collapse text-left">
+ <caption className="sr-only">
+ {side === "provider" ? "Providers serving this call" : "Call sites resolving here"}
+ </caption>
+ <thead>
+ <tr className="text-xs uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ <Th>Repository</Th>
+ <Th>File</Th>
+ {/* Column priority, as the shared tables run it: below md only
+ the repository and the path survive, because three wrapping
+ mono columns in 358px break a path mid-token to make room for
+ a symbol nobody came here to read. */}
+ <Th className="max-md:hidden">Symbol</Th>
+ <Th className="max-lg:hidden">Match</Th>
+ <Th className="max-md:hidden">Confidence</Th>
+ </tr>
+ </thead>
+ <tbody>
+ {links.map((link) => {
+ const repo = side === "provider" ? link.provider_repo : link.consumer_repo;
+ const file = side === "provider" ? link.provider_file : link.consumer_file;
+ const symbol = side === "provider" ? link.provider_symbol : link.consumer_symbol;
+ const service = side === "provider" ? link.provider_service : link.consumer_service;
+ return (
+ <tr
+ key={`${repo}|${file}|${symbol}`}
+ className="border-t border-[var(--color-border-default)] align-top"
+ >
+ <Td>
+ <span className="text-xs font-medium text-[var(--color-text-primary)]">
+ {repo}
+ </span>
+ {service && (
+ <span className="mt-0.5 block font-mono text-[11px] text-[var(--color-text-tertiary)] [overflow-wrap:anywhere]">
+ {service}
+ </span>
+ )}
+ </Td>
+ <Td>
+ <FileRef repo={repo} path={file} line={null} repoIds={repoIds} />
+ </Td>
+ <Td className="max-md:hidden">
+ <span className="font-mono text-xs text-[var(--color-text-tertiary)] [overflow-wrap:anywhere]">
+ {symbol}
+ </span>
+ </Td>
+ <Td className="max-lg:hidden">
+ <span className="text-xs text-[var(--color-text-secondary)]">
+ {link.match_type}
+ </span>
+ </Td>
+ <Td className="max-lg:hidden">
+ <span className="text-xs tabular-nums text-[var(--color-text-tertiary)]">
+ {Math.round(link.confidence * 100)}%
+ </span>
+ </Td>
+ </tr>
+ );
+ })}
+ </tbody>
+ </table>
+ </TableScroll>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// The shape section
+// ---------------------------------------------------------------------------
+
+/**
+ * The request and response shapes, when a parser recovered them.
+ *
+ * The view adapts and then says what it dropped. A `data` contract never
+ * carries a shape at all, and the signature reader recovers parameters and
+ * stops, so a response table would be an empty box under every contract that
+ * has one. Naming what would fill it is the whole content of the absent case.
+ */
+function SchemaSection({
+ contract,
+ schema,
+}: {
+ contract: WorkspaceContractEntry;
+ schema: ContractSchema | null;
+}) {
+ if (!schema) {
+ return <Section title="Shape" description={noSchemaProse(contract.contract_type)} />;
+ }
+
+ const hasRequest = schema.request_fields.length > 0;
+ const hasResponse = schema.response_fields.length > 0;
+
+ return (
+ <Section title="Shape" description={schemaProse(schema.source, hasResponse)}>
+ {hasRequest && <FieldTable caption="Request" fields={schema.request_fields} />}
+ {hasResponse && <FieldTable caption="Response" fields={schema.response_fields} />}
+ {!hasRequest && !hasResponse && (
+ <p className="text-sm text-[var(--color-text-tertiary)]">
+ The reader produced a shape with no fields in it.
+ </p>
+ )}
+ </Section>
+ );
+}
+
+function schemaProse(source: string, hasResponse: boolean): string {
+ const head = `Recovered by the ${source} reader.`;
+ if (hasResponse) {
+ return `${head} Fields are what the declaration names, not what any one caller passes.`;
+ }
+ if (source === "signature") {
+ return `${head} It reads a declaration's parameters and stops there, so there is no return shape below; a response would have to come from an OpenAPI or proto declaration.`;
+ }
+ return `${head} It recovered no return shape for this contract.`;
+}
+
+function noSchemaProse(type: string): string {
+ if (type === "data") {
+ return "A table contract carries no field shape. It is matched on the table name, and nothing on that path reads a column list, so this section is empty for every table contract rather than for this one in particular.";
+ }
+ return "No reader recovered a shape for this contract. A shape comes off a typed declaration, so an untyped signature, a route declared through a decorator alone, or a file the index never parsed all arrive here without one.";
+}
+
+function FieldTable({ caption, fields }: { caption: string; fields: SchemaField[] }) {
+ return (
+ <TableScroll>
+ <table className="w-full border-collapse text-left">
+ <caption className="pb-2 text-left text-xs font-medium text-[var(--color-text-secondary)]">
+ {caption}
+ </caption>
+ <thead>
+ <tr className="text-xs uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ <Th>Field</Th>
+ <Th>Type</Th>
+ <Th>Required</Th>
+ </tr>
+ </thead>
+ <tbody>
+ {fields.map((f, i) => (
+ <tr
+ key={`${f.name}|${f.number ?? i}`}
+ className="border-t border-[var(--color-border-default)]"
+ >
+ <Td>
+ <span className="font-mono text-xs text-[var(--color-text-primary)] [overflow-wrap:anywhere]">
+ {f.name}
+ {f.repeated && (
+ <span className="text-[var(--color-text-tertiary)]"> (repeated)</span>
+ )}
+ </span>
+ </Td>
+ <Td>
+ <span className="font-mono text-xs text-[var(--color-text-secondary)] [overflow-wrap:anywhere]">
+ {f.type}
+ </span>
+ </Td>
+ <Td>
+ <span className="text-xs text-[var(--color-text-tertiary)]">
+ {f.required ? "Required" : "Optional"}
+ </span>
+ </Td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </TableScroll>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Pieces
+// ---------------------------------------------------------------------------
+
+/**
+ * A hairline and vertical rhythm, not a card. Five states invite five boxes,
+ * and boxes at the same weight say every section matters equally.
+ */
+function Section({
+ title,
+ description,
+ children,
+}: {
+ title: string;
+ description?: string;
+ children?: ReactNode;
+}) {
+ return (
+ <section className="mt-10 flex flex-col gap-3 border-t border-[var(--color-border-default)] pt-6 sm:mt-12 sm:pt-8">
+ <h2 className="text-xl font-semibold tracking-tight text-[var(--color-text-primary)]">
+ {title}
+ </h2>
+ {description && (
+ <p className="max-w-[68ch] text-base leading-relaxed text-[var(--color-text-secondary)] [text-wrap:pretty]">
+ {description}
+ </p>
+ )}
+ {children}
+ </section>
+ );
+}
+
+/** Wide content scrolls inside its own container, and bleeds to the edge on
+ * mobile rather than sitting in a padded box narrower than the screen. */
+function TableScroll({ children }: { children: ReactNode }) {
+ return (
+ <div className="-mx-[var(--page-pad)] overflow-x-auto px-[var(--page-pad)] sm:mx-0 sm:px-0">
+ {children}
+ </div>
+ );
+}
+
+function Facts({ children }: { children: ReactNode }) {
+ return (
+ <dl className="m-0 grid grid-cols-1 gap-x-10 gap-y-4 sm:grid-cols-[max-content_minmax(0,1fr)]">
+ {children}
+ </dl>
+ );
+}
+
+function Fact({ label, children }: { label: string; children: ReactNode }) {
+ return (
+ <div className="contents">
+ <dt className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)] sm:pt-1">
+ {label}
+ </dt>
+ {/* min-w-0 or a long path refuses to shrink and pushes the page wide. */}
+ <dd className="m-0 min-w-0 text-sm text-[var(--color-text-secondary)]">{children}</dd>
+ </div>
+ );
+}
+
+function Th({ children, className }: { children: ReactNode; className?: string }) {
+ return <th className={`px-3 py-2 font-medium ${className ?? ""}`}>{children}</th>;
+}
+
+function Td({ children, className }: { children: ReactNode; className?: string }) {
+ return <td className={`px-3 py-2 align-top ${className ?? ""}`}>{children}</td>;
+}
+
+/**
+ * A path, linked into the repo's file page when that repo is indexed.
+ *
+ * A workspace repo that has never been indexed carries no `repo_id` and has no
+ * page to send anybody to, so the path is printed rather than linked, matching
+ * how the workspace listing degrades. The line is text rather than part of the
+ * href because the file page takes no line parameter, and a link that lands
+ * nowhere near the number it names is worse than the number on its own.
+ */
+function FileRef({
+ repo,
+ path,
+ line,
+ repoIds,
+}: {
+ repo: string;
+ path: string;
+ line: number | null;
+ repoIds: Record<string, string>;
+}) {
+ const repoId = repoIds[repo];
+ const text = <span className="font-mono text-xs [overflow-wrap:anywhere]">{path}</span>;
+ return (
+ <span>
+ {repoId ? (
+ <Link
+ href={fileEntityPath(`/repos/${repoId}`, path)}
+ className="text-[var(--color-accent-primary)] hover:underline"
+ >
+ {text}
+ </Link>
+ ) : (
+ <span className="text-[var(--color-text-tertiary)]">{text}</span>
+ )}
+ {line != null && (
+ <span className="ml-2 text-xs tabular-nums text-[var(--color-text-tertiary)]">
+ line {line}
+ </span>
+ )}
+ </span>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Copy
+// ---------------------------------------------------------------------------
+
+/** The readable name of a contract, falling back to its id. */
+export function headingFor(contract: WorkspaceContractEntry): string {
+ const meta = contract.meta ?? {};
+ const method = typeof meta.method === "string" ? meta.method : null;
+ const path = typeof meta.path === "string" ? meta.path : null;
+ const table = typeof meta.table === "string" ? meta.table : null;
+ if (method && path) return `${method} ${path}`;
+ if (table) return table;
+ if (contract.contract_type === "code" && contract.symbol_name) return contract.symbol_name;
+ return contract.contract_id;
+}
+
+/** One sentence saying what this record is, before any of the tables. */
+function ledeFor(contract: WorkspaceContractEntry): string {
+ const isProvider = contract.role === "provider";
+ const pkg = typeof contract.meta?.package === "string" ? contract.meta.package : null;
+ switch (contract.contract_type) {
+ case "http":
+ return isProvider
+ ? `${contract.repo} serves this route.`
+ : `${contract.repo} calls this route.`;
+ case "data":
+ return isProvider
+ ? `${contract.repo} defines this table.`
+ : `${contract.repo} reads or writes this table.`;
+ case "code":
+ return isProvider
+ ? `${contract.repo} exports this from ${pkg ?? "a package"}.`
+ : `${contract.repo} imports this from ${pkg ?? "a package"}.`;
+ default:
+ return isProvider
+ ? `${contract.repo} declares this ${contractTypeLabel(contract.contract_type)} contract.`
+ : `${contract.repo} consumes this ${contractTypeLabel(contract.contract_type)} contract.`;
+ }
+}
+
+function countPhrase(n: number, one: string, many: string): string {
+ return `${formatNumber(n)} ${n === 1 ? one : many}`;
+}
+
+/** `meta` keys in the order they read, across every contract type. */
+const META_ORDER = [
+ "extraction_layer",
+ "framework",
+ "client",
+ "handler",
+ "method",
+ "path",
+ "table",
+ "verb",
+ "package",
+ "ecosystem",
+ "host",
+ "external",
+ "base_token",
+ "base_stripped",
+];
+
+const META_LABELS: Record<string, string> = {
+ extraction_layer: "Layer",
+ framework: "Framework",
+ client: "Client",
+ handler: "Handler",
+ method: "Method",
+ path: "Path",
+ table: "Table",
+ verb: "Verb",
+ package: "Package",
+ ecosystem: "Ecosystem",
+ host: "Host",
+ external: "External",
+ base_token: "Base token",
+ base_stripped: "Base stripped",
+};
+
+function metaLabel(key: string): string {
+ return META_LABELS[key] ?? key.replace(/_/g, " ");
+}
+
+/**
+ * `meta` as ordered, printable pairs. Keys vary by contract type and an
+ * extractor is free to add one, so anything unrecognised is kept and printed
+ * under its own name rather than dropped.
+ */
+function metaEntries(meta: Record<string, unknown>): [string, string][] {
+ const known = new Set(META_ORDER);
+ const present = (k: string) => meta?.[k] !== undefined && meta[k] !== null;
+ const keys = [
+ ...META_ORDER.filter(present),
+ ...Object.keys(meta ?? {}).filter((k) => !known.has(k) && present(k)),
+ ];
+ return keys.map((k) => [k, String(meta[k])]);
+}
+
+/**
+ * Narrow the loosely-typed `contract_schema` off the wire.
+ *
+ * It arrives as a bare object because the endpoint passes the artifact block
+ * straight through, so the shape is checked here rather than assumed: a
+ * workspace indexed by an older build can carry a block without the arrays.
+ */
+function asSchema(raw: Record<string, unknown> | null): ContractSchema | null {
+ if (!raw) return null;
+ return {
+ source: typeof raw.source === "string" ? raw.source : "unknown",
+ request_fields: Array.isArray(raw.request_fields) ? (raw.request_fields as SchemaField[]) : [],
+ response_fields: Array.isArray(raw.response_fields)
+ ? (raw.response_fields as SchemaField[])
+ : [],
+ };
+}
diff --git a/packages/web/src/app/workspace/contracts/detail/page.tsx b/packages/web/src/app/workspace/contracts/detail/page.tsx
new file mode 100644
index 000000000..4481e472e
--- /dev/null
+++ b/packages/web/src/app/workspace/contracts/detail/page.tsx
@@ -0,0 +1,62 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { ApiClientError } from "@/lib/api/client";
+import { getWorkspace, getWorkspaceContractDetail } from "@/lib/api/workspace";
+import { ContractBody, headingFor } from "./contract-body";
+
+export const revalidate = 30;
+
+type Props = {
+ searchParams: Promise<{ repo?: string; file?: string; id?: string }>;
+};
+
+export async function generateMetadata({ searchParams }: Props): Promise<Metadata> {
+ const { repo, file, id } = await searchParams;
+ if (!repo || !file || !id) return { title: "Contract" };
+ try {
+ const detail = await getWorkspaceContractDetail({ repo, file, id });
+ return { title: `${headingFor(detail.contract)} — Contract` };
+ } catch {
+ return { title: "Contract" };
+ }
+}
+
+/**
+ * One contract.
+ *
+ * A route rather than a modal: the identity is three query parameters, which
+ * makes it the thing somebody pastes to a teammate, and the list page already
+ * keeps its own state in the URL so the two read the same way.
+ *
+ * The workspace payload comes along for one reason: contracts name their repo
+ * by alias, and a file link needs the indexed repo id. A repo that has never
+ * been indexed has no id, which is why the map is passed down whole rather
+ * than resolved into hrefs here — the degrade belongs next to the link.
+ */
+export default async function ContractDetailPage({ searchParams }: Props) {
+ const { repo, file, id } = await searchParams;
+ if (!repo || !file || !id) notFound();
+
+ const [detailResult, ws] = await Promise.allSettled([
+ getWorkspaceContractDetail({ repo, file, id }),
+ getWorkspace(),
+ ]);
+
+ if (detailResult.status === "rejected") {
+ const err = detailResult.reason;
+ // A missing contract and a workspace with no contract data both answer 404,
+ // and both mean this page has nothing to draw. Anything else is a real
+ // failure and belongs on the error boundary, not behind a "not found".
+ if (err instanceof ApiClientError && err.status === 404) notFound();
+ throw err;
+ }
+
+ const repoIds: Record<string, string> = {};
+ if (ws.status === "fulfilled") {
+ for (const r of ws.value.repos) {
+ if (r.repo_id) repoIds[r.alias] = r.repo_id;
+ }
+ }
+
+ return <ContractBody detail={detailResult.value} repoIds={repoIds} />;
+}
diff --git a/packages/web/src/app/workspace/contracts/page.tsx b/packages/web/src/app/workspace/contracts/page.tsx
index 76d066a6f..841a979a5 100644
--- a/packages/web/src/app/workspace/contracts/page.tsx
+++ b/packages/web/src/app/workspace/contracts/page.tsx
@@ -60,7 +60,12 @@ export default async function ContractsPage({ searchParams }: Props) {
const data = ct.status === "fulfilled" ? ct.value : null;
const diagnostics = diag.status === "fulfilled" ? diag.value : null;
- const repos = ws.status === "fulfilled" ? ws.value.repos.map((r) => r.alias) : [];
+ const workspace = ws.status === "fulfilled" ? ws.value : null;
+ const repos = workspace?.repos.map((r) => r.alias) ?? [];
+ // The workspace-wide breakdown, not `data.by_type`: that one is counted
+ // after the filters run, so picking a type would leave the select holding
+ // only the type already picked.
+ const byType = workspace?.contract_summary?.by_type ?? null;
const rows = data?.contracts ?? [];
const links = data?.links ?? [];
@@ -169,7 +174,7 @@ export default async function ContractsPage({ searchParams }: Props) {
<OverviewSection
title="All detected contracts"
description={tableDescription(rows.length, data?.total_contracts ?? 0, filtered)}
- action={<ContractFilters repos={repos} />}
+ action={<ContractFilters repos={repos} byType={byType} />}
>
{rows.length === 0 ? (
<EmptyState