a11y-loop 0.1.0

package/src/lib/format/json.js

@@ -0,0 +1,139 @@
+/**
+ * The JSON report — the primary machine format and the agent-facing contract.
+ *
+ * Design rules:
+ *  - Stable keys, so a loop can rely on them across versions.
+ *  - `violations` / `needsReview` / `bestPractice` are separate arrays.
+ *    best-practice rules have no success criterion behind them and are NEVER
+ *    counted as violations or allowed to affect the exit code.
+ *  - Every finding carries a fingerprint, so `diff` can match across runs.
+ *  - The summary states what was NOT checked as prominently as what was.
+ *  - No conformance language, ever. See RED_LINE_PATTERNS.
+ */
+
+import { bucketFindings } from '../finding.js';
+import { compareSc, CONFORMANCE_SET } from '../wcag-map.js';
+
+/** The clean-run sentence. Deliberately not "passed", "compliant" or "accessible". */
+export const CLEAN_VERDICT = 'No automatically detectable failures';
+
+/** Coverage, with denominators attached. Quoting 57% alone overstates the case. */
+export const COVERAGE = Object.freeze({
+  statement:
+    'Automated checks cover a subset of WCAG (Deque: ~57% of issues by volume; ~31% of AA ' +
+    'criteria have any automated rule). This is not an audit or conformance claim.',
+  issueVolumePercent: 57,
+  issueVolumeDenominator: 'instances of individual issues found, per Deque’s 2,000-audit study',
+  criteriaWithAnyAutomatedRulePercent: 31,
+  criteriaWithAnyAutomatedRuleDenominator: `17 of the ${CONFORMANCE_SET.aaSet} WCAG 2.2 A/AA criteria`,
+  criteriaReliablyAutomatedPercent: 13,
+  criteriaReliablyAutomatedDenominator: `7 of the ${CONFORMANCE_SET.aaSet} WCAG 2.2 A/AA criteria`,
+  criteriaUntestableByAnyTool: 9,
+  criteriaRequiringHumanVerification: 13,
+});
+
+/**
+ * Phrases that must never appear in a11y-loop's own report language. The FTC
+ * fined accessiBe $1M over claims of this kind; the Overlay Fact Sheet has 800+
+ * signatories. A tool that overstates coverage makes agents declare victory
+ * early, which is the exact failure this one exists to prevent.
+ */
+export const RED_LINE_PATTERNS = [
+  /\bcompliant\b/i,
+  /\bcompliance\s+(?:guaranteed|achieved|confirmed)\b/i,
+  /\bconforms?\s+to\s+WCAG\b/i,
+  /\bfully\s+accessible\b/i,
+  /\bis\s+accessible\b/i,
+  /\bpasse[sd]\s+WCAG\b/i,
+  /\bguarantee\w*\b/i,
+  /\bno\s+manual\s+testing\b/i,
+  /\breduces?\s+legal\s+risk\b/i,
+  /\baccessibility\s+score\b/i,
+  /\b100%\s+accessible\b/i,
+];
+
+/** @returns {string[]} the red-line phrases present in a block of text. */
+export function findRedLineLanguage(text) {
+  return RED_LINE_PATTERNS.filter((pattern) => pattern.test(String(text ?? ''))).map(
+    (pattern) => pattern.source,
+  );
+}
+
+const IMPACTS = ['critical', 'serious', 'moderate', 'minor'];
+
+function countByImpact(findings) {
+  const counts = {};
+  for (const impact of IMPACTS) {
+    const n = findings.filter((f) => f.impact === impact).length;
+    if (n > 0) counts[impact] = n;
+  }
+  return counts;
+}
+
+/** Distinct success criteria touched by a set of findings, in criterion order. */
+export function affectedCriteria(findings) {
+  const map = new Map();
+  for (const finding of findings) {
+    if (!finding.wcag?.sc) continue;
+    if (!map.has(finding.wcag.sc)) {
+      map.set(finding.wcag.sc, {
+        sc: finding.wcag.sc,
+        name: finding.wcag.name,
+        level: finding.wcag.level,
+        wcag22Only: finding.wcag.wcag22Only,
+        count: 0,
+      });
+    }
+    map.get(finding.wcag.sc).count += 1;
+  }
+  return [...map.values()].sort((a, b) => compareSc(a.sc, b.sc));
+}
+
+/**
+ * Assemble the report.
+ *
+ * @param {object} input
+ * @param {object} input.tool provenance: name, version, axeCoreVersion, browser, …
+ * @param {{type:string, value:string}} input.target
+ * @param {Array} input.findings deduped, flat
+ * @param {Array} input.manualChecklist
+ * @param {object} [input.facts]
+ */
+export function buildReport({ tool, target, findings, manualChecklist = [], facts = {} }) {
+  const buckets = bucketFindings(findings);
+  const violationCount = buckets.violations.length;
+
+  const summary = {
+    violations: violationCount,
+    needsReview: buckets.needsReview.length,
+    bestPractice: buckets.bestPractice.length,
+    manualChecklist: manualChecklist.length,
+    byImpact: countByImpact(buckets.violations),
+    criteriaAffected: affectedCriteria(buckets.violations),
+    wcag22OnlyViolations: buckets.violations.filter((f) => f.wcag?.wcag22Only).length,
+    verdict:
+      violationCount === 0
+        ? CLEAN_VERDICT
+        : `${violationCount} automatically detectable failure${violationCount === 1 ? '' : 's'}`,
+    target: 'WCAG 2.2 Level AA',
+    coverage: COVERAGE,
+  };
+
+  return {
+    tool,
+    target,
+    summary,
+    findings: {
+      violations: buckets.violations,
+      needsReview: buckets.needsReview,
+      bestPractice: buckets.bestPractice,
+    },
+    manualChecklist,
+    pageInventory: facts,
+  };
+}
+
+/** Pretty-printed JSON with a trailing newline, for stdout or a file. */
+export function serializeReport(report) {
+  return `${JSON.stringify(report, null, 2)}\n`;
+}

