문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.
고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
needs after", 다르면 "evidence explains after=..., the change is
after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
registry-governance tamper 사례)에 after를 넣었다.
버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
하지 않았다.
위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
적어야 한다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
("rejects evidence written for another value", "requires the explained
value": expected [] to deeply equal [...]). X3 변이로 check-registries
"11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
after=\"/examples/reference-resources/items/:resourceId\", the change is
after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
"11 registries PASS". registry-compatibility·registry-governance·
release-artifacts·second-api-feature-registries 53/53 통과.
compatibility fixtures 11 PASS. verify-documentation-readiness
PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
221 lines
7.5 KiB
TypeScript
221 lines
7.5 KiB
TypeScript
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);
|
|
});
|
|
});
|
|
|
|
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);
|
|
});
|
|
|
|
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);
|
|
});
|
|
});
|
|
});
|