@burdenoff/fe-libs 2026.823.2 → 2026.825.2

package/scripts/a11y-audit/server.ts

@@ -0,0 +1,237 @@
+/**
+ * Getting a running app in front of the browser.
+ *
+ * Three modes, mirroring how the fleet ships frontends:
+ *   staticDir — app shells and websites, which build to a servable `dist/`
+ *   command   — microfrontends, which build to a library and need their Vite
+ *               harness (`bun run dev`) to render anything
+ *   baseUrl   — an already-running target (a preview deploy, alpha, prod)
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
+import { createServer, type Server } from 'node:http';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import type { ResolvedConfig } from './types';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.map': 'application/json; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.txt': 'text/plain; charset=utf-8',
+  '.webmanifest': 'application/manifest+json',
+};
+
+/** A file resolved out of the built `dist/` directory. */
+export interface ResolvedAsset {
+  body: Buffer;
+  contentType: string;
+}
+
+export interface RunningApp {
+  baseUrl: string;
+  close: () => Promise<void>;
+  /**
+   * Present in `staticDir` mode: resolves a URL path straight out of the build
+   * directory. The audit fulfils the page's own requests through this instead
+   * of letting Chromium open a socket per chunk, which keeps a code-split shell
+   * from losing a hundred parallel chunk loads to one spurious
+   * ERR_NETWORK_CHANGED and rendering blank.
+   */
+  resolveAsset?: (urlPath: string) => ResolvedAsset | null;
+}
+
+function resolveWithinRoot(root: string, urlPath: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return null;
+  }
+  const candidate = resolve(root, `.${normalize(decoded)}`);
+  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
+  return candidate;
+}
+
+/**
+ * Map a URL path onto a file inside the build directory.
+ *
+ * `null` means "outside the root" (403) and `undefined` means "no such file"
+ * (404). Both the HTTP server and the browser-side interception use this, so
+ * the two can never disagree about what the build contains.
+ */
+function resolveBuildFile(
+  rootDir: string,
+  indexPath: string,
+  spa: boolean,
+  urlPath: string
+): string | null | undefined {
+  let filePath = resolveWithinRoot(rootDir, urlPath);
+  if (filePath === null) return null;
+
+  if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+    filePath = join(filePath, 'index.html');
+  }
+  if (existsSync(filePath) && statSync(filePath).isFile()) return filePath;
+  // Client-routed URLs get the shell. A missing *asset* stays a 404 — a broken
+  // bundle must not be laundered into a successful page load.
+  if (spa && extname(urlPath) === '') return indexPath;
+  return undefined;
+}
+
+/** Serve a built `dist/` over loopback, with optional SPA fallback. */
+export function startStaticServer(root: string, spa: boolean): Promise<RunningApp> {
+  const rootDir = resolve(root);
+  if (!existsSync(rootDir)) {
+    return Promise.reject(
+      new Error(
+        `staticDir "${root}" does not exist — build the app before running the audit ` +
+          '(e.g. `bun run build`)'
+      )
+    );
+  }
+  const indexPath = join(rootDir, 'index.html');
+  if (!existsSync(indexPath)) {
+    return Promise.reject(new Error(`staticDir "${root}" has no index.html`));
+  }
+
+  const contentTypeFor = (filePath: string): string =>
+    MIME_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+
+  const resolveAsset = (urlPath: string): ResolvedAsset | null => {
+    const filePath = resolveBuildFile(rootDir, indexPath, spa, urlPath);
+    if (filePath === null || filePath === undefined) return null;
+    return { body: readFileSync(filePath), contentType: contentTypeFor(filePath) };
+  };
+
+  const server: Server = createServer((req, res) => {
+    const urlPath = (req.url ?? '/').split('?')[0].split('#')[0];
+    const filePath = resolveBuildFile(rootDir, indexPath, spa, urlPath);
+
+    if (filePath === null) {
+      res.writeHead(403).end('Forbidden');
+      return;
+    }
+    if (filePath === undefined) {
+      res.writeHead(404, { 'content-type': 'text/plain' }).end('Not found');
+      return;
+    }
+
+    res.writeHead(200, {
+      'content-type': contentTypeFor(filePath),
+      'cache-control': 'no-store',
+    });
+    createReadStream(filePath).pipe(res);
+  });
+
+  return new Promise<RunningApp>((resolvePromise, rejectPromise) => {
+    server.on('error', rejectPromise);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (address === null || typeof address === 'string') {
+        rejectPromise(new Error('static server did not bind to a TCP port'));
+        return;
+      }
+      resolvePromise({
+        baseUrl: `http://127.0.0.1:${address.port}`,
+        resolveAsset,
+        close: () =>
+          new Promise<void>((done) => {
+            server.close(() => done());
+            server.closeAllConnections?.();
+          }),
+      });
+    });
+  });
+}
+
+async function waitForUrl(url: string, timeoutMs: number, child?: ChildProcess): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = 'no response';
+  while (Date.now() < deadline) {
+    if (child && child.exitCode !== null) {
+      throw new Error(`server command exited with code ${child.exitCode} before serving ${url}`);
+    }
+    try {
+      const response = await fetch(url, { redirect: 'manual' });
+      if (response.status < 500) return;
+      lastError = `HTTP ${response.status}`;
+    } catch (error) {
+      lastError = (error as Error).message;
+    }
+    await new Promise((done) => setTimeout(done, 500));
+  }
+  throw new Error(`timed out after ${timeoutMs}ms waiting for ${url} (last error: ${lastError})`);
+}
+
+/** Start a server via a shell command and wait until its port answers. */
+export async function startCommandServer(
+  command: string,
+  port: number,
+  readyTimeoutMs: number
+): Promise<RunningApp> {
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const child = spawn(command, {
+    shell: true,
+    stdio: ['ignore', 'inherit', 'inherit'],
+    detached: true,
+    env: { ...process.env, PORT: String(port) },
+  });
+
+  const close = async (): Promise<void> => {
+    if (child.pid === undefined || child.exitCode !== null) return;
+    try {
+      process.kill(-child.pid, 'SIGTERM');
+    } catch {
+      child.kill('SIGTERM');
+    }
+    await new Promise((done) => setTimeout(done, 500));
+  };
+
+  try {
+    await waitForUrl(baseUrl, readyTimeoutMs, child);
+  } catch (error) {
+    await close();
+    throw error;
+  }
+  return { baseUrl, close };
+}
+
+/** Resolve the configured serve mode into a running app. */
+export async function startApp(
+  config: ResolvedConfig,
+  baseUrlOverride?: string
+): Promise<RunningApp> {
+  if (baseUrlOverride) {
+    await waitForUrl(baseUrlOverride, config.serve.readyTimeoutMs);
+    return { baseUrl: baseUrlOverride.replace(/\/$/, ''), close: async () => {} };
+  }
+  if (config.serve.baseUrl) {
+    await waitForUrl(config.serve.baseUrl, config.serve.readyTimeoutMs);
+    return { baseUrl: config.serve.baseUrl.replace(/\/$/, ''), close: async () => {} };
+  }
+  if (config.serve.staticDir) {
+    return startStaticServer(config.serve.staticDir, config.serve.spa);
+  }
+  return startCommandServer(
+    config.serve.command as string,
+    config.serve.port as number,
+    config.serve.readyTimeoutMs
+  );
+}

package/scripts/a11y-audit/types.ts

@@ -0,0 +1,234 @@
+/**
+ * Shared type definitions for the fleet accessibility gate.
+ *
+ * See README.md in this directory for the config shape and worked examples.
+ */
+
+/** axe-core impact levels, ordered least to most severe. */
+export const IMPACT_LEVELS = ['minor', 'moderate', 'serious', 'critical'] as const;
+
+export type ImpactLevel = (typeof IMPACT_LEVELS)[number];
+
+/**
+ * One explicitly-documented exception. Every entry MUST carry a `reason`;
+ * there is deliberately no way to disable a rule globally, no `enabled: false`
+ * escape hatch and no wildcard rule id. Narrowing an entry to specific routes
+ * and/or specific DOM subtrees is optional but strongly encouraged — an entry
+ * with neither is a fleet-wide exemption for that one rule and reads that way
+ * in the report.
+ */
+export interface AllowlistEntry {
+  /** axe rule id, e.g. `color-contrast`. Wildcards are rejected. */
+  rule: string;
+  /** Why this violation is tolerated. Free prose, minimum 20 characters. */
+  reason: string;
+  /**
+   * Routes this entry applies to. Each is either an exact configured route
+   * path or a `/prefix/*` subtree. Omit to apply to every audited route.
+   */
+  routes?: string[];
+  /**
+   * CSS selectors this entry applies to. A node matches when the selector is
+   * the node's own axe target or an ancestor prefix of it. Omit to apply to
+   * every node the rule flags.
+   */
+  selectors?: string[];
+  /**
+   * ISO `YYYY-MM-DD` date after which the entry stops suppressing anything and
+   * the violations it covered start failing the build again. Optional, but the
+   * only thing that keeps an allowlist from becoming permanent.
+   */
+  expires?: string;
+  /** Linear ticket tracking the fix, e.g. `BOFF-1234`. */
+  ticket?: string;
+}
+
+/** One page to audit. */
+export interface RouteSpec {
+  /** Path appended to the base URL, e.g. `/settings/profile`. */
+  path: string;
+  /** Human label used in reports. Defaults to `path`. */
+  name?: string;
+  /** Selector that must be present before axe runs. */
+  waitForSelector?: string;
+  /** Settle time in ms for this route, replacing the global `settleMs`. */
+  settleMs?: number;
+  /**
+   * Minimum rendered text length for THIS route, overriding the global
+   * `minTextLength`. Raise it on a heavy page whose load has a visible plateau
+   * — a splash or skeleton can hold steady long enough to look like a settled
+   * DOM, and auditing that frame measures the skeleton, not the page.
+   */
+  minTextLength?: number;
+  /**
+   * Treat a redirect away from `path` as expected. When false (the default) a
+   * redirect is still audited, but the report records the final URL so a
+   * "clean" result on an unexpected error page cannot be mistaken for a pass.
+   */
+  allowRedirect?: boolean;
+}
+
+export interface ViewportSpec {
+  name: string;
+  width: number;
+  height: number;
+}
+
+/**
+ * How the audit gets a running app. Exactly one of `staticDir`, `command` or
+ * `baseUrl` must be set.
+ */
+export interface ServeConfig {
+  /** Directory of built static assets to serve, relative to the repo root. */
+  staticDir?: string;
+  /** Serve `index.html` for unknown extension-less paths. Client-routed apps need this. */
+  spa?: boolean;
+  /** Command that starts a server, e.g. `bun run preview --port 4180`. */
+  command?: string;
+  /** Port the command listens on. Required with `command`. */
+  port?: number;
+  /** Audit an already-running server instead of starting one. */
+  baseUrl?: string;
+  /** How long to wait for `command` to answer, ms. Default 60000. */
+  readyTimeoutMs?: number;
+}
+
+export interface A11yAuditConfig {
+  /** Repo/app name, used in report headings. */
+  name: string;
+  serve: ServeConfig;
+  routes: RouteSpec[];
+  /** Defaults to a single 1280x800 `desktop` viewport. */
+  viewports?: ViewportSpec[];
+  /** axe tag set. Defaults to the WCAG 2.1 AA tags. */
+  standard?: string[];
+  /** Impacts that fail the build. Defaults to `['critical', 'serious']`. */
+  failOn?: ImpactLevel[];
+  allowlist?: AllowlistEntry[];
+  /** Where the JSON report is written. Defaults to `a11y-report.json`. */
+  reportPath?: string;
+  /** Fail when an allowlist entry matched nothing. Defaults to false (warn only). */
+  failOnStaleAllowlist?: boolean;
+  /** Per-navigation timeout in ms. Defaults to 45000. */
+  navigationTimeoutMs?: number;
+  /** Settle time in ms applied to every route after load. Defaults to 1500. */
+  settleMs?: number;
+  /**
+   * Abort every request that leaves the app's own origin. Defaults to true.
+   *
+   * A build-time gate must produce the same DOM on a laptop, a CI runner and a
+   * re-run three weeks later. Letting the built bundle talk to a live gateway
+   * makes axe race backend latency: the same route audits a splash screen on
+   * one run and a rendered page on the next. Blocking egress pins the app to
+   * one deterministic state. Set false only when auditing a live deployment
+   * via `--base-url`, where the backend is part of what you are auditing.
+   */
+  blockExternalRequests?: boolean;
+  /**
+   * How long the DOM must stop changing before axe runs, in ms. Defaults to
+   * 1500.
+   *
+   * Single-page shells paint a splash, then hydrate, then swap in the real
+   * page. A fixed sleep audits whichever frame it happens to land on, which is
+   * how a gate ends up reporting a clean splash screen as a pass.
+   */
+  domQuietMs?: number;
+  /**
+   * Minimum rendered `body.innerText` length for a route to count as audited.
+   * Defaults to 100 characters.
+   *
+   * Below this the page never rendered, and axe finding nothing means nothing.
+   * The run fails as an incomplete audit rather than reporting a false pass.
+   */
+  minTextLength?: number;
+  /**
+   * How many times a route may be re-navigated on a fresh page before the run
+   * is declared an incomplete audit. Defaults to 3.
+   *
+   * Chromium in a VM/container periodically fires a spurious network-change
+   * notification that cancels every in-flight request; on a code-split shell
+   * that lands as a blank page. The content floor catches it, and a retry on a
+   * clean page recovers it. A route that never renders across all attempts is
+   * still a hard failure — this retries a flake, it does not tolerate one.
+   */
+  routeAttempts?: number;
+}
+
+/** Config with every default resolved. */
+export interface ResolvedConfig {
+  name: string;
+  serve: Required<Pick<ServeConfig, 'spa' | 'readyTimeoutMs'>> & ServeConfig;
+  routes: Array<Required<Pick<RouteSpec, 'path' | 'name' | 'allowRedirect'>> & RouteSpec>;
+  viewports: ViewportSpec[];
+  standard: string[];
+  failOn: ImpactLevel[];
+  allowlist: AllowlistEntry[];
+  reportPath: string;
+  failOnStaleAllowlist: boolean;
+  navigationTimeoutMs: number;
+  settleMs: number;
+  blockExternalRequests: boolean;
+  domQuietMs: number;
+  minTextLength: number;
+  routeAttempts: number;
+}
+
+/** A single failing DOM node, flattened out of an axe violation. */
+export interface FlatNode {
+  rule: string;
+  impact: ImpactLevel;
+  help: string;
+  helpUrl: string;
+  tags: string[];
+  route: string;
+  routeName: string;
+  viewport: string;
+  target: string[];
+  html: string;
+  failureSummary: string;
+}
+
+export interface AllowedNode extends FlatNode {
+  allowlistIndex: number;
+  allowlistReason: string;
+  allowlistTicket?: string;
+}
+
+export interface RouteResult {
+  route: string;
+  routeName: string;
+  viewport: string;
+  /** URL the browser actually ended on — records redirects. */
+  finalUrl: string;
+  blocking: FlatNode[];
+  allowed: AllowedNode[];
+  advisory: FlatNode[];
+  /** Rules that ran clean, for the "we actually looked" evidence trail. */
+  passCount: number;
+  incompleteCount: number;
+  /** Rendered text length at the moment axe ran — evidence the page was real. */
+  renderedTextLength: number;
+  /** Whether the DOM went quiet before the navigation timeout. */
+  domSettled: boolean;
+  /** Navigation attempts this route needed. >1 means the runner hit a flake. */
+  attempts: number;
+}
+
+export interface AuditReport {
+  name: string;
+  generatedAt: string;
+  baseUrl: string;
+  standard: string[];
+  failOn: ImpactLevel[];
+  axeVersion: string;
+  blockExternalRequests: boolean;
+  routes: RouteResult[];
+  staleAllowlistEntries: Array<{ index: number; rule: string; reason: string }>;
+  expiredAllowlistEntries: Array<{ index: number; rule: string; expires: string }>;
+  totals: {
+    blocking: number;
+    allowed: number;
+    advisory: number;
+    routesAudited: number;
+  };
+}