fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)
문제
레지스트리 호환성 분류기(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
This commit is contained in:
@@ -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)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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<string, unknown>;
|
||||
const current = after as Record<string, unknown>;
|
||||
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<string, unknown>
|
||||
@@ -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 (
|
||||
|
||||
@@ -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": {
|
||||
|
||||
@@ -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<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" } });
|
||||
|
||||
Reference in New Issue
Block a user