@burdenoff/fe-libs 2026.823.2 → 2026.825.2

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);
+  }
+);

package/scripts/a11y-audit/config.ts

@@ -0,0 +1,319 @@
+/**
+ * Config parsing + validation for the accessibility gate.
+ *
+ * Everything here is pure so the rules that decide what may be suppressed are
+ * unit-testable without a browser. A config that does not validate is a hard
+ * error (exit 2) — a gate that silently degrades to "audited nothing" is the
+ * failure mode this whole check exists to remove.
+ */
+
+import { IMPACT_LEVELS } from './types';
+import type {
+  A11yAuditConfig,
+  AllowlistEntry,
+  ImpactLevel,
+  ResolvedConfig,
+  RouteSpec,
+  ViewportSpec,
+} from './types';
+
+export const DEFAULT_STANDARD = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
+export const DEFAULT_FAIL_ON: ImpactLevel[] = ['critical', 'serious'];
+export const DEFAULT_VIEWPORTS: ViewportSpec[] = [{ name: 'desktop', width: 1280, height: 800 }];
+export const MIN_REASON_LENGTH = 20;
+
+/** Reason strings that are technically non-empty but say nothing. */
+const PLACEHOLDER_REASONS = [
+  'todo',
+  'tbd',
+  'fixme',
+  'wip',
+  'n/a',
+  'na',
+  'none',
+  'temporary',
+  'temp',
+  'later',
+  'known issue',
+  'known issues',
+  'legacy',
+  'see ticket',
+];
+
+export class ConfigError extends Error {
+  readonly issues: string[];
+
+  constructor(issues: string[]) {
+    super(`Invalid a11y-audit config:\n  - ${issues.join('\n  - ')}`);
+    this.name = 'ConfigError';
+    this.issues = issues;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** `true` for a bare wildcard, in any of the shapes people reach for first. */
+export function isWildcard(value: string): boolean {
+  const trimmed = value.trim();
+  return trimmed === '*' || trimmed === '**' || trimmed === '/*' || trimmed === '.*';
+}
+
+const PLACEHOLDER_PREFIX =
+  /^(todo|tbd|fixme|wip|n\/a|na|none|temp|temporary|later|known issues?|legacy|see ticket)\b[\s:,.\-–—]*/;
+
+/**
+ * True for a reason that is technically prose but says nothing — either the
+ * bare placeholder, or a placeholder token with no substance behind it
+ * ("TODO: fix later"). Checked before the length floor so the error message
+ * names the real problem.
+ */
+export function isPlaceholderReason(reason: string): boolean {
+  const normalized = reason
+    .trim()
+    .toLowerCase()
+    .replace(/[.!\-–—:;,]+$/g, '')
+    .trim();
+  if (PLACEHOLDER_REASONS.includes(normalized)) return true;
+  const stripped = normalized.replace(PLACEHOLDER_PREFIX, '').trim();
+  return stripped !== normalized && stripped.length < MIN_REASON_LENGTH;
+}
+
+/** Valid ISO calendar date, and a real one (2026-02-31 is rejected). */
+export function isIsoDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const parsed = new Date(`${value}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime())) return false;
+  return parsed.toISOString().slice(0, 10) === value;
+}
+
+function validateAllowlistEntry(entry: unknown, index: number, issues: string[]): void {
+  const where = `allowlist[${index}]`;
+  if (!isPlainObject(entry)) {
+    issues.push(`${where} must be an object`);
+    return;
+  }
+
+  if (!isNonEmptyString(entry.rule)) {
+    issues.push(`${where}.rule is required and must be a non-empty axe rule id`);
+  } else if (isWildcard(entry.rule)) {
+    issues.push(
+      `${where}.rule "${entry.rule}" is a wildcard — allowlist entries must name one axe rule; ` +
+        'blanket suppressions are not supported'
+    );
+  }
+
+  if (!isNonEmptyString(entry.reason)) {
+    issues.push(
+      `${where}.reason is required — every allowlisted violation must say why it is tolerated`
+    );
+  } else if (isPlaceholderReason(entry.reason)) {
+    issues.push(
+      `${where}.reason "${entry.reason.trim()}" is a placeholder, not a reason — describe the ` +
+        'actual constraint and who owns the fix'
+    );
+  } else if (entry.reason.trim().length < MIN_REASON_LENGTH) {
+    issues.push(
+      `${where}.reason must be at least ${MIN_REASON_LENGTH} characters explaining why this is ` +
+        `tolerated (got ${entry.reason.trim().length})`
+    );
+  }
+
+  for (const key of ['routes', 'selectors'] as const) {
+    const value = entry[key];
+    if (value === undefined) continue;
+    if (!Array.isArray(value) || value.length === 0) {
+      issues.push(`${where}.${key} must be a non-empty array when present`);
+      continue;
+    }
+    value.forEach((item, i) => {
+      if (!isNonEmptyString(item)) {
+        issues.push(`${where}.${key}[${i}] must be a non-empty string`);
+      } else if (isWildcard(item)) {
+        issues.push(
+          `${where}.${key}[${i}] "${item}" is a wildcard — omit ${key} entirely if the entry is ` +
+            'meant to apply everywhere, so the report shows it as unscoped'
+        );
+      }
+    });
+  }
+
+  if (entry.expires !== undefined) {
+    if (!isNonEmptyString(entry.expires) || !isIsoDate(entry.expires)) {
+      issues.push(`${where}.expires must be an ISO date, e.g. "2026-12-31"`);
+    }
+  }
+
+  if (entry.ticket !== undefined && !isNonEmptyString(entry.ticket)) {
+    issues.push(`${where}.ticket must be a non-empty string when present`);
+  }
+}
+
+function validateRoute(route: unknown, index: number, issues: string[]): void {
+  const where = `routes[${index}]`;
+  if (!isPlainObject(route)) {
+    issues.push(`${where} must be an object`);
+    return;
+  }
+  if (!isNonEmptyString(route.path)) {
+    issues.push(`${where}.path is required`);
+  } else if (!route.path.startsWith('/')) {
+    issues.push(`${where}.path "${route.path}" must start with "/"`);
+  }
+  if (route.name !== undefined && !isNonEmptyString(route.name)) {
+    issues.push(`${where}.name must be a non-empty string when present`);
+  }
+  if (route.waitForSelector !== undefined && !isNonEmptyString(route.waitForSelector)) {
+    issues.push(`${where}.waitForSelector must be a non-empty string when present`);
+  }
+  if (
+    route.settleMs !== undefined &&
+    (typeof route.settleMs !== 'number' || !Number.isFinite(route.settleMs) || route.settleMs < 0)
+  ) {
+    issues.push(`${where}.settleMs must be a non-negative number when present`);
+  }
+  if (
+    route.minTextLength !== undefined &&
+    (typeof route.minTextLength !== 'number' ||
+      !Number.isFinite(route.minTextLength) ||
+      route.minTextLength < 0)
+  ) {
+    issues.push(`${where}.minTextLength must be a non-negative number when present`);
+  }
+}
+
+function validateServe(serve: unknown, issues: string[]): void {
+  if (!isPlainObject(serve)) {
+    issues.push('serve is required and must be an object');
+    return;
+  }
+  const modes = (['staticDir', 'command', 'baseUrl'] as const).filter((k) =>
+    isNonEmptyString(serve[k])
+  );
+  if (modes.length === 0) {
+    issues.push('serve must set exactly one of staticDir, command or baseUrl');
+  } else if (modes.length > 1) {
+    issues.push(`serve sets ${modes.join(' and ')} — pick exactly one`);
+  }
+  if (isNonEmptyString(serve.command) && typeof serve.port !== 'number') {
+    issues.push('serve.port is required when serve.command is used');
+  }
+  if (
+    serve.readyTimeoutMs !== undefined &&
+    (typeof serve.readyTimeoutMs !== 'number' || serve.readyTimeoutMs <= 0)
+  ) {
+    issues.push('serve.readyTimeoutMs must be a positive number when present');
+  }
+}
+
+/**
+ * Validate a raw parsed config and fill in defaults.
+ *
+ * @throws ConfigError listing every problem found, not just the first.
+ */
+export function resolveConfig(raw: unknown): ResolvedConfig {
+  const issues: string[] = [];
+
+  if (!isPlainObject(raw)) {
+    throw new ConfigError(['config must be a JSON object']);
+  }
+
+  if (!isNonEmptyString(raw.name)) {
+    issues.push('name is required (use the repo name, e.g. "vibecontrols-app")');
+  }
+
+  validateServe(raw.serve, issues);
+
+  if (!Array.isArray(raw.routes) || raw.routes.length === 0) {
+    issues.push('routes must be a non-empty array — an audit with no routes proves nothing');
+  } else {
+    raw.routes.forEach((route, i) => validateRoute(route, i, issues));
+  }
+
+  if (raw.viewports !== undefined) {
+    if (!Array.isArray(raw.viewports) || raw.viewports.length === 0) {
+      issues.push('viewports must be a non-empty array when present');
+    } else {
+      raw.viewports.forEach((vp, i) => {
+        if (
+          !isPlainObject(vp) ||
+          !isNonEmptyString(vp.name) ||
+          typeof vp.width !== 'number' ||
+          typeof vp.height !== 'number'
+        ) {
+          issues.push(`viewports[${i}] must be { name, width, height }`);
+        }
+      });
+    }
+  }
+
+  if (raw.standard !== undefined) {
+    if (!Array.isArray(raw.standard) || raw.standard.length === 0) {
+      issues.push('standard must be a non-empty array of axe tags when present');
+    } else if (!raw.standard.every(isNonEmptyString)) {
+      issues.push('standard entries must be non-empty axe tag strings');
+    }
+  }
+
+  if (raw.failOn !== undefined) {
+    if (!Array.isArray(raw.failOn) || raw.failOn.length === 0) {
+      issues.push('failOn must be a non-empty array when present');
+    } else {
+      for (const level of raw.failOn) {
+        if (typeof level !== 'string' || !IMPACT_LEVELS.includes(level as ImpactLevel)) {
+          issues.push(`failOn contains "${String(level)}" — allowed: ${IMPACT_LEVELS.join(', ')}`);
+        }
+      }
+      if (Array.isArray(raw.failOn) && !raw.failOn.includes('critical')) {
+        issues.push('failOn must include "critical" — the fleet floor is critical + serious');
+      }
+      if (Array.isArray(raw.failOn) && !raw.failOn.includes('serious')) {
+        issues.push('failOn must include "serious" — the fleet floor is critical + serious');
+      }
+    }
+  }
+
+  if (raw.allowlist !== undefined) {
+    if (!Array.isArray(raw.allowlist)) {
+      issues.push('allowlist must be an array when present');
+    } else {
+      raw.allowlist.forEach((entry, i) => validateAllowlistEntry(entry, i, issues));
+    }
+  }
+
+  if (issues.length > 0) throw new ConfigError(issues);
+
+  const config = raw as unknown as A11yAuditConfig;
+  const settleMs = typeof config.settleMs === 'number' ? config.settleMs : 1500;
+
+  return {
+    name: config.name,
+    serve: {
+      ...config.serve,
+      spa: config.serve.spa !== false,
+      readyTimeoutMs: config.serve.readyTimeoutMs ?? 60_000,
+    },
+    routes: config.routes.map((route: RouteSpec) => ({
+      ...route,
+      name: route.name ?? route.path,
+      allowRedirect: route.allowRedirect ?? false,
+    })),
+    viewports: config.viewports ?? DEFAULT_VIEWPORTS,
+    standard: config.standard ?? DEFAULT_STANDARD,
+    failOn: config.failOn ?? DEFAULT_FAIL_ON,
+    allowlist: (config.allowlist ?? []) as AllowlistEntry[],
+    reportPath: config.reportPath ?? 'a11y-report.json',
+    failOnStaleAllowlist: config.failOnStaleAllowlist ?? false,
+    navigationTimeoutMs: config.navigationTimeoutMs ?? 45_000,
+    settleMs,
+    blockExternalRequests: config.blockExternalRequests !== false,
+    domQuietMs: config.domQuietMs ?? 1500,
+    minTextLength: config.minTextLength ?? 100,
+    routeAttempts: config.routeAttempts ?? 3,
+  };
+}

package/scripts/a11y-audit/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Programmatic entry point for the accessibility gate, for the rare consumer
+ * that needs to embed the audit rather than shell out to the CLI.
+ */
+
+export { resolveConfig, ConfigError, DEFAULT_FAIL_ON, DEFAULT_STANDARD } from './config';
+export {
+  entryCovers,
+  findUnreachableRouteScopes,
+  flattenViolations,
+  isExpired,
+  partitionNodes,
+  routeMatches,
+  selectorMatches,
+} from './allowlist';
+export { renderConsole, renderMarkdown } from './report';
+export { runAudit } from './audit';
+export { startApp } from './server';
+export type * from './types';

package/scripts/a11y-audit/report.ts

@@ -0,0 +1,144 @@
+/**
+ * Report rendering. Pure string building so the output format is testable and
+ * the CLI stays a thin shell.
+ */
+
+import type { AuditReport, FlatNode } from './types';
+
+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 }
+  >();
+  for (const node of nodes) {
+    const existing = byRule.get(node.rule);
+    if (existing) existing.count += 1;
+    else
+      byRule.set(node.rule, {
+        rule: node.rule,
+        impact: node.impact,
+        count: 1,
+        helpUrl: node.helpUrl,
+        help: node.help,
+      });
+  }
+  return [...byRule.values()].sort((a, b) => b.count - a.count || a.rule.localeCompare(b.rule));
+}
+
+/** Human-readable console report. */
+export function renderConsole(report: AuditReport): string {
+  const lines: string[] = [];
+  lines.push('');
+  lines.push(`  a11y-audit — ${report.name}`);
+  lines.push(
+    `  axe-core ${report.axeVersion} · tags: ${report.standard.join(', ')} · failing on: ${report.failOn.join(', ')}`
+  );
+  lines.push(
+    `  base URL: ${report.baseUrl}` +
+      (report.blockExternalRequests ? ' (external requests blocked)' : '')
+  );
+  lines.push('');
+
+  for (const route of report.routes) {
+    const status = route.blocking.length === 0 ? 'PASS' : 'FAIL';
+    const redirect = route.finalUrl.endsWith(route.route) ? '' : `  ->  ${route.finalUrl}`;
+    lines.push(
+      `  [${status}] ${route.routeName} @ ${route.viewport}${redirect}` +
+        `\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)'}`
+    );
+    for (const entry of ruleSummary(route.blocking)) {
+      lines.push(`           x ${entry.rule} (${entry.impact}) x${entry.count} — ${entry.help}`);
+      for (const node of route.blocking.filter((n) => n.rule === entry.rule).slice(0, 5)) {
+        lines.push(`               ${node.target.join(' , ')}`);
+      }
+      const hidden = route.blocking.filter((n) => n.rule === entry.rule).length - 5;
+      if (hidden > 0) lines.push(`               ... and ${hidden} more node(s)`);
+      lines.push(`               ${entry.helpUrl}`);
+    }
+    for (const node of route.allowed) {
+      lines.push(
+        `           ~ ${node.rule} (${node.impact}) allowlisted [#${node.allowlistIndex}` +
+          `${node.allowlistTicket ? ` ${node.allowlistTicket}` : ''}]: ${node.allowlistReason}`
+      );
+    }
+  }
+
+  lines.push('');
+  lines.push(
+    `  TOTAL: ${report.totals.blocking} blocking · ${report.totals.allowed} allowlisted · ` +
+      `${report.totals.advisory} advisory across ${report.totals.routesAudited} route/viewport runs`
+  );
+
+  if (report.expiredAllowlistEntries.length > 0) {
+    lines.push('');
+    lines.push('  EXPIRED allowlist entries (they no longer suppress anything):');
+    for (const entry of report.expiredAllowlistEntries) {
+      lines.push(`    - allowlist[${entry.index}] ${entry.rule} expired ${entry.expires}`);
+    }
+  }
+
+  if (report.staleAllowlistEntries.length > 0) {
+    lines.push('');
+    lines.push('  STALE allowlist entries (matched nothing this run — delete them):');
+    for (const entry of report.staleAllowlistEntries) {
+      lines.push(`    - allowlist[${entry.index}] ${entry.rule}: ${entry.reason}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** GitHub step-summary flavoured markdown. */
+export function renderMarkdown(report: AuditReport): string {
+  const lines: string[] = [];
+  const verdict = report.totals.blocking === 0 ? 'PASS' : 'FAIL';
+  lines.push(`## Accessibility (WCAG 2.1 AA) — ${report.name}: ${verdict}`);
+  lines.push('');
+  lines.push(
+    `axe-core \`${report.axeVersion}\`, tags \`${report.standard.join(', ')}\`, failing on ` +
+      `\`${report.failOn.join(', ')}\`.`
+  );
+  lines.push('');
+  lines.push('| Route | Viewport | Blocking | Allowlisted | Advisory |');
+  lines.push('| --- | --- | ---: | ---: | ---: |');
+  for (const route of report.routes) {
+    lines.push(
+      `| \`${route.routeName}\` | ${route.viewport} | ${route.blocking.length} | ` +
+        `${route.allowed.length} | ${route.advisory.length} |`
+    );
+  }
+
+  const allBlocking = report.routes.flatMap((r) => r.blocking);
+  if (allBlocking.length > 0) {
+    lines.push('');
+    lines.push('### Blocking violations');
+    lines.push('');
+    lines.push('| Rule | Impact | Nodes | Help |');
+    lines.push('| --- | --- | ---: | --- |');
+    for (const entry of ruleSummary(allBlocking)) {
+      lines.push(
+        `| \`${entry.rule}\` | ${entry.impact} | ${entry.count} | [${entry.help}](${entry.helpUrl}) |`
+      );
+    }
+  }
+
+  if (report.staleAllowlistEntries.length > 0 || report.expiredAllowlistEntries.length > 0) {
+    lines.push('');
+    lines.push('### Allowlist hygiene');
+    for (const entry of report.expiredAllowlistEntries) {
+      lines.push(`- expired: \`allowlist[${entry.index}]\` \`${entry.rule}\` (${entry.expires})`);
+    }
+    for (const entry of report.staleAllowlistEntries) {
+      lines.push(`- stale: \`allowlist[${entry.index}]\` \`${entry.rule}\` matched nothing`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}