소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로 템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다. 참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록 7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트 참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은 비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을 하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다. 기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로 옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플 경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다. 레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약 기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능 539B, context 4B)을 다시 받았다. 위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은 수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에 공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는 플랫폼 코드에 남았다. 검증(desktop): check:types, lint, check:architecture, check:registries, check:ci, verify:documentation, test:unit, test:component, test:contract, test:integration, test:recipes, test:coverage(Risk coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual, test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76 checks), test:sample-removal SKIP, build, check:bundle.
187 lines
7.2 KiB
TypeScript
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
|
|
* (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,
|
|
};
|
|
}
|