ultra11y 4.3.0 → 4.4.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "4.3.0",
+      "version": "4.4.1",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "4.3.0";
+const ULTRA11Y_PLUGIN_VERSION = "4.4.1";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -196,15 +196,15 @@ the one output an accessibility tool must never produce.
 
 ### Tools
 
-Eleven read tools. `ultra11y_audit` is the entry point:
+Sixteen read tools, in two blocks. **The audit block** tells you what the page does:
 
 | Tool | What it does |
 |------|--------------|
 | `ultra11y_audit` | The static pass — findings keyed by success criterion |
 | `ultra11y_adjudicate` | The criteria the engine **cannot** decide, with their evidence |
-| `ultra11y_criteria` | The offline standards reference — look a criterion up, don't recall it |
 | `ultra11y_report` | The dated conformance report, WCAG or a country pack |
 | `ultra11y_prd` | Non-conformities → remediation units with effort |
+| `ultra11y_tickets` | The same backlog as a ticket plan — dry-run, files nothing |
 | `ultra11y_check` | The gate: nothing asserted conformant that was never tested |
 | `ultra11y_verify` | Claim↔evidence worklist |
 | `ultra11y_pack_check` | Validate a country standards pack against what it really ships |
@@ -212,6 +212,28 @@ Eleven read tools. `ultra11y_audit` is the entry point:
 | `ultra11y_pages` | The per-page view: the criterion × page grid, or one dossier per page |
 | `ultra11y_read` | A file, or a line range, from the project |
 
+**The reference block** tells you what the standard requires — the half that keeps an agent
+from auditing out of memory. `cwd` is optional on all five; it selects whose packs are visible:
+
+| Tool | What it does |
+|------|--------------|
+| `ultra11y_standards` | Which standards exist here, and how much of each any engine can decide |
+| `ultra11y_criteria` | One criterion in full — wording, **numbered tests**, techniques, mapping, defined terms — or the index, or one theme |
+| `ultra11y_glossary` | What a term the standard **defines** means, and which criteria it governs |
+| `ultra11y_guidance` | The before/after implementation pattern, inherited through the WCAG mapping when the pack has none |
+| `ultra11y_method` | The work plan: what the engine settles, what needs a render, what is yours |
+
+`ultra11y_method` is the one to call first. It partitions the standard into evidence tiers —
+`source`, `cross-file`, `rendered-page`, `browser`, `judgment`, `out-of-scope` — from the
+engine's own per-criterion rule applicability, never from guessing at the wording of a test.
+For RGAA it reports that **58 of 106 criteria declare that no engine rule can evidence them**.
+That is the standard saying they are yours, and a plan that hides it reads as coverage that
+does not exist.
+
+`standard` carries no enum, deliberately: a country pack arrives with a project, so an enum
+pinned when the tool list was built would reject a pack that is perfectly valid for the
+project being asked about. The handler validates against the registry and names what it knows.
+
 `--allow-write` additionally exposes `ultra11y_fix` (safe codemods, dry-run by
 default) and `ultra11y_init` (hook/CI/baseline) — the tools that change **your**
 project. `ultra11y_scan` is declared but declines over MCP: it drives a headless
@@ -237,12 +259,26 @@ Each carries the coverage arithmetic: of the 55 WCAG 2.2 AA criteria the static
 engine decides a handful, a browser decides fourteen, and **thirty-eight are
 yours**.
 
-### Resources — the skill's own documentation
+### Resources — the documentation, and the standards themselves
 
-`SKILL.md` and all 32 `references/*.md` are served under `skill://`, read off
+`SKILL.md` and all 37 `references/*.md` are served under `skill://`, read off
 disk at request time — so a documentation fix reaches every client without a
 rebuild.
 
