ultra11y 2.22.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxgfr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# ultra11y
+
+> 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:
+
+- **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".
+- **Needs rendering (scan tier):** computed contrast, visible focus, zoom/reflow, content on hover — decided by `scan` (axe-core in a real browser); until then they stay **residual risks**, never silently "conforming".
+- **Advisory vs non-conformity:** a good practice with no failing normative test (an `advisory` pack rule, a best-practice-only axe violation, an agent recommendation) renders as « Recommandation (non normative) » — it never flips a criterion to `NC` nor enters the conformance rate. An NC always cites a `normativeRef`.
+- **Stateful scan probes:** the local runtime drives the page with bounded, non-navigating interactions (fill inputs then re-measure overflow; a live-region probe for status messages 4.1.3) — `--no-interact` opts out; `--interact-clicks` re-enables button clicks on authenticated scans (destructive-named buttons are never clicked).
+- **Normative page sample (échantillon):** a country-standard audit runs over a declared `sample.pages` set — `sample check` lints its coverage against the standard's required page kinds, `scan --sample` scans it, and an un-scanned `--standard rgaa` report is flagged **partial**.
+- **Pack-only detection (declarative):** a standards pack can ship its own `rules` (a bounded, ReDoS-guarded matcher DSL — no code) and normativity/severity `overrides`, projecting onto its criteria without forking the engine.
+
+## Measured against a corpus it did not write
+
+A self-authored fixture can only prove that a rule fires on the defect written for it. So the engine is also scored against the **[W3C ACT-Rules Community Group](https://act-rules.github.io) test corpus** — 1 134 `passed` / `failed` / `inapplicable` examples across 91 rules, authored independently of this project:
+
+| | |
+|---|---|
+| Rules scored | **32** (the ACT rules an equivalent engine check exists for) |
+| `failed` examples caught | **103 / 149** |
+| `passed` / `inapplicable` examples left alone | **291 / 291** — no unexplained false positive |
+| Deliberate divergences | 9, each argued on the record |
+| Declared gaps (statically decidable, not implemented) | 13 |
+
+Rules needing a rendered page (computed contrast, keyboard traps) or a human call (is this heading descriptive?) are **declared and routed**, not silently scored zero. The full per-rule matrix — including every gap and every divergence — is generated into [`skills/ultra11y/references/act.md`](skills/ultra11y/references/act.md) and re-checked on every build; the corpus itself is refreshed daily by a workflow, so the numbers cannot quietly go stale.
+
+## Install
+
+```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.
+
+Or clone and run the bundled engine directly (Node ≥ 22.18, zero dependencies):
+
+```sh
+node scripts/ultra11y.mjs --help
+```
+
+## Commands
+
+```
+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 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 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]
+ultra11y fix      <globs… | ->  [--write] [--iterate] [--changed | --since <ref> | --staged] [--safe] [--only <ids>] [--jsx] [--json]
+ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
+ultra11y pack     check <pack.json> [--guidance <g.json>]  |  scaffold                 # gate an (AI-)authored standards pack
+ultra11y scan     <url|file…> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--out <dir>] [--json]
+ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime …] [--merge <audit.json>] [--json]
+ultra11y mcp      [--transport stdio|http] [--cwd <dir>] [--allow-write] [--port <n>] [--bind <addr>] [--allow-remote]
+
+# global: --pack <paths> (load external standards pack(s) at runtime) · --override
+```
+
+## Use it as an MCP server
+
+The skill shells out to the CLI and parses its output. An MCP server skips both:
+your agent calls ultra11y as typed tools, with JSON schemas in and structured
+results out. Same engine, same standards data, no wrapper.
+
+```bash
+# stdio — the default, and what Claude Code / Claude Desktop / Cursor expect
+claude mcp add ultra11y -- node /abs/path/to/scripts/ultra11y.mjs mcp
+
+# or over HTTP, on loopback
+node scripts/ultra11y.mjs mcp --transport http --port 7341
+claude mcp add --transport http ultra11y http://127.0.0.1:7341/mcp
+```
+
+```jsonc
+// Claude Desktop takes stdio servers only — a remote URL here will not work.
+{ "mcpServers": { "ultra11y": { "command": "node", "args": ["/abs/path/to/scripts/ultra11y.mjs", "mcp"] } } }
+// Cursor, HTTP:
+{ "mcpServers": { "ultra11y": { "url": "http://127.0.0.1:7341/mcp" } } }
+```
+
+It serves all three MCP primitives, because a skill is three things: the engine
+(**tools**), the method (**prompts**), and the documentation the method refers
+to (**resources**). A client given only the tools runs the audit, sees no
+errors, and reports the page as accessible — a false conformance claim, which is
+the one output an accessibility tool must never produce.
+
+### Tools
+
+Ten read tools. `ultra11y_audit` is the entry point:
+
+| 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_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 |
+| `ultra11y_sample_check` | Lint the normative page sample |
+| `ultra11y_read` | A file, or a line range, from the project |
+
+`--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
+browser and may pull a Docker image, which is not a subprocess lifecycle a
+long-lived server should own. It tells you to run it from the CLI and re-audit.
+
+Pass `--cwd <dir>` at startup to dedicate the server to one project — `cwd` then
+becomes optional on every tool.
+
+### Prompts — the workflow, not just the tools
+
+| Prompt | Arguments | What it drives |
+|--------|-----------|----------------|
+| `audit_wcag` | `cwd`, `globs?`, `standard?` | audit → adjudicate → rule on each → report → check, with the untested criteria named |
+| `adjudicate_criteria` | `cwd`, `standard?` | What alt-text relevance, link purpose, heading structure and reading order actually ask |
+| `review_diff_a11y` | `cwd`, `since?` | Audit exactly the diff, refute the false positives, state the residual risks |
+
+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
+
+`SKILL.md` and all 28 `references/*.md` are served under `skill://`, read off
+disk at request time — so a documentation fix reaches every client without a
+rebuild.
+
+Two things worth knowing:
+
+- **A criterion nobody tested is untested, never conformant.** Every tool
+  description and every prompt says so, because the failure mode here is not a
+  wrong answer — it is a confident silence.
+- **The HTTP transport binds `127.0.0.1` and refuses anything else** unless you
+  pass `--allow-remote`. This server reads local files; an exposed port is a
+  read-anything primitive for whoever finds it.
+
+## Standards packs (RGAA France first; add your country)
+
+WCAG 2.2 AA is the engine's canonical key. Each country standard ships as an in-repo
+**standards pack** — a small JSON that maps the national standard's criteria onto WCAG
+success criteria — so the same audit re-keys to any standard:
+
+```sh
+node scripts/ultra11y.mjs report   --in audits/audit-latest.json --standard rgaa   # → audits/rgaa-YYYY-MM-DD.md
+node scripts/ultra11y.mjs criteria --standard rgaa 8.3                              # a pack criterion (+ its WCAG SCs)
+```
+
+**RGAA 4.1.2** (France) ships as the flagship pack. Section 508 (US), EN 301 549 (EU) and
+others are welcome — adding a country is a single PR (pack JSON + one registration line +
+a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/references/standards.md`.
+
+### Scale, fixes, and repo automation
+
+- **Scale** — the engine streams file-by-file (bounded memory), audits **only markup**,
+  and lets you focus: `--changed`/`--since` (git diff only), priority ordering
+  (layouts/templates/shared components first), content de-duplication, and an explicit
+  `--max-files` cap with logged truncation. See `references/scale.md`.
+- **Fixes** — `fix` puts the fixes in place (native-first, anti-hallucination): deterministic
+  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`.
+- **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
+  regression variant (hook + committed baseline / GitHub Actions job) that fails only on **new**
+  non-conformities, not the existing backlog. See `references/automation.md`.
+
+### Optional dynamic tier (axe-core)
+
+`scan` runs **axe-core in a headless browser** to decide the *needs-rendering* criteria the static engine leaves as residual risks — chiefly **computed colour contrast (1.4.3)** plus a 320px **reflow** check (1.4.10) and a render cross-check of the structural rules. Two runtimes (default `--runtime auto`): **`--runtime local`** uses a Playwright that resolves from your project (`--cwd`) — **no Docker** — and additionally probes focus visibility (2.4.7), 200% zoom (1.4.4), text spacing (1.4.12) and content-on-hover (1.4.13), plus **stateful** probes (fill inputs then re-measure overflow, and a live-region probe for status messages 4.1.3 — opt out with `--no-interact`, `--interact-clicks` for authed-scan button clicks), and takes `--storage-state` for authenticated pages; **`--runtime docker`** falls back to a self-contained image built on first use. `--merge` folds the findings into a static `AuditResult`, upgrading `manual` criteria to `C`/`NC`. A country-standard audit scans its declared page sample with `scan --sample` (lint it first with `sample check`):
+
+```sh
+node scripts/ultra11y.mjs audit "src/**/*.html" --out audits --json > /dev/null
+node scripts/ultra11y.mjs scan http://localhost:3000 --runtime local --cwd . --merge audits/audit-latest.json --out audits
+node scripts/ultra11y.mjs report --in audits/audit-latest.json --out audits
+```
+
+Only the Docker runtime needs Docker; `--runtime local` needs a project with `@playwright/test` + `@axe-core/playwright`. The rest of the skill is zero-dependency. The Docker runner + Dockerfile are embedded in the engine and mirrored under `docker/` (with a `docker-compose.yml`). See `skills/ultra11y/references/dynamic.md`.
+
+Typical audit flow:
+
+```sh
+node scripts/ultra11y.mjs audit "src/**/*.html" --json > audit.json
+node scripts/ultra11y.mjs report --in audit.json --out audits      # audits/wcag-YYYY-MM-DD.md
+node scripts/ultra11y.mjs check  --report audits/wcag-YYYY-MM-DD.md # integrity gate
+```
+
+The skill (`skills/ultra11y/SKILL.md` + `references/`) teaches the agent when and how to run these, how to complete the manual criteria, and the native-first authoring doctrine.
+
+## Development
+
+```sh
+pnpm install
+pnpm test               # vitest
+pnpm run typecheck
+pnpm run build          # tsup → scripts/ultra11y.mjs, mirrored into skills/ultra11y/scripts/
+pnpm run check:build    # asserts the committed bundle is reproducible
+pnpm run build:wcag     # re-derive src/data/wcag.json from the vendored W3C source
+pnpm run build:pack:rgaa # re-build the RGAA pack from the vendored DINUM source
+pnpm run build:criteria  # regenerate skills/ultra11y/references/criteria.md
+```
+
+Releases are cut automatically by semantic-release on push to `main` (GitHub release + tarball, no npm publish).
+
+## Data & licensing
+
+- ultra11y's code: **MIT** (see `LICENSE`).
+- The **WCAG 2.2** success-criteria dataset (`src/data/wcag.json`) is derived from the official W3C source ([w3c/wcag](https://github.com/w3c/wcag)); WCAG 2.2 is © **W3C**, reused under the **W3C Document License** (only SC ids/titles/levels are reproduced) — see `NOTICE`.
+- The **RGAA pack** (`src/data/standards/rgaa.json`, `rgaa.glossary.json`) is derived from the official **RGAA 4.1.2** reference published by DINUM/DISIC, under the **Licence Ouverte / Etalab 2.0** — see `NOTICE`. Attribution: « RGAA 4.1.2 — DINUM ».
+- The report format is inspired by DINUM/etalab-ia audit conventions; the native-first authoring rules are adapted from the SocialGouv accessibility skill. No source code was copied.

package/docker/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:22-bookworm-slim
+WORKDIR /app
+COPY package.json ./
+RUN npm install --omit=dev && npx playwright install --with-deps chromium
+COPY runner.mjs ./
+WORKDIR /work
+ENTRYPOINT ["node", "/app/runner.mjs"]

package/docker/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "ultra11y-dynamic",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "playwright": "^1.49.0",
+    "axe-core": "4.12.1"
+  }
+}

package/docker/runner.mjs

@@ -0,0 +1,23 @@
+import { chromium } from "playwright";
+import axe from "axe-core";
+const target = process.argv[2];
+const isFile = target.startsWith("/work/");
+const browser = await chromium.launch({ args: ["--no-sandbox", "--disable-dev-shm-usage"] });
+try {
+  const page = await browser.newPage();
+  await page.goto(isFile ? "file://" + target : target, { waitUntil: "load", timeout: 45000 });
+  await page.addScriptTag({ content: axe.source });
+  const axeRes = await page.evaluate(async () => await window.axe.run(document, { resultTypes: ["violations"] }));
+  await page.setViewportSize({ width: 320, height: 800 });
+  const reflow = await page.evaluate(() => {
+    const el = document.scrollingElement || document.documentElement;
+    return { horizontalScroll: el.scrollWidth > el.clientWidth + 2 };
+  });
+  const violations = axeRes.violations.map((v) => ({
+    id: v.id, impact: v.impact, help: v.help, tags: v.tags,
+    nodes: v.nodes.slice(0, 10).map((n) => ({ target: n.target, html: (n.html || "").slice(0, 200) })),
+  }));
+  console.log(JSON.stringify({ url: target, violations, reflow }));
+} finally {
+  await browser.close();
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "ultra11y",
+  "version": "2.22.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",
+  "bin": {
+    "ultra11y": "scripts/ultra11y.mjs"
+  },
+  "files": [
+    "scripts",
+    "src",
+    "skills",
+    "docker"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-bundle.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:perf": "vitest run --config vitest.perf.config.ts",
+    "bench": "node scripts/bench.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome ci .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "verify:bundle": "node scripts/verify-skill-bundle.mjs",
+    "check:build": "tsup && node scripts/copy-bundle.mjs && git diff --exit-code -- scripts/ultra11y.mjs skills/ultra11y/scripts/ultra11y.mjs skills/review-a11y/scripts/ultra11y.mjs && node scripts/verify-skill-bundle.mjs && node scripts/sync-engine.mjs --check",
+    "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: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",
+    "build:adjudication": "node scripts/build-adjudication.mjs && UPDATE_ADJUDICATION_MD=1 vitest run tests/adjudication-md-sync.test.ts",
+    "check:adjudication": "node scripts/build-adjudication.mjs --check",
+    "demo": "node scripts/ultra11y.mjs audit tests/fixtures/non-conforming/bad.html --out /tmp/ultra11y-demo --json > /dev/null && node scripts/ultra11y.mjs report --in /tmp/ultra11y-demo/audit-latest.json --out /tmp/ultra11y-demo && node scripts/ultra11y.mjs check --report /tmp/ultra11y-demo/wcag-*.md && node scripts/ultra11y.mjs criteria --list",
+    "release": "semantic-release"
+  },
+  "license": "MIT",
+  "author": "maxgfr",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maxgfr/ultra11y"
+  },
+  "dependencies": {
+    "@babel/parser": "^8.0.0",
+    "domhandler": "^6.0.1",
+    "htmlparser2": "^12.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^26.0.1",
+    "@vitest/coverage-v8": "^4.1.9",
+    "jsdom": "^29.1.1",
+    "semantic-release": "^25.0.5",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "yaml": "^2.9.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/scripts/bench.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// DEV-ONLY (not in `bin`). Perf harness for the shipped bundle.
+//
+// Absolute timings are machine-specific, so this is NOT a CI gate — the automatic,
+// machine-independent regression guard is tests/perf-shape.test.ts, which asserts the
+// SHAPE of the cost curve (quadratic work fails, linear work passes). This script is
+// the human-facing counterpart: it builds a deterministic synthetic repository whose
+// proportions mirror a real front-end codebase, runs the real CLI over it as a
+// subprocess, and prints wall times you can compare across two revisions.
+//
+// Usage:
+//   node scripts/bench.mjs                       # default corpus, table output
+//   node scripts/bench.mjs --scale 3             # 3x the file counts
+//   node scripts/bench.mjs --json                # machine-readable
+//   node scripts/bench.mjs --engine <path.mjs>   # bench another bundle (e.g. a git-restored one)
+//   node scripts/bench.mjs --compare <old.mjs>   # run BOTH and print the delta per scenario
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const DEFAULT_ENGINE = join(ROOT, "scripts", "ultra11y.mjs");
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : fallback;
+};
+const SCALE = Number(flag("--scale", "1")) || 1;
+const AS_JSON = argv.includes("--json");
+const ENGINE = flag("--engine", DEFAULT_ENGINE);
+const COMPARE = flag("--compare", null);
+const RUNS = Number(flag("--runs", "3")) || 3;
+
+// Proportions of a mid-size front-end repo: many components, a smaller shared
+// TS/JS layer the graph must resolve through, a handful of full HTML pages.
+const COUNTS = { modules: Math.round(300 * SCALE), components: Math.round(400 * SCALE), pages: Math.round(120 * SCALE) };
+
+/** A shared TS module: no markup, but real graph structure (exports the graph resolves). */
+function tsModule(i) {
+  const body = Array.from(
+    { length: 12 },
+    (_, k) => `export function helper${i}_${k}(items: string[], opts: Record<string, number> = {}): string {\n` + `  return items.map((s) => s.trim()).join(String(opts.sep ?? ${k}));\n}`,
+  ).join("\n\n");
+  return `export const ANCHOR_${i} = "anchor-${i}";\nexport const LABEL_${i} = "Label ${i}";\n\n${body}\n`;
+}
+
+/** A realistic ~130-line TSX component carrying a handful of genuine defects. */
+function component(i, moduleCount) {
+  const dep = i % moduleCount;
+  const rows = Array.from({ length: 10 }, (_, k) => `        <tr><td>{row.a${k}}</td><td>{row.b${k}}</td></tr>`).join("\n");
+  const fields = Array.from(
+    { length: 8 },
+    (_, k) => `      <div className="field">\n        <label htmlFor="f${i}_${k}">Field ${k}</label>\n        <input id="f${i}_${k}" type="text" name="n${i}_${k}" />\n      </div>`,
+  ).join("\n");
+  return `import { ANCHOR_${dep}, LABEL_${dep} } from "../lib/mod${dep}";
+import type { ReactNode } from "react";
+
+interface Props {
+  label: string;
+  rows: { a0: string; b0: string }[];
+  children?: ReactNode;
+}
+
+export function C${i}({ label, rows, children }: Props) {
+  const title = label || LABEL_${dep};
+  return (
+    <section className="card" id={ANCHOR_${dep}}>
+      <header>
+        <h2>{title}</h2>
+        <img src="/thumb${i}.png" />
+        <button></button>
+        <a href="/detail/${i}"></a>
+      </header>
+${fields}
+      <table>
+        <tbody>
+${rows}
+        </tbody>
+      </table>
+      <footer>{children}</footer>
+    </section>
+  );
+}
+
+export default C${i};
+`;
+}
+
+/** A full HTML page — the page-scoped rules (title, lang, landmarks) only fire on these. */
+function page(i) {
+  const cells = Array.from({ length: 12 }, (_, k) => `<tr><td>${k}</td><td>value ${k}</td></tr>`).join("");
+  return `<!doctype html><html><head></head><body><main><img src="hero${i}.png"><a href="#missing${i}">Skip</a><table>${cells}</table><form><input type="text" name="q"><button></button></form></main></body></html>`;
+}
+
+function buildCorpus() {
+  const root = mkdtempSync(join(tmpdir(), "ultra11y-bench-"));
+  mkdirSync(join(root, "src", "lib"), { recursive: true });
+  mkdirSync(join(root, "src", "components"), { recursive: true });
+  mkdirSync(join(root, "src", "pages"), { recursive: true });
+  let bytes = 0;
+  const write = (p, s) => {
+    writeFileSync(p, s);
+    bytes += Buffer.byteLength(s);
+  };
+  for (let i = 0; i < COUNTS.modules; i++) write(join(root, "src", "lib", `mod${i}.ts`), tsModule(i));
+  for (let i = 0; i < COUNTS.components; i++) write(join(root, "src", "components", `C${i}.tsx`), component(i, COUNTS.modules));
+  for (let i = 0; i < COUNTS.pages; i++) write(join(root, "src", "pages", `p${i}.html`), page(i));
+  return { root, bytes };
+}
+
+function time(engine, args, cwd) {
+  const samples = [];
+  for (let i = 0; i < RUNS; i++) {
+    const t0 = performance.now();
+    const r = spawnSync(process.execPath, [engine, ...args], { cwd, stdio: "ignore", maxBuffer: 512 * 1024 * 1024 });
+    if (r.error) throw r.error;
+    samples.push(performance.now() - t0);
+  }
+  return Math.min(...samples); // best-of: the least noisy estimate of the real cost
+}
+
+const SCENARIOS = [
+  { id: "audit", args: ["audit", "src", "--json"] },
+  { id: "audit --graph", args: ["audit", "src", "--graph", "--json"] },
+  { id: "audit --max-files 50", args: ["audit", "src", "--max-files", "50", "--json"] },
+  { id: "fix (dry-run)", args: ["fix", "src", "--json"] },
+];
+
+const { root, bytes } = buildCorpus();
+try {
+  const files = COUNTS.modules + COUNTS.components + COUNTS.pages;
+  const results = SCENARIOS.map((s) => {
+    const ms = time(ENGINE, s.args, root);
+    return COMPARE ? { ...s, ms, baseMs: time(COMPARE, s.args, root) } : { ...s, ms };
+  });
+  if (AS_JSON) {
+    console.log(JSON.stringify({ corpus: { ...COUNTS, files, bytes }, engine: ENGINE, runs: RUNS, results }, null, 2));
+  } else {
+    console.log(`corpus: ${files} files (${COUNTS.modules} .ts, ${COUNTS.components} .tsx, ${COUNTS.pages} .html), ${(bytes / 1024 / 1024).toFixed(1)} MiB`);
+    console.log(`engine: ${ENGINE}${COMPARE ? `\nbaseline: ${COMPARE}` : ""}\nbest of ${RUNS} runs\n`);
+    for (const r of results) {
+      const base = r.baseMs === undefined ? "" : `   baseline ${r.baseMs.toFixed(0).padStart(6)} ms   ${(((r.ms - r.baseMs) / r.baseMs) * 100).toFixed(1).padStart(6)} %`;
+      console.log(`${r.id.padEnd(22)} ${r.ms.toFixed(0).padStart(6)} ms${base}`);
+    }
+  }
+} finally {
+  rmSync(root, { recursive: true, force: true });
+}

package/scripts/build-act-corpus.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// DEV-ONLY (not in `bin`). Vendors the OFFICIAL W3C ACT-Rules Community Group test
+// corpus so the engine can be measured against third-party HTML nobody here wrote.
+//
+// Why this matters: the engine's own recall suite seeds one fixture per rule that
+// EXISTS, so it can only ever prove "the rules we wrote fire on the defects we wrote".
+// The ACT corpus is written by the ACT-Rules Community Group against the ACT Rules
+// Format, independently of this project — it is the only external yardstick available
+// for both recall (does a `failed` example get caught?) and precision (does a `passed`
+// or `inapplicable` example stay clean?).
+//
+// The snapshot is COMMITTED (scripts/vendor/act-testcases.json) so the test suite stays
+// offline and deterministic, exactly like the vendored WCAG/RGAA sources.
+//
+// Usage:
+//   node scripts/build-act-corpus.mjs                 # verify the vendored snapshot parses + summarize
+//   node scripts/build-act-corpus.mjs --refresh       # re-fetch metadata AND every test case's HTML (network)
+//   node scripts/build-act-corpus.mjs --check         # exit 1 if the snapshot is missing/!well-formed
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const VENDOR_DIR = join(root, "scripts", "vendor");
+const SNAPSHOT = join(VENDOR_DIR, "act-testcases.json");
+const INDEX_URL = "https://act-rules.github.io/testcases.json";
+const CONCURRENCY = 12;
+
+const argv = process.argv.slice(2);
+const REFRESH = argv.includes("--refresh");
+const CHECK = argv.includes("--check");
+
+/** Fetch with a small retry — a transient failure must not silently shrink the corpus. */
+async function fetchText(url, attempts = 3) {
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      const res = await fetch(url, { redirect: "follow" });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return await res.text();
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw new Error(`${url}: ${lastErr instanceof Error ? lastErr.message : lastErr}`);
+}
+
+/** Run `jobs` with a bounded number in flight (politeness + memory). */
+async function pool(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      for (;;) {
+        const i = next++;
+        if (i >= items.length) return;
+        out[i] = await fn(items[i], i);
+      }
+    }),
+  );
+  return out;
+}
+
+async function refresh() {
+  process.stderr.write(`fetching ${INDEX_URL}\n`);
+  const index = JSON.parse(await fetchText(INDEX_URL));
+  const cases = index.testcases ?? [];
+  if (!cases.length) throw new Error("the ACT index returned no test cases — refusing to write an empty snapshot");
+  process.stderr.write(`fetching ${cases.length} test case documents (concurrency ${CONCURRENCY})…\n`);
+  let done = 0;
+  const html = await pool(cases, CONCURRENCY, async (tc) => {
+    const body = await fetchText(tc.url);
+    if (++done % 100 === 0) process.stderr.write(`  ${done}/${cases.length}\n`);
+    return body;
+  });
+
+  // Keep only what a conformance run needs, in a stable order, so the snapshot diffs
+  // readably and a re-fetch of unchanged upstream data is a no-op.
+  const testcases = cases
+    .map((tc, i) => ({
+      ruleId: tc.ruleId,
+      ruleName: tc.ruleName,
+      testcaseId: tc.testcaseId,
+      title: tc.testcaseTitle,
+      expected: tc.expected,
+      // Which WCAG success criteria the rule is a test for — lets the corpus be
+      // cross-referenced with the engine's own criterion mapping.
+      wcag: Object.keys(tc.ruleAccessibilityRequirements ?? {})
+        .filter((k) => /^wcag\d*:\d/.test(k))
+        .map((k) => k.split(":")[1])
+        .sort(),
+      html: html[i],
+    }))
+    .sort((a, b) => a.ruleId.localeCompare(b.ruleId) || a.testcaseId.localeCompare(b.testcaseId));
+
+  const snapshot = {
+    source: INDEX_URL,
+    name: index.name,
+    website: index.website,
+    license: index.license,
+    fetchedCount: testcases.length,
+    rules: [...new Set(testcases.map((t) => t.ruleId))].length,
+    testcases,
+  };
+  mkdirSync(VENDOR_DIR, { recursive: true });
+  writeFileSync(SNAPSHOT, `${JSON.stringify(snapshot, null, 2)}\n`);
+  process.stderr.write(`wrote ${SNAPSHOT} — ${snapshot.rules} rules, ${snapshot.fetchedCount} cases\n`);
+  return snapshot;
+}
+
+function load() {
+  if (!existsSync(SNAPSHOT)) {
+    process.stderr.write(`missing ${SNAPSHOT} — run: node scripts/build-act-corpus.mjs --refresh\n`);
+    process.exitCode = 1;
+    return null;
+  }
+  const snap = JSON.parse(readFileSync(SNAPSHOT, "utf8"));
+  if (!Array.isArray(snap.testcases) || !snap.testcases.length) {
+    process.stderr.write(`${SNAPSHOT} holds no test cases\n`);
+    process.exitCode = 1;
+    return null;
+  }
+  for (const tc of snap.testcases) {
+    if (!tc.ruleId || !tc.expected || typeof tc.html !== "string") {
+      process.stderr.write(`${SNAPSHOT}: malformed test case ${tc.testcaseId ?? "?"}\n`);
+      process.exitCode = 1;
+      return null;
+    }
+  }
+  return snap;
+}
+
+const snap = REFRESH ? await refresh() : load();
+if (snap && !CHECK) {
+  const byExpected = {};
+  for (const t of snap.testcases) byExpected[t.expected] = (byExpected[t.expected] ?? 0) + 1;
+  process.stdout.write(
+    `ACT corpus: ${snap.rules} rules, ${snap.testcases.length} cases ` +
+      `(${Object.entries(byExpected)
+        .map(([k, v]) => `${v} ${k}`)
+        .join(", ")})\n`,
+  );
+}