ultra11y 2.22.0

package/src/color.ts

@@ -0,0 +1,102 @@
+// Zero-dependency colour maths for the static contrast check (theme 3). Parses the
+// literal colour values an author can write inline, and computes the WCAG 2.x
+// contrast ratio. Anything non-literal (var(), currentColor, named-but-unknown,
+// gradients) returns null so the engine stays conservative and never invents a NC.
+
+export interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+// The subset of CSS named colours common in hand-written inline styles. Unknown
+// names fall through to null (→ criterion stays a residual risk, not a false NC).
+const NAMED: Record<string, RGBA> = {
+  transparent: { r: 0, g: 0, b: 0, a: 0 },
+  white: { r: 255, g: 255, b: 255, a: 1 },
+  black: { r: 0, g: 0, b: 0, a: 1 },
+  red: { r: 255, g: 0, b: 0, a: 1 },
+  lime: { r: 0, g: 255, b: 0, a: 1 },
+  green: { r: 0, g: 128, b: 0, a: 1 },
+  blue: { r: 0, g: 0, b: 255, a: 1 },
+  yellow: { r: 255, g: 255, b: 0, a: 1 },
+  cyan: { r: 0, g: 255, b: 255, a: 1 },
+  aqua: { r: 0, g: 255, b: 255, a: 1 },
+  magenta: { r: 255, g: 0, b: 255, a: 1 },
+  fuchsia: { r: 255, g: 0, b: 255, a: 1 },
+  silver: { r: 192, g: 192, b: 192, a: 1 },
+  gray: { r: 128, g: 128, b: 128, a: 1 },
+  grey: { r: 128, g: 128, b: 128, a: 1 },
+  maroon: { r: 128, g: 0, b: 0, a: 1 },
+  olive: { r: 128, g: 128, b: 0, a: 1 },
+  purple: { r: 128, g: 0, b: 128, a: 1 },
+  teal: { r: 0, g: 128, b: 128, a: 1 },
+  navy: { r: 0, g: 0, b: 128, a: 1 },
+  orange: { r: 255, g: 165, b: 0, a: 1 },
+};
+
+function hex(part: string): number {
+  return parseInt(part.length === 1 ? part + part : part, 16);
+}
+
+/** Parse a literal CSS colour to RGBA, or null if it isn't a static literal. */
+export function parseColor(input: string): RGBA | null {
+  const s = input.trim().toLowerCase();
+  if (!s) return null;
+  if (s in NAMED) return { ...NAMED[s]! };
+
+  if (s.startsWith("#")) {
+    const h = s.slice(1);
+    if (/^[0-9a-f]{3}$/.test(h)) return { r: hex(h[0]!), g: hex(h[1]!), b: hex(h[2]!), a: 1 };
+    if (/^[0-9a-f]{4}$/.test(h)) return { r: hex(h[0]!), g: hex(h[1]!), b: hex(h[2]!), a: hex(h[3]!) / 255 };
+    if (/^[0-9a-f]{6}$/.test(h)) return { r: hex(h.slice(0, 2)), g: hex(h.slice(2, 4)), b: hex(h.slice(4, 6)), a: 1 };
+    if (/^[0-9a-f]{8}$/.test(h)) return { r: hex(h.slice(0, 2)), g: hex(h.slice(2, 4)), b: hex(h.slice(4, 6)), a: hex(h.slice(6, 8)) / 255 };
+    return null;
+  }
+
+  const m = /^rgba?\(([^)]+)\)$/.exec(s);
+  if (m) {
+    const parts = m[1]!.split(/[,/\s]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const chan = (p: string): number => (p.endsWith("%") ? Math.round((parseFloat(p) / 100) * 255) : parseFloat(p));
+    const r = chan(parts[0]!);
+    const g = chan(parts[1]!);
+    const b = chan(parts[2]!);
+    const a = parts[3] !== undefined ? (parts[3].endsWith("%") ? parseFloat(parts[3]) / 100 : parseFloat(parts[3])) : 1;
+    if ([r, g, b, a].some((n) => Number.isNaN(n))) return null;
+    return { r, g, b, a };
+  }
+  return null;
+}
+
+function channelLuminance(c: number): number {
+  const cs = c / 255;
+  return cs <= 0.03928 ? cs / 12.92 : ((cs + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG relative luminance of an opaque colour. */
+export function relativeLuminance({ r, g, b }: RGBA): number {
+  return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b);
+}
+
+/** WCAG 2.x contrast ratio between two opaque colours (1 … 21). */
+export function contrastRatio(a: RGBA, b: RGBA): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Split an inline `style` attribute into a lowercased property → value map. */
+export function parseInlineStyle(style: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const decl of style.split(";")) {
+    const i = decl.indexOf(":");
+    if (i === -1) continue;
+    const prop = decl.slice(0, i).trim().toLowerCase();
+    const val = decl.slice(i + 1).trim();
+    if (prop && val) out.set(prop, val);
+  }
+  return out;
+}

package/src/config.ts

@@ -0,0 +1,182 @@
+// Runtime configuration so external standards PACKS + GUIDANCE can be plugged WITHOUT
+// rebuilding the bundle. Two explicit sources — no fs glob, no auto-discovery walk:
+//   • a `.ultra11yrc.json` in the cwd: { packs?: string[]; guidance?: string[]; standard?: string }
+//   • repeated/comma-separated `--pack <path>` flags on the CLI
+// A pack path is either a pack JSON file, or a directory holding pack.json (+ optional
+// glossary.json / guidance.json). Every pack is run through `validatePack` before it is
+// registered (src/standards/validate.ts); an invalid pack is a HARD error returned to the
+// caller, never a silent skip.
+import { existsSync, statSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { readText } from "./util.js";
+import { registerRuntimePack, getPack, enableSecondaryMapping } from "./standards/registry.js";
+import { formatIssues } from "./standards/validate.js";
+import { checkGuidance } from "./pack.js";
+import { registerRuntimeGuidance, hasGuidance } from "./guidance/index.js";
+import type { GuidanceDataset } from "./guidance/types.js";
+import type { LocaleString } from "./standards/types.js";
+import type { Glossary, SampleConfig } from "./types.js";
+
+export interface Ultra11yConfig {
+  packs?: string[];
+  guidance?: string[];
+  standard?: string;
+  // Normative page sample (échantillon) — standard-agnostic mechanics. Validated by
+  // `validateSample` (src/sample.ts) when a `scan --sample` / `sample check` reads it; NOT
+  // validated at pack-load time (an audit with no sample block is the common case).
+  sample?: SampleConfig;
+  // Opt-in SECONDARY crosswalk mappings to activate (see src/standards/types.ts
+  // SecondaryMapping). Each entry names a registered `standard` (pack key), a `ruleId`, and
+  // the additional `criterion` it should also project onto, with an optional localized
+  // `note`. Applied AFTER packs are registered (registry.enableSecondaryMapping): a pack
+  // ships the mapping DISABLED; this flips it on (or appends a new enabled one).
+  secondaryMappings?: Array<{ standard: string; ruleId: string; criterion: string; note?: LocaleString }>;
+}
+
+export interface LoadResult {
+  defaultStandard?: string; // config.standard, if set (applied when no --standard flag)
+  errors: string[]; // fatal: a bad config or an invalid pack
+  loadedPacks: string[];
+  loadedGuidance: string[];
+}
+
+const CONFIG_FILE = ".ultra11yrc.json";
+
+export function loadConfig(cwd: string): Ultra11yConfig | null {
+  const p = join(cwd, CONFIG_FILE);
+  if (!existsSync(p)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readText(p));
+  } catch {
+    throw new Error(`${CONFIG_FILE}: not valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${CONFIG_FILE}: must be a JSON object`);
+  }
+  return parsed as Ultra11yConfig;
+}
+
+/** A --pack path: a .json file IS the pack; a directory holds pack.json (+ optional
+ *  glossary.json / guidance.json). Returns the resolved file paths, or null if absent. */
+function packPaths(path: string): { pack: string; glossary?: string; guidance?: string } | null {
+  if (!existsSync(path)) return null;
+  if (statSync(path).isDirectory()) {
+    const pack = join(path, "pack.json");
+    if (!existsSync(pack)) return null;
+    const glossary = join(path, "glossary.json");
+    const guidance = join(path, "guidance.json");
+    return {
+      pack,
+      glossary: existsSync(glossary) ? glossary : undefined,
+      guidance: existsSync(guidance) ? guidance : undefined,
+    };
+  }
+  return { pack: path };
+}
+
+/** Load + register every configured/flagged pack (and its guidance) into the registries.
+ *  Must run BEFORE any `resolveStandard`/`loadPack` so a runtime pack is resolvable. */
+export function loadRuntimeStandards(cwd: string, packFlags: string[], onWarn: (m: string) => void, override = false): LoadResult {
+  const result: LoadResult = { errors: [], loadedPacks: [], loadedGuidance: [] };
+  let config: Ultra11yConfig | null = null;
+  try {
+    config = loadConfig(cwd);
+  } catch (e) {
+    result.errors.push(e instanceof Error ? e.message : String(e));
+    return result;
+  }
+  result.defaultStandard = config?.standard;
+
+  for (const raw of [...(config?.packs ?? []), ...packFlags]) {
+    // Relative pack paths resolve against the working dir (= the config dir), not the
+    // process cwd, so `.ultra11yrc.json` entries work regardless of where node runs.
+    const paths = packPaths(isAbsolute(raw) ? raw : join(cwd, raw));
+    if (!paths) {
+      result.errors.push(`--pack ${raw}: not found (expected a pack JSON file or a directory with pack.json)`);
+      continue;
+    }
+    let packObj: unknown;
+    try {
+      packObj = JSON.parse(readText(paths.pack));
+    } catch {
+      result.errors.push(`--pack ${paths.pack}: not valid JSON`);
+      continue;
+    }
+    let glossary: Glossary = {};
+    if (paths.glossary) {
+      try {
+        glossary = JSON.parse(readText(paths.glossary)) as Glossary;
+      } catch {
+        onWarn(`ultra11y: ${paths.glossary} is not valid JSON — ignoring glossary.`);
+      }
+    }
+    const v = registerRuntimePack(packObj, glossary, { override });
+    for (const issue of v.issues) if (issue.severity === "warn") onWarn(`ultra11y: ${raw}: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`);
+    if (!v.ok || !v.pack) {
+      result.errors.push(`--pack ${paths.pack}: invalid pack\n${formatIssues(v.issues).join("\n")}`);
+      continue;
+    }
+    result.loadedPacks.push(v.pack.key);
+    if (paths.guidance) loadGuidanceFile(paths.guidance, result, onWarn);
+  }
+
+  for (const g of config?.guidance ?? []) loadGuidanceFile(isAbsolute(g) ? g : join(cwd, g), result, onWarn);
+
+  // Activate any opt-in secondary crosswalk mappings — AFTER every pack is registered, so a
+  // mapping can target a built-in (rgaa) OR a just-loaded runtime pack. An unknown standard
+  // (or the WCAG core, which has no pack criteria) is a hard error, never a silent skip.
+  for (const sm of config?.secondaryMappings ?? []) {
+    if (!sm || typeof sm.standard !== "string" || typeof sm.ruleId !== "string" || typeof sm.criterion !== "string") {
+      result.errors.push("secondaryMappings: each entry must be { standard, ruleId, criterion, note? }");
+      continue;
+    }
+    if (!getPack(sm.standard)) {
+      result.errors.push(`secondaryMappings: unknown standard "${sm.standard}" (register its pack first; the WCAG core has no pack criteria)`);
+      continue;
+    }
+    enableSecondaryMapping(sm.standard, { ruleId: sm.ruleId, criterion: sm.criterion, note: sm.note });
+  }
+
+  return result;
+}
+
+function loadGuidanceFile(path: string, result: LoadResult, onWarn: (m: string) => void): void {
+  if (!existsSync(path)) {
+    onWarn(`ultra11y: guidance ${path} not found — skipping.`);
+    return;
+  }
+  let ds: GuidanceDataset;
+  try {
+    ds = JSON.parse(readText(path)) as GuidanceDataset;
+  } catch {
+    onWarn(`ultra11y: guidance ${path} is not valid JSON — skipping.`);
+    return;
+  }
+  if (!ds || typeof ds.pack !== "string" || !Array.isArray(ds.entries)) {
+    onWarn(`ultra11y: guidance ${path} is not a valid dataset (needs { pack, entries[] }) — skipping.`);
+    return;
+  }
+  // Gate runtime guidance the SAME way `pack check` does, so fabrication can't sneak in via
+  // the load path (a bogus criterionId / SC, or a malformed entry, is a hard error — never a
+  // silent register). When the augmented pack isn't loaded, fall back to a structural check.
+  const pack = getPack(ds.pack);
+  if (pack) {
+    const g = checkGuidance(ds, pack);
+    for (const w of g.warnings) onWarn(`ultra11y: guidance ${path}: ${w}`);
+    if (g.errors.length) {
+      result.errors.push(`guidance ${path}: invalid\n${g.errors.map((e) => `  ✗ ${e}`).join("\n")}`);
+      return;
+    }
+  } else {
+    for (const e of ds.entries) {
+      if (!Array.isArray(e?.wcag) || !Array.isArray(e?.examples)) {
+        onWarn(`ultra11y: guidance ${path}: entry "${e?.id ?? "?"}" missing wcag[]/examples[] — skipping dataset.`);
+        return;
+      }
+    }
+  }
+  if (hasGuidance(ds.pack)) onWarn(`ultra11y: guidance ${path} overrides the existing guidance for pack "${ds.pack}".`);
+  registerRuntimeGuidance(ds);
+  result.loadedGuidance.push(path);
+}

package/src/crawl.ts

@@ -0,0 +1,75 @@
+// Zero-dependency page discovery for the dynamic tier: turn one entry point into
+// the set of URLs to scan, either from a sitemap.xml or by breadth-first crawling
+// the same-origin links found in the SERVED HTML. The latter sees links present in
+// the response body (SSR/MPA); pure client-rendered SPA routes should come from a
+// sitemap instead. The actual axe run per URL stays in the Docker tier (scan.ts).
+
+/** Pull every `<loc>` value out of a sitemap.xml (urlset or sitemapindex). */
+export function parseSitemapUrls(xml: string): string[] {
+  const out: string[] = [];
+  const re = /<loc>\s*([^<]+?)\s*<\/loc>/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(xml)) !== null) out.push(m[1]!);
+  return out;
+}
+
+/** Same-origin, hash-stripped, de-duplicated absolute links from a page's HTML. */
+export function extractLinks(html: string, baseUrl: string): string[] {
+  const origin = new URL(baseUrl).origin;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const re = /<a\b[^>]*\bhref\s*=\s*["']([^"']+)["']/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(html)) !== null) {
+    const href = m[1]!.trim();
+    if (!href || href.startsWith("#")) continue; // pure fragment → current page
+    let abs: URL;
+    try {
+      abs = new URL(href, baseUrl);
+    } catch {
+      continue;
+    }
+    if (abs.protocol !== "http:" && abs.protocol !== "https:") continue; // mailto/tel/js
+    if (abs.origin !== origin) continue;
+    abs.hash = "";
+    const url = abs.href;
+    if (seen.has(url)) continue;
+    seen.add(url);
+    out.push(url);
+  }
+  return out;
+}
+
+export interface CrawlOpts {
+  fetchHtml: (url: string) => Promise<string>;
+  depth?: number;
+  max?: number;
+}
+
+/** Breadth-first crawl from `start`, following same-origin links in served HTML.
+ *  Visits the start URL first; bounded by `depth` (link hops) and `max` (pages). */
+export async function crawlUrls(start: string, opts: CrawlOpts): Promise<string[]> {
+  const depth = opts.depth ?? 1;
+  const max = opts.max ?? 50;
+  const order: string[] = [];
+  const seen = new Set<string>([start]);
+  const queue: { url: string; d: number }[] = [{ url: start, d: 0 }];
+
+  while (queue.length > 0 && order.length < max) {
+    const { url, d } = queue.shift()!;
+    order.push(url);
+    if (d >= depth) continue;
+    let html = "";
+    try {
+      html = await opts.fetchHtml(url);
+    } catch {
+      continue;
+    }
+    for (const link of extractLinks(html, url)) {
+      if (seen.has(link)) continue;
+      seen.add(link);
+      queue.push({ url: link, d: d + 1 });
+    }
+  }
+  return order;
+}