package/src/lib/format/sarif.js

@@ -0,0 +1,111 @@
+/**
+ * SARIF v2.1 output, via Microsoft's axe-sarif-converter.
+ *
+ * Supported with eyes open. GitHub code scanning only DISPLAYS results whose
+ * location is a file path with a valid `physicalLocation.artifactLocation.uri`;
+ * an accessibility finding's natural location is (page URL, CSS selector), so a
+ * naive upload produces an empty Code Scanning view. The honest approach, taken
+ * here, is to emit valid SARIF for Azure DevOps and the VS Code SARIF viewer and
+ * to document the GitHub limitation rather than fake file paths.
+ *
+ * Plain JSON remains the primary machine format: SARIF is verbose and hostile to
+ * an LLM's context budget.
+ */
+
+import { createRequire } from 'node:module';
+import { SEVERITY } from '../finding.js';
+
+const require = createRequire(import.meta.url);
+
+/** Where GitHub's limitation is documented for report readers. */
+export const GITHUB_LIMITATION_NOTE =
+  'GitHub code scanning drops SARIF results without a file-path location. These results are ' +
+  'located by URL and CSS selector, so use the Azure DevOps SARIF viewer or the VS Code SARIF ' +
+  'extension, or map selectors back to source templates before uploading.';
+
+/**
+ * Rebuild an axe-shaped results object from our report so the converter can
+ * consume it. Our own a11y-loop checks are included as additional rules — they
+ * are real findings and dropping them from the SARIF would misrepresent the run.
+ *
+ * @param {object} report
+ * @returns {object} an axe-core AxeResults-shaped object
+ */
+export function toAxeShape(report) {
+  const nodeFor = (finding) => ({
+    html: finding.html,
+    target: [finding.selector],
+    any: [],
+    all: [],
+    none: [],
+    impact: finding.impact ?? null,
+    failureSummary: finding.message,
+  });
+
+  const groupByRule = (findings) => {
+    const groups = new Map();
+    for (const finding of findings) {
+      if (!groups.has(finding.ruleId)) {
+        const tags = [];
+        if (finding.wcag?.sc) {
+          tags.push(`wcag${finding.wcag.sc.replace(/\./g, '')}`);
+          if (finding.wcag.level) {
+            const version = finding.wcag.minVersion === '2.0' ? '2' : finding.wcag.minVersion.replace('.', '');
+            tags.push(`wcag${version}${finding.wcag.level.toLowerCase()}`);
+          }
+        }
+        if (finding.severity === SEVERITY.BEST_PRACTICE) tags.push('best-practice');
+        for (const act of finding.act ?? []) tags.push(`ACT-${act}`);
+
+        groups.set(finding.ruleId, {
+          id: finding.ruleId,
+          impact: finding.impact ?? null,
+          tags,
+          description: finding.message,
+          help: finding.message,
+          helpUrl: finding.helpUrl ?? 'https://github.com/chanmeng/a11y-loop',
+          nodes: [],
+        });
+      }
+      groups.get(finding.ruleId).nodes.push(nodeFor(finding));
+    }
+    return [...groups.values()];
+  };
+
+  return {
+    testEngine: { name: 'axe-core', version: report.tool.axeCoreVersion },
+    testRunner: { name: `${report.tool.name} ${report.tool.version}` },
+    testEnvironment: {
+      userAgent: report.tool.userAgent ?? `${report.tool.browser}/${report.tool.browserVersion}`,
+      windowWidth: report.tool.viewport.width,
+      windowHeight: report.tool.viewport.height,
+      orientationAngle: 0,
+      orientationType: 'landscape-primary',
+    },
+    toolOptions: { passes: report.tool.passesRun, states: report.tool.statesRun ?? [] },
+    timestamp: report.tool.timestamp,
+    url: report.target.value,
+    violations: groupByRule([...report.findings.violations, ...report.findings.bestPractice]),
+    incomplete: groupByRule(report.findings.needsReview),
+    passes: [],
+    inapplicable: [],
+  };
+}
+
+/**
+ * @param {object} report
+ * @returns {object} a SARIF v2.1 log
+ */
+export function toSarif(report) {
+  const { convertAxeToSarif } = require('axe-sarif-converter');
+  const log = convertAxeToSarif(toAxeShape(report));
+  for (const run of log.runs ?? []) {
+    run.properties = { ...run.properties, a11yLoopNote: GITHUB_LIMITATION_NOTE };
+  }
+  return log;
+}
+
+/** Serialized SARIF, with a trailing newline. */
+export function serializeSarif(report) {
+  return `${JSON.stringify(toSarif(report), null, 2)}\n`;
+}

