Files
clean-architecture-frontend…/tests/unit/registry-compatibility.test.ts
T
DongHyeonka 3b62ccd5db fix(registry): 응답 스키마 행을 REJECT_UNKNOWN으로 좁히면 breaking으로 본다
문제: 응답 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
2026-11-05 22:10:05 +09:00

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