+The standards are served too, under `std://`, because in MCP documentation is a
+*resource*, not a tool call:
+
+```
+std://rgaa/criteria/8.3      std://rgaa/glossary/lien      std://rgaa/method
+std://rgaa/themes/8          std://rgaa/guidance/13.2      std://rgaa/pack.json
+std://wcag/criteria/1.4.3    std://wcag/glossary           std://wcag/method
+```
+
+`resources/list` carries a bounded index per standard; the per-item URIs are
+**templates** (`resources/templates/list`), because enumerating RGAA's 106
+criteria and 119 glossary terms would bloat every client's listing and go stale
+the moment a project's own pack registers.
+
 Two things worth knowing:
 
 - **A criterion nobody tested is untested, never conformant.** Every tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
@@ -58,6 +58,8 @@
     "build:wcag": "node scripts/build-standards.mjs",
     "build:pack:rgaa": "node scripts/build-pack-rgaa.mjs",
     "check:pack:rgaa": "node scripts/build-pack-rgaa.mjs --check",
+    "build:guidance:wcag": "node scripts/build-guidance-wcag.mjs",
+    "check:guidance:wcag": "node scripts/build-guidance-wcag.mjs --check",
     "build:criteria": "node scripts/ultra11y.mjs criteria --generate > skills/ultra11y/references/criteria.md",
     "build:act": "UPDATE_ACT_MATRIX=1 vitest run tests/act-matrix-sync.test.ts",
     "build:act:refresh": "node scripts/build-act-corpus.mjs --refresh",

