@surea11y/core 1.2.0 → 1.4.0

package/docs/LIMITATIONS.md

@@ -14,7 +14,7 @@ surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at
 
 - **jsdom (Node, no real browser) has no CSS layout engine.** Rules needing real geometry — most notably `target-size-minimum` (WCAG 2.5.8, needs real `getBoundingClientRect()`) — report `notApplicable` under plain jsdom rather than guess. Run under a real browser (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules.
 - **`<dialog>` and other elements hidden by the default UA stylesheet** (no `open` attribute, `display: none` by spec), along with any other subtree hidden via `display:none`, `visibility:hidden`, `[hidden]`, or closed `<details>`, are **excluded from rule evaluation by default** — matching the visibility-aware behavior of other established engines. This is a deliberate default (`engineOptions.includeHiddenElements: false`), not an oversight: hidden content isn't reachable by assistive technology or keyboard until it's shown, so flagging a markup defect inside it by default would often be noise. Set `engineOptions.includeHiddenElements: true` to evaluate hidden/collapsed subtrees anyway — e.g. to catch a markup defect (like a broken ARIA ID reference) before a dialog ever opens. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#engineoptions--the-rest) for the option and exactly which hiding mechanisms it covers.
-- **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/core scan <url>`) specifically fetches static HTML only, with no JS execution — see [`CLI.md`](./CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. Other engines running inside an actual loaded browser tab see the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with either engine's rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
+- **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/cli scan <url>`) specifically fetches static HTML only, with no JS execution — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. Other engines running inside an actual loaded browser tab see the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with either engine's rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
 
 ## Deliberately not attempted — judgment calls, not automatable safely
 

package/docs/OUTPUT_SCHEMA.md

