Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(workspace): 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.py
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.json
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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<Metadat
if (!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.tsx
index 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 && (
<OverviewSection
title="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.py
index 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)