test(contracts): 탐침이 닿지 않는 스키마는 방향만 요구한다

문제: e7b1b01 뒤 정책 테스트는 HTTP 자리 스키마의 행이
unknownFieldPolicy를 빼면 실패하고, 적으면 탐침 결과와 비교한다. 탐침이
객체에 닿지 못하는 검증기(두 탐침을 모두 루트에서 거절: `responseBody:
"NONE"` 출력의 z.undefined(), 문자열·null 본문)는 결과가 UNREACHED다.
행 타입은 REJECT_UNKNOWN·STRIP_UNKNOWN만 받으므로, 그런 operation은 행을
어떻게 적어도 통과하지 못한다. 칸을 빼면 `row states no
unknownFieldPolicy`, STRIP_UNKNOWN을 적으면 `row STRIP_UNKNOWN, validator
UNREACHED`다. 템플릿에는 그런 operation이 없어 다운스트림에서 난다.

고른 방법: 리뷰의 가장 작은 방향. 탐침 결과가 UNREACHED인 자리는 정책
비교에서만 빼고, direction은 그대로 요구한다. 두 검사를 슬롯·행을 받는
함수(directionProblems, policyProblems)로 꺼내, 설치된 descriptor 검사와
가짜 스키마 검사가 같은 함수를 쓴다. 새 describe가 z.undefined() 같은
NoContent 검증기로 탐침이 UNREACHED인지, 행이 direction을 빼면 실패하는지,
정책을 빼거나 적어도 통과하는지 본다. 매뉴얼 01, errors.md, CHANGELOG
1106 절의 먼저 할 일 1과 07-02 행에 적었다.
검사를 느슨하게 한 것이 아닌 이유: 탐침은 객체가 없는 스키마의 모르는
필드 정책을 판정할 수 없다. 그 자리의 비교는 맞는 답이 없는 질문이었다.
e7b1b01 전에는 칸을 빼면 이 자리 전체를 건너뛰었다. 지금은 direction을
요구하므로 그때보다 넓다. 객체에 닿는 스키마의 정책 비교는 그대로다.
버린 대안: 행 타입에 객체가 아닌 본문용 값을 더한다. src/contracts의
SchemaDefinition 모양, 분류기, 기준선이 함께 바뀐다.

위험·한계: 행이 UNREACHED 스키마에 적은 정책 값은 아무도 검사하지 않는다.
루트에서 이슈 하나로 거절하는 union(zod `invalid_union`, 예:
strict 객체 | null)도 UNREACHED가 되어 정책 비교에서 빠진다(추론, 실행하지
않음). 고친 곳이 테스트 파일 자신이라 RED는 테스트 파일만으로
만들 수 없다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts

