From 5e6be9a92fb9f17bb799ffe9ef7e5289fe3a4d5b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:29:29 +0900 Subject: [PATCH] =?UTF-8?q?fix(registry):=20breaking=20=EC=A6=9D=EA=B1=B0?= =?UTF-8?q?=EB=A5=BC=20=EA=B7=B8=20=EC=A6=9D=EA=B1=B0=EA=B0=80=20=EC=84=A4?= =?UTF-8?q?=EB=AA=85=ED=95=98=EB=8A=94=20=EA=B0=92=EC=97=90=20=EB=AC=B6?= =?UTF-8?q?=EB=8A=94=EB=8B=A4=20(0929/07-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- .../contracts/registry-change-evidence.json | 1 + docs/operations/ci-quality-gates.md | 2 +- scripts/lib/registry-compatibility.ts | 16 ++++++ tests/unit/registry-compatibility.test.ts | 57 +++++++++++++++++++ tests/unit/registry-governance.test.ts | 1 + 5 files changed, 76 insertions(+), 1 deletion(-) diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index 10de93e0..2a765018 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -115,6 +115,7 @@ }, { "changeId": "FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed", + "after": "/examples/reference-resources/items/:resourceId", "versionBump": "The reference detail route moves from /examples/reference-resources/:resourceId to /examples/reference-resources/items/:resourceId (maturity review 08-13), so a server id equal to the static segments new or status opens its detail instead of the form or status screen.", "migration": "The only in-app link (reference-resource-page.tsx) builds the new path from the contract route. The reference feature is a sample; downstream features that copied it keep their own paths.", "compatibilityWindow": "None for bookmarked sample detail URLs: an old /examples/reference-resources/ URL no longer matches the detail route; new and status keep opening the form and status screens.", diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 1634e3af..5ddce76f 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -64,7 +64,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경 | 기준선 | 파일 | 갱신 방법 | 검사 위치 | |---|---|---|---| | CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` | -| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가 | `scripts/check-registries.ts`의 baseline 비교 | +| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다 | `scripts/check-registries.ts`의 baseline 비교 | | 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" | | 기능 끄기 설정 | `config/runtime/.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 없음. 남은 키는 조용히 무시된다(리뷰 09-09) | | 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` | diff --git a/scripts/lib/registry-compatibility.ts b/scripts/lib/registry-compatibility.ts index aefd7ade..9dbcdf25 100644 --- a/scripts/lib/registry-compatibility.ts +++ b/scripts/lib/registry-compatibility.ts @@ -389,6 +389,22 @@ export function validateBreakingEvidence( failures.push(`breaking change missing evidence: ${change.changeId}`); continue; } + // 0929/07-01. The changeId names a row and field, not a value. Without + // the value, evidence for one change would also pass the next change of + // the same field. Removals have no value to name. + if (change.after !== undefined) { + if (!Object.hasOwn(entry, "after")) { + failures.push( + `breaking change ${change.changeId} evidence needs after (the canonical JSON value it explains)`, + ); + } else if ( + canonicalRegistryJson(entry.after) !== canonicalRegistryJson(change.after) + ) { + failures.push( + `breaking change ${change.changeId} evidence explains after=${canonicalRegistryJson(entry.after)}, the change is after=${canonicalRegistryJson(change.after)}`, + ); + } + } for (const field of [ "versionBump", "migration", diff --git a/tests/unit/registry-compatibility.test.ts b/tests/unit/registry-compatibility.test.ts index 1373851b..197eacfa 100644 --- a/tests/unit/registry-compatibility.test.ts +++ b/tests/unit/registry-compatibility.test.ts @@ -150,6 +150,7 @@ describe("registry compatibility evidence", () => { changes: [ { changeId, + after: "/after", versionBump: "2", migration: "dual-read", compatibilityWindow: "one release", @@ -160,4 +161,60 @@ describe("registry compatibility evidence", () => { }).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); + }); + }); }); diff --git a/tests/unit/registry-governance.test.ts b/tests/unit/registry-governance.test.ts index f939e3cf..e188da79 100644 --- a/tests/unit/registry-governance.test.ts +++ b/tests/unit/registry-governance.test.ts @@ -286,6 +286,7 @@ describe("registry governance manifest", () => { validateBreakingEvidence(diff, { changes: breakingChanges.map((change) => ({ changeId: change.changeId, + after: change.after, versionBump: "2", migration: `migrate ${tamperCase.name}`, compatibilityWindow: "one release",