From 3b40f736381c9c68c214e1f0b88b2da3b195baf7 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 23:06:52 +0900 Subject: [PATCH] =?UTF-8?q?fix(contracts)!:=20=EC=8A=A4=ED=82=A4=EB=A7=88?= =?UTF-8?q?=20=EB=A9=94=ED=83=80=EC=9D=98=20boundary=EB=A5=BC=20=EC=93=B0?= =?UTF-8?q?=EC=9E=84=EA=B3=BC=20=EB=8C=80=EC=A1=B0=ED=95=98=EA=B3=A0=20?= =?UTF-8?q?=EC=8B=A4=ED=8C=A8=20=EB=B3=B8=EB=AC=B8=20=ED=96=89=EC=9D=84=20?= =?UTF-8?q?=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 -schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이 목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입· 레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과 unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의 problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과 생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)). 고른 방법 - schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의 입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다 쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데 행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패 검증기까지 넓힌다. - boundary에 "api-problem"을 더한다(SchemaDefinition, governance allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를 governance에 더한다. - 참조 기능 ReferenceProblem, 생성 뼈대 Problem, second-api fixture에 실패 본문 행을 더한다. 버린 대안 - 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의 사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가 "빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다. - owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는 "...-vertical-slice"). 그대로 둔다. 위험·한계 - governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다 (REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시 찍는다. - 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다. CHANGELOG에 이행 안내가 필요하다. - 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때 잡힌다. 검증 - RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패. 행을 더한 뒤 통과. - 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row api-request, used as api-response"로 실패. 되돌림. - check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS compatibility=none. - second-api-feature-registries, registry-governance, release-artifacts, create-feature 테스트 통과. check:types, lint, verify:documentation 통과. BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다. 설치된 기능의 problemValidator 스키마마다 -schema-metadata.ts에 boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가 "FE-REG-API..problemSchema references unknown FE-REG-SCHEMA"로 실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04 Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 --- .../contracts/registry-baseline.approval.json | 6 +- config/contracts/registry-baseline.json | 20 +++++- config/contracts/registry-governance.json | 8 ++- docs/manual/01-add-a-feature.md | 13 +++- docs/manual/reference/errors.md | 3 +- scripts/create-feature.ts | 14 +++- src/contracts/schema-registry.ts | 4 +- .../contracts/reference-schema-metadata.ts | 10 +++ tests/unit/schema-metadata-policy.test.ts | 68 +++++++++++++++++++ .../second-api-feature-registries.test.ts | 2 + 10 files changed, 137 insertions(+), 11 deletions(-) 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({