a11y-loop 0.1.0

package/src/commands/audit.js

@@ -0,0 +1,125 @@
+/**
+ * `a11y-loop audit` — run the browser audit and emit the report.
+ *
+ * Exit codes: 0 no violations · 1 violations found · 2 tool error.
+ */
+
+import { writeFile, readFile } from 'node:fs/promises';
+import { resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { runAudit, ToolError, DEFAULT_VIEWPORT } from '../lib/axe-runner.js';
+import { axeCoreVersion } from '../lib/wcag-map.js';
+import { buildReport, serializeReport } from '../lib/format/json.js';
+import { formatHuman } from '../lib/format/human.js';
+import { serializeSarif } from '../lib/format/sarif.js';
+import { buildChecklist } from '../lib/format/checklist.js';
+
+export const TOOL_NAME = 'a11y-loop';
+
+/** Read our own version rather than hardcoding it in two places. */
+async function toolVersion() {
+  try {
+    const pkgUrl = new URL('../../package.json', import.meta.url);
+    return JSON.parse(await readFile(pkgUrl, 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Load an --interact module: `export const states = { name: async (page) => {} }`.
+ * @param {string} path
+ */
+export async function loadStates(path) {
+  const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  let module;
+  try {
+    module = await import(pathToFileURL(absolute).href);
+  } catch (error) {
+    throw new ToolError(`Could not load --interact module ${absolute}: ${error.message}`, {
+      hint:
+        'The module must be ESM (.mjs, or .js in a "type":"module" package) and export:\n\n' +
+        '  export const states = {\n' +
+        '    "modal-open": async (page) => { await page.click("#open-dialog"); },\n' +
+        '  };',
+    });
+  }
+  const states = module.states ?? module.default?.states ?? module.default;
+  if (!states || typeof states !== 'object') {
+    throw new ToolError(`--interact module ${absolute} does not export "states".`, {
+      hint: 'Expected: export const states = { "state-name": async (page) => { … } };',
+    });
+  }
+  for (const [name, fn] of Object.entries(states)) {
+    if (typeof fn !== 'function') {
+      throw new ToolError(`--interact state "${name}" is not a function.`);
+    }
+  }
+  return states;
+}
+
+/**
+ * @param {object} input
+ * @param {{type:'url'|'file'|'html', value:string}} input.target
+ * @param {object} input.flags parsed CLI flags
+ * @param {{write:(s:string)=>void, writeError:(s:string)=>void}} io
+ * @returns {Promise<number>} process exit code
+ */
+export async function runAuditCommand({ target, flags }, io) {
+  const states = flags.interact ? await loadStates(flags.interact) : {};
+
+  const result = await runAudit({
+    target,
+    options: {
+      headed: Boolean(flags.headed),
+      bestPractice: flags.bestPractice !== false,
+      states,
+    },
+  });
+
+  const manualChecklist = buildChecklist({
+    facts: result.facts,
+    incompleteRuleIds: result.incompleteRuleIds,
+    statesRun: result.statesRun,
+  });
+
+  const report = buildReport({
+    tool: {
+      name: TOOL_NAME,
+      version: await toolVersion(),
+      axeCoreVersion: axeCoreVersion(),
+      browser: 'Chromium',
+      browserVersion: result.browserVersion,
+      userAgent: result.userAgent,
+      viewport: DEFAULT_VIEWPORT,
+      timestamp: new Date().toISOString(),
+      passesRun: result.passesRun,
+      statesRun: result.statesRun,
+    },
+    target: { ...target, servedAt: result.url },
+    findings: result.findings,
+    manualChecklist,
+    facts: result.facts,
+  });
+
+  const json = serializeReport(report);
+
+  if (flags.out) await writeFile(resolve(flags.out), json, 'utf8');
+  if (flags.sarif) await writeFile(resolve(flags.sarif), serializeSarif(report), 'utf8');
+
+  if (flags.json) {
+    io.write(json);
+  } else {
+    io.write(formatHuman(report, { quiet: Boolean(flags.quiet) }));
+  }
+
+  if (flags.out && !flags.json && !flags.quiet) {
+    io.writeError(`JSON report written to ${resolve(flags.out)}\n`);
+  }
+  if (flags.sarif && !flags.json && !flags.quiet) {
+    io.writeError(`SARIF written to ${resolve(flags.sarif)}\n`);
+  }
+
+  return report.summary.violations > 0 ? 1 : 0;
+}

package/src/commands/contrast.js

@@ -0,0 +1,141 @@
+/**
+ * `a11y-loop contrast <fg> <bg>` — WCAG 2.x contrast check, with fixes.
+ *
+ * Exit codes: 0 the pair meets the requested threshold · 1 it does not ·
+ * 2 the colours could not be parsed.
+ */
+
+import { checkContrast, ColorParseError, THRESHOLDS } from '../lib/contrast-math.js';
+import { suggestColors } from '../lib/suggest-color.js';
+import { ToolError } from '../lib/axe-runner.js';
+
+/** Build the machine-readable result, shared by --json and the human output. */
+export function contrastResult(fg, bg, { large = false, ui = false, fix = false } = {}) {
+  const check = checkContrast(fg, bg, { large, ui });
+  const required = check.thresholds.AA;
+
+  const result = {
+    foreground: { input: fg, hex: check.fg.hex, alpha: check.fg.alpha },
+    background: { input: bg, hex: check.bg.hex, alpha: check.bg.alpha },
+    ratio: check.ratioTruncated,
+    ratioDisplay: check.ratioDisplay,
+    context: check.context,
+    wcag: {
+      sc: check.sc.AA,
+      name: ui ? 'Non-text Contrast' : 'Contrast (Minimum)',
+      level: 'AA',
+      required,
+    },
+    thresholds: {
+      normalText: THRESHOLDS.normal,
+      largeText: THRESHOLDS.large,
+      nonText: THRESHOLDS.nonText,
+    },
+    passes: check.passes,
+  };
+
+  if (check.fg.alpha < 1 || check.bg.alpha < 1) {
+    result.composited = { foreground: check.fg.composited, background: check.bg.composited };
+  }
+
+  if (fix) {
+    result.fix = suggestColors(check.fg.composited, check.bg.composited, { target: required });
+  }
+
+  return result;
+}
+
+function contextLabel(result) {
+  if (result.context === 'non-text') return 'non-text / UI component';
+  return result.context === 'large' ? 'large-scale text (≥24px, or ≥18.5px bold)' : 'normal text';
+}
+
+export function formatContrastHuman(result) {
+  const lines = [];
+  const verdictFor = (level, threshold) => {
+    const passes = result.passes[level];
+    return `${passes ? 'PASS' : 'FAIL'} ${level} (${threshold}:1)`;
+  };
+
+  lines.push(`${result.foreground.hex} on ${result.background.hex} — ${result.ratioDisplay}:1`);
+  if (result.composited) {
+    lines.push(
+      `  composited for alpha: ${result.composited.foreground} on ${result.composited.background}`,
+    );
+  }
+  lines.push(`  measured as: ${contextLabel(result)}`);
+
+  const levels = Object.keys(result.passes);
+  const thresholdFor = (level) =>
+    result.context === 'non-text'
+      ? result.thresholds.nonText[level]
+      : result.context === 'large'
+        ? result.thresholds.largeText[level]
+        : result.thresholds.normalText[level];
+  lines.push(`  ${levels.map((level) => verdictFor(level, thresholdFor(level))).join('  ·  ')}`);
+  lines.push(
+    `  SC ${result.wcag.sc} ${result.wcag.name} (Level ${result.wcag.level}) requires ${result.wcag.required}:1`,
+  );
+
+  if (result.fix) {
+    lines.push('');
+    if (result.fix.suggestions.length === 0) {
+      lines.push(
+        result.fix.original.passes
+          ? '  Already meets the threshold — nothing to fix.'
+          : `  No candidate reached ${result.fix.target}:1 by adjusting lightness alone. ` +
+            'Change hue or chroma, or pick a different pair.',
+      );
+    } else {
+      lines.push(`  Candidates that reach ${result.fix.target}:1 (hue and chroma preserved):`);
+      for (const s of result.fix.suggestions) {
+        const what = s.role === 'background' ? 'background' : 'text';
+        const from = s.role === 'background' ? result.fix.original.bg : result.fix.original.fg;
+        lines.push(
+          `    ${what} ${s.direction}: ${from} → ${s.hex}  ` +
+            `(${result.fix.original.ratioDisplay}:1 → ${s.newRatioDisplay}:1)` +
+            (s.note ? `  — ${s.note}` : ''),
+        );
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('Contrast is measured with the WCAG 2.x algorithm; the ratio is truncated to two');
+  lines.push('decimals, matching axe-core and the WebAIM Contrast Checker.');
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * @param {{fg:string, bg:string, flags:object}} input
+ * @param {{write:Function, writeError:Function}} io
+ * @returns {Promise<number>}
+ */
+export async function runContrastCommand({ fg, bg, flags }, io) {
+  let result;
+  try {
+    result = contrastResult(fg, bg, {
+      large: Boolean(flags.large),
+      ui: Boolean(flags.ui),
+      fix: Boolean(flags.fix),
+    });
+  } catch (error) {
+    if (error instanceof ColorParseError) {
+      throw new ToolError(error.message, {
+        hint:
+          'Accepted formats: #rgb, #rrggbb, #rrggbbaa, rgb()/rgba(), hsl()/hsla(), oklch(), ' +
+          'and CSS named colours.',
+      });
+    }
+    throw error;
+  }
+
+  if (flags.json) {
+    io.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    io.write(formatContrastHuman(result));
+  }
+
+  return result.passes.AA ? 0 : 1;
+}

package/src/commands/diff.js

@@ -0,0 +1,65 @@
+/**
+ * `a11y-loop diff --before a.json --after b.json`
+ *
+ * Exit codes: 0 no new violations · 1 regression (NEW is non-empty) ·
+ * 2 a report could not be read.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { diffReports, formatDiffHuman } from '../lib/diff.js';
+import { ToolError } from '../lib/axe-runner.js';
+
+async function readReport(path, label) {
+  const absolute = resolve(path);
+  let text;
+  try {
+    text = await readFile(absolute, 'utf8');
+  } catch (error) {
+    throw new ToolError(`Could not read --${label} report ${absolute}: ${error.message}`, {
+      hint: 'Produce reports with: a11y-loop audit <target> --out report.json',
+    });
+  }
+  let report;
+  try {
+    report = JSON.parse(text);
+  } catch (error) {
+    throw new ToolError(`--${label} report ${absolute} is not valid JSON: ${error.message}`);
+  }
+  if (!report?.findings?.violations) {
+    throw new ToolError(
+      `--${label} report ${absolute} is not an a11y-loop report (no findings.violations array).`,
+      { hint: 'Produce reports with: a11y-loop audit <target> --out report.json' },
+    );
+  }
+  return report;
+}
+
+/**
+ * @param {{flags:object}} input
+ * @param {{write:Function, writeError:Function}} io
+ * @returns {Promise<number>}
+ */
+export async function runDiffCommand({ flags }, io) {
+  if (!flags.before || !flags.after) {
+    throw new ToolError('diff requires both --before <a.json> and --after <b.json>.');
+  }
+
+  const before = await readReport(flags.before, 'before');
+  const after = await readReport(flags.after, 'after');
+  const diff = diffReports(before, after);
+
+  if (flags.json) {
+    io.write(`${JSON.stringify(diff, null, 2)}\n`);
+  } else {
+    io.write(
+      formatDiffHuman(diff, {
+        beforePath: resolve(flags.before),
+        afterPath: resolve(flags.after),
+      }),
+    );
+  }
+
+  return diff.summary.regression ? 1 : 0;
+}