Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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 (<ResponsiveTablecolumns={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 onediff --git a/packages/web/src/app/workspace/contracts/detail/contract-body.tsx b/packages/web/src/app/workspace/contracts/detail/contract-body.tsxnew file mode 100644index 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>←</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.tsxnew file mode 100644index 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.tsxindex 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) {<OverviewSectiontitle="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