diff --git a/CHANGELOG.md b/CHANGELOG.md index f1a6e323..56da8040 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) @@ -33,7 +33,7 @@ #### 옮긴 뒤 확인 1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `test:unit`(1단계), `check:i18n`(2단계), `check:ci`(5단계), `check:types`(6단계), `test:a11y`(FE-GATE-009. 한 자원을 읽는 상세 라우트에 실패 화면 기록이 없으면 `a11y.json not written:`으로 실패한다), `check:bundle`(셸에 `RUN_OUTPUT_ROOT`가 있으면 멈춘다. 지우고 돈다). -2. 제품 기능 제거 드릴(`test:sample-removal -- --feature=`)은 본문에 그 기능 ID를 한 이름으로 적은 Playwright spec을 잔여로 센다. +2. 제품 기능 제거 드릴(`test:sample-removal -- --feature=`)은 본문에 그 기능 ID를 적힌 그대로 한 이름으로 적은 Playwright spec을 잔여로 센다. `-`가 없는 한 단어 ID는 spec 본문에서 찾지 않는다. 3. 시각 골든: `base.css`·`primitives.css`를 받은 제품은 열린 modal을 찍은 자기 골든을 다시 찍는다(`corepack pnpm test:visual:update`). 새 시각 검사 `tests/visual/scrollbar-gutter.visual.spec.ts`는 템플릿 셸의 메뉴 버튼과 `/not-found`를 쓴다. 셸을 바꾼 제품은 그 spec을 자기 셸에 맞춘다. 제품 셸에서는 돌려 보지 않았다. 4. 배포가 있는 제품: `/service-worker.js`를 redirect 뒤에 주는 호스트는 FE-GATE-019가 FAIL이다. 그런 호스트에서는 지금도 워커 등록·업데이트·kill switch가 실패한다. 5. 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)이 충돌하면 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`를 다시 돌려 푼다. @@ -45,9 +45,9 @@ | [계약] | FE-GATE-027이 `scan:dependency-advisories`를 `check:release-admission`보다 먼저 돈다. 공개 대상 승인이 거절된 run에도 advisory 기록(`artifacts/security/dependency-advisories.json`)이 생긴다. FE-GATE-015가 실패하면 FE-GATE-027이 돌지 않아 기록이 없다. 승인 판정과 gate 결과는 그대로이고, 거절되는 run은 scan 시간(상한 120초)만큼 늦게 끝난다. 생성 workflow는 그대로다. gate 모양 기준선 `gateShapeSha256`을 다시 기록했다. 위 "먼저 할 일" 5단계 (1106/13-01) | `config/ci/gates.json`, `config/ci/contract-baseline.json`, `scripts/scan-dependency-advisories.ts`, `docs/operations/ci-quality-gates.md` | `c5ab7a3` | | [계약] | 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` 잔여에, 본문이 기능 ID나 폴더 이름을 한 이름(앞뒤가 영문·숫자·`-`가 아님)으로 적은 Playwright spec(`*.spec.[cm]?[jt]sx?`)이 든다. vitest는 spec을 돌지 않아 `test:all`도 잡지 못했다. vitest 테스트 본문은 전처럼 보지 않는다. 매뉴얼 01 11단계와 `errors.md`의 판정 문장을 고쳤다 (1106/16-01) | `scripts/lib/feature-residue.ts`, `docs/manual/` | `af3344b` | +| [계약] | `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 입력과 다른 상세 라우트는 전처럼 기록만으로 정해진다. 그 GET을 부르지 않는 페이지의 라우트(하위 항목 작성 폼 등)가 GET 입력 스키마를 `paramsSchema`로 쓰면 이 검사가 실패한다. 그 라우트에 자기 `paramsSchema`를 따로 둔다 (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 행과 생성기가 쓰는 행은 이미 두 칸을 적는다. 탐침이 객체에 닿지 못하는 검증기(객체가 아닌 본문)는 `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, 401, 403, 503 `RATE_LIMIT_*`, 422 `IDEMPOTENT_REQUEST_MISMATCH`, 기능이 선언한 code)이나 보내기 전 실패(`NOT_STARTED`)로 끝나면, 훅이 결과 불명과 intent·키를 남긴다. 전에는 그 판정을 논리 요청 전체의 판정으로 써서 다음 저장이 새 키로 나갔다. 실패는 그대로 돌려주고, `Retry-After`는 다음 재전송의 대기 시각이 되고, 낙관적 층은 되돌리지 않고 불확실로 둔다. 폼은 결과 불명 화면(확인·다시 보내기)을 그대로 두고 `form.resendLater` 문구로 feedback에 포커스를 옮긴다. 같은 요청이 매번 받는 거절(`isRefusedOnEveryAttempt`: 입력 검증 `VALIDATION_REJECTED`, 400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID`)은 첫 요청도 거절됐다는 뜻이라 결과 불명을 풀고, 폼은 필드 오류를 보이고 저장을 다시 받는다. 처음 보낸 요청의 `NOT_APPLIED`와 재전송의 성공은 전처럼 정리한다. 메인 세션 결정 D10과 그 보충이다. 위 "먼저 할 일" 2단계 (1106/03-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/contracts/errors.ts`, `src/presentation/i18n/catalog.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `2568587`, `80e7f1d` | | [계약] | `commandMutationIdentity`가 `resendSafe`(`retrySemantics`가 `KEYED`나 `IDEMPOTENT`)도 돌려주고, `BoundMutation`에 선택 칸 `resendSafe?`가 생겼다(추가만). 결과 불명 뒤 재전송 버튼과 같은 입력 재제출 거절(아래 절 0929/03-03 행)이 키 유무 대신 "키가 있거나 `resendSafe`"를 본다. 그래서 IDEMPOTENT 쓰기도 다시 보낼 수 있다. 그 재전송도 위 1106/03-01 행의 규칙을 따른다. 기능 분류기가 적용 안 됨으로 읽는 404·412 같은 code는 첫 요청이 이미 적용됐을 때 흔한 답이라 결과 불명을 남기고, 입력 검증 거절만 푼다. 칸이 없는 손 정책과 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`, `80e7f1d` | | [계약] **BREAKING** | `createBoundedPollCoordinator`와 `BoundedPollCoordinatorDependencies`에 타입 인자 `Operation extends BoundedPollOperation = BoundedPollOperation`이 생겼다. `operation`과 `execute`의 `input.operation`이 그 타입이라, 실행기 호출이 기능 descriptor의 입력·출력 타입으로 검사된다. 런타임 동작은 같다. realtime 설계 9.2절에 V3 실행기 결과 kind마다 poll 결과(kind, retryable, `retryAfterMs`)를 적은 표가 생겼다. 표대로 조합하면 401·403은 요청 한 번으로 lease를 끝낸다. 표는 조합 코드가 따를 규칙이고 강제하지 않는다. 위 "먼저 할 일" 6단계 (1106/04-02) | `src/adapters/realtime/polling/bounded-poll-coordinator.ts`, `src/application/policies/bounded-polling.ts`, `docs/architecture/realtime-events-web-push-and-bounded-polling.md` | `6f06e77` | @@ -75,7 +75,7 @@ - 일부: poll 조합 코드가 `input.operation`을 무시하고 다른 descriptor를 넘기는 것은 여전히 막지 않는다. 이제 `input.operation`이 descriptor 타입을 가져 그 길을 쓰기가 더 쉽다. 9.2절 표는 규칙이고, 템플릿은 poll `execute` 기본 구현을 주지 않는다 (1103/04-01, 1106/04-02). - 일부: reconnect `attempt` 안에서 연결을 만드는 조합 코드는 설정 오류가 여전히 서버 장애로 보인다. 규칙만 적었다 (1106/04-01). - 일부: 결과 불명 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남고, 다시 보내기는 `Retry-After`(상한 5초)를 기다린다. 폼 밖에서 부른 같은 입력 재저장이 `NOT_APPLIED`로 끝나면 훅은 키를 지키지만 폼은 retry-later를 보인다. 기능이 선언한 결정적 거절(생성 기능의 400 `_INVALID`)은 어느 쪽인지 알 수 없어 재전송 뒤에도 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다 (1106/03-01). -- 일부: 기능 제거 드릴은 route ID나 URL만 적은 spec을 잡지 못하고, 다운스트림 spec이 다른 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 부분 문자열 검색의 거짓 양성과 dist 빌드 잔여 검사는 그대로다 (1106/16-01, 1105/16-04). +- 일부: 기능 제거 드릴은 route ID나 URL만 적은 spec과 한 단어 기능 ID만 적은 spec을 잡지 못하고, 다운스트림 spec이 다른 이유로 `-`가 든 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 부분 문자열 검색의 거짓 양성과 dist 빌드 잔여 검사는 그대로다 (1106/16-01, 1105/16-04). - 일부: `:has()`를 모르는 브라우저(Firefox 121 미만 등)는 전처럼 가림막 옆에 띠가 남는다. 오른쪽 drawer, RTL, Firefox, WebKit은 보지 않았다 (1106/08-03). - 일부: Cache Storage release marker 본문이 계속 읽히지 않으면 stage가 marker를 다시 쓰지 않는다. `replaceUnreadablePointer`는 active pointer만 푼다 (1105/02-02, 1106/02-01). - 일부: 초기 JS 예산의 폭과 되돌림 규칙은 문서에만 있다. 예산 값을 규칙 밖으로 바꿔도 실패하는 테스트는 없다 (1106/15-01). diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index cdb83b44..34d9bff8 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. 입력에 관한 칸과 응답 모양 줄만 적었다. @@ -433,6 +433,7 @@ projectRequest: (input) => Object.freeze({ - API 요청은 설치된 descriptor에서 method와 `pathTemplate`으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope)으로 답한다. 그 뒤 경고 상자(`role="alert"`)가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다. - 한 자원을 읽는 조회(경로 파라미터가 있고 빈 목록을 받지 않는 GET)에는 빈 목록 말고 답할 것이 없다. 그래서 상세 페이지는 실패 상태로 그려지고, 테스트 결과에 `a11y-data-state` annotation이 남는다. - `a11y.json`은 그 라우트를 통과(`scope`)가 아니라 `notChecked`에 적는다. report(`scripts/write-a11y-report.ts`)는 라우트의 `paramsSchema`가 그런 GET의 입력 스키마이면 descriptor만 보고 그 라우트를 `notChecked`로 기대한다. spec이 기록을 남기지 않으면 `a11y.json not written:`으로 실패한다(1106/11-01). 생성 명령의 상세 라우트는 GET과 같은 `Params`를 쓰므로 이 규칙에 든다. + - 그 GET을 부르지 않는 페이지의 라우트(예: 상세 아래의 하위 항목 작성 폼 `/things/:thingId/parts/new`)는 상세 GET의 입력 스키마를 `paramsSchema`로 쓰지 않는다. 같은 스키마를 쓰면 report가 기록을 기대하는데 spec은 한 자원 응답을 보지 못해 기록을 남기지 않으므로 실패한다. 그 라우트에 자기 `paramsSchema`(예: `ThingPartCreateParams`)를 따로 둔다. - 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(`requests no installed list or single-resource read answers`). - spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: `heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다. - 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_HOME`을 쓴다. `docs/architecture/starter-experience.md`의 "Product home and layouts" 절을 본다. @@ -660,11 +661,12 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature ③ **잡는 검사 / 못 잡는 것** -- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다. +- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에 `-`가 든 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` - 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. - - spec 본문은 이름 단위로 찾는다(1106/16-01). `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다. -- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. + - spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에 `[A-Za-z0-9_-]`가 붙으면 다른 이름이다. `test.describe("invoice-feature", …)`는 잔여이고, `product-feature`를 지울 때 `generate-product-feature-index.ts`처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은 `test:all`(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다. + - `-`가 없는 한 단어 ID·폴더 이름(`messages`, `status`)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(`status: 200`, `getByRole("status")`) 찾으면 템플릿 spec이 잔여로 나온다. +- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec, `artifacts/tests/a11y-manual/.md`. 기능 전용 spec은 [03 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. vitest 테스트(`*.test.ts`) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 8eded627..3595a75f 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` 하나를 쓰게 한다 | @@ -178,7 +178,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 |---|---|---| | `artifacts/tests/a11y-manual/ has no record for route IDs: ` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 | | `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 | -| `a11y.json not written:` 다음 `a11y: reads one resource () but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록을 남기지 않았다(1106/11-01). 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`). 기능 파일은 고치지 않는다 | +| `a11y.json not written:` 다음 `a11y: reads one resource () but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | 페이지가 그 GET을 부르면 `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: `/things/:thingId/parts/new` 같은 하위 항목 작성 폼이 상세 GET과 같은 `ThingParams`를 쓴다) 그 라우트에 자기 `paramsSchema`를 따로 둔다. 기능의 라우트 계약과 `contracts/-schema-metadata.ts`를 고친다 | | `Manual accessibility evidence is incomplete:` 다음 `: ` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) | | `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 | | ` names paths that do not exist: ` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 | @@ -198,6 +198,6 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | 메시지 | 원인 | 고칠 곳 | |---|---|---| -| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일, 본문에 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 지운 기능 전용 spec이면 지운다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | +| ` removal failed:` 다음 `fixture-id-residue: residue: ` (`test:sample-removal`) | 기능을 지운 뒤에도 그 기능을 가리키는 파일이 남았다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름이 기능 ID를 담거나 기능 폴더(`src/features//`, `tests/features//`)에서 import하는 파일, 본문에 `-`가 든 기능 ID나 폴더 이름을 적힌 그대로 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 지운 기능 전용 spec이면 지운다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | | `No installed feature declares FEATURE_MODULE_ID ""` | `--feature=`에 없는 기능 ID | 명령 인자 | | `feature scaffold failed:` 다음 `: ` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 | diff --git a/scripts/lib/a11y-data-state.ts b/scripts/lib/a11y-data-state.ts index e3d8a2fa..07db68ab 100644 --- a/scripts/lib/a11y-data-state.ts +++ b/scripts/lib/a11y-data-state.ts @@ -157,7 +157,7 @@ export function oneResourceRoutesCountedAsChecked( .filter(({ routeId }) => !recorded.has(routeId)) .map( ({ routeId, operationIds }) => - `${routeId} reads one resource (${operationIds.join(", ")}) but has no failure-state record in ${A11Y_DATA_STATE_DIRECTORY}; tests/e2e/accessibility.spec.ts must record why it scanned the route on its failure state only`, + `${routeId} reads one resource (${operationIds.join(", ")}) but has no failure-state record in ${A11Y_DATA_STATE_DIRECTORY}; tests/e2e/accessibility.spec.ts must record why it scanned the route on its failure state only, or, when the route's page does not call that read, the route needs a params schema of its own`, ), ); } diff --git a/scripts/lib/feature-residue.ts b/scripts/lib/feature-residue.ts index 757a4051..459a6262 100644 --- a/scripts/lib/feature-residue.ts +++ b/scripts/lib/feature-residue.ts @@ -22,10 +22,17 @@ import path from "node:path"; * `tests/`, vitest.config.ts), and no step of the drill runs a Playwright * spec. So a spec (`*.spec.ts`) that names the feature only in its text, * such as `test.describe("invoice-feature", ...)`, is residue: its text is - * searched for the ID or folder name as a whole kebab-case name. A longer - * name that contains it (`generate-product-feature-index.ts` for - * `product-feature`) does not count. A spec that names only the feature's - * routes or URLs is not found; 03's hand list removes the feature's specs. + * searched for the ID or folder name as written, case-sensitive, with no + * identifier character (`[A-Za-z0-9_-]`) on either side. A longer name + * that contains it (`generate-product-feature-index.ts` for + * `product-feature`, `KO_MESSAGES` for `messages`) does not count. A spec + * that names only the feature's routes or URLs is not found; 03's hand list + * removes the feature's specs. + * Diff review DR-02: only a name with a hyphen is searched. A one-word ID + * or folder (`status`, `reports`, `messages`) is an ordinary word in the + * template's own specs (`status: 200`, `getByRole("status")`, "reports" in + * a test title), and no text rule tells that from a reference, so a spec + * that names only a one-word ID is not found either. * * The reference sample keeps its own, wider pattern in * scripts/test-sample-removal.ts: the template owns all of its files. @@ -56,7 +63,13 @@ export async function productFeatureResidue( String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`, "u", ); - const wholeName = new RegExp(`(? name.includes("-")) + .map(escapeRegExp); + const wholeName = + specNames.length === 0 + ? null + : new RegExp(`(? path.relative(root, file).split(path.sep).join("/"); @@ -70,7 +83,7 @@ export async function productFeatureResidue( if ( named.test(name) || imported.test(text) || - (playwrightSpec.test(name) && wholeName.test(text)) + (wholeName !== null && playwrightSpec.test(name) && wholeName.test(text)) ) { residue.push(name); } diff --git a/tests/unit/feature-residue.test.ts b/tests/unit/feature-residue.test.ts index 657a77d8..7b3f374c 100644 --- a/tests/unit/feature-residue.test.ts +++ b/tests/unit/feature-residue.test.ts @@ -1,4 +1,4 @@ -import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import path from "node:path"; @@ -100,6 +100,39 @@ describe("product feature residue (1105/16-04)", () => { ).toEqual([]); }); + // 1106/16-01 (diff review DR-02). The spec search ignored case and took + // `_` as a boundary, so removing a feature named `messages` counted the + // template's accessibility spec (`KO_MESSAGES`), and `status` or `reports` + // counted a dozen template specs that use the word. + it("does not count the template's own specs for common feature IDs", async () => { + const specs: Record = {}; + for (const entry of await readdir("tests", { recursive: true })) { + const file = path.join("tests", entry).split(path.sep).join("/"); + if (/\.spec\.[cm]?[jt]sx?$/u.test(file)) specs[file] = await readFile(file, "utf8"); + } + expect(Object.keys(specs)).toContain("tests/e2e/accessibility.spec.ts"); + // A copy of the specs alone: `src` is searched by substring (1105/16-04). + const root = await fixture(specs); + + for (const id of ["product-feature", "messages", "status", "reports"]) { + expect(await productFeatureResidue(root, id, id), id).toEqual([]); + } + }); + + it("finds the name in a spec as written, and the folder name by the same rule", async () => { + const root = await fixture({ + "tests/e2e/checkout.spec.ts": `test.describe("${ID}", () => {});\n`, + "tests/e2e/documents.spec.ts": 'const FOLDER = "invoice-docs";\n', + "tests/e2e/title-case.spec.ts": 'test.describe("Invoice-Feature", () => {});\n', + "tests/e2e/longer-key.spec.ts": `const KEY = "${ID}_v2";\n`, + }); + + expect(await productFeatureResidue(root, ID, "invoice-docs")).toEqual([ + "tests/e2e/checkout.spec.ts", + "tests/e2e/documents.spec.ts", + ]); + }); + it("matches the folder name as well as the ID", async () => { const root = await fixture({ "src/contracts/leftover.ts": 'export const DIRECTORY = "invoices";\n', 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([]); }); });