diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json index 38b05eee..74247c76 100644 --- a/config/contracts/registry-baseline.approval.json +++ b/config/contracts/registry-baseline.approval.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "snapshotDigest": "8f5ae6dde9c6a293144e5bccad1765367f06ac3a6b58a6229c69426703158c9c", + "snapshotDigest": "319a798ca3c9a87d7e2943177d952b13941622f4faec23c28f36024196a9e91d", "owner": "DongHyeonka", - "reason": "1103/13-04 FE-REG-ENV runtime rows state required and defaultValue as runtimeConfigV2ArtifactSchema reads them (TELEMETRY_ENABLED, AUTH_MODE, RELEASE_MANIFEST_URL, CAPABILITY_OVERRIDES, FEATURE_OVERRIDES); defaultValue may be an object", - "approvedAt": "2026-11-04T11:26:00.863Z" + "reason": "1103/16-04 FE-REG-API problemSchema가 FE-REG-SCHEMA api-problem 행을 참조한다", + "approvedAt": "2026-11-04T14:04:44.377Z" } diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json index da86f4cd..6a56a3ef 100644 --- a/config/contracts/registry-baseline.json +++ b/config/contracts/registry-baseline.json @@ -419,6 +419,11 @@ "field": "responseSchema", "registryId": "FE-REG-SCHEMA", "targetField": "schemaId" + }, + { + "field": "problemSchema", + "registryId": "FE-REG-SCHEMA", + "targetField": "schemaId" } ], "keyField": "operationId", @@ -543,7 +548,7 @@ "registryId": "FE-REG-SCHEMA", "owner": "feature-frontend-contract-schema-registry", "source": "src/features/loaded-feature-runtimes.ts", - "rowCount": 7, + "rowCount": 8, "contract": { "requiredFields": [ "schemaId", @@ -566,7 +571,8 @@ "route-search", "route-search-api-request", "api-request", - "api-response" + "api-response", + "api-problem" ], "runtime": [ "zod" @@ -602,6 +608,15 @@ "runtime": "zod", "schemaId": "NotFoundSplat" }, + "ReferenceProblem": { + "boundary": "api-problem", + "direction": "RESPONSE", + "owner": "feature-frontend-reference-feature-vertical-slice", + "runtime": "zod", + "schemaId": "ReferenceProblem", + "schemaVersion": 1, + "unknownFieldPolicy": "STRIP_UNKNOWN" + }, "ReferenceResourceListPayload": { "boundary": "api-response", "direction": "RESPONSE", @@ -1407,6 +1422,7 @@ ], "optionalAttributes": [ "duration_bucket", + "effect_certainty", "operation_id" ], "requiredAttributes": [ diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index dce422f5..a7755371 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -227,6 +227,11 @@ "field": "responseSchema", "registryId": "FE-REG-SCHEMA", "targetField": "schemaId" + }, + { + "field": "problemSchema", + "registryId": "FE-REG-SCHEMA", + "targetField": "schemaId" } ], "consumerIdentityField": "operationId", @@ -269,7 +274,8 @@ "route-search", "route-search-api-request", "api-request", - "api-response" + "api-response", + "api-problem" ], "runtime": ["zod"] }, diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index c1353836..d9d30b06 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -241,6 +241,14 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 - `route-search-api-request`: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다. - `api-request`: 요청 입력. - `api-response`: 응답 DTO. +- `api-problem`: 실패 본문(`problemValidator`). Envelope operation이면 `error` 객체다. FE-REG-API의 `problemSchema`가 이 행을 가리킨다. + +스키마 메타데이터의 `boundary`·`direction`·`unknownFieldPolicy`는 손으로 적지만 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 실제 쓰임과 대조한다. + +- `boundary`: descriptor의 입력·응답·실패 검증기와 라우트의 `paramsSchema`·`searchSchema`에서 쓰인 자리로 정해진다. 다르면 `: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `: no FE-REG-SCHEMA row`. +- `direction`: 입력은 `REQUEST`, 응답·실패는 `RESPONSE`. +- `unknownFieldPolicy`: zod가 모르는 키를 거부하면(`.strict()`) `REJECT_UNKNOWN`, 버리면(`.strip()`) `STRIP_UNKNOWN`. +- 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서 `test:unit`을 돌릴 때 잡힌다. 예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다. @@ -268,8 +276,9 @@ projectRequest: (input) => Object.freeze({ ③ **잡는 검사 / 못 잡는 것** -- descriptor의 입력·응답 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다. - - 메시지: `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` (`responseSchema`도 같다) +- descriptor의 입력·응답·실패 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다. + - 메시지: `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` (`responseSchema`, `problemSchema`도 같다) +- 스키마 메타데이터의 `boundary`·`direction`·`unknownFieldPolicy`가 실제 쓰임과 다르면 `test:unit`의 `tests/unit/schema-metadata-policy.test.ts`가 실패한다(위 "입력과 스키마 메타데이터"). - 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다. - 오류의 `reason`: `/: unknown authProfileId ` - 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index aa3c68f1..c41a802c 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -82,7 +82,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 |---|---|---| | `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-schema-metadata.ts`. 접두어를 붙인다 | | `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.ts`. 접두어를 붙인다 | -| `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`도 같은 꼴) | `contracts/-schema-metadata.ts` | +| `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/-schema-metadata.ts` | +| `: row , used as ` (`tests/unit/schema-metadata-policy.test.ts`) | 스키마 메타 행의 `boundary`가 그 스키마가 쓰인 자리와 다르다. `no FE-REG-SCHEMA row`는 쓰이는데 행이 없다 | `contracts/-schema-metadata.ts` | | `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` | | `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` | | ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 | diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index 12a7f7e3..c1e565d6 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -602,7 +602,10 @@ function renderSchemaMetadata({ names, owner }: Shape): string { * FE-REG-SCHEMA rows of the feature's schemas (\`check:registries\`). The HTTP * operation is written once, in \`${names.base}-contract-contribution.ts\`; * FE-REG-API rows are projected from it. Runtime half only: - * \`feature-runtime.ts\` loads it. + * \`feature-runtime.ts\` loads it. \`boundary\`, \`direction\` and + * \`unknownFieldPolicy\` must say where and how each schema is used: + * tests/unit/schema-metadata-policy.test.ts compares them with the + * descriptors, the routes and the zod validators. */ export const ${upper}_SCHEMA_METADATA = Object.freeze({ ${pascal}NoRequest: Object.freeze({ @@ -623,6 +626,15 @@ export const ${upper}_SCHEMA_METADATA = Object.freeze({ direction: "RESPONSE", unknownFieldPolicy: "STRIP_UNKNOWN", }), + ${pascal}Problem: Object.freeze({ + schemaId: "${pascal}Problem", + boundary: "api-problem", + owner: OWNER, + runtime: "zod", + schemaVersion: 1, + direction: "RESPONSE", + unknownFieldPolicy: "STRIP_UNKNOWN", + }), } as const); `; } diff --git a/src/contracts/schema-registry.ts b/src/contracts/schema-registry.ts index ace442c1..8667fa8f 100644 --- a/src/contracts/schema-registry.ts +++ b/src/contracts/schema-registry.ts @@ -8,7 +8,9 @@ export type SchemaDefinition = Readonly<{ | "route-search" | "route-search-api-request" | "api-request" - | "api-response"; + | "api-response" + /** 1103/16-04. An operation's failure body (`problemValidator`). */ + | "api-problem"; owner: string; runtime: "zod"; schemaVersion?: number; diff --git a/src/features/reference-feature/contracts/reference-schema-metadata.ts b/src/features/reference-feature/contracts/reference-schema-metadata.ts index 6975658f..f31003ba 100644 --- a/src/features/reference-feature/contracts/reference-schema-metadata.ts +++ b/src/features/reference-feature/contracts/reference-schema-metadata.ts @@ -50,4 +50,14 @@ export const REFERENCE_SCHEMA_METADATA = Object.freeze({ direction: "RESPONSE", unknownFieldPolicy: "STRIP_UNKNOWN", }), + // 1103/16-04. FE-REG-API's problemSchema references this row. + ReferenceProblem: Object.freeze({ + schemaId: "ReferenceProblem", + boundary: "api-problem", + owner: "feature-frontend-reference-feature-vertical-slice", + runtime: "zod", + schemaVersion: 1, + direction: "RESPONSE", + unknownFieldPolicy: "STRIP_UNKNOWN", + }), }); diff --git a/tests/unit/schema-metadata-policy.test.ts b/tests/unit/schema-metadata-policy.test.ts index 16923671..287271f6 100644 --- a/tests/unit/schema-metadata-policy.test.ts +++ b/tests/unit/schema-metadata-policy.test.ts @@ -1,6 +1,8 @@ import { describe, expect, it } from "vitest"; import type { RuntimeValidator } from "../../src/contracts/external-contract-runtime.ts"; +import type { SchemaDefinition } from "../../src/contracts/schema-registry.ts"; +import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts"; import { COMPOSED_CONTRACT_CONTRIBUTIONS, SCHEMA_REGISTRY, @@ -66,9 +68,59 @@ const slots = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.flatMap( direction: "RESPONSE" as const, validator: contract.outputValidator, }, + // 1103/16-04. The failure body is read as a response too. + { + operationId: contract.operationId, + direction: "RESPONSE" as const, + validator: contract.problemValidator, + }, ]), ); +type Boundary = SchemaDefinition["boundary"]; + +/** + * 1103/16-04. Where each installed schema is used: an HTTP input, output or + * failure body, or a route's params or search. The row's `boundary` is + * derived from that set; a schema used in two places that no one boundary + * names (an output that is also an input) has no right answer and is listed. + */ +function usesBySchema(): ReadonlyMap> { + const uses = new Map>(); + const add = (schemaId: string | null, use: string) => { + if (schemaId === null) return; + const set = uses.get(schemaId) ?? new Set(); + set.add(use); + uses.set(schemaId, set); + }; + for (const { http } of COMPOSED_CONTRACT_CONTRIBUTIONS.contributions) { + for (const { contract } of http) { + add(contract.inputValidator.schemaId, "http-input"); + add(contract.outputValidator.schemaId, "http-output"); + add(contract.problemValidator.schemaId, "http-problem"); + } + } + for (const route of Object.values(ROUTE_REGISTRY)) { + add(route.paramsSchema, "route-params"); + add(route.searchSchema, "route-search"); + } + return uses; +} + +function boundaryFor(uses: ReadonlySet): Boundary | undefined { + const key = [...uses].sort().join("+"); + const boundaries: Readonly> = { + "http-input": "api-request", + "http-output": "api-response", + "http-problem": "api-problem", + "route-params": "route-params", + "http-input+route-params": "route-params", + "route-search": "route-search", + "http-input+route-search": "route-search-api-request", + }; + return boundaries[key]; +} + // With no installed feature (after the sample is removed) there is nothing to // probe, and both cases pass empty. describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () => { @@ -83,6 +135,22 @@ describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () = expect(wrong).toEqual([]); }); + it("gives every schema an operation or route uses a row at the boundary it is used", () => { + const wrong = [...usesBySchema()].flatMap(([schemaId, uses]) => { + const row = SCHEMA_REGISTRY[schemaId]; + const expected = boundaryFor(uses); + if (row === undefined) return [`${schemaId}: no FE-REG-SCHEMA row`]; + if (expected === undefined) { + return [`${schemaId}: used as ${[...uses].sort().join(" and ")}, which no boundary names`]; + } + return row.boundary === expected + ? [] + : [`${schemaId}: row ${row.boundary}, used as ${expected}`]; + }); + + expect(wrong).toEqual([]); + }); + it("declares the unknown-field policy its validator applies", () => { const wrong = slots.flatMap(({ operationId, validator }) => { const declared = SCHEMA_REGISTRY[validator.schemaId]?.unknownFieldPolicy; diff --git a/tests/unit/second-api-feature-registries.test.ts b/tests/unit/second-api-feature-registries.test.ts index a579b9c3..2dc6ba0d 100644 --- a/tests/unit/second-api-feature-registries.test.ts +++ b/tests/unit/second-api-feature-registries.test.ts @@ -100,6 +100,8 @@ export const SECOND_API_SCHEMAS = Object.freeze({ SecondItemListQuery: schema("SecondItemListQuery", "route-search", "REQUEST"), SecondItemParams: schema("SecondItemParams", "api-request", "REQUEST"), SecondItemPayload: schema("SecondItemPayload", "api-response", "RESPONSE"), + // 1103/16-04. FE-REG-API's problemSchema references a row too. + SecondItemProblem: schema("SecondItemProblem", "api-problem", "RESPONSE"), } as const); export const SECOND_API_CONTRIBUTION: InstalledContractContribution = Object.freeze({