everyhexcode 0.0.0-stage → 0.1.0

package/src/engine/plain.js

@@ -0,0 +1,124 @@
+// Each finding in plain words, for people who have never heard of WCAG: what it is and where (named the way a person
+// sees it: the search box, the footer line, a link), why it matters, and the fix as a colour and a CSS line. The
+// selector, the variable and the rule number stay as detail. A template, the same words every time, no model.
+import { contrast, family, info } from './color.js';
+
+const TAGS = { a: 'link', button: 'button', input: 'text field', textarea: 'text box', select: 'drop-down', label: 'label', h1: 'main heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading', p: 'text', li: 'list item', th: 'table heading', td: 'table text', small: 'small print', code: 'code', pre: 'code', blockquote: 'quote', caption: 'caption', figcaption: 'caption', summary: 'toggle', nav: 'menu', footer: 'footer', header: 'header', svg: 'icon', hr: 'divider line', body: 'page text', html: 'page text', span: 'text', div: 'text', strong: 'bold text', b: 'bold text', em: 'text', time: 'date', mark: 'highlight' };
+const PLACES = [[/\bfooter\b|(^|[-_])footer/, 'in the footer'], [/\bheader\b|(^|[-_])(header|masthead|topbar)/, 'in the header'], [/\bnav\b|(^|[-_])(nav|navbar|menu)/, 'in the menu'], [/\baside\b|(^|[-_])sidebar/, 'in the sidebar'], [/(^|[-_.])(modal|dialog|popover)/, 'in pop-ups'], [/(^|[-_.])card/, 'on cards'], [/(^|[-_.])hero/, 'in the top banner'], [/\btable\b|\bt[dh]\b/, 'in tables'], [/(^|[-_.])(alert|toast|banner)/, 'in notices'], [/(^|[-_.])(tooltip)/, 'in tooltips']];
+// class words that say nothing to a reader
+const NOISE = /^(js|is|has|u|c|l|o|wp|el|col|row|d|flex|grid|container|wrapper|wrap|inner|outer|item|block|main|content|text|color|colour|style|active|current|default|base|primary|secondary|lg|md|sm|xs|xl|\d+)$/;
+
+const human = (s) => s.replace(/^[-_.#]+/, '').split(/[-_]+|(?<=[a-z])(?=[A-Z])/).map((w) => w.toLowerCase()).filter((w) => w && !NOISE.test(w));
+
+/** The selector's last element, read as a person would name it. */
+export function thingOf(selector, part, kind) {
+  const first = String(selector || '').split(/,(?![^(]*\))/)[0].trim();
+  const steps = first.split(/\s*[>+~]\s*|\s+/).filter(Boolean);
+  const last = steps[steps.length - 1] || '';
+  const before = steps.slice(0, -1).join(' ').toLowerCase();
+  const state = /:hover/.test(last) ? 'hover' : /:focus/.test(last) ? 'focus' : /:visited/.test(last) ? 'visited' : /::?placeholder/.test(last) ? 'placeholder' : /:active/.test(last) ? 'pressed' : null;
+  const bare = last.replace(/::?[\w-]+(\([^)]*\))?/g, '');
+  const tag = (bare.match(/^[a-z][a-z0-9]*/i) || [''])[0].toLowerCase();
+  const classes = [...bare.matchAll(/[.#]([\w-]+)/g)].map((m) => m[1]);
+  const attr = (bare.match(/\[type=["']?(\w+)/) || [])[1];
+  const cls = classes.join(' ').toLowerCase();
+  let name = null, shape = kind === 'ui' ? 'field' : 'text';
+  if (/search/.test(cls) || attr === 'search') { name = 'search box'; shape = 'field'; }
+  else if (attr === 'checkbox' || /checkbox/.test(cls)) { name = 'checkbox'; shape = 'check'; }
+  else if (attr === 'radio' || /radio/.test(cls)) { name = 'option button'; shape = 'check'; }
+  else if (tag === 'input' || tag === 'textarea' || tag === 'select' || /(^|[-_ ])(input|field|form-control|textarea|select)([-_ ]|$)/.test(cls)) { name = tag === 'select' || /select/.test(cls) ? 'drop-down' : tag === 'textarea' ? 'text box' : 'text field'; shape = 'field'; }
+  else if (tag === 'button' || attr === 'submit' || /(^|[-_ ])(btn|button|cta)([-_ ]|$)/.test(cls)) { name = 'button'; shape = 'button'; }
+  else if (tag === 'a' || /(^|[-_ ])link([-_ ]|s?$)/.test(cls)) { name = 'link'; shape = 'link'; }
+  else if (/^h[1-6]$/.test(tag) || /(^|[-_ ])(heading|title|headline)([-_ ]|$)/.test(cls)) { name = tag === 'h1' ? 'main heading' : 'heading'; shape = 'heading'; }
+  else if (/icon|svg/.test(cls) || tag === 'svg') { name = 'icon'; shape = 'icon'; }
+  else if (/badge|tag|chip|pill|label/.test(cls)) { name = 'label'; shape = 'badge'; }
+  // otherwise the class or id in words: .footer-trademark is the "footer trademark" text
+  const PLACE_WORDS = /^(footer|header|masthead|topbar|nav|navbar|menu|sidebar|modal|dialog|popover|card|hero|alert|toast|banner|tooltip)$/;
+  const words = human(classes[classes.length - 1] || '').filter((w) => !PLACE_WORDS.test(w));
+  if (!name) name = words.length ? `“${words.join(' ')}” ${tag && TAGS[tag] && !/^(text|page text)$/.test(TAGS[tag]) ? TAGS[tag] : 'text'}` : (TAGS[tag] || (kind === 'ui' ? 'control' : 'text'));
+  // where it sits, from the elements around it (or its own class), unless its name already says so
+  let where = null;
+  const around = `${before} ${cls}`;
+  for (const [re, w] of PLACES) if (re.test(around) && !name.includes(w.replace(/^(in|on) (the )?/, '').replace(/s$/, ''))) { where = w; break; }
+  if (!where) { const id = (before.match(/#([\w-]+)/g) || []).pop(); if (id) { const w = human(id); if (w.length) where = `in the “${w.join(' ')}” section`; } }
+  if (state === 'placeholder') name = `placeholder text in the ${name}`;
+  const when = state === 'hover' ? 'when the pointer is over it' : state === 'focus' ? 'when it has keyboard focus' : state === 'visited' ? 'once visited' : state === 'pressed' ? 'while pressed' : null;
+  const what = part === 'border' ? `border of the ${name}` : part === 'outline' ? `focus ring of the ${name}` : name;
+  return { name, what, where, when, shape: part === 'outline' ? 'focus' : shape };
+}
+
+/** A colour variable's name in words: --muted-foreground is "muted text", --input is "input borders". */
+function tokenThing(name, kind) {
+  const w = human(String(name).replace(/^(--|\$|@)/, '')).filter((x) => !/^(fg|foreground|bg|background|on)$/.test(x));
+  if (kind === 'ui') return w.some((x) => /ring|focus|outline/.test(x)) ? 'focus ring' : w.some((x) => /input|border|field|control/.test(x)) ? 'text field borders' : `${w.join(' ') || 'interface'} color`;
+  return w.length ? `${w.join(' ')} text` : 'body text';
+}
+
+/** A colour named for a reader: "very light gray", "near-black". */
+export function colorWords(hex) {
+  const o = info(hex).oklch || { l: 50, c: 0 }, l = o.l / 100, f = family(hex);
+  if (l > 0.95) return /^f{6}$/i.test(hex) ? 'white' : 'off-white';
+  if (l < 0.2) return 'near-black';
+  if (f === 'white' || f === 'black' || f === 'gray') return l > 0.85 ? 'very light gray' : l > 0.7 ? 'light gray' : l < 0.4 ? 'dark gray' : 'gray';
+  return `${l > 0.85 ? 'very light ' : l > 0.7 ? 'light ' : l < 0.4 ? 'dark ' : ''}${f}`;
+}
+
+const lighterOrDarker = (from, to) => ((info(to).oklch?.l ?? 0) > (info(from).oklch?.l ?? 0) ? 'lighter' : 'darker');
+const propOf = (part, side) => (side === 'bg' ? 'background-color' : part === 'border' ? 'border-color' : part === 'outline' ? 'outline-color' : 'color');
+
+/**
+ * The plain finding for one judged pair. `fix` is the nearest passing colour for this pair if there is one:
+ * { side: 'fg' | 'bg', name, from, to, ratio }.
+ */
+export function explain(p, fix) {
+  const part = /sets (border|outline)\b/.test(p.why || '') ? (p.why.match(/sets (border|outline)/)[1]) : 'color';
+  const fromRule = p.selector && !/^(body|html|:root)$/.test(p.selector);
+  const t = fromRule ? thingOf(p.selector, part, p.kind) : { what: /default link/.test(p.fg.name) ? 'links' : /default text|browser default/.test(p.fg.name) ? 'page text' : tokenThing(p.fg.source || p.fg.name, p.kind), where: null, when: null, shape: p.kind === 'ui' ? 'field' : 'text' };
+  if (/links? no CSS rule colours/.test(p.why || '')) { t.what = /^1 link/.test(p.why) ? 'link' : 'links'; t.shape = 'link'; }
+  const plural = /s$/.test(t.what) && !/(text|ss)$/.test(t.what);
+  const onPage = p.pageBg && p.bg.shown === p.pageBg;
+  const bgWords = onPage ? 'the page background' : `its ${colorWords(p.bg.shown)} background`;
+  const subject = `${t.what}${t.where ? ` ${t.where}` : ''}`;
+  const Subject = subject.replace(/[a-z]/, (c) => c.toUpperCase());
+  const swatches = `${colorWords(p.fg.shown)} #${p.fg.shown} on ${p.bg.shown === p.pageBg ? '' : `${colorWords(p.bg.shown)} `}#${p.bg.shown}`;
+  const isUi = p.kind === 'ui';
+  const bad = isUi ? 'too faint' : p.ratio < 3 ? 'hard to read' : 'harder to read than it should be';
+  const rule = isUi ? 'Borders, icons and focus rings need at least 3:1' : p.kind === 'large' ? 'Large text (24px, or 19px bold) needs at least 3:1' : 'Text needs at least 4.5:1';
+  const who = isUi ? (t.shape === 'focus' ? 'Keyboard users may not see where they are on the page.' : /field|search|box|drop-down|check/.test(t.what) ? `People with low vision may not see where the ${t.name || 'field'} is or where to type.` : 'People with low vision may not see it.') : 'People with low vision, or on a phone in sunlight, may not be able to read it.';
+  const base = {
+    subject: Subject, shape: t.shape,
+    title: p.kind === 'decor' ? `${Subject}: decoration, no minimum` : p.pass === false ? `${Subject} ${plural ? 'are' : 'is'} ${bad}` : p.pass ? `${Subject}: ${p.ratio >= p.need + 0.5 ? 'clear' : 'just clear enough'}` : `${Subject}: not judged`,
+    where: [t.where, t.when].filter(Boolean).join(', ') || null,
+    colors: swatches,
+  };
+  if (p.pass !== false || p.kind === 'decor') return { ...base, what: null, why: null, fix: null };
+  base.what = `The ${subject}${t.when ? ` (${t.when})` : ''} ${plural ? 'are' : 'is'} ${colorWords(p.fg.shown)} (#${p.fg.shown}) on ${bgWords} (#${p.bg.shown}). The two are only ${p.ratio}:1 apart.`;
+  base.why = `${who} ${rule}; ${plural ? 'these are' : 'this one is'} ${p.ratio}:1.`;
+  if (fix) {
+    const prop = propOf(part, fix.side);
+    const isVar = /^(--|\$|@)/.test(fix.name);
+    const css = isVar ? `${fix.name}: #${fix.to};` : `${fromRule ? p.selector.split(/,(?![^(]*\))/)[0].trim() : fix.side === 'bg' ? 'body' : 'a'} { ${prop}: #${fix.to}; }`;
+    base.fix = { side: fix.side, name: fix.name, from: fix.from, to: fix.to, ratio: fix.ratio, css,
+      text: `Make the ${fix.side === 'bg' ? 'background' : part === 'color' ? (t.shape === 'link' ? 'link color' : 'text color') : part === 'outline' ? 'focus ring' : 'border'} a little ${lighterOrDarker(fix.from, fix.to)}: #${fix.from} → #${fix.to}, the nearest shade of the same color that passes (${fix.ratio}:1).${isVar ? ` It is set once, as ${fix.name}, so every place that uses it is fixed too.` : ''}` };
+  } else base.fix = null;
+  return base;
+}
+
+/** The top of a report in plain words: how much was checked, how much fails, the things to fix first. */
+export function plainSummary(r) {
+  const judged = r.pairs.filter((p) => p.kind !== 'decor' && !p.optional);
+  const fail = judged.filter((p) => p.pass === false).sort((a, b) => a.ratio / a.need - b.ratio / b.need);
+  const seen = new Set(), top = [];
+  for (const p of fail) { const k = p.plain?.title; if (k && !seen.has(k)) { seen.add(k); top.push(k); } }
+  const n = judged.length;
+  const text = !n ? 'No color combinations to judge.' : fail.length
+    ? `We checked ${n} color ${n === 1 ? 'combination' : 'combinations'}. ${fail.length === 1 ? '1 is' : `${fail.length} are`} too low in contrast: people with low vision, or on a phone in bright light, may not be able to see ${fail.length === 1 ? 'it' : 'them'}.`
+    : `We checked ${n} color ${n === 1 ? 'combination' : 'combinations'}, and all of them are clear enough to read and see.`;
+  return { text, top: top.slice(0, 5) };
+}
+
+/** Contrast in words, for column help. */
+export const CONTRAST_HELP = 'How far apart two colors are in lightness: 1:1 is the same color, 21:1 is black on white.';
+export const RULE_HELP = 'The accessibility standard (WCAG 2, level AA): normal text needs 4.5:1; large text, borders, icons and focus rings need 3:1.';
+export const APCA_HELP = 'APCA is a newer method, still a draft. Lc runs from 0 (invisible) to about 106; body text wants Lc 75 or more. Advisory only: it does not change pass or fail.';
+export { contrast };

package/src/files.js

@@ -0,0 +1,97 @@
+// Which files to check: paths, folders (walked) and simple globs (*, **), the kinds the checker reads, and how CSS
+// files are joined so a variable set in one file resolves where another file uses it.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const EXT = /\.(css|scss|sass|less|pcss|postcss|json|js|cjs|mjs|ts|txt)$/i;
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.nuxt', '.svelte-kit', 'coverage', 'vendor', '.turbo', '.cache']);
+// a JS or TS file is read only when it is a Tailwind config or a theme/tokens file, never as app code
+const CONFIG_JS = /(^|[/\\])(tailwind\.config|theme|tokens?|colors?|palette)[\w.-]*\.(c|m)?(js|ts)$/i;
+
+function globToRe(g) {
+  let s = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') { s += '.*'; i++; if (g[i + 1] === '/') i++; }
+    else if (c === '*') s += '[^/]*';
+    else if (c === '?') s += '[^/]';
+    else s += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${s}$`);
+}
+
+function walk(dir, out, root) {
+  let list;
+  try { list = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of list) {
+    if (e.name.startsWith('.') && e.name !== '.') continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) { if (!SKIP.has(e.name)) walk(p, out, root); }
+    else if (EXT.test(e.name)) out.push(p);
+  }
+}
+
+/** The files a list of arguments means, each once, in a stable order. */
+export function expand(args, cwd = process.cwd()) {
+  const out = [];
+  const named = new Set(); // files given by name are read whatever they are called
+  for (const a of args.length ? args : ['.']) {
+    if (/[*?]/.test(a)) {
+      const base = a.slice(0, a.search(/[*?]/)).replace(/[^/]*$/, '') || '.';
+      const re = globToRe(path.posix.normalize(a.replace(/\\/g, '/')).replace(/^\.\//, ''));
+      const all = [];
+      walk(path.resolve(cwd, base), all, cwd);
+      for (const f of all) { const rel = path.relative(cwd, f).replace(/\\/g, '/'); if (re.test(rel)) out.push(f); }
+      continue;
+    }
+    const p = path.resolve(cwd, a);
+    let st;
+    try { st = fs.statSync(p); } catch { throw new Error(`No such file or folder: ${a}`); }
+    if (st.isDirectory()) walk(p, out, cwd); else { out.push(p); named.add(p); }
+  }
+  const keep = (f) => !/\.(js|cjs|mjs|ts)$/i.test(f) || CONFIG_JS.test(f);
+  const jsonOk = (f) => !/\.json$/i.test(f) || !/(^|[/\\])(package(-lock)?|tsconfig[\w.-]*|jsconfig|composer|manifest|\.?eslintrc[\w.-]*|renovate|turbo|vercel|firebase|app)\.json$/i.test(f);
+  return [...new Set(out)].filter((f) => named.has(f) || (keep(f) && jsonOk(f))).sort();
+}
+
+/**
+ * Groups to check: all stylesheets together (one cascade: a variable set in tokens.css resolves in buttons.css), and
+ * each token or config file alone. Each group keeps where every file starts in the joined text, so findings and fixes
+ * go back to the right file and line.
+ */
+export const skipped = [];
+export function groups(files, read = (f) => fs.readFileSync(f, 'utf8')) {
+  const css = [], other = [];
+  for (const f of files) {
+    const text = read(f);
+    if (text.length > 5_000_000) { skipped.push(`${f} (over 5 MB, not read)`); continue; }
+    if (/\.(css|scss|sass|less|pcss|postcss)$/i.test(f)) css.push({ file: f, text }); else other.push({ file: f, text });
+  }
+  const out = [];
+  // stylesheets are read together only when one uses a variable another defines (tokens.css and buttons.css): unrelated
+  // files stay apart, so a fix in one never comes from another's colours
+  const defs = css.map((c) => new Set([...c.text.matchAll(/(--[\w-]+)\s*:/g)].map((m) => m[1])));
+  const uses = css.map((c) => new Set([...c.text.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1])));
+  const parent = css.map((_, i) => i);
+  const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+  for (let i = 0; i < css.length; i++) for (let j = 0; j < css.length; j++) {
+    if (i !== j && [...uses[i]].some((v) => !defs[i].has(v) && defs[j].has(v))) parent[find(i)] = find(j);
+  }
+  const sets = new Map();
+  css.forEach((c, i) => { const r = find(i); sets.set(r, [...(sets.get(r) || []), c]); });
+  for (const list of sets.values()) {
+    let text = '', parts = [];
+    for (const c of list) { parts.push({ file: c.file, start: text.length, end: text.length + c.text.length, text: c.text }); text += c.text + '\n'; }
+    out.push({ label: list.length === 1 ? list[0].file : `${list.length} stylesheets that share variables`, text, parts });
+  }
+  for (const o of other) out.push({ label: o.file, text: o.text, parts: [{ file: o.file, start: 0, end: o.text.length, text: o.text }] });
+  return out;
+}
+
+/** File, line and column of an offset in a joined group. */
+export function locate(group, offset) {
+  const p = group.parts.find((x) => offset >= x.start && offset <= x.end) || group.parts[0];
+  const before = p.text.slice(0, Math.max(0, offset - p.start));
+  const line = before.split('\n').length;
+  return { file: p.file, line, column: before.length - before.lastIndexOf('\n') };
+}

package/src/no-apca.js

@@ -0,0 +1,10 @@
+// The command-line build leaves APCA out (its licence is for W3C web-content use; see LICENSE.md): these stand in for
+// shared/apca.js, so nothing in the bundle computes or names an APCA value.
+export const apca = () => null;
+export const apcaUse = () => '';
+export const APCA_LEVELS = [];
+export const APCA_NOTICE = '';
+export const APCA_WHY = '';
+export const APCA_FORUM = '';
+export const apcaLine = () => '';
+export const lcText = () => '';

package/src/output.js

@@ -0,0 +1,110 @@
+// How a check is written out: text for a terminal, JSON, SARIF (GitHub code scanning shows it on the pull request),
+// Markdown (a job summary or a PR comment) and GitHub annotations.
+import path from 'node:path';
+import { locate } from './files.js';
+
+const C = process.stdout.isTTY && !process.env.NO_COLOR ? { r: '\x1b[31m', g: '\x1b[32m', y: '\x1b[33m', d: '\x1b[2m', b: '\x1b[1m', x: '\x1b[0m' } : { r: '', g: '', y: '', d: '', b: '', x: '' };
+const rel = (f) => (/^https?:/.test(f) ? f : path.relative(process.cwd(), f).replace(/\\/g, '/') || f);
+const SITE = 'https://everyhexcode.com';
+
+/** Where a pair's text colour is declared (else its background), as file and line. */
+export function whereOf(group, report, pair) {
+  for (const side of [pair.fg, pair.bg]) {
+    const t = report.tokens.find((x) => x.name === side.name && x.mode === pair.mode && x.at != null) || report.tokens.find((x) => x.name === side.name && x.at != null);
+    if (t) return locate(group, t.at);
+  }
+  return { file: group.parts[0].file, line: 1, column: 1 };
+}
+
+export const failing = (r) => r.pairs.filter((p) => !p.pass && p.kind !== 'decor' && !p.optional);
+// look-alike pairs once, whichever modes they occur in
+export const lookAlike = (r) => r.collisions.filter((c) => c.common).filter((c, i, l) => l.findIndex((x) => x.a.name === c.a.name && x.b.name === c.b.name) === i);
+const link = (r) => `${SITE}/color-checker`;
+const fixOf = (r, p) => r.fix.changes.filter((c) => c.mode === p.mode && (c.name === p.fg.name || c.name === p.bg.name)).map((c) => `${c.name} → #${c.to}`).filter((x, i, l) => l.indexOf(x) === i).join(', ');
+
+export function text(results, opts) {
+  const out = [];
+  for (const { group, report: r } of results) {
+    out.push(`${C.b}${rel(group.label)}${C.x} ${C.d}(${r.input.kind}, ${r.input.colors} ${r.input.colors === 1 ? 'color' : 'colors'}${r.input.modes.length > 1 ? ', light and dark' : ''})${C.x}`);
+    const f = failing(r);
+    for (const p of f) {
+      const at = whereOf(group, r, p);
+      const fx = fixOf(r, p);
+      // a rendered page has no file lines: the element is the place to look
+      const where = /^https?:/.test(at.file) ? (p.why || '').replace(/ sets .*$/, '') : `${rel(at.file)}:${at.line}`;
+      const pl = p.plain || {};
+      out.push(`  ${C.r}✗${C.x} ${C.b}${pl.title || `${p.fg.name} on ${p.bg.name}`}${C.x}${r.input.modes.length > 1 ? ` [${p.mode}]` : ''}: #${p.fg.shown} on #${p.bg.shown}, ${C.b}${p.ratio}:1${C.x}, needs ${p.need}:1  ${C.d}${where}${C.x}${pl.why ? `\n      ${pl.why}` : ''}${pl.fix ? `\n      ${C.g}fix:${C.x} ${pl.fix.text}\n      ${C.g}${pl.fix.css}${C.x}` : fx ? `\n      ${C.g}fix:${C.x} ${fx}` : ''}`);
+    }
+    for (const c of lookAlike(r)) out.push(`  ${C.y}!${C.x} ${c.a.name} and ${c.b.name} look alike with ${c.worst.label.toLowerCase()} (ΔE ${c.worst.d})`);
+    if (opts.verbose) for (const p of r.pairs.filter((x) => x.pass)) out.push(`  ${C.g}✓${C.x} ${p.fg.name} on ${p.bg.name}${r.input.modes.length > 1 ? ` [${p.mode}]` : ''}: ${p.ratio}:1`);
+    out.push(`  ${f.length ? C.r : C.g}${r.summary.pass} pass, ${r.summary.fail} fail${C.x} against ${r.standard}${r.input.warnings.length ? `  ${C.y}${r.input.warnings.join(' ')}${C.x}` : ''}`);
+    if (r.fix.remaining.length) out.push(`  ${C.y}${r.fix.remaining.length} ${r.fix.remaining.length === 1 ? 'pair has' : 'pairs have'} no single-color fix: ${r.fix.remaining.slice(0, 2).map((x) => `${x.fg} on ${x.bg}: ${x.reason}`).join('; ')}.${C.x}`);
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+export function json(results) {
+  return JSON.stringify(results.map(({ group, report }) => ({ file: group.parts.length === 1 ? rel(group.parts[0].file) : group.parts.map((p) => rel(p.file)), report })), null, 2);
+}
+
+export function markdown(results) {
+  const out = ['## Color check', ''];
+  for (const { group, report: r } of results) {
+    const f = failing(r);
+    out.push(`### ${rel(group.label)}: ${f.length ? `❌ ${r.summary.fail} failing` : '✅ all pass'} (${r.standard})`, '', r.summary.plain?.text || r.summary.text, '');
+    if (f.length) {
+      out.push('| What | Colors | Mode | Contrast | Needs | Where | Fix |', '|---|---|---|---|---|---|---|');
+      const cell = (x) => String(x).replace(/\|/g, '/');
+      for (const p of f) { const at = whereOf(group, r, p); const pl = p.plain || {}; out.push(`| ${cell(pl.title || '–')} | \`#${p.fg.shown}\` on \`#${p.bg.shown}\` ${p.fg.name === '#' + p.fg.shown && p.bg.name === '#' + p.bg.shown ? '' : `(\`${cell(p.fg.name)}\` on \`${cell(p.bg.name)}\`)`} | ${p.mode} | ${p.ratio}:1 | ${p.need}:1 | ${/^https?:/.test(at.file) ? `\`${cell((p.why || '').replace(/ sets .*$/, ''))}\`` : `${rel(at.file)}:${at.line}`} | ${pl.fix ? `\`${cell(pl.fix.css)}\`` : fixOf(r, p) || '–'} |`); }
+      out.push('');
+      for (const p of f.filter((x) => x.plain?.why)) out.push(`- **${p.plain.title}.** ${p.plain.why}${p.plain.fix ? ` ${p.plain.fix.text}` : ''}`);
+      out.push('');
+    }
+    if (r.fix.diff) out.push('<details><summary>The fix as a diff</summary>', '', '```diff', r.fix.diff.trim(), '```', '', '</details>', '');
+  }
+  out.push(`Checked with [everyhexcode](${link()}): WCAG 2 contrast, color vision and the nearest passing colors.`);
+  return out.join('\n');
+}
+
+const esc = (s) => String(s).replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+// property values (file, title) also escape : and , (GitHub's workflow command format)
+const escP = (s) => esc(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
+export function github(results) {
+  const out = [];
+  for (const { group, report: r } of results) {
+    for (const p of failing(r)) {
+      const at = whereOf(group, r, p), fx = fixOf(r, p);
+      const loc = /^https?:/.test(at.file) ? '' : `file=${escP(rel(at.file))},line=${at.line},col=${at.column},`;
+      out.push(`::error ${loc}title=${escP(p.plain?.title ? `${p.plain.title}: ${p.ratio}:1, needs ${p.need}:1` : `Contrast ${p.ratio}:1 (needs ${p.need}:1)`)}::${esc(`${p.plain?.why ? `${p.plain.why} ${p.plain.fix ? `Fix: ${p.plain.fix.css} ` : ''}` : ''}${p.fg.name} on ${p.bg.name}${r.input.modes.length > 1 ? ` (${p.mode} mode)` : ''}${loc ? '' : ` at ${(p.why || '').replace(/ sets .*$/, '')}`} is ${p.ratio}:1; ${p.kind === 'ui' ? 'UI parts need 3:1 (WCAG 1.4.11)' : `text needs ${p.need}:1 (WCAG 1.4.3)`}.${fx ? ` Nearest passing: ${fx}.` : ''}`)}`);
+    }
+    for (const c of lookAlike(r)) out.push(`::warning title=Colors look alike::${esc(`${c.a.name} and ${c.b.name} look alike with ${c.worst.label.toLowerCase()} (ΔE ${c.worst.d}). Do not let color alone tell them apart (WCAG 1.4.1).`)}`);
+  }
+  return out.join('\n');
+}
+
+export function sarif(results, version) {
+  const rules = [
+    { id: 'contrast-text', name: 'TextContrast', shortDescription: { text: 'Text contrast below WCAG 2 (1.4.3)' }, helpUri: `${SITE}/guides/wcag-color-contrast`, defaultConfiguration: { level: 'error' } },
+    { id: 'contrast-ui', name: 'NonTextContrast', shortDescription: { text: 'UI part contrast below 3:1 (WCAG 1.4.11)' }, helpUri: `${SITE}/guides/wcag-color-contrast`, defaultConfiguration: { level: 'error' } },
+    { id: 'look-alike', name: 'ColorsLookAlike', shortDescription: { text: 'Colors that look alike with color blindness (WCAG 1.4.1)' }, helpUri: `${SITE}/color-blind-palette-checker`, defaultConfiguration: { level: 'warning' } },
+  ];
+  const res = [];
+  for (const { group, report: r } of results) {
+    for (const p of failing(r)) {
+      const at = whereOf(group, r, p), fx = fixOf(r, p);
+      res.push({ ruleId: p.kind === 'ui' ? 'contrast-ui' : 'contrast-text', level: 'error',
+        message: { text: `${p.plain?.title ? `${p.plain.title}. ${p.plain.why} ${p.plain.fix ? `${p.plain.fix.text} ` : ''}(` : ''}${p.fg.name} on ${p.bg.name}${r.input.modes.length > 1 ? ` (${p.mode} mode)` : ''}: ${p.ratio}:1, needs ${p.need}:1.${fx ? ` Nearest passing: ${fx}.` : ''}${p.plain?.title ? ')' : ''}` },
+        locations: [{ physicalLocation: { artifactLocation: { uri: rel(at.file) }, region: { startLine: at.line, startColumn: at.column } } }],
+        partialFingerprints: { pair: `${p.fg.name}|${p.bg.name}|${p.mode}` } });
+    }
+    for (const c of lookAlike(r)) {
+      const t = r.tokens.find((x) => x.name === c.a.name && x.at != null);
+      const at = t ? locate(group, t.at) : { file: group.parts[0].file, line: 1, column: 1 };
+      res.push({ ruleId: 'look-alike', level: 'warning', message: { text: `${c.a.name} and ${c.b.name} look alike with ${c.worst.label.toLowerCase()} (ΔE ${c.worst.d}).` },
+        locations: [{ physicalLocation: { artifactLocation: { uri: rel(at.file) }, region: { startLine: at.line } } }] });
+    }
+  }
+  return JSON.stringify({ $schema: 'https://json.schemastore.org/sarif-2.1.0.json', version: '2.1.0',
+    runs: [{ tool: { driver: { name: 'everyhexcode', version, informationUri: SITE + '/color-checker', rules } }, results: res }] }, null, 2);
+}