a11y-loop 0.1.0

package/src/lib/finding.js

@@ -0,0 +1,164 @@
+/**
+ * The finding record — the unit of everything downstream (dedupe, diff, JSON,
+ * human output, SARIF).
+ *
+ * Three severities, and the split matters:
+ *  - `violation`   — a success criterion is failed. Blocking; exit code 1.
+ *  - `needsReview` — axe `incomplete`, or one of our own checks that found
+ *                    something real but cannot judge it. Never merged into
+ *                    passes, never blocking.
+ *  - `bestPractice`— an axe best-practice rule with no criterion behind it.
+ *                    Never blocking, never counted as a violation.
+ */
+
+import { fingerprint } from './fingerprint.js';
+import { wcagFromTags, wcagForSc, actIdsForRule } from './wcag-map.js';
+
+export const SEVERITY = {
+  VIOLATION: 'violation',
+  NEEDS_REVIEW: 'needsReview',
+  BEST_PRACTICE: 'bestPractice',
+};
+
+export const HTML_TRUNCATE_AT = 200;
+
+/** Collapse whitespace and cap length, so reports stay readable and small. */
+export function truncateHtml(html, limit = HTML_TRUNCATE_AT) {
+  if (typeof html !== 'string') return '';
+  const flat = html.replace(/\s+/g, ' ').trim();
+  return flat.length <= limit ? flat : `${flat.slice(0, limit)}…`;
+}
+
+/**
+ * @param {object} spec
+ * @param {string} spec.ruleId
+ * @param {'axe'|'a11y-loop'} spec.source
+ * @param {string} spec.severity  one of SEVERITY
+ * @param {string} [spec.impact]  minor | moderate | serious | critical
+ * @param {string} [spec.sc]      success criterion number, for own checks
+ * @param {string[]} [spec.tags]  axe tags, for axe findings
+ * @param {string[]} [spec.act]   ACT rule ids (looked up from axe when omitted)
+ * @param {string|Array} spec.selector
+ * @param {string} [spec.html]
+ * @param {string} spec.message
+ * @param {string} [spec.helpUrl]
+ * @param {Array} [spec.suggestions]
+ * @param {string[]} [spec.passes] which emulation passes it appeared in
+ * @param {string|null} [spec.state] interaction state name, if any
+ * @param {object} [spec.data] extra check-specific detail
+ */
+export function makeFinding(spec) {
+  const {
+    ruleId,
+    source,
+    severity,
+    impact = null,
+    sc = null,
+    tags = [],
+    act,
+    selector,
+    html = '',
+    message,
+    helpUrl = null,
+    suggestions,
+    passes = [],
+    state = null,
+    data,
+  } = spec;
+
+  const wcag = sc ? wcagForSc(sc) : wcagFromTags(tags);
+
+  const finding = {
+    fingerprint: fingerprint({ ruleId, selector, html }),
+    ruleId,
+    source,
+    severity,
+    impact,
+    wcag: wcag ?? null,
+    act: act ?? (source === 'axe' ? actIdsForRule(ruleId) : []),
+    passes: [...passes],
+    state,
+    selector: Array.isArray(selector) ? selector.flat(Infinity).join(', ') : String(selector ?? ''),
+    html: truncateHtml(html),
+    message,
+    helpUrl,
+  };
+
+  if (suggestions?.length) finding.suggestions = suggestions;
+  if (data) finding.data = data;
+  return finding;
+}
+
+/**
+ * Merge findings that the five emulation passes reported more than once,
+ * recording every pass a finding appeared in. Same fingerprint + same state is
+ * the same finding.
+ *
+ * @param {Array} findings
+ * @returns {Array}
+ */
+/**
+ * Rules where a lone forced-colors-pass "violation" contradicting an
+ * already-established needs-review verdict from every other pass is not
+ * trusted. Verified directly (real repro, not assumed): under
+ * `forcedColors: 'active'`, a gradient background is correctly flattened by
+ * Chromium (backgroundImage becomes 'none', backgroundColor becomes the
+ * Canvas colour) but axe-core's color-contrast check evaluates the ORIGINAL,
+ * pre-forced-colors author foreground colour against that new background —
+ * not the actual rendered colour (confirmed by reading getComputedStyle
+ * directly: the real rendered text was black-on-white, 21:1, while axe
+ * reported the author's un-adjusted light colour and a 1.17:1 failure).
+ * Every other pass, and a plain default axe.run() with no emulation at all,
+ * correctly call the same element's background undeterminable. This is a
+ * gradient-plus-forced-colors-specific axe-core limitation, reproduced with
+ * a minimal two-line test page independent of any a11y-loop code, not
+ * something specific to one page or fixable by changing what gets served.
+ */
+const FORCED_COLORS_FRAGILE_RULES = new Set(['color-contrast', 'color-contrast-enhanced']);
+
+export function dedupeFindings(findings) {
+  const byKey = new Map();
+  for (const finding of findings) {
+    const key = `${finding.fingerprint}::${finding.state ?? ''}`;
+    const existing = byKey.get(key);
+    if (!existing) {
+      byKey.set(key, { ...finding, passes: [...finding.passes] });
+      continue;
+    }
+    for (const pass of finding.passes) {
+      if (!existing.passes.includes(pass)) existing.passes.push(pass);
+    }
+
+    const isUncorroboratedForcedColorsPromotion =
+      FORCED_COLORS_FRAGILE_RULES.has(finding.ruleId) &&
+      finding.severity === SEVERITY.VIOLATION &&
+      existing.severity === SEVERITY.NEEDS_REVIEW &&
+      finding.passes.length === 1 &&
+      finding.passes[0] === 'forced-colors';
+
+    // A violation seen in any pass outranks a needs-review sighting of the same
+    // thing, and richer data (suggestions) should survive the merge — except
+    // the specific, verified forced-colors/gradient case above, where trusting
+    // the lone dissenting pass would replace four correct "undeterminable"
+    // verdicts with a false failure.
+    if (
+      existing.severity !== SEVERITY.VIOLATION &&
+      finding.severity === SEVERITY.VIOLATION &&
+      !isUncorroboratedForcedColorsPromotion
+    ) {
+      existing.severity = SEVERITY.VIOLATION;
+      existing.message = finding.message;
+    }
+    if (!existing.suggestions && finding.suggestions) existing.suggestions = finding.suggestions;
+  }
+  return [...byKey.values()];
+}
+
+/** Split a flat finding list into the three report buckets. */
+export function bucketFindings(findings) {
+  return {
+    violations: findings.filter((f) => f.severity === SEVERITY.VIOLATION),
+    needsReview: findings.filter((f) => f.severity === SEVERITY.NEEDS_REVIEW),
+    bestPractice: findings.filter((f) => f.severity === SEVERITY.BEST_PRACTICE),
+  };
+}