@@ -56,7 +56,7 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 
 - `topFrame` is exactly the [top-level result](#top-level-result) shape, for the frame the function was called in.
 - `frames` has one entry per direct child `<iframe>`/`<frame>` in the scanned scope. A reachable child (one that called `a11yCoreEnableFrameResponder()`) contributes its own complete `{ url, topFrame, frames }` — including *its own* nested `frames`, recursively, since a further-nested grandchild is only reachable through its immediate parent. An unreachable child (the common case for most third-party embeds — no cooperating responder, or it timed out) contributes `{ url, error }` instead, and does not abort the rest of the scan.
-- This is a **tree, not a flat list** — a deliberate difference from the `surea11y-playwright` binding's `.frames(true)`, which *can* flatten because Playwright's `page.frames()` already gives every frame regardless of nesting depth; a `postMessage` relay has no such global view, so nesting is expressed structurally instead.
+- This is a **tree, not a flat list** — a deliberate difference from the `@surea11y/playwright` binding's `.frames(true)`, which *can* flatten because Playwright's `page.frames()` already gives every frame regardless of nesting depth; a `postMessage` relay has no such global view, so nesting is expressed structurally instead.
 
 ## A check result (`checksResults[i]`)
 

package/docs/REPORT.md

@@ -18,7 +18,7 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 ## Library usage
 
 ```js
-const { renderHtmlReport } = require('@surea11y/core/src/report');
+const { renderHtmlReport } = require('@surea11y/core/report');
 const { runDomRulesInPage } = require('@surea11y/core');
 
 const result = runDomRulesInPage(url, null, {}, null);

package/docs/RULE_CATALOG.md

@@ -134,7 +134,7 @@ See [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) for what `type`/`confidence`/`sever
 | `region` | Page content should be inside a landmark region | — | — | medium | minor |
 | `scope-attr-valid` | scope attribute must have a valid value | — | — | medium | minor |
 | `scrollable-region-focusable` | Scrollable regions with no focusable content should be keyboard-focusable | 2.1.1, 2.1.3 | AAA | low | moderate |
-| `skip-link` | Skip link must have a resolvable target | — | — | medium | minor |
+| `skip-link` | Skip link must have a resolvable, usable target | — | — | medium | minor |
 | `svg-text-alternative-quality` | <svg> text alternative must be appropriate (manual review) | 1.1.1 | A | medium | minor |
 | `tabindex` | tabindex should not be greater than 0 | — | — | medium | minor |
 | `table-duplicate-name` | Table caption must not duplicate its summary attribute | — | — | medium | minor |

package/docs/SARIF.md

@@ -0,0 +1,59 @@
+# SARIF report
+
+`--sarif <path>` writes a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) log — the standard format GitHub Code Scanning (and other SARIF-consuming dashboards) expect — instead of, or alongside, `--json`'s raw engine result.
+
+```sh
+surea11y scan ./dist/index.html --sarif results.sarif
+```
+
+See [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md) for a ready-to-paste GitHub Actions workflow that runs a scan and uploads `results.sarif` to the "Security" tab.
+
+## Why a separate format from `--json`
+
+`--json`'s raw result (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)) is this engine's own contract, versioned and stable per [`API_STABILITY.md`](./API_STABILITY.md). SARIF is a different, externally-defined contract purpose-built for code-scanning dashboards — a `checksResults[]` entry and a SARIF `result` don't map 1:1, so this is a real conversion, not a re-serialization.
+
+## What becomes a SARIF result
+
+Only `fail`/`cantTell` occurrences produce SARIF results — a `pass`/`notApplicable` check has no occurrences to report at all (same "violations only" framing as [`REPORT.md`](./REPORT.md)'s HTML report).
+
+| Engine outcome | SARIF `level` | Meaning |
+|---|---|---|
+| `fail` | `error` | Deterministic, high-confidence violation — the CI-gating case. |
+| `cantTell` | `warning` | Needs human review — surfaced, but shouldn't block a build on its own. |
+
+Every rule that ran (regardless of whether it produced a result) is listed once in `runs[0].tool.driver.rules`, with `defaultConfiguration.level` set from the rule's `type`: `automatic` (fail-capable) → `error`, `manual` (capped at `cantTell`) → `warning`.
+
+## Field mapping
+
+| SARIF field | Source |
+|---|---|
+| `results[].ruleId` | `checksResults[i].ruleId` |
+| `results[].message.text` | `occurrence.summary` + `occurrence.hint` |
+| `results[].locations[].physicalLocation.artifactLocation.uri` | The scanned target — see "Locations" below. |
+| `results[].locations[].logicalLocations[].fullyQualifiedName` | `occurrence.selector`, when present. |
+| `results[].partialFingerprints["surea11y/violation/v1"]` | The same `ruleId + reasonCode + html` identity key used by [`BASELINE.md`](./BASELINE.md) (`computeBaselineKey`) — a stable, content-based fingerprint rather than a position-based one. |
+| `results[].properties.severity` / `.confidence` | `checksResults[i].severity` / `.confidence` — informational, not part of SARIF's own schema. |
+| `tool.driver.rules[].properties.tags` | `accessibility`, `automatic`/`manual`, and a `wcag-<SC>` tag per `meta.normativeMappings[].requirement`. |
+
+## Locations
+
+DOM-based scanning has no line/column to report, so `physicalLocation.artifactLocation.uri` is the scanned target itself, not a source-file position:
+
+- **Local file scans**: a path relative to the current working directory (forward-slashed). If this matches a real file in your repository, GitHub Code Scanning can render the finding as an inline annotation.
+- **URL scans**: the scanned URL itself. GitHub Code Scanning will still list the finding, but can't attach an inline annotation to a URL that isn't a file in the repository — this is inherent to how SARIF/Code Scanning associate findings with source, not a surea11y limitation. If you need inline annotations, scan the rendered HTML file (e.g. a build output artifact) rather than a live URL.
+
+`occurrence.selector` is additionally carried as a `logicalLocations[].fullyQualifiedName`, so a consumer that reads logical locations still gets the "which element" signal even without a usable physical location.
+
+## Combining with `--baseline`
+
+A generic SARIF consumer has no "known, don't gate on this" concept of its own — the only faithful way to honor a baseline in SARIF output is to omit already-known `fail` occurrences entirely, rather than downgrade them to `warning`:
+
+```sh
+surea11y scan ./dist/index.html --baseline baseline.json --sarif results.sarif
+```
+
+`cantTell` occurrences are never filtered by a baseline — the baseline mechanism only ever tracks `fail` occurrences (matching `--write-baseline`, see [`BASELINE.md`](./BASELINE.md)).
+
+## Combining with `--html`/`--json`
+
+`--sarif`, `--html`, and `--json` are independent output flags — pass any combination in one run; each writes/prints its own report from the same single scan.

package/package.json

@@ -1,20 +1,50 @@
 {
   "name": "@surea11y/core",
-  "version": "1.2.0",
-  "description": "Lightweight DOM rules accessibility core with modular rules.",
+  "version": "1.4.0",
+  "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "wcag21",
+    "wcag22",
+    "accessibility-testing",
+    "a11y-testing",
+    "audit",
+    "aria",
+    "contrast",
+    "sarif",
+    "zero-dependencies",
+    "jsdom",
+    "playwright",
+    "puppeteer",
+    "selenium",
+    "cypress",
+    "webdriverio",
+    "jest",
+    "vitest"
+  ],
   "main": "src/index.js",
   "bin": {
-    "surea11y": "bin/core.js"
+    "surea11y-core": "bin/surea11y-core.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./baseline": "./src/baseline.js",
+    "./report": "./src/report.js",
+    "./sarif": "./src/sarif.js",
+    "./browser": "./surea11y.browser.js",
+    "./package.json": "./package.json"
   },
   "author": "Jorge Rumoroso",
-  "license": "MIT",
+  "license": "MPL-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rumoroso/surea11y-core.git"
+    "url": "git+https://github.com/SureA11y/core.git"
   },
