fix(contracts): 계약 조립 오류 메시지에 원인을 싣는다 (1103/09-07)
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.
고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.
위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.
검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
This commit is contained in:
@@ -188,7 +188,7 @@ Files outside the feature directory. Everything else a feature needs is in
|
||||
| `artifacts/tests/a11y-manual/<ROUTE_ID>.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release |
|
||||
| `tests/e2e/accessibility.spec.ts` | a route path has a parameter other than `:resourceId`, or a protected page cannot render while every API answers `[]` | `test:a11y` (FE-GATE-009): the spec fills in only `:resourceId` and answers every API with `[]` |
|
||||
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from `composeProductSessionOwner` instead of installing it on the host global before boot | `check:types`; at runtime `feature <id> needs <capability>, which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` |
|
||||
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile, or a product runtime-config key and its FE-REG-ENV row (`PRODUCT_ENV_REGISTRY`) | auth profile: every gate that loads the operation, with `REST security profiles are incoherent for <operationId>: unknown authProfileId …`. Config key: `check:types` where it is read. FE-REG-ENV row: `check:registries` checks its fields; nothing requires the row |
|
||||
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile, or a product runtime-config key and its FE-REG-ENV row (`PRODUCT_ENV_REGISTRY`) | auth profile: every gate that loads the operation, with `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`. Config key: `check:types` where it is read. FE-REG-ENV row: `check:registries` checks its fields; nothing requires the row |
|
||||
| `config/runtime/<profile>.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing |
|
||||
| `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:<package>` |
|
||||
|
||||
|
||||
@@ -199,9 +199,8 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|
||||
|
||||
**틀리면**
|
||||
|
||||
- 없는 프로필이거나 `auth`와 조합이 틀리면 operation을 적재하는 모든 게이트가 실패한다.
|
||||
- `REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.`
|
||||
- `REST security profiles are incoherent for <operationId>: auth "external-session" cannot use the ANONYMOUS profile <id>.`
|
||||
- 없는 프로필이면 operation을 적재하는 모든 게이트가 실패한다.
|
||||
- `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`
|
||||
- 제품 프로필 ID가 템플릿 것과 같으면 `Product REST auth profile <id> reuses a template profile id.`
|
||||
|
||||
---
|
||||
|
||||
@@ -88,7 +88,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
| `<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `<BASE>_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
|
||||
| `contract package <packageId> is declared with conflicting identities` | 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 | 두 기능의 `<BASE>_CONTRACT_PACKAGE`를 맞춘다 |
|
||||
|
||||
계약 조립 실패는 메시지가 `Installed contract contribution is not composable` 하나다. 원인은 오류 객체(`ContractContributionError`)의 `reason` 속성에 있다. 메시지만 보이면 `reason`을 출력해 본다.
|
||||
계약 조립 실패의 메시지는 `Installed contract contribution is not composable: <reason>`이다. `reason`은 오류 객체(`ContractContributionError`)의 `reason` 속성에도 있다.
|
||||
|
||||
| `reason` | 원인 | 고칠 곳 |
|
||||
|---|---|---|
|
||||
|
||||
@@ -268,7 +268,9 @@ export class ContractContributionError extends Error {
|
||||
readonly reason: string;
|
||||
|
||||
constructor(reason: string, code: ContractCompositionFailureCode = "CONTRACT_CONTRIBUTION_INVALID") {
|
||||
super("Installed contract contribution is not composable");
|
||||
// 1103/09-07. The reason is in the message too: a gate that prints only
|
||||
// the message (check:registries) still names the operation and the cause.
|
||||
super(`Installed contract contribution is not composable: ${reason}`);
|
||||
this.name = "ContractContributionError";
|
||||
this.code = code;
|
||||
this.reason = reason;
|
||||
|
||||
@@ -195,40 +195,46 @@ afterAll(async () => {
|
||||
await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
|
||||
});
|
||||
|
||||
/** A copy of the repository with the second feature written into it. */
|
||||
async function repositoryWithSecondFeature(featureContract = FEATURE_CONTRACT) {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-"));
|
||||
roots.push(root);
|
||||
// scripts/check-diagnostics.ts is a FE-REG-TELEMETRY consumer path.
|
||||
for (const entry of [
|
||||
"src",
|
||||
"config/contracts",
|
||||
"schemas/artifacts",
|
||||
"scripts/check-diagnostics.ts",
|
||||
]) {
|
||||
await cp(path.resolve(entry), path.join(root, entry), { recursive: true });
|
||||
}
|
||||
await linkFixtureNodeModules(root);
|
||||
const files: Readonly<Record<string, string>> = {
|
||||
[`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-runtime.ts`]: FEATURE_RUNTIME,
|
||||
[`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES,
|
||||
[`src/features/${FEATURE_ID}/contracts/second-api-contract.ts`]: featureContract,
|
||||
[`src/features/${FEATURE_ID}/adapters/second-api-gateway.ts`]: FEATURE_GATEWAY,
|
||||
};
|
||||
for (const [file, content] of Object.entries(files)) {
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), content);
|
||||
}
|
||||
|
||||
const generated = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(generated.stderr).toBe("");
|
||||
expect(generated.status).toBe(0);
|
||||
return root;
|
||||
}
|
||||
|
||||
describe("adding a feature with an API operation, a route and an invalidation topic (F-3, 09-07, 0929/07-03, 1101/16-01)", () => {
|
||||
it("passes check-registries without edits outside the feature and its context", async () => {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-"));
|
||||
roots.push(root);
|
||||
// scripts/check-diagnostics.ts is a FE-REG-TELEMETRY consumer path.
|
||||
for (const entry of [
|
||||
"src",
|
||||
"config/contracts",
|
||||
"schemas/artifacts",
|
||||
"scripts/check-diagnostics.ts",
|
||||
]) {
|
||||
await cp(path.resolve(entry), path.join(root, entry), { recursive: true });
|
||||
}
|
||||
await linkFixtureNodeModules(root);
|
||||
const files: Readonly<Record<string, string>> = {
|
||||
[`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE,
|
||||
[`src/features/${FEATURE_ID}/feature-runtime.ts`]: FEATURE_RUNTIME,
|
||||
[`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES,
|
||||
[`src/features/${FEATURE_ID}/contracts/second-api-contract.ts`]: FEATURE_CONTRACT,
|
||||
[`src/features/${FEATURE_ID}/adapters/second-api-gateway.ts`]: FEATURE_GATEWAY,
|
||||
};
|
||||
for (const [file, content] of Object.entries(files)) {
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), content);
|
||||
}
|
||||
|
||||
const generated = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
expect(generated.stderr).toBe("");
|
||||
expect(generated.status).toBe(0);
|
||||
const root = await repositoryWithSecondFeature();
|
||||
|
||||
const checked = spawnSync(
|
||||
process.execPath,
|
||||
@@ -267,4 +273,21 @@ describe("adding a feature with an API operation, a route and an invalidation to
|
||||
["topics", "additive"],
|
||||
]);
|
||||
}, 60_000);
|
||||
|
||||
it("names the operation and the profile when the auth profile id is wrong (1103/09-07)", async () => {
|
||||
const root = await repositoryWithSecondFeature(
|
||||
FEATURE_CONTRACT.replace('authProfileId: "ANONYMOUS"', 'authProfileId: "SECOND_UNKNOWN"'),
|
||||
);
|
||||
|
||||
const checked = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/check-registries.ts")],
|
||||
{ cwd: root, encoding: "utf8" },
|
||||
);
|
||||
|
||||
expect(checked.status).toBe(1);
|
||||
expect(checked.stderr).toContain(
|
||||
`${FEATURE_ID}/GET_SECOND_ITEM: unknown authProfileId SECOND_UNKNOWN`,
|
||||
);
|
||||
}, 60_000);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user