package/src/lib/format/checklist.js

@@ -0,0 +1,281 @@
+/**
+ * The manual-verification checklist.
+ *
+ * This is a first-class output, not a disclaimer. Automated rules cover a
+ * minority of WCAG — 57% of issue instances by volume on Deque's own numbers,
+ * but only ~31% of the 55 AA criteria have any ACT-approved automated rule and
+ * ~13% are reliably flagged. Nine A/AA criteria cannot be meaningfully tested by
+ * any tool.
+ *
+ * Items are generated from what was actually on the page, so the list is short
+ * and specific rather than a generic wall of text. An empty page gets three
+ * items; a page with a form, images and a dialog gets the ones that apply.
+ */
+
+/** Always relevant, whatever the page contains. */
+const UNIVERSAL = [
+  {
+    id: 'assistive-technology',
+    sc: null,
+    text: 'Test with a real screen reader (NVDA or JAWS on Windows, VoiceOver on macOS/iOS).',
+    why:
+      'No automated tool, and no simulator, reproduces real AT behaviour — NVDA, JAWS and ' +
+      'VoiceOver diverge from each other and from the specification.',
+  },
+  {
+    id: 'focus-order-logic',
+    sc: '2.4.3',
+    text: 'Tab through the page and confirm the focus order is logical, not merely present.',
+    why:
+      'a11y-loop can see that focus moves and where it goes, but whether the sequence makes ' +
+      'sense for this content is a human judgment.',
+  },
+  {
+    id: 'keyboard-only-walkthrough',
+    sc: '2.1.1',
+    text: 'Complete the page’s main task using only the keyboard.',
+    why:
+      'Automated checks probe individual controls; they do not know what the user is trying ' +
+      'to accomplish.',
+  },
+];
+
+/**
+ * Conditional items, keyed by a fact on the page.
+ * `when` receives the page inventory and returns whether the item applies.
+ */
+const CONDITIONAL = [
+  {
+    id: 'alt-text-quality',
+    sc: '1.1.1',
+    when: (f) => f.images > 0,
+    text: (f) =>
+      `Confirm the alt text on ${f.images} image${f.images === 1 ? '' : 's'} is accurate and ` +
+      'useful, and that decorative images use alt="" rather than a description.',
+    why:
+      'Automation can only see whether alt text exists. alt="decorative image" passes every ' +
+      'automated rule and is worse than alt="". If any alt text was generated by an AI, treat ' +
+      'it as a draft that a human must confirm.',
+  },
+  {
+    id: 'form-error-quality',
+    sc: '3.3.3',
+    when: (f) => f.formFields > 0,
+    text: (f) =>
+      `Submit the form with ${f.formFields} field${f.formFields === 1 ? '' : 's'} in an invalid ` +
+      'state and confirm each error is announced, identifies the field, and says how to fix it.',
+    why:
+      'SC 3.3.1 and 3.3.3 are about whether an error message is actionable, which no tool can ' +
+      'assess. Error states also usually only exist after interaction — audit them with ' +
+      '--interact.',
+  },
+  {
+    id: 'label-clarity',
+    sc: '2.4.6',
+    when: (f) => f.formFields > 0,
+    text: 'Confirm every field label describes what to enter, not just that a label exists.',
+    why: 'A label of "Field 1" satisfies every automated rule and tells the user nothing.',
+  },
+  {
+    id: 'link-purpose',
+    sc: '2.4.4',
+    when: (f) => f.links > 0,
+    text: 'Read each link text out of context and confirm the destination is still clear.',
+    why:
+      'SC 2.4.4 permits vague link text when the surrounding context supplies the purpose — ' +
+      'whether it does is a judgment call.',
+  },
+  {
+    id: 'heading-semantics',
+    sc: '1.3.1',
+    when: (f) => f.headings > 0,
+    text: 'Confirm the heading structure describes the content hierarchy, not the visual sizes.',
+    why:
+      'Automation can detect skipped levels but not whether the outline reflects the actual ' +
+      'structure of the page.',
+  },
+  {
+    id: 'media-alternatives',
+    sc: '1.2.2',
+    when: (f) => f.videos > 0 || f.audios > 0,
+    text: 'Check caption accuracy, and provide a transcript and (for video) audio description.',
+    why:
+      'Caption and transcript quality is entirely a human assessment; the presence of a track ' +
+      'element says nothing about whether it is correct or synchronised.',
+  },
+  {
+    id: 'table-reflow-meaning',
+    sc: '1.4.10',
+    when: (f) => f.tables > 0,
+    text: 'Confirm the table still conveys its meaning at a 320px viewport.',
+    why:
+      'SC 1.4.10 excepts content requiring two-dimensional layout. Whether a given table ' +
+      'qualifies, and whether it remains understandable, needs a person.',
+  },
+  {
+    id: 'aria-appropriateness',
+    sc: '4.1.2',
+    when: (f) => f.ariaAttributes > 0,
+    text: (f) =>
+      `Review the ${f.ariaAttributes} ARIA attribute${f.ariaAttributes === 1 ? '' : 's'} on this ` +
+      'page: is each one appropriate, or merely valid?',
+    why:
+      'Pages using ARIA average more accessibility errors than pages without it (WebAIM ' +
+      'Million 2026: 59.1 vs 42.0). A role is a promise — role="button" commits to the full ' +
+      'keyboard behaviour of a button. No ARIA is better than bad ARIA.',
+  },
+  {
+    id: 'dialog-behaviour',
+    sc: '2.1.2',
+    when: (f) => f.dialogs > 0,
+    text: 'Confirm each dialog announces itself on open and describes how to dismiss it.',
+    why:
+      'a11y-loop tests the focus trap, Escape, and focus return mechanically. Whether the ' +
+      'dialog is comprehensible when announced is a screen-reader test.',
+  },
+  {
+    id: 'motion-essential',
+    sc: '2.3.3',
+    when: (f) => f.animations > 0,
+    text: 'Confirm any animation that survives prefers-reduced-motion is genuinely essential.',
+    why: 'The "essential" exception cannot be evaluated automatically.',
+  },
+  {
+    id: 'color-not-only-cue',
+    sc: '1.4.1',
+    when: (f) => f.links > 0 || f.formFields > 0,
+    text: 'Confirm colour is never the only way information is conveyed.',
+    why:
+      'SC 1.4.1 is one of the criteria no tool can test: recognising that "the required fields ' +
+      'are in red" needs comprehension of the content.',
+  },
+  {
+    id: 'focus-not-obscured',
+    sc: '2.4.11',
+    when: (f) => f.stickyElements > 0,
+    text: 'Tab through the page and confirm the focused element is never hidden behind sticky or fixed content.',
+    why:
+      'SC 2.4.11 (new in WCAG 2.2) has no automated rule. This page has position:sticky or ' +
+      'position:fixed elements, which are the usual cause.',
+  },
+];
+
+/**
+ * Engine limitations worth restating when the relevant rule actually turned up
+ * in axe's `incomplete` array — each one is a place axe knows it does not know.
+ */
+const ENGINE_NOTES = {
+  'color-contrast': {
+    id: 'contrast-undeterminable',
+    sc: '1.4.3',
+    text:
+      'Check the contrast of the elements axe could not measure by hand (WebAIM Contrast ' +
+      'Checker, or a11y-loop contrast <fg> <bg>).',
+    why:
+      'axe gives up on background images, gradients, pseudo-element backgrounds and ' +
+      'foreground opacity or occlusion, and reports them as incomplete. A computed ratio of ' +
+      '1:1 is the usual tell.',
+  },
+  'color-contrast-enhanced': {
+    id: 'contrast-enhanced-undeterminable',
+    sc: '1.4.6',
+    text: 'Check the enhanced-contrast candidates axe could not measure by hand.',
+    why: 'Same limitation as SC 1.4.3: computed backgrounds defeat the measurement.',
+  },
+  'frame-tested': {
+    id: 'cross-origin-frames',
+    sc: null,
+    text: 'Audit the contents of cross-origin iframes separately, at their own origin.',
+    why:
+      'axe cannot inject into a frame it cannot script, so that content was not tested at ' +
+      'all — its absence from this report means nothing.',
+  },
+  'aria-hidden-focus': {
+    id: 'aria-hidden-focus-review',
+    sc: '4.1.2',
+    text: 'Confirm that elements inside aria-hidden containers really are unreachable.',
+    why: 'axe could not determine focusability for some of these elements.',
+  },
+  'link-in-text-block': {
+    id: 'link-distinguishable',
+    sc: '1.4.1',
+    text: 'Confirm links inside body text are distinguishable without relying on colour alone.',
+    why: 'axe could not determine the surrounding text colour for some links.',
+  },
+  'target-size': {
+    id: 'target-size-axe',
+    sc: '2.5.8',
+    text: 'Re-measure the targets axe flagged for size by hand.',
+    why:
+      'axe ships target-size disabled by default because of a documented false-positive trail ' +
+      'with overlapping and translucent targets. a11y-loop enables it, and always reports it ' +
+      'as needs-review.',
+  },
+};
+
+/** Checks that are never automated at all, listed so their absence is not read as a pass. */
+const NEVER_AUTOMATED = [
+  {
+    id: 'hover-focus-contrast',
+    sc: '1.4.11',
+    text: 'Check the contrast of hover and focus states.',
+    why:
+      'No engine checks state contrast unless the state is driven and re-scanned. Use ' +
+      '--interact to add hover and focus states to the audit.',
+  },
+];
+
+/**
+ * @param {object} input
+ * @param {object} input.facts page inventory from `surveyPageFacts`
+ * @param {string[]} [input.incompleteRuleIds] axe rules that returned incomplete
+ * @param {boolean} [input.statesRun] whether any --interact states were audited
+ * @returns {Array<{id:string, sc:string|null, text:string, why:string}>}
+ */
+export function buildChecklist({ facts = {}, incompleteRuleIds = [], statesRun = [] } = {}) {
+  const inventory = {
+    images: 0,
+    formFields: 0,
+    links: 0,
+    headings: 0,
+    videos: 0,
+    audios: 0,
+    tables: 0,
+    iframes: 0,
+    dialogs: 0,
+    ariaAttributes: 0,
+    animations: 0,
+    stickyElements: 0,
+    ...facts,
+  };
+
+  const items = [...UNIVERSAL];
+
+  for (const item of CONDITIONAL) {
+    if (!item.when(inventory)) continue;
+    items.push({
+      id: item.id,
+      sc: item.sc,
+      text: typeof item.text === 'function' ? item.text(inventory) : item.text,
+      why: item.why,
+    });
+  }
+
+  const seen = new Set(items.map((i) => i.id));
+  for (const ruleId of incompleteRuleIds) {
+    const note = ENGINE_NOTES[ruleId];
+    if (note && !seen.has(note.id)) {
+      items.push(note);
+      seen.add(note.id);
+    }
+  }
+
+  // If no interaction states were audited, hover/focus contrast is untested.
+  if (statesRun.length === 0) {
+    for (const item of NEVER_AUTOMATED) {
+      if (!seen.has(item.id)) items.push(item);
+    }
+  }
+
+  return items;
+}

