@surea11y/core 1.2.0 → 1.3.0

package/docs/CLI.md

@@ -21,9 +21,11 @@ The CLI reads **static HTML only** — a local file, or the raw response of an H
 | `--exclude-rules <ids>` | Comma-separated rule IDs — never run these. |
 | `--tags <tags>` | Comma-separated tags — e.g. `--tags wcag2a,wcag2aa` to target a conformance level (see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md)). |
 | `--context <selector>` | Scope the scan to one CSS-selected subtree. |
+| `--custom-rules <path>` | Load runtime custom rules from a local JS file. Repeatable. See [Custom rules](#custom-rules) below. |
 | `--write-baseline <path>` | Write every current `fail` occurrence to `<path>`; never fails the build. See [`BASELINE.md`](./BASELINE.md). |
 | `--baseline <path>` | Gate only on occurrences not already recorded in `<path>`. See [`BASELINE.md`](./BASELINE.md). |
 | `--html <path>` | Write a self-contained, browsable HTML report to `<path>`. See [`REPORT.md`](./REPORT.md). |
+| `--sarif <path>` | Write a SARIF 2.1.0 report to `<path>` (e.g. for GitHub Code Scanning). See [`SARIF.md`](./SARIF.md). |
 | `-h`, `--help` | Show usage. |
 | `-v`, `--version` | Show the installed version. |
 
@@ -52,6 +54,47 @@ surea11y scan ./dist/index.html --baseline baseline.json         # in CI, from t
 
 See [`BASELINE.md`](./BASELINE.md) for the matching semantics, file format, and known limitations.
 
+## Custom rules
+
+For an org-specific check that isn't (and shouldn't be) one of the built-in rules — an internal design-system convention, a company style-guide requirement — `--custom-rules <path>` registers your own rule(s) for that one scan, on top of every built-in rule:
+
+```sh
+surea11y scan ./dist/index.html --custom-rules ./a11y-rules.js
+```
+
+`a11y-rules.js` exports either a single rule descriptor or an array of them, using the same shape as a built-in rule module:
+
+```js
+// a11y-rules.js
+module.exports = [
+  {
+    id: 'org-no-inline-onclick',
+    meta: { title: 'No inline onclick handlers', defaultSeverity: 'moderate' },
+    runInPage(ctx) {
+      const els = ctx.helpers.queryAll('[onclick]');
+      const occurrences = els.map((el) => ({
+        selector: ctx.helpers.buildSelector(el),
+        html: el.outerHTML,
+        summary: 'Inline onclick handler found.',
+        hint: 'Move event handling into an external script.'
+      }));
+      return {
+        ruleId: ctx.rule.ruleId,
+        outcome: occurrences.length ? 'fail' : 'pass',
+        occurrences
+      };
+    }
+  }
+];
+```
+
+- `<path>` is a **local file**, `require()`d directly by the CLI — never a URL. (Unlike the scan target, which does accept a URL: fetching and executing remote code as a rule would be a very different, much riskier trust model than running a file you already have on disk.)
+- Because the CLI runs your rule in the same Node process as the scan, `runInPage`/`applicability` can be plain functions — no `fn.toString()` string-source workaround needed (that's only required for callers, like a browser-automation binding, whose `engineOptions` crosses a serialization boundary). See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) for the full descriptor contract (`meta` defaulting, the `ctx` shape, etc.) — it's identical here.
+- Repeat the flag to load rules from more than one file: `--custom-rules ./a.js --custom-rules ./b.js`.
+- A custom rule's `id` colliding with a built-in one **overrides** that built-in for the scan, surfaced via a `console.warn` and the result's top-level `overriddenBuiltinIds` array — see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md).
+- The file itself is validated at load time (must export a descriptor, or array of descriptors, each with a string `id` and a function-or-source-string `runInPage`) — a malformed export exits `2` with a clear error rather than silently scanning with one fewer rule than expected.
+- Works alongside every other flag, including `--rules`/`--exclude-rules`/`--tags` (which can target your custom rule's `id` exactly like a built-in one) and `--baseline`/`--html`/`--sarif`.
+
 ## HTML report
 
 For a browsable view of a scan's results — hero summary, WCAG rollup grouped by conformance level, and a searchable/filterable occurrence table — rather than raw JSON or a terminal summary:
@@ -62,13 +105,23 @@ surea11y scan ./dist/index.html --html report.html
 
 Open `report.html` directly from disk; no server, no external assets. Works alongside any other output mode. See [`REPORT.md`](./REPORT.md).
 
+## SARIF report
+
+For GitHub Code Scanning or another SARIF-consuming dashboard:
+
+```sh
+surea11y scan ./dist/index.html --sarif results.sarif
+```
+
+Works alongside any other output mode, and alongside `--baseline` (already-known `fail` occurrences are omitted from the SARIF output rather than re-reported). See [`SARIF.md`](./SARIF.md).
+
 ## In CI
 
 ```sh
 npx @surea11y/core scan ./dist/index.html || exit 1
 ```
 
-Or, since the exit code already reflects pass/fail, just let the command's own exit code propagate — most CI systems fail the step automatically on a non-zero exit.
+Or, since the exit code already reflects pass/fail, just let the command's own exit code propagate — most CI systems fail the step automatically on a non-zero exit. See [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md) for ready-to-paste GitHub Actions and Bitbucket Pipelines templates, including a SARIF-upload example.
 
 ## A note on dependencies
 

package/docs/ENGINE_OPTIONS.md

@@ -224,6 +224,8 @@ See the option-by-option table above for anything not shown here, and the `custo
 
 Every shipped rule is baked into `src/core.js` at build time. `engineOptions.customRules` is the runtime escape hatch: an array of rule descriptors registered for that one call only — nothing is added to the static catalog (`getRulesCatalog()`/`getChecksCatalog()`), and nothing persists between calls. This is deliberate, not a limitation to work around: surea11y already takes fresh `engineOptions` per call with no mutable global config (unlike some other engines, which need a `configure()`/`reset()` step against a shared runtime), and custom rules follow that same per-call model.
 
+Calling the library directly is one way in; the CLI also exposes this via `--custom-rules <path>` (a local file, loaded once per scan) — see [`CLI.md`](./CLI.md#custom-rules).
+
 A descriptor has the *same shape as an internal rule module's own export* — if you already know how to write a rule file for this engine, you already know this API:
 
 ```js

package/docs/INTEGRATION.md

@@ -91,6 +91,24 @@ const result = await page.evaluate(wrapperFn, {
 
 This is the only pattern that gives every rule real computed layout, so it's the one to reach for if you need `target-size-minimum` or any other geometry-dependent check to actually run instead of reporting `notApplicable`.
 
+## Pattern 3 — a standalone `<script>` tag (no driver, no bundler)
+
+Good for: a manual check against a page open in a real browser, a bookmarklet, or any other context where there's no automation driver and no build step to reach for.
+
+`@surea11y/core` ships `surea11y.browser.js` at the package root, a bundle generated from the same rule sources as `src/core.js`. Loading it directly defines one global, `a11ycore`:
+
+```html
+<script src="node_modules/@surea11y/core/surea11y.browser.js"></script>
+<script>
+  const result = a11ycore.runa11yCoreInPage(location.href, null, {}, null);
+  console.log(result.checksResults.filter((r) => r.outcome === 'fail'));
+</script>
+```
+
+`a11ycore.runa11yCoreInPage` is the exact same function described in Pattern 2 above — the bundle exists only to solve *loading* it without `require`/a module system, not to add a separate API surface. It carries the same self-containment property (own inlined rule catalog, no free variables), which is what makes a plain `<script>` tag sufficient.
+
+Deliberately excluded from this bundle: `runa11yCoreAcrossFrames`/`a11yCoreEnableFrameResponder`. Cross-frame scanning needs the embedded frame to load the engine and opt in too (see "Cross-frame scanning" below) — not a fit for a single dropped-in script tag. Use the npm package directly if you need it.
+
 ## Scoping a scan to part of the page
 
 Pass a CSS selector as the 2nd argument (`contextSelector`) to scan one subtree instead of the whole document — e.g. `runDomRulesInPage(url, '#app', {}, null)` to skip a surrounding CMS chrome you don't control. Pass an array of selectors (or a single comma-separated selector string) to scan multiple, possibly disjoint regions in one run — e.g. `runDomRulesInPage(url, ['#header', '#main'], {}, null)`. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) for the full `contextSelector` reference and for `excludeSelectors`, the complementary "skip specific elements anywhere" option.

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/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,13 +1,13 @@
 {
   "name": "@surea11y/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Lightweight DOM rules accessibility core with modular rules.",
   "main": "src/index.js",
   "bin": {
     "surea11y": "bin/core.js"
   },
   "author": "Jorge Rumoroso",
-  "license": "MIT",
+  "license": "MPL-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rumoroso/surea11y-core.git"
@@ -25,6 +25,7 @@
   "files": [
     "src",
     "bin",
+    "surea11y.browser.js",
     "docs/**/*.md",
     "README.md",
     "LICENSE",
@@ -36,9 +37,14 @@
     "!src/explain"
   ],
   "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:coverage": "npm run build && node scripts/run-tests.js --experimental-test-coverage --test-coverage-include=src/**/*.js --test-coverage-include=bin/**/*.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",
@@ -56,6 +62,11 @@
     "jsdom": "^29.1.1"
   },
   "devDependencies": {
-    "playwright": "^1.61.1"
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.8.0",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6"
   }
 }