문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의 `unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면 check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03 수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에 필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서 FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다. 고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로 바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향 (REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은 그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지 증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두 기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다. 리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다. 위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘 (src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도 고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를 REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿 스냅샷은 기준선과 같아 결과는 none 그대로다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts 리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를 다시 적용하면 check:registries가 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy: response-reader-narrowed`로 실패해야 한다. Refs: 1105/07-02
366 lines
14 KiB
TypeScript
366 lines
14 KiB
TypeScript
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<Record<string, Readonly<Record<string, unknown>>>>,
|
|
) {
|
|
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<Record<string, unknown>>,
|
|
rows: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
|
|
) {
|
|
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<string, Graph> }>;
|
|
};
|
|
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<Record<string, unknown>>) => ({
|
|
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);
|
|
});
|
|
});
|
|
});
|