@burdenoff/fe-libs 2026.825.1 → 2026.825.3

package/scripts/a11y-audit/audit.ts

@@ -0,0 +1,306 @@
+/**
+ * Browser driving: navigate each configured route at each configured viewport
+ * and run a real axe-core pass against the rendered DOM.
+ *
+ * `playwright-core` and `@axe-core/playwright` are imported dynamically so the
+ * shared runner can live in fe-libs without dragging a browser automation
+ * dependency into every consumer of the component library. Consuming repos
+ * declare them as devDependencies; a missing one is a loud, actionable error.
+ */
+
+import { partitionNodes, flattenViolations } from './allowlist';
+import type { AxeViolationLike } from './allowlist';
+import type { RunningApp } from './server';
+import type { AuditReport, ResolvedConfig, RouteResult } from './types';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- dynamically imported
+   third-party modules have no static types available inside this script. */
+type AnyRecord = Record<string, any>;
+
+const MISSING_DEP_HINT =
+  'Add them to the repo devDependencies:\n' +
+  '    bun add -d @playwright/test @axe-core/playwright\n' +
+  '    bunx playwright install --with-deps chromium';
+
+async function loadPlaywright(): Promise<AnyRecord> {
+  for (const specifier of ['playwright', 'playwright-core', '@playwright/test']) {
+    try {
+      const mod = (await import(specifier)) as AnyRecord;
+      if (mod?.chromium) return mod.chromium as AnyRecord;
+    } catch {
+      /* try the next specifier */
+    }
+  }
+  throw new Error(`[a11y-audit] Cannot resolve Playwright.\n  ${MISSING_DEP_HINT}`);
+}
+
+type AxeBuilderCtor = new (options: { page: AnyRecord }) => {
+  withTags: (tags: string[]) => { analyze: () => Promise<AnyRecord> };
+};
+
+async function loadAxeBuilder(): Promise<AxeBuilderCtor> {
+  try {
+    const mod = (await import('@axe-core/playwright')) as AnyRecord;
+    return (mod.default ?? mod) as AxeBuilderCtor;
+  } catch (error) {
+    throw new Error(
+      `[a11y-audit] Cannot resolve @axe-core/playwright (${(error as Error).message}).\n  ` +
+        MISSING_DEP_HINT,
+      { cause: error }
+    );
+  }
+}
+
+async function loadAxeVersion(): Promise<string> {
+  try {
+    const mod = (await import('axe-core')) as AnyRecord;
+    return (mod.default?.version ?? mod.version ?? 'unknown') as string;
+  } catch {
+    return 'unknown';
+  }
+}
+
+interface DomSnapshot {
+  textLength: number;
+  elementCount: number;
+}
+
+async function snapshotDom(page: AnyRecord): Promise<DomSnapshot> {
+  return (await page.evaluate(() => ({
+    textLength: (document.body?.innerText ?? '').trim().length,
+    elementCount: document.querySelectorAll('*').length,
+  }))) as DomSnapshot;
+}
+
+/**
+ * Poll until the rendered DOM stops changing for `quietMs`, or `timeoutMs`
+ * elapses. Returns the final snapshot and whether it actually went quiet.
+ *
+ * This is what makes the gate reproducible on a shell that paints a splash
+ * before it paints the page.
+ */
+async function waitForStableDom(
+  page: AnyRecord,
+  quietMs: number,
+  timeoutMs: number
+): Promise<{ snapshot: DomSnapshot; settled: boolean }> {
+  const pollMs = 250;
+  const deadline = Date.now() + timeoutMs;
+  let previous = await snapshotDom(page);
+  let quietSince = Date.now();
+
+  while (Date.now() < deadline) {
+    await page.waitForTimeout(pollMs);
+    const current = await snapshotDom(page);
+    if (
+      current.textLength !== previous.textLength ||
+      current.elementCount !== previous.elementCount
+    ) {
+      previous = current;
+      quietSince = Date.now();
+      continue;
+    }
+    previous = current;
+    if (Date.now() - quietSince >= quietMs) return { snapshot: current, settled: true };
+  }
+  return { snapshot: previous, settled: false };
+}
+
+/** Run the full audit. Throws on navigation failure — never silently skips a route. */
+export async function runAudit(
+  config: ResolvedConfig,
+  app: Pick<RunningApp, 'baseUrl' | 'resolveAsset'>,
+  now: Date = new Date()
+): Promise<AuditReport> {
+  const { baseUrl, resolveAsset } = app;
+  const chromium = await loadPlaywright();
+  const AxeBuilder = await loadAxeBuilder();
+  const axeVersion = await loadAxeVersion();
+
+  const browser = await chromium.launch({
+    args: ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+  });
+  const results: RouteResult[] = [];
+  const usedEntries = new Set<number>();
+  const navigationErrors: string[] = [];
+
+  /** Fresh page with request routing applied — used for the first try and every retry. */
+  const openPage = async (context: AnyRecord): Promise<AnyRecord> => {
+    const page = await context.newPage();
+    if (config.blockExternalRequests || resolveAsset) {
+      await page.route('**/*', (route: AnyRecord) => {
+        const requestUrl: string = route.request().url();
+        const isOwnOrigin = requestUrl.startsWith(baseUrl);
+
+        // Serve the build's own files straight from disk. Chromium never opens
+        // a socket for them, so a spurious network-change notification cannot
+        // cancel a hundred in-flight chunk loads and leave the shell blank.
+        if (isOwnOrigin && resolveAsset) {
+          const asset = resolveAsset(new URL(requestUrl).pathname);
+          if (asset) {
+            void route.fulfill({
+              status: 200,
+              contentType: asset.contentType,
+              headers: { 'cache-control': 'no-store' },
+              body: asset.body,
+            });
+            return;
+          }
+          void route.fulfill({ status: 404, contentType: 'text/plain', body: 'Not found' });
+          return;
+        }
+
+        // Deterministic DOM: nothing the audit sees depends on a live backend,
+        // a CDN or the runner's network latency.
+        if (isOwnOrigin || requestUrl.startsWith('data:') || !config.blockExternalRequests) {
+          void route.continue();
+          return;
+        }
+        void route.abort();
+      });
+    }
+    return page;
+  };
+
+  try {
+    for (const viewport of config.viewports) {
+      const context = await browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height },
+        // Deterministic rendering: no OS locale/timezone drift between the dev
+        // machine and the CI runner changing what axe sees.
+        locale: 'en-US',
+        timezoneId: 'UTC',
+        reducedMotion: 'reduce',
+        // A service worker caching the shell across routes would make the audit
+        // depend on which route ran first.
+        serviceWorkers: 'block',
+      });
+
+      for (const route of config.routes) {
+        const url = `${baseUrl}${route.path}`;
+        const attemptFailures: string[] = [];
+        let result: RouteResult | null = null;
+
+        for (let attempt = 1; attempt <= config.routeAttempts && result === null; attempt += 1) {
+          const page = await openPage(context);
+          try {
+            const response = await page.goto(url, {
+              waitUntil: 'load',
+              timeout: config.navigationTimeoutMs,
+            });
+            if (response && response.status() >= 400) {
+              throw new Error(`HTTP ${response.status()}`);
+            }
+            if (route.waitForSelector) {
+              await page.waitForSelector(route.waitForSelector, {
+                timeout: config.navigationTimeoutMs,
+              });
+            }
+            await page.waitForTimeout(route.settleMs ?? config.settleMs);
+
+            const stability = await waitForStableDom(
+              page,
+              config.domQuietMs,
+              config.navigationTimeoutMs
+            );
+            const floor = route.minTextLength ?? config.minTextLength;
+            if (stability.snapshot.textLength < floor) {
+              throw new Error(
+                `rendered only ${stability.snapshot.textLength} characters of text (floor is ` +
+                  `${floor}) — the page never finished painting, so a clean axe result here ` +
+                  'would be meaningless'
+              );
+            }
+
+            const axeResults = (await new AxeBuilder({ page })
+              .withTags(config.standard)
+              .analyze()) as AnyRecord;
+
+            const nodes = flattenViolations(axeResults.violations as AxeViolationLike[], {
+              route: route.path,
+              routeName: route.name,
+              viewport: viewport.name,
+            });
+            const partition = partitionNodes(nodes, config.allowlist, config.failOn, now);
+            partition.usedEntries.forEach((index) => usedEntries.add(index));
+
+            result = {
+              route: route.path,
+              routeName: route.name,
+              viewport: viewport.name,
+              finalUrl: page.url(),
+              blocking: partition.blocking,
+              allowed: partition.allowed,
+              advisory: partition.advisory,
+              passCount: (axeResults.passes as unknown[]).length,
+              incompleteCount: (axeResults.incomplete as unknown[]).length,
+              renderedTextLength: stability.snapshot.textLength,
+              domSettled: stability.settled,
+              attempts: attempt,
+            };
+          } catch (error) {
+            attemptFailures.push(`attempt ${attempt}: ${(error as Error).message}`);
+          } finally {
+            await page.close();
+          }
+        }
+
+        if (result === null) {
+          navigationErrors.push(
+            `${route.name} @ ${viewport.name} (${url}):\n      ${attemptFailures.join('\n      ')}`
+          );
+          continue;
+        }
+        if (result.attempts > 1) {
+          console.warn(
+            `[a11y-audit] ${route.name} @ ${viewport.name} needed ${result.attempts} attempts ` +
+              `(${attemptFailures.join('; ')})`
+          );
+        }
+        results.push(result);
+      }
+
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+
+  if (navigationErrors.length > 0) {
+    throw new Error(
+      `[a11y-audit] ${navigationErrors.length} route(s) could not be loaded, so the audit is ` +
+        'incomplete and cannot be treated as a pass:\n  - ' +
+        navigationErrors.join('\n  - ')
+    );
+  }
+
+  const staleAllowlistEntries = config.allowlist
+    .map((entry, index) => ({ index, rule: entry.rule, reason: entry.reason }))
+    .filter((entry) => !usedEntries.has(entry.index));
+
+  const expiredAllowlistEntries = config.allowlist
+    .map((entry, index) => ({ index, rule: entry.rule, expires: entry.expires ?? '' }))
+    .filter((entry) => {
+      if (!entry.expires) return false;
+      return now.getTime() > new Date(`${entry.expires}T23:59:59.999Z`).getTime();
+    });
+
+  return {
+    name: config.name,
+    generatedAt: now.toISOString(),
+    baseUrl,
+    standard: config.standard,
+    failOn: config.failOn,
+    axeVersion,
+    blockExternalRequests: config.blockExternalRequests,
+    routes: results,
+    staleAllowlistEntries,
+    expiredAllowlistEntries,
+    totals: {
+      blocking: results.reduce((sum, r) => sum + r.blocking.length, 0),
+      allowed: results.reduce((sum, r) => sum + r.allowed.length, 0),
+      advisory: results.reduce((sum, r) => sum + r.advisory.length, 0),
+      routesAudited: results.length,
+    },
+  };
+}

