a11y-loop 0.1.0

package/src/lib/axe-runner.js

@@ -0,0 +1,400 @@
+/**
+ * The audit engine: five rendering passes, own checks, interaction states.
+ *
+ * Engine choice is deliberate and documented in docs/research/tooling.md:
+ * axe-core via @axe-core/playwright, Chromium only, one engine done well.
+ * Pa11y is LGPL and pins a stale axe; Lighthouse's accessibility category is an
+ * axe subset behind a gameable 0–100 score.
+ *
+ * The five passes cost almost nothing and roughly double real-world contrast
+ * findings, because a single default-mode scan never sees dark-mode or
+ * forced-colors failures.
+ */
+
+import { chromium } from 'playwright';
+import { AxeBuilder } from '@axe-core/playwright';
+
+import { HELPERS_SOURCE, tabbableScript } from './browser-utils.js';
+import { makeFinding, dedupeFindings, SEVERITY } from './finding.js';
+import { isBestPractice } from './wcag-map.js';
+import { suggestColors } from './suggest-color.js';
+import { resolveTarget } from './serve.js';
+
+import { surveyKeyboard, keyboardFindings } from './checks/keyboard.js';
+import { surveyFocusVisibility, focusVisibilityFindings } from './checks/focus-visible.js';
+import { surveyTargets, targetSizeFindings } from './checks/target-size.js';
+import { surveyAnimations, reducedMotionFindings } from './checks/reduced-motion.js';
+import { surveyLinks, linkTextFindings } from './checks/link-text.js';
+import { surveyReflow, reflowFindings, REFLOW_VIEWPORT } from './checks/reflow.js';
+import { surveyClickableNonInteractive, divButtonFindings } from './checks/div-button.js';
+import {
+  hasVisibleDialog,
+  captureDialogInitialState,
+  surveyDialog,
+  dialogFindings,
+  surveyRoleButtons,
+  roleButtonFindings,
+} from './checks/dialog.js';
+
+export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+
+/**
+ * axe tags are NOT cumulative — every tag must be listed explicitly or coverage
+ * silently drops. `best-practice` is included so those rules can be reported in
+ * their own non-blocking bucket, and removed by --no-best-practice.
+ */
+export const WCAG_TAGS = [
+  'wcag2a',
+  'wcag2aa',
+  'wcag21a',
+  'wcag21aa',
+  'wcag22a',
+  'wcag22aa',
+];
+
+export const BEST_PRACTICE_TAG = 'best-practice';
+
+/** The five rendering passes. */
+export const PASSES = [
+  { name: 'default', viewport: DEFAULT_VIEWPORT, context: {} },
+  { name: 'dark', viewport: DEFAULT_VIEWPORT, context: { colorScheme: 'dark' } },
+  { name: 'forced-colors', viewport: DEFAULT_VIEWPORT, context: { forcedColors: 'active' } },
+  { name: 'reduced-motion', viewport: DEFAULT_VIEWPORT, context: { reducedMotion: 'reduce' } },
+  { name: 'reflow', viewport: REFLOW_VIEWPORT, context: {} },
+];
+
+/** An error the CLI should report as a tool failure (exit 2), not a finding. */
+export class ToolError extends Error {
+  constructor(message, { hint } = {}) {
+    super(message);
+    this.name = 'ToolError';
+    this.hint = hint ?? null;
+  }
+}
+
+const MISSING_BROWSER_HINT = [
+  'Install the browser a11y-loop needs:',
+  '',
+  '  npx playwright install chromium',
+  '',
+  'If you keep Playwright browsers outside the default location, set',
+  'PLAYWRIGHT_BROWSERS_PATH to that directory both when installing and when running',
+  'a11y-loop — a11y-loop honours it automatically when it is set. For example:',
+  '',
+  '  PLAYWRIGHT_BROWSERS_PATH=/path/to/playwright-browsers npx playwright install chromium',
+].join('\n');
+
+/** Launch Chromium, translating a missing install into an actionable message. */
+export async function launchBrowser({ headed = false } = {}) {
+  try {
+    return await chromium.launch({ headless: !headed });
+  } catch (error) {
+    const message = String(error?.message ?? '');
+    if (/Executable doesn't exist|Failed to launch|browserType\.launch/i.test(message)) {
+      throw new ToolError('Chromium is not available to Playwright.', {
+        hint: MISSING_BROWSER_HINT,
+      });
+    }
+    throw error;
+  }
+}
+
+/** `"4.5:1"` → 4.5 */
+function parseExpectedRatio(value, fallback = 4.5) {
+  const n = Number.parseFloat(String(value ?? ''));
+  return Number.isFinite(n) ? n : fallback;
+}
+
+/**
+ * Concrete colour suggestions for a contrast finding — the thing that closes the
+ * loop for an agent. "3.8:1, fails" is not actionable; "#6B7280 → #4B5563
+ * (3.8:1 → 7.1:1), or lighten the background to #F9FAFB" is.
+ */
+export function contrastSuggestionsForNode(node) {
+  const data = node.any?.find((check) => check.data?.fgColor && check.data?.bgColor)?.data;
+  if (!data) return undefined;
+  const target = parseExpectedRatio(data.expectedContrastRatio);
+  try {
+    const result = suggestColors(data.fgColor, data.bgColor, { target });
+    return result.suggestions.length ? result.suggestions : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const CONTRAST_RULES = new Set(['color-contrast', 'color-contrast-enhanced']);
+
+/** Convert one axe result entry into a11y-loop findings. */
+export function findingsFromAxeResult(result, { severity, passName, state }) {
+  return result.nodes.map((node) => {
+    // target-size findings are ALWAYS downgraded: axe ships the rule disabled
+    // because of a documented false-positive trail with overlapping and
+    // translucent targets.
+    const effectiveSeverity =
+      result.id === 'target-size' ? SEVERITY.NEEDS_REVIEW : severity;
+
+    return makeFinding({
+      ruleId: result.id,
+      source: 'axe',
+      severity: effectiveSeverity,
+      impact: node.impact ?? result.impact ?? null,
+      tags: result.tags ?? [],
+      selector: node.ancestry ?? node.target,
+      html: node.html,
+      message: node.failureSummary
+        ? `${result.help}. ${node.failureSummary.replace(/\s+/g, ' ')}`
+        : result.help,
+      helpUrl: result.helpUrl,
+      suggestions: CONTRAST_RULES.has(result.id) ? contrastSuggestionsForNode(node) : undefined,
+      passes: [passName],
+      state,
+    });
+  });
+}
+
+/** Split axe output into our three buckets and flatten to findings. */
+export function findingsFromAxeResults(axeResults, { passName, state = null }) {
+  const findings = [];
+  for (const violation of axeResults.violations ?? []) {
+    const severity = isBestPractice(violation.tags ?? [])
+      ? SEVERITY.BEST_PRACTICE
+      : SEVERITY.VIOLATION;
+    findings.push(...findingsFromAxeResult(violation, { severity, passName, state }));
+  }
+  for (const incomplete of axeResults.incomplete ?? []) {
+    findings.push(
+      ...findingsFromAxeResult(incomplete, {
+        severity: SEVERITY.NEEDS_REVIEW,
+        passName,
+        state,
+      }),
+    );
+  }
+  return findings;
+}
+
+/** Count what is on the page, so the manual checklist can be specific. */
+export async function surveyPageFacts(page) {
+  return page.evaluate(() => {
+    const count = (selector) => document.querySelectorAll(selector).length;
+    let ariaAttributes = 0;
+    for (const el of document.querySelectorAll('*')) {
+      for (const attr of el.attributes) {
+        if (attr.name === 'role' || attr.name.startsWith('aria-')) ariaAttributes += 1;
+      }
+    }
+    let animations = 0;
+    let stickyElements = 0;
+    for (const el of document.querySelectorAll('*')) {
+      const style = getComputedStyle(el);
+      if (style.animationName && style.animationName !== 'none') animations += 1;
+      if (style.position === 'sticky' || style.position === 'fixed') stickyElements += 1;
+    }
+    return {
+      images: count('img, [role="img"], svg[aria-label], svg[role="img"]'),
+      formFields: count('input:not([type="hidden"]), select, textarea'),
+      links: count('a[href], [role="link"]'),
+      headings: count('h1, h2, h3, h4, h5, h6, [role="heading"]'),
+      videos: count('video'),
+      audios: count('audio'),
+      tables: count('table'),
+      iframes: count('iframe'),
+      dialogs: count('[role="dialog"], [role="alertdialog"], dialog'),
+      buttons: count('button, [role="button"]'),
+      ariaAttributes,
+      animations,
+      stickyElements,
+      lang: document.documentElement.getAttribute('lang'),
+      title: document.title,
+    };
+  });
+}
+
+/** Prepare a page: inject helpers and tabbable, then navigate. */
+async function openPage(context, url) {
+  const page = await context.newPage();
+  await page.addInitScript({ content: tabbableScript() });
+  await page.addInitScript({ content: HELPERS_SOURCE });
+  await page.goto(url, { waitUntil: 'load' });
+  // Let webfonts settle and any entrance animation finish, so contrast and
+  // geometry are measured against what a user would actually see.
+  await page.waitForTimeout(120);
+  return page;
+}
+
+function buildAxe(page, { includeBestPractice }) {
+  const tags = includeBestPractice ? [...WCAG_TAGS, BEST_PRACTICE_TAG] : [...WCAG_TAGS];
+  return new AxeBuilder({ page }).options({
+    runOnly: { type: 'tag', values: tags },
+    resultTypes: ['violations', 'incomplete'],
+    ancestry: true,
+    // Tag filtering does not resurrect a disabled rule; target-size has to be
+    // switched on by name. Its findings are always downgraded to needs-review.
+    rules: { 'target-size': { enabled: true } },
+  });
+}
+
+/**
+ * Own checks that only make sense once, on a normally-rendered page.
+ *
+ * The dialog's initial-focus state is captured FIRST, before anything else
+ * runs: the keyboard and focus-visibility surveys each drive real Tab presses
+ * to walk the page, which moves focus around, and "was focus moved into the
+ * dialog on open" must answer for the moment the dialog opened — not for
+ * wherever those other surveys happened to leave focus afterwards. The
+ * interactive probes (trap, Escape, focus-return) still run last, since
+ * pressing Escape may close the dialog and change page state for anything
+ * that ran after it.
+ */
+async function runDefaultPassChecks(page, ctx) {
+  const findings = [];
+
+  const dialogInitial = (await hasVisibleDialog(page))
+    ? await captureDialogInitialState(page, { presumedTrigger: ctx.presumedTrigger ?? null })
+    : null;
+
+  const keyboard = await surveyKeyboard(page);
+  findings.push(...keyboardFindings(keyboard, ctx));
+
+  const focus = await surveyFocusVisibility(page);
+  findings.push(...focusVisibilityFindings(focus, ctx));
+
+  const targets = await surveyTargets(page);
+  findings.push(...targetSizeFindings(targets, ctx));
+
+  const links = await surveyLinks(page);
+  findings.push(...linkTextFindings(links, ctx));
+
+  const clickableDivs = await surveyClickableNonInteractive(page);
+  findings.push(...divButtonFindings(clickableDivs, ctx));
+
+  const roleButtons = await surveyRoleButtons(page);
+  findings.push(...roleButtonFindings(roleButtons, ctx));
+
+  if (dialogInitial) {
+    const dialog = await surveyDialog(page, dialogInitial);
+    findings.push(...dialogFindings(dialog, ctx));
+  }
+
+  return findings;
+}
+
+/**
+ * Run the audit.
+ *
+ * @param {object} input
+ * @param {{type:'url'|'file'|'html', value:string}} input.target
+ * @param {object} [input.options]
+ * @param {boolean} [input.options.headed]
+ * @param {boolean} [input.options.bestPractice]
+ * @param {Record<string, (page:any) => Promise<void>>} [input.options.states]
+ * @returns {Promise<{findings:Array, facts:object, tool:object, incompleteRuleIds:string[]}>}
+ */
+export async function runAudit({ target, options = {} }) {
+  const { headed = false, bestPractice = true, states = {} } = options;
+
+  const served = await resolveTarget(target);
+  const browser = await launchBrowser({ headed });
+  const findings = [];
+  const passesRun = [];
+  const statesRun = [];
+  let facts = {};
+  let browserVersion = 'unknown';
+  let userAgent = null;
+
+  try {
+    browserVersion = browser.version();
+
+    for (const pass of PASSES) {
+      const context = await browser.newContext({ viewport: pass.viewport, ...pass.context });
+      const page = await openPage(context, served.url);
+      const ctx = { passes: [pass.name], state: null };
+
+      try {
+        const axeResults = await buildAxe(page, { includeBestPractice: bestPractice }).analyze();
+        findings.push(...findingsFromAxeResults(axeResults, { passName: pass.name }));
+
+        if (pass.name === 'default') {
+          userAgent = await page.evaluate(() => navigator.userAgent);
+          facts = await surveyPageFacts(page);
+          findings.push(...(await runDefaultPassChecks(page, ctx)));
+        }
+
+        if (pass.name === 'reduced-motion') {
+          const animations = await surveyAnimations(page);
+          findings.push(...reducedMotionFindings(animations, ctx));
+        }
+
+        if (pass.name === 'reflow') {
+          const overflow = await surveyReflow(page);
+          findings.push(...reflowFindings(overflow, ctx));
+        }
+
+        passesRun.push(pass.name);
+      } finally {
+        await context.close();
+      }
+    }
+
+    // --interact states: the "state coverage" pillar. Each state gets a fresh
+    // page, so states never contaminate each other.
+    //
+    // Only findings the base page did NOT already have are reported for a state.
+    // Otherwise every pre-existing issue would be repeated once per state, and a
+    // page with five states would report six times its actual problems.
+    const baseFingerprints = new Set(findings.map((f) => f.fingerprint));
+
+    for (const [name, setup] of Object.entries(states)) {
+      const context = await browser.newContext({ viewport: DEFAULT_VIEWPORT });
+      const page = await openPage(context, served.url);
+      const ctx = { passes: ['default'], state: name };
+      try {
+        await setup(page);
+        await page.waitForTimeout(150);
+
+        // The last element clicked, not whatever currently has focus: a
+        // well-behaved dialog moves focus into itself as soon as it opens,
+        // which would overwrite the one clue that identifies the trigger by
+        // the time anything looked at document.activeElement.
+        const presumedTrigger = await page.evaluate(() => window.__a11yLoop.lastClickSelector());
+
+        const axeResults = await buildAxe(page, { includeBestPractice: bestPractice }).analyze();
+        const stateFindings = [
+          ...findingsFromAxeResults(axeResults, { passName: 'default', state: name }),
+          ...(await runDefaultPassChecks(page, { ...ctx, presumedTrigger })),
+        ];
+        findings.push(...stateFindings.filter((f) => !baseFingerprints.has(f.fingerprint)));
+        statesRun.push(name);
+      } catch (error) {
+        throw new ToolError(`The --interact state "${name}" threw: ${error.message}`, {
+          hint: 'Each state is `async (page) => { … }` and receives a Playwright Page.',
+        });
+      } finally {
+        await context.close();
+      }
+    }
+  } finally {
+    await browser.close();
+    await served.close();
+  }
+
+  const deduped = dedupeFindings(findings);
+  const incompleteRuleIds = [
+    ...new Set(
+      deduped
+        .filter((f) => f.severity === SEVERITY.NEEDS_REVIEW && f.source === 'axe')
+        .map((f) => f.ruleId),
+    ),
+  ];
+
+  return {
+    findings: deduped,
+    facts,
+    incompleteRuleIds,
+    passesRun,
+    statesRun,
+    browserVersion,
+    userAgent,
+    url: served.url,
+  };
+}

package/src/lib/browser-utils.js

@@ -0,0 +1,221 @@
+/**
+ * Code injected into the audited page.
+ *
+ * `tabbable` is loaded from its UMD build (it is a browser library, not a Node
+ * one) and the small helper set below gives every own check a consistent way to
+ * name an element in a report.
+ */
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+
+let tabbableSource = null;
+
+/** The tabbable UMD bundle, read once. */
+export function tabbableScript() {
+  if (tabbableSource === null) {
+    tabbableSource = readFileSync(require.resolve('tabbable/dist/index.umd.min.js'), 'utf8');
+  }
+  return tabbableSource;
+}
+
+/**
+ * Helpers available in-page as `window.__a11yLoop`.
+ * Kept as a source string so it can go through `addInitScript`, which runs
+ * before page scripts on every navigation.
+ */
+export const HELPERS_SOURCE = `
+(() => {
+  if (window.__a11yLoop) return;
+
+  /** A short, stable-ish CSS path for an element. */
+  function cssPath(el) {
+    if (!el || el.nodeType !== 1) return '';
+    if (el === document.documentElement) return 'html';
+    if (el === document.body) return 'html > body';
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && parts.length < 7) {
+      let part = node.tagName.toLowerCase();
+      if (node.id && /^[A-Za-z][-\\w]*$/.test(node.id)) {
+        parts.unshift('#' + node.id);
+        break;
+      }
+      const cls = (node.getAttribute('class') || '')
+        .trim()
+        .split(/\\s+/)
+        .filter((c) => c && /^[A-Za-z][-\\w]*$/.test(c))
+        .slice(0, 2);
+      if (cls.length) part += '.' + cls.join('.');
+      const parent = node.parentElement;
+      if (parent) {
+        const sameTag = Array.from(parent.children).filter((c) => c.tagName === node.tagName);
+        if (sameTag.length > 1) part += ':nth-of-type(' + (sameTag.indexOf(node) + 1) + ')';
+      }
+      parts.unshift(part);
+      node = parent;
+      // Stop at the root so paths read like axe's ancestry selectors.
+      if (node === document.documentElement) {
+        parts.unshift('html');
+        break;
+      }
+    }
+    return parts.join(' > ');
+  }
+
+  /** Opening tag plus a little text — enough for an agent to locate the element. */
+  function shortHtml(el, limit) {
+    if (!el || el.nodeType !== 1) return '';
+    const html = el.outerHTML || '';
+    return html.length > (limit || 200) ? html.slice(0, limit || 200) : html;
+  }
+
+  /** Accessible name, best effort: aria-label, aria-labelledby, then text. */
+  function accessibleName(el) {
+    if (!el) return '';
+    const label = el.getAttribute && el.getAttribute('aria-label');
+    if (label && label.trim()) return label.trim();
+    const ids = el.getAttribute && el.getAttribute('aria-labelledby');
+    if (ids) {
+      const text = ids
+        .split(/\\s+/)
+        .map((id) => {
+          const target = document.getElementById(id);
+          return target ? (target.textContent || '').trim() : '';
+        })
+        .filter(Boolean)
+        .join(' ');
+      if (text) return text;
+    }
+    if (el.tagName === 'IMG') {
+      const alt = el.getAttribute('alt');
+      if (alt !== null) return alt.trim();
+    }
+    if (el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA') {
+      if (el.labels && el.labels.length) {
+        return Array.from(el.labels).map((l) => (l.textContent || '').trim()).join(' ');
+      }
+      const title = el.getAttribute('title');
+      if (title) return title.trim();
+      const value = el.getAttribute('value');
+      if (el.type === 'submit' || el.type === 'button') return (value || '').trim();
+    }
+    return (el.textContent || '').replace(/\\s+/g, ' ').trim();
+  }
+
+  /** Is the element actually rendered — regardless of who it is hidden from? */
+  function isRendered(el) {
+    if (!el || el.nodeType !== 1) return false;
+    const style = getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+    if (Number(style.opacity) === 0) return false;
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0) return false;
+    return true;
+  }
+
+  /**
+   * Is the element rendered AND exposed to assistive technology / keyboard
+   * navigation? Most checks want this — an aria-hidden element is not
+   * reachable, not announced, not a real target. Motion is the exception:
+   * SC 2.2.2 is about what a SIGHTED user sees moving on screen, which has
+   * nothing to do with the accessibility tree, so the reduced-motion check
+   * uses isRendered directly rather than this.
+   */
+  function isVisible(el) {
+    if (!isRendered(el)) return false;
+    if (el.closest('[aria-hidden="true"]')) return false;
+    // A native <dialog> opened with showModal() (or a fullscreen element)
+    // makes everything outside itself genuinely inert: unclickable,
+    // unfocusable, unreachable by Tab, whatever the DOM and CSS say. Without
+    // this, every check that surveys "visible" elements would flood a report
+    // with the rest of the page once a modal is open — not a real defect,
+    // just this helper not knowing the platform already handled it.
+    var modal = document.querySelector(':modal');
+    if (modal && !modal.contains(el)) return false;
+    return true;
+  }
+
+  // Record the CSS path of whatever was last clicked, for the whole life of
+  // the page. This is how a dialog check identifies "the trigger" when
+  // nothing declares it explicitly (no aria-controls / data-dialog-target):
+  // a click is a far more reliable signal than "whatever has focus right
+  // now", because a well-behaved dialog moves focus into itself as soon as
+  // it opens, which overwrites the one clue that would otherwise identify
+  // the trigger by the time anything gets a chance to look.
+  document.addEventListener(
+    'click',
+    function (event) {
+      window.__a11yLoopLastClick = cssPath(event.target);
+    },
+    true,
+  );
+
+  /** Elements a user can interact with — the population for target-size etc. */
+  function interactiveElements() {
+    const selector = [
+      'a[href]', 'button', 'input:not([type="hidden"])', 'select', 'textarea',
+      'summary', '[role="button"]', '[role="link"]', '[role="checkbox"]',
+      '[role="radio"]', '[role="switch"]', '[role="tab"]', '[role="menuitem"]',
+      '[role="option"]', '[onclick]', '[tabindex]',
+    ].join(',');
+    return Array.from(document.querySelectorAll(selector)).filter((el) => {
+      if (!isVisible(el)) return false;
+      if (el.disabled) return false;
+      return true;
+    });
+  }
+
+  /**
+   * The first opaque background colour behind an element, walking ancestors.
+   * Returns null when nothing determinable is found (a background image or
+   * gradient), which callers must surface as needs-review rather than guess.
+   */
+  function backdropColor(el) {
+    let node = el;
+    while (node && node.nodeType === 1) {
+      const style = getComputedStyle(node);
+      if (style.backgroundImage && style.backgroundImage !== 'none') return null;
+      const bg = style.backgroundColor;
+      const match = /rgba?\\(([^)]+)\\)/.exec(bg || '');
+      if (match) {
+        const parts = match[1].split(/[,\\s/]+/).filter(Boolean).map(Number);
+        const alpha = parts.length > 3 ? parts[3] : 1;
+        if (alpha >= 1) return 'rgb(' + parts[0] + ', ' + parts[1] + ', ' + parts[2] + ')';
+      }
+      node = node.parentElement;
+    }
+    return 'rgb(255, 255, 255)';
+  }
+
+  /**
+   * Where a forward Tab walk should be scoped: inside the open modal dialog
+   * if there is one (everything outside it is inert and cannot be reached),
+   * otherwise the whole document. tabbable() itself has no idea a native
+   * dialog element made the rest of the page inert, so callers must pass
+   * this as the container rather than always walking document.body.
+   */
+  function tabbableRoot() {
+    return document.querySelector(':modal') || document.body;
+  }
+
+  /** The CSS path of whatever was last clicked, or null if nothing was. */
+  function lastClickSelector() {
+    return window.__a11yLoopLastClick || null;
+  }
+
+  window.__a11yLoop = {
+    cssPath: cssPath,
+    shortHtml: shortHtml,
+    accessibleName: accessibleName,
+    isRendered: isRendered,
+    isVisible: isVisible,
+    tabbableRoot: tabbableRoot,
+    lastClickSelector: lastClickSelector,
+    interactiveElements: interactiveElements,
+    backdropColor: backdropColor,
+  };
+})();
+`;