import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; import { canonicalRegistryJson, diffRegistrySnapshots, registrySnapshotDigest, validateBreakingEvidence, verifyRegistryBaselineApproval, } from "../../scripts/lib/registry-compatibility.ts"; function snapshot( rows: Readonly>>>, ) { return { schemaVersion: 2, registries: [ { registryId: "FE-REG-TEST", contract: { breakingFields: ["path"] }, rows, }, ], }; } describe("registry compatibility evidence", () => { it("canonicalizes object and primitive-array ordering", () => { expect( canonicalRegistryJson({ second: ["b", "a"], first: { z: 1, a: 2 }, }), ).toBe('{"first":{"a":2,"z":1},"second":["a","b"]}'); }); it("classifies additive, behavioral and breaking actual diffs", () => { expect( diffRegistrySnapshots( snapshot({ A: { path: "/a" } }), snapshot({ A: { path: "/a" }, B: { path: "/b" } }), ).impact, ).toBe("additive"); expect( diffRegistrySnapshots( snapshot({ A: { path: "/a", owner: "one" } }), snapshot({ A: { path: "/a", owner: "two" } }), ).impact, ).toBe("behavior-change"); expect( diffRegistrySnapshots( snapshot({ A: { path: "/a" } }), snapshot({ A: { path: "/moved" } }), ).impact, ).toBe("breaking"); expect( diffRegistrySnapshots( snapshot({ A: { path: "/a" } }), snapshot({}), ).impact, ).toBe("breaking"); }); // 0929/07-02. Changes the governance contract already describes are graded // by it; anything else stays fail-closed. describe("changes the declared contract describes", () => { function registry( contract: Readonly>, rows: Readonly>>>, ) { return { schemaVersion: 2, registries: [{ registryId: "FE-REG-TEST", contract, rows }], }; } const nullable = { breakingFields: ["path", "schema"], fieldTypes: { path: "string", label: "string|null", order: "integer|null", schema: "string|null", }, }; it.each([ ["a label hidden", { label: "Home" }, { label: null }, "behavior-change", "field-changed"], ["a label shown", { label: null }, { label: "Home" }, "behavior-change", "field-changed"], ["an order set", { order: null }, { order: 2 }, "behavior-change", "field-changed"], ["a nullable breaking field set", { schema: null }, { schema: "Params" }, "breaking", "field-changed"], ["a value outside the declared type", { order: null }, { order: "2" }, "breaking", "field-type-changed"], ])("grades %s by the declared field type", (_label, before, after, impact, kind) => { const diff = diffRegistrySnapshots( registry(nullable, { A: { path: "/a", ...before } }), registry(nullable, { A: { path: "/a", ...after } }), ); expect(diff.changes.map((change) => [change.kind, change.impact])).toEqual([ [kind, impact], ]); }); it("keeps a null transition breaking when no field type is declared", () => { expect( diffRegistrySnapshots( registry({ breakingFields: ["path"] }, { A: { path: "/a", label: "Home" } }), registry({ breakingFields: ["path"] }, { A: { path: "/a", label: null } }), ).impact, ).toBe("breaking"); }); it.each([ ["one more allowed value", { kind: ["one"] }, { kind: ["one", "two"] }, "additive"], ["an allowed value removed", { kind: ["one", "two"] }, { kind: ["two", "three"] }, "breaking"], ["a newly restricted field", { kind: ["one"] }, { kind: ["one"], mode: ["a"] }, "breaking"], ["a restriction dropped", { kind: ["one"], mode: ["a"] }, { kind: ["one"] }, "breaking"], ])("grades %s in allowedValues", (_label, before, after, impact) => { const diff = diffRegistrySnapshots( registry({ breakingFields: ["path"], allowedValues: before }, { A: { path: "/a" } }), registry({ breakingFields: ["path"], allowedValues: after }, { A: { path: "/a" } }), ); expect(diff.impact).toBe(impact); }); }); // 1105/07-02. A response schema that starts rejecting unknown keys fails // every response the backend extends with a field, so it is graded like // removing an accepted status. Widening, and a request row the frontend // fills itself, stay behavior-change. The rows are FE-REG-SCHEMA's shape // (src/contracts/schema-registry.ts), not the committed baseline, which // loses the reference rows when the sample is removed. describe("a schema row's unknown-key policy", () => { const contract = { breakingFields: ["schemaId", "boundary", "runtime"] }; function schemas(direction: "REQUEST" | "RESPONSE", unknownFieldPolicy: string) { return { schemaVersion: 2, registries: [ { registryId: "FE-REG-SCHEMA", contract, rows: { Payload: { schemaId: "Payload", boundary: direction === "RESPONSE" ? "api-response" : "api-request", direction, owner: "fixture", runtime: "zod", schemaVersion: 1, unknownFieldPolicy, }, }, }, ], }; } it.each([ ["a response narrowed to REJECT_UNKNOWN", "RESPONSE", "STRIP_UNKNOWN", "REJECT_UNKNOWN", "response-reader-narrowed", "breaking"], ["a response widened to STRIP_UNKNOWN", "RESPONSE", "REJECT_UNKNOWN", "STRIP_UNKNOWN", "field-changed", "behavior-change"], ["a request narrowed to REJECT_UNKNOWN", "REQUEST", "STRIP_UNKNOWN", "REJECT_UNKNOWN", "field-changed", "behavior-change"], ["a request widened to STRIP_UNKNOWN", "REQUEST", "REJECT_UNKNOWN", "STRIP_UNKNOWN", "field-changed", "behavior-change"], ] as const)("grades %s", (_label, direction, before, after, kind, impact) => { const diff = diffRegistrySnapshots( schemas(direction, before), schemas(direction, after), ); expect(diff.changes.map((change) => [change.changeId, change.impact])).toEqual([ [`FE-REG-SCHEMA:Payload:unknownFieldPolicy:${kind}`, impact], ]); expect(diff.impact).toBe(impact); }); it("asks for evidence when a response row is narrowed", () => { const diff = diffRegistrySnapshots( schemas("RESPONSE", "STRIP_UNKNOWN"), schemas("RESPONSE", "REJECT_UNKNOWN"), ); expect( validateBreakingEvidence(diff, { schemaVersion: 1, changes: [] }).failures, ).toEqual([ "breaking change missing evidence: FE-REG-SCHEMA:Payload:unknownFieldPolicy:response-reader-narrowed", ]); }); }); // 1101/16-01 (decision 1). Every feature with server state adds a topic, so // adding one must not need a new baseline. The committed baseline is used // as it stands: after the sample's removal its graph may be empty. describe("the invalidation graph in the committed baseline", () => { type Graph = { topics: unknown[]; namespaces: unknown[]; edges: unknown[] }; type Snapshot = { registries: Array<{ registryId: string; rows: Record }>; }; const baseline = JSON.parse( readFileSync("config/contracts/registry-baseline.json", "utf8"), ) as Snapshot; const namespace = { namespaceId: "added-namespace", namespaceVersion: 1 }; const topicId = "qinv.01k9zaddedtopic000000000"; function withGraph(snapshot: Snapshot, edit: (graph: Graph) => void): Snapshot { const copy = structuredClone(snapshot); const graph = copy.registries.find( ({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION", )?.rows["invalidation-graph"]; if (!graph) throw new Error("baseline has no invalidation graph"); edit(graph); return copy; } const extended = withGraph(baseline, (graph) => { graph.topics.push(topicId); graph.namespaces.push(namespace); graph.edges.push({ topicId, namespace }); }); it("grades a topic, namespace and edge added to the graph as additive", () => { const diff = diffRegistrySnapshots(baseline, extended); expect(diff.changes.map(({ field, impact }) => [field, impact])).toEqual([ ["edges", "additive"], ["namespaces", "additive"], ["topics", "additive"], ]); expect(diff.impact).toBe("additive"); }); it.each([ ["a topic removed", (graph: Graph) => graph.topics.splice(graph.topics.indexOf(topicId), 1)], ["an edge removed", (graph: Graph) => graph.edges.pop()], [ "a namespace version changed", (graph: Graph) => { graph.namespaces[graph.namespaces.length - 1] = { ...namespace, namespaceVersion: 2 }; }, ], [ "an edge moved to another topic", (graph: Graph) => { graph.edges[graph.edges.length - 1] = { topicId: "qinv.01k9zothertopic000000000", namespace }; }, ], ])("keeps %s breaking", (_label, edit) => { expect(diffRegistrySnapshots(extended, withGraph(extended, edit)).impact).toBe("breaking"); }); }); it("verifies the approved digest and complete breaking evidence", () => { const before = snapshot({ A: { path: "/before" } }); const after = snapshot({ A: { path: "/after" } }); const digest = registrySnapshotDigest(before); expect( verifyRegistryBaselineApproval(before, { schemaVersion: 1, snapshotDigest: digest, owner: "platform", approvedAt: "2026-07-26T00:00:00.000Z", }).passed, ).toBe(true); expect( verifyRegistryBaselineApproval(before, { schemaVersion: 1, snapshotDigest: "tampered", owner: "platform", approvedAt: "2026-07-26T00:00:00.000Z", }).passed, ).toBe(false); const diff = diffRegistrySnapshots(before, after); expect(validateBreakingEvidence(diff, { changes: [] }).passed).toBe(false); const changeId = diff.changes[0]?.changeId; expect( validateBreakingEvidence(diff, { changes: [ { changeId, after: "/after", versionBump: "2", migration: "dual-read", compatibilityWindow: "one release", rollback: "restore previous registry snapshot", owner: "platform", }, ], }).passed, ).toBe(true); }); // 0929/07-01. Evidence is for one value, not for every later change of the // same row and field. describe("evidence bound to the value it explains", () => { const evidence = (extra: Readonly>) => ({ changes: [ { changeId: "FE-REG-TEST:A:path:field-changed", versionBump: "2", migration: "dual-read", compatibilityWindow: "one release", rollback: "restore previous registry snapshot", owner: "platform", ...extra, }, ], }); const moved = diffRegistrySnapshots( snapshot({ A: { path: "/a" } }), snapshot({ A: { path: "/entries" } }), ); it("rejects evidence written for another value of the same field", () => { expect(validateBreakingEvidence(moved, evidence({ after: "/items" })).failures).toEqual([ 'breaking change FE-REG-TEST:A:path:field-changed evidence explains after="/items", the change is after="/entries"', ]); }); it("requires the explained value", () => { expect(validateBreakingEvidence(moved, evidence({})).failures).toEqual([ "breaking change FE-REG-TEST:A:path:field-changed evidence needs after (the canonical JSON value it explains)", ]); }); it("compares canonical values, so key and primitive order do not matter", () => { const reordered = diffRegistrySnapshots( snapshot({ A: { path: { b: ["y", "x"], a: 1 } } }), snapshot({ A: { path: { a: 2, b: ["x", "y"] } } }), ); expect( validateBreakingEvidence(reordered, evidence({ after: { b: ["y", "x"], a: 2 } })).passed, ).toBe(true); }); // 0929/07-01 (2). A row that explains no breaking change of the current // diff fails the gate, and the message names every such row. it("fails on evidence rows that explain no breaking change of the current diff", () => { const diff = diffRegistrySnapshots( snapshot({ A: { path: "/a", owner: "one" } }), snapshot({ A: { path: "/entries", owner: "two" } }), ); const row = (changeId: string, after?: string) => ({ ...evidence(after === undefined ? {} : { after }).changes[0], changeId, }); expect( validateBreakingEvidence(diff, { changes: [ row("FE-REG-TEST:A:path:field-changed", "/entries"), row("FE-REG-TEST:B:*:removed"), row("FE-REG-TEST:A:owner:field-changed", "two"), ], }).failures, ).toEqual([ "stale breaking evidence FE-REG-TEST:B:*:removed: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)", "stale breaking evidence FE-REG-TEST:A:owner:field-changed: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)", ]); }); it("needs no value for a removal", () => { const removed = diffRegistrySnapshots( snapshot({ A: { path: "/a" } }), snapshot({}), ); expect( validateBreakingEvidence(removed, { changes: [{ ...evidence({}).changes[0], changeId: "FE-REG-TEST:A:*:removed" }], }).passed, ).toBe(true); }); }); });