From 82c9e594ff285e794ea63b8e87ae5ad4f57e068f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:26:18 +0900 Subject: [PATCH] =?UTF-8?q?fix(registry):=20=EC=84=A0=EC=96=B8=EB=90=9C=20?= =?UTF-8?q?null=20=EC=A0=84=ED=99=98=EA=B3=BC=20=ED=97=88=EC=9A=A9?= =?UTF-8?q?=EA=B0=92=20=EC=B6=94=EA=B0=80=EB=A5=BC=20breaking=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EB=A7=89=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4=20?= =?UTF-8?q?(0929/07-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS 타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로 판정한다. null과 문자열은 타입이 달라서, governance가 string|null로 선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도 breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도 어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에 "마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID defaultValue null -> "local-build"에 "the value itself did not change"라고 적은 breaking 증거를 남겼다. 고른 방법 (리뷰 최소 개선 B) - 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입 (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라 field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나 선언 밖 값이면 지금처럼 field-type-changed(breaking)다. - contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두 포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나, 새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지 contract 변경도 그대로 breaking이다. - 선언 타입 판정은 check-registries.ts에 있던 runtimeType· matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다. - semantic-diff.json fixture에 nullable-field-cleared(behavior-change), registry-contract-extension(additive)을 더하고 artifact id 목록에도 넣었다. 버린 대안 - 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는 길을 더 넓힌다(0929/07-04). - nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른 레지스트리 영향을 다시 봐야 하는 넓은 변경이다. - 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰 기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로 breaking에 남겼다. 위험·한계 - fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능 꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다. paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다. - 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서 behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행 (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는 0929/07-01 범위라 이번에는 지우지 않았다. - 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이 바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번 라운드는 CHANGELOG 미출시 절이 없어 적지 않았다). - fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아 계속 breaking으로 남는다. 검증 - RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패 (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의 kind, allowlist 확장 breaking). check-registry-compatibility-fixtures: nullable-field-cleared actual breaking, registry-contract-extension actual breaking. - GREEN: registry-compatibility·registry-governance·release-artifacts· second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS. check-registries "11 registries PASS"(남은 breaking은 REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음). ci-artifact-contract "semantic validator" 사례 통과. - 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0. - 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian exit=126 환경 문제로 이 변경과 무관하게 실패). Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md --- scripts/check-registries.ts | 22 +---- scripts/contracts/release-artifacts.ts | 2 + scripts/lib/registry-compatibility.ts | 83 ++++++++++++++++++- .../registry/compatibility/semantic-diff.json | 60 ++++++++++++++ tests/unit/registry-compatibility.test.ts | 61 ++++++++++++++ 5 files changed, 205 insertions(+), 23 deletions(-) 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" } });