package/src/criteria.ts

@@ -0,0 +1,183 @@
+// `criteria` — offline reference lookup. The CORE reference is WCAG 2.2 AA: one
+// success criterion (`criteria 1.4.3`), or the full list grouped by guideline
+// (`criteria --list`). A country pack adds `--standard <pack>`: one pack criterion
+// (`criteria --standard rgaa 8.3`), a pack theme (`--theme N`), or the theme list.
+// Also generates references/criteria.md (never hand-edited).
+import type { Lang, Sc } from "./types.js";
+import { allSC, allGuidelines, allPrinciples, getSC, scsByGuideline, principleTitle, guidelineTitle, scTitle, meta } from "./wcag.js";
+import {
+  type StandardId,
+  isCore,
+  loadPack,
+  listPacks,
+  packsForSc,
+  getCriterion as getPackCriterion,
+  listTheme as listPackTheme,
+  titlePlain as packTitlePlain,
+  themeName,
+  type StandardPack,
+  type PackCriterion,
+} from "./standards/index.js";
+
+const AUTO_LABEL: Record<string, { fr: string; en: string }> = {
+  static: { fr: "automatisable (moteur)", en: "automatable (engine)" },
+  "needs-rendering": { fr: "nécessite un rendu (tiers scan)", en: "needs rendering (scan tier)" },
+  judgment: { fr: "jugement de l'agent (gaté)", en: "agent judgment (gated)" },
+};
+
+// ---- WCAG core formatting -------------------------------------------------
+
+export function formatSC(c: Sc, lang: Lang = "en"): string {
+  const out: string[] = [];
+  out.push(`${c.sc} — ${scTitle(c.sc, lang) ?? c.title} (${c.level}, ${lang === "fr" ? "ajouté en" : "added in"} WCAG ${c.addedIn})`);
+  const auto = AUTO_LABEL[c.automatability]![lang];
+  const gl = guidelineTitle(c.guideline, lang) ?? "";
+  const pr = principleTitle(c.principle, lang) ?? "";
+  out.push(
+    `${lang === "fr" ? "Règle" : "Guideline"} ${c.guideline} (${gl}) · ${lang === "fr" ? "principe" : "principle"} ${c.principle} (${pr}) · ${lang === "fr" ? "automatisabilité" : "automatability"} : ${auto}${c.ruleIds.length ? ` · ${lang === "fr" ? "règles" : "rules"} : ${c.ruleIds.join(", ")}` : ""}`,
+  );
+  out.push(`${lang === "fr" ? "Comprendre" : "Understanding"} : ${c.understanding}`);
+  if (c.techniques?.length) out.push(`Techniques : ${c.techniques.join(", ")}`);
+  const packs = packsForSc(c.sc);
+  if (packs.length)
+    out.push(`${lang === "fr" ? "Référencé par" : "Mapped by"} : ${packs.map((p) => `${p.key.toUpperCase()} ${p.ids.join(", ")}`).join(" · ")}`);
+  return out.join("\n");
+}
+
+function wcagList(lang: Lang): string {
+  const m = meta();
+  const out: string[] = [];
+  out.push(
+    lang === "fr"
+      ? `WCAG ${m.wcagVersion} niveau ${m.level} — ${allPrinciples().length} principes, ${allGuidelines().length} règles, ${allSC().length} critères de succès`
+      : `WCAG ${m.wcagVersion} Level ${m.level} — ${allPrinciples().length} principles, ${allGuidelines().length} guidelines, ${allSC().length} success criteria`,
+  );
+  const byG = scsByGuideline();
+  for (const g of allGuidelines()) {
+    out.push(`${g.number} ${guidelineTitle(g.number, lang) ?? g.title}`);
+    for (const c of byG.get(g.number) ?? []) out.push(`  ${c.sc.padEnd(8)} [${c.level.padEnd(2)}] ${scTitle(c.sc, lang) ?? c.title}  [${c.automatability}]`);
+  }
+  return out.join("\n");
+}
+
+// ---- pack formatting ------------------------------------------------------
+
+export function formatPackCriterion(pack: StandardPack, c: PackCriterion, lang: Lang = "en"): string {
+  const out: string[] = [];
+  out.push(`${pack.name} ${c.id} — ${packTitlePlain(pack, c, lang)}`);
+  out.push(`${lang === "fr" ? "Thématique" : "Theme"} ${c.theme} (${themeName(pack, c.theme, lang) ?? ""}) · WCAG : ${c.wcag.join(", ") || "—"}`);
+  if (c.techniques?.length) out.push(`Techniques : ${c.techniques.join(", ")}`);
+  const testKeys = Object.keys(c.tests ?? {});
+  if (testKeys.length) {
+    out.push(`${lang === "fr" ? "Tests" : "Tests"} :`);
+    for (const k of testKeys) for (const line of c.tests![k]!) out.push(`  ${c.id}.${k} ${line.replace(/\[([^\]]+)\]\(#[^)]*\)/g, "$1")}`);
+  }
+  if (c.technicalNote?.length) out.push(`${lang === "fr" ? "Note technique" : "Technical note"} : ${c.technicalNote.join(" ")}`);
+  if (c.particularCases?.length) out.push(`${lang === "fr" ? "Cas particuliers" : "Particular cases"} : ${c.particularCases.join(" ")}`);
+  return out.join("\n");
+}
+
+function packThemeList(pack: StandardPack, lang: Lang): string {
+  const out: string[] = [];
+  out.push(
+    `${pack.name} ${pack.baseVersion} — ${pack.themes.length} ${lang === "fr" ? "thématiques" : "themes"}, ${pack.criteria.length} ${lang === "fr" ? "critères" : "criteria"}`,
+  );
+  for (const t of pack.themes) {
+    out.push(
+      `${String(t.number).padStart(2)}. ${(themeName(pack, t.number, lang) ?? "").padEnd(32).slice(0, 32)} ${String(t.count).padStart(3)} ${lang === "fr" ? "critères" : "criteria"}`,
+    );
+  }
+  return out.join("\n");
+}
+
+// ---- query + run ----------------------------------------------------------
+
+export interface CriteriaOpts {
+  id?: string;
+  theme?: number;
+  list?: boolean;
+  json?: boolean;
+  lang: Lang;
+  standard: StandardId;
+}
+
+function runWcag(opts: CriteriaOpts): number {
+  if (opts.id) {
+    const sc = getSC(opts.id);
+    if (!sc) {
+      console.error(`ultra11y criteria: unknown WCAG success criterion "${opts.id}".`);
+      return 2;
+    }
+    console.log(opts.json ? JSON.stringify(sc, null, 2) : formatSC(sc, opts.lang));
+    return 0;
+  }
+  if (typeof opts.theme === "number") {
+    console.error(
+      `ultra11y criteria: WCAG has no themes; use --list (grouped by guideline) or a success-criterion id, or pass --standard <pack> for a pack's themes.`,
+    );
+    return 2;
+  }
+  console.log(opts.json ? JSON.stringify(allSC(), null, 2) : wcagList(opts.lang));
+  return 0;
+}
+
+function runPack(opts: CriteriaOpts): number {
+  const pack = loadPack(opts.standard);
+  if (opts.id) {
+    const c = getPackCriterion(pack, opts.id);
+    if (!c) {
+      console.error(`ultra11y criteria: unknown ${pack.name} criterion "${opts.id}".`);
+      return 2;
+    }
+    console.log(opts.json ? JSON.stringify(c, null, 2) : formatPackCriterion(pack, c, opts.lang));
+    return 0;
+  }
+  if (typeof opts.theme === "number") {
+    const crits = listPackTheme(pack, opts.theme);
+    if (!crits.length) {
+      console.error(`ultra11y criteria: unknown ${pack.name} theme "${opts.theme}".`);
+      return 2;
+    }
+    if (opts.json) console.log(JSON.stringify(crits, null, 2));
+    else for (const c of crits) console.log(`${c.id}\t${packTitlePlain(pack, c, opts.lang)}\t→ WCAG ${c.wcag.join(", ")}`);
+    return 0;
+  }
+  console.log(opts.json ? JSON.stringify(pack.themes, null, 2) : packThemeList(pack, opts.lang));
+  return 0;
+}
+
+export function runCriteria(opts: CriteriaOpts): number {
+  return isCore(opts.standard) ? runWcag(opts) : runPack(opts);
+}
+
+/** Generate the references/criteria.md doc bundled with the skill (WCAG 2.2 AA core). */
+export function renderCriteriaReference(): string {
+  const out: string[] = [];
+  out.push("<!-- GENERATED from src/data/wcag.json by `ultra11y criteria --generate` — do not edit by hand. -->");
+  out.push("");
+  out.push("# WCAG 2.2 Level AA — success-criteria reference");
+  out.push("");
+  out.push("The 55 Level A + AA success criteria across the 4 principles / 13 guidelines, with each");
+  out.push("SC's level, the ultra11y automatability class (automatable / needs rendering / judgment),");
+  out.push("the engine rules that cover it, and — one column per registered standards pack — the pack");
+  out.push("criteria that map to it. SC ids, titles and levels are derived from the W3C source");
+  out.push("(https://github.com/w3c/wcag); WCAG 2.2 © W3C.");
+  out.push("");
+  const packs = listPacks();
+  const byG = scsByGuideline();
+  for (const g of allGuidelines()) {
+    out.push(`## ${g.number} ${g.title}`);
+    out.push("");
+    const head = ["SC", "Title", "Level", "Automatability", "Rules", ...packs.map((p) => p.name)];
+    out.push(`| ${head.join(" | ")} |`);
+    out.push(`|${"---|".repeat(head.length)}`);
+    for (const c of byG.get(g.number) ?? []) {
+      const hits = packsForSc(c.sc);
+      const packCols = packs.map((p) => hits.find((h) => h.key === p.key)?.ids.join(", ") ?? "—");
+      const row = [c.sc, c.title.replace(/\|/g, "\\|"), c.level, c.automatability, c.ruleIds.join(", ") || "—", ...packCols];
+      out.push(`| ${row.join(" | ")} |`);
+    }
+    out.push("");
+  }
+  return out.join("\n");
+}