문제
레지스트리 호환성 분류기(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
412 lines
12 KiB
TypeScript
412 lines
12 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
export const COMPATIBILITY_IMPACTS = Object.freeze([
|
|
"none",
|
|
"additive",
|
|
"behavior-change",
|
|
"breaking",
|
|
] as const);
|
|
|
|
type CompatibilityImpact = (typeof COMPATIBILITY_IMPACTS)[number];
|
|
type RegistryRecord = Record<string, unknown> & {
|
|
registryId?: unknown;
|
|
contract?: unknown;
|
|
rows?: unknown;
|
|
};
|
|
type RegistryChange = {
|
|
changeId: string;
|
|
registryId: string;
|
|
rowName: string;
|
|
field: string;
|
|
kind: string;
|
|
impact: CompatibilityImpact;
|
|
before?: unknown;
|
|
after?: unknown;
|
|
};
|
|
type RegistryDiff = Readonly<{
|
|
impact: CompatibilityImpact;
|
|
changes: readonly RegistryChange[];
|
|
}>;
|
|
|
|
const impactRank = new Map(
|
|
COMPATIBILITY_IMPACTS.map((impact, index) => [impact, index]),
|
|
);
|
|
|
|
export function canonicalizeRegistryValue(value: unknown): unknown {
|
|
if (Array.isArray(value)) {
|
|
const projected: unknown[] = value.map(canonicalizeRegistryValue);
|
|
return projected.every(
|
|
(item) =>
|
|
item === null ||
|
|
["string", "number", "boolean"].includes(typeof item),
|
|
)
|
|
? projected.sort((left, right) =>
|
|
JSON.stringify(left).localeCompare(JSON.stringify(right)),
|
|
)
|
|
: projected;
|
|
}
|
|
if (value && typeof value === "object") {
|
|
return Object.fromEntries(
|
|
Object.entries(value)
|
|
.sort(([left], [right]) => left.localeCompare(right))
|
|
.map(([key, item]) => [key, canonicalizeRegistryValue(item)]),
|
|
);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
export function canonicalRegistryJson(value: unknown): string {
|
|
return JSON.stringify(canonicalizeRegistryValue(value)) ?? "undefined";
|
|
}
|
|
|
|
export function registrySnapshotDigest(snapshot: unknown): string {
|
|
return createHash("sha256")
|
|
.update(canonicalRegistryJson(snapshot))
|
|
.digest("hex");
|
|
}
|
|
|
|
function strongestImpact(
|
|
current: CompatibilityImpact,
|
|
candidate: CompatibilityImpact,
|
|
): CompatibilityImpact {
|
|
return (impactRank.get(candidate) ?? 0) > (impactRank.get(current) ?? 0)
|
|
? candidate
|
|
: current;
|
|
}
|
|
|
|
function valueType(value: unknown): string {
|
|
if (value === null) return "null";
|
|
if (Array.isArray(value)) return "array";
|
|
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,
|
|
field: string,
|
|
kind: string,
|
|
): string {
|
|
return `${registryId}:${rowName}:${field}:${kind}`;
|
|
}
|
|
|
|
/**
|
|
* Calculates a semantic diff. Object key and primitive-array ordering is
|
|
* canonicalized before comparison and therefore cannot create a false change.
|
|
*/
|
|
export function diffRegistrySnapshots(
|
|
before: Readonly<Record<string, unknown>>,
|
|
after: Readonly<Record<string, unknown>>,
|
|
): RegistryDiff {
|
|
const changes: RegistryChange[] = [];
|
|
let impact: CompatibilityImpact = "none";
|
|
const beforeRegistryRows = (before.registries ?? []) as RegistryRecord[];
|
|
const beforeRegistries = new Map<string, RegistryRecord>(
|
|
beforeRegistryRows.map((registry) => [
|
|
String(registry.registryId),
|
|
registry,
|
|
]),
|
|
);
|
|
const afterRegistryRows = (after.registries ?? []) as RegistryRecord[];
|
|
const afterRegistries = new Map<string, RegistryRecord>(
|
|
afterRegistryRows.map((registry) => [
|
|
String(registry.registryId),
|
|
registry,
|
|
]),
|
|
);
|
|
const registryIds = new Set([
|
|
...beforeRegistries.keys(),
|
|
...afterRegistries.keys(),
|
|
]);
|
|
|
|
for (const registryId of [...registryIds].sort()) {
|
|
const previous = beforeRegistries.get(registryId);
|
|
const current = afterRegistries.get(registryId);
|
|
if (!previous || !current) {
|
|
const changeImpact = previous ? "breaking" : "additive";
|
|
impact = strongestImpact(impact, changeImpact);
|
|
changes.push({
|
|
changeId: changeId(registryId, "*", "*", previous ? "removed" : "added"),
|
|
registryId,
|
|
rowName: "*",
|
|
field: "*",
|
|
kind: previous ? "registry-removed" : "registry-added",
|
|
impact: changeImpact,
|
|
});
|
|
continue;
|
|
}
|
|
|
|
const previousContract = (previous.contract ?? {}) as Record<string, unknown>;
|
|
const currentContract = (current.contract ?? {}) as Record<string, unknown>;
|
|
const contractFields = new Set([
|
|
...Object.keys(previousContract),
|
|
...Object.keys(currentContract),
|
|
]);
|
|
for (const field of [...contractFields].sort()) {
|
|
const beforeHas = Object.hasOwn(previousContract, field);
|
|
const afterHas = Object.hasOwn(currentContract, field);
|
|
const beforeValue = previousContract[field];
|
|
const afterValue = currentContract[field];
|
|
if (
|
|
beforeHas &&
|
|
afterHas &&
|
|
canonicalRegistryJson(beforeValue) ===
|
|
canonicalRegistryJson(afterValue)
|
|
) {
|
|
continue;
|
|
}
|
|
const extendsAllowedValues =
|
|
field === "allowedValues" &&
|
|
beforeHas &&
|
|
afterHas &&
|
|
onlyExtendsAllowedValues(beforeValue, afterValue);
|
|
const kind = !beforeHas
|
|
? "contract-field-added"
|
|
: !afterHas
|
|
? "contract-field-removed"
|
|
: 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: changeImpact,
|
|
before: canonicalizeRegistryValue(beforeValue),
|
|
after: canonicalizeRegistryValue(afterValue),
|
|
});
|
|
}
|
|
|
|
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>
|
|
>;
|
|
const afterRows = (current.rows ?? {}) as Record<
|
|
string,
|
|
Record<string, unknown>
|
|
>;
|
|
const rowNames = new Set([
|
|
...Object.keys(beforeRows),
|
|
...Object.keys(afterRows),
|
|
]);
|
|
for (const rowName of [...rowNames].sort()) {
|
|
const beforeRow = beforeRows[rowName];
|
|
const afterRow = afterRows[rowName];
|
|
if (!beforeRow || !afterRow) {
|
|
const changeImpact = beforeRow ? "breaking" : "additive";
|
|
impact = strongestImpact(impact, changeImpact);
|
|
changes.push({
|
|
changeId: changeId(
|
|
registryId,
|
|
rowName,
|
|
"*",
|
|
beforeRow ? "removed" : "added",
|
|
),
|
|
registryId,
|
|
rowName,
|
|
field: "*",
|
|
kind: beforeRow ? "row-removed" : "row-added",
|
|
impact: changeImpact,
|
|
});
|
|
continue;
|
|
}
|
|
|
|
const fields = new Set([
|
|
...Object.keys(beforeRow),
|
|
...Object.keys(afterRow),
|
|
]);
|
|
for (const field of [...fields].sort()) {
|
|
const beforeHas = Object.hasOwn(beforeRow, field);
|
|
const afterHas = Object.hasOwn(afterRow, field);
|
|
const beforeValue = beforeRow[field];
|
|
const afterValue = afterRow[field];
|
|
if (
|
|
beforeHas &&
|
|
afterHas &&
|
|
canonicalRegistryJson(beforeValue) ===
|
|
canonicalRegistryJson(afterValue)
|
|
) {
|
|
continue;
|
|
}
|
|
let kind: string;
|
|
let changeImpact: CompatibilityImpact;
|
|
if (!beforeHas) {
|
|
kind = "field-added";
|
|
changeImpact = "additive";
|
|
} else if (!afterHas) {
|
|
kind = "field-removed";
|
|
changeImpact = "breaking";
|
|
} else if (
|
|
valueType(beforeValue) !== valueType(afterValue) &&
|
|
!isDeclaredNullableChange(beforeValue, afterValue, fieldTypes[field])
|
|
) {
|
|
kind = "field-type-changed";
|
|
changeImpact = "breaking";
|
|
} else if (
|
|
Array.isArray(beforeValue) &&
|
|
Array.isArray(afterValue) &&
|
|
beforeValue.some(
|
|
(item) =>
|
|
!afterValue.some(
|
|
(candidate) =>
|
|
canonicalRegistryJson(candidate) ===
|
|
canonicalRegistryJson(item),
|
|
),
|
|
)
|
|
) {
|
|
kind = "allowed-value-removed";
|
|
changeImpact = "breaking";
|
|
} else {
|
|
kind = "field-changed";
|
|
changeImpact = breakingFields.has(field)
|
|
? "breaking"
|
|
: "behavior-change";
|
|
}
|
|
impact = strongestImpact(impact, changeImpact);
|
|
changes.push({
|
|
changeId: changeId(registryId, rowName, field, kind),
|
|
registryId,
|
|
rowName,
|
|
field,
|
|
kind,
|
|
impact: changeImpact,
|
|
before: canonicalizeRegistryValue(beforeValue),
|
|
after: canonicalizeRegistryValue(afterValue),
|
|
});
|
|
}
|
|
}
|
|
}
|
|
|
|
return Object.freeze({
|
|
impact,
|
|
changes: Object.freeze(changes),
|
|
});
|
|
}
|
|
|
|
export function verifyRegistryBaselineApproval(
|
|
snapshot: Readonly<Record<string, unknown>>,
|
|
approval: Readonly<Record<string, unknown>>,
|
|
) {
|
|
const actualDigest = registrySnapshotDigest(snapshot);
|
|
const approvedDigest = approval.snapshotDigest;
|
|
return Object.freeze({
|
|
passed:
|
|
approval.schemaVersion === 1 &&
|
|
typeof approval.owner === "string" &&
|
|
approval.owner.length > 0 &&
|
|
typeof approval.approvedAt === "string" &&
|
|
approvedDigest === actualDigest,
|
|
actualDigest,
|
|
approvedDigest:
|
|
typeof approvedDigest === "string" ? approvedDigest : "missing",
|
|
});
|
|
}
|
|
|
|
export function validateBreakingEvidence(
|
|
diff: RegistryDiff,
|
|
evidenceFile: Readonly<Record<string, unknown>>,
|
|
) {
|
|
const entries = (evidenceFile.changes ?? []) as Array<Record<string, unknown>>;
|
|
const evidence = new Map<string, Record<string, unknown>>(
|
|
entries.map((entry) => [String(entry.changeId), entry]),
|
|
);
|
|
const failures: string[] = [];
|
|
for (const change of diff.changes.filter(
|
|
(entry) => entry.impact === "breaking",
|
|
)) {
|
|
const entry = evidence.get(change.changeId);
|
|
if (!entry) {
|
|
failures.push(`breaking change missing evidence: ${change.changeId}`);
|
|
continue;
|
|
}
|
|
for (const field of [
|
|
"versionBump",
|
|
"migration",
|
|
"compatibilityWindow",
|
|
"rollback",
|
|
"owner",
|
|
]) {
|
|
const value = entry[field];
|
|
if (typeof value !== "string" || value.trim().length === 0) {
|
|
failures.push(
|
|
`breaking change ${change.changeId} missing non-empty ${field}`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
return Object.freeze({
|
|
passed: failures.length === 0,
|
|
failures: Object.freeze(failures),
|
|
});
|
|
}
|