fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-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, 생성 뼈대 <Base>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 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.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
This commit is contained in:
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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": [
|
||||
|
||||
@@ -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"]
|
||||
},
|
||||
|
||||
@@ -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`에서 쓰인 자리로 정해진다. 다르면 `<schemaId>: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `<schemaId>: 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.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` (`responseSchema`도 같다)
|
||||
- descriptor의 입력·응답·실패 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다.
|
||||
- 메시지: `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` (`responseSchema`, `problemSchema`도 같다)
|
||||
- 스키마 메타데이터의 `boundary`·`direction`·`unknownFieldPolicy`가 실제 쓰임과 다르면 `test:unit`의 `tests/unit/schema-metadata-policy.test.ts`가 실패한다(위 "입력과 스키마 메타데이터").
|
||||
- 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다.
|
||||
- 오류의 `reason`: `<featureId>/<operationId>: unknown authProfileId <id>`
|
||||
- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다.
|
||||
|
||||
@@ -82,7 +82,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
||||
|---|---|---|
|
||||
| `Invalid or duplicate schema definition: <schemaId>` | 스키마 ID 중복 또는 메타 형식 | `contracts/<base>-schema-metadata.ts`. 접두어를 붙인다 |
|
||||
| `duplicate operation: <operationId>` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/<base>-contract-contribution.ts`. 접두어를 붙인다 |
|
||||
| `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`도 같은 꼴) | `contracts/<base>-schema-metadata.ts` |
|
||||
| `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`, `problemSchema`도 같은 꼴. 실패 본문 행은 `boundary: "api-problem"`) | `contracts/<base>-schema-metadata.ts` |
|
||||
| `<schemaId>: row <boundary>, used as <boundary>` (`tests/unit/schema-metadata-policy.test.ts`) | 스키마 메타 행의 `boundary`가 그 스키마가 쓰인 자리와 다르다. `no FE-REG-SCHEMA row`는 쓰이는데 행이 없다 | `contracts/<base>-schema-metadata.ts` |
|
||||
| `Unregistered route codec: <codecId>` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/<base>-routes.ts` |
|
||||
| `contract package <packageId> is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/<base>-contract-contribution.ts`의 `source` |
|
||||
| `<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `<BASE>_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
|
||||
|
||||
@@ -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);
|
||||
`;
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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",
|
||||
}),
|
||||
});
|
||||
|
||||
@@ -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<string, ReadonlySet<string>> {
|
||||
const uses = new Map<string, Set<string>>();
|
||||
const add = (schemaId: string | null, use: string) => {
|
||||
if (schemaId === null) return;
|
||||
const set = uses.get(schemaId) ?? new Set<string>();
|
||||
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<string>): Boundary | undefined {
|
||||
const key = [...uses].sort().join("+");
|
||||
const boundaries: Readonly<Record<string, Boundary>> = {
|
||||
"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;
|
||||
|
||||
@@ -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({
|
||||
|
||||
Reference in New Issue
Block a user