package/src/lib/format/human.js

@@ -0,0 +1,175 @@
+/**
+ * Terse human output.
+ *
+ * Findings are grouped by rule so a page with 34 contrast failures does not
+ * produce 34 identical citation lines, and every group leads with the success
+ * criterion, because the criterion is the source of the obligation — the ACT id
+ * and the axe rule id are secondary identifiers.
+ */
+
+import { formatCitation } from '../wcag-map.js';
+import { CLEAN_VERDICT, COVERAGE } from './json.js';
+
+const BULLET = '·';
+
+/**
+ * A one-line description of what was audited. An inline fragment is summarised
+ * rather than printed, because agents pass whole components on the command line.
+ */
+export function describeTarget(target) {
+  if (target.type === 'url') return target.value;
+  if (target.type === 'file') {
+    return `${target.value}${target.servedAt ? ` (served at ${target.servedAt})` : ''}`;
+  }
+  const size = String(target.value ?? '').length;
+  return `inline HTML fragment, ${size} chars${target.servedAt ? ` (served at ${target.servedAt})` : ''}`;
+}
+
+/** `SC 4.1.2 Name, Role, Value (Level A) · ACT 97a4e1 · axe: button-name` */
+export function findingHeadline(finding) {
+  const parts = [];
+  const citation = formatCitation(finding.wcag);
+  parts.push(citation ?? `${finding.source}: ${finding.ruleId}`);
+  if (finding.act?.length) parts.push(`ACT ${finding.act.join(', ')}`);
+  if (citation) {
+    parts.push(finding.source === 'axe' ? `axe: ${finding.ruleId}` : `a11y-loop: ${finding.ruleId}`);
+  }
+  if (finding.wcag?.wcag22Only) parts.push('WCAG 2.2 only');
+  return parts.join(` ${BULLET} `);
+}
+
+/** Group findings that share a headline, preserving first-seen order. */
+export function groupFindings(findings) {
+  const groups = new Map();
+  for (const finding of findings) {
+    const key = `${finding.ruleId}::${finding.state ?? ''}`;
+    if (!groups.has(key)) {
+      groups.set(key, { headline: findingHeadline(finding), state: finding.state, items: [] });
+    }
+    groups.get(key).items.push(finding);
+  }
+  return [...groups.values()];
+}
+
+function formatSuggestionLines(finding, indent) {
+  if (!finding.suggestions?.length) return [];
+  return finding.suggestions.map((s) => {
+    const what = s.role === 'background' ? 'background' : 'text';
+    return `${indent}fix: ${what} ${s.direction} → ${s.hex} (ratio ${s.newRatioDisplay ?? s.newRatio}:1)`;
+  });
+}
+
+function formatPassNote(finding) {
+  const passes = finding.passes ?? [];
+  if (passes.length === 0 || passes.includes('default')) return '';
+  return `  [only under: ${passes.join(', ')}]`;
+}
+
+function formatGroup(group, { indent = '  ' } = {}) {
+  const lines = [];
+  const inner = `${indent}  `;
+  const count = group.items.length;
+  const stateNote = group.state ? ` ${BULLET} state: ${group.state}` : '';
+  lines.push(`${indent}${group.headline}${stateNote}${count > 1 ? ` (${count} elements)` : ''}`);
+
+  const messages = new Set(group.items.map((f) => f.message));
+  const shared = messages.size === 1 && count > 1;
+  if (shared) lines.push(`${inner}${group.items[0].message}`);
+
+  for (const finding of group.items) {
+    lines.push(`${inner}${BULLET} ${finding.selector || '(document)'}${formatPassNote(finding)}`);
+    if (!shared) lines.push(`${inner}  ${finding.message}`);
+    lines.push(...formatSuggestionLines(finding, `${inner}  `));
+  }
+
+  const helpUrl = group.items.find((f) => f.helpUrl)?.helpUrl;
+  if (helpUrl) lines.push(`${inner}${helpUrl}`);
+  return lines;
+}
+
+function section(title, findings, note) {
+  if (findings.length === 0) return [];
+  const lines = ['', `${title} (${findings.length})${note ? ` — ${note}` : ''}`];
+  for (const group of groupFindings(findings)) {
+    lines.push(...formatGroup(group));
+  }
+  return lines;
+}
+
+/**
+ * @param {object} report the JSON report
+ * @param {{quiet?:boolean}} [opts]
+ * @returns {string}
+ */
+export function formatHuman(report, opts = {}) {
+  const { quiet = false } = opts;
+  const { summary, findings, tool, target, manualChecklist = [] } = report;
+
+  if (quiet) {
+    return [
+      `${summary.verdict} ${BULLET} ${summary.needsReview} to review ${BULLET} ` +
+        `${summary.bestPractice} best-practice ${BULLET} ${manualChecklist.length} manual checks`,
+      '',
+    ].join('\n');
+  }
+
+  const lines = [];
+  lines.push(`a11y-loop audit ${BULLET} ${describeTarget(target)}`);
+  lines.push(`Target standard: ${summary.target}`);
+
+  lines.push(...section('VIOLATIONS', findings.violations));
+  lines.push(
+    ...section(
+      'NEEDS REVIEW',
+      findings.needsReview,
+      'axe reported these as incomplete, or a11y-loop found something it cannot judge alone',
+    ),
+  );
+  lines.push(...section('BEST PRACTICE', findings.bestPractice, 'no success criterion, non-blocking'));
+
+  if (manualChecklist.length > 0) {
+    lines.push('', `MANUAL CHECKS (${manualChecklist.length}) — automation cannot judge these`);
+    for (const item of manualChecklist) {
+      const sc = item.sc ? `SC ${item.sc}: ` : '';
+      lines.push(`  ${BULLET} ${sc}${item.text}`);
+      lines.push(`    why: ${item.why}`);
+    }
+  }
+
+  lines.push('');
+  if (summary.violations === 0) {
+    lines.push(`${CLEAN_VERDICT} across ${tool.passesRun.length} rendering passes.`);
+  } else {
+    lines.push(
+      `${summary.verdict}, ${summary.needsReview} finding(s) needing review, ` +
+        `${summary.bestPractice} best-practice note(s).`,
+    );
+  }
+  if (summary.needsReview > 0) {
+    lines.push(
+      `The ${summary.needsReview} needs-review finding(s) are not passes — see the NEEDS REVIEW ` +
+        'section above, or the needsReview array in --json output.',
+    );
+  }
+
+  lines.push('');
+  lines.push(provenanceLine(tool));
+  lines.push(COVERAGE.statement);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Per-report provenance: everything needed to reproduce or date the result. */
+export function provenanceLine(tool) {
+  const parts = [
+    `${tool.name} ${tool.version}`,
+    `axe-core ${tool.axeCoreVersion}`,
+    `${tool.browser} ${tool.browserVersion}`,
+    `viewport ${tool.viewport.width}×${tool.viewport.height}`,
+    `passes: ${tool.passesRun.join(', ')}`,
+  ];
+  if (tool.statesRun?.length) parts.push(`states: ${tool.statesRun.join(', ')}`);
+  else parts.push('states: none (use --interact to audit modal/error/route states)');
+  parts.push(tool.timestamp);
+  return `Provenance: ${parts.join(` ${BULLET} `)}`;
+}