Files
clean-architecture-frontend…/scripts/lib/registry-compatibility.ts
T
DongHyeonka 605fd17d9f fix(registry): 무효화 그래프에 더하기만 한 변경을 additive로 분류한다 (0929/07-02)
문제
FE-REG-QUERY-INVALIDATION은 무효화 그래프를 행 하나(invalidation-graph)로
투영하고 topics·namespaces·edges를 breakingFields로 둔다. 분류기는 배열에서
빠진 원소가 없으면 field-changed로 보고 breakingFields로 등급을 정한다. 그래서
topic 하나, namespace 하나, edge 하나를 더하기만 해도 breaking 3건이 되고
기준선 재승인이나 breaking 증거가 필요하다. 서버 상태를 쓰는 기능은 모두
topic을 달기 때문에 기능을 하나 추가할 때마다 사람이 재승인해야 한다(1101
리뷰 16 영역 2.1절: P-07-02가 남았고 범위가 더 넓다).

고른 방법 (오케스트레이터 결정 1)
- governance의 snapshotProjection.canonicalArrayKeyFields에 있는 필드는
  키로 식별되는 원소 집합이다. 이 필드에서 원소가 빠지지 않았으면
  set-items-added(additive)로 분류한다. 다른 레지스트리의 "행 추가"와 같은
  성격이다. 이전 집합의 원소를 읽던 소비자는 모두 그대로 찾는다. 무효화가
  늘어날 뿐이다.
- 원소를 빼거나 바꾸면 지금처럼 allowed-value-removed(breaking)다. 이 분기는
  새 분기보다 먼저 판정된다.
- 0929/07-02(82c9e59)의 의도와 맞는지 확인했다. 그 커밋은 "이전에 유효하던
  값이 모두 유효하게 남는 변경"(null 전환, allowedValues 확장)을 breaking에서
  뺐고, 새·빠진·좁아진 제한은 breaking으로 남겼다. 이번 변경도 같은 기준이다.
  1101/07-02(3c31576)는 V2/V3 parity 테스트라 레지스트리 분류와 겹치지 않는다.

버린 대안
- registryId(FE-REG-QUERY-INVALIDATION)를 분류기에 적기: 분류 규칙이
  governance 밖에 숨는다.
- governance에 새 필드(예: additiveSetFields)를 두거나 breakingFields에서
  세 필드를 빼기: $contract가 바뀌어 기준선 재승인이 필요하다. 빼기만 하면
  behavior-change가 되어 결정(additive)과도 다르다.
- 뼈대·기능에서 topic을 빼기: 실제 기능에서 같은 문제가 다시 난다.
- 기능마다 재승인: 사람 승인이 기능 추가 비용이 된다.

위험·한계
- 게이트 판정이 바뀐다. 다운스트림에서 snapshotProjection을 쓰는
  레지스트리는 키 집합에 원소를 더해도 breaking 증거를 요구하지 않는다.
  다운스트림이 이런 추가에 적어 둔 breaking 증거 행은 이제 맞는 변경이 없어
  0929/07-01 규칙대로 stale로 실패한다. update:registry-baseline으로 지운다.
- governance의 breakingFields에 topics·namespaces·edges가 남아 있지만 이
  세 필드에서는 더 이상 판정을 바꾸지 않는다(빼기·바꾸기는 그 전에
  breaking이다). 지우면 $contract 변경이라 기준선 재승인과 함께 할 일이다.
- 투영된 키 집합의 순서만 바뀐 경우도 additive로 분류된다.
  check-registries가 키 순서로 정렬해 투영하므로 실제로는 생기지 않는다.
- 키 경로가 점을 포함한 필드(a.b)는 행 최상위 필드 이름과 맞지 않아 지금처럼
  breakingFields로 판정한다.

검증
- RED(수정 전): registry-compatibility.test.ts "grades a topic, namespace
  and edge added to the graph as additive" 실패. 커밋된 기준선에 topic·
  namespace·edge를 하나씩 더한 스냅샷이 [edges, breaking], [namespaces,
  breaking], [topics, breaking]로 분류됐다. 빼기·바꾸기 4건은 통과(breaking).
- GREEN: 같은 파일 23건 통과. registry-governance(무효화 원소 변조 4건이
  여전히 breaking)·second-api-feature-registries 포함 33건 통과.
  check-registry-compatibility-fixtures 11 PASS. check-registries "11
  registries PASS; compatibility=none".
- 회귀: tests/unit 178파일 중 177 통과. 실패 1건
  feature-shape-growth(초기 JS 증가 1036 > 1024 B)는 이 변경을 빼고 돌려도
  실패한다(1042 B, 기준 커밋의 기존 상태). tsc node·test rc=0, 바꾼 파일
  eslint rc=0.
- 미실행: check:architecture(pnpm 필요).

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 2.1, 16-01
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md 07-02
2026-11-03 01:50:12 +09:00

458 lines
15 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
>;
// 1101/16-01 (decision 1). A projected registry keeps keyed sets in one
// row: the invalidation graph's topics, namespaces and edges. An item
// added to such a set is what a new row is elsewhere, so it is additive
// even when the field is a breaking field. A removed or changed item is
// graded as allowed-value-removed below and stays breaking.
const keyedSetFields = new Set(
Object.keys(
(
currentContract.snapshotProjection as
| { canonicalArrayKeyFields?: Record<string, unknown> }
| undefined
)?.canonicalArrayKeyFields ?? {},
),
);
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 if (keyedSetFields.has(field) && Array.isArray(afterValue)) {
kind = "set-items-added";
changeImpact = "additive";
} 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[] = [];
const breakingChanges = diff.changes.filter(
(entry) => entry.impact === "breaking",
);
for (const change of breakingChanges) {
const entry = evidence.get(change.changeId);
if (!entry) {
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",
"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}`,
);
}
}
}
// 0929/07-01 (2). A row that explains no breaking change of this diff was
// absorbed by an earlier baseline or describes a change that is gone. It
// fails rather than being listed, because a printed list is not read, and
// the fix is cheap: update:registry-baseline deletes absorbed rows.
const explained = new Set(breakingChanges.map((change) => change.changeId));
for (const entry of entries) {
if (!explained.has(String(entry.changeId))) {
failures.push(
`stale breaking evidence ${String(entry.changeId)}: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)`,
);
}
}
return Object.freeze({
passed: failures.length === 0,
failures: Object.freeze(failures),
});
}