package/src/lib/serve.js

@@ -0,0 +1,189 @@
+/**
+ * Ephemeral static server on 127.0.0.1.
+ *
+ * `file://` is deliberately not supported: its null origin breaks axe's frame
+ * injection (axe-core #3002), ES modules and `fetch`, and Windows path→URL
+ * conversion is its own bug source. Serving over HTTP costs ~20 lines and no
+ * dependencies, and behaves like the real thing.
+ */
+
+import { createServer } from 'node:http';
+import { createReadStream } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, resolve, join, sep } from 'node:path';
+
+const CONTENT_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+const contentTypeFor = (path) => CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+
+/**
+ * Wrap an HTML fragment in a minimal valid document.
+ *
+ * `lang` and `<title>` are supplied so that auditing a fragment does not
+ * report the wrapper's own missing-lang and missing-title failures as if they
+ * were the agent's. A fragment that already looks like a full document is
+ * passed through untouched, so `--html` can also take a whole page.
+ */
+export function wrapFragment(fragment) {
+  const text = String(fragment ?? '');
+  if (/<html[\s>]/i.test(text) || /^\s*<!doctype/i.test(text)) {
+    return /^\s*<!doctype/i.test(text) ? text : `<!doctype html>\n${text}`;
+  }
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<title>a11y-loop fragment audit</title>',
+    '</head>',
+    '<body>',
+    text,
+    '</body>',
+    '</html>',
+  ].join('\n');
+}
+
+/**
+ * Serve a single in-memory HTML document.
+ * @param {string} html
+ * @returns {Promise<{url:string, close:() => Promise<void>}>}
+ */
+export async function serveHtml(html) {
+  const body = Buffer.from(html, 'utf8');
+  const server = createServer((req, res) => {
+    if (req.url === '/' || req.url === '/index.html') {
+      res.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8',
+        'content-length': body.length,
+      });
+      res.end(body);
+      return;
+    }
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('Not found');
+  });
+  const port = await listen(server);
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    close: () => closeServer(server),
+  };
+}
+
+/**
+ * Serve a file's own directory as the document root, so relative stylesheets,
+ * scripts and images resolve the way they would in a dev server.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{url:string, close:() => Promise<void>}>}
+ */
+export async function serveFile(filePath) {
+  const absolute = resolve(filePath);
+  const info = await stat(absolute).catch(() => null);
+  if (!info) throw new Error(`File not found: ${absolute}`);
+  if (info.isDirectory()) return serveDirectory(absolute, 'index.html');
+
+  const root = absolute.slice(0, absolute.lastIndexOf(sep));
+  const entry = absolute.slice(absolute.lastIndexOf(sep) + 1);
+  return serveDirectory(root, entry);
+}
+
+/**
+ * @param {string} root
+ * @param {string} entry file within `root` served at `/`
+ */
+export async function serveDirectory(root, entry = 'index.html') {
+  const server = createServer(async (req, res) => {
+    try {
+      const requested = decodeURIComponent((req.url ?? '/').split('?')[0]);
+      const relative = requested === '/' ? entry : requested.replace(/^\/+/, '');
+      const target = resolve(join(root, relative));
+
+      // Never serve outside the document root.
+      if (target !== resolve(root) && !target.startsWith(resolve(root) + sep)) {
+        res.writeHead(403, { 'content-type': 'text/plain' });
+        res.end('Forbidden');
+        return;
+      }
+
+      const info = await stat(target).catch(() => null);
+      if (!info || info.isDirectory()) {
+        res.writeHead(404, { 'content-type': 'text/plain' });
+        res.end('Not found');
+        return;
+      }
+
+      res.writeHead(200, { 'content-type': contentTypeFor(target), 'content-length': info.size });
+      createReadStream(target).pipe(res);
+    } catch {
+      res.writeHead(500, { 'content-type': 'text/plain' });
+      res.end('Server error');
+    }
+  });
+  const port = await listen(server);
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    close: () => closeServer(server),
+  };
+}
+
+/**
+ * Resolve the target of an audit into a URL plus a teardown function.
+ *
+ * @param {{type:'url'|'file'|'html', value:string}} target
+ * @returns {Promise<{url:string, close:() => Promise<void>}>}
+ */
+export async function resolveTarget(target) {
+  if (target.type === 'url') {
+    return { url: target.value, close: async () => {} };
+  }
+  if (target.type === 'file') {
+    return serveFile(target.value);
+  }
+  if (target.type === 'html') {
+    return serveHtml(wrapFragment(target.value));
+  }
+  throw new Error(`Unknown target type: ${target.type}`);
+}
+
+/** Read a fragment or document from disk, for `--html @file` style use. */
+export async function readHtmlFile(path) {
+  return readFile(resolve(path), 'utf8');
+}
+
+/** Listen on an OS-assigned port and resolve with it. */
+function listen(server) {
+  return new Promise((resolvePort, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      resolvePort(typeof address === 'object' && address ? address.port : 0);
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((done) => {
+    server.closeAllConnections?.();
+    server.close(() => done());
+  });
+}

package/src/lib/suggest-color.js

@@ -0,0 +1,169 @@
+/**
+ * "Nearest accessible color" suggester.
+ *
+ * No well-maintained library does this properly, so it is implemented here in
+ * ~100 lines. The search runs on OKLCh **lightness** with hue and chroma held
+ * fixed, which keeps suggestions recognisably part of the designer's palette —
+ * an HSL search desaturates and hue-shifts badly.
+ *
+ * Both a LIGHTER and a DARKER candidate are returned for the foreground, plus
+ * one background option. A loop that silently picks one direction will destroy
+ * a brand palette, so the caller (agent or human) chooses.
+ *
+ * culori is used only for color-space conversion; all contrast math is ours.
+ */
+
+import { converter, clampChroma, formatHex } from 'culori';
+import { parseColor, contrastRatio, formatRatio, truncateRatio } from './contrast-math.js';
+
+const toOklch = converter('oklch');
+
+/** Coarse scan resolution when bracketing the first lightness that passes. */
+const SCAN_STEPS = 120;
+/** Bisection refinement steps once a bracket is found. */
+const REFINE_STEPS = 24;
+
+/** @returns {string} hex for an OKLCh color at lightness `l`, gamut-mapped to sRGB. */
+function hexAtLightness(base, l) {
+  const clamped = clampChroma({ ...base, l: Math.min(1, Math.max(0, l)) }, 'oklch', 'rgb');
+  return formatHex(clamped);
+}
+
+/**
+ * Walk lightness away from `base` in one direction until the contrast against
+ * `other` reaches `target`, then bisect back toward the original color to find
+ * the smallest change that still passes.
+ *
+ * Contrast is not monotonic in lightness across the whole range (it dips to 1:1
+ * where the two colors meet), which is why this brackets with a coarse scan
+ * first instead of bisecting blindly.
+ *
+ * @returns {{hex:string, l:number, ratio:number}|null} null if unreachable
+ */
+function searchLightness(base, other, target, direction) {
+  const startL = base.l;
+  const endL = direction === 'lighter' ? 1 : 0;
+  const span = endL - startL;
+  if (Math.abs(span) < 1e-6) return null;
+
+  const ratioAt = (l) => {
+    const hex = hexAtLightness(base, l);
+    return { hex, ratio: contrastRatio(parseColor(hex), other) };
+  };
+
+  // Coarse scan for the first sample that meets the target.
+  let bracketLo = startL; // known-failing end (closest to the original)
+  let hit = null;
+  for (let i = 1; i <= SCAN_STEPS; i++) {
+    const l = startL + (span * i) / SCAN_STEPS;
+    const probe = ratioAt(l);
+    if (probe.ratio >= target) {
+      hit = { l, ...probe };
+      break;
+    }
+    bracketLo = l;
+  }
+  if (!hit) return null;
+
+  // Bisect between the last failing sample and the first passing one.
+  let lo = bracketLo;
+  let hi = hit.l;
+  let best = hit;
+  for (let i = 0; i < REFINE_STEPS; i++) {
+    const mid = (lo + hi) / 2;
+    const probe = ratioAt(mid);
+    if (probe.ratio >= target) {
+      best = { l: mid, ...probe };
+      hi = mid;
+    } else {
+      lo = mid;
+    }
+  }
+  return best;
+}
+
+/**
+ * Suggest passing alternatives for a failing foreground/background pair.
+ *
+ * @param {string} fgInput  CSS color
+ * @param {string} bgInput  CSS color
+ * @param {{target?:number, includeBackground?:boolean}} [opts]
+ *   `target` is the required ratio (4.5 normal text, 3 large text / non-text).
+ * @returns {{
+ *   target:number,
+ *   original:{fg:string, bg:string, ratio:number, ratioDisplay:string, passes:boolean},
+ *   suggestions:Array<{role:'foreground'|'background', direction:'lighter'|'darker',
+ *                      hex:string, newRatio:number, newRatioDisplay:string, note?:string}>
+ * }}
+ */
+export function suggestColors(fgInput, bgInput, opts = {}) {
+  const { target = 4.5, includeBackground = true } = opts;
+  const fg = parseColor(fgInput);
+  const bg = parseColor(bgInput);
+  const original = contrastRatio(fg, bg);
+
+  const fgOk = toOklch({ mode: 'rgb', r: fg.r / 255, g: fg.g / 255, b: fg.b / 255 });
+  const bgOk = toOklch({ mode: 'rgb', r: bg.r / 255, g: bg.g / 255, b: bg.b / 255 });
+  // Hue is undefined for achromatic colors; keep it at 0 so clampChroma is happy.
+  if (!Number.isFinite(fgOk.h)) fgOk.h = 0;
+  if (!Number.isFinite(bgOk.h)) bgOk.h = 0;
+
+  const suggestions = [];
+
+  for (const direction of ['lighter', 'darker']) {
+    const found = searchLightness(fgOk, bg, target, direction);
+    if (found && found.hex !== fg.hex) {
+      suggestions.push({
+        role: 'foreground',
+        direction,
+        hex: found.hex,
+        newRatio: truncateRatio(found.ratio),
+        newRatioDisplay: formatRatio(found.ratio),
+      });
+    }
+  }
+
+  if (includeBackground) {
+    // Move the background away from the foreground: if the text is dark, the
+    // surface should get lighter, and vice versa.
+    const direction = fgOk.l <= bgOk.l ? 'lighter' : 'darker';
+    const found = searchLightness(bgOk, fg, target, direction);
+    if (found && found.hex !== bg.hex) {
+      suggestions.push({
+        role: 'background',
+        direction,
+        hex: found.hex,
+        newRatio: truncateRatio(found.ratio),
+        newRatioDisplay: formatRatio(found.ratio),
+        note: 'changes the surface, which affects every element drawn on it',
+      });
+    }
+  }
+
+  return {
+    target,
+    original: {
+      fg: fg.hex,
+      bg: bg.hex,
+      ratio: truncateRatio(original),
+      ratioDisplay: formatRatio(original),
+      passes: original >= target,
+    },
+    suggestions,
+  };
+}
+
+/**
+ * One-line rendering of a suggestion set, for human output.
+ * e.g. `#777777 → #595959 (4.47 → 7.00) or lighten background #ffffff → …`
+ */
+export function formatSuggestions(result) {
+  if (result.suggestions.length === 0) return null;
+  return result.suggestions
+    .map((s) => {
+      const what = s.role === 'foreground' ? 'text' : 'background';
+      const from = s.role === 'foreground' ? result.original.fg : result.original.bg;
+      return `${what} ${s.direction}: ${from} → ${s.hex} (${result.original.ratioDisplay} → ${s.newRatioDisplay})`;
+    })
+    .join('; ');
+}