ultra11y 2.22.0 → 2.24.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Audit HTML/CSS/JSX against **WCAG 2.2 AA** accessibility and produce a dated compliance report — or author/review accessible markup without regressions. A [skills.sh](https://skills.sh) agent skill: a deterministic, zero-dependency static engine **plus** the agent's judgment, with `check`/`verify` gates against hallucinated non-conformities. **The central deliverable is the auditor conformance block** — theme, criterion + official wording, test(s), WCAG mapping + level, finding, expected state, verification, `file:line` occurrences — rendered identically by the `report` (compliance doc), the `prd` backlog and the GitHub issues, in the active standard's vocabulary and **in your language** (`--lang auto` follows the conversation/repo). **WCAG is the worldwide core; country standards (RGAA, …) are pluggable in-repo packs.**
 
-ultra11y is built around an honest **division of labour**. Automated tools only catch a fraction of accessibility problems, so the engine does the *mechanical* work — 72 machine-detectable static checks tied to the WCAG 2.2 success criteria — and is explicit about everything it can't decide statically. What it can't, the **AI agent adjudicates** (statically, from the evidence, gated by `verify`/`check`) — not a deferral to a human:
+ultra11y is built around an honest **division of labour**. Automated tools only catch a fraction of accessibility problems, so the engine does the *mechanical* work — 78 machine-detectable static checks tied to the WCAG 2.2 success criteria — and is explicit about everything it can't decide statically. What it can't, the **AI agent adjudicates** (statically, from the evidence, gated by `verify`/`check`) — not a deferral to a human:
 
 - **Automatable (engine):** missing `alt`/`lang`/`title`, unlabeled fields, empty links/buttons, icon-only controls, iframes without title, tables without headers, heading-level skips, empty/dangling headings & labels, duplicate ids, invalid/broken ARIA, positive `tabindex`, autoplay/timed-refresh/`blink`/`marquee` media…
 - **Agent judgment (gated):** alt-text relevance, link purpose in context, reading/tab order, caption accuracy — the agent rules on these via `verify --manual` → `--apply`, each verdict carrying a justification (or a groundable NC), never a silent "conforming".
@@ -28,17 +28,37 @@ Rules needing a rendered page (computed contrast, keyboard traps) or a human cal
 
 ## Install
 
+**As a CLI** — on npm, zero runtime dependencies (Node ≥ 22.18):
+
+```sh
+npx ultra11y --help          # no install
+npm i -D ultra11y            # or as a dev dependency
+```
+
+**As an agent skill** — the repository ships **two** (pick at the prompt, or pass the name):
+`ultra11y` for full audits, compliance reports, PRD backlogs and standards packs, and
+`review-a11y` for the fast loop that audits **exactly the code under change** (staged files,
+working diff, or branch vs merge-base) and reports like a code reviewer. Both bundle the same
+install-free engine.
+
 ```sh
 npx skills add maxgfr/ultra11y
 ```
 
-The repository ships **two skills** (pick at the prompt, or pass the skill name):
-`ultra11y` — full audits, compliance reports, PRD backlogs, standards packs — and
-`review-a11y` — the fast review loop that audits **exactly the code under change**
-(staged files, working diff, or branch vs merge-base) and reports like a code reviewer.
-Both bundle the same install-free engine.
+**As an MCP server** — so an agent drives the engine as tools instead of shelling out:
+
+```sh
+claude mcp add ultra11y -- npx -y ultra11y mcp
+```
+
+**As a GitHub Action** — audits the PR diff and, optionally, the served pages:
+
+```yaml
+- uses: maxgfr/ultra11y@v2
+  with: { since: auto, standard: rgaa, fail-on: blocking }
+```
 
-Or clone and run the bundled engine directly (Node ≥ 22.18, zero dependencies):
+Or clone and run the bundled engine straight from the repo:
 
 ```sh
 node scripts/ultra11y.mjs --help
@@ -50,9 +70,14 @@ node scripts/ultra11y.mjs --help
 ultra11y audit    <globs… | ->  [--out <dir>] [--include <glob>] [--exclude <glob>] [--ext <list>] [--jsx] [--graph] [--json] [--lang auto|en|fr] [--no-default-excludes]
 ultra11y audit    [--changed | --since <ref> | --staged] [--max-files <n>] [--dedup exact|normalized|off] [--baseline <file>] [--fail-on blocking|major|minor]
 ultra11y audit    [--captures <dir>] [--no-captures] [--require-captures]              # audit rendered-DOM captures alongside source
-ultra11y report   --in <audit.json> [--out <dir>] [--standard <pack>] [--lang auto|en|fr]
+ultra11y audit    [--format sarif|github]                                               # CI: code-scanning SARIF, or inline annotations + job summary
+ultra11y report   --in <audit.json> [--out <dir>] [--standard <pack>] [--format sarif|github] [--lang auto|en|fr]
 ultra11y prd      --in <audit.json> [--out <dir>] [--split criterion] [--format audit|doc|remediation] [--standard <pack>] [--gh-issues | --gh-single] [--lang auto|en|fr]
-ultra11y render   [<dir>] [--scaffold | --setup | --coverage | --storybook] [--captures <dir>] [--out <file>] [--json]
+ultra11y render   [<dir>] [--scaffold | --setup | --e2e | --coverage | --storybook] [--runner playwright|cypress] [--captures <dir>] [--out <file>] [--json]
+ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   # payload on stdin → .ultra11y/pages/<id>/ + audit
+ultra11y snapshot list  [--root <dir>] [--json]
+ultra11y pages    --in <audit.json> [--standard <pack>] [--json] [--lang auto|en|fr]   # the per-page criterion grid
+ultra11y dev      [--port <n>] [--standard <pack>]   |   dev --next                        # live overlay while you build + dashboard
 ultra11y criteria [<sc>] [--list] [--standard <pack> [--theme <N>]] [--generate] [--json] [--lang auto|en|fr]
 ultra11y check    --report <md> [--standard <pack>] [--quiet] [--json]
 ultra11y verify   --report <md> [--standard <pack>] [--semantic] [--apply <verdicts.json>] [--max-verify <n>] [--json]
@@ -172,6 +197,65 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   auto-codemods, fill-in `TODO` placeholders for the agent to complete, and judgment-only
   proposals. `--dry-run` is the default; `--write` applies but only after a re-audit proves
   no new non-conformity, and never on lossy JSX/TSX. See `references/fix.md`.
+- **During your E2E run** — `render --e2e` writes Playwright/Cypress fixtures that audit a
+  targeted page **inside the test run you already have**, so the page is checked in the state
+  your test built (logged in, form filled, modal open) — state a separate `scan` run does not
+  have. Each checked page is persisted as a **snapshot** (`.ultra11y/pages/<id>/`: the whole
+  rendered document + computed styles + boxes), which is the durable half: the same page
+  re-audits **offline, with no browser**, so CI and the per-page report work from it. Because
+  a snapshot is a full document, the page-scoped rules finally run — RGAA **8.3** (`lang`),
+  **8.5/8.6** (`title`) — and every finding carries both its page and the source file that
+  rendered it. See `references/e2e.md` and `references/pages.md`.
+- **While you build** — `dev --next` writes a one-line Next overlay component and `dev` starts
+  a loopback side-car: a floating panel lists the current page's non-conformities as you
+  browse, each linking to its `file:line` in your editor, and `http://127.0.0.1:4111` shows
+  the per-page grid accumulating. The overlay detaches itself before collecting — otherwise it
+  would audit itself and shift every element index — and renders nothing outside development.
+  See `references/devtools.md`.
+- **A country standard is adjudicated at its OWN granularity** — 99 of RGAA's 106 criteria can
+  only ever derive `manual`, so ~93% of an RGAA audit is settled by the agent. `verify --manual
+  --standard rgaa` now keys the worklist by **RGAA criteria**, each carrying its numbered tests
+  in full, its technical note, its particular cases, its guidance and the glossary definitions
+  its tests cite (119 entries that previously had no reader). A `normativeRef` must cite one of
+  the item's **own** tests — the laxer check accepted a WCAG id that happened to collide with
+  an unrelated RGAA test number. Verdicts fold into a separate `packAdjudication` layer so a
+  pack decision never rewrites the WCAG core. See `references/judgment.md`.
+- **Rendered tier (offline)** — six rules read a snapshot's browser-only signals inside the
+  ordinary `audit`: **no browser, no Docker, no running server**. `rendered-contrast` measures
+  contrast on the *computed* styles (the inline-literal rule could only see colours written in
+  the markup); `rendered-contrast-pixel` measures it **on the screenshot** for text over a
+  gradient or image, where `background-color` is transparent and every CSSOM-based checker —
+  axe-core included — is blind; `rendered-nontext-contrast` decides whether a form control's
+  boundary is perceivable (**RGAA 3.3**); and two more read the *stylesheet itself*, which is
+  the only place they exist: a focus indicator removed with nothing put back (**10.7**, until
+  now reachable only by a live browser probe) and an orientation lock (**13.9**).
+  `rendered-link-colour-only` makes **RGAA 10.6** decidable at all.
+  Each can say *"I don't know"*: an unresolvable backdrop, a varied region, a cross-origin
+  stylesheet, a `box-shadow` that might be the boundary — all leave the criterion undecided
+  rather than guessed, and without signals the rules do not fire, so no pre-existing verdict
+  changes. `tests/rgaa-coverage.test.ts` ratchets the result: **48 of 106** RGAA criteria now
+  map onto an engine rule, up from 43, and the number can only go up.
+- **Page by page** — RGAA is a per-page norm; the engine's verdict is scope-wide. `pages`
+  bridges the two: one row per criterion, one column per page, embedded in `report` and
+  rebuilt from a committed `audit.json` alone. The per-page status is not recomputed — a
+  per-page *view* of the audit runs through the very same projection the report uses, so grid
+  and report agree by construction. Two rules hold the line: a finding is attributed to a page
+  only when something **says** so (else it is counted as unattributed, never spread across
+  pages), and a criterion is conforming *by silence* only on a page whose real rendered DOM
+  was audited. See `references/pages.md`.
+- **A shipped GitHub Action** — `uses: maxgfr/ultra11y@main` audits the **code** (PR diff) and,
+  optionally, the **pages** (it can start your app, wait for it, then scan real URLs or your
+  declared sample). The engine ships inside the action, so there is nothing to install and no
+  `setup-node`. The gate runs **last**, after SARIF, annotations, the summary, the sticky PR
+  comment and the report — a red job is never a dead end. `ultra11y init --ci` writes a
+  workflow using it. See `references/ci.md`.
+- **CI surfaces** — a red job says *that* the build broke, not *where*. `--format sarif` emits
+  SARIF 2.1.0 for GitHub code scanning, so each finding lands as an **inline annotation on the
+  causing line** of the PR; `--format github` does the same via `::error::` workflow commands
+  plus a `$GITHUB_STEP_SUMMARY` table, for plans without code scanning. Alert identity reuses
+  the baseline's `findingId`, so an alert survives line drift; a URL-keyed finding gets **no**
+  location rather than a guessed one. Run it from `report --standard rgaa` for pack-keyed
+  output. See `references/ci.md`.
 - **Automation** — `init --hook` (default) wires a zero-dependency git pre-commit gate over the
   **strict staged snapshot**: it audits the exact index blobs, auto-applies the safe fixes and
   re-stages them, and blocks only on judgment issues. `init --baseline`/`--ci` is the opt-in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "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",
@@ -56,10 +56,11 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
     "@types/node": "^26.0.1",
     "@vitest/coverage-v8": "^4.1.9",
     "jsdom": "^29.1.1",
-    "semantic-release": "^25.0.5",
+    "semantic-release": "^25.0.8",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
@@ -69,5 +70,8 @@
     "onlyBuiltDependencies": [
       "esbuild"
     ]
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/scripts/build-pack-rgaa.mjs

@@ -58,7 +58,23 @@ const slug = (s) =>
 
 // [term](#anchor) -> term
 const plain = (s) => s.replace(/\[([^\]]+)\]\(#[^)]*\)/g, "$1");
-const toArr = (v) => (Array.isArray(v) ? v.map(String) : v == null ? [] : [String(v)]);
+// DINUM nests a bullet list inside a note as `{ ul: [...] }` (17 places across
+// technicalNote / particularCases). A plain `String(v)` on those produced a literal
+// "[object Object]" in the shipped pack, silently deleting the normative sub-conditions an
+// auditor needs — e.g. every exception under RGAA 1.2's images-of-text rule. Flatten the
+// node instead of stringifying it, and refuse anything still unrecognised rather than
+// emitting placeholder text (see the assertion at the end of this file).
+const flattenNode = (v) => {
+  if (v == null) return [];
+  if (typeof v === "string") return [v];
+  if (Array.isArray(v)) return v.flatMap(flattenNode);
+  if (typeof v === "object") {
+    const list = v.ul ?? v.ol ?? v.li ?? v.p ?? v.text;
+    if (list !== undefined) return flattenNode(list);
+  }
+  return [];
+};
+const toArr = (v) => flattenNode(v);
 
 // crude HTML -> plaintext for glossary bodies
 const deHtml = (s) =>
@@ -94,6 +110,8 @@ const RULE_SC = {
   "aria-required-children": ["4.1.2"], "autoplay-media": ["1.4.2", "2.2.2"], "blink-marquee": ["2.2.2"],
   "button-empty-name": ["4.1.2"], "canvas-fallback-missing": ["1.1.1"], "chart-no-accessible-name": ["1.1.1"],
   "clickable-noninteractive": ["4.1.2", "2.1.1"], "contrast-literal": ["1.4.3"], "control-label-missing": ["4.1.2"],
+  "rendered-contrast": ["1.4.3"], "rendered-contrast-pixel": ["1.4.3"], "rendered-link-colour-only": ["1.4.1"],
+  "rendered-nontext-contrast": ["1.4.11"], "rendered-focus-not-visible": ["2.4.7"], "rendered-orientation-lock": ["1.3.4"],
   "css-generated-content-informative": ["1.3.1"], "date-fields-ungrouped": ["3.3.2"], "disabled-context-content": ["4.1.2"],
   "control-name-title-only": ["4.1.2"], "cross-icon-only-unnamed": ["4.1.2"],
   "cross-prop-drilled-name-lost": ["4.1.2"], "data-table-no-headers": ["1.3.1"],
@@ -125,6 +143,22 @@ const RULE_TO_CRITERIA = {
   "iframe-title-missing": ["2.1"], "axe:frame-title": ["2.1"], "axe:frame-title-unique": ["2.1"],
   // Theme 3 / 10.5 — colour contrast (3.2 text/bg, 10.5 CSS declarations)
   "contrast-literal": ["3.2", "10.5"], "axe:color-contrast": ["3.2", "10.5"], "axe:color-contrast-enhanced": ["3.2", "10.5"],
+  // Rendered tier: contrast measured on the real page (computed styles) and on the
+  // screenshot, for the gradient/background-image case the CSSOM cannot express.
+  "rendered-contrast": ["3.2", "10.5"], "rendered-contrast-pixel": ["3.2", "10.5"],
+  // 10.6 — a link in running text identified by colour alone. Deliberately NOT also
+  // mapped to 3.1 (the general "information by colour alone"): 10.6 is RGAA's specific
+  // criterion for links, and claiming both would count one defect twice.
+  "rendered-link-colour-only": ["10.6"],
+  // 3.3 — the boundary of a form control, measured on the computed borders/fill. The
+  // only WCAG SC RGAA 3.3 maps to (1.4.11) had no rule at all before.
+  "rendered-nontext-contrast": ["3.3"],
+  // 10.7 — a focus indicator removed by the stylesheet with nothing put back. The live
+  // `scan` probe (dyn-focus-visible) already evidenced this; the CSSOM route decides it
+  // OFFLINE, with no browser and no running app.
+  "rendered-focus-not-visible": ["10.7"],
+  // 13.9 — orientation lock. Its SC (1.3.4) had no rule.
+  "rendered-orientation-lock": ["13.9"],
   // Theme 4 — multimedia (4.3 captions)
   "media-no-track": ["4.3"], "axe:audio-caption": ["4.3"], "axe:video-caption": ["4.3"],
   // Theme 5 — tables (5.4 title, 5.6/5.7 headers, 5.8 layout-table markup)
@@ -267,6 +301,51 @@ async function main() {
         fr: "Indiquez le format et le poids du fichier dans l’intitulé du lien, par exemple « Rapport annuel (PDF, 2 Mo) ».",
       },
     },
+    // RGAA 11.8.2 — "Dans chaque balise <select>, chaque balise <optgroup> possède-t-elle un
+    // attribut label ?" Fully mechanical, and the criterion had no rule at all. Its siblings
+    // 11.8.1 ("si nécessaire") and 11.8.3 ("le label est-il pertinent ?") stay the agent's:
+    // this rule decides the one test of the three that is decidable from markup, which is
+    // exactly what the DSL is for. NORMATIVE — a missing `label` is a plain failure.
+    {
+      id: "optgroup-without-label",
+      criterion: "11.8",
+      wcag: ["1.3.1"],
+      severity: "majeur",
+      match: { tag: "optgroup", attrs: [{ name: "label", op: "absent" }] },
+      message: {
+        en: "<optgroup> without a label attribute — the group of options is unnamed (RGAA test 11.8.2).",
+        fr: "<optgroup> sans attribut label — le regroupement d’options n’est pas nommé (test RGAA 11.8.2).",
+      },
+      remediation: {
+        en: 'Add label="…" naming what the options in this group have in common, e.g. <optgroup label="Europe">.',
+        fr: 'Ajoutez label="…" nommant ce que les options du groupe ont en commun, par ex. <optgroup label="Europe">.',
+      },
+    },
+    // RGAA 8.10.2 — the FIRST of its two sub-conditions: "La valeur de l'attribut dir est
+    // conforme (rtl ou ltr)". Mechanical. The second ("la valeur est pertinente") and 8.10.1
+    // (is a reading-direction change signalled at all?) need language detection and stay
+    // manual. Anchored negative lookahead so only a genuinely invalid value matches; `auto`
+    // is valid HTML and is accepted.
+    {
+      id: "dir-value-invalid",
+      criterion: "8.10",
+      wcag: ["1.3.2"],
+      severity: "majeur",
+      match: {
+        attrs: [
+          { name: "dir", op: "present" },
+          { name: "dir", op: "matches", value: "^(?!(rtl|ltr|auto)$).+$" },
+        ],
+      },
+      message: {
+        en: "dir attribute with a value that is not rtl, ltr or auto — the reading direction change is not declared conformantly (RGAA test 8.10.2).",
+        fr: "Attribut dir dont la valeur n’est ni rtl, ni ltr, ni auto — le changement de sens de lecture n’est pas déclaré conformément (test RGAA 8.10.2).",
+      },
+      remediation: {
+        en: 'Use dir="rtl" or dir="ltr" (or dir="auto"), matching the reading direction of the text it carries.',
+        fr: 'Utilisez dir="rtl" ou dir="ltr" (ou dir="auto"), en accord avec le sens de lecture du texte porté.',
+      },
+    },
   ];
   // Wire each rule's namespaced id (`pack:rgaa:<id>`) into the criterion it reports under,
   // so derivePackResults routes its finding onto that criterion through the same
@@ -385,6 +464,21 @@ async function main() {
   writeFileSync(join(OUT, "rgaa.json"), packText);
   writeFileSync(join(OUT, "rgaa.glossary.json"), glossaryText);
 
+  // A normative sentence that stringified to "[object Object]" is a DELETED sub-condition an
+  // auditor would have had to apply. Fail the build rather than ship placeholder text.
+  const stringified = [];
+  for (const c of criteria) {
+    for (const field of ["technicalNote", "particularCases"]) {
+      for (const line of c[field] ?? []) if (String(line).includes("[object Object]")) stringified.push(`${c.id}.${field}`);
+    }
+    for (const [k, lines] of Object.entries(c.tests ?? {})) {
+      for (const line of lines) if (String(line).includes("[object Object]")) stringified.push(`${c.id} test ${k}`);
+    }
+  }
+  if (stringified.length) {
+    throw new Error(`build-pack-rgaa: ${stringified.length} normative text(s) stringified to "[object Object]" — extend flattenNode: ${stringified.join(", ")}`);
+  }
+
   const noWcag = criteria.filter((c) => c.wcag.length === 0).map((c) => c.id);
   console.log(`build-pack-rgaa: ${themes.length} themes, ${criteria.length} criteria → src/data/standards/rgaa.json`);
   console.log(`build-pack-rgaa: glossary ${Object.keys(glossary).length} entries → src/data/standards/rgaa.glossary.json`);

package/scripts/build-standards.mjs

@@ -341,7 +341,10 @@ const RULE_SC_COVERAGE = {
   ],
   "1.3.5": ["field-purpose-incomplete", "autocomplete-token-invalid"],
   "1.4.2": ["autoplay-media"],
-  "1.4.3": ["contrast-literal"],
+  "1.3.4": ["rendered-orientation-lock"],
+  "1.4.1": ["rendered-link-colour-only"],
+  "1.4.3": ["contrast-literal", "rendered-contrast", "rendered-contrast-pixel"],
+  "1.4.11": ["rendered-nontext-contrast"],
   "1.4.4": ["meta-viewport-zoom-block"],
   "2.1.1": ["clickable-noninteractive"],
   "2.2.1": ["meta-refresh-redirect"],
@@ -349,6 +352,7 @@ const RULE_SC_COVERAGE = {
   "2.4.1": ["skip-link-target-missing"],
   "2.4.2": ["title-missing-empty"],
   "2.4.3": ["positive-tabindex"],
+  "2.4.7": ["rendered-focus-not-visible"],
   "2.4.4": ["link-empty-name", "icon-only-control-unnamed"],
   "2.5.3": ["label-in-name-mismatch"],
   "3.2.2": ["on-input-context-change"],