-  "homepage": "https://github.com/rumoroso/surea11y-core#readme",
+  "homepage": "https://github.com/SureA11y/core#readme",
   "bugs": {
-    "url": "https://github.com/rumoroso/surea11y-core/issues"
+    "url": "https://github.com/SureA11y/core/issues"
   },
   "engines": {
     "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
@@ -23,8 +53,14 @@
     "access": "public"
   },
   "files": [
-    "src",
-    "bin",
+    "src/index.js",
+    "src/core.js",
+    "src/baseline.js",
+    "src/report.js",
+    "src/sarif.js",
+    "src/checks/**/*.js",
+    "bin/surea11y-core.js",
+    "surea11y.browser.js",
     "docs/**/*.md",
     "README.md",
     "LICENSE",
@@ -32,13 +68,17 @@
     "!docs/RULE_TEMPLATE.md",
     "!docs/RULE_TEST_TEMPLATE.md",
     "!docs/RULE_TEST_AUTHORING.md",
-    "!docs/TEST_OUTCOME_STABILITY.md",
-    "!src/explain"
+    "!docs/TEST_OUTCOME_STABILITY.md"
   ],
   "scripts": {
-    "build": "node scripts/build-core.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.js\" \"bin/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"bin/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
+    "build": "node scripts/build-core.js && node scripts/build-browser.js",
     "pretest": "playwright install chromium",
-    "test": "npm run build && node scripts/run-tests.js",
+    "test": "npm run format:check && npm run build && node scripts/run-tests.js",
+    "test:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",
     "engine-perf-bench": "node --expose-gc scripts/engine-perf-bench.js  --profileRules=true --iters=25 --top=15",
@@ -50,12 +90,17 @@
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
-    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual"
-  },
-  "dependencies": {
-    "jsdom": "^29.1.1"
+    "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
+    "i18n:new": "node scripts/i18n-scaffold.js",
+    "i18n:report": "node scripts/i18n-report.js"
   },
   "devDependencies": {
-    "playwright": "^1.61.1"
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.8.0",
+    "jsdom": "^29.1.1",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6"
   }
 }

