From 84d6e526a33f69244fd0b413e5ca2e953d254f58 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:32:20 +0900 Subject: [PATCH] =?UTF-8?q?fix(registries):=20=EA=B3=84=EC=95=BD=20?= =?UTF-8?q?=EC=A1=B0=EB=A6=BD=20=EC=8B=A4=ED=8C=A8=EC=9D=98=20reason?= =?UTF-8?q?=EC=9D=84=20=EC=A0=81=EA=B3=A0=20=EC=9D=BD=EC=A7=80=20=EB=AA=BB?= =?UTF-8?q?=ED=95=9C=20=EB=A0=88=EC=A7=80=EC=8A=A4=ED=8A=B8=EB=A6=AC?= =?UTF-8?q?=EB=A5=BC=20=EC=A7=80=EC=9A=B4=20=EA=B2=83=EC=9C=BC=EB=A1=9C=20?= =?UTF-8?q?=EC=84=B8=EC=A7=80=20=EC=95=8A=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은 "missing registry source src/features/loaded-feature-runtimes.ts: Installed contract contribution is not composable" 두 줄, "FE-REG-API is not an object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA", "breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은 ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다. 끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을 제안한다(실험 E-9). 고른 방법 - source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께 적는다. - 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사 ("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교 (removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지 않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다. - errors.md 레지스트리 표에 이 메시지 행을 더했다. 버린 대안 - 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와 CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다. 위험·한계 - source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도 "missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서 지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다. - FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다. 검증 - RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가 다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를 던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고 cascade 3줄이 더 나와 실패했다. - GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록 operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason: reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다. - check:registries:fixture·check:routes:fixture·baseline-fixture가 기대 진단으로 실패한다. eslint, check:types:node, check:types:test 통과. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06 --- docs/manual/reference/errors.md | 1 + scripts/check-registries.ts | 48 ++++++++++- tests/unit/registry-governance.test.ts | 112 +++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 3 deletions(-) diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 4cf83d62..8397a68f 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -144,6 +144,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `FE-REG-ROUTE.. has unknown value ` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` | | `FE-REG-ROUTE..paramsSchema references unknown FE-REG-SCHEMA.schemaId=` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 | | `FE-REG-API. has no executable consumer for operationId=` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 | +| `missing registry source : (reason: )` | 레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 ``이 위 `reason` 표의 값이다. 읽지 못한 레지스트리는 `removed` 증거를 요구하지 않는다 | ``이 가리키는 곳 | | `breaking change missing evidence: ` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` | | `stale breaking evidence : no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 | | `registry baseline approval digest mismatch: approved= actual=` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 | diff --git a/scripts/check-registries.ts b/scripts/check-registries.ts index b34bba0c..73c3c11d 100644 --- a/scripts/check-registries.ts +++ b/scripts/check-registries.ts @@ -116,6 +116,13 @@ const owners = new Map(); const snapshots: RegistrySnapshot[] = []; const rowsByRegistry = new Map(); const sourcesByRegistry = new Map(); +/** + * 1103/14-06. Registries whose source did not load. Their failure is already + * reported with its cause, so the checks that read their rows (references, + * the baseline comparison) skip them instead of reporting the same failure + * again as a deleted registry. + */ +const unloadedRegistries = new Set(); const registryExtensions = [".ts", ".tsx", ".mts", ".cts"]; async function resolveRegistrySource( @@ -144,6 +151,33 @@ async function resolveRegistrySource( return candidates[0] ?? null; } +/** + * 1103/14-06. A contract composition failure (`ContractContributionError`) + * says only "not composable"; its cause is the `reason` property. + */ +function loadErrorText(error: Error): string { + const message = error.message.split("\n")[0] ?? ""; + const reason: unknown = (error as Error & { reason?: unknown }).reason; + return typeof reason === "string" && reason.length > 0 + ? `${message} (reason: ${reason})` + : message; +} + +function withoutRegistries( + snapshot: Readonly>, + registryIds: ReadonlySet, +): Readonly> { + if (registryIds.size === 0 || !Array.isArray(snapshot.registries)) { + return snapshot; + } + return { + ...snapshot, + registries: (snapshot.registries as Array<{ registryId?: unknown }>).filter( + (registry) => !registryIds.has(String(registry.registryId)), + ), + }; +} + type FieldLookup = Readonly<{ found: boolean; value: unknown; @@ -371,8 +405,12 @@ for (const specification of governance.registries) { } catch (error) { // A source that exists but fails to load names its error, so a broken // import in a feature contract is not reported as a missing file. - const reason = sourcePath && error instanceof Error ? `: ${error.message.split("\n")[0]}` : ""; - if (!rows) failures.push(`missing registry source ${specification.path}${reason}`); + const reason = sourcePath && error instanceof Error ? `: ${loadErrorText(error)}` : ""; + if (!rows) { + failures.push(`missing registry source ${specification.path}${reason}`); + unloadedRegistries.add(specification.registryId); + continue; + } } const registryRows = projectRegistryRows(specification, rows); @@ -534,6 +572,7 @@ for (const specification of governance.registries) { for (const reference of specification.references ?? []) { const targetRows = rowsByRegistry.get(reference.registryId); if (!targetRows) { + if (unloadedRegistries.has(reference.registryId)) continue; failures.push( `${specification.registryId} references unknown registry ${reference.registryId}`, ); @@ -672,7 +711,10 @@ if (baselinePath && approvalPath && evidencePath) { `registry baseline approval digest mismatch: approved=${approvalResult.approvedDigest} actual=${approvalResult.actualDigest}`, ); } - const registryDiff = diffRegistrySnapshots(baseline, currentSnapshot); + const registryDiff = diffRegistrySnapshots( + withoutRegistries(baseline, unloadedRegistries), + currentSnapshot, + ); compatibility = registryDiff; const evidence = JSON.parse( await readFile(evidencePath, "utf8"), diff --git a/tests/unit/registry-governance.test.ts b/tests/unit/registry-governance.test.ts index 8c2e0586..e038d441 100644 --- a/tests/unit/registry-governance.test.ts +++ b/tests/unit/registry-governance.test.ts @@ -6,6 +6,7 @@ import { describe, expect, it } from "vitest"; import { diffRegistrySnapshots, + registrySnapshotDigest, validateBreakingEvidence, verifyRegistryBaselineApproval, } from "../../scripts/lib/registry-compatibility.ts"; @@ -536,4 +537,115 @@ describe("registry governance manifest", () => { await rm(directory, { recursive: true, force: true }); } }); + + // 1103/14-06. A contract contribution that fails to compose throws while + // the registry source loads. The gate names the cause the error carries in + // `reason` and does not also report the unloaded registries as deleted + // (`removed` evidence) or as unknown reference targets. + it("names a load error's reason and reports no cascade for the registries it did not load", async () => { + const directory = await mkdtemp(path.join(tmpdir(), "registry-source-reason-")); + const run = (extra: readonly string[]) => + spawnSync( + process.execPath, + [ + path.resolve("scripts/check-registries.ts"), + "--governance", + "governance.json", + "--artifact", + "out.json", + ...extra, + ], + { cwd: directory, encoding: "utf8" }, + ); + try { + await mkdir(path.join(directory, "src"), { recursive: true }); + await writeFile( + path.join(directory, "src/composed.ts"), + 'export const ROWS = { A: { id: "A" } };\n', + ); + await writeFile( + path.join(directory, "src/routes.ts"), + 'export const ROUTES = { R: { id: "R", target: "A" } };\n', + ); + await writeFile( + path.join(directory, "governance.json"), + JSON.stringify({ + schemaVersion: 1, + sourceDirectories: [], + registries: [ + { + registryId: "FIXTURE-COMPOSED", + path: "src/composed.ts", + exportName: "ROWS", + owner: "fixture", + keyField: "id", + requiredFields: ["id"], + fieldTypes: { id: "string" }, + }, + { + registryId: "FIXTURE-ROUTES", + path: "src/routes.ts", + exportName: "ROUTES", + owner: "fixture", + keyField: "id", + requiredFields: ["id", "target"], + fieldTypes: { id: "string", target: "string" }, + references: [ + { + field: "target", + registryId: "FIXTURE-COMPOSED", + targetField: "id", + }, + ], + }, + ], + }), + ); + const healthy = run(["--no-baseline"]); + expect(healthy.status, healthy.stderr).toBe(0); + const report = JSON.parse( + await readFile(path.join(directory, "out.json"), "utf8"), + ) as { registries: unknown[] }; + const baseline = { schemaVersion: 2, registries: report.registries }; + await writeFile(path.join(directory, "baseline.json"), JSON.stringify(baseline)); + await writeFile( + path.join(directory, "approval.json"), + JSON.stringify({ + schemaVersion: 1, + snapshotDigest: registrySnapshotDigest(baseline), + owner: "fixture", + reason: "fixture", + approvedAt: "2026-11-04T00:00:00.000Z", + }), + ); + await writeFile( + path.join(directory, "evidence.json"), + JSON.stringify({ schemaVersion: 1, changes: [] }), + ); + const withBaseline = [ + "--baseline", + "baseline.json", + "--approval", + "approval.json", + "--compatibility-evidence", + "evidence.json", + ]; + expect(run(withBaseline).status).toBe(0); + + await writeFile( + path.join(directory, "src/composed.ts"), + 'throw Object.assign(new Error("Installed contract contribution is not composable"), { reason: "notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE" });\n', + ); + const broken = run(withBaseline); + const output = `${broken.stdout}${broken.stderr}`; + + expect(broken.status).toBe(1); + expect(output.trim().split("\n")).toEqual([ + "Registry governance failed:", + "missing registry source src/composed.ts: Installed contract contribution is not composable (reason: notice-feature/NOTICE_LIST_ITEMS: unknown authProfileId NOTICE_NOPE)", + ]); + } finally { + await rm(directory, { recursive: true, force: true }); + } + }); });