Files
clean-architecture-frontend…/tests/unit/registry-governance.test.ts
T
DongHyeonka 5e6be9a92f fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.

고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
  하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
  needs after", 다르면 "evidence explains after=..., the change is
  after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
  그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
  after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
  registry-governance tamper 사례)에 after를 넣었다.

버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
  X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
  출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
  update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
  14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
  하지 않았다.

위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
  남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
  다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
  않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
  된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
  적어야 한다.

검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
  ("rejects evidence written for another value", "requires the explained
  value": expected [] to deeply equal [...]). X3 변이로 check-registries
  "11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
  after=\"/examples/reference-resources/items/:resourceId\", the change is
  after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
  "11 registries PASS". registry-compatibility·registry-governance·
  release-artifacts·second-api-feature-registries 53/53 통과.
  compatibility fixtures 11 PASS. verify-documentation-readiness
  PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00

379 lines
12 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
import {
diffRegistrySnapshots,
validateBreakingEvidence,
verifyRegistryBaselineApproval,
} from "../../scripts/lib/registry-compatibility.ts";
type RegistryDefinition = Readonly<{
registryId: string;
owner: string;
requiredFields: string[];
fieldTypes: Record<string, string>;
path: string;
exportName: string;
rowsPath?: string;
rowKeyFields?: string[];
uniqueFields?: string[];
uniqueFieldSets?: string[][];
snapshotProjection?: {
singletonRowKey: string;
canonicalArrayKeyFields: Record<string, string[]>;
};
consumers?: Array<{ path: string; token: string }>;
breakingFields?: string[];
}>;
describe("registry governance manifest", () => {
it("declares eleven typed, single-owner executable registries", async () => {
const governance = JSON.parse(
await readFile("config/contracts/registry-governance.json", "utf8"),
);
const registries = governance.registries as RegistryDefinition[];
expect(governance.registries).toHaveLength(11);
expect(new Set(registries.map((entry) => entry.registryId)).size).toBe(
11,
);
expect(registries.every((entry) => entry.owner)).toBe(true);
expect(
registries.every(
(entry) =>
Array.isArray(entry.requiredFields) &&
entry.requiredFields.length > 0 &&
entry.fieldTypes &&
Object.keys(entry.fieldTypes).length > 0,
),
).toBe(true);
});
it("governs the installed invalidation graph and wire versions at their real exports", async () => {
const governance = JSON.parse(
await readFile("config/contracts/registry-governance.json", "utf8"),
) as { registries: RegistryDefinition[] };
const byId = new Map(
governance.registries.map((registry) => [registry.registryId, registry]),
);
expect(byId.get("FE-REG-QUERY-INVALIDATION")).toMatchObject({
path: "src/features/installed-feature-contracts.ts",
exportName: "INVALIDATION_REGISTRY",
rowsPath: "edges",
rowKeyFields: [
"topicId",
"namespace.namespaceId",
"namespace.namespaceVersion",
],
uniqueFieldSets: [
[
"topicId",
"namespace.namespaceId",
"namespace.namespaceVersion",
],
],
snapshotProjection: {
singletonRowKey: "invalidation-graph",
canonicalArrayKeyFields: {
topics: ["$value"],
namespaces: ["namespaceId", "namespaceVersion"],
edges: [
"topicId",
"namespace.namespaceId",
"namespace.namespaceVersion",
],
},
},
consumers: [
{
path: "src/bootstrap/runtime-adapters.ts",
token: "indexInvalidationRegistry(INVALIDATION_REGISTRY)",
},
],
breakingFields: ["topics", "namespaces", "edges"],
});
expect(byId.get("FE-REG-QUERY-INVALIDATION-TOPIC-VERSION")).toMatchObject({
path: "src/features/installed-feature-contracts.ts",
exportName: "INVALIDATION_TOPIC_VERSIONS",
rowKeyFields: ["topicId"],
uniqueFields: ["topicId"],
consumers: [
{
path: "src/bootstrap/runtime-adapters.ts",
token: "indexInvalidationTopicVersions(",
},
],
breakingFields: ["topicId", "topicVersion"],
});
});
it("projects graph and array exports into deterministic governed rows", async () => {
const directory = await mkdtemp(
path.join(tmpdir(), "registry-governance-projection-"),
);
const artifact = path.join(directory, "registries.json");
try {
const result = spawnSync(
process.execPath,
[
"scripts/check-registries.ts",
"--governance",
"tests/fixtures/registry/invalidation/governance.json",
"--artifact",
artifact,
"--no-baseline",
],
{ encoding: "utf8" },
);
expect(result.status, result.stderr).toBe(0);
const report = JSON.parse(await readFile(artifact, "utf8")) as {
registries: Array<{
registryId: string;
rows: Record<string, Record<string, unknown>>;
}>;
};
expect(
report.registries.find(
(registry) => registry.registryId === "FIXTURE-INVALIDATION-EDGES",
)?.rows,
).toEqual({
"invalidation-graph": {
topics: ["orders", "qinv.fixture.changed"],
namespaces: [
{ namespaceId: "orders", namespaceVersion: 1 },
{ namespaceId: "qinv.fixture.changed", namespaceVersion: 1 },
],
edges: [
{
topicId: "orders",
namespace: {
namespaceId: "qinv.fixture.changed",
namespaceVersion: 1,
},
},
{
topicId: "qinv.fixture.changed",
namespace: { namespaceId: "orders", namespaceVersion: 1 },
},
],
},
});
expect(
report.registries.find(
(registry) => registry.registryId === "FIXTURE-INVALIDATION-VERSIONS",
)?.rows,
).toHaveProperty('["qinv.fixture.changed"]');
} finally {
await rm(directory, { recursive: true, force: true });
}
});
it("requires explicit evidence for post-baseline graph and version drift", async () => {
const directory = await mkdtemp(
path.join(tmpdir(), "registry-governance-tamper-"),
);
const artifact = path.join(directory, "registries.json");
try {
const result = spawnSync(
process.execPath,
[
"scripts/check-registries.ts",
"--governance",
"tests/fixtures/registry/invalidation/governance.json",
"--artifact",
artifact,
"--no-baseline",
],
{ encoding: "utf8" },
);
expect(result.status, result.stderr).toBe(0);
const report = JSON.parse(await readFile(artifact, "utf8")) as {
registries: Array<{
registryId: string;
contract: Record<string, unknown>;
rows: Record<string, Record<string, unknown>>;
}>;
};
const baseline = { schemaVersion: 2, registries: report.registries };
expect(
baseline.registries.find(
(registry) => registry.registryId === "FIXTURE-INVALIDATION-EDGES",
)?.rows["invalidation-graph"],
).toBeDefined();
const tamperCases = [
{
name: "topic",
registryId: "FIXTURE-INVALIDATION-EDGES",
field: "topics",
apply(snapshot: typeof baseline) {
const graph = snapshot.registries.find(
(registry) => registry.registryId === this.registryId,
)?.rows["invalidation-graph"];
(graph?.topics as string[])[0] = "tampered-topic";
},
},
{
name: "namespace",
registryId: "FIXTURE-INVALIDATION-EDGES",
field: "namespaces",
apply(snapshot: typeof baseline) {
const graph = snapshot.registries.find(
(registry) => registry.registryId === this.registryId,
)?.rows["invalidation-graph"];
const namespaces = graph?.namespaces as Array<{
namespaceId: string;
}>;
namespaces[0]!.namespaceId = "tampered-namespace";
},
},
{
name: "edge",
registryId: "FIXTURE-INVALIDATION-EDGES",
field: "edges",
apply(snapshot: typeof baseline) {
const graph = snapshot.registries.find(
(registry) => registry.registryId === this.registryId,
)?.rows["invalidation-graph"];
const edges = graph?.edges as Array<{ topicId: string }>;
edges[0]!.topicId = "tampered-edge";
},
},
{
name: "version",
registryId: "FIXTURE-INVALIDATION-VERSIONS",
field: "topicVersion",
apply(snapshot: typeof baseline) {
const versions = snapshot.registries.find(
(registry) => registry.registryId === this.registryId,
)?.rows;
const firstVersion = versions?.[Object.keys(versions)[0] ?? ""];
if (!firstVersion) throw new Error("version fixture row missing");
firstVersion.topicVersion = 2;
},
},
];
for (const tamperCase of tamperCases) {
const current = structuredClone(baseline);
tamperCase.apply(current);
const diff = diffRegistrySnapshots(baseline, current);
expect(diff.impact, tamperCase.name).toBe("breaking");
expect(
diff.changes.some((change) => change.kind === "registry-added"),
tamperCase.name,
).toBe(false);
const breakingChanges = diff.changes.filter(
(change) => change.impact === "breaking",
);
expect(breakingChanges, tamperCase.name).toEqual(
expect.arrayContaining([
expect.objectContaining({
registryId: tamperCase.registryId,
field: tamperCase.field,
}),
]),
);
expect(
validateBreakingEvidence(diff, { changes: [] }).passed,
tamperCase.name,
).toBe(false);
expect(
validateBreakingEvidence(diff, {
changes: breakingChanges.map((change) => ({
changeId: change.changeId,
after: change.after,
versionBump: "2",
migration: `migrate ${tamperCase.name}`,
compatibilityWindow: "one release",
rollback: `restore ${tamperCase.name} baseline`,
owner: "fixture-owner",
})),
}).passed,
tamperCase.name,
).toBe(true);
}
} finally {
await rm(directory, { recursive: true, force: true });
}
});
it("pins the full invalidation graph and versions in the approved repository baseline", async () => {
const baseline = JSON.parse(
await readFile("config/contracts/registry-baseline.json", "utf8"),
) as {
schemaVersion: number;
registries: Array<{
registryId: string;
rows: Record<string, Record<string, unknown>>;
}>;
};
const approval = JSON.parse(
await readFile(
"config/contracts/registry-baseline.approval.json",
"utf8",
),
) as Record<string, unknown>;
expect(verifyRegistryBaselineApproval(baseline, approval).passed).toBe(true);
expect(baseline.registries).toHaveLength(11);
const graph = baseline.registries.find(
(registry) => registry.registryId === "FE-REG-QUERY-INVALIDATION",
);
const versions = baseline.registries.find(
(registry) =>
registry.registryId ===
"FE-REG-QUERY-INVALIDATION-TOPIC-VERSION",
);
expect(graph?.rows["invalidation-graph"]).toMatchObject({
topics: expect.any(Array),
namespaces: expect.any(Array),
edges: expect.any(Array),
});
expect(versions?.rows).toBeDefined();
// Who approved and why, not this template's wording: a project that
// re-baselines with update:registry-baseline writes its own (D-13).
expect(approval).toMatchObject({
owner: expect.stringMatching(/\S/u),
reason: expect.stringMatching(/\S/u),
});
});
it("rejects duplicate composite invalidation edges after projection", async () => {
const directory = await mkdtemp(
path.join(tmpdir(), "registry-governance-duplicate-"),
);
const artifact = path.join(directory, "registries.json");
try {
const result = spawnSync(
process.execPath,
[
"scripts/check-registries.ts",
"--governance",
"tests/fixtures/registry/invalidation/duplicate-governance.json",
"--artifact",
artifact,
"--no-baseline",
],
{ encoding: "utf8" },
);
expect(result.status).toBe(1);
const report = JSON.parse(await readFile(artifact, "utf8")) as {
failures: string[];
};
expect(report.failures).toEqual([
expect.stringContaining(
"duplicates topicId+namespace.namespaceId+namespace.namespaceVersion",
),
]);
} finally {
await rm(directory, { recursive: true, force: true });
}
});
});