diff --git a/scripts/check-registries.ts b/scripts/check-registries.ts index 3bec84f5..5725e58e 100644 --- a/scripts/check-registries.ts +++ b/scripts/check-registries.ts @@ -10,6 +10,8 @@ import { pathToFileURL } from "node:url"; import { canonicalizeRegistryValue, diffRegistrySnapshots, + matchesDeclaredType, + registryRuntimeType, registrySnapshotDigest, validateBreakingEvidence, verifyRegistryBaselineApproval, @@ -140,24 +142,6 @@ async function resolveRegistrySource( return candidates[0] ?? null; } -function runtimeType(value: unknown): string { - if (value === null) return "null"; - if (Array.isArray(value)) return "array"; - if (Number.isInteger(value)) return "integer"; - return typeof value; -} - -function matchesDeclaredType(value: unknown, declaration: string): boolean { - const actual = runtimeType(value); - return declaration - .split("|") - .some( - (candidate) => - candidate === actual || - (candidate === "number" && actual === "integer"), - ); -} - type FieldLookup = Readonly<{ found: boolean; value: unknown; @@ -417,7 +401,7 @@ for (const specification of governance.registries) { ) ) { failures.push( - `${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${runtimeType(lookupField(row, field).value)}`, + `${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${registryRuntimeType(lookupField(row, field).value)}`, ); } } diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index b4fd743f..090869e1 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1211,6 +1211,8 @@ const REGISTRY_COMPATIBILITY_FIXTURE_IDS = [ "field-type-narrowing", "route-path-change", "registry-contract-narrowing", + "nullable-field-cleared", + "registry-contract-extension", "breaking-evidence-required", "tampered-baseline-digest", ] as const; diff --git a/scripts/lib/registry-compatibility.ts b/scripts/lib/registry-compatibility.ts index 9245dcea..aefd7ade 100644 --- a/scripts/lib/registry-compatibility.ts +++ b/scripts/lib/registry-compatibility.ts @@ -80,6 +80,64 @@ function valueType(value: unknown): string { return typeof value; } +/** The governance `fieldTypes` vocabulary: `integer` is its own name. */ +export function registryRuntimeType(value: unknown): string { + if (Number.isInteger(value)) return "integer"; + return valueType(value); +} + +/** `declaration` is a governance field type such as `string|null`. */ +export function matchesDeclaredType(value: unknown, declaration: string): boolean { + const actual = registryRuntimeType(value); + return declaration + .split("|") + .some( + (candidate) => + candidate === actual || + (candidate === "number" && actual === "integer"), + ); +} + +/** + * 0929/07-02. A null on one side and a value on the other is a change inside + * the field's declared type when that type admits both (`string|null`), not a + * change of type: hiding a navigation label is graded like renaming it. + */ +function isDeclaredNullableChange( + before: unknown, + after: unknown, + declaration: unknown, +): boolean { + return ( + typeof declaration === "string" && + (before === null || after === null) && + matchesDeclaredType(before, declaration) && + matchesDeclaredType(after, declaration) + ); +} + +/** + * 0929/07-02. Every field keeps its restriction and every value it allowed: + * rows valid before stay valid. A new, dropped or narrowed restriction is + * still breaking. + */ +function onlyExtendsAllowedValues(before: unknown, after: unknown): boolean { + if (!before || !after || typeof before !== "object" || typeof after !== "object") { + return false; + } + const previous = before as Record; + const current = after as Record; + const fields = Object.keys(previous); + if (fields.length !== Object.keys(current).length) return false; + return fields.every((field) => { + const allowedBefore = previous[field]; + const allowedAfter = current[field]; + if (!Array.isArray(allowedBefore) || !Array.isArray(allowedAfter)) return false; + const kept = new Set(allowedAfter.map((value) => canonicalRegistryJson(value))); + return allowedBefore.every((value) => kept.has(canonicalRegistryJson(value))); + }); +} + function changeId( registryId: string, rowName: string, @@ -154,19 +212,29 @@ export function diffRegistrySnapshots( ) { continue; } + const extendsAllowedValues = + field === "allowedValues" && + beforeHas && + afterHas && + onlyExtendsAllowedValues(beforeValue, afterValue); const kind = !beforeHas ? "contract-field-added" : !afterHas ? "contract-field-removed" - : "contract-field-changed"; - impact = strongestImpact(impact, "breaking"); + : extendsAllowedValues + ? "allowed-values-extended" + : "contract-field-changed"; + const changeImpact: CompatibilityImpact = extendsAllowedValues + ? "additive" + : "breaking"; + impact = strongestImpact(impact, changeImpact); changes.push({ changeId: changeId(registryId, "$contract", field, kind), registryId, rowName: "$contract", field, kind, - impact: "breaking", + impact: changeImpact, before: canonicalizeRegistryValue(beforeValue), after: canonicalizeRegistryValue(afterValue), }); @@ -175,6 +243,10 @@ export function diffRegistrySnapshots( const breakingFields = new Set( (currentContract.breakingFields ?? []) as string[], ); + const fieldTypes = (currentContract.fieldTypes ?? {}) as Record< + string, + unknown + >; const beforeRows = (previous.rows ?? {}) as Record< string, Record @@ -234,7 +306,10 @@ export function diffRegistrySnapshots( } else if (!afterHas) { kind = "field-removed"; changeImpact = "breaking"; - } else if (valueType(beforeValue) !== valueType(afterValue)) { + } else if ( + valueType(beforeValue) !== valueType(afterValue) && + !isDeclaredNullableChange(beforeValue, afterValue, fieldTypes[field]) + ) { kind = "field-type-changed"; changeImpact = "breaking"; } else if ( diff --git a/tests/fixtures/registry/compatibility/semantic-diff.json b/tests/fixtures/registry/compatibility/semantic-diff.json index b81e9cc4..646ab105 100644 --- a/tests/fixtures/registry/compatibility/semantic-diff.json +++ b/tests/fixtures/registry/compatibility/semantic-diff.json @@ -186,6 +186,66 @@ } ] } + }, + { + "id": "nullable-field-cleared", + "expected": "behavior-change", + "before": { + "schemaVersion": 2, + "registries": [ + { + "registryId": "FE-REG-TEST", + "contract": { + "breakingFields": ["path"], + "fieldTypes": { "path": "string", "label": "string|null" } + }, + "rows": { "A": { "path": "/a", "label": "Home" } } + } + ] + }, + "after": { + "schemaVersion": 2, + "registries": [ + { + "registryId": "FE-REG-TEST", + "contract": { + "breakingFields": ["path"], + "fieldTypes": { "path": "string", "label": "string|null" } + }, + "rows": { "A": { "path": "/a", "label": null } } + } + ] + } + }, + { + "id": "registry-contract-extension", + "expected": "additive", + "before": { + "schemaVersion": 2, + "registries": [ + { + "registryId": "FE-REG-TEST", + "contract": { + "breakingFields": ["path"], + "allowedValues": { "kind": ["one"] } + }, + "rows": { "A": { "path": "/a", "kind": "one" } } + } + ] + }, + "after": { + "schemaVersion": 2, + "registries": [ + { + "registryId": "FE-REG-TEST", + "contract": { + "breakingFields": ["path"], + "allowedValues": { "kind": ["one", "two"] } + }, + "rows": { "A": { "path": "/a", "kind": "one" } } + } + ] + } } ], "breakingEvidence": { diff --git a/tests/unit/registry-compatibility.test.ts b/tests/unit/registry-compatibility.test.ts index 8d335f7d..1373851b 100644 --- a/tests/unit/registry-compatibility.test.ts +++ b/tests/unit/registry-compatibility.test.ts @@ -60,6 +60,67 @@ describe("registry compatibility evidence", () => { ).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" } });