@bounded-systems/conformance-kit 0.5.0 → 0.7.0

package/gates/target-size-gate.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Target-size gate — STATIC analysis over a site/brand's INTERACTIVE-TARGET size
+// tokens (the dimensions a design system ships for buttons, controls, icon hit-
+// areas, list rows, …), member of the Token Accessibility suite. Reasons about the
+// size TOKENS, not a rendered layout, so it answers: "do these control tokens
+// PERMIT a large-enough pointer target, or do they bake in a too-small one?"
+//
+// Checks, mapped to WCAG 2.2:
+//   1. TARGET SIZE (Minimum) — SC 2.5.8 (AA): the bounding box of a pointer target
+//      must be ≥ 24×24 CSS px (unless an exception applies). A declared target token
+//      whose min(width,height) < 24px → ERROR (fails closed).
+//   2. TARGET SIZE (Enhanced) — SC 2.5.5 (AAA): ≥ 44×44 px. Reported as STATUS only
+//      (pass/fail per target) — not a hard failure, since 2.5.5 is AAA.
+//
+// SC 2.5.8 EXCEPTIONS (spacing, inline, user-agent, essential): a consumer may mark
+// a target `exception: "inline" | "essential" | "user-agent" | "spacing"` with a
+// `reason`; an exempt target is recorded (not failed) but the reason is surfaced so
+// the claim stays auditable. The HONEST SCOPE: tokens declare *intended* dimensions;
+// only the rendered DOM proves the actual box and the spacing-offset exception — so
+// this gate verifies the tokens don't UNDERCUT the floor, not that every instance
+// meets it. (The axe-gate / a manual check cover the rendered side.)
+//
+// Zero-dependency, pure exported primitives + a fail-closed CLI.
+//
+//   node gates/target-size-gate.mjs [config.json]
+//
+// INPUTS the consumer supplies (the consumer DECLARES which tokens are targets —
+// nothing is auto-assumed, because "is this token a tap target?" is design intent):
+//   argv[2] / $TARGET_CONFIG  a `config.json`:
+//     { "thresholds": { "minPx": 24, "aaaPx": 44 },
+//       "tokens": { "control-min": "44px", … },           // optional token map
+//       "targets": [ { "name":"icon-button", "width":"{control-min}"|"24px",
+//                      "height":"24px", "exception?":"inline", "reason?":"…" } ] }
+//     `width`/`height` (or a single `size` for a square) are a literal px, a `{name}`
+//     ref into `tokens`, or a number. A target with only one dimension is treated as
+//     a square of that side.
+//   $TARGET_REPORT            path to write the machine-readable JSON report.
+//
+// Thresholds (config ⊕ env), fail closed:
+//   $TARGET_MIN_PX  (default 24)  SC 2.5.8 AA floor
+//   $TARGET_AAA_PX  (default 44)  SC 2.5.5 AAA target (status only)
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export const DEFAULT_THRESHOLDS = {
+  minPx: 24, // WCAG 2.2 SC 2.5.8 (AA)
+  aaaPx: 44, // WCAG 2.2 SC 2.5.5 (AAA)
+};
+
+export const EXCEPTIONS = new Set(["inline", "essential", "user-agent", "spacing"]);
+
+/** Resolve a dimension ref (`"24px"` | `24` | `"{token}"`) against a token map → px or null. */
+export function resolveDimension(ref, tokens = {}) {
+  if (ref == null) return null;
+  if (typeof ref === "number") return ref;
+  let s = String(ref).trim();
+  const m = /^\{(.+)\}$/.exec(s);
+  if (m) { if (!(m[1] in tokens)) return null; s = String(tokens[m[1]]).trim(); }
+  const px = /^(-?[0-9]*\.?[0-9]+)\s*px$/.exec(s) || /^(-?[0-9]*\.?[0-9]+)$/.exec(s);
+  if (px) return parseFloat(px[1]);
+  const rem = /^(-?[0-9]*\.?[0-9]+)\s*rem$/.exec(s);
+  if (rem) return parseFloat(rem[1]) * 16;
+  return null;
+}
+
+/** Evaluate ONE declared target. Pure. */
+export function evaluateTarget(target, tokens = {}, thresholds = DEFAULT_THRESHOLDS) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const w = resolveDimension(target.width ?? target.size, tokens);
+  const h = resolveDimension(target.height ?? target.size, tokens);
+  const minSide = [w, h].filter((n) => n != null).length ? Math.min(...[w, h].filter((n) => n != null)) : null;
+
+  const exception = target.exception && EXCEPTIONS.has(target.exception) ? target.exception : null;
+  const aaPass = minSide == null ? null : minSide + 1e-9 >= t.minPx;
+  const aaaPass = minSide == null ? null : minSide + 1e-9 >= t.aaaPx;
+
+  const findings = [];
+  if (minSide == null) {
+    findings.push({ severity: "warn", sc: "2.5.8", msg: `target "${target.name}" has no resolvable dimension` });
+  } else if (!aaPass && !exception) {
+    findings.push({ severity: "error", sc: "2.5.8", msg: `${minSide}px < ${t.minPx}px (AA minimum)` });
+  } else if (!aaPass && exception) {
+    findings.push({ severity: "info", sc: "2.5.8", msg: `${minSide}px < ${t.minPx}px but exempt via "${exception}"${target.reason ? `: ${target.reason}` : ""}` });
+  }
+
+  return {
+    name: target.name,
+    width: w, height: h, minSide,
+    exception,
+    reason: target.reason ?? null,
+    aa: { min: t.minPx, pass: aaPass },
+    aaa: { min: t.aaaPx, pass: aaaPass },
+    findings,
+    passed: findings.every((f) => f.severity !== "error"),
+  };
+}
+
+/** Whole-suite evaluation → fail-closed report. Pure. */
+export function evaluateTargets({ targets = [], tokens = {}, thresholds = DEFAULT_THRESHOLDS } = {}) {
+  const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+  const results = targets.map((tg) => evaluateTarget(tg, tokens, t));
+  const errors = results.flatMap((r) => r.findings.filter((f) => f.severity === "error"));
+  const notes = [];
+  if (targets.length === 0) {
+    notes.push("no interactive-target tokens declared — target-size cannot be asserted from tokens alone (declare the controls' size tokens to enable this gate)");
+  }
+  return {
+    passed: errors.length === 0,
+    thresholds: t,
+    summary: {
+      targets: results.length,
+      belowAA: results.filter((r) => r.aa.pass === false && !r.exception).length,
+      exempt: results.filter((r) => r.exception).length,
+      meetsAAA: results.filter((r) => r.aaa.pass === true).length,
+      unresolved: results.filter((r) => r.minSide == null).length,
+    },
+    targets: results,
+    notes,
+    coverage: targets.length === 0 ? "none" : "declared",
+    // Envelope a future lone `target.min-size` criterion can consume.
+    target: { minSizeAA: errors.length === 0, declared: targets.length },
+  };
+}
+
+export async function runTargetSizeGate({ config = {}, thresholds = {} }) {
+  const cfg = typeof config === "string" ? JSON.parse(await readFile(config, "utf8")) : config;
+  return evaluateTargets({
+    targets: cfg.targets || [],
+    tokens: cfg.tokens || {},
+    thresholds: { ...DEFAULT_THRESHOLDS, ...(cfg.thresholds || {}), ...thresholds },
+  });
+}
+
+function envThresholds() {
+  const t = {};
+  const num = (e) => (process.env[e] != null ? Number(process.env[e]) : undefined);
+  const set = (k, e) => { const v = num(e); if (v != null && !Number.isNaN(v)) t[k] = v; };
+  set("minPx", "TARGET_MIN_PX");
+  set("aaaPx", "TARGET_AAA_PX");
+  return t;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const config = argv[0] || process.env.TARGET_CONFIG;
+  if (!config) {
+    console.error("✗ target-size-gate: usage: target-size-gate.mjs <config.json>  (or set $TARGET_CONFIG)");
+    process.exit(2);
+  }
+  const report = await runTargetSizeGate({ config, thresholds: envThresholds() });
+  if (process.env.TARGET_REPORT) await writeFile(resolve(process.env.TARGET_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const s = report.summary;
+  const line = `target-size-gate: ${s.targets} target(s) — ${s.belowAA} below AA, ${s.exempt} exempt, ${s.meetsAAA} meet AAA`;
+  if (!report.passed) {
+    console.error(`✗ ${line}`);
+    for (const r of report.targets) for (const f of r.findings) if (f.severity === "error") console.error(`  · ${r.name}: ${f.msg}`);
+    process.exit(1);
+  }
+  console.log(`✓ ${line}`);
+  for (const n of report.notes) console.log(`  · note: ${n}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ target-size-gate: error —", e.stack || e.message); process.exit(1); });
+}

package/gates/token-a11y.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Token Accessibility suite — the UNIFIED runner. One `token-a11y.json` config drives
+// every member of the suite over a single token map, and the runner FAILS CLOSED if
+// ANY member fails. This is the named "thing": token-level accessibility as one gate.
+//
+// Members (each a standalone gate, documented in TOKEN-A11Y.md):
+//   · palette          — palette-gate.mjs       CVD-safe / APCA / non-text contrast
+//   · pairing          — pairing-extractor.mjs  derive fg×bg pairings from CSS usage,
+//                        then feed the palette check (coverage without hand-listing)
+//   · typography       — typography-gate.mjs    line-height / spacing / size / weight
+//   · targetSize       — target-size-gate.mjs   interactive target ≥ 24×24 (2.5.8)
+//   · opacity          — opacity-contrast-gate  effective contrast of translucent fg
+//   · likeness         — likeness-gate.mjs      near-duplicate + confusable categoricals
+//
+//   node gates/token-a11y.mjs <token-a11y.json>      # (or $TOKEN_A11Y_CONFIG)
+//
+// CONFIG (every member is OPTIONAL — only declared members run):
+//   { "tokens": "brand/tokens/tokens.css",          // default token map (path or map)
+//     "palette":   { "pairings":[…], "categorical":[…], "thresholds":{…} } | "pairings.json",
+//     "pairing":   { "css":["a.css","b.css"], "declared":"pairings.json", "gate":true,
+//                    "allowlist":true },  // closed-world: `declared` is the opt-in
+//                    // allowlist; any pairing the CSS produces that ISN'T declared is a
+//                    // violation, and declared pairings must pass. Palette envelope is
+//                    // evaluated over the vetted declared set (no surface false-positives).
+//     "typography":{ "tokens":"…", "body":["body"], "thresholds":{…} } | "typo.json",
+//     "targetSize":{ "targets":[…], "thresholds":{…} } | "targets.json",
+//     "opacity":   { "usages":[…], "opacityTokens":{…} } | "usages.json",
+//     "likeness":  { "categorical":[…], "thresholds":{…} } | "likeness.json" }
+//   A member may set its own `tokens` to override the top-level map.
+//   $TOKEN_A11Y_REPORT writes the aggregate JSON report.
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve, dirname, isAbsolute, join } from "node:path";
+import { runPaletteGate } from "./palette-gate.mjs";
+import { runTypographyGate } from "./typography-gate.mjs";
+import { runTargetSizeGate } from "./target-size-gate.mjs";
+import { runOpacityContrastGate } from "./opacity-contrast-gate.mjs";
+import { runLikenessGate } from "./likeness-gate.mjs";
+import { runPairingExtractor } from "./pairing-extractor.mjs";
+
+const MEMBERS = ["palette", "pairing", "typography", "targetSize", "opacity", "likeness"];
+
+/** Resolve a path/config value relative to the config file's directory. */
+function rel(base, p) {
+  if (typeof p !== "string") return p;
+  return isAbsolute(p) ? p : join(base, p);
+}
+
+/**
+ * Run the suite from a parsed config. `base` is the dir paths resolve against.
+ * Returns the aggregate report. Pure-ish (I/O only via the member runners).
+ */
+export async function runTokenA11y(config, base = ".") {
+  const tokens = (m) => rel(base, m?.tokens ?? config.tokens);
+  const members = {};
+  const run = async (name, fn) => { try { members[name] = { ...(await fn()), error: null }; } catch (e) { members[name] = { passed: false, error: String(e.message || e) }; } };
+
+  if (config.palette) {
+    const m = typeof config.palette === "string" ? rel(base, config.palette) : config.palette;
+    await run("palette", () => runPaletteGate({ tokens: tokens(typeof m === "object" ? m : {}), pairings: m }));
+  }
+  if (config.pairing) {
+    const m = config.pairing;
+    await run("pairing", async () => {
+      const r = await runPairingExtractor({
+        tokens: tokens(m), css: (m.css || []).map((c) => rel(base, c)),
+        declared: m.declared ? rel(base, m.declared) : null,
+        allowlist: m.allowlist || false,
+      });
+      // Allowlist (closed-world) gates by default — undeclared pairings are
+      // violations. Extraction-only mode is report-only unless `gate:true`.
+      return (m.allowlist || m.gate) ? r : { ...r, passed: true, gated: false };
+    });
+  }
+  if (config.typography) {
+    const m = typeof config.typography === "string" ? rel(base, config.typography) : config.typography;
+    await run("typography", () => runTypographyGate({ tokens: tokens(typeof m === "object" ? m : {}), config: m }));
+  }
+  if (config.targetSize) {
+    const m = typeof config.targetSize === "string" ? rel(base, config.targetSize) : config.targetSize;
+    await run("targetSize", () => runTargetSizeGate({ config: m }));
+  }
+  if (config.opacity) {
+    const m = typeof config.opacity === "string" ? rel(base, config.opacity) : config.opacity;
+    await run("opacity", () => runOpacityContrastGate({ tokens: tokens(typeof m === "object" ? m : {}), usages: m }));
+  }
+  if (config.likeness) {
+    const m = typeof config.likeness === "string" ? rel(base, config.likeness) : config.likeness;
+    await run("likeness", () => runLikenessGate({ tokens: tokens(typeof m === "object" ? m : {}), config: m }));
+  }
+
+  const ran = Object.keys(members);
+  const failing = ran.filter((k) => members[k].passed === false);
+  return {
+    passed: failing.length === 0,
+    members: Object.fromEntries(MEMBERS.filter((k) => k in members).map((k) => [k, members[k]])),
+    summary: { ran, passed: ran.filter((k) => members[k].passed !== false), failing },
+  };
+}
+
+/** One-line status per member, for the CLI. */
+function memberLine(name, m) {
+  if (m.error) return `  ✗ ${name}: error — ${m.error}`;
+  const s = m.summary || {};
+  const tail =
+    name === "palette" ? `${s.pairs} pair(s), ${s.failingPairs} failing, ${s.categoricalCollapses} collapse(s)`
+    : name === "pairing" ? (m.mode === "allowlist"
+        ? `${s.declared} declared, ${s.undeclared} undeclared, ${s.failingDeclared} failing`
+        : `${s.total} pair(s), ${s.failing} failing${m.gated === false ? " (report-only)" : ""}`)
+    : name === "typography" ? `${s.styles} style(s), ${s.errors} error(s), ${s.warnings} warn(s)`
+    : name === "targetSize" ? `${s.targets} target(s), ${s.belowAA} below AA${m.coverage === "none" ? " (none declared)" : ""}`
+    : name === "opacity" ? `${s.usages} usage(s), ${s.failing} failing`
+    : name === "likeness" ? `${s.nearDuplicates} near-dup(s), ${s.categoricalCollapses} collapse(s)`
+    : "";
+  return `  ${m.passed ? "✓" : "✗"} ${name}: ${tail}`;
+}
+
+async function main() {
+  const argv = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const configPath = argv[0] || process.env.TOKEN_A11Y_CONFIG;
+  if (!configPath) {
+    console.error("✗ token-a11y: usage: token-a11y.mjs <token-a11y.json>  (or set $TOKEN_A11Y_CONFIG)");
+    process.exit(2);
+  }
+  const config = JSON.parse(await readFile(configPath, "utf8"));
+  const report = await runTokenA11y(config, dirname(resolve(configPath)));
+  if (process.env.TOKEN_A11Y_REPORT) await writeFile(resolve(process.env.TOKEN_A11Y_REPORT), JSON.stringify(report, null, 2) + "\n");
+
+  const lines = Object.entries(report.members).map(([k, m]) => memberLine(k, m));
+  const head = `token-a11y: ${report.summary.ran.length} member(s) — ${report.summary.failing.length} failing`;
+  if (!report.passed) { console.error(`✗ ${head}`); for (const l of lines) console.error(l); process.exit(1); }
+  console.log(`✓ ${head}`); for (const l of lines) console.log(l);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ token-a11y: error —", e.stack || e.message); process.exit(1); });
+}