Files
clean-architecture-frontend…/scripts/lib/a11y-data-state.ts
T
DongHyeonka 95141f1d85 docs(a11y): 한 자원 GET을 부르지 않는 라우트는 자기 paramsSchema를 둔다고 적는다
문제: 9c4cddc의 report는 "로그인 라우트의 paramsSchema = 한 자원 GET의
입력 스키마"만으로 실패 화면 기록을 기대한다. 그 라우트의 페이지가 그
GET을 실제로 부르는지는 보지 않는다. 손으로 쓴 기능이 하위 항목 작성 폼
(`/things/:thingId/parts/new`)의 paramsSchema로 상세 GET과 같은
ThingParams를 쓰면, spec은 한 자원 응답을 보지 못해 기록을 남기지 않고
report가 `a11y.json not written:`으로 FE-GATE-009를 실패시킨다. 그런데
errors.md는 "spec의 기록 호출을 본다. 기능 파일은 고치지 않는다"고만
안내했다. 이 경우 고칠 곳은 기능의 라우트 스키마 ID다.

고른 방법: 리뷰의 첫 방향. report 판정은 그대로 두고 안내를 고친다.
errors.md 행이 두 원인(spec이 기록을 놓침 / 페이지가 그 GET을 부르지
않음)과 각각 고칠 곳을 적는다. 매뉴얼 01 6단계에 같은 경우와 고치는 법
(그 라우트에 자기 paramsSchema)을 더했다. CHANGELOG 1106 절 11-01 행에
같은 줄을 더했다. report의 실패 문장 끝에도 같은 안내를 붙였다. 판정
조건과 문장 앞부분은 그대로라 단위 테스트의 기대(`stringContaining`)도
그대로다.
버린 대안: spec이 "기대했지만 보지 못함"을 따로 기록하고 report가 그
경우를 다르게 다룬다. report 판정이 바뀌어 이번 범위(문서) 밖이다.

위험·한계: 같은 스키마를 쓰면서 그 GET을 부르지 않는 라우트는 여전히
실패한다. 안내로만 풀린다. 그 라우트에 스키마를 따로 두면 FE-REG-SCHEMA
행과 route codec이 하나씩 는다.

검증: desktop batch에서 확인. 테스트 없음(문서와 실패 문장 끝).
corepack pnpm verify:documentation
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/unit/changelog-review-ids.test.ts

Refs: 1106/11-01 (diff review DR-05)
2026-11-06 07:59:04 +09:00

187 lines
7.2 KiB
TypeScript

import { randomUUID } from "node:crypto";
import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
import path from "node:path";
/**
* 1103/11-01. Which routes `tests/e2e/accessibility.spec.ts` could scan only
* on their failure state. The spec answers a protected page's list reads with
* an empty list; a read of one resource (a detail page) has no generic answer,
* so that page is scanned on its error screen. Passing axe there says nothing
* about the page's own content, and `artifacts/tests/a11y.json` used to list
* it as passed anyway.
*
* Each route's test leaves its answer in this directory: a record when it saw
* 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";
export type A11yNotCheckedRoute = Readonly<{ routeId: string; reason: string }>;
const ROUTE_ID = /^[A-Z][A-Z0-9_]*$/u;
function recordPath(directory: string, routeId: string): string {
if (!ROUTE_ID.test(routeId)) {
throw new TypeError(`not a route id: ${routeId}`);
}
return path.join(directory, `${routeId}.json`);
}
/** `reason` is null when the route was scanned in its own state. */
export async function recordA11yDataState(
routeId: string,
reason: string | null,
directory: string = A11Y_DATA_STATE_DIRECTORY,
): Promise<void> {
const file = recordPath(directory, routeId);
if (reason === null) {
await rm(file, { force: true });
return;
}
if (reason.length === 0) throw new TypeError("a not-checked route needs a reason");
await mkdir(directory, { recursive: true });
// Every engine records the same route at once: write whole, then rename.
const pending = `${file}.${randomUUID()}.tmp`;
await writeFile(pending, `${JSON.stringify({ routeId, reason })}\n`, "utf8");
await rename(pending, file);
}
/** The records for `routeIds`, in their order. A route with none was checked. */
export async function readA11yNotCheckedRoutes(
routeIds: readonly string[],
directory: string = A11Y_DATA_STATE_DIRECTORY,
): Promise<readonly A11yNotCheckedRoute[]> {
const notChecked: A11yNotCheckedRoute[] = [];
for (const routeId of routeIds) {
let text: string;
try {
text = await readFile(recordPath(directory, routeId), "utf8");
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
throw error;
}
const record = JSON.parse(text) as Partial<Record<"routeId" | "reason", unknown>>;
if (
record.routeId !== routeId ||
typeof record.reason !== "string" ||
record.reason.length === 0
) {
throw new TypeError(`malformed a11y data-state record for ${routeId}`);
}
notChecked.push(Object.freeze({ routeId, reason: record.reason }));
}
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<RouteFacts>,
operations: Iterable<ReadFacts>,
): readonly OneResourceRoute[] {
const readsByInput = new Map<string, string[]>();
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, or, when the route's page does not call that read, the route needs a params schema of its own`,
),
);
}
/**
* The `artifacts/tests/a11y.json` value. `automatedStatus: "passed"` speaks
* for `scope` only: the installed routes axe scanned in their own state.
*/
export function automatedA11yReport(
input: Readonly<{
routeIds: readonly string[];
notChecked: readonly A11yNotCheckedRoute[];
generatedAt: string;
}>,
) {
const notCheckedIds = new Set(input.notChecked.map(({ routeId }) => routeId));
return {
schemaVersion: 2 as const,
generatedAt: input.generatedAt,
scope: input.routeIds.filter((routeId) => !notCheckedIds.has(routeId)),
notChecked: input.notChecked.map(({ routeId, reason }) => ({ routeId, reason })),
threshold: { critical: 0 as const, serious: 0 as const },
automatedStatus: "passed" as const,
manualReview: "see artifacts/tests/a11y-manual/report.json" as const,
};
}