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); }); }); 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); }); 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); }); }); });