package/scripts/build-guidance-wcag.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// DEV-ONLY (not in `bin`). Builds src/data/guidance/wcag.json — the WCAG-keyed
+// implementation guidance — from the W3C's own Techniques and Understanding documents.
+//
+// Nothing here is hand-written. The RGAA guidance is derived from an upstream rule source
+// and rebuilt by a script; this one had been authored by hand, which made it the only
+// dataset in the repo whose content nobody could re-derive or check against a source. Now
+// it is generated the same way everything else is:
+//
+//   · WHICH techniques implement a criterion — understanding/understanding.11tydata.js,
+//     the W3C's own machine-readable association map (sufficient / advisory / failure).
+//   · WHAT the criterion asks — the "In brief" block of understanding/<ver>/<slug>.html
+//     (Goal / What to do / Why it's important), written by the WCAG working group.
+//   · The GOOD example — the first sufficient technique carrying an HTML or CSS code
+//     sample, in the W3C's own listing order.
+//   · The BAD example — the first documented FAILURE carrying one.
+//
+// The selection is positional, never editorial: "the first one that has a code sample",
+// in the order W3C lists them. A criterion whose techniques carry no HTML/CSS sample gets
+// an entry with the official summary and no example, rather than an invented one.
+//
+// WCAG 2.2 © W3C, reused under the W3C Document License; the code samples are Code
+// Components under the W3C Software License. See NOTICE.
+//
+// Usage:
+//   node scripts/build-guidance-wcag.mjs --refresh   # re-fetch (network) the vendored snapshot
+//   node scripts/build-guidance-wcag.mjs             # emit the dataset from the snapshot
+//   node scripts/build-guidance-wcag.mjs --check     # verify the committed dataset matches
+import { writeFileSync, readFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const VENDOR = join(root, "scripts", "vendor", "wcag-2.2-techniques.json");
+const SNAPSHOT = join(root, "scripts", "vendor", "wcag-2.2-sc.json");
+const OUT = join(root, "src", "data", "guidance", "wcag.json");
+const BIOME = join(root, "node_modules", ".bin", "biome");
+const RAW = "https://raw.githubusercontent.com/w3c/wcag/main";
+const VER_OF = { "2.0": "20", "2.1": "21", "2.2": "22" };
+
+// Technique id → the directory it lives in. The W3C names these by technology, and the
+// prefix is the technology — no directory listing needed, and no id ever special-cased.
+const TECH_DIR = {
+  ARIA: "aria",
+  C: "css",
+  F: "failures",
+  FLASH: "flash",
+  G: "general",
+  H: "html",
+  PDF: "pdf",
+  SCR: "client-side-script",
+  SL: "silverlight",
+  SM: "smil",
+  SVR: "server-side-script",
+  T: "text",
+};
+
+function techDir(id) {
+  const prefix = (id.match(/^[A-Z]+/) || [])[0];
+  return TECH_DIR[prefix];
+}
+
+function biomeFormat(text, relPath) {
+  return execFileSync(BIOME, ["format", `--stdin-file-path=${relPath}`], { input: text, encoding: "utf8" });
+}
+
+async function fetchText(path) {
+  const r = await fetch(`${RAW}/${path}`);
+  if (!r.ok) return null; // a technique listed but not present is data, not a crash
+  return r.text();
+}
+
+const ENTITIES = {
+  "&nbsp;": " ",
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&apos;": "'",
+  "&rsquo;": "’",
+  "&lsquo;": "‘",
+  "&ldquo;": "“",
+  "&rdquo;": "”",
+  "&mdash;": "—",
+  "&ndash;": "–",
+  "&hellip;": "…",
+};
+function decodeEntities(s) {
+  return s
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(Number.parseInt(h, 16)))
+    .replace(/&[a-z]+;/gi, (m) => ENTITIES[m] ?? m);
+}
+
+/** Tags out, entities in, whitespace collapsed — for prose, never for code. */
+function plain(html) {
+  return decodeEntities(html.replace(/<[^>]+>/g, " "))
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * The W3C's own association map, read by EVALUATING the module rather than regexing it.
+ *
+ * It is an ES module exporting a function of 11ty's data cascade; calling it with a stub
+ * yields the map exactly as the W3C's own site build sees it. Parsing this shape with a
+ * regex would be guesswork, and it is dev-only code from the same repo this project already
+ * derives its entire WCAG dataset from.
+ */
+async function fetchAssociations() {
+  const src = await fetchText("understanding/understanding.11tydata.js");
+  if (!src) throw new Error("build-guidance-wcag: understanding.11tydata.js not found upstream");
+  const tmp = join(tmpdir(), `u11y-assoc-${process.pid}.mjs`);
+  writeFileSync(tmp, src);
+  try {
+    const mod = await import(`file://${tmp}`);
+    return mod.default({ understandingUrl: "" }).associatedTechniques ?? {};
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** Every technique id an entry mentions, flattened, in the W3C's own listing order. */
+function flattenTechniques(node, out = []) {
+  if (node === null || node === undefined) return out;
+  if (typeof node === "string") {
+    // Ids only: the map also carries free prose ("Providing a descriptive label").
+    if (/^[A-Z]+\d+$/.test(node)) out.push(node);
+    return out;
+  }
+  if (Array.isArray(node)) {
+    for (const n of node) flattenTechniques(n, out);
+    return out;
+  }
+  if (typeof node === "object") {
+    // { and: [...] } / { title, techniques, groups } — order matters, so walk explicitly.
+    for (const key of ["and", "techniques", "groups", "using"]) {
+      if (node[key]) flattenTechniques(node[key], out);
+    }
+    return out;
+  }
+  return out;
+}
+
+/** The first HTML or CSS code sample in a technique document, with the prose above it. */
+function firstCodeExample(html) {
+  const EX = /<section class="example">([\s\S]*?)<\/section>/g;
+  let m;
+  while ((m = EX.exec(html))) {
+    const block = m[1];
+    const code = /<pre><code class="language-(html|css)">([\s\S]*?)<\/code><\/pre>/.exec(block);
+    if (!code) continue;
+    const snippet = decodeEntities(code[2]).trim();
+    if (!snippet) continue;
+    const before = block.slice(0, code.index);
+    return { lang: code[1], code: snippet, note: plain(before) };
+  }
+  return null;
+}
+
+function techniqueTitle(html) {
+  const h1 = /<h1>([\s\S]*?)<\/h1>/.exec(html);
+  return h1 ? plain(h1[1]) : "";
+}
+
+/** The "In brief" block: the working group's own Goal / What to do / Why. */
+function briefOf(html) {
+  const sec = /<section id="brief">([\s\S]*?)<\/section>/.exec(html);
+  if (!sec) return null;
+  const out = {};
+  const DL = /<dt>([\s\S]*?)<\/dt>\s*<dd>([\s\S]*?)<\/dd>/g;
+  let m;
+  while ((m = DL.exec(sec[1]))) out[plain(m[1]).toLowerCase().replace(/[^a-z]+/g, "")] = plain(m[2]);
+  return Object.keys(out).length ? out : null;
+}
+
+async function refresh() {
+  if (!existsSync(SNAPSHOT)) {
+    console.error(`build-guidance-wcag --refresh: missing ${SNAPSHOT}. Run: node scripts/build-standards.mjs --refresh <w3c/wcag checkout>`);
+    process.exit(1);
+  }
+  const snap = JSON.parse(readFileSync(SNAPSHOT, "utf8"));
+  const assoc = await fetchAssociations();
+
+  const cache = new Map();
+  const techniqueDoc = async (id) => {
+    if (cache.has(id)) return cache.get(id);
+    const dir = techDir(id);
+    const doc = dir ? await fetchText(`techniques/${dir}/${id}.html`) : null;
+    cache.set(id, doc);
+    return doc;
+  };
+
+  const criteria = {};
+  for (const c of snap.criteria) {
+    const a = assoc[c.slug];
+    const understanding = await fetchText(`understanding/${VER_OF[c.addedIn]}/${c.slug}.html`);
+    const brief = understanding ? briefOf(understanding) : null;
+
+    // Selection: the first technique that carries a code sample, taking the technologies in
+    // a fixed order rather than purely positionally.
+    //
+    // Order matters because the W3C lists techniques by conformance strategy, not by how
+    // well they READ as an example. For 1.1.1 the first listed with a sample is ARIA6,
+    // whose own example is a navigation landmark — true to the technique, useless as an
+    // illustration of a text alternative. Preferring HTML picks H37 (`alt` on `img`)
+    // instead. This is one uniform rule applied to every criterion, not a per-criterion
+    // choice: within a technology the W3C's own order still decides.
+    const TECH_ORDER = ["html", "css", "aria", "client-side-script", "general", "text"];
+    const pick = async (ids) => {
+      const byTech = new Map();
+      for (const id of ids) {
+        const dir = techDir(id);
+        if (!dir) continue;
+        if (!byTech.has(dir)) byTech.set(dir, []);
+        byTech.get(dir).push(id);
+      }
+      const ordered = [...TECH_ORDER.flatMap((t) => byTech.get(t) ?? []), ...ids.filter((id) => !TECH_ORDER.includes(techDir(id)))];
+      for (const id of ordered) {
+        const doc = await techniqueDoc(id);
+        if (!doc) continue;
+        const ex = firstCodeExample(doc);
+        if (ex) return { id, title: techniqueTitle(doc), ...ex };
+      }
+      return null;
+    };
+
+    const good = a ? await pick(flattenTechniques(a.sufficient)) : null;
+    const bad = a ? await pick(flattenTechniques(a.failure)) : null;
+
+    criteria[c.sc] = {
+      slug: c.slug,
+      ...(brief ? { brief } : {}),
+      ...(good ? { good } : {}),
+      ...(bad ? { bad } : {}),
+    };
+  }
+
+  const out = {
+    source: "https://github.com/w3c/wcag",
+    understanding: "https://www.w3.org/WAI/WCAG22/Understanding/",
+    license: "W3C Document License (code samples: W3C Software License)",
+    fetchedAt: new Date().toISOString().slice(0, 10),
+    criteria,
+  };
+  mkdirSync(dirname(VENDOR), { recursive: true });
+  writeFileSync(VENDOR, JSON.stringify(out, null, 2) + "\n");
+  const withGood = Object.values(criteria).filter((x) => x.good).length;
+  const withBad = Object.values(criteria).filter((x) => x.bad).length;
+  const withBrief = Object.values(criteria).filter((x) => x.brief).length;
+  console.log(`build-guidance-wcag --refresh: ${Object.keys(criteria).length} SCs — ${withBrief} briefs, ${withGood} good samples, ${withBad} failure samples → ${VENDOR}`);
+  return out;
+}
+
+/** The dataset, from the vendored snapshot. Offline and deterministic. */
+function build() {
+  if (!existsSync(VENDOR)) {
+    console.error(`build-guidance-wcag: missing ${VENDOR}. Run: node scripts/build-guidance-wcag.mjs --refresh`);
+    process.exit(1);
+  }
+  const snap = JSON.parse(readFileSync(VENDOR, "utf8"));
+  const core = JSON.parse(readFileSync(join(root, "src", "data", "wcag.json"), "utf8"));
+  const titleOf = new Map(core.criteria.map((c) => [c.sc, c]));
+
+  const entries = [];
+  for (const [sc, d] of Object.entries(snap.criteria)) {
+    const meta = titleOf.get(sc);
+    if (!meta) continue; // not in the shipped AA core
+    const summary = d.brief
+      ? [d.brief.whattodo, d.brief.goal, d.brief.whyitsimportant].filter(Boolean).join(" ")
+      : undefined;
+    // A `bad`/`good` pair shares ONE `lang`, so the two halves may only be paired when they
+    // are the same technology. A CSS failure beside an HTML fix, labelled `html`, would be
+    // a snippet the reader cannot trust — so they are emitted separately instead.
+    const label = (t) => ({ en: `${t.kind}: ${t.title} (${t.id}).` });
+    const examples = [];
+    if (d.good && d.bad && d.good.lang === d.bad.lang) {
+      examples.push({
+        lang: d.good.lang,
+        bad: d.bad.code,
+        good: d.good.code,
+        note: { en: `Good: ${d.good.title} (${d.good.id}). Bad: ${d.bad.title} (${d.bad.id}).` },
+      });
+    } else {
+      if (d.good) examples.push({ lang: d.good.lang, good: d.good.code, note: label({ kind: "Good", ...d.good }) });
+      if (d.bad) examples.push({ lang: d.bad.lang, bad: d.bad.code, note: label({ kind: "Bad", ...d.bad }) });
+    }
+    entries.push({
+      id: `wcag-${d.slug}`,
+      criterionId: sc,
+      wcag: [sc],
+      title: { en: meta.title, ...(meta.titleFr ? { fr: meta.titleFr } : {}) },
+      ...(summary ? { summary: { en: summary } } : { summary: {} }),
+      examples,
+      reference: `https://www.w3.org/WAI/WCAG22/Understanding/${d.slug}.html`,
+    });
+  }
+  entries.sort((a, b) => a.criterionId.localeCompare(b.criterionId, "en", { numeric: true }));
+
+  const out = {
+    pack: "wcag",
+    source: snap.understanding,
+    license: snap.license,
+    attribution:
+      "Derived from the W3C Techniques for WCAG 2.2 and the Understanding documents (https://github.com/w3c/wcag). WCAG 2.2 © W3C. " +
+      "Summaries are the working group's own 'In brief' text; code samples are the techniques' own examples. Generated by scripts/build-guidance-wcag.mjs — never hand-edited.",
+    entries,
+  };
+  return biomeFormat(JSON.stringify(out, null, 2) + "\n", "src/data/guidance/wcag.json");
+}
+
+async function main() {
+  if (process.argv.includes("--refresh")) await refresh();
+  const text = build();
+  if (process.argv.includes("--check")) {
+    const current = existsSync(OUT) ? readFileSync(OUT, "utf8") : "";
+    if (current !== text) {
+      console.error("build-guidance-wcag --check: src/data/guidance/wcag.json does not match the vendored W3C source. Re-run: node scripts/build-guidance-wcag.mjs");
+      process.exit(1);
+    }
+    console.log("build-guidance-wcag --check: src/data/guidance/wcag.json matches the vendored source.");
+    return;
+  }
+  mkdirSync(dirname(OUT), { recursive: true });
+  writeFileSync(OUT, text);
+  const n = JSON.parse(text).entries.length;
+  console.log(`build-guidance-wcag: ${n} entries → src/data/guidance/wcag.json`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});