automatica11y 0.0.0-stage → 0.3.0

package/src/tiers/rules/axe.js

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+let axeSource = null;
+
+/** Hand AxeBuilder our own axe-core, so the version we record is the version that ran. */
+function loadAxe() {
+  axeSource ??= readFileSync(require.resolve("axe-core/axe.min.js"), "utf8");
+  return axeSource;
+}
+
+/** Tag sets that match a WCAG version and level. Best-practice rules aren't WCAG, so they stay out. */
+export function axeTags(wcag, level) {
+  const tags = ["wcag2a"];
+  if (level !== "A") tags.push("wcag2aa");
+  if (level === "AAA") tags.push("wcag2aaa");
+  if (wcag === "2.1" || wcag === "2.2") {
+    tags.push("wcag21a");
+    if (level !== "A") tags.push("wcag21aa");
+    if (level === "AAA") tags.push("wcag21aaa");
+  }
+  if (wcag === "2.2") {
+    if (level !== "A") tags.push("wcag22aa");
+    if (level === "AAA") tags.push("wcag22aaa");
+  }
+  return tags;
+}
+
+/** `wcag143` becomes `1.4.3`. Returns null for tags that aren't success criteria. */
+function criterionFromTag(tag) {
+  const match = /^wcag(\d)(\d)(\d{1,2})$/.exec(tag);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+/** An axe target can be nested for iframes and shadow roots. Flatten it to one readable selector. */
+function selectorFor(target) {
+  return (Array.isArray(target) ? target.flat(Infinity) : [target]).join(" ");
+}
+
+function normalize(items, maxNodes) {
+  return items.map((item) => ({
+    ruleId: item.id,
+    impact: item.impact ?? null,
+    wcag: item.tags.map(criterionFromTag).filter(Boolean),
+    tags: item.tags.filter((tag) => tag.startsWith("wcag") || tag.startsWith("best-practice")),
+    help: item.help,
+    helpUrl: item.helpUrl,
+    nodeCount: item.nodes.length,
+    nodes: item.nodes.slice(0, maxNodes).map((node) => ({ selector: selectorFor(node.target), html: String(node.html).slice(0, 300) })),
+  }));
+}
+
+/**
+ * Run axe-core against the page for one WCAG version and level.
+ * @param {import("playwright-core").Page} page
+ * @param {{ wcag: string, level: string, maxNodes?: number, scope?: string | string[] | null }} options
+ *   `scope` is a CSS selector. Component evidence checks only that element, so page-level rules like document title don't fire.
+ */
+export async function runAxe(page, { wcag, level, maxNodes = 5, scope = null }) {
+  const { AxeBuilder } = await import("@axe-core/playwright");
+  const tags = axeTags(wcag, level);
+  const builder = new AxeBuilder({ page, axeSource: loadAxe() }).withTags(tags);
+  for (const selector of [scope ?? []].flat()) builder.include(selector);
+  const result = await builder.analyze();
+  return {
+    status: /** @type {const} */ ("ran"),
+    version: result.testEngine.version,
+    config: { tags, ...(scope ? { scope } : {}) },
+    violations: normalize(result.violations, maxNodes),
+    incomplete: normalize(result.incomplete, maxNodes),
+    passesCount: result.passes.length,
+    notes: /** @type {string[]} */ ([]),
+  };
+}

package/src/tiers/rules/canvas.js

@@ -0,0 +1,34 @@
+/**
+ * Decide whether the scope is mainly a canvas with nothing a rule engine can read.
+ * A canvas is a bitmap to the accessibility tree. Without a text alternative, a nearby table or SVG, or a label,
+ * axe and IBM would find nothing and the result would read as clean. It isn't clean. It's untested.
+ * @param {import("playwright-core").Page} page
+ * @param {string | string[] | null} scope
+ * @returns {Promise<{ canvases: number, canvasOnly: boolean, hasAlternative: boolean }>}
+ */
+export async function inspectCanvas(page, scope) {
+  return page.evaluate((scopes) => {
+    const roots = scopes.length ? scopes.flatMap((selector) => [...document.querySelectorAll(selector)]) : [document.body];
+    const canvases = roots.flatMap((root) => [...root.querySelectorAll("canvas")]);
+    if (canvases.length === 0) return { canvases: 0, canvasOnly: false, hasAlternative: false };
+    const labelled = canvases.some(
+      (canvas) =>
+        canvas.hasAttribute("aria-label") ||
+        canvas.hasAttribute("aria-labelledby") ||
+        ["img", "graphics-document"].includes(canvas.getAttribute("role") ?? "") ||
+        (canvas.textContent ?? "").trim().length > 0,
+    );
+    const nearby = roots.some((root) => root.querySelector('svg, table, [role="img"], [role="graphics-document"], [role="figure"], figure'));
+    const text = roots
+      .map((root) => {
+        const copy = /** @type {HTMLElement} */ (root.cloneNode(true));
+        copy.querySelectorAll("canvas, script, style").forEach((el) => el.remove());
+        return (copy.textContent ?? "").trim();
+      })
+      .join(" ").length;
+    const hasAlternative = labelled || nearby || text >= 20;
+    return { canvases: canvases.length, canvasOnly: !hasAlternative, hasAlternative };
+  }, [scope ?? []].flat());
+}
+
+export const CANVAS_REASON = "Canvas output exposes nothing to rule checks.";

package/src/tiers/rules/ibm.js

@@ -0,0 +1,121 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readPackageVersion } from "../../env/versions.js";
+
+const require = createRequire(import.meta.url);
+let aceSource = null;
+
+/** Read ace.js once. The engine runs inside the page, so we only need its source text. */
+function loadAce() {
+  aceSource ??= readFileSync(require.resolve("accessibility-checker-engine/ace.js"), "utf8");
+  return aceSource;
+}
+
+const LEVEL_ORDER = { A: 1, AA: 2 };
+
+export const helpUrl = (ruleId) => `https://able.ibm.com/rules/archives/latest/doc/en-US/${ruleId}.html`;
+
+/**
+ * Group raw IBM results into findings, one per rule and kind, with the first few nodes.
+ * @param {Array<{ ruleId: string, message: string, dom?: string, snippet?: string }>} items
+ * @param {Map<string, { wcag: string[], toolkitLevel: number | null }>} ruleInfo
+ * @param {(item: any) => string} kindOf
+ * @param {number} maxNodes
+ */
+function group(items, ruleInfo, kindOf, maxNodes, withKind) {
+  const groups = new Map();
+  for (const item of items) {
+    const kind = kindOf(item);
+    const key = withKind ? `${item.ruleId}|${kind}` : item.ruleId;
+    let entry = groups.get(key);
+    if (!entry) {
+      const info = ruleInfo.get(item.ruleId);
+      entry = {
+        ruleId: item.ruleId,
+        impact: null,
+        toolkitLevel: info?.toolkitLevel ?? null,
+        wcag: info?.wcag ?? [],
+        ...(withKind ? { kind } : {}),
+        help: item.message,
+        helpUrl: helpUrl(item.ruleId),
+        nodeCount: 0,
+        nodes: [],
+      };
+      groups.set(key, entry);
+    }
+    entry.nodeCount += 1;
+    if (entry.nodes.length < maxNodes) entry.nodes.push({ selector: item.dom ?? "", html: String(item.snippet ?? "").slice(0, 300) });
+  }
+  return [...groups.values()].sort((a, b) => a.ruleId.localeCompare(b.ruleId));
+}
+
+/**
+ * Run the IBM Equal Access engine against the page.
+ * The engine's WCAG rulesets cover levels A and AA. Level AAA runs the AA rules and says so.
+ * ace.js goes in through page.evaluate, because a strict CSP blocks addScriptTag.
+ * @param {import("playwright-core").Page} page
+ * @param {{ wcag: string, level: string, maxNodes?: number, scope?: string | string[] | null }} options
+ *   `scope` is a CSS selector. Component evidence checks only that element.
+ */
+export async function runIbm(page, { wcag, level, maxNodes = 5, scope = null }) {
+  const ruleset = `WCAG_${wcag.replace(".", "_")}`;
+  const maxLevel = LEVEL_ORDER[level] ?? LEVEL_ORDER.AA;
+  await page.evaluate(loadAce());
+  const scopes = [scope ?? []].flat();
+  const raw = await page.evaluate(async ({ id, scopes }) => {
+    // @ts-ignore ace.js defines window.ace in the page.
+    const checker = new window.ace.Checker();
+    const set = checker.rulesets.find((r) => r.id === id);
+    if (!set) throw new Error(`The IBM engine has no ruleset ${id}.`);
+    const roots = scopes.length ? scopes.flatMap((selector) => [...document.querySelectorAll(selector)]) : [document];
+    if (roots.length === 0) throw new Error(`Nothing matches the scope ${scopes.join(", ")}.`);
+    const passed = new Set();
+    const found = [];
+    const seen = new Set();
+    for (const root of roots) {
+      const report = await checker.check(root, [id]);
+      for (const r of report.results) {
+        if (r.value[1] === "PASS") passed.add(r.ruleId);
+        else {
+          const key = `${r.ruleId}|${r.path?.dom}|${r.value.join()}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          found.push({ ruleId: r.ruleId, value: r.value, message: r.message, dom: r.path?.dom, snippet: r.snippet });
+        }
+      }
+    }
+    return {
+      checkpoints: set.checkpoints.map((cp) => ({ num: cp.num, level: cp.wcagLevel, rules: cp.rules.map((x) => [x.id, x.toolkitLevel]) })),
+      found,
+      passedRules: [...passed],
+    };
+  }, { id: ruleset, scopes });
+
+  /** @type {Map<string, { wcag: string[], toolkitLevel: number | null }>} */
+  const ruleInfo = new Map();
+  for (const checkpoint of raw.checkpoints) {
+    if ((LEVEL_ORDER[checkpoint.level] ?? 99) > maxLevel) continue;
+    for (const [id, toolkit] of checkpoint.rules) {
+      const info = ruleInfo.get(id) ?? { wcag: [], toolkitLevel: null };
+      if (!info.wcag.includes(checkpoint.num)) info.wcag.push(checkpoint.num);
+      const number = Number(toolkit);
+      if (Number.isFinite(number)) info.toolkitLevel = info.toolkitLevel === null ? number : Math.min(info.toolkitLevel, number);
+      ruleInfo.set(id, info);
+    }
+  }
+
+  const inScope = raw.found.filter((item) => ruleInfo.has(item.ruleId));
+  const violations = inScope.filter((item) => item.value[0] === "VIOLATION" && item.value[1] === "FAIL");
+  const review = inScope.filter((item) => !(item.value[0] === "VIOLATION" && item.value[1] === "FAIL"));
+  const reviewKind = (item) => (item.value[1] === "MANUAL" ? "manual" : item.value[1] === "POTENTIAL" ? "potential" : "recommendation");
+  const notes = level === "AAA" ? ["IBM's WCAG rulesets cover levels A and AA. This run used the AA rules."] : [];
+  return {
+    status: /** @type {const} */ ("ran"),
+    version: readPackageVersion("accessibility-checker-engine"),
+    config: { ruleset, levels: level === "A" ? ["A"] : ["A", "AA"], ...(scope ? { scope } : {}) },
+    violations: group(violations, ruleInfo, () => "violation", maxNodes, false),
+    incomplete: group(review, ruleInfo, reviewKind, maxNodes, true),
+    passesCount: raw.passedRules.filter((id) => ruleInfo.has(id)).length,
+    notes,
+  };
+}

package/src/tiers/rules/index.js

@@ -0,0 +1,81 @@
+import { CANVAS_REASON, inspectCanvas } from "./canvas.js";
+import { runAxe } from "./axe.js";
+import { runIbm } from "./ibm.js";
+
+const RUNNERS = { axe: runAxe, ibm: runIbm };
+
+/**
+ * Run each chosen engine against the page. Engines report separately, and one failing engine doesn't stop the other.
+ * @param {import("playwright-core").Page} page
+ * @param {{ engines: string[], wcag: string, level: string, maxNodes?: number, scope?: string | string[] | null }} options
+ */
+export async function runRules(page, { engines, wcag, level, maxNodes = 5, scope = null }) {
+  const canvas = await inspectCanvas(page, scope);
+  if (canvas.canvasOnly) {
+    const reason = `${CANVAS_REASON} The page or component is mainly a canvas with no text alternative, label, table, or SVG, so there was nothing to test.`;
+    return {
+      status: "not-testable",
+      reason,
+      engines: Object.fromEntries(engines.map((engine) => [engine, { status: "not-testable", reason }])),
+    };
+  }
+  /** @type {Record<string, any>} */
+  const results = {};
+  for (const engine of engines) {
+    try {
+      results[engine] = await RUNNERS[/** @type {keyof typeof RUNNERS} */ (engine)](page, { wcag, level, maxNodes, scope });
+    } catch (error) {
+      results[engine] = { status: "failed", reason: error instanceof Error ? error.message.split("\n")[0] : String(error) };
+    }
+  }
+  if (canvas.canvases > 0) {
+    for (const result of Object.values(results)) {
+      if (result.status === "ran") (result.notes ??= []).push("The canvas drawing itself isn't checked. The rules ran on the markup around it.");
+    }
+  }
+  const statuses = Object.values(results).map((r) => r.status);
+  return {
+    status: statuses.includes("ran") ? "ran" : "failed",
+    reason: statuses.includes("ran") ? null : "Every rule engine failed.",
+    engines: results,
+  };
+}
+
+const SELF_TEST_HTML = `<!doctype html><html lang="en"><head><title>Self-test</title></head><body><main><h1>Self-test</h1>
+<img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=">
+<p style="color:#ccc;background:#fff">Low contrast text</p></main></body></html>`;
+
+const EXPECTED = {
+  axe: ["image-alt", "color-contrast"],
+  ibm: ["img_alt_valid", "text_contrast_sufficient"],
+};
+
+/**
+ * Audit a page with known problems and check that every chosen engine flags them.
+ * A run that can't pass this must not report a clean result.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string[]} engines
+ * @param {Function} [run] Swap in a stand-in to test the failure path.
+ */
+export async function selfTest(browser, engines, run = runRules) {
+  const context = await browser.newContext();
+  try {
+    const page = await context.newPage();
+    await page.setContent(SELF_TEST_HTML);
+    const result = await run(page, { engines, wcag: "2.2", level: "AA", maxNodes: 1 });
+    const problems = [];
+    for (const engine of engines) {
+      const engineResult = result.engines[engine];
+      if (engineResult.status !== "ran") {
+        problems.push(`${engine}: ${engineResult.reason}`);
+        continue;
+      }
+      const found = new Set(engineResult.violations.map((v) => v.ruleId));
+      const missing = EXPECTED[/** @type {keyof typeof EXPECTED} */ (engine)].filter((id) => !found.has(id));
+      if (missing.length) problems.push(`${engine} missed ${missing.join(", ")}`);
+    }
+    return { passed: problems.length === 0, problems };
+  } finally {
+    await context.close();
+  }
+}

package/src/tiers/vsr.js

@@ -0,0 +1,134 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { readPackageVersion } from "../env/versions.js";
+
+const require = createRequire(import.meta.url);
+let injected = null;
+
+/**
+ * The browser build of the virtual screen reader is one ES module. Turn its `export` line into a global,
+ * so `page.evaluate` can run it. `evaluate` isn't subject to the page's CSP, and a script tag would be.
+ */
+function loadSource() {
+  if (injected) return injected;
+  const source = readFileSync(require.resolve("@guidepup/virtual-screen-reader/browser.js"), "utf8").replace(/\/\/# sourceMappingURL=.*$/m, "");
+  const exported = /export\s*\{([^}]*)\};?/.exec(source);
+  if (!exported) throw new Error("The virtual screen reader's browser build has an unexpected shape.");
+  const names = exported[1].split(",").map((part) => {
+    const [local, alias] = part.trim().split(/\s+as\s+/);
+    return `${alias ?? local}:${local}`;
+  });
+  injected = `(()=>{${source.replace(/export\s*\{[^}]*\};?/, "")}\nwindow.__vsr={${names.join(",")}};})()`;
+  return injected;
+}
+
+/** Roles that should come with a name. A phrase that is only the role means the control has none. */
+export const UNNAMED_ROLES = new Set([
+  "button", "link", "image", "textbox", "searchbox", "checkbox", "radio", "switch", "slider", "spinbutton",
+  "combobox", "tab", "menuitem", "menuitemcheckbox", "menuitemradio", "option", "dialog", "alertdialog", "listbox", "menu",
+]);
+const GENERIC_ROLES = new Set(["generic", "none", "presentation"]);
+
+/**
+ * Point at phrases a person should look at. This doesn't judge the log. It marks two patterns and nothing else:
+ * a control announced as only its role, and a role announced as generic.
+ * @param {string[]} phrases
+ */
+export function flagPhrases(phrases) {
+  /** @type {Array<{ type: string, phrase: string, index: number }>} */
+  const flags = [];
+  phrases.forEach((phrase, index) => {
+    const text = phrase.trim().toLowerCase();
+    if (UNNAMED_ROLES.has(text)) flags.push({ type: "unnamed-control", phrase, index });
+    else if (GENERIC_ROLES.has(text)) flags.push({ type: "generic-role", phrase, index });
+  });
+  return flags;
+}
+
+/**
+ * Walk the page with the virtual screen reader and record what it would announce.
+ * Every result is simulated. It's not a real screen reader's output.
+ * Open shadow roots inside the scope aren't read, and the result says so.
+ * @param {import("playwright-core").Page} page
+ * @param {{ scope?: string, state?: string | null, maxSteps?: number }} [options]
+ */
+export async function runVsr(page, { scope = "body", state = null, maxSteps = 150 } = {}) {
+  await page.evaluate(loadSource());
+  const hosts = await page.evaluate(async (scope) => {
+    const container = document.querySelector(scope);
+    if (!container) throw new Error(`Nothing matches the scope ${scope}.`);
+    /** Hosts of open shadow roots inside the container, with counts. */
+    const found = {};
+    const visit = (root) => {
+      for (const el of root.querySelectorAll("*")) {
+        if (el.shadowRoot) {
+          found[el.localName] = (found[el.localName] ?? 0) + 1;
+          visit(el.shadowRoot);
+        }
+      }
+    };
+    visit(container);
+    await window.__vsr.virtual.start({ container });
+    return found;
+  }, scope);
+  let phrases = [];
+  let reachedEnd = false;
+  try {
+    while (phrases.length < maxSteps + 1 && !reachedEnd) {
+      const chunk = await page.evaluate(async (steps) => {
+        const virtual = window.__vsr.virtual;
+        for (let i = 0; i < steps; i += 1) {
+          if ((await virtual.lastSpokenPhrase()) === "end of document") break;
+          await virtual.next();
+        }
+        return { log: await virtual.spokenPhraseLog(), ended: (await virtual.lastSpokenPhrase()) === "end of document" };
+      }, 10);
+      phrases = chunk.log;
+      // Inside a container that isn't the whole document, the reader wraps around instead of ending.
+      const period = repeatLength(phrases);
+      if (chunk.ended) reachedEnd = true;
+      else if (period) {
+        phrases = phrases.slice(0, period);
+        reachedEnd = true;
+      }
+    }
+  } finally {
+    await page.evaluate(() => window.__vsr.virtual.stop());
+  }
+  phrases = phrases.slice(0, maxSteps + 1);
+  const notTestable = Object.entries(hosts).map(([tag, n]) => `open shadow root in <${tag}> (${n}): the virtual screen reader doesn't read inside it`);
+  return {
+    status: /** @type {const} */ ("ran"),
+    simulated: true,
+    version: readPackageVersion("@guidepup/virtual-screen-reader"),
+    log: [{ state, announcements: phrases, reachedEnd, truncated: !reachedEnd }],
+    flags: flagPhrases(phrases).map((flag) => ({ ...flag, state })),
+    notTestable,
+    notes: reachedEnd ? [] : [`The walk stopped after ${maxSteps} steps, before it came back around to the start.`],
+  };
+}
+
+/**
+ * When a walk wraps around, the log repeats. Returns how much of the log is the first full pass, or 0 if it hasn't repeated yet.
+ * The first pass can start with a stray phrase (a container announced twice), so the repeating part may begin a step or two in.
+ * A pass counts only after it has run a full time and started again, so a long document isn't cut short.
+ * @param {string[]} log
+ */
+export function repeatLength(log) {
+  for (let offset = 0; offset <= 2; offset += 1) {
+    for (let period = 1; offset + period * 2 + 1 <= log.length; period += 1) {
+      let same = true;
+      for (let i = offset; i + period < log.length; i += 1) {
+        if (log[i] !== log[i + period]) {
+          same = false;
+          break;
+        }
+      }
+      if (same) return offset + period;
+    }
+  }
+  return 0;
+}
+
+/** What the tier reports when it can't run. */
+export const failedVsr = (error) => ({ status: /** @type {const} */ ("failed"), simulated: true, reason: (error instanceof Error ? error.message : String(error)).split("\n")[0] });