diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ce1f407..d113c570 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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()`로 받은 정책은 이제 `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` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 37b65111..96374ad3 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -269,7 +269,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 - `boundary`: descriptor의 입력·응답·실패 검증기와 라우트의 `paramsSchema`·`searchSchema`에서 쓰인 자리로 정해진다. 다르면 `: row <적은 값>, used as <맞는 값>`으로 실패한다. 쓰이는데 행이 없으면 `: 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. 입력에 관한 칸과 응답 모양 줄만 적었다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 0b7aa1e4..7b875aa4 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -86,7 +86,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.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` | -| ` : row states no direction, used as ` 또는 `row states no unknownFieldPolicy, validator ` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다 | +| ` : row states no direction, used as ` 또는 `row states no unknownFieldPolicy, validator ` (`tests/unit/schema-metadata-policy.test.ts`) | descriptor가 쓰는 스키마의 행이 `direction`·`unknownFieldPolicy`를 적지 않았다(1106/07-02) | `contracts/-schema-metadata.ts`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다. 객체가 아닌 본문의 검증기(`z.undefined()` 등)는 `direction`만 요구한다 | | `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/tests/unit/schema-metadata-policy.test.ts b/tests/unit/schema-metadata-policy.test.ts index f33f0e88..c0833bda 100644 --- a/tests/unit/schema-metadata-policy.test.ts +++ b/tests/unit/schema-metadata-policy.test.ts @@ -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; +}>; +type Rows = Readonly>; + +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): 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 = { + 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, + ): 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([]); }); });