package/src/checks/automatic/area-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,7 +22,8 @@ const id = 'area-alt-present';
 
 const meta = {
   title: '<area> must have an alt attribute',
-  description: 'Checks that <area> elements provide an alt attribute to support a text alternative mechanism.',
+  description:
+    'Checks that <area> elements provide an alt attribute to support a text alternative mechanism.',
   i18n: {
     titleKey: 'area_altPresent_title',
     descriptionKey: 'area_altPresent_description'
@@ -29,7 +32,13 @@ const meta = {
   tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'imagemap', 'atomic', 'automatic'],
   wcagSc: ['1.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -46,25 +55,29 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-  const queryAll = helpers && typeof helpers.queryAll === 'function'
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
       ? helpers.queryAll
       : (sel) => {
-        try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
-        catch { return []; }
-      };
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
+        };
 
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-      ? helpers.getEligibilityInfo
-      : null;
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-      ? helpers.isAccTreeEligible
-      : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
-  const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
-      ? helpers.getAriaNameInfo
-      : null;
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
   // --- image-map semantics (rule-local) ---
 
@@ -72,7 +85,7 @@ function runInPage(ctx) {
     try {
       const s = String(val || '').trim();
       if (!s) return '';
-      return (s[0] === '#') ? s.slice(1).trim().toLowerCase() : s.toLowerCase();
+      return s[0] === '#' ? s.slice(1).trim().toLowerCase() : s.toLowerCase();
     } catch {
       return '';
     }
@@ -92,7 +105,8 @@ function runInPage(ctx) {
   const __usemapIndex = (() => {
     const idx = new Map();
     try {
-      const imgs = document && document.querySelectorAll ? document.querySelectorAll('img[usemap]') : [];
+      const imgs =
+        document && document.querySelectorAll ? document.querySelectorAll('img[usemap]') : [];
       for (const img of imgs) {
         if (!img || !img.getAttribute) continue;
         const u = normUsemap(img.getAttribute('usemap'));
@@ -120,8 +134,11 @@ function runInPage(ctx) {
   }
 
   const areas = (() => {
-    try { return Array.from((queryAllSmart ? queryAllSmart('area') : queryAll('area')) || []); }
-    catch { return queryAll('area'); }
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('area') : queryAll('area')) || []);
+    } catch {
+      return queryAll('area');
+    }
   })();
 
   if (!areas.length) {
@@ -143,7 +160,11 @@ function runInPage(ctx) {
     // This is the "visibility of map/area doesn't matter; the image does" policy.
     if (isAccTreeEligible) {
       const imgElig = (() => {
-        try { return isAccTreeEligible(img, ctx); } catch { return { eligible: true, reasons: [] }; }
+        try {
+          return isAccTreeEligible(img, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
       })();
       if (imgElig && imgElig.eligible === false) continue;
     }
@@ -151,7 +172,11 @@ function runInPage(ctx) {
     // 2) The <area> itself must be eligible (aria-hidden/inert exceptions handled by helper).
     if (isAccTreeEligible) {
       const elig = (() => {
-        try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
       })();
       if (elig && elig.eligible === false) continue;
     }
@@ -166,7 +191,7 @@ function runInPage(ctx) {
     // text-alternative mechanism for <area> (HTML-AAM accessible name
     // computation includes ARIA naming before falling back to alt).
     if (getAriaNameInfo) {
-      let ariaName = null;
+      let ariaName;
       try {
         ariaName = getAriaNameInfo(el, ctx);
       } catch {
@@ -176,13 +201,15 @@ function runInPage(ctx) {
     }
 
     // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent -- also accepted by a widely-used
-    // reference engine's equivalent area-alt rule (non-empty-title, same "any" list as
-    // non-empty-alt/aria-label/aria-labelledby). See img-alt-present's
-    // sibling fix (2026-07-23, AliExpress's title-only logo <img>) for
-    // the real page this was found via -- same gap, same fix, different
-    // element.
-    const titleRaw = (() => { try { return el.getAttribute('title'); } catch { return null; } })();
+    // source once alt is entirely absent. Same gap img-alt-present handles
+    // for <img title="..."> with no alt.
+    const titleRaw = (() => {
+      try {
+        return el.getAttribute('title');
+      } catch {
+        return null;
+      }
+    })();
     if (titleRaw !== null && String(titleRaw).trim()) continue;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
@@ -219,7 +246,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'minor',
+    occurrences
+  };
 }
 
 module.exports = { id, meta, runInPage };