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