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): breaking changes on the contracts page and a contract drawer (#2116)
Raghav Chamadiya08bae55d3f93
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/workspace.py b/packages/cli/src/repowise/cli/commands/update_cmd/workspace.pyindex 74ef4548e..fc9aa7fb4 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/workspace.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/workspace.py@@ -265,6 +265,9 @@ def _workspace_update()+_BREAKING_DETAIL_LINES = 3++def _print_breaking_changes(ws_root: Path, started_at: datetime) -> None:"""One line naming the contracts this update broke, if any.@@ -309,6 +312,19 @@ def _print_breaking_changes(ws_root: Path, started_at: datetime) -> None:+ (f", plus {others} non-breaking" if others else "")+ ". [dim]repowise workspace check[/dim]")+ # Name a few of them, so the count is actionable without a second command.+ # Capped: this runs at the end of an update, and `workspace check` is the+ # place that lists every one.+ for change in gating[:_BREAKING_DETAIL_LINES]:+ hit = sorted(+ {ic.repo for ic in change.impacted_consumers if ic.repo != change.provider_repo}+ )+ console.print(+ f" [dim]{escape(change.contract_id)}[/dim] "+ f"{escape(change.provider_repo)} -> {escape(', '.join(hit))}"+ )+ if len(gating) > _BREAKING_DETAIL_LINES:+ console.print(f" [dim]and {len(gating) - _BREAKING_DETAIL_LINES} more[/dim]")def _workspace_docs_update(diff --git a/packages/ui/__tests__/workspace/breaking-changes-view.test.tsx b/packages/ui/__tests__/workspace/breaking-changes-view.test.tsxnew file mode 100644index 000000000..4662202af--- /dev/null+++ b/packages/ui/__tests__/workspace/breaking-changes-view.test.tsx@@ -0,0 +1,187 @@+import { describe, it, expect, vi } from "vitest";+import { render, screen, fireEvent } from "@testing-library/react";+import type { BreakingChange, BreakingChangeReport } from "@repowise-dev/types";+import { BreakingChangesView } from "../../src/workspace/breaking-changes-view.js";+import { SystemMapBreakingPanel } from "../../src/workspace/system-map/system-map-breaking-panel.js";++function change(over: Partial<BreakingChange> = {}): BreakingChange {+ return {+ kind: "removed_endpoint",+ severity: "breaking",+ contract_id: "http::GET::/users",+ contract_type: "http",+ provider_repo: "api",+ provider_file: "routes.py",+ provider_symbol: "handler",+ provider_symbol_id: "routes.py::handler",+ provider_service: null,+ provider_node_id: "api",+ detail: "http::GET::/users was removed",+ impacted_consumers: [+ {+ repo: "web",+ service: null,+ node_id: "web",+ file: "client.ts",+ symbol: "fetchUser",+ symbol_id: "client.ts::fetchUser",+ match_type: "exact",+ confidence: 0.9,+ },+ ],+ ...over,+ };+}++function report(+ changes: BreakingChange[],+ over: Partial<BreakingChangeReport> = {},+): BreakingChangeReport {+ return {+ version: 1,+ generated_at: "2026-09-04T00:00:00Z",+ changes,+ total: changes.length,+ breaking_count: changes.filter((c) => c.severity === "breaking").length,+ warning_count: changes.filter((c) => c.severity === "warning").length,+ impacted_repos: ["web"],+ impacted_services: ["web"],+ total_impacted_consumers: changes.length,+ ...over,+ };+}++const links = {+ symbolHref: (repo: string, symbolId: string) =>+ `/repos/${repo}/symbols/${encodeURIComponent(symbolId)}`,+ fileHref: (repo: string, file: string) => `/repos/${repo}/files/${file}`,+};++describe("BreakingChangesView", () => {+ it("separates a report that never ran from one with no changes", () => {+ const { unmount } = render(<BreakingChangesView report={null} />);+ expect(screen.getByText(/has not run/i)).toBeInTheDocument();+ unmount();++ const noTimestamp = render(+ <BreakingChangesView report={report([], { generated_at: null })} />,+ );+ expect(screen.getByText(/has not run/i)).toBeInTheDocument();+ noTimestamp.unmount();++ render(<BreakingChangesView report={report([])} />);+ expect(screen.getByText(/no breaking changes/i)).toBeInTheDocument();+ });++ it("says it is still checking while loading", () => {+ render(<BreakingChangesView report={null} loading />);+ expect(screen.getByText(/checking the latest update/i)).toBeInTheDocument();+ });++ it("summarises the counts and the impacted repos", () => {+ render(<BreakingChangesView report={report([change()])} />);+ expect(screen.getByText(/1 breaking, 0 warnings across 1 repo/i)).toBeInTheDocument();+ });++ it("links the provider symbol and the consumer symbol when hrefs are supplied", () => {+ render(<BreakingChangesView report={report([change()])} links={links} />);++ const provider = screen.getByText("routes.py");+ expect(provider.tagName).toBe("A");+ expect(provider).toHaveAttribute(+ "href",+ "/repos/api/symbols/routes.py%3A%3Ahandler",+ );++ const consumer = screen.getByText(/client\.ts/);+ expect(consumer.tagName).toBe("A");+ expect(consumer).toHaveAttribute(+ "href",+ "/repos/web/symbols/client.ts%3A%3AfetchUser",+ );+ });++ it("falls back to the file route when a side has no symbol id", () => {+ const c = change({+ provider_symbol_id: null,+ impacted_consumers: [+ {+ repo: "web",+ service: null,+ node_id: "web",+ file: "client.ts",+ symbol: "fetchUser",+ symbol_id: null,+ match_type: "exact",+ confidence: 0.9,+ },+ ],+ });+ render(<BreakingChangesView report={report([c])} links={links} />);+ expect(screen.getByText("routes.py")).toHaveAttribute("href", "/repos/api/files/routes.py");+ expect(screen.getByText(/client\.ts/)).toHaveAttribute("href", "/repos/web/files/client.ts");+ });++ it("renders plain text when no href builders are supplied", () => {+ const { container } = render(<BreakingChangesView report={report([change()])} />);+ expect(container.querySelectorAll("a")).toHaveLength(0);+ expect(screen.getByText(/routes\.py/)).toBeInTheDocument();+ expect(screen.getByText(/client\.ts/)).toBeInTheDocument();+ });++ it("leaves a side unlinked when the host cannot route it", () => {+ const { container } = render(+ <BreakingChangesView+ report={report([change()])}+ links={{ symbolHref: () => null, fileHref: () => null }}+ />,+ );+ expect(container.querySelectorAll("a")).toHaveLength(0);+ expect(screen.getByText(/routes\.py/)).toBeInTheDocument();+ });++ it("sorts breaking before warning whatever order the report holds", () => {+ const warning = change({+ severity: "warning",+ contract_id: "http::GET::/orders",+ kind: "field_type_changed",+ detail: "orders response field changed type",+ });+ const { container } = render(+ <BreakingChangesView report={report([warning, change()])} />,+ );+ const ids = Array.from(container.querySelectorAll("button"))+ .map((b) => b.textContent ?? "")+ .filter((t) => t.startsWith("http::"));+ expect(ids).toEqual(["http::GET::/users", "http::GET::/orders"]);+ });++ it("hands the contract back to the host when its id is clicked", () => {+ const onSelectContract = vi.fn();+ render(+ <BreakingChangesView report={report([change()])} onSelectContract={onSelectContract} />,+ );+ fireEvent.click(screen.getByText("http::GET::/users"));+ expect(onSelectContract).toHaveBeenCalledWith("http::GET::/users", expect.anything());+ });+});++describe("SystemMapBreakingPanel through the shared row", () => {+ it("keeps both code sides as node-selecting buttons, not links", () => {+ const onSelectNode = vi.fn();+ const { container } = render(+ <SystemMapBreakingPanel+ report={report([change()])}+ onSelectNode={onSelectNode}+ onClear={() => {}}+ />,+ );+ expect(container.querySelectorAll("a")).toHaveLength(0);++ fireEvent.click(screen.getByText("http::GET::/users"));+ expect(onSelectNode).toHaveBeenCalledWith("api");++ fireEvent.click(screen.getByText(/client\.ts/));+ expect(onSelectNode).toHaveBeenCalledWith("web");+ });+});diff --git a/packages/ui/__tests__/workspace/contract-drawer.test.tsx b/packages/ui/__tests__/workspace/contract-drawer.test.tsxnew file mode 100644index 000000000..80be5e1a9--- /dev/null+++ b/packages/ui/__tests__/workspace/contract-drawer.test.tsx@@ -0,0 +1,149 @@+import { describe, it, expect, vi } from "vitest";+import { render, screen, fireEvent } from "@testing-library/react";+import type { WorkspaceContractLinkEntry } from "@repowise-dev/types/workspace";+import { ContractDrawer } from "../../src/workspace/contract-drawer.js";+import { linksForContract, type ContractEntry } from "../../src/workspace/contract-facts.js";++function contract(overrides: Partial<ContractEntry> = {}): ContractEntry {+ return {+ contract_id: "http::GET::/users/{id}",+ contract_type: "http",+ role: "provider",+ repo: "users-api",+ file_path: "src/routes/users.ts",+ symbol_name: "fastapi::get_user",+ confidence: 0.92,+ service: "users",+ line: 42,+ symbol_id: "src/routes/users.ts::get_user",+ meta: { method: "GET", path: "/users/{id}", framework: "fastapi" },+ ...overrides,+ };+}++function link(overrides: Partial<WorkspaceContractLinkEntry> = {}): WorkspaceContractLinkEntry {+ return {+ contract_id: "http::GET::/users/{id}",+ contract_type: "http",+ match_type: "exact",+ confidence: 0.8,+ provider_repo: "users-api",+ provider_file: "src/routes/users.ts",+ provider_symbol: "get_user",+ consumer_repo: "web-app",+ consumer_file: "src/api/users-client.ts",+ consumer_symbol: "fetchUser",+ provider_service: "users",+ consumer_service: "web",+ provider_symbol_id: null,+ consumer_symbol_id: "src/api/users-client.ts::fetchUser",+ ...overrides,+ };+}++describe("ContractDrawer", () => {+ it("renders the contract identity, role, location and confidence", () => {+ render(+ <ContractDrawer+ contract={contract()}+ open+ onOpenChange={() => {}}+ fullPageHref="/workspace/contracts/detail?id=x"+ />,+ );+ expect(screen.getByText("GET /users/{id}")).toBeInTheDocument();+ expect(screen.getByText("http::GET::/users/{id}")).toBeInTheDocument();+ // Type and role share the eyebrow line, so they are read off it together.+ expect(screen.getByText(/HTTP contract/).textContent).toContain("Provider");+ expect(screen.getByText("users-api")).toBeInTheDocument();+ expect(screen.getByText("src/routes/users.ts")).toBeInTheDocument();+ expect(screen.getByText("line 42")).toBeInTheDocument();+ expect(screen.getByText("92%")).toBeInTheDocument();+ expect(screen.getByText("fastapi")).toBeInTheDocument();+ });++ it("links the file and the counterpart symbol with the supplied hrefs", () => {+ const c = contract();+ const links = [link()];+ render(+ <ContractDrawer+ contract={c}+ open+ onOpenChange={() => {}}+ links={linksForContract(c, links)}+ codeLinks={{+ fileHref: (repo, file) => `/repos/${repo}/files/${file}`,+ symbolHref: (repo, symbolId) => `/repos/${repo}/symbols/${symbolId}`,+ }}+ fullPageHref="/workspace/contracts/detail?id=x"+ />,+ );+ expect(screen.getByText("src/routes/users.ts").closest("a")).toHaveAttribute(+ "href",+ "/repos/users-api/files/src/routes/users.ts",+ );+ // The consumer bound to a symbol id, so its link goes to the symbol page.+ expect(screen.getByText("src/api/users-client.ts").closest("a")).toHaveAttribute(+ "href",+ "/repos/web-app/symbols/src/api/users-client.ts::fetchUser",+ );+ expect(screen.getByText("web-app")).toBeInTheDocument();+ expect(screen.getByText("fetchUser")).toBeInTheDocument();+ expect(screen.getByRole("link", { name: "Open full page" })).toHaveAttribute(+ "href",+ "/workspace/contracts/detail?id=x",+ );+ });++ it("renders schema fields when a reader recovered them", () => {+ render(+ <ContractDrawer+ contract={contract()}+ open+ onOpenChange={() => {}}+ schema={{+ source: "signature",+ request_fields: [{ name: "user_id", type: "str", required: true }],+ response_fields: [],+ }}+ />,+ );+ expect(screen.getByText("Request")).toBeInTheDocument();+ expect(screen.getByText("user_id")).toBeInTheDocument();+ expect(screen.getByText("str")).toBeInTheDocument();+ expect(screen.getByText("Required")).toBeInTheDocument();+ });++ it("says nothing resolves when the contract has no links", () => {+ render(<ContractDrawer contract={contract()} open onOpenChange={() => {}} links={[]} />);+ expect(screen.getByText("Callers")).toBeInTheDocument();+ expect(screen.getByText(/nothing in this workspace resolves/i)).toBeInTheDocument();+ });++ it("fires the close callback from the close button", () => {+ const onOpenChange = vi.fn();+ render(<ContractDrawer contract={contract()} open onOpenChange={onOpenChange} />);+ fireEvent.click(screen.getByRole("button", { name: "Close contract" }));+ expect(onOpenChange).toHaveBeenCalledWith(false);+ });+});++describe("linksForContract", () => {+ it("keeps only the links whose matching side is this declaration", () => {+ const c = contract();+ const mine = link();+ const otherFile = link({ provider_file: "src/routes/legacy.ts" });+ const otherId = link({ contract_id: "http::POST::/users" });+ expect(linksForContract(c, [mine, otherFile, otherId])).toEqual([mine]);+ });++ it("matches on the consumer side for a consumer contract", () => {+ const c = contract({+ role: "consumer",+ repo: "web-app",+ file_path: "src/api/users-client.ts",+ });+ const mine = link();+ expect(linksForContract(c, [mine])).toEqual([mine]);+ });+});diff --git a/packages/ui/package.json b/packages/ui/package.jsonindex 586d4739d..c8d53c681 100644--- a/packages/ui/package.json+++ b/packages/ui/package.json@@ -70,6 +70,8 @@"./overview": "./src/overview/index.ts","./overview/*": "./src/overview/*.tsx","./workspace": "./src/workspace/index.ts",+ "./workspace/contract-facts": "./src/workspace/contract-facts.ts",+ "./workspace/contract-type-label": "./src/workspace/contract-type-label.ts","./workspace/system-map": "./src/workspace/system-map/index.ts","./workspace/dsm": "./src/workspace/dsm/index.ts","./workspace/*": "./src/workspace/*.tsx",diff --git a/packages/ui/src/workspace/breaking-change-row.tsx b/packages/ui/src/workspace/breaking-change-row.tsxnew file mode 100644index 000000000..d70e67de0--- /dev/null+++ b/packages/ui/src/workspace/breaking-change-row.tsx@@ -0,0 +1,185 @@+"use client";++/**+ * One breaking change, rendered the same way wherever it appears: the System+ * Map rail and the contracts page both draw this row rather than each keeping+ * their own copy.+ *+ * The row is pure presentation. It knows a change carries a provider symbol and+ * a consumer symbol, but not how this application routes to code, so the host+ * passes href builders in. With none supplied the row renders exactly the plain+ * text it always did, which is what the map rail wants.+ */++import type { BreakingChange, BreakingChangeConsumer, BreakingChangeReport } from "@repowise-dev/types";+import { RailChip } from "./system-map/system-map-rail";++/**+ * How the host turns a change's code references into links. `repo` is the+ * workspace alias on the change; the host owns the alias-to-repo-id map and the+ * route shape. Returning null means "not routable", and the row falls back to+ * plain text rather than a dead link.+ */+export interface BreakingChangeLinks {+ symbolHref?: (repo: string, symbolId: string) => string | null;+ fileHref?: (repo: string, file: string) => string | null;+}++export interface BreakingChangeRowProps {+ change: BreakingChange;+ /** Focus a provider/consumer service on the map. */+ onSelectNode?: (id: string) => void;+ /** Open the contract itself. Takes precedence over `onSelectNode` on the contract id. */+ onSelectContract?: (contractId: string, change: BreakingChange) => void;+ links?: BreakingChangeLinks;+}++export function severityColor(severity: string): string {+ return severity === "breaking" ? "var(--color-risk-high)" : "var(--color-warning)";+}++/** Breaking first, warnings after; otherwise the report's own order is kept. */+export function sortChangesBySeverity(changes: BreakingChange[]): BreakingChange[] {+ return [...changes].sort((a, b) =>+ a.severity === b.severity ? 0 : a.severity === "breaking" ? -1 : 1,+ );+}++/** The one-line count both surfaces show above the rows. */+export function breakingChangeSummary(report: BreakingChangeReport): string {+ const repos = report.impacted_repos.length;+ return `${report.breaking_count} breaking, ${report.warning_count} ${+ report.warning_count === 1 ? "warning" : "warnings"+ } across ${repos} ${repos === 1 ? "repo" : "repos"}`;+}++/** Stable key for a change inside a report. */+export function breakingChangeKey(change: BreakingChange): string {+ return `${change.contract_id}:${change.kind}:${change.field_name ?? ""}`;+}++/** Prefer the symbol page, fall back to the file page, then to plain text. */+function codeHref(+ links: BreakingChangeLinks | undefined,+ repo: string,+ symbolId: string | null | undefined,+ file: string,+): string | undefined {+ if (symbolId && links?.symbolHref) {+ const href = links.symbolHref(repo, symbolId);+ if (href) return href;+ }+ if (links?.fileHref) return links.fileHref(repo, file) ?? undefined;+ return undefined;+}++export function BreakingChangeRow({+ change,+ onSelectNode,+ onSelectContract,+ links,+}: BreakingChangeRowProps) {+ const color = severityColor(change.severity);+ const providerHref = codeHref(links, change.provider_repo, change.provider_symbol_id, change.provider_file);+ const onContract = onSelectContract+ ? () => onSelectContract(change.contract_id, change)+ : onSelectNode+ ? () => onSelectNode(change.provider_node_id)+ : undefined;++ return (+ <div className="border-b border-[var(--color-border-subtle)] px-3 py-2">+ <div className="flex items-center gap-1.5">+ <RailChip color={color}>{change.severity}</RailChip>+ <button+ type="button"+ onClick={onContract}+ disabled={!onContract}+ title={`Provider: ${change.provider_repo} · ${change.provider_file}`}+ className={`min-w-0 flex-1 truncate text-left font-semibold text-[var(--color-text-primary)] ${+ onContract ? "cursor-pointer hover:underline" : "cursor-default"+ }`}+ >+ {change.contract_id}+ </button>+ </div>+ <div className="mt-[3px] text-[var(--color-text-secondary)]">{change.detail}</div>+ <div className="mt-0.5 text-[10px] text-[var(--color-text-tertiary)]">+ {change.provider_repo} ·{" "}+ {providerHref ? (+ <a+ href={providerHref}+ title={change.provider_symbol_id ?? change.provider_file}+ className="cursor-pointer hover:underline"+ >+ {change.provider_file}+ </a>+ ) : (+ change.provider_file+ )}+ </div>+ {change.impacted_consumers.length > 0 && (+ <div className="mt-1.5">+ <div className="text-[10px] font-bold text-[var(--color-text-tertiary)]">+ {change.impacted_consumers.length === 1+ ? "Endangers 1 consumer"+ : `Endangers ${change.impacted_consumers.length} consumers`}+ </div>+ {change.impacted_consumers.map((c) => (+ <ConsumerLine+ key={`${c.node_id}:${c.file}`}+ consumer={c}+ {...(onSelectNode ? { onSelectNode } : {})}+ {...(links ? { links } : {})}+ />+ ))}+ </div>+ )}+ </div>+ );+}++/**+ * A link wins over the node-selection button when the host supplied one: an+ * anchor cannot sit inside a button, and code is the more useful destination+ * when there is no map to focus.+ */+function ConsumerLine({+ consumer,+ onSelectNode,+ links,+}: {+ consumer: BreakingChangeConsumer;+ onSelectNode?: (id: string) => void;+ links?: BreakingChangeLinks;+}) {+ const href = codeHref(links, consumer.repo, consumer.symbol_id, consumer.file);+ const className = `block w-full truncate py-0.5 pl-2 text-left text-[11px] text-[var(--color-text-secondary)] ${+ href || onSelectNode ? "cursor-pointer hover:underline" : "cursor-default"+ }`;+ const title = `Consumer: ${consumer.repo} · ${consumer.file}`;+ const body = (+ <>+ <span className="text-[var(--color-text-primary)]">{consumer.repo}</span> · {consumer.file}+ </>+ );++ if (href) {+ return (+ <a href={href} title={title} className={className}>+ {body}+ </a>+ );+ }+ return (+ <button+ type="button"+ onClick={() => onSelectNode?.(consumer.node_id)}+ disabled={!onSelectNode}+ title={title}+ className={className}+ >+ {body}+ </button>+ );+}diff --git a/packages/ui/src/workspace/breaking-changes-view.tsx b/packages/ui/src/workspace/breaking-changes-view.tsxnew file mode 100644index 000000000..20c082cd0--- /dev/null+++ b/packages/ui/src/workspace/breaking-changes-view.tsx@@ -0,0 +1,90 @@+"use client";++/**+ * Breaking changes as a page section rather than a map rail: the provider+ * contracts that changed in the last workspace update and the consumers they+ * endanger, breaking first.+ *+ * The empty states are two different facts and are worded as two: a report that+ * never ran is silence, and only a report with a timestamp can say "nothing+ * broke". Reading the first as the second is the failure mode this view exists+ * to avoid.+ */++import { AlertTriangle } from "lucide-react";+import type { BreakingChange, BreakingChangeReport } from "@repowise-dev/types";+import { Card } from "../ui/card";+import { EmptyState } from "../shared/empty-state";+import {+ BreakingChangeRow,+ breakingChangeKey,+ breakingChangeSummary,+ sortChangesBySeverity,+ type BreakingChangeLinks,+} from "./breaking-change-row";++export interface BreakingChangesViewProps {+ /** The latest report, or null while it is loading or unavailable. */+ report: BreakingChangeReport | null;+ loading?: boolean;+ links?: BreakingChangeLinks;+ onSelectContract?: (contractId: string, change: BreakingChange) => void;+ /** Focus a service on a map, when the host has one. */+ onSelectNode?: (nodeId: string) => void;+}++const NOT_RUN_TITLE = "Breaking-change detection has not run";+const NOT_RUN_BODY =+ "Detection compares each update against the previously indexed contracts. Run a workspace update to produce a first result.";++export function BreakingChangesView({+ report,+ loading,+ links,+ onSelectContract,+ onSelectNode,+}: BreakingChangesViewProps) {+ if (loading) {+ return (+ <Card className="px-3 py-4 text-xs text-[var(--color-text-tertiary)]">+ Checking the latest update…+ </Card>+ );+ }++ // No report at all and a report with no timestamp are the same fact: nothing+ // has been compared yet, so an empty change list is not an all-clear.+ if (!report || !report.generated_at) {+ return <EmptyState className="p-6" title={NOT_RUN_TITLE} description={NOT_RUN_BODY} />;+ }++ if (report.changes.length === 0) {+ return (+ <EmptyState+ className="p-6"+ title="No breaking changes in the most recent update"+ description="Every provider contract that changed still matches the consumers linked to it."+ />+ );+ }++ const sorted = sortChangesBySeverity(report.changes);++ return (+ <Card className="overflow-hidden text-xs text-[var(--color-text-secondary)]">+ <div className="flex items-center gap-1.5 border-b border-[var(--color-border-default)] px-3 py-2 text-[11px] text-[var(--color-text-tertiary)]">+ <AlertTriangle size={13} style={{ color: "var(--color-risk-high)" }} />+ <span>{breakingChangeSummary(report)}</span>+ </div>+ {sorted.map((change) => (+ <BreakingChangeRow+ key={breakingChangeKey(change)}+ change={change}+ {...(links ? { links } : {})}+ {...(onSelectContract ? { onSelectContract } : {})}+ {...(onSelectNode ? { onSelectNode } : {})}+ />+ ))}+ </Card>+ );+}diff --git a/packages/ui/src/workspace/contract-drawer.tsx b/packages/ui/src/workspace/contract-drawer.tsxnew file mode 100644index 000000000..88a4ad253--- /dev/null+++ b/packages/ui/src/workspace/contract-drawer.tsx@@ -0,0 +1,375 @@+"use client";++/**+ * One contract, as a right-hand drawer.+ *+ * The contracts table used to navigate away on a row click, which cost the+ * reader their filters and their scroll position to answer a question that+ * fits in a panel. The drawer answers it in place; the route it replaced is+ * still the shareable identity, so "Open full page" is always present and the+ * table keeps a modifier click on the contract id.+ *+ * Presentation only. It knows a contract names a repo, a file and a symbol,+ * but not how the host routes to code, so href builders come in the same shape+ * `BreakingChangeRow` takes them.+ */++import type { ReactNode } from "react";+import type {+ BreakingChange,+ ContractSchema,+ SchemaField,+ WorkspaceContractLinkEntry,+} from "@repowise-dev/types/workspace";++import { Sheet, SheetContent, SheetTitle } from "../ui/sheet";+import {+ BreakingChangeRow,+ breakingChangeKey,+ sortChangesBySeverity,+ type BreakingChangeLinks,+} from "./breaking-change-row";+import { contractTypeLabel } from "./contract-type-label";+import {+ contractHeading,+ contractLede,+ contractMetaEntries,+ contractMetaLabel,+ contractMetaString,+ type ContractEntry,+} from "./contract-facts";++/** `meta` keys the facts list already prints. */+const FACT_META_KEYS = new Set(["method", "path", "framework", "client"]);++export interface ContractDrawerProps {+ contract: ContractEntry | null;+ open: boolean;+ onOpenChange: (open: boolean) => void;+ /** The matched links this contract sits on. Use `linksForContract` to pick them. */+ links?: WorkspaceContractLinkEntry[];+ /** Request and response fields, when a reader recovered them. */+ schema?: ContractSchema | null | undefined;+ /** Changes from the latest report that touch this contract id. */+ breakingChanges?: BreakingChange[];+ /** How the host routes to code. A null return renders plain text. */+ codeLinks?: BreakingChangeLinks | undefined;+ /** The detail route for this contract. */+ fullPageHref?: string | undefined;+}++export function ContractDrawer({+ contract,+ open,+ onOpenChange,+ links = [],+ schema,+ breakingChanges = [],+ codeLinks,+ fullPageHref,+}: ContractDrawerProps) {+ return (+ <Sheet open={open} onOpenChange={onOpenChange}>+ <SheetContent+ side="right"+ closeLabel="Close contract"+ // Wider than the nav sheet this primitive was written for: a request+ // path and a wrapping file path are what set the floor here.+ className="w-full max-w-[620px] sm:w-[92vw]"+ >+ {contract ? (+ <DrawerBody+ contract={contract}+ links={links}+ schema={schema ?? null}+ breakingChanges={breakingChanges}+ codeLinks={codeLinks}+ fullPageHref={fullPageHref}+ />+ ) : (+ <SheetTitle className="sr-only">Contract</SheetTitle>+ )}+ </SheetContent>+ </Sheet>+ );+}++function DrawerBody({+ contract,+ links,+ schema,+ breakingChanges,+ codeLinks,+ fullPageHref,+}: {+ contract: ContractEntry;+ links: WorkspaceContractLinkEntry[];+ schema: ContractSchema | null;+ breakingChanges: BreakingChange[];+ codeLinks?: BreakingChangeLinks | undefined;+ fullPageHref?: string | undefined;+}) {+ const isProvider = contract.role === "provider";+ const meta = contract.meta ?? {};+ const method = contractMetaString(meta, "method");+ const path = contractMetaString(meta, "path");+ const frameworkName = contractMetaString(meta, "framework");+ const client = contractMetaString(meta, "client");+ const fileHref = codeLinks?.fileHref?.(contract.repo, contract.file_path) ?? null;+ // What the facts above already print is dropped here, so the panel does not+ // say "fastapi" twice under two different headings.+ const metaEntries = contractMetaEntries(meta).filter(+ ([key]) => !FACT_META_KEYS.has(key),+ );++ return (+ <>+ <div className="border-b border-[var(--color-border-default)] px-5 py-4 pr-12">+ <div className="text-[11px] text-[var(--color-text-secondary)]">+ {contractTypeLabel(contract.contract_type)} contract+ <span className="mx-2 text-[var(--color-border-hover)]">/</span>+ {isProvider ? "Provider" : "Consumer"}+ </div>+ <SheetTitle className="mt-0.5 break-words font-mono text-[15px] font-semibold text-[var(--color-text-primary)]">+ {contractHeading(contract)}+ </SheetTitle>+ <p className="mt-1.5 text-[12.5px] leading-relaxed text-[var(--color-text-secondary)]">+ {contractLede(contract)}+ </p>+ </div>++ <div className="flex min-h-0 flex-1 flex-col gap-6 overflow-y-auto px-5 py-5">+ <Facts>+ <Fact label="Contract id">+ <Mono>{contract.contract_id}</Mono>+ </Fact>+ {method ? (+ <Fact label="Method">+ <span className="text-xs">{method}</span>+ </Fact>+ ) : null}+ {path ? (+ <Fact label="Path">+ <Mono>{path}</Mono>+ </Fact>+ ) : null}+ <Fact label="Repository">+ <span className="text-xs">{contract.repo}</span>+ </Fact>+ <Fact label="File">+ {fileHref ? (+ <a href={fileHref} className="text-[var(--color-accent-primary)] hover:underline">+ <Mono>{contract.file_path}</Mono>+ </a>+ ) : (+ <Mono>{contract.file_path}</Mono>+ )}+ {contract.line != null ? (+ <span className="ml-2 text-xs tabular-nums text-[var(--color-text-tertiary)]">+ line {contract.line}+ </span>+ ) : null}+ </Fact>+ {contract.service ? (+ <Fact label="Service">+ <span className="text-xs">{contract.service}</span>+ </Fact>+ ) : null}+ {frameworkName ? (+ <Fact label="Framework">+ <span className="text-xs">{frameworkName}</span>+ </Fact>+ ) : client ? (+ <Fact label="Client">+ <span className="text-xs">{client}</span>+ </Fact>+ ) : null}+ <Fact label="Confidence">+ <span className="text-xs tabular-nums">{Math.round(contract.confidence * 100)}%</span>+ </Fact>+ </Facts>++ <Section title={isProvider ? "Callers" : "Served by"}>+ {links.length === 0 ? (+ <p className="text-[12.5px] leading-relaxed text-[var(--color-text-tertiary)]">+ {isProvider+ ? "Nothing in this workspace resolves to this contract. A call from inside the same repository and service is excluded by construction, and a call written in a form extraction could not follow looks the same from here."+ : "This call matched no declaration in the workspace. The full page names the reason recorded for it."}+ </p>+ ) : (+ <ul className="flex flex-col gap-2.5">+ {links.map((link) => (+ <CounterpartRow+ key={`${link.provider_repo}|${link.provider_file}|${link.consumer_repo}|${link.consumer_file}`}+ link={link}+ side={isProvider ? "consumer" : "provider"}+ codeLinks={codeLinks}+ />+ ))}+ </ul>+ )}+ </Section>++ {schema && (schema.request_fields.length > 0 || schema.response_fields.length > 0) ? (+ <Section title="Shape">+ <p className="text-[12.5px] leading-relaxed text-[var(--color-text-tertiary)]">+ Recovered by the {schema.source} reader. Fields are what the declaration names, not+ what any one caller passes.+ </p>+ {schema.request_fields.length > 0 ? (+ <FieldList caption="Request" fields={schema.request_fields} />+ ) : null}+ {schema.response_fields.length > 0 ? (+ <FieldList caption="Response" fields={schema.response_fields} />+ ) : null}+ </Section>+ ) : null}++ {breakingChanges.length > 0 ? (+ <Section title="Breaking changes">+ <div className="overflow-hidden rounded-md border border-[var(--color-border-default)] text-xs text-[var(--color-text-secondary)]">+ {sortChangesBySeverity(breakingChanges).map((change) => (+ <BreakingChangeRow+ key={breakingChangeKey(change)}+ change={change}+ {...(codeLinks ? { links: codeLinks } : {})}+ />+ ))}+ </div>+ </Section>+ ) : null}++ {metaEntries.length > 0 ? (+ <Section title="How it was found">+ <Facts>+ {metaEntries.map(([key, value]) => (+ <Fact key={key} label={contractMetaLabel(key)}>+ <Mono>{value}</Mono>+ </Fact>+ ))}+ </Facts>+ </Section>+ ) : null}+ </div>++ {fullPageHref ? (+ <div className="border-t border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-5 py-3">+ <a+ href={fullPageHref}+ className="text-xs font-medium text-[var(--color-accent-primary)] hover:underline"+ >+ Open full page+ </a>+ </div>+ ) : null}+ </>+ );+}++/** The other side of one matched link: where it lives and what code it is. */+function CounterpartRow({+ link,+ side,+ codeLinks,+}: {+ link: WorkspaceContractLinkEntry;+ side: "provider" | "consumer";+ codeLinks?: BreakingChangeLinks | undefined;+}) {+ 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 symbolId = side === "provider" ? link.provider_symbol_id : link.consumer_symbol_id;+ // The symbol page is the better destination when the side bound to one; the+ // file page is the fallback, and plain text when the repo has no index.+ const href =+ (symbolId ? codeLinks?.symbolHref?.(repo, symbolId) : null) ??+ codeLinks?.fileHref?.(repo, file) ??+ null;++ return (+ <li className="min-w-0">+ <div className="text-xs font-medium text-[var(--color-text-primary)]">{repo}</div>+ {href ? (+ <a href={href} className="text-[var(--color-accent-primary)] hover:underline">+ <Mono>{file}</Mono>+ </a>+ ) : (+ <Mono>{file}</Mono>+ )}+ {symbol ? (+ <div className="mt-0.5 text-[var(--color-text-tertiary)]">+ <Mono>{symbol}</Mono>+ </div>+ ) : null}+ <div className="mt-0.5 text-[11px] text-[var(--color-text-tertiary)]">+ {link.match_type} match ·{" "}+ <span className="tabular-nums">{Math.round(link.confidence * 100)}%</span>+ </div>+ </li>+ );+}++function FieldList({ caption, fields }: { caption: string; fields: SchemaField[] }) {+ return (+ <div>+ <div className="mb-1 text-xs font-medium text-[var(--color-text-secondary)]">{caption}</div>+ <ul className="flex flex-col">+ {fields.map((f, i) => (+ <li+ key={`${f.name}|${f.number ?? i}`}+ className="flex flex-wrap items-baseline gap-x-2 border-t border-[var(--color-border-default)] py-1"+ >+ <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>+ ) : null}+ </span>+ <span className="font-mono text-xs text-[var(--color-text-secondary)] [overflow-wrap:anywhere]">+ {f.type}+ </span>+ <span className="text-[11px] text-[var(--color-text-tertiary)]">+ {f.required ? "Required" : "Optional"}+ </span>+ </li>+ ))}+ </ul>+ </div>+ );+}++function Section({ title, children }: { title: string; children: ReactNode }) {+ return (+ <section className="flex flex-col gap-2">+ <h4 className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ {title}+ </h4>+ {children}+ </section>+ );+}++function Facts({ children }: { children: ReactNode }) {+ return (+ <dl className="m-0 grid grid-cols-1 gap-x-6 gap-y-2 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 panel wide. */}+ <dd className="m-0 min-w-0 text-[var(--color-text-secondary)]">{children}</dd>+ </div>+ );+}++function Mono({ children }: { children: ReactNode }) {+ return <span className="font-mono text-xs [overflow-wrap:anywhere]">{children}</span>;+}diff --git a/packages/ui/src/workspace/contract-facts.ts b/packages/ui/src/workspace/contract-facts.tsnew file mode 100644index 000000000..59cc28c75--- /dev/null+++ b/packages/ui/src/workspace/contract-facts.ts@@ -0,0 +1,173 @@+/**+ * The pure reading of one contract: its name, its one-line summary, the+ * extractor detail it carries and the shape a reader recovered for it.+ *+ * These were local to the detail page and are now shared with the drawer, so+ * the two surfaces name a contract the same way. No `"use client"`: the detail+ * page is a server component and calls straight into them.+ */++import { contractTypeLabel } from "./contract-type-label";+import type { ContractSchema, SchemaField } from "@repowise-dev/types/workspace";++/**+ * One detected contract, as both the workspace list and the detail endpoint+ * return it. Declared structurally here so `packages/ui` stays free of the+ * API client, matching how the link entry is already carried.+ */+export interface ContractEntry {+ contract_id: string;+ contract_type: string;+ role: string;+ repo: string;+ file_path: string;+ symbol_name: string;+ confidence: number;+ service: string | null;+ line: number | null;+ symbol_id: string | null;+ meta: Record<string, unknown>;+}++/** The readable name of a contract, falling back to its id. */+export function contractHeading(contract: ContractEntry): 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. */+export function contractLede(contract: ContractEntry): 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.`;+ }+}++/** `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",+};++export function contractMetaLabel(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.+ */+export function contractMetaEntries(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])]);+}++/** One `meta` value as a string, or null when the extractor recorded none. */+export function contractMetaString(+ meta: Record<string, unknown> | undefined,+ key: string,+): string | null {+ const value = meta?.[key];+ return typeof value === "string" && value !== "" ? value : null;+}++/**+ * 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.+ */+export function asContractSchema(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[])+ : [],+ };+}++/**+ * The matched links this contract sits on, read from a page-wide link list.+ *+ * A link is keyed by both sides, and one contract id can be declared in+ * several files, so the file has to match too: without it a provider would+ * claim the callers of every other declaration sharing its id.+ */+export function linksForContract<+ T extends {+ contract_id: string;+ provider_repo: string;+ provider_file: string;+ consumer_repo: string;+ consumer_file: string;+ },+>(contract: ContractEntry, links: T[]): T[] {+ const isProvider = contract.role === "provider";+ return links.filter(+ (l) =>+ l.contract_id === contract.contract_id &&+ (isProvider+ ? l.provider_repo === contract.repo && l.provider_file === contract.file_path+ : l.consumer_repo === contract.repo && l.consumer_file === contract.file_path),+ );+}diff --git a/packages/ui/src/workspace/contract-type-badge.tsx b/packages/ui/src/workspace/contract-type-badge.tsxindex aa4f745d6..033ab76cc 100644--- a/packages/ui/src/workspace/contract-type-badge.tsx+++ b/packages/ui/src/workspace/contract-type-badge.tsx@@ -1,24 +1,10 @@"use client";-/**- * 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",-};+import { contractTypeLabel } from "./contract-type-label";-/** 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;-}+// Re-exported so client callers that already reach for the label through this+// module keep working; server components must import it from the source.+export { contractTypeLabel };/*** The contract's transport, as a word.diff --git a/packages/ui/src/workspace/contract-type-label.ts b/packages/ui/src/workspace/contract-type-label.tsnew file mode 100644index 000000000..2f620b0d7--- /dev/null+++ b/packages/ui/src/workspace/contract-type-label.ts@@ -0,0 +1,27 @@+/**+ * The contract type's display name.+ *+ * Server-safe on purpose. This lives apart from `contract-type-badge` because+ * that module is a client boundary, and a server component calling into a+ * `"use client"` module throws at render rather than at build.+ */++/**+ * 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;+}diff --git a/packages/ui/src/workspace/index.ts b/packages/ui/src/workspace/index.tsindex c112c0a12..e246b93f2 100644--- a/packages/ui/src/workspace/index.ts+++ b/packages/ui/src/workspace/index.ts@@ -1,4 +1,8 @@+export * from "./breaking-change-row";+export * from "./breaking-changes-view";export * from "./co-change-table";+export * from "./contract-drawer";+export * from "./contract-facts";export * from "./contract-links-table";export * from "./contract-type-badge";export * from "./cross-repo-summary";diff --git a/packages/ui/src/workspace/system-map/system-map-breaking-panel.tsx b/packages/ui/src/workspace/system-map/system-map-breaking-panel.tsxindex c1708b6da..a06a0dd14 100644--- a/packages/ui/src/workspace/system-map/system-map-breaking-panel.tsx+++ b/packages/ui/src/workspace/system-map/system-map-breaking-panel.tsx@@ -6,11 +6,21 @@* endangers, showing both code sides — the provider file that changed and the* consumer file that calls it. Pure presentation: the host owns the fetch and* passes the report in; the at-risk badges ride the map's overlay prop.+ *+ * The rows themselves are `BreakingChangeRow`, shared with the contracts page.+ * The rail passes no href builders, so they stay plain text and every click+ * focuses the map instead.*/import { AlertTriangle } from "lucide-react";-import type { BreakingChange, BreakingChangeReport } from "@repowise-dev/types";-import { RailChip, SystemMapRailPanel } from "./system-map-rail";+import type { BreakingChangeReport } from "@repowise-dev/types";+import {+ BreakingChangeRow,+ breakingChangeKey,+ breakingChangeSummary,+ sortChangesBySeverity,+} from "../breaking-change-row";+import { SystemMapRailPanel } from "./system-map-rail";export interface SystemMapBreakingPanelProps {report: BreakingChangeReport | null;@@ -20,65 +30,6 @@ export interface SystemMapBreakingPanelProps {onClear: () => void;}-function severityColor(severity: string): string {- return severity === "breaking" ? "var(--color-risk-high)" : "var(--color-warning)";-}--function ChangeRow({- change,- onSelectNode,-}: {- change: BreakingChange;- onSelectNode?: (id: string) => void;-}) {- const color = severityColor(change.severity);- return (- <div className="border-b border-[var(--color-border-subtle)] px-3 py-2">- <div className="flex items-center gap-1.5">- <RailChip color={color}>{change.severity}</RailChip>- <button- type="button"- onClick={() => onSelectNode?.(change.provider_node_id)}- disabled={!onSelectNode}- title={`Provider: ${change.provider_repo} · ${change.provider_file}`}- className={`min-w-0 flex-1 truncate text-left font-semibold text-[var(--color-text-primary)] ${- onSelectNode ? "cursor-pointer hover:underline" : "cursor-default"- }`}- >- {change.contract_id}- </button>- </div>- <div className="mt-[3px] text-[var(--color-text-secondary)]">{change.detail}</div>- <div className="mt-0.5 text-[10px] text-[var(--color-text-tertiary)]">- {change.provider_repo} · {change.provider_file}- </div>- {change.impacted_consumers.length > 0 && (- <div className="mt-1.5">- <div className="text-[10px] font-bold text-[var(--color-text-tertiary)]">- {change.impacted_consumers.length === 1- ? "Endangers 1 consumer"- : `Endangers ${change.impacted_consumers.length} consumers`}- </div>- {change.impacted_consumers.map((c) => (- <button- key={`${c.node_id}:${c.file}`}- type="button"- onClick={() => onSelectNode?.(c.node_id)}- disabled={!onSelectNode}- title={`Consumer: ${c.repo} · ${c.file}`}- className={`block w-full truncate py-0.5 pl-2 text-left text-[11px] text-[var(--color-text-secondary)] ${- onSelectNode ? "cursor-pointer hover:underline" : "cursor-default"- }`}- >- <span className="text-[var(--color-text-primary)]">{c.repo}</span> · {c.file}- </button>- ))}- </div>- )}- </div>- );-}-export function SystemMapBreakingPanel({report,loading,@@ -87,14 +38,7 @@ export function SystemMapBreakingPanel({}: SystemMapBreakingPanelProps) {if (!report) return null;- const sorted = [...report.changes].sort((a, b) =>- a.severity === b.severity ? 0 : a.severity === "breaking" ? -1 : 1,- );-- const repos = report.impacted_repos.length;- const summary = `${report.breaking_count} breaking, ${report.warning_count} ${- report.warning_count === 1 ? "warning" : "warnings"- } across ${repos} ${repos === 1 ? "repo" : "repos"}`;+ const sorted = sortChangesBySeverity(report.changes);return (<SystemMapRailPanel@@ -102,7 +46,13 @@ export function SystemMapBreakingPanel({icon={<AlertTriangle size={13} style={{ color: "var(--color-risk-high)" }} />}onClear={onClear}clearLabel="Clear breaking changes"- summary={loading ? "Checking the latest update…" : !report.generated_at ? "Not yet checked" : summary}+ summary={+ loading+ ? "Checking the latest update…"+ : !report.generated_at+ ? "Not yet checked"+ : breakingChangeSummary(report)+ }>{!loading && report.changes.length === 0 && (<div className="p-3 text-[var(--color-text-tertiary)]">@@ -115,8 +65,8 @@ export function SystemMapBreakingPanel({)}{sorted.map((change) => (- <ChangeRow- key={`${change.contract_id}:${change.kind}:${change.field_name ?? ""}`}+ <BreakingChangeRow+ key={breakingChangeKey(change)}change={change}{...(onSelectNode ? { onSelectNode } : {})}/>diff --git a/packages/web/src/app/workspace/contracts/breaking-changes-section.tsx b/packages/web/src/app/workspace/contracts/breaking-changes-section.tsxnew file mode 100644index 000000000..3cc7bd374--- /dev/null+++ b/packages/web/src/app/workspace/contracts/breaking-changes-section.tsx@@ -0,0 +1,59 @@+"use client";++import { useRouter } from "next/navigation";+import { BreakingChangesView } from "@repowise-dev/ui/workspace/breaking-changes-view";+import { fileEntityPath, symbolEntityPath } from "@repowise-dev/ui/shared/entity";+import { useWorkspaceBreakingChanges } from "@/lib/hooks/use-workspace";+import { contractDetailHref } from "./contract-href";++/**+ * The breaking-change report on the contracts page.+ *+ * A client boundary because the report is fetched per view rather than at build+ * time: it is written by the most recent workspace update, and a page cached for+ * 30 seconds would report a stale all-clear.+ *+ * The alias-to-repo-id map comes from the page, which already loads the+ * workspace. A change names a repo by its workspace alias; the per-repo routes+ * are keyed on the indexed repo id, and a repo that was never indexed has none,+ * so those references stay plain text instead of linking into a missing page.+ */+export function BreakingChangesSection({+ repoIds,+}: {+ repoIds: Record<string, string>;+}) {+ const router = useRouter();+ const { data, isLoading } = useWorkspaceBreakingChanges();++ const prefixFor = (repo: string): string | null => {+ const id = repoIds[repo];+ return id ? `/repos/${id}` : null;+ };++ return (+ <BreakingChangesView+ report={data}+ loading={isLoading}+ links={{+ symbolHref: (repo, symbolId) => {+ const prefix = prefixFor(repo);+ return prefix ? symbolEntityPath(prefix, symbolId) : null;+ },+ fileHref: (repo, file) => {+ const prefix = prefixFor(repo);+ return prefix ? fileEntityPath(prefix, file) : null;+ },+ }}+ onSelectContract={(_contractId, change) =>+ router.push(+ contractDetailHref({+ repo: change.provider_repo,+ file_path: change.provider_file,+ contract_id: change.contract_id,+ }),+ )+ }+ />+ );+}diff --git a/packages/web/src/app/workspace/contracts/contracts-table.tsx b/packages/web/src/app/workspace/contracts/contracts-table.tsxindex dbc7828dc..f16c0ebbb 100644--- a/packages/web/src/app/workspace/contracts/contracts-table.tsx+++ b/packages/web/src/app/workspace/contracts/contracts-table.tsx@@ -1,15 +1,19 @@"use client";-import { useRouter } from "next/navigation";+import { useState, type MouseEvent } from "react";import {ResponsiveTable,type ResponsiveColumn,} from "@repowise-dev/ui/shared";+import { fileEntityPath, symbolEntityPath } from "@repowise-dev/ui/shared/entity";import {ContractTypeBadge,RoleBadge,} from "@repowise-dev/ui/workspace/contract-type-badge";-import type { WorkspaceContractEntry } from "@/lib/api/types";+import { ContractDrawer } from "@repowise-dev/ui/workspace/contract-drawer";+import { linksForContract } from "@repowise-dev/ui/workspace/contract-facts";+import type { WorkspaceContractEntry, WorkspaceContractLinkEntry } from "@/lib/api/types";+import { useWorkspaceBreakingChanges } from "@/lib/hooks/use-workspace";import { contractDetailHref } from "./contract-href";type ContractRow = WorkspaceContractEntry & { _key: string };@@ -27,10 +31,23 @@ const CONTRACT_COLUMNS: ResponsiveColumn<ContractRow>[] = [{key: "contract_id",header: "Contract",+ // An anchor, so the detail route keeps its middle-click and its+ // open-in-new-tab. An unmodified click is cancelled and left to bubble to+ // the row, which opens the drawer instead of leaving the page.render: (c) => (- <span className="font-mono text-xs text-[var(--color-text-secondary)] [overflow-wrap:anywhere]">+ <a+ href={contractDetailHref(c)}+ onClick={(e: MouseEvent<HTMLAnchorElement>) => {+ if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {+ e.stopPropagation();+ return;+ }+ e.preventDefault();+ }}+ className="font-mono text-xs text-[var(--color-text-secondary)] [overflow-wrap:anywhere] hover:underline"+ >{c.contract_id}- </span>+ </a>),},{@@ -69,29 +86,73 @@ const CONTRACT_COLUMNS: ResponsiveColumn<ContractRow>[] = [},];-export function ContractsTable({ contracts }: { contracts: WorkspaceContractEntry[] }) {- const router = useRouter();+export function ContractsTable({+ contracts,+ links = [],+ repoIds = {},+}: {+ contracts: WorkspaceContractEntry[];+ /** The page's matched links, narrowed to the open contract by the drawer. */+ links?: WorkspaceContractLinkEntry[];+ /** Repo alias to indexed repo id. A never-indexed repo has no entry. */+ repoIds?: Record<string, string>;+}) {+ const [selected, setSelected] = useState<WorkspaceContractEntry | null>(null);+ // The same report the section above renders, off the same SWR key, so+ // opening a row costs no second request.+ const { data: breaking } = useWorkspaceBreakingChanges();++ const prefixFor = (repo: string): string | null => {+ const id = repoIds[repo];+ return id ? `/repos/${id}` : null;+ };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- // file can call the same endpoint from two places, which is a duplicate- // React key without it.- ...c,- _key: `${c.repo}|${c.file_path}|${c.contract_id}|${c.line ?? ""}`,- }))}- rowKey={(c) => c._key}- caption="All detected contracts"- stacked="md"- bare- />+ <>+ <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) => setSelected(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+ // file can call the same endpoint from two places, which is a duplicate+ // React key without it.+ ...c,+ _key: `${c.repo}|${c.file_path}|${c.contract_id}|${c.line ?? ""}`,+ }))}+ rowKey={(c) => c._key}+ caption="All detected contracts"+ stacked="md"+ bare+ />+ <ContractDrawer+ contract={selected}+ open={selected !== null}+ onOpenChange={(open) => {+ if (!open) setSelected(null);+ }}+ links={selected ? linksForContract(selected, links) : []}+ breakingChanges={+ selected+ ? (breaking?.changes ?? []).filter((c) => c.contract_id === selected.contract_id)+ : []+ }+ codeLinks={{+ symbolHref: (repo, symbolId) => {+ const prefix = prefixFor(repo);+ return prefix ? symbolEntityPath(prefix, symbolId) : null;+ },+ fileHref: (repo, file) => {+ const prefix = prefixFor(repo);+ return prefix ? fileEntityPath(prefix, file) : null;+ },+ }}+ {...(selected ? { fullPageHref: contractDetailHref(selected) } : {})}+ />+ </>);}diff --git a/packages/web/src/app/workspace/contracts/detail/contract-body.tsx b/packages/web/src/app/workspace/contracts/detail/contract-body.tsxindex 06075c250..3eeb1358e 100644--- a/packages/web/src/app/workspace/contracts/detail/contract-body.tsx+++ b/packages/web/src/app/workspace/contracts/detail/contract-body.tsx@@ -6,7 +6,14 @@ import type {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 { contractTypeLabel } from "@repowise-dev/ui/workspace/contract-type-label";+import {+ asContractSchema,+ contractHeading,+ contractLede,+ contractMetaEntries,+ contractMetaLabel,+} from "@repowise-dev/ui/workspace/contract-facts";import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import { formatNumber } from "@repowise-dev/ui/lib/format";@@ -34,7 +41,7 @@ interface Props {export function ContractBody({ detail, repoIds }: Props) {const { contract, links, unmatched_reason: unmatchedReason } = detail;const isProvider = contract.role === "provider";- const schema = asSchema(detail.contract_schema);+ const schema = asContractSchema(detail.contract_schema);return (<div className="mx-auto w-full max-w-[1280px] p-[var(--page-pad)]">@@ -52,10 +59,10 @@ export function ContractBody({ detail, repoIds }: Props) {{isProvider ? "Provider" : "Consumer"}</p><h1 className="text-[2rem] font-semibold leading-tight tracking-tight text-[var(--color-text-primary)] [overflow-wrap:anywhere]">- {headingFor(contract)}+ {contractHeading(contract)}</h1><p className="max-w-[68ch] text-base leading-relaxed text-[var(--color-text-secondary)] [text-wrap:pretty]">- {ledeFor(contract)}+ {contractLede(contract)}</p></header>@@ -111,12 +118,12 @@ export function ContractBody({ detail, repoIds }: Props) {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)}>+ {contractMetaEntries(contract.meta).map(([key, value]) => (+ <Fact key={key} label={contractMetaLabel(key)}><span className="font-mono text-xs [overflow-wrap:anywhere]">{value}</span></Fact>))}- {metaEntries(contract.meta).length === 0 && (+ {contractMetaEntries(contract.meta).length === 0 && (<Fact label="Detail"><span className="text-[var(--color-text-tertiary)]">The extractor recorded none.@@ -549,114 +556,6 @@ function FileRef({// 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.tsxindex 4481e472e..5eb5b7993 100644--- a/packages/web/src/app/workspace/contracts/detail/page.tsx+++ b/packages/web/src/app/workspace/contracts/detail/page.tsx@@ -2,7 +2,8 @@ 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";+import { contractHeading } from "@repowise-dev/ui/workspace/contract-facts";+import { ContractBody } from "./contract-body";export const revalidate = 30;@@ -15,7 +16,7 @@ export async function generateMetadata({ searchParams }: Props): Promise<Metadatif (!repo || !file || !id) return { title: "Contract" };try {const detail = await getWorkspaceContractDetail({ repo, file, id });- return { title: `${headingFor(detail.contract)} — Contract` };+ return { title: `${contractHeading(detail.contract)} — Contract` };} catch {return { title: "Contract" };}diff --git a/packages/web/src/app/workspace/contracts/page.tsx b/packages/web/src/app/workspace/contracts/page.tsxindex 841a979a5..4c773b17e 100644--- a/packages/web/src/app/workspace/contracts/page.tsx+++ b/packages/web/src/app/workspace/contracts/page.tsx@@ -13,6 +13,7 @@ import {getWorkspaceContracts,getWorkspaceDiagnostics,} from "@/lib/api/workspace";+import { BreakingChangesSection } from "./breaking-changes-section";import { ContractFilters } from "./contract-filters";import { ContractsTable } from "./contracts-table";@@ -66,6 +67,13 @@ export default async function ContractsPage({ searchParams }: Props) {// 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;+ // Alias to indexed repo id, so the breaking-change rows can link a symbol or+ // a file into the repo that owns it. Repos that were never indexed have no+ // id and are left out; their references render as plain text.+ const repoIds: Record<string, string> = {};+ for (const repo of workspace?.repos ?? []) {+ if (repo.repo_id) repoIds[repo.alias] = repo.repo_id;+ }const rows = data?.contracts ?? [];const links = data?.links ?? [];@@ -158,6 +166,13 @@ export default async function ContractsPage({ searchParams }: Props) {<StatRibbon stats={ribbon} />+ <OverviewSection+ title="Breaking changes"+ description="Provider contracts that changed in the most recent workspace update, and the consumers linked to them. Breaking first, then warnings."+ >+ <BreakingChangesSection repoIds={repoIds} />+ </OverviewSection>+{links.length > 0 && (<OverviewSectiontitle="Matched links"@@ -187,7 +202,7 @@ export default async function ContractsPage({ searchParams }: Props) {}/>) : (- <ContractsTable contracts={rows} />+ <ContractsTable contracts={rows} links={links} repoIds={repoIds} />)}</OverviewSection>diff --git a/tests/unit/cli/test_update_workspace_breaking_line.py b/tests/unit/cli/test_update_workspace_breaking_line.pyindex 161181443..bdc9bad27 100644--- a/tests/unit/cli/test_update_workspace_breaking_line.py+++ b/tests/unit/cli/test_update_workspace_breaking_line.py@@ -57,6 +57,65 @@ def _save()+def _save_many(root: Path, count: int) -> None:+ """`count` breaking changes, each crossing a repo boundary."""+ save_breaking_change_report(+ BreakingChangeReport(+ generated_at=(STAMP + timedelta(seconds=5)).isoformat(),+ changes=[+ BreakingChange(+ kind="removed_endpoint",+ severity="breaking",+ contract_id=f"http::GET::/thing/{i}",+ contract_type="http",+ provider_repo="api",+ provider_file="src/routes.ts",+ provider_symbol="handler",+ provider_service=None,+ detail=f"http::GET::/thing/{i} was removed",+ impacted_consumers=[+ ImpactedConsumer(+ repo="frontend",+ service=None,+ node_id="frontend",+ file="src/api.ts",+ symbol="getThing",+ match_type="exact",+ confidence=0.9,+ )+ ],+ )+ for i in range(count)+ ],+ ),+ root,+ )+++def test_names_the_first_few_changes_under_the_count(+ tmp_path: Path, capsys: pytest.CaptureFixture[str]+):+ _save_many(tmp_path, 5)+ _print_breaking_changes(tmp_path, STAMP)+ out = capsys.readouterr().out+ assert "5 breaking contract change(s)" in out+ for i in range(3):+ assert f"http::GET::/thing/{i}" in out+ assert "http::GET::/thing/3" not in out+ assert "api -> frontend" in out+ assert "and 2 more" in out+++def test_no_overflow_line_when_every_change_is_named(+ tmp_path: Path, capsys: pytest.CaptureFixture[str]+):+ _save_many(tmp_path, 2)+ _print_breaking_changes(tmp_path, STAMP)+ out = capsys.readouterr().out+ assert "http::GET::/thing/1" in out+ assert "more" not in out++def test_reports_a_report_this_update_wrote(tmp_path: Path, capsys: pytest.CaptureFixture[str]):_save(tmp_path, generated_at=(STAMP + timedelta(seconds=5)).isoformat())_print_breaking_changes(tmp_path, STAMP)