ultra11y 5.14.0 → 5.14.2

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": "5.14.0",
+      "version": "5.14.2",
       "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": "5.14.0",
+  "version": "5.14.2",
   "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": "5.14.0",
+  "version": "5.14.2",
   "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 = "5.14.0";
+const ULTRA11Y_PLUGIN_VERSION = "5.14.2";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/dist/playwright.mjs

@@ -595,14 +595,20 @@ async function runAxe(page, mode) {
   if (mode === false) return void 0;
   const demanded = mode === true;
   let AxeBuilder;
-  try {
-    const req = createRequire2(join(process.cwd(), "package.json"));
-    const mod = req("@axe-core/playwright");
-    AxeBuilder = mod.default ?? mod;
-  } catch (e) {
+  let lastError;
+  for (const from of [join(process.cwd(), "package.json"), import.meta.url]) {
+    try {
+      const mod = createRequire2(from)("@axe-core/playwright");
+      AxeBuilder = mod.default ?? mod;
+      break;
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  if (!AxeBuilder) {
     if (demanded) {
       console.warn(
-        `ultra11y: axe was requested but @axe-core/playwright could not be resolved from ${process.cwd()} \u2014 ${e instanceof Error ? e.message : String(e)}. Install it, or set \`axe: false\`. The criteria axe decides stay to assess.`
+        `ultra11y: axe was requested but @axe-core/playwright could not be resolved from ${process.cwd()} nor from this package \u2014 ${lastError instanceof Error ? lastError.message : String(lastError)}. Install it, or set \`axe: false\`. The criteria axe decides stay to assess.`
       );
     }
     return void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.14.0",
+  "version": "5.14.2",
   "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",
@@ -48,6 +48,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:perf": "vitest run --config vitest.perf.config.ts",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "bench": "node scripts/bench.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "biome ci .",
@@ -81,7 +82,9 @@
     "htmlparser2": "^12.0.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
     "@biomejs/biome": "^2.5.1",
+    "@playwright/test": "^1.62.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.0";
+var VERSION = "5.14.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -19918,6 +19918,7 @@ function isUrlPath(file) {
   return /^https?:\/\//i.test(file);
 }
 function repoRelative(file, baseDir) {
+  if (typeof file !== "string" || !file) return "";
   const posix3 = file.split("\\").join("/").replace(/^\.\//, "");
   const base = baseDir.split("\\").join("/").replace(/\/+$/, "");
   if (base && posix3.startsWith(`${base}/`)) return posix3.slice(base.length + 1);
@@ -58072,6 +58073,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else if (v === "NC") {
       if (!it.findings || it.findings.length === 0) blame(it.criteriaId, `criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
+        if (typeof f.file !== "string" || !f.file.trim()) {
+          blame(
+            it.criteriaId,
+            `criterion ${it.criteriaId}: an NC finding must name the file it was observed in \u2014 nobody can act on a non-conformity with no location`
+          );
+          continue;
+        }
         if (!f.normativeRef || !f.normativeRef.trim()) {
           blame(it.criteriaId, `criterion ${it.criteriaId}: an NC finding requires a normativeRef citing the failed test of the active standard`);
         } else if (!normativeRefResolves(f.normativeRef, adj.standard, isCore(adj.standard) ? void 0 : it.criteriaId)) {
@@ -58088,7 +58096,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else {
       blame(it.criteriaId, `criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
-    for (const rec of it.recommendations ?? []) toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    for (const rec of it.recommendations ?? []) {
+      if (typeof rec.file !== "string" || !rec.file.trim()) {
+        blame(it.criteriaId, `criterion ${it.criteriaId}: a recommendation must name the file it was observed in`);
+        continue;
+      }
+      toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    }
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
@@ -59694,7 +59708,9 @@ function localAvailable(cwd) {
     const req = createRequire(resolve12(cwd, "package.json"));
     req.resolve(PW_SPEC);
     req.resolve(AXE_SPEC);
-    return true;
+    const pw = req(PW_SPEC);
+    const bin = pw.chromium?.executablePath?.();
+    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
   } catch {
     return false;
   }

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 5.14.0
+  version: 5.14.2
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.0";
+var VERSION = "5.14.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -19918,6 +19918,7 @@ function isUrlPath(file) {
   return /^https?:\/\//i.test(file);
 }
 function repoRelative(file, baseDir) {
+  if (typeof file !== "string" || !file) return "";
   const posix3 = file.split("\\").join("/").replace(/^\.\//, "");
   const base = baseDir.split("\\").join("/").replace(/\/+$/, "");
   if (base && posix3.startsWith(`${base}/`)) return posix3.slice(base.length + 1);
@@ -58072,6 +58073,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else if (v === "NC") {
       if (!it.findings || it.findings.length === 0) blame(it.criteriaId, `criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
+        if (typeof f.file !== "string" || !f.file.trim()) {
+          blame(
+            it.criteriaId,
+            `criterion ${it.criteriaId}: an NC finding must name the file it was observed in \u2014 nobody can act on a non-conformity with no location`
+          );
+          continue;
+        }
         if (!f.normativeRef || !f.normativeRef.trim()) {
           blame(it.criteriaId, `criterion ${it.criteriaId}: an NC finding requires a normativeRef citing the failed test of the active standard`);
         } else if (!normativeRefResolves(f.normativeRef, adj.standard, isCore(adj.standard) ? void 0 : it.criteriaId)) {
@@ -58088,7 +58096,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else {
       blame(it.criteriaId, `criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
-    for (const rec of it.recommendations ?? []) toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    for (const rec of it.recommendations ?? []) {
+      if (typeof rec.file !== "string" || !rec.file.trim()) {
+        blame(it.criteriaId, `criterion ${it.criteriaId}: a recommendation must name the file it was observed in`);
+        continue;
+      }
+      toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    }
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
@@ -59694,7 +59708,9 @@ function localAvailable(cwd) {
     const req = createRequire(resolve12(cwd, "package.json"));
     req.resolve(PW_SPEC);
     req.resolve(AXE_SPEC);
-    return true;
+    const pw = req(PW_SPEC);
+    const bin = pw.chromium?.executablePath?.();
+    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
   } catch {
     return false;
   }

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 5.14.0
+  version: 5.14.2
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.14.0";
+var VERSION = "5.14.2";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -19918,6 +19918,7 @@ function isUrlPath(file) {
   return /^https?:\/\//i.test(file);
 }
 function repoRelative(file, baseDir) {
+  if (typeof file !== "string" || !file) return "";
   const posix3 = file.split("\\").join("/").replace(/^\.\//, "");
   const base = baseDir.split("\\").join("/").replace(/\/+$/, "");
   if (base && posix3.startsWith(`${base}/`)) return posix3.slice(base.length + 1);
@@ -58072,6 +58073,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else if (v === "NC") {
       if (!it.findings || it.findings.length === 0) blame(it.criteriaId, `criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
+        if (typeof f.file !== "string" || !f.file.trim()) {
+          blame(
+            it.criteriaId,
+            `criterion ${it.criteriaId}: an NC finding must name the file it was observed in \u2014 nobody can act on a non-conformity with no location`
+          );
+          continue;
+        }
         if (!f.normativeRef || !f.normativeRef.trim()) {
           blame(it.criteriaId, `criterion ${it.criteriaId}: an NC finding requires a normativeRef citing the failed test of the active standard`);
         } else if (!normativeRefResolves(f.normativeRef, adj.standard, isCore(adj.standard) ? void 0 : it.criteriaId)) {
@@ -58088,7 +58096,13 @@ function applyAdjudication(audit2, adj, opts = {}) {
     } else {
       blame(it.criteriaId, `criterion ${it.criteriaId}: unknown verdict "${String(v)}" \u2014 expected one of ${VERDICTS.join(" | ")}`);
     }
-    for (const rec of it.recommendations ?? []) toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    for (const rec of it.recommendations ?? []) {
+      if (typeof rec.file !== "string" || !rec.file.trim()) {
+        blame(it.criteriaId, `criterion ${it.criteriaId}: a recommendation must name the file it was observed in`);
+        continue;
+      }
+      toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    }
   }
   const grounding = { grounded: 0, moved: 0, failed: 0, issues: [] };
   for (const [criteriaId, inputs] of groundInputs) {
@@ -59694,7 +59708,9 @@ function localAvailable(cwd) {
     const req = createRequire(resolve12(cwd, "package.json"));
     req.resolve(PW_SPEC);
     req.resolve(AXE_SPEC);
-    return true;
+    const pw = req(PW_SPEC);
+    const bin = pw.chromium?.executablePath?.();
+    return typeof bin !== "string" || bin.length === 0 ? true : existsSync24(bin);
   } catch {
     return false;
   }

package/src/adjudicate.ts

@@ -879,6 +879,18 @@ export function applyAdjudication(
     } else if (v === "NC") {
       if (!it.findings || it.findings.length === 0) blame(it.criteriaId, `criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
+        // AN NC NOBODY CAN OPEN IS NOT A FINDING. Checked before the normativeRef, because a
+        // finding with no file cannot be grounded at all — there is nothing to go and read.
+        // Measured once: a model returned an NC with no `file`, the fold minted it anyway, and
+        // it reached `repoRelative`, which crashed on `undefined.split` and took SARIF, the
+        // annotations, the comment, the report, the HTML and the artifact upload with it.
+        if (typeof f.file !== "string" || !f.file.trim()) {
+          blame(
+            it.criteriaId,
+            `criterion ${it.criteriaId}: an NC finding must name the file it was observed in — nobody can act on a non-conformity with no location`,
+          );
+          continue;
+        }
         // FAIL-CLOSED: every NC finding must cite a precise, resolvable test of the active
         // standard. A good practice with no normative test is a recommendation, not an NC.
         if (!f.normativeRef || !f.normativeRef.trim()) {
@@ -905,7 +917,15 @@ export function applyAdjudication(
     // Recommendations are independent of the verdict (a C criterion may still carry a good
     // practice) and are grounded exactly like an NC finding — no normativeRef required, as
     // a recommendation has no normative test by definition.
-    for (const rec of it.recommendations ?? []) toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    for (const rec of it.recommendations ?? []) {
+      // Same contract, same reason: a recommendation is rendered through the very surfaces an
+      // NC is, so one with no location breaks them just as thoroughly.
+      if (typeof rec.file !== "string" || !rec.file.trim()) {
+        blame(it.criteriaId, `criterion ${it.criteriaId}: a recommendation must name the file it was observed in`);
+        continue;
+      }
+      toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    }
   }
 
   // Content-level grounding of every agent NC finding, every C/NA citation, and every

package/src/integrations/playwright.ts

@@ -90,15 +90,27 @@ async function runAxe(page: PlaywrightPage, mode: boolean | "auto" | undefined):
   const demanded = mode === true;
   // biome-ignore lint/suspicious/noExplicitAny: the builder's shape is axe's, which is not a dependency here
   let AxeBuilder: any;
-  try {
-    const req = createRequire(join(process.cwd(), "package.json"));
-    const mod = req("@axe-core/playwright");
-    AxeBuilder = mod.default ?? mod;
-  } catch (e) {
+  // PROJECT FIRST, then relative to this module — the same order the Playwright fixture above
+  // and `scan --runtime local` use, and for the same reason: module-relative alone works for an
+  // ordinary `node_modules/ultra11y` install but yields nothing whenever the package is linked,
+  // pnpm-hoisted elsewhere, or in a monorepo. Anchoring on the cwd ALONE is just as wrong in the
+  // other direction — a suite that changes directory to write its snapshot then resolves nothing
+  // at all, and the pass evaporates silently because the default is `auto`.
+  let lastError: unknown;
+  for (const from of [join(process.cwd(), "package.json"), import.meta.url]) {
+    try {
+      const mod = createRequire(from)("@axe-core/playwright");
+      AxeBuilder = mod.default ?? mod;
+      break;
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  if (!AxeBuilder) {
     if (demanded) {
       console.warn(
-        `ultra11y: axe was requested but @axe-core/playwright could not be resolved from ${process.cwd()} — ${
-          e instanceof Error ? e.message : String(e)
+        `ultra11y: axe was requested but @axe-core/playwright could not be resolved from ${process.cwd()} nor from this package — ${
+          lastError instanceof Error ? lastError.message : String(lastError)
         }. Install it, or set \`axe: false\`. The criteria axe decides stay to assess.`,
       );
     }

package/src/scan-local.ts

@@ -59,14 +59,29 @@ interface LocalDeps {
 const PW_SPEC = "@playwright/test";
 const AXE_SPEC = "@axe-core/playwright";
 
-/** Resolvable WITHOUT loading (cheap auto-detection): @playwright/test + @axe-core/playwright
- *  both resolve from `--cwd`. */
+/** Is the LOCAL tier actually usable from `cwd`? Drives `runtime: auto`.
+ *
+ *  Both packages must resolve — and the browser BINARY must be on disk. The second half is not
+ *  belt-and-braces: `npm i @playwright/test` installs the package, `npx playwright install`
+ *  installs the browsers, and the two are separate steps that CI images routinely do only one
+ *  of. Resolution alone therefore says "local is available" on a machine that cannot launch
+ *  anything, and `auto` — whose whole contract is to degrade to Docker when the local tier is
+ *  not there — instead picks it and dies on the launch.
+ *
+ *  Measured on this repository the day Playwright became a devDependency: three `--runtime
+ *  local` tests and the action's own crawl job switched themselves on in jobs that install no
+ *  browser, and failed rather than degrading. `executablePath()` is a pure path computation, so
+ *  this stays cheap: no launch, no download, one `stat`. */
 export function localAvailable(cwd: string): boolean {
   try {
     const req = createRequire(resolve(cwd, "package.json"));
     req.resolve(PW_SPEC);
     req.resolve(AXE_SPEC);
-    return true;
+    const pw = req(PW_SPEC) as { chromium?: { executablePath?: () => string } };
+    const bin = pw.chromium?.executablePath?.();
+    // No path at all ⇒ a Playwright that cannot tell us; treat as available and let the launch
+    // report its own failure, rather than refusing a tier that might work.
+    return typeof bin !== "string" || bin.length === 0 ? true : existsSync(bin);
   } catch {
     return false;
   }

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "5.14.0";
+export const VERSION = "5.14.2";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,

package/src/util.ts

@@ -36,6 +36,13 @@ export function isUrlPath(file: string): boolean {
  *  under `baseDir`; leave it as-is when it does not, rather than inventing a path that
  *  resolves nowhere. */
 export function repoRelative(file: string, baseDir: string): string {
+  // A finding with no file at all. It should never reach here — the adjudication fold refuses
+  // an NC that names none — but an AuditResult can also be hand-written or produced by an
+  // external tool's adapter, and neither goes through that gate. Measured once: one such
+  // finding threw here and took SARIF, the annotations, the pull-request comment, the report,
+  // the HTML and the artifact upload with it, because every one of those steps runs after.
+  // A rendering surface that explodes on bad input tells its reader nothing at all.
+  if (typeof file !== "string" || !file) return "";
   const posix = file.split("\\").join("/").replace(/^\.\//, "");
   const base = baseDir.split("\\").join("/").replace(/\/+$/, "");
   if (base && posix.startsWith(`${base}/`)) return posix.slice(base.length + 1);