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 { 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 { 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>; 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, 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. */ 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, }; }