fix(registries): 계약 조립 실패의 reason을 적고 읽지 못한 레지스트리를 지운 것으로 세지 않는다
문제
기능 계약 조립이 실패하면(예: 없는 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
This commit is contained in:
@@ -144,6 +144,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
| `FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value>` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` |
|
||||
| `FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 |
|
||||
| `FE-REG-API.<operationId> has no executable consumer for operationId=<operationId>` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 |
|
||||
| `missing registry source <path>: <message> (reason: <reason>)` | 레지스트리 source를 읽다가 오류가 났다. 계약 조립 실패면 `<reason>`이 위 `reason` 표의 값이다. 읽지 못한 레지스트리는 `removed` 증거를 요구하지 않는다 | `<reason>`이 가리키는 곳 |
|
||||
| `breaking change missing evidence: <changeId>` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` |
|
||||
| `stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
|
||||
| `registry baseline approval digest mismatch: approved=<digest> actual=<digest>` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 |
|
||||
|
||||
@@ -116,6 +116,13 @@ const owners = new Map<string, string>();
|
||||
const snapshots: RegistrySnapshot[] = [];
|
||||
const rowsByRegistry = new Map<string, RegistryRows>();
|
||||
const sourcesByRegistry = new Map<string, string>();
|
||||
/**
|
||||
* 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<string>();
|
||||
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<Record<string, unknown>>,
|
||||
registryIds: ReadonlySet<string>,
|
||||
): Readonly<Record<string, unknown>> {
|
||||
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"),
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user