문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
60 lines
2.0 KiB
TypeScript
60 lines
2.0 KiB
TypeScript
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
import { registrySnapshotDigest } from "./lib/registry-compatibility.ts";
|
|
|
|
const inputPath =
|
|
process.argv[2] ?? "artifacts/quality/registry-current-snapshot.json";
|
|
const outputPath =
|
|
process.argv[3] ?? "config/contracts/registry-baseline.json";
|
|
const evidencePath = "config/contracts/registry-change-evidence.json";
|
|
const owner = process.env.REGISTRY_BASELINE_OWNER;
|
|
const reason = process.env.REGISTRY_BASELINE_REASON;
|
|
|
|
if (!owner || !reason) {
|
|
process.stderr.write(
|
|
"REGISTRY_BASELINE_OWNER and REGISTRY_BASELINE_REASON are required.\n",
|
|
);
|
|
process.exit(1);
|
|
}
|
|
|
|
const input = JSON.parse(await readFile(inputPath, "utf8"));
|
|
// Read before anything is written, so a missing file changes nothing.
|
|
const evidence = JSON.parse(await readFile(evidencePath, "utf8"));
|
|
const snapshot = input.registries
|
|
? { schemaVersion: 2, registries: input.registries }
|
|
: input;
|
|
const digest = registrySnapshotDigest(snapshot);
|
|
await mkdir(path.dirname(outputPath), { recursive: true });
|
|
await writeFile(outputPath, `${JSON.stringify(snapshot, null, 2)}\n`);
|
|
await writeFile(
|
|
"config/contracts/registry-baseline.approval.json",
|
|
`${JSON.stringify(
|
|
{
|
|
schemaVersion: 1,
|
|
snapshotDigest: digest,
|
|
owner,
|
|
reason,
|
|
approvedAt: new Date().toISOString(),
|
|
},
|
|
null,
|
|
2,
|
|
)}\n`,
|
|
);
|
|
// 0929/07-01 (3). The new baseline is the current snapshot, so it explains
|
|
// every change an evidence row described. A row left behind would match no
|
|
// change and fail check:registries. Git history keeps the deleted rows.
|
|
const deleted = (evidence.changes ?? []).map(
|
|
(entry: { changeId?: unknown }) => String(entry.changeId),
|
|
);
|
|
await writeFile(
|
|
evidencePath,
|
|
`${JSON.stringify({ ...evidence, changes: [] }, null, 2)}\n`,
|
|
);
|
|
process.stdout.write(`Registry baseline updated: ${digest}\n`);
|
|
if (deleted.length > 0) {
|
|
process.stdout.write(
|
|
`Deleted evidence the new baseline explains:\n${deleted.join("\n")}\n`,
|
|
);
|
|
}
|