package/scripts/a11y-audit/cli.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+/**
+ * a11y-audit — the fleet's WCAG 2.1 AA gate.
+ *
+ * Runs a real axe-core pass against a built app shell, microfrontend harness or
+ * website and fails the build on `serious` and `critical` violations. Known
+ * exceptions live in an explicit allowlist where every entry must carry a
+ * written reason; there is no way to switch a rule off wholesale.
+ *
+ * This replaces the per-repo Playwright specs that asserted `critical` only via
+ * `expect.soft`, which could never fail a build and were never wired into CI.
+ *
+ * Usage (from a consuming repo root, after `bun run build`):
+ *   bun run node_modules/@burdenoff/fe-libs/scripts/a11y-audit/cli.ts
+ * or, since fe-libs declares this as a package `bin`:
+ *   a11y-audit [configPath] [--base-url=URL] [--json=PATH] [--route=/path ...] [--quiet]
+ *
+ * `configPath` defaults to `./a11y-audit.config.json`.
+ *
+ * Exit codes:
+ *   0  no blocking violations
+ *   1  blocking violations (or a stale allowlist when failOnStaleAllowlist is set)
+ *   2  the audit could not run — bad config, app never came up, route failed to load
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { runAudit } from './audit';
+import { ConfigError, resolveConfig } from './config';
+import { renderConsole, renderMarkdown } from './report';
+import { findUnreachableRouteScopes } from './allowlist';
+import { startApp } from './server';
+
+interface CliArgs {
+  configPath: string;
+  baseUrl?: string;
+  jsonPath?: string;
+  routes: string[];
+  quiet: boolean;
+}
+
+export function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { configPath: 'a11y-audit.config.json', routes: [], quiet: false };
+  let positionalSeen = false;
+  for (const arg of argv) {
+    if (arg.startsWith('--base-url=')) args.baseUrl = arg.slice('--base-url='.length);
+    else if (arg.startsWith('--json=')) args.jsonPath = arg.slice('--json='.length);
+    else if (arg.startsWith('--route=')) args.routes.push(arg.slice('--route='.length));
+    else if (arg === '--quiet') args.quiet = true;
+    else if (arg.startsWith('--')) throw new Error(`Unknown flag: ${arg}`);
+    else if (!positionalSeen) {
+      args.configPath = arg;
+      positionalSeen = true;
+    } else throw new Error(`Unexpected argument: ${arg}`);
+  }
+  return args;
+}
+
+async function main(): Promise<number> {
+  let args: CliArgs;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`[a11y-audit] ${(error as Error).message}`);
+    return 2;
+  }
+
+  const configPath = resolve(process.cwd(), args.configPath);
+  if (!existsSync(configPath)) {
+    console.error(`[a11y-audit] Config not found: ${configPath}`);
+    console.error(
+      'Create an a11y-audit.config.json at your repo root. See ' +
+        '@burdenoff/fe-libs/scripts/a11y-audit/README.md for the config shape.'
+    );
+    return 2;
+  }
+
+  let config;
+  try {
+    config = resolveConfig(JSON.parse(readFileSync(configPath, 'utf8')));
+  } catch (error) {
+    if (error instanceof ConfigError) console.error(`[a11y-audit] ${error.message}`);
+    else console.error(`[a11y-audit] Failed to read ${configPath}: ${(error as Error).message}`);
+    return 2;
+  }
+
+  if (args.routes.length > 0) {
+    const filtered = config.routes.filter((route) => args.routes.includes(route.path));
+    if (filtered.length === 0) {
+      console.error(`[a11y-audit] --route filter matched none of the configured routes.`);
+      return 2;
+    }
+    config.routes = filtered;
+  }
+
+  const unreachable = findUnreachableRouteScopes(config.allowlist, config.routes);
+  if (unreachable.length > 0 && args.routes.length === 0) {
+    for (const item of unreachable) {
+      console.error(
+        `[a11y-audit] allowlist[${item.index}] is scoped to route "${item.route}", which is not ` +
+          'in the audited route list — fix the typo or the scope is silently doing nothing'
+      );
+    }
+    return 2;
+  }
+
+  let app;
+  try {
+    app = await startApp(config, args.baseUrl);
+  } catch (error) {
+    console.error(`[a11y-audit] Could not reach the app under test: ${(error as Error).message}`);
+    return 2;
+  }
+
+  try {
+    const report = await runAudit(config, app);
+
+    const jsonPath = resolve(process.cwd(), args.jsonPath ?? config.reportPath);
+    mkdirSync(dirname(jsonPath), { recursive: true });
+    writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+    if (!args.quiet) console.log(renderConsole(report));
+    console.log(`[a11y-audit] JSON report written to ${jsonPath}`);
+
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryPath) {
+      writeFileSync(summaryPath, renderMarkdown(report), { flag: 'a' });
+    }
+
+    if (report.totals.blocking > 0) {
+      console.error(
+        `[a11y-audit] FAILED: ${report.totals.blocking} blocking violation node(s) at ` +
+          `${config.failOn.join('/')} impact. Fix them, or add a narrowly-scoped allowlist entry ` +
+          'with a written reason and an expiry.'
+      );
+      return 1;
+    }
+    if (config.failOnStaleAllowlist && report.staleAllowlistEntries.length > 0) {
+      console.error(
+        `[a11y-audit] FAILED: ${report.staleAllowlistEntries.length} allowlist entr(ies) matched ` +
+          'nothing and failOnStaleAllowlist is set — delete them.'
+      );
+      return 1;
+    }
+    console.log('[a11y-audit] PASSED: no blocking accessibility violations.');
+    return 0;
+  } catch (error) {
+    console.error(`[a11y-audit] ${(error as Error).message}`);
+    return 2;
+  } finally {
+    await app.close();
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(`[a11y-audit] Unexpected failure: ${(error as Error).stack ?? error}`);
+    process.exit(2);
+  }
+);