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 (
|
||||
|
||||
Reference in New Issue
Block a user