Refs: 1106/07-02 (diff review DR-04)
This commit is contained in:
DongHyeonka
2026-11-06 07:58:07 +09:00
parent eb03dabdfd
commit efe11f1581
4 changed files with 94 additions and 27 deletions
+2 -2
View File
@@ -23,7 +23,7 @@
#### 옮기는 법
1. **HTTP 스키마 행에 `direction`·`unknownFieldPolicy`를 적는다.** descriptor의 입력·응답·실패 검증기로 쓰이는 스키마의 FE-REG-SCHEMA 행이 둘 중 하나를 빼면 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 `row states no direction, used as <방향>`이나 `row states no unknownFieldPolicy, validator <탐침 결과>`로 실패한다. 행이 아예 없으면 같은 메시지와 `no FE-REG-SCHEMA row`가 나온다. 라우트에만 쓰는 행은 그대로 둬도 된다. memento-web이 2026-11-03 조치 절 "옮기는 법" 5단계로 더하는 43행도 두 칸을 적는다 (1106/07-02)
1. **HTTP 스키마 행에 `direction`·`unknownFieldPolicy`를 적는다.** descriptor의 입력·응답·실패 검증기로 쓰이는 스키마의 FE-REG-SCHEMA 행이 둘 중 하나를 빼면 `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 `row states no direction, used as <방향>`이나 `row states no unknownFieldPolicy, validator <탐침 결과>`로 실패한다. 행이 아예 없으면 같은 메시지와 `no FE-REG-SCHEMA row`가 나온다. 라우트에만 쓰는 행은 그대로 둬도 된다. 객체가 아닌 본문의 검증기(`responseBody: "NONE"` 출력의 `z.undefined()` 등)는 탐침이 정책을 판정할 수 없어 `direction`만 요구한다. memento-web이 2026-11-03 조치 절 "옮기는 법" 5단계로 더하는 43행도 두 칸을 적는다 (1106/07-02)
2. **`src/presentation/i18n/catalog.ts`를 고친 제품은 `form.resendLater`를 한국어·영어 두 catalog에 더한다.** 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전에 거절되면 폼이 이 문구를 보인다. 키가 없으면 그 자리에 `common.unavailable` 문구가 나오고, 한 언어에만 있으면 `check:i18n`이 실패한다 (1106/03-01)
3. **디자인 토큰 CSS를 고친 제품은 `src/presentation/design-system/tokens/component.css`의 `--dialog-backdrop-weight`·`--dialog-backdrop`·`--dialog-backdrop-on-surface`를 가져온다.** `primitives.css`의 `.ui-dialog::backdrop`과 `:root:has(.ui-dialog[open])`이 이 토큰을 읽는다. 빠지면 modal 가림막이 투명해지고, 그것을 잡는 검사는 없다. memento는 이 파일을 고쳤다 (1106/08-03)
4. **IDEMPOTENT로 선언한 쓰기가 두 번 적용해도 결과가 같은지 확인한다.** `...commandMutationIdentity(<descriptor>)`로 받은 정책은 이제 `resendSafe`를 싣는다. 그래서 IDEMPOTENT 쓰기는 결과 불명 뒤 재전송 버튼이 그려지고, 같은 입력 저장이 `UNKNOWN_EFFECT_PENDING`으로 거절되지 않는다. 백엔드가 중복을 막지 못하는 쓰기를 IDEMPOTENT로 적었다면 사용자가 다시 보내 같은 항목이 둘 생길 수 있다(매뉴얼 02 결정표 3절). memento-web의 IDEMPOTENT 쓰기는 아래 절 2단계로 옮기면 여기에 든다. `commandMutationIdentity` 결과를 `toEqual`로 비교하던 테스트는 `resendSafe`를 더한다 (1106/03-03)
@@ -46,7 +46,7 @@
| [계약] | FE-GATE-019 live probe가 `/service-worker.js`를 같은 origin 안 redirect 뒤에 준 호스트를 FAIL로 본다(`serviceWorker` surface의 `redirect` 행, `response.redirected`나 `opaqueredirect`). 브라우저는 워커 스크립트를 redirect mode "error"로 받는다. `index`·`appRoute`의 redirect는 전처럼 받는다. 위 "옮긴 뒤 확인" 4 (1106/06-01) | `scripts/lib/hosting-probe.ts`, `docs/operations/release-cache-rollback.md`, `docs/operations/browser-file-storage-recovery.md` | `2a78169` |
| [계약] | `check:bundle`의 `generate-supply-chain.ts`·`check-bundle.ts`가 `RUN_OUTPUT_ROOT`가 비어 있지 않고 `.`도 아니면 변수 값과 이유를 적고 exit 1로 멈춘다. 빌드는 그 경로 아래에 쓰는데 두 스크립트는 checkout의 `dist`·`artifacts/`를 읽어서, 예산을 넘는 새 빌드 대신 이전 빌드로 PASS했다. `ci:gate -- FE-GATE-012`도 check-bundle 단계에서 멈춘다 (1106/12-02) | `scripts/lib/run-isolation.ts`, `scripts/check-bundle.ts`, `scripts/generate-supply-chain.ts`, `docs/testing/frontend-platform-testing-strategy.md` | `68fde02` |
| [계약] | `test:a11y`(FE-GATE-009)의 report(`scripts/write-a11y-report.ts`)가 설치된 descriptor로 한 자원을 읽는 라우트를 찾는다. 로그인이 필요한 라우트의 `paramsSchema`가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마인 경우다. 그 라우트에 실패 화면 기록(`artifacts/tests/a11y-data-state/`)이 없으면 `a11y.json not written:`으로 실패하고 `a11y.json`을 쓰지 않는다. 접근성 spec의 라우트 test는 시작할 때 자기 기록을 지운다. `paramsSchema`가 GET 입력과 다른 상세 라우트는 전처럼 기록만으로 정해진다 (1106/11-01) | `scripts/lib/a11y-data-state.ts`, `scripts/write-a11y-report.ts`, `tests/e2e/accessibility.spec.ts` | `9c4cddc` |
| [계약] | `tests/unit/schema-metadata-policy.test.ts`가 descriptor의 입력·응답·실패 검증기로 쓰인 스키마 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 실패한다. 전에는 건너뛰어서, 응답 DTO를 strict로 바꿔도 `check:registries`와 `test:unit` 어느 쪽도 보지 않았다. 템플릿 HTTP 행과 생성기가 쓰는 행은 이미 두 칸을 적는다. 위 "먼저 할 일" 1단계 (1106/07-02) | `tests/unit/schema-metadata-policy.test.ts`, `docs/manual/01-add-a-feature.md`, `docs/manual/reference/errors.md` | `e7b1b01` |
| [계약] | `tests/unit/schema-metadata-policy.test.ts`가 descriptor의 입력·응답·실패 검증기로 쓰인 스키마 행이 `direction`·`unknownFieldPolicy`를 적지 않으면 실패한다. 전에는 건너뛰어서, 응답 DTO를 strict로 바꿔도 `check:registries`와 `test:unit` 어느 쪽도 보지 않았다. 템플릿 HTTP 행과 생성기가 쓰는 행은 이미 두 칸을 적는다. 탐침이 객체에 닿지 못하는 검증기(객체가 아닌 본문)는 `direction`만 요구한다. 위 "먼저 할 일" 1단계 (1106/07-02) | `tests/unit/schema-metadata-policy.test.ts`, `docs/manual/01-add-a-feature.md`, `docs/manual/reference/errors.md` | `e7b1b01` |
| [계약] | 제품 기능 제거 드릴의 `tests` 잔여에, 본문이 기능 ID나 폴더 이름을 적힌 그대로(대소문자 구분) 한 이름(앞뒤가 `[A-Za-z0-9_-]`가 아님)으로 적은 Playwright spec(`*.spec.[cm]?[jt]sx?`)이 든다. `-`가 든 이름만 찾는다. `messages`·`status` 같은 한 단어 ID는 템플릿 spec이 평범한 단어로 쓰므로 찾지 않는다. vitest는 spec을 돌지 않아 `test:all`도 잡지 못했다. vitest 테스트 본문은 전처럼 보지 않는다. 매뉴얼 01 11단계와 `errors.md`의 판정 문장을 고쳤다 (1106/16-01) | `scripts/lib/feature-residue.ts`, `docs/manual/` | `af3344b` |
| [계약] | KEYED 결과 불명 요청을 같은 키로 다시 보낸 시도가 쓰기 전 거절(429, 503 `RATE_LIMIT_*`, 401)이나 보내기 전 실패(`NOT_STARTED`)로 끝나면, 훅이 결과 불명과 intent·키를 남긴다. 전에는 그 판정을 논리 요청 전체의 판정으로 써서 다음 저장이 새 키로 나갔다. 실패는 그대로 돌려주고, `Retry-After`는 다음 재전송의 대기 시각이 되고, 낙관적 층은 되돌리지 않고 불확실로 둔다. 폼은 결과 불명 화면을 그대로 두고 `form.resendLater` 문구로 feedback에 포커스를 옮긴다. 처음 보낸 요청의 `NOT_APPLIED`와 재전송의 성공은 전처럼 정리한다. 메인 세션 결정 D10이다. 위 "먼저 할 일" 2단계 (1106/03-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/i18n/catalog.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `2568587` |
| [계약] | `commandMutationIdentity`가 `resendSafe`(`retrySemantics`가 `KEYED`나 `IDEMPOTENT`)도 돌려주고, `BoundMutation`에 선택 칸 `resendSafe?`가 생겼다(추가만). 결과 불명 뒤 재전송 버튼과 같은 입력 재제출 거절(아래 절 0929/03-03 행)이 키 유무 대신 "키가 있거나 `resendSafe`"를 본다. 그래서 IDEMPOTENT 쓰기도 다시 보낼 수 있다. 칸이 없는 손 정책과 NEVER는 전과 같다. 위 "먼저 할 일" 4단계 (1106/03-03) | `src/contracts/server-state.ts`, `src/presentation/adapters/query/application-query.ts`, `src/application/view-models/async-state.ts`, `docs/manual/` | `815ea58` |
+1 -1
View File
@@ -269,7 +269,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는
- `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`.
- descriptor의 입력·응답·실패 검증기로 쓰인 스키마의 행은 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 `row states no direction` 또는 `row states no unknownFieldPolicy`로 실패한다(1106/07-02). 칸이 없으면 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`가 breaking으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다.
- descriptor의 입력·응답·실패 검증기로 쓰인 스키마의 행은 `direction`·`unknownFieldPolicy`를 빼지 않는다. 빼면 `row states no direction` 또는 `row states no unknownFieldPolicy`로 실패한다(1106/07-02). 칸이 없으면 응답 DTO를 `.strict()`로 바꿔도 행이 바뀌지 않아 `check:registries`가 breaking으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다. 모르는 필드를 볼 객체가 없는 검증기(`responseBody: "NONE"` 출력의 `z.undefined()`, 문자열·null 본문)는 `direction`만 본다.
- 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서 `test:unit`을 돌릴 때 잡힌다.
예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다.
+1 -1
View File
@@ -86,7 +86,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| `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`, `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` |
| `<operationId> <schemaId>: row states no direction, used as <direction>` 또는 `row states no unknownFieldPolicy, validator <policy>` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/<base>-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다 |
| `<operationId> <schemaId>: row states no direction, used as <direction>` 또는 `row states no unknownFieldPolicy, validator <policy>` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/<base>-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다. 객체가 아닌 본문의 검증기(`z.undefined()` 등)는 `direction`만 요구한다 |
| `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` 하나를 쓰게 한다 |
+90 -23
View File
@@ -26,8 +26,9 @@ import {
* them out used to be skipped here. 1105/07-02 grades a response row whose
* policy turns `REJECT_UNKNOWN` as breaking, but a row with no policy does not
* change when its DTO turns `.strict()`, so nothing saw it. A schema an HTTP
* operation uses now fails here without them. Route-only rows (`NotFoundSplat`)
* are not in `slots` and still need neither.
* operation uses now fails here without them; the policy only where the probe
* reaches an object (`policyProblems`). Route-only rows (`NotFoundSplat`) are
* not in `slots` and still need neither.
*/
const PROBE_KEY = "__unknownFieldProbe";
@@ -84,6 +85,44 @@ const slots = COMPOSED_CONTRACT_CONTRIBUTIONS.contributions.flatMap(
]),
);
type Slot = Readonly<{
operationId: string;
direction: "REQUEST" | "RESPONSE";
validator: RuntimeValidator<unknown>;
}>;
type Rows = Readonly<Record<string, SchemaDefinition | undefined>>;
function directionProblems(used: readonly Slot[], rows: Rows): string[] {
return used.flatMap(({ operationId, direction, validator }) => {
const declared = rows[validator.schemaId]?.direction;
return declared === direction
? []
: [
`${operationId} ${validator.schemaId}: row ${declared ?? "states no direction"}, used as ${direction}`,
];
});
}
/**
* 1106/07-02 (diff review DR-04). A validator the probe cannot reach, one
* that refuses both probes at the root (`z.undefined()` for a
* `responseBody: "NONE"` output, a string or null payload), has no object
* level to judge, and no row value equals `UNREACHED`. Its policy is not
* compared; `directionProblems` still requires its `direction`.
*/
function policyProblems(used: readonly Slot[], rows: Rows): string[] {
return used.flatMap(({ operationId, validator }) => {
const probed = probeUnknownFieldPolicy(validator);
if (probed === "UNREACHED") return [];
const declared = rows[validator.schemaId]?.unknownFieldPolicy;
return probed === declared
? []
: [
`${operationId} ${validator.schemaId}: row ${declared ?? "states no unknownFieldPolicy"}, validator ${probed}`,
];
});
}
type Boundary = SchemaDefinition["boundary"];
/**
@@ -132,16 +171,7 @@ function boundaryFor(uses: ReadonlySet<string>): Boundary | undefined {
// probe, and both cases pass empty.
describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () => {
it("declares the direction each schema is used in", () => {
const wrong = slots.flatMap(({ operationId, direction, validator }) => {
const declared = SCHEMA_REGISTRY[validator.schemaId]?.direction;
return declared === direction
? []
: [
`${operationId} ${validator.schemaId}: row ${declared ?? "states no direction"}, used as ${direction}`,
];
});
expect(wrong).toEqual([]);
expect(directionProblems(slots, SCHEMA_REGISTRY)).toEqual([]);
});
it("gives every schema an operation or route uses a row at the boundary it is used", () => {
@@ -161,16 +191,53 @@ describe("FE-REG-SCHEMA policy of the installed HTTP schemas (1103/07-03)", () =
});
it("declares the unknown-field policy its validator applies", () => {
const wrong = slots.flatMap(({ operationId, validator }) => {
const declared = SCHEMA_REGISTRY[validator.schemaId]?.unknownFieldPolicy;
const probed = probeUnknownFieldPolicy(validator);
return probed === declared
? []
: [
`${operationId} ${validator.schemaId}: row ${declared ?? "states no unknownFieldPolicy"}, validator ${probed}`,
];
});
expect(wrong).toEqual([]);
expect(policyProblems(slots, SCHEMA_REGISTRY)).toEqual([]);
});
});
// 1106/07-02 (diff review DR-04). No row value passed for such a schema: the
// policy check asked for a field and then compared it with `UNREACHED`.
describe("FE-REG-SCHEMA policy of a schema the probe cannot reach (1106/07-02)", () => {
const noContent: RuntimeValidator<unknown> = {
schemaId: "NoContent",
safeParse: (value) =>
value === undefined
? { success: true, data: value }
: { success: false, issues: [{ path: [], code: "invalid_type" }] },
};
const used: readonly Slot[] = [
{ operationId: "DELETE_THING", direction: "RESPONSE", validator: noContent },
];
const rows = (
fields: Pick<SchemaDefinition, "direction" | "unknownFieldPolicy">,
): Rows => ({
NoContent: {
schemaId: "NoContent",
boundary: "api-response",
owner: "test",
runtime: "zod",
...fields,
},
});
it("is a schema the probe cannot reach", () => {
expect(probeUnknownFieldPolicy(noContent)).toBe("UNREACHED");
});
it("still needs its direction", () => {
expect(directionProblems(used, rows({}))).toEqual([
"DELETE_THING NoContent: row states no direction, used as RESPONSE",
]);
expect(directionProblems(used, rows({ direction: "RESPONSE" }))).toEqual([]);
});
it("is not held to an unknown-field policy", () => {
expect(policyProblems(used, rows({ direction: "RESPONSE" }))).toEqual([]);
expect(
policyProblems(
used,
rows({ direction: "RESPONSE", unknownFieldPolicy: "STRIP_UNKNOWN" }),
),
).toEqual([]);
});
});