@burdenoff/fe-libs 2026.1022.3 → 2026.1023.2

package/scripts/a11y-audit/fixtures.ts

@@ -0,0 +1,277 @@
+/**
+ * Route fixtures: audit a signed-in page without a live backend.
+ *
+ * The gate blocks every request that leaves the app's own origin so the DOM it
+ * audits is reproducible. That is exactly why signed-in pages were never
+ * audited: with the gateway unreachable the shell bounces to /auth/login and
+ * the audit measures the login page a second time.
+ *
+ * A fixture fixes both halves deterministically:
+ *
+ *   - `localStorage` is seeded before any page script runs, so the shell boots
+ *     with a session. Values may embed `{ "$jwt": { ...claims } }`, which is
+ *     encoded here into an UNSIGNED token. Nothing in a repo ever holds a real
+ *     or real-looking credential, and the claims (exp, workspaceId, ...) stay
+ *     readable in the fixture file. Expiries use `{ "$fromNow": seconds }` so
+ *     a session is always valid for a realistic window when the page opens.
+ *   - `cookies` are set on the app origin, for shells that cross-check the
+ *     session against a cookie marker.
+ *   - `graphql.operations` answers GraphQL requests to the configured
+ *     endpoints by operation name, batched or not. An operation the fixture
+ *     does not cover gets a GraphQL error response (never a live call) and is
+ *     recorded in the report, so fixture drift is visible instead of silent.
+ *
+ * Everything in this file is pure, so it is unit-tested without a browser.
+ */
+
+import type { FixtureSpec, GraphqlResult } from './types';
+
+/** Marker key: `{ "$jwt": { ...claims } }` becomes an unsigned JWT string. */
+export const JWT_MARKER = '$jwt';
+
+/**
+ * Time markers, resolved when the page is opened:
+ * `{ "$fromNow": 3600 }` → unix SECONDS one hour from now (JWT `exp`/`iat`),
+ * `{ "$fromNowMs": 3600000 }` → epoch MILLISECONDS one hour from now
+ * (`expiresAt` fields). A fixed far-future expiry is not a safe substitute:
+ * shells schedule refresh timers off it, and a delay past setTimeout's 2^31-1
+ * ms ceiling fires immediately — the session "expires" on load.
+ */
+export const FROM_NOW_MARKER = '$fromNow';
+export const FROM_NOW_MS_MARKER = '$fromNowMs';
+
+/**
+ * Signature segment of every fixture token. It is not a signature; it says so,
+ * and it keeps the three-segment shape clients check for.
+ */
+export const UNSIGNED_SIGNATURE = 'a11y-fixture-unsigned';
+
+/** Error code carried by the response for an operation the fixture lacks. */
+export const UNMOCKED_CODE = 'A11Y_FIXTURE_UNMOCKED';
+
+function base64Url(value: string): string {
+  return Buffer.from(value, 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/** Encode claims as an unsigned JWT (`alg: none`). For fixtures only. */
+export function encodeUnsignedJwt(claims: Record<string, unknown>): string {
+  const header = base64Url(JSON.stringify({ alg: 'none', typ: 'JWT' }));
+  const payload = base64Url(JSON.stringify(claims));
+  return `${header}.${payload}.${UNSIGNED_SIGNATURE}`;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function soleKey(value: unknown): string | null {
+  if (!isPlainObject(value)) return null;
+  const keys = Object.keys(value);
+  return keys.length === 1 ? keys[0] : null;
+}
+
+/**
+ * Replace every marker in a JSON value: `{ "$jwt": {...} }` with its encoded
+ * token (claims are expanded first, so `exp` may itself be a `$fromNow`), and
+ * `{ "$fromNow": s }` / `{ "$fromNowMs": ms }` with a timestamp relative to
+ * `nowMs`.
+ */
+export function expandMarkers(value: unknown, nowMs: number = Date.now()): unknown {
+  const key = soleKey(value);
+  if (key !== null && isPlainObject(value)) {
+    const inner = value[key];
+    if (key === JWT_MARKER && isPlainObject(inner)) {
+      return encodeUnsignedJwt(expandMarkers(inner, nowMs) as Record<string, unknown>);
+    }
+    if (key === FROM_NOW_MARKER && typeof inner === 'number') {
+      return Math.floor(nowMs / 1000) + inner;
+    }
+    if (key === FROM_NOW_MS_MARKER && typeof inner === 'number') {
+      return nowMs + inner;
+    }
+  }
+  if (Array.isArray(value)) return value.map((item) => expandMarkers(item, nowMs));
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expandMarkers(v, nowMs)]));
+  }
+  return value;
+}
+
+/**
+ * The exact strings written to localStorage. A string value is stored as-is;
+ * anything else is stored as JSON, which is how persisted stores read it back.
+ */
+export function materializeLocalStorage(
+  spec: FixtureSpec,
+  nowMs: number = Date.now()
+): Record<string, string> {
+  const entries = Object.entries(spec.localStorage ?? {});
+  return Object.fromEntries(
+    entries.map(([key, value]) => {
+      const expanded = expandMarkers(value, nowMs);
+      return [key, typeof expanded === 'string' ? expanded : JSON.stringify(expanded)];
+    })
+  );
+}
+
+/**
+ * Cookies set on the app origin before the page opens. A string value is used
+ * as-is; anything else is stored as URL-encoded JSON, the encoding shells use
+ * for their own JSON cookies (e.g. the `bf-sso` session marker).
+ */
+export function materializeCookies(
+  spec: FixtureSpec,
+  nowMs: number = Date.now()
+): Array<{ name: string; value: string }> {
+  return Object.entries(spec.cookies ?? {}).map(([name, value]) => {
+    const expanded = expandMarkers(value, nowMs);
+    return {
+      name,
+      value: typeof expanded === 'string' ? expanded : encodeURIComponent(JSON.stringify(expanded)),
+    };
+  });
+}
+
+/** True when `url` is a request to one of the fixture's GraphQL endpoints. */
+export function matchesGraphqlEndpoint(url: string, spec: FixtureSpec): boolean {
+  const endpoints = spec.graphql?.endpoints ?? [];
+  if (endpoints.length === 0) return false;
+  let pathname: string;
+  try {
+    pathname = new URL(url).pathname.replace(/\/+$/, '');
+  } catch {
+    return false;
+  }
+  return endpoints.some((endpoint) => pathname.endsWith(endpoint.replace(/\/+$/, '')));
+}
+
+interface GraphqlRequestLike {
+  operationName?: unknown;
+  query?: unknown;
+}
+
+const OPERATION_NAME = /\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/;
+
+/** Operation name of one GraphQL request, from `operationName` or the document. */
+export function operationNameOf(request: GraphqlRequestLike): string {
+  if (typeof request.operationName === 'string' && request.operationName.length > 0) {
+    return request.operationName;
+  }
+  if (typeof request.query === 'string') {
+    const match = OPERATION_NAME.exec(request.query);
+    if (match) return match[1];
+  }
+  return '(anonymous)';
+}
+
+export interface FixtureResponse {
+  status: number;
+  body: string;
+  /** Operations in this request the fixture had no answer for. */
+  unmocked: string[];
+}
+
+function unmockedResult(name: string): GraphqlResult {
+  return {
+    data: null,
+    errors: [
+      {
+        message: `a11y fixture has no response for operation "${name}"`,
+        extensions: { code: UNMOCKED_CODE },
+      },
+    ],
+  };
+}
+
+/**
+ * Parse the request parameters of a GraphQL call: a POST body (single or
+ * batched), or a GET query string.
+ */
+export function parseGraphqlRequest(
+  method: string,
+  url: string,
+  body: string | null
+): GraphqlRequestLike | GraphqlRequestLike[] | null {
+  if (method.toUpperCase() === 'GET') {
+    try {
+      const params = new URL(url).searchParams;
+      return {
+        operationName: params.get('operationName') ?? undefined,
+        query: params.get('query'),
+      };
+    } catch {
+      return null;
+    }
+  }
+  if (!body) return null;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (Array.isArray(parsed)) return parsed.filter(isPlainObject) as GraphqlRequestLike[];
+    return isPlainObject(parsed) ? (parsed as GraphqlRequestLike) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Answer a GraphQL request from the fixture. Batched requests get a batched
+ * response in the same order. A request that cannot be parsed is answered with
+ * a 400, never forwarded.
+ */
+export function respondToGraphql(
+  spec: FixtureSpec,
+  method: string,
+  url: string,
+  body: string | null,
+  nowMs: number = Date.now()
+): FixtureResponse {
+  const operations = spec.graphql?.operations ?? {};
+  const parsed = parseGraphqlRequest(method, url, body);
+  if (parsed === null) {
+    return {
+      status: 400,
+      body: JSON.stringify({
+        errors: [{ message: 'a11y fixture could not parse the request' }],
+      }),
+      unmocked: ['(unparseable request)'],
+    };
+  }
+
+  const unmocked: string[] = [];
+  const answer = (request: GraphqlRequestLike): GraphqlResult => {
+    const name = operationNameOf(request);
+    const result = Object.prototype.hasOwnProperty.call(operations, name)
+      ? operations[name]
+      : undefined;
+    if (result === undefined) {
+      unmocked.push(name);
+      return unmockedResult(name);
+    }
+    return expandMarkers(result, nowMs) as GraphqlResult;
+  };
+
+  const response = Array.isArray(parsed) ? parsed.map(answer) : answer(parsed);
+  return { status: 200, body: JSON.stringify(response), unmocked };
+}
+
+export interface SeedArgs {
+  /** Only documents on this origin are seeded (not about:blank or iframes). */
+  origin: string;
+  entries: Record<string, string>;
+}
+
+/**
+ * Script injected before every page script of a fixture route. Self-contained
+ * (no closure over module scope) so Playwright can serialize it into the page.
+ * It seeds once per document load, before the shell reads its session.
+ */
+export function seedLocalStorageScript(args: SeedArgs): void {
+  if (window.location.origin !== args.origin) return;
+  for (const [key, value] of Object.entries(args.entries)) {
+    window.localStorage.setItem(key, value);
+  }
+}

package/scripts/a11y-audit/index.ts

@@ -3,7 +3,23 @@
  * that needs to embed the audit rather than shell out to the CLI.
  */
 
-export { resolveConfig, ConfigError, DEFAULT_FAIL_ON, DEFAULT_STANDARD } from './config';
+export {
+  resolveConfig,
+  inlineFixtureFiles,
+  ConfigError,
+  DEFAULT_FAIL_ON,
+  DEFAULT_STANDARD,
+} from './config';
+export {
+  encodeUnsignedJwt,
+  expandMarkers,
+  materializeCookies,
+  materializeLocalStorage,
+  matchesGraphqlEndpoint,
+  operationNameOf,
+  parseGraphqlRequest,
+  respondToGraphql,
+} from './fixtures';
 export {
   entryCovers,
   findUnreachableRouteScopes,

package/scripts/a11y-audit/report.ts

@@ -5,12 +5,22 @@
 
 import type { AuditReport, FlatNode } from './types';
 
-function ruleSummary(
-  nodes: FlatNode[]
-): Array<{ rule: string; impact: string; count: number; helpUrl: string; help: string }> {
+function ruleSummary(nodes: FlatNode[]): Array<{
+  rule: string;
+  impact: string;
+  count: number;
+  helpUrl: string;
+  help: string;
+}> {
   const byRule = new Map<
     string,
-    { rule: string; impact: string; count: number; helpUrl: string; help: string }
+    {
+      rule: string;
+      impact: string;
+      count: number;
+      helpUrl: string;
+      help: string;
+    }
   >();
   for (const node of nodes) {
     const existing = byRule.get(node.rule);
@@ -49,7 +59,12 @@ export function renderConsole(report: AuditReport): string {
         `\n         ${route.blocking.length} blocking · ${route.allowed.length} allowlisted · ` +
         `${route.advisory.length} advisory · ${route.passCount} checks passed · ` +
         `${route.incompleteCount} needs review · ${route.renderedTextLength} chars rendered` +
-        `${route.domSettled ? '' : ' (DOM never went quiet)'}`
+        `${route.domSettled ? '' : ' (DOM never went quiet)'}` +
+        (route.fixture ? `\n         fixture: ${route.fixture}` : '') +
+        (route.unmockedOperations && route.unmockedOperations.length > 0
+          ? ` · unmocked GraphQL operations (answered with an error): ` +
+            route.unmockedOperations.join(', ')
+          : '')
     );
     for (const entry of ruleSummary(route.blocking)) {
       lines.push(`           x ${entry.rule} (${entry.impact}) x${entry.count} — ${entry.help}`);
@@ -114,6 +129,22 @@ export function renderMarkdown(report: AuditReport): string {
     );
   }
 
+  const unmocked = report.routes.filter(
+    (r) => r.unmockedOperations && r.unmockedOperations.length > 0
+  );
+  if (unmocked.length > 0) {
+    lines.push('');
+    lines.push('### Fixture coverage');
+    lines.push('');
+    lines.push('Operations these fixture routes sent that the fixture has no answer for:');
+    for (const route of unmocked) {
+      lines.push(
+        `- \`${route.routeName}\` @ ${route.viewport} (fixture \`${route.fixture}\`): ` +
+          (route.unmockedOperations ?? []).map((name) => `\`${name}\``).join(', ')
+      );
+    }
+  }
+
   const allBlocking = report.routes.flatMap((r) => r.blocking);
   if (allBlocking.length > 0) {
     lines.push('');

package/scripts/a11y-audit/types.ts

@@ -66,6 +66,39 @@ export interface RouteSpec {
    * "clean" result on an unexpected error page cannot be mistaken for a pass.
    */
   allowRedirect?: boolean;
+  /**
+   * Name of an entry in the top-level `fixtures` map to load this route with —
+   * typically a signed-in session plus canned GraphQL answers. A fixture route
+   * that ends anywhere other than `path` fails the attempt (unless
+   * `allowRedirect` is set): landing on /auth/login means the fixture did not
+   * sign in, and auditing the login page again would be a false pass.
+   */
+  fixture?: string;
+}
+
+/** A GraphQL response body, as the gateway would send it. */
+export interface GraphqlResult {
+  data?: unknown;
+  errors?: Array<{ message: string; [key: string]: unknown }>;
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Deterministic page state for a route. See fixtures.ts for the semantics.
+ * Never put a real credential in one: `{ "$jwt": { ...claims } }` is encoded
+ * into an unsigned token at run time.
+ */
+export interface FixtureSpec {
+  /** Seeded into localStorage before the first page script runs. */
+  localStorage?: Record<string, unknown>;
+  /** Cookies set on the app origin before the page opens. */
+  cookies?: Record<string, unknown>;
+  graphql?: {
+    /** Path suffixes that identify a GraphQL endpoint, on any origin. */
+    endpoints: string[];
+    /** Response body per operation name. */
+    operations: Record<string, GraphqlResult>;
+  };
 }
 
 export interface ViewportSpec {
@@ -152,6 +185,11 @@ export interface A11yAuditConfig {
    * still a hard failure — this retries a flake, it does not tolerate one.
    */
   routeAttempts?: number;
+  /**
+   * Named route fixtures. A value may be the fixture itself or a path, relative
+   * to the config file, of a JSON file holding it.
+   */
+  fixtures?: Record<string, FixtureSpec | string>;
 }
 
 /** Config with every default resolved. */
@@ -171,6 +209,7 @@ export interface ResolvedConfig {
   domQuietMs: number;
   minTextLength: number;
   routeAttempts: number;
+  fixtures: Record<string, FixtureSpec>;
 }
 
 /** A single failing DOM node, flattened out of an axe violation. */
@@ -212,6 +251,10 @@ export interface RouteResult {
   domSettled: boolean;
   /** Navigation attempts this route needed. >1 means the runner hit a flake. */
   attempts: number;
+  /** Fixture the route was loaded with, if any. */
+  fixture?: string;
+  /** GraphQL operations the page sent that the fixture had no answer for. */
+  unmockedOperations?: string[];
 }
 
 export interface AuditReport {
@@ -224,7 +267,11 @@ export interface AuditReport {
   blockExternalRequests: boolean;
   routes: RouteResult[];
   staleAllowlistEntries: Array<{ index: number; rule: string; reason: string }>;
-  expiredAllowlistEntries: Array<{ index: number; rule: string; expires: string }>;
+  expiredAllowlistEntries: Array<{
+    index: number;
+    rule: string;
+    expires: string;
+  }>;
   totals: {
     blocking: number;
     allowed: number;