@surea11y/core 1.5.0 → 1.7.0

package/docs/RULE_HELPERS.md

@@ -0,0 +1,333 @@
+# RULE_HELPERS.md — `ctx.helpers` Reference (Canonical, repo-derived)
+
+This is the full reference for `ctx.helpers`, the object every rule's `runInPage(ctx)`
+receives (`const { helpers } = ctx`, per [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) §6).
+It exists because that doc's own helpers section only calls out the dozen or so most
+common ones — the underlying object (`createDomHelpers()` in `src/core/dom-helpers.js`)
+exports around 35, and several of them replace logic a new rule would otherwise
+duplicate (often incorrectly — see the naming helpers below).
+
+Read [`RULE_AUTHORING.md`](./RULE_AUTHORING.md) first for the rule contract itself
+(module shape, `runInPage` constraints, occurrence reporting). This doc only covers
+what each helper does and when to reach for it.
+
+All helpers below are called as `helpers.<name>(...)` from inside `runInPage`. None of
+them may be assigned to a module-scope variable and closed over — same
+serialization constraint as everything else in `runInPage` (§1 of `RULE_AUTHORING.md`).
+
+---
+
+## 1) Query & traversal
+
+### `queryAll(selector)` → `Element[]`
+Plain `querySelectorAll(selector)` across the resolved context root(s), deduped, with
+self-match included (a root element matching `selector` itself is returned, which
+`querySelectorAll` alone never does). Light DOM only.
+
+### `queryAllDeep(selector)` → `Element[]`
+Same as `queryAll`, but also descends into open shadow roots (BFS over discovered
+`shadowRoot`s). Ignores `includeShadowDom`/hidden-content policy — it's the raw
+traversal `queryAllSmart` builds on.
+
+### `queryAllSmart(selector)` → `Element[]`
+**The one almost every rule should use.** Honors `engineOptions.includeShadowDom`
+(shadow-aware by default), applies the default hidden-content policy (filters out
+`display:none`/`hidden`/etc. unless `includeHiddenElements:true`), and applies any
+rule-scoped `excludeSelectors`. See `RULE_AUTHORING.md` §6.1 — write rules assuming
+open shadow roots are in scope and let this helper honor the caller's choice.
+
+```js
+const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img') : helpers.queryAll('img');
+```
+
+### `composedParent(node)` → `Node | null`
+One step up the *flat tree*: `assignedSlot` first (a slotted node's rendered parent is
+its slot, not its light-DOM `parentNode`), then `parentNode`, then `.host` once you're
+at a `ShadowRoot`. Use this instead of `parentNode`/`closest` for any ancestor walk that
+must work correctly across shadow boundaries and slots.
+
+### `buildSimpleSelector(el, fallbackTag)` → `string`
+A short, non-unique selector for an element: `#id`, else a `data-testid`/`data-test`/
+`data-cy`/`data-qa` attribute selector, else `tag[name="..."]`, else just the tag name.
+Cheap; not guaranteed unique. Prefer `reportOccurrence` (§6 below) over building
+selectors by hand — see the perf note there.
+
+### `buildSelector(el)` → `string`
+The engine's real, best-effort-unique CSS selector builder (cached per element per
+run). Used internally by `reportOccurrence`'s finalization; rules generally don't need
+to call this directly.
+
+### `getOuterHtmlSnippet(el)` → `string`
+`el.outerHTML`, truncated to 2000 characters (with a trailing `…`) and cached per
+element per run. `reportOccurrence` (§6 below) already fills in an occurrence's `html`
+from the reported element, so most rules never call this directly — it's for the rare
+case where a rule needs the HTML snippet itself, not just an occurrence carrying it.
+
+### `isExcluded(el)` → `boolean`
+Whether `el` matches the currently effective `excludeSelectors` (global config ∪ the
+active rule's own `engineOptions.rules[ruleId].excludeSelectors`), via `closest()`.
+`queryAllSmart` already applies this filtering for you; reach for `isExcluded` directly
+only if a rule walks the DOM some other way (e.g. following `composedParent`) and still
+needs to respect exclusions on nodes found off that path.
+
+### `buildStructuralPath(node, selector)` → `number[] | null`
+Sibling-index path from the document root to `node` (or, given only a `selector`,
+re-resolves the element first — the same fallback `reportOccurrence` triggers, and the
+same one `perfStats.counters['structuralPath.selectorFallback']` counts, per
+`RULE_AUTHORING.md` §4.3). Rules don't normally call this either — it's what backs
+`selector`/`structuralPath` finalization for reported occurrences.
+
+---
+
+## 2) Eligibility & visibility
+
+These answer "is this node in scope" from different angles. They are easy to reach for
+the wrong one, so the distinctions matter:
+
+### `isAccTreeEligible(node)` → `{ eligible, reasons[] }`
+Whether a node is eligible for the accessibility tree, per an ordered set of checks
+(display/visibility, `hidden`, `inert`, closed `<details>`, template content, etc.).
+Deliberately keeps a focusable-but-`aria-hidden` element *eligible* — see the header
+comment on `isIncludedInAccessibilityTree` below for why.
+
+### `isIncludedInAccessibilityTree(el)` → `boolean`
+The narrower question most accessible-name rules actually want: `isAccTreeEligible`,
+minus anything eligible only because of an `ariaHiddenOverridden*` reason. ACT scopes
+name-computation rules (button-name, link-name, etc.) to elements genuinely included in
+the accessibility tree; a focusable element hidden by `aria-hidden` is a real
+issue, but it's `aria-hidden-focus`'s issue (WCAG 4.1.2), not a naming rule's — so
+naming rules should check this, not `isAccTreeEligible`, to avoid double-flagging the
+same element under the wrong rule.
+
+### `isDomVisibleEligible(node, ctx, opts)` → `{ eligible, reasons[], metrics }`
+Style/geometry-only visibility (not accessibility-tree membership): `display`,
+`visibility`, size/position, opacity, etc. `opts.visibilityMode` (`'styleOnly'` |
+`'styleAndGeometry'`), `opts.disableGeometry`, `opts.ignoreOpacity` tune what's checked.
+Use when a rule cares about visual rendering specifically, not AT exposure.
+
+### `getEligibilityInfo(node, ctx, opts)` → `{ eligible, reasons[], targetSet, accEligible }`
+A single wrapper choosing between the two above via `opts.targetSet` (`'acc'` |
+`'dom'`, default `'dom'`). **This is also the shape `RULE_AUTHORING.md` §7 requires every
+occurrence to carry** as `data.visibilityFilter` — call this once per element and pass
+its result straight through.
+
+### `getVisibilityHintsInfo(el, ctx, opts)` → `{ hints[], metrics, flags[] }`
+Style-only visibility *hints* for triage/diagnostics (`opacityZero`, `clipped`, etc.) —
+explicitly does **not** decide eligibility; a rule's own logic still owns the outcome.
+
+### `isWholeDocumentScope()` → `boolean`
+`true` unless `engineOptions.fragment: true` was set, or `contextSelector` scoped the
+run narrower than the whole document. Required for any rule checking a page-wide,
+one-per-document property (`<title>`, `<html lang>`, landmark structure) — gate it with
+an `applicability(ctx)` export using this, per `RULE_AUTHORING.md` §4.2/§11.2, or the
+rule will wrongly fault a scoped subtree for lacking something it was never meant to
+have.
+
+### `hasTruncatedAncestorWalk` (internal)
+Backs confidence scoring during result normalization when a 200-step ancestor walk
+didn't reach the root. Not something a rule calls directly.
+
+---
+
+## 3) Accessible naming & labeling
+
+Naming is layered — each function below builds on the ones above it — and several exist
+specifically to replace a naive reimplementation that gets an edge case wrong. Reach for
+the highest-level one that answers your actual question before dropping to a primitive.
+
+### `getAriaLabelInfo(el)` → `{ present, value, mechanism, flags[] }`
+Just `aria-label`, trimmed, presence-checked.
+
+### `getAriaLabelledByInfo(el, ctx, opts)` → `{ present, value, mechanism, refsCount, missing[], flags[] }`
+Resolves `aria-labelledby` through `getTextFromIdRefs` (recursive, accname-aligned — see
+§4 below), not raw `textContent`.
+
+### `getAriaNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+ARIA-only name with correct precedence: `aria-labelledby` (if it resolves non-empty)
+wins over `aria-label`. Use this rather than checking the two attributes yourself when
+you specifically want "does ARIA name this," excluding native `<label>`/content/title.
+
+### `getLandmarkNameInfo(el, ctx)` → `{ present, value, mechanism, flags[] }`
+Landmark-role naming (`nav`/`main`/`region`/`banner`/`contentinfo`, etc.): ARIA name,
+then `title` — landmark roles don't get a name from content, and `title` must be
+included or two landmarks distinguished only by `title` both read as unnamed and get
+flagged as duplicates. Shared by all 7 landmark rule files; use this rather than
+reimplementing landmark naming in a new landmark rule.
+
+### `getAccessibleNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+The general-purpose accessible name: ARIA name → native `<label>` association → `alt`
+(image-like elements) → `title` (flagged `title-used` — see the policy note in the
+source; `title` is accepted per spec but is a weak mechanism in practice). This is what
+almost every naming rule should call.
+
+### `getAccessibleDescriptionInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+`aria-describedby` (via `getTextFromIdRefs`), then optionally `title` if
+`opts.allowTitle === true`.
+
+### `getTextAlternativeInfo(el, ctx, opts)` → `{ present, value, mechanism, requiredMechanism, flags[] }`
+Mechanism-aware text alternative for elements with a *specific required* mechanism:
+`alt` for `img`/`area`/`input[type=image]` (missing `alt` is flagged even when an
+accessible name exists elsewhere — that's still a real alt-text violation), fallback
+content or ARIA/`title` for `<canvas>`. Use this for alt-text-shaped rules, not
+`getAccessibleNameInfo`, when the rule cares which mechanism was used, not just whether
+a name exists.
+
+### `getContentNameInfo(el, ctx, opts)` → `{ present, value, mechanism, flags[] }`
+Recursive "name from content" (accname step 2F): walks children using each child's
+*own* accessible name (not just literal text), so `<a href="…"><img alt="Company
+Name"></a>` and `<button><span aria-label="Close"></span></button>` both name correctly.
+A plain `TreeWalker(SHOW_TEXT)` walk misses both.
+
+### `getAssociatedLabelElements(el)` → `Element[]`
+Real `<label>` element(s) associated with `el` — a `<label for="id">` pointing at it,
+plus a wrapping `<label>` whose first labelable descendant it is. **Does not call the
+native `.labels`/`.control` API** — in this project's supported jsdom runtime,
+`.labels` is an expensive whole-document walk per element (`.control` resolution is
+another one), which used to dominate whole-engine runtime on form-heavy pages. Use this
+whenever a rule needs the actual label element(s), not just a yes/no.
+
+### `labelContributesAccessibleName(labelEl)` → `boolean`
+Whether a `<label>` element itself carries text that would name its control: own
+ARIA name, else rendered content (`getContentNameInfo`, so `aria-hidden`/`display:none`
+descendants are correctly excluded), else its own `title`. Shared by
+`form-control-single-label` and `form-control-programmatic-label-present` so they agree
+on what "a label with content" means.
+
+### `getLabelMethod(el, ctx, opts)` → `{ method, value }`
+Which mechanism actually labels `el` — `'label'` | `'aria-labelledby'` |
+`'aria-label'` | `'title'` | `'placeholder'` | `'none'` — checked in that precedence
+order.
+
+### `getLabelStrength(method)` → `'strong' | 'medium' | 'weak' | 'none'`
+Policy classification of a `getLabelMethod` result (`label`/`aria-labelledby` →
+strong, `aria-label` → medium, `title`/`placeholder` → weak). Deterministic and
+intentionally tweakable in one place rather than per rule.
+
+### `hasAccessibleName(el)` → `boolean`
+Back-compat convenience: `!!getAccessibleNameInfo(el).value`.
+
+---
+
+## 4) IDREF resolution
+
+Backs `aria-labelledby`/`aria-describedby` and any other space-separated ID-reference
+attribute.
+
+### `resolveIdRefs(idrefString, ctx, opts)` → `{ refs: Element[], missing: string[], flags[] }`
+Splits and resolves a space-separated ID list to elements (deduped, cached per scope).
+`opts.maxRefs` truncates deterministically (adds `'truncated'` to `flags`).
+
+### `getTextFromIdRefs(idrefString, ctx, opts)` → `{ text, refsCount, missing[], flags[] }`
+Resolves refs, then computes **each target's own text alternative** recursively
+(accname-aligned — a referenced element's name is recomputed, not read as raw
+`textContent`), joins with spaces. This is what `getAriaLabelledByInfo`/
+`getAccessibleDescriptionInfo` call internally.
+
+### `getTextFromIdRefsIdrefEligible(idrefString, ctx, opts)` → `{ text, refsCount, missing[], excluded[], flags[] }`
+Same, but under IDREF eligibility rules specifically: hidden/`aria-hidden`/collapsed
+targets are still included (IDREF targets aren't scoped by visibility the way rendered
+content is — see the `root` note in the source), only `inert` targets are excluded.
+`excluded` lists `{ id, reasons }` for anything dropped.
+
+---
+
+## 5) Role & focusability
+
+### `getRoleInfo(el, ctx, opts)` → `{ role, source, flags[] }`
+Explicit `role` attribute if present (flags `'presentation'` for
+`presentation`/`none`, `'multiple-roles'` if it contains whitespace), else a small,
+deliberately minimal implicit-role mapping (`a[href]`→`link`, `button`→`button`,
+`input[type=checkbox]`→`checkbox`, etc.) unless `opts.disallowImplicit`.
+
+### `getFocusableInfo(el, ctx, opts)` → `{ focusable, tabbable, mechanism, flags[] }`
+Platform focusability: whether `el` can receive focus at all, and whether it's in the
+default tab order.
+
+### `hasLandmarkScopingAncestor(el, ctx)` → `boolean`
+Whether `el` sits inside a landmark-scoping ancestor — the role-aware
+sectioning-content/`<main>` check backing `<header>`/`<footer>`/`<aside>`'s conditional
+implicit roles (their implicit landmark role only applies when *not* nested inside
+certain ancestors). Available both as `helpers.hasLandmarkScopingAncestor` and
+`helpers.aria.hasLandmarkScopingAncestor` — same function, re-exported at the top level
+so landmark-check files don't need to reach into `aria.*` for it.
+
+---
+
+## 6) Attributes, language, reporting, outcomes
+
+### `getAttributeInfo(el, attrName)` → `{ present, value, mechanism, flags[] }`
+Generic trimmed-attribute presence/value check. Use for any plain attribute a rule
+inspects directly (not one of the naming/ARIA attributes above, which have their own
+dedicated helpers).
+
+### `isValidLanguageTag(value)` / `isRegisteredLanguageSubtag(subtag)` → `boolean`
+BCP 47 well-formedness **plus** a real IANA subtag-registry check — shape alone accepts
+`"eng"` or `"em-US"`, which look like language tags but use an unregistered primary
+subtag (the registry only lists a three-letter subtag when no two-letter one exists,
+so `"en"` is registered and `"eng"` is not). Use `isValidLanguageTag` for any
+`lang`/`xml:lang`-checking rule instead of a regex-only check.
+
+### `reportOccurrence(node, partial)` → occurrence object
+**Use this to build every occurrence.** Attaches the element so the engine fills in
+`selector`, `html`, and `structuralPath` centrally — see `RULE_AUTHORING.md` §4.3/§9 for
+the full contract and why hand-building these fields yourself is a real (measured:
+4 min → <1 s) performance regression on any rule reporting many occurrences.
+
+```js
+occurrences.push(helpers.reportOccurrence(el, {
+  summary: '…',
+  hint: '…',
+  i18n: { summaryKey: '…', hintKey: '…', params: { element: 'img' } },
+  data: { visibilityFilter: eligInfo }
+}));
+```
+
+### `resolveTieredOutcome(failOccurrences, cantTellOccurrences, severity)` → `{ outcome, severity, occurrences }`
+For a rule that collects two confidence tiers in one run — some findings confident
+enough for `fail`, others only `cantTell` ("needs human review"). Returns `fail` (with
+**both** tiers' occurrences, tagged via `occurrenceOutcome`) whenever any fail-tier
+finding exists, `cantTell` when only cantTell-tier findings exist, `pass` otherwise.
+Reach for this instead of the naive `if (fails.length) return fail(fails); else if
+(cantTells.length) return cantTell(cantTells);`, which silently drops every cantTell
+finding whenever at least one fail finding also exists on the page.
+
+### `getPerfStats()` / `resetPerfStats()`
+Only populated when the engine is run with `perfStats: true`. Not for rule logic —
+useful when profiling a new rule's hot paths during development.
+
+---
+
+## 7) Namespaced helper groups
+
+Two larger helper sets are exposed as namespaces rather than flattened, since their
+member counts and internal cohesion (contrast math, ARIA validity data) don't fit the
+flat `helpers.*` list above:
+
+### `helpers.contrast.*`
+Color/contrast math and text-run analysis: `parseCssColorToRgba`, `compositeRgba`,
+`relativeLuminance`, `contrastRatio`, `requiredRatio`, `isLargeText`,
+`computeEffectiveForeground`/`computeEffectiveBackground`, `getComputabilityBlocker`,
+`getTextScan`, `isInactiveUiComponent`, plus small numeric/formatting utilities
+(`clamp01`, `round2`, `toHex2`, `pxToPt`, `fontWeightLabel`, …). Backs the
+`contrast-*` rule family (`contrast-minimum`, `contrast-enhanced`,
+`contrast-computable`) — see `src/core/contrast-helpers.js` if you're extending that
+family specifically.
+
+### `helpers.aria.*`
+ARIA validity/taxonomy data and checks: `isValidAriaAttrName`, `getAttrValueType`,
+`validateAttrValue`, `getExplicitRole`, `getAllRoleTokens`, `isAbstractRole`,
+`isDeprecatedRole`, `isAuthorDiscouragedRole`, `isAuthorProhibitedRole`,
+`isDeprecatedAttr`, `getDeprecatedRoleGuidance`, `isKnownRole`, `isValidConcreteRole`,
+`getRequiredAttrsForRole`, `getRequiredOwnedRoles`, `getRequiredContextRoles`,
+`isRoleAllowedOnElement`, `getContainmentRole`, `getNativeRoleForElement`,
+`hasLandmarkScopingAncestor` (also re-exported flat, see §5). Backs the whole
+`aria-*` rule family — check here before hand-rolling role/attribute validity logic in
+a new ARIA rule.
+
+---
+
+## 8) Not for rule use
+
+`helpers.__setActiveRuleExcludeSelectors` exists on the object but is engine-internal —
+`dom-runner.js` calls it before invoking each rule to scope that rule's
+`engineOptions.rules[ruleId].excludeSelectors`. A rule itself never calls it.

package/docs/RULE_TAXONOMY.md

@@ -11,20 +11,41 @@ It reflects **what already exists in the rules and tests**, not theory.
 Encoded by: `meta.type`
 
 - `automatic`
-    - Rule makes a **normative decision**
-    - Allowed outcomes: `pass`, `fail`, `notApplicable`, and `cantTell` as a defensive fallback only (e.g. an internal-failure safety net, or a computability gate a rule can't resolve — see `contrast-minimum.js`/`contrast-enhanced.js`/`contrast-computable.js`/`target-size-minimum.js`), never as its primary intended path
+    - Rule **decides deterministically**, with no heuristics and no guessing
+    - Allowed outcomes: `pass`, `fail`, `notApplicable`, `cantTell`
+    - `cantTell` is the primary path in two distinct cases, and a defensive
+      fallback in a third:
+        - the rule decides that a real violation exists, but the violation does
+          not on its own establish that the mapped criterion fails — an ARIA
+          author requirement the exposed name, role and value survive
+          (`aria-valid-attr`, `aria-braille-equivalent`,
+          `aria-conditional-attr`), or the graded tier of a rule that fails
+          elsewhere (`aria-required-attr`, `aria-roles-valid`)
+        - the rule decides deterministically but claims no Success Criterion at
+          all (`aria-allowed-role`, tagged `best-practice`)
+        - the rule asks whether something is PRESENT, and its absence conveys
+          nothing false, while the question of whether what IS present is valid
+          belongs to a sibling rule that still fails
+          (`aria-required-children`, paired with `aria-prohibited-children`)
+        - a computability gate the rule cannot resolve, or an internal-failure
+          safety net (`contrast-minimum.js`/`contrast-enhanced.js`/
+          `contrast-computable.js`/`target-size-minimum.js`)
 - `manual`
-    - Rule signals **human review required**
+    - Rule signals **human review required**: it cannot decide at all
     - Allowed outcomes: `cantTell`, `notApplicable`
 
-Manual rules MUST NOT make normative failure decisions.
+Manual rules MUST NOT make normative failure decisions. The dividing line
+between the two types is whether the rule can decide, not which outcome it
+reports: an automatic rule that reports `cantTell` has decided, and is saying
+what it found; a manual rule reports `cantTell` because the question is not
+decidable from markup.
 
 ---
 
 ### 1.2 Intent
 Encoded by: **rule id suffix**
 
-Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's 125 rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
+Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's 130 rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
 
 - `present`
     - Verifies that a required **mechanism exists**
@@ -43,7 +64,7 @@ Intent determines whether a rule can be automatic.
 ### 1.3 Target Family
 Encoded by: **rule id prefix**
 
-Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's 125 rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
+Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's 130 rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
 
 - `img`
 - `area`

package/docs/SARIF.md

@@ -14,11 +14,30 @@ See [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md) for a ready-to-paste GitHub Act
 
 ## 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).
+Only `fail`/`cantTell` occurrences produce SARIF results (same "violations only" framing as [`REPORT.md`](./REPORT.md)'s HTML report).
+
+A `notApplicable` check is not always empty: a rule may attach one occurrence explaining why it had nothing to judge, which the contrast rules do when no text had a computable background. Those never become results — a consumer treats every result as an alert, and "this was not evaluated" is not one — but they are not dropped either. They are carried as `note`-level entries in `runs[0].invocations[0].toolExecutionNotices`, each naming the rule it came from via `associatedRule.id`:
+
+```json
+"invocations": [
+  {
+    "executionSuccessful": true,
+    "toolExecutionNotices": [
+      {
+        "level": "note",
+        "message": { "text": "No eligible text had computable contrast (eligible text nodes: 13). See the contrast computability rule for details." },
+        "associatedRule": { "id": "contrast-minimum" }
+      }
+    ]
+  }
+]
+```
+
+That keeps a SARIF-only pipeline from reading silence as a clean bill of health: no contrast alerts can mean the page is fine, or that contrast was never computable, and only the notice separates the two. The block is emitted only when there is something to say, so a run with nothing to report has no `invocations` key at all.
 
 | Engine outcome | SARIF `level` | Meaning |
 |---|---|---|
-| `fail` | `error` | Deterministic, high-confidence violation — the CI-gating case. |
+| `fail` | `error` | Deterministic 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`.

package/docs/TROUBLESHOOTING.md

@@ -18,7 +18,7 @@ Check the result's `error` field first — if it says `"<something> is not defin
 
 ## "A geometry-dependent rule (e.g. `target-size-minimum`) always says `notApplicable`"
 
-Plain jsdom (no real browser) doesn't implement CSS layout — `getBoundingClientRect()` always returns zero geometry. Rules that need real layout deliberately report `notApplicable` under jsdom rather than guess. Run through a real browser instead (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules. See [`LIMITATIONS.md`](./LIMITATIONS.md).
+Plain jsdom (no real browser) doesn't implement CSS layout — `getBoundingClientRect()` always returns zero geometry. Rules that need real layout report `notApplicable` under jsdom rather than guess. Run through a real browser instead (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules. See [`LIMITATIONS.md`](./LIMITATIONS.md).
 
 ## "I only see `fail`/`cantTell` occurrences — where's the list of elements that passed?"
 
@@ -28,7 +28,7 @@ By design, this engine never enumerates the elements a rule *passed* — only th
 
 Two common causes, in order of likelihood:
 
-1. **The element is excluded from the accessibility tree** — `aria-hidden="true"`, `display: none`, `visibility: hidden`, `hidden`, or an `inert` ancestor. Most rules deliberately skip content that's already invisible to assistive technology (checking a hidden element would be meaningless, and could produce a misleading `fail` on content no user encounters). Some rules explicitly opt out of this gating when it wouldn't make sense to (e.g. `no-autoplay-audio` — hidden audio still plays sound) — check the specific rule's file header comment (`@applicability`) in `src/checks/`.
+1. **The element is excluded from the accessibility tree** — `aria-hidden="true"`, `display: none`, `visibility: hidden`, `hidden`, or an `inert` ancestor. Most rules skip content that's already invisible to assistive technology, since checking a hidden element would be meaningless and could produce a misleading `fail` on content no user encounters. Some rules explicitly opt out of this gating when it wouldn't make sense to (e.g. `no-autoplay-audio` — hidden audio still plays sound) — check the specific rule's file header comment (`@applicability`) in `src/checks/`.
 2. **`excludeSelectors`** — if you've configured this (directly or inherited from a shared config), confirm the element in question isn't matched by it. Remember this can also be scoped to a single rule via `engineOptions.rules[ruleId].excludeSelectors` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#rule-scoped-excludeselectors)) — if a rule you expect to fire keeps coming back `notApplicable`/`pass` for one element only, check whether that rule specifically has its own exclude list configured, not just the global one.
 
 ## "Does a clean scan (`pass` everywhere) mean the page is WCAG conformant?"

package/docs/WCAG_CONFORMANCE.md

@@ -4,9 +4,9 @@ How individual rule results relate to a WCAG Success Criterion (SC), and what su
 
 ## The three layers
 
-1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 125.
+1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 130.
 2. **Facets** — a WCAG SC is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" (e.g. 1.1.1 Non-text Content has facets like `img-alt-attr-present`, `text-alternative-quality`, `decorative-null`) tracked in `src/coverage/wcag-facets.js`, each marked `full` (a rule decides it with high confidence), `partial` (a rule decides *part* of it — see each rule's own scope notes), or `manual` (no safe automated heuristic exists at all). Run `npm run coverage` to regenerate `coverage/coverage-report.md`, the per-SC facet breakdown.
-3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-31) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
+3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-33) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
 
 ## How a composite's outcome is computed
 
@@ -25,24 +25,48 @@ A composite's `data.details.contributors` array (see [`OUTPUT_SCHEMA.md`](./OUTP
 
 ## Targeting a conformance level (A / AA / AAA)
 
-Pass `runOnly.tags` (or `engineOptions.tags.include`) with one of `wcag2a`, `wcag2aa`, `wcag2aaa`:
+Pass `runOnly.tags` (or `engineOptions.tags.include`) with the level tags you want:
 
 ```js
-runDomRulesInPage(url, null, {}, { tags: ['wcag2aa'] });
+// WCAG 2.0 A and AA. Both tags are required: they are not cumulative.
+runDomRulesInPage(url, null, {}, { tags: ['wcag2a', 'wcag2aa'] });
 ```
 
-This does two things at once:
-- **Filters atomic rules** to ones tagged at or under that level (a `wcag2aa`-tagged rule also carries `wcag2a`, since AA is cumulative on top of A — WCAG conformance is always defined this way).
-- **Suppresses composites above the target level** — e.g. requesting `wcag2aa` will not return a `rulesResults` entry for an AAA-only SC's composite, even if some AAA-level atomic rules happen to be tagged loosely. This is `inferTargetLevelFromRunOnly`/`isAllowedByTargetLevel` in the runner — see `src/core/dom-runner.js` if you need the exact precedence logic.
-
-Omit `tags` entirely (the default) and every rule at every level runs, with no composite suppression.
+**Level tags do not nest, and this is the easiest thing to get wrong here.** A rule
+carries one level tag per Success Criterion it maps to, and nothing more: a rule
+mapped only to an AA criterion is tagged `wcag2aa` and *not* `wcag2a`. Asking for
+`{ tags: ['wcag2aa'] }` on its own therefore runs the 10 rules mapped to a 2.0 AA
+criterion, not the ~100 that make up an A + AA target. List every level you mean.
+
+The same applies across WCAG versions — a criterion introduced in 2.1 or 2.2 carries
+only its own origin tag — so a full conformance target is a union of tag sets. See
+[`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#filtering-by-wcag-version-21-vs-22) for the
+ready-made sets per version, including the one criterion WCAG 2.2 removed rather than
+added.
+
+**The removed criterion is handled for you.** Every run resolves a target WCAG version
+(`engineOptions.wcagVersion`, else whatever your version tags imply, else `2.2`) and
+reports it back as `engine.wcagVersion`. Under a 2.2 target, a rule mapped only to SC
+4.1.1 Parsing cannot report `fail` — it runs, reports its occurrences, and comes back
+`cantTell` with a `wcagVersionScope` field explaining the coercion. So a default scan
+never gates on a criterion WCAG 2.2 does not contain, and a 2.0/2.1 scan still gets a
+real 4.1.1 verdict.
+
+Composites, unlike atomic rules, *are* filtered cumulatively. The runner reads the
+highest level named in `tags` and drops every composite above it, so requesting
+`['wcag2a', 'wcag2aa']` returns no `rulesResults` entry for an AAA-only SC. That is
+`inferTargetLevelFromRunOnly`/`isAllowedByTargetLevel` in `src/core/dom-runner.js` if
+you need the exact precedence.
+
+Omit `tags` entirely (the default) and every rule at every level runs, with no composite
+suppression.
 
 ## What this engine cannot tell you
 
 No automated tool — this one included — can certify full WCAG conformance. That's not a limitation specific to surea11y; it's inherent to WCAG itself; a meaningful fraction of Success Criteria require human judgment (is this alt text *accurate*, not just *present*; is this error message *understandable*) or dynamic testing this engine's static-DOM-scan architecture cannot do at all (keyboard-trap detection, real layout/reflow at zoom). See [`LIMITATIONS.md`](./LIMITATIONS.md) for the full, explicit list of what's out of scope and why.
 
 What surea11y *can* give you, honestly:
-- Every `fail` is a real, deterministic, normative violation — never a guess.
+- Every `fail` is a real, deterministic, normative violation under the version you targeted — never a guess.
 - Every `cantTell` is an explicit flag for human review, not a swallowed uncertainty.
 - The facet coverage table tells you exactly which parts of which SCs have zero automated coverage, so you know where a `pass` is silent rather than exhaustive.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -25,15 +25,14 @@
     "vitest"
   ],
   "main": "src/index.js",
-  "bin": {
-    "surea11y-core": "bin/surea11y-core.js"
-  },
   "exports": {
     ".": "./src/index.js",
     "./baseline": "./src/baseline.js",
     "./report": "./src/report.js",
     "./sarif": "./src/sarif.js",
+    "./earl": "./src/earl.js",
     "./browser": "./surea11y.browser.js",
+    "./i18n/*": "./surea11y.i18n.*.js",
     "./package.json": "./package.json"
   },
   "author": "Jorge Rumoroso",
@@ -58,8 +57,8 @@
     "src/baseline.js",
     "src/report.js",
     "src/sarif.js",
+    "src/earl.js",
     "src/checks/**/*.js",
-    "bin/surea11y-core.js",
     "surea11y.browser.js",
     "surea11y.i18n.*.js",
     "docs/**/*.md",
@@ -74,11 +73,11 @@
   "scripts": {
     "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\"",
+    "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"tests/**/*.js\" \"eslint.config.js\"",
+    "format:check": "prettier --check \"src/**/*.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 format:check && npm run build && node scripts/run-tests.js",
+    "test": "npm run lint && npm run format:check && npm run build && npm run validate:rules && 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",
@@ -89,11 +88,13 @@
     "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
     "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
     "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
+    "finding-ids": "npm run build && node scripts/generate-finding-ids.js",
     "fixtures:index": "node scripts/generate-fixture-index.js",
+    "fixtures:check": "node scripts/generate-fixture-index.js --check",
     "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",
-    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
+    "validate:rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic src/checks/manual",
     "i18n:new": "node scripts/i18n-scaffold.js",
     "i18n:sync": "node scripts/i18n-sync.js",
     "i18n:check": "node scripts/i18n-sync.js --check",
@@ -102,6 +103,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "aria-query": "^5.3.2",
+    "esbuild": "^0.28.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",

package/src/baseline.js

@@ -3,13 +3,13 @@
 'use strict';
 
 // docs/BASELINE.md: identity for one violation occurrence is
-// `ruleId + reasonCode + html` -- deliberately NOT `selector`/`structuralPath`
+// `ruleId + reasonCode + html`, on purpose NOT `selector`/`structuralPath`
 // (both position-derived, so they shift when unrelated markup changes
 // elsewhere on the page; see buildSelector/buildStructuralPath in
 // src/core/dom-helpers.js). Unlike src/explain/group.js's computeGroupKey,
-// this does not use a coarse structural signature: that's deliberately lossy
+// this does not use a coarse structural signature: that's lossy on purpose
 // for AI-explanation dedup (one prompt per shape), which would risk a CI gate
-// silently treating a genuinely new violation as "known" just because it
+// silently treating an actually new violation as "known" just because it
 // shares tag/class shape with an old baselined one -- the wrong failure mode
 // here. Content-based matching survives incidental DOM changes elsewhere on
 // the page; its known limitation is a flagged element with dynamic content

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

@@ -21,9 +21,9 @@
 const id = 'area-alt-present';
 
 const meta = {
-  title: '<area> must have an alt attribute',
+  title: '<area> must have an alt attribute',
   description:
-    'Checks that &lt;area&gt; elements provide an alt attribute to support a text alternative mechanism.',
+    'Checks that <area> elements provide an alt attribute to support a text alternative mechanism.',
   i18n: {
     titleKey: 'area_altPresent_title',
     descriptionKey: 'area_altPresent_description'