From e7b1b018da61432e905f7b1ea8c799d488a85ac5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:24:11 +0900 Subject: [PATCH 1/3] =?UTF-8?q?test(contracts):=20HTTP=20=EC=8A=A4?= =?UTF-8?q?=ED=82=A4=EB=A7=88=20=ED=96=89=EC=9D=B4=20=EB=B0=A9=ED=96=A5?= =?UTF-8?q?=C2=B7=EB=AA=A8=EB=A5=B4=EB=8A=94=20=ED=95=84=EB=93=9C=20?= =?UTF-8?q?=EC=A0=95=EC=B1=85=EC=9D=84=20=EB=B9=BC=EB=A9=B4=20=EC=8B=A4?= =?UTF-8?q?=ED=8C=A8=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: FE-REG-SCHEMA 행의 direction·unknownFieldPolicy는 타입에서 선택 칸이다. tests/unit/schema-metadata-policy.test.ts는 행이 값을 적지 않으면 그 자리를 건너뛰었다(direction의 `declared === undefined`, 정책의 `if (declared === undefined) return []`). 1105/07-02는 RESPONSE 행의 정책이 REJECT_UNKNOWN으로 바뀔 때만 breaking으로 본다. 그래서 손으로 쓴 응답 행이 두 칸을 빼고 들어오면, 뒤에 응답 DTO를 .strict()로 바꿔도 행이 바뀌지 않아 check:registries는 아무것도 보지 않고 정책 테스트도 건너뛴다. 백엔드가 응답에 필드 하나를 더하면 그 API가 SCHEMA_MISMATCH로 실패한다. 고른 방법: 리뷰의 (A). descriptor의 입력·응답·실패 검증기(`slots`)로 쓰인 스키마의 행이 두 칸을 적지 않으면 두 테스트가 실패로 센다. 메시지는 `row states no direction, used as <방향>`과 `row states no unknownFieldPolicy, validator <탐침 결과>`다. 행이 아예 없으면 같은 메시지가 나오고, boundary 테스트도 `no FE-REG-SCHEMA row`로 실패한다. 템플릿 HTTP 행과 생성기가 쓰는 행(create-feature.ts, create-feature- write-slice.ts)은 이미 두 칸을 적어 통과한다. 라우트에만 쓰이는 행 (NotFoundSplat)은 slots에 없어 그대로 두 칸이 없어도 된다. 매뉴얼 01 4단계와 errors.md에 규칙과 메시지를 적었다. 버린 대안: (B) governance가 api-* 경계 행에 두 칸을 필수로 둔다. 경계별 필수 칸 규칙이 governance에 없어 분류기 변경과 기준선 재승인이 필요하다. 타입에서 두 칸을 필수로 만들면 route 전용 행까지 바뀌고, src/contracts export의 모양이 바뀐다. 위험·한계: 다운스트림이 두 칸 없는 HTTP 행을 가졌다면 동기화 뒤 test:unit이 실패한다. 메시지대로 두 칸을 적으면 된다. 고친 곳이 검사(테스트 파일) 자신이라 RED는 테스트 파일만으로 만들 수 없다. 참조 응답 행에서 두 칸을 지운 변이로 확인한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/schema-metadata-policy.test.ts (변이 없이 통과, ReferenceResourcePayload 행의 두 칸을 지운 변이에서 두 테스트 실패) Refs: 1106/07-02 --- docs/manual/01-add-a-feature.md | 1 + docs/manual/reference/errors.md | 1 + tests/unit/schema-metadata-policy.test.ts | 18 ++++++++++++++---- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 17121c2a..b790a13c 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -269,6 +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으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다. - 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서 `test:unit`을 돌릴 때 잡힌다. 예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 8f4a9af9..910fa46c 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -86,6 +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`에 두 칸을 적는다. 값은 쓰인 자리와 검증기가 정한다 | | `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 287271f6..f33f0e88 100644 --- a/tests/unit/schema-metadata-policy.test.ts +++ b/tests/unit/schema-metadata-policy.test.ts @@ -21,6 +21,13 @@ import { * `unrecognized_keys` rejects unknown fields; one that reaches the object * without that issue tolerates them. A nested object below that level is not * probed. + * + * 1106/07-02. Both fields are optional in the row type, and a row that left + * 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. */ const PROBE_KEY = "__unknownFieldProbe"; @@ -127,9 +134,11 @@ 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 === undefined || declared === direction + return declared === direction ? [] - : [`${operationId} ${validator.schemaId}: row ${declared}, used as ${direction}`]; + : [ + `${operationId} ${validator.schemaId}: row ${declared ?? "states no direction"}, used as ${direction}`, + ]; }); expect(wrong).toEqual([]); @@ -154,11 +163,12 @@ 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; - if (declared === undefined) return []; const probed = probeUnknownFieldPolicy(validator); return probed === declared ? [] - : [`${operationId} ${validator.schemaId}: row ${declared}, validator ${probed}`]; + : [ + `${operationId} ${validator.schemaId}: row ${declared ?? "states no unknownFieldPolicy"}, validator ${probed}`, + ]; }); expect(wrong).toEqual([]); From 9c4cddc201a9e2a341ec9948372f1fd22124decf Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:29:21 +0900 Subject: [PATCH 2/3] =?UTF-8?q?fix(a11y):=20=ED=95=9C=20=EC=9E=90=EC=9B=90?= =?UTF-8?q?=EC=9D=84=20=EC=9D=BD=EB=8A=94=20=EB=9D=BC=EC=9A=B0=ED=8A=B8?= =?UTF-8?q?=EA=B0=80=20=EA=B8=B0=EB=A1=9D=20=EC=97=86=EC=9D=B4=20=ED=86=B5?= =?UTF-8?q?=EA=B3=BC=EB=A1=9C=20=EC=84=B8=EC=A7=80=EB=A9=B4=20report?= =?UTF-8?q?=EA=B0=80=20=EC=8B=A4=ED=8C=A8=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다. 기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec 말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을 null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두 통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를 적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난 실행의 기록 파일도 디렉터리에 남아 있었다. 고른 방법: 리뷰의 (다)와 기록 초기화. - scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된 descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이 필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마일 때다. GET 쪽 규칙은 tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다. 참조 기능 상세와 create:feature --with-create 상세는 GET과 같은 Params를 쓰므로 이 규칙에 든다. - write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면 `a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다. a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다. - accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다. 기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다. 엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에 기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다. - 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개 라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은 허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL 하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도 모른다. 참조 기능과 함께 지워진다. - 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset). 버린 대안: - (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만 reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도 정해야 한다. - 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능 런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가 많다. - spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할 뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다. - 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정: 11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다. 위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고, 규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라 받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는 규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이 API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임 전체를 불러온다(check:registries와 같은 경로). check:types:node가 그 그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts tests/features/reference-feature/reference-contract.test.ts 11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤 node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm test:a11y Refs: 1106/11-01 --- docs/accessibility/manual-checklist.md | 5 +- docs/manual/01-add-a-feature.md | 1 + docs/manual/reference/errors.md | 1 + scripts/lib/a11y-data-state.ts | 88 +++++++++++++++++ scripts/write-a11y-report.ts | 20 ++++ tests/e2e/accessibility.spec.ts | 4 + .../reference-contract.test.ts | 18 ++++ tests/unit/a11y-report.test.ts | 96 +++++++++++++++++++ 8 files changed, 232 insertions(+), 1 deletion(-) diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index 2e4158db..61425334 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -74,7 +74,10 @@ What the automated run scans: no alert box is on screen, so a list page is scanned in its empty state. A read of one resource (a detail page) has no generic answer: that route is scanned in its failure state and the run records an `a11y-data-state` - annotation. + annotation. `a11y.json` lists it under `notChecked`. When a protected + route's `paramsSchema` is the input of such a read, the report expects that + record from the descriptors alone and fails without it + (`scripts/write-a11y-report.ts`). - The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that state is on screen (`tests/e2e/reference-form.spec.ts`, removed with the diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index b790a13c..d8ff2cbf 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -432,6 +432,7 @@ projectRequest: (input) => Object.freeze({ - 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두 `a11y-1`로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다. - 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이 아닌 요청을 그리기 전에 보내면 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" 절을 본다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 910fa46c..90f2714b 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -178,6 +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`). 기능 파일은 고치지 않는다 | | `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`) | 문서가 없는 경로를 적었다 | 그 문서 | diff --git a/scripts/lib/a11y-data-state.ts b/scripts/lib/a11y-data-state.ts index 81dfd740..e3d8a2fa 100644 --- a/scripts/lib/a11y-data-state.ts +++ b/scripts/lib/a11y-data-state.ts @@ -14,6 +14,12 @@ import path from "node:path"; * only the failure state, no record otherwise. A route's latest run therefore * decides. `scripts/write-a11y-report.ts` reads the records and reports those * routes under `notChecked` instead of in the passed `scope`. + * + * 1106/11-01. No record used to mean "checked", and nothing but the spec said + * which routes needed one: a record call changed to `null` (review 11-R2) put + * the detail page back in `scope` and every check passed. The report now + * works the same routes out from the installed descriptors + * (`oneResourceReadRoutes`) and fails when one has no record. */ export const A11Y_DATA_STATE_DIRECTORY = "artifacts/tests/a11y-data-state"; @@ -74,6 +80,88 @@ export async function readA11yNotCheckedRoutes( return Object.freeze(notChecked); } +export type OneResourceRoute = Readonly<{ + routeId: string; + operationIds: readonly string[]; +}>; + +type RouteFacts = Readonly<{ + routeId: string; + access: string; + paramsSchema: string | null; +}>; + +type ReadFacts = Readonly<{ + contract: Readonly<{ + operationId: string; + method: string; + pathTemplate: string; + inputValidator: Readonly<{ schemaId: string }>; + outputValidator: Readonly<{ + safeParse(value: unknown): Readonly<{ success: boolean }>; + }>; + }>; +}>; + +/** + * 1106/11-01. The installed routes the spec can scan only on their failure + * state, from the descriptors alone: a protected route whose `paramsSchema` is + * the input of a GET that reads one resource. A GET reads one resource by the + * rule `tests/e2e/support/installed-api-answers.ts` answers with: it has a + * path parameter and its output rejects an empty list, so no generic body + * answers it. The spec signs in only on protected routes, so a public route is + * not listed. + * + * This finds the detail pages that take their params schema from their read + * (the reference sample and every `create:feature --with-create` slice). A + * detail page whose params schema differs is not found, and its record alone + * decides, as before. + */ +export function oneResourceReadRoutes( + routes: Iterable, + operations: Iterable, +): readonly OneResourceRoute[] { + const readsByInput = new Map(); + for (const { contract } of operations) { + if (contract.method !== "GET" || !contract.pathTemplate.includes("{")) continue; + if (contract.outputValidator.safeParse([]).success) continue; + const reads = readsByInput.get(contract.inputValidator.schemaId) ?? []; + reads.push(contract.operationId); + readsByInput.set(contract.inputValidator.schemaId, reads); + } + const found: OneResourceRoute[] = []; + for (const route of routes) { + if (route.access !== "session-required" || route.paramsSchema === null) continue; + const reads = readsByInput.get(route.paramsSchema); + if (reads === undefined) continue; + found.push( + Object.freeze({ routeId: route.routeId, operationIds: Object.freeze([...reads]) }), + ); + } + return Object.freeze(found); +} + +/** + * 1106/11-01. One line for each route in `expected` that `notChecked` leaves + * out, which `a11y.json` would count as passed. Empty when every route that + * reads one resource has its failure-state record. A record for a route not in + * `expected` claims less and is not refused. + */ +export function oneResourceRoutesCountedAsChecked( + expected: readonly OneResourceRoute[], + notChecked: readonly A11yNotCheckedRoute[], +): readonly string[] { + const recorded = new Set(notChecked.map(({ routeId }) => routeId)); + return Object.freeze( + expected + .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`, + ), + ); +} + /** * The `artifacts/tests/a11y.json` value. `automatedStatus: "passed"` speaks * for `scope` only: the installed routes axe scanned in their own state. diff --git a/scripts/write-a11y-report.ts b/scripts/write-a11y-report.ts index da9b06e2..8e51ff94 100644 --- a/scripts/write-a11y-report.ts +++ b/scripts/write-a11y-report.ts @@ -1,8 +1,12 @@ import { mkdir } from "node:fs/promises"; +import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts"; +import { COMPOSED_CONTRACT_CONTRIBUTIONS } from "../src/features/loaded-feature-runtimes.ts"; import { automatedA11yArtifactSchema } from "./contracts/release-artifacts.ts"; import { automatedA11yReport, + oneResourceReadRoutes, + oneResourceRoutesCountedAsChecked, readA11yNotCheckedRoutes, } from "./lib/a11y-data-state.ts"; import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts"; @@ -12,6 +16,22 @@ await mkdir("artifacts/tests", { recursive: true }); // 1103/11-01. Routes the spec scanned only on their failure state are not // reported as passed. const notChecked = await readA11yNotCheckedRoutes(MANUAL_A11Y_ROUTE_IDS); +// 1106/11-01. The records come from the spec alone. The descriptors say which +// routes need one, so a record call the spec lost fails here instead of +// counting a detail page as passed. +const countedAsChecked = oneResourceRoutesCountedAsChecked( + oneResourceReadRoutes( + Object.values(ROUTE_REGISTRY), + COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId.values(), + ), + notChecked, +); +if (countedAsChecked.length > 0) { + process.stderr.write( + `a11y.json not written:\n${countedAsChecked.map((line) => `a11y: ${line}`).join("\n")}\n`, + ); + process.exit(1); +} await writeValidatedJsonArtifact({ path: "artifacts/tests/a11y.json", schema: automatedA11yArtifactSchema, diff --git a/tests/e2e/accessibility.spec.ts b/tests/e2e/accessibility.spec.ts index e8264ff4..d4c797b1 100644 --- a/tests/e2e/accessibility.spec.ts +++ b/tests/e2e/accessibility.spec.ts @@ -40,6 +40,10 @@ for (const definition of ROUTES) { test(`@a11y ${route} has no critical or serious axe violations`, async ({ page, }) => { + // 1106/11-01. An earlier run's record never outlives this run, even when + // no record call below is reached. scripts/write-a11y-report.ts then + // fails on a route the descriptors say reads one resource. + await recordA11yDataState(definition.routeId, null); const heading = page.getByRole("heading", { level: 1 }); if (definition.access === "session-required") { // 1103/11-01. Feature data is not this spec's subject: a list read gets diff --git a/tests/features/reference-feature/reference-contract.test.ts b/tests/features/reference-feature/reference-contract.test.ts index 4f632f12..c388871f 100644 --- a/tests/features/reference-feature/reference-contract.test.ts +++ b/tests/features/reference-feature/reference-contract.test.ts @@ -23,6 +23,7 @@ import { REFERENCE_FEATURE_ROUTE_CODECS } from "../../../src/features/reference- import type { ReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts"; import { createTestApplication } from "../../helpers/create-test-application.ts"; import { createReferenceFeatureInstalledInput } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts"; +import { oneResourceReadRoutes } from "../../../scripts/lib/a11y-data-state.ts"; describe("reference feature boundary contracts", () => { it("propagates uncertain command effect certainty into the application failure", async () => { @@ -138,6 +139,23 @@ describe("reference feature boundary contracts", () => { ); }); + // 1106/11-01. scripts/write-a11y-report.ts fails when a11y.json would count + // these routes as passed: the accessibility spec has no generic answer for a + // read of one resource and scans the page on its failure state only. + it("has one detail page the a11y report expects under notChecked", () => { + expect( + oneResourceReadRoutes( + Object.values(REFERENCE_FEATURE_CONTRACT.routes), + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION.http, + ), + ).toEqual([ + { + routeId: "REFERENCE_RESOURCE_DETAIL", + operationIds: ["GET_REFERENCE_RESOURCE"], + }, + ]); + }); + it("contributes an identity-based invalidation graph and an explicit wire version", () => { expect(REFERENCE_FEATURE_CONTRACT.invalidation).toEqual({ topics: [REFERENCE_RESOURCE_INVALIDATION_TOPIC], diff --git a/tests/unit/a11y-report.test.ts b/tests/unit/a11y-report.test.ts index 330b46a9..bf23e4f7 100644 --- a/tests/unit/a11y-report.test.ts +++ b/tests/unit/a11y-report.test.ts @@ -7,6 +7,8 @@ import { afterEach, describe, expect, it } from "vitest"; import { automatedA11yArtifactSchema } from "../../scripts/contracts/release-artifacts.ts"; import { automatedA11yReport, + oneResourceReadRoutes, + oneResourceRoutesCountedAsChecked, readA11yNotCheckedRoutes, recordA11yDataState, } from "../../scripts/lib/a11y-data-state.ts"; @@ -99,3 +101,97 @@ describe("automated accessibility report", () => { ).toBe(false); }); }); + +/** + * 1106/11-01. Which routes need a failure-state record comes from the + * descriptors, not from the spec that writes the records. Review 11-R2 passed + * `null` for the detail page's record and every check passed. + */ +describe("routes the accessibility spec can scan only on their failure state", () => { + const read = ( + operationId: string, + method: string, + pathTemplate: string, + inputSchemaId: string, + acceptsEmptyList: boolean, + ) => ({ + contract: { + operationId, + method, + pathTemplate, + inputValidator: { schemaId: inputSchemaId }, + outputValidator: { + safeParse: (value: unknown) => ({ + success: acceptsEmptyList && Array.isArray(value), + }), + }, + }, + }); + const route = ( + routeId: string, + access: string, + paramsSchema: string | null, + ) => ({ routeId, access, paramsSchema }); + + it("finds a protected route whose params are the input of a read of one resource", () => { + expect( + oneResourceReadRoutes( + [ + route("THING_LIST", "session-required", null), + route("THING_DETAIL", "session-required", "ThingParams"), + route("THING_PARTS", "session-required", "ThingPartsParams"), + route("THING_EDIT", "session-required", "ThingEditParams"), + route("PUBLIC_THING", "public", "ThingParams"), + ], + [ + read("LIST_THINGS", "GET", "/api/things", "ThingListQuery", true), + read("GET_THING", "GET", "/api/things/{thingId}", "ThingParams", false), + // A list under a path parameter gets the empty list. + read("LIST_THING_PARTS", "GET", "/api/things/{thingId}/parts", "ThingPartsParams", true), + // Not a read. + read("DELETE_THING", "DELETE", "/api/things/{thingId}", "ThingEditParams", false), + ], + ), + ).toEqual([{ routeId: "THING_DETAIL", operationIds: ["GET_THING"] }]); + }); + + it("refuses records that count such a route as checked", async () => { + const directory = await recordDirectory(); + const expected = [ + { routeId: FAILURE_STATE_ROUTE, operationIds: ["TEST_GET_ENTITY"] }, + ]; + + // 11-R2: the spec recorded the route as scanned in its own state. + await recordA11yDataState(FAILURE_STATE_ROUTE, null, directory); + expect( + oneResourceRoutesCountedAsChecked( + expected, + await readA11yNotCheckedRoutes(ROUTES, directory), + ), + ).toEqual([ + expect.stringContaining( + `${FAILURE_STATE_ROUTE} reads one resource (TEST_GET_ENTITY) but has no failure-state record`, + ), + ]); + + await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory); + expect( + oneResourceRoutesCountedAsChecked( + expected, + await readA11yNotCheckedRoutes(ROUTES, directory), + ), + ).toEqual([]); + }); + + it("does not refuse a record for a route the descriptors do not name", async () => { + const directory = await recordDirectory(); + await recordA11yDataState(FAILURE_STATE_ROUTE, REASON, directory); + + expect( + oneResourceRoutesCountedAsChecked( + [], + await readA11yNotCheckedRoutes(ROUTES, directory), + ), + ).toEqual([]); + }); +}); From af3344b3107b0e94cbeb3b2861124a821b3fdd39 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:32:31 +0900 Subject: [PATCH 3/3] =?UTF-8?q?fix(removal):=20=EB=B3=B8=EB=AC=B8=EC=97=90?= =?UTF-8?q?=EB=A7=8C=20=EA=B8=B0=EB=8A=A5=20ID=EB=A5=BC=20=EC=A0=81?= =?UTF-8?q?=EC=9D=80=20Playwright=20spec=EC=9D=84=20=EC=9E=94=EC=97=AC?= =?UTF-8?q?=EB=A1=9C=20=EC=84=BC=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 1105/16-04 수정 뒤 제품 기능 제거 드릴의 tests 잔여는 파일 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일뿐이다. 주석과 매뉴얼 01 11단계는 빠진 경우(본문에만 ID가 있는 테스트)를 test:all이 잡는다고 적었다. 그런데 test:all은 vitest 묶음이고 vitest는 tests의 *.test.ts(x)만 돈다. tests/e2e·visual 등의 *.spec.ts는 test:all도 드릴의 다른 단계도 돌리지 않는다. 그래서 `test.describe("invoice-feature", …)`처럼 본문에만 ID를 담은 spec은 드릴을 통과하고, 다음 CI의 브라우저 게이트에서 지운 라우트를 열다가 실패한다. 고른 방법: 리뷰의 (b). tests 중 vitest가 돌지 않는 Playwright spec (`*.spec.[cm]?[jt]sx?`)은 본문도 찾는다. 다만 1105/16-04가 없앤 부분 문자열 검색으로 돌아가지 않고, 기능 ID·폴더 이름을 앞뒤가 영문·숫자·`-`가 아닌 한 이름으로만 찾는다. `"invoice-feature"`, `'invoices'`, `/features/invoices/`는 잔여이고, product-feature를 지울 때 `generate-product-feature-index.ts`·`data-product-feature`· `product-features`는 잔여가 아니다. vitest 테스트 본문은 그대로 찾지 않는다 (템플릿 테스트가 예시 ID를 데이터로 쓴다). 템플릿 자신의 spec에는 invoice-feature·product-feature·scaffold-feature가 한 이름으로 나오지 않는다 (git grep 0건). 그래서 16-R2(invoice-feature 제거)와 FE-GATE-020 (scaffold-feature)은 그대로 통과해야 한다. 주석, 매뉴얼 01 11단계, errors.md의 판정 문장을 고쳤다. 버린 대안: (a) 문서만 고친다. 빈틈이 남는다. spec 본문을 부분 문자열로 찾는다: 짧은 ID와 템플릿 이름(`generate-product-feature-index`)이 거짓 양성을 다시 낸다. tests의 모든 비-vitest 파일(helpers, mocks, fixtures)을 찾는다: tests/helpers/runtime-capabilities-stub.ts가 주석에 "product-feature"를 한 이름으로 적어 거짓 양성이 된다. spec이 import하는 helper는 spec이 지워지면 아무 데서도 돌지 않아 해가 없다. 위험·한계: route ID나 URL만 적은 spec은 여전히 못 잡는다(03 손 목록). 다운스트림 spec이 무관한 이유로 기능 ID를 한 이름으로 적으면 거짓 양성이 난다. 1105/16-04의 남은 부분(src 경로·본문과 tests 파일 이름의 부분 문자열 검색, dist 빌드 잔여 검사)은 이 변경이 덮지 않아 그대로 두었다. 같은 이름 단위 검색으로 바꾸면 product-feature의 거짓 양성(16-R3, 20파일)은 풀리지만, 폴더 이름에 붙은 식별자(`invoices` → `InvoicesPage`)와 `-helpers.test.ts` 같은 파일 이름을 놓쳐 검사가 좁아진다. 따로 정한다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/feature-residue.test.ts corepack pnpm create:feature invoice-feature에 본문에만 ID를 적은 tests/e2e/checkout.spec.ts를 더한 뒤 corepack pnpm test:sample-removal -- --feature=invoice-feature가 fixture-id-residue로 실패, spec 없이는 통과 Refs: 1106/16-01 --- docs/manual/01-add-a-feature.md | 5 ++-- docs/manual/reference/errors.md | 2 +- scripts/lib/feature-residue.ts | 31 +++++++++++++++++----- tests/unit/feature-residue.test.ts | 41 ++++++++++++++++++++++++++++++ 4 files changed, 69 insertions(+), 10 deletions(-) diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index d8ff2cbf..16ae309c 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -658,10 +658,11 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature ③ **잡는 검사 / 못 잡는 것** -- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일이다. +- 남은 파일이 지운 기능을 가리키면 실패한다. `src`는 기능 ID나 폴더 이름을 담은 파일, `tests`는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(`*.spec.ts`)이다. - 메시지: ` removal failed:` 다음 줄 `fixture-id-residue: residue: ` - 템플릿 테스트가 예시 ID(`invoice-feature` 등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. -- **못 잡음**: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID만 적은 e2e spec, `artifacts/tests/a11y-manual/.md`. `tests` 안에서 기능 ID를 글자로만 적은 테스트도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의 `test:all`이 실패한다. 드릴은 `src`와 `tests`만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다. + - 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 기록은 남아도 검사가 실패하지 않는다. ④ **쓸 스킬**: `documentation-and-adrs`, `deprecation-and-migration` diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 90f2714b..8eded627 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -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하는 파일이다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능을 가리키지 않게 한다. 목록에 템플릿 파일이 나오면 템플릿 결함이다. 그 파일을 고치지 말고 템플릿에 알린다 | +| ` 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/feature-residue.ts b/scripts/lib/feature-residue.ts index 2bcfc934..757a4051 100644 --- a/scripts/lib/feature-residue.ts +++ b/scripts/lib/feature-residue.ts @@ -11,13 +11,21 @@ import path from "node:path"; * there is a reference the type checker cannot see (a catalog key, a * runtime override, a link). * - `tests/`: a file named after the feature, or one that imports from the - * feature's `src/features//` or `tests/features//`. The test - * text is not searched for the bare name: the template's own tests use - * example IDs as data (`tests/unit/create-feature.test.ts` writes + * feature's `src/features//` or `tests/features//`. A vitest + * test's text is not searched for the bare name: the template's own tests + * use example IDs as data (`tests/unit/create-feature.test.ts` writes * `invoice-feature`, the manual's example, 51 times), and the drill flagged - * them as residue of a product feature that took that name. A test that - * still depends on the removed feature fails `test:all`, which the drill - * runs. + * them as residue of a product feature that took that name. A vitest test + * that still depends on the removed feature fails `test:all`, which the + * drill runs. + * - 1106/16-01. `test:all` runs vitest only (the `*.test.ts(x)` files under + * `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. * * The reference sample keeps its own, wider pattern in * scripts/test-sample-removal.ts: the template owns all of its files. @@ -48,6 +56,8 @@ export async function productFeatureResidue( String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`, "u", ); + const wholeName = new RegExp(`(? path.relative(root, file).split(path.sep).join("/"); for (const file of await filesUnder(path.join(root, "src"))) { @@ -56,7 +66,14 @@ export async function productFeatureResidue( } for (const file of await filesUnder(path.join(root, "tests"))) { const name = relative(file); - if (named.test(name) || imported.test(await readFile(file, "utf8"))) residue.push(name); + const text = await readFile(file, "utf8"); + if ( + named.test(name) || + imported.test(text) || + (playwrightSpec.test(name) && wholeName.test(text)) + ) { + residue.push(name); + } } return residue.sort(); } diff --git a/tests/unit/feature-residue.test.ts b/tests/unit/feature-residue.test.ts index 7ebbeff4..657a77d8 100644 --- a/tests/unit/feature-residue.test.ts +++ b/tests/unit/feature-residue.test.ts @@ -59,6 +59,47 @@ describe("product feature residue (1105/16-04)", () => { ]); }); + // 1106/16-01. test:all is vitest only and the drill runs no Playwright + // spec, so a spec that names the removed feature in its text and nowhere + // else was caught by no step. + it("counts a Playwright spec that names the feature only in its text", async () => { + const spec = [ + `test.describe("${ID}", () => {`, + ' test("opens", async ({ page }) => {', + ' await page.goto("/invoice");', + " });", + "});", + "", + ].join("\n"); + const root = await fixture({ + "tests/e2e/checkout.spec.ts": spec, + "tests/visual/billing.visual.spec.ts": `const FEATURE = '${ID}';\n`, + // The same text in a vitest test is data (1105/16-04). + "tests/unit/checkout.test.ts": spec, + "tests/e2e/route-only.spec.ts": 'test("opens", ({ page }) => page.goto("/invoice"));\n', + }); + + expect(await productFeatureResidue(root, ID, ID)).toEqual([ + "tests/e2e/checkout.spec.ts", + "tests/visual/billing.visual.spec.ts", + ]); + }); + + it("does not count a spec whose longer names only contain the ID", async () => { + const root = await fixture({ + "tests/e2e/builds.spec.ts": [ + 'run("scripts/generate-product-feature-index.ts");', + 'const attribute = "data-product-feature";', + 'const registry = "product-features";', + "", + ].join("\n"), + }); + + expect( + await productFeatureResidue(root, "product-feature", "product-feature"), + ).toEqual([]); + }); + it("matches the folder name as well as the ID", async () => { const root = await fixture({ "src/contracts/leftover.ts": 'export const DIRECTORY = "invoices";\n',