@surea11y/core 1.6.0 → 1.8.0

package/docs/RULE_HELPERS.md

@@ -0,0 +1,390 @@
+# 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');
+```
+
+### `queryAllSource(selector)` → `Element[]`
+The same query as `queryAllSmart` (shadow roots per `includeShadowDom`, context scope,
+`excludeSelectors`) with no hidden-content filter: elements inside `hidden`,
+`display:none`, closed `<details>` and the like are returned whatever
+`includeHiddenElements` says. Only for rules that judge the markup itself rather than
+what is rendered, such as a standard's tests on the generated source.
+`<template>` content is not in the DOM tree and stays out. A WCAG rule should not use
+it: hidden content is not presented to users.
+
+### `getDoctypeInfo()` → `{ kind, name, publicId, systemId }`
+The document's doctype, classified by HTML version. `kind` is one of:
+
+| `kind` | Doctype |
+|---|---|
+| `'html5'` | name `html`, no public id, and no system id or `about:legacy-compat` |
+| `'xhtml10'` | a public id of XHTML 1.0 (strict, transitional or frameset) |
+| `'xhtml11'` | any other W3C XHTML public id: XHTML 1.1, XHTML Basic, XHTML 1.1 plus MathML (and SVG), XHTML+RDFa |
+| `'html4'` | a W3C or IETF HTML public id: HTML 2.0, 3.2, 4.0, 4.01, HTML 4.01+RDFa |
+| `'other'` | any other doctype, including one whose name is not `html` |
+| `'none'` | no doctype |
+
+Public ids are compared without regard to case, as the HTML parser does. `name`,
+`publicId` and `systemId` are the doctype's own values (empty strings when there is
+none). For rules whose verdict depends on the HTML version: a requirement that
+applies to HTML5 only, or `lang` read as `lang` or `xml:lang` by version. Whether a
+doctype is valid at all is not this helper's question.
+
+### `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. An SVG element with a `<title>` child
+speaks for itself through that title (SVG-AAM), after its own `aria-labelledby` and
+`aria-label`, so `<button><svg><title>Search</title></svg></button>` is named "Search".
+
+### `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.
+
+### `getNativeHostNameInfo(el, ctx, opts)` → `{ present, value, mechanism }`
+The name an element gets from its HTML host markup rather than from ARIA: an associated
+`<label>` on a labelable element, the first child `<legend>` of a `<fieldset>`, the first
+child `<caption>` of a `<table>`, and, only with `opts.placeholder: true`, the
+`placeholder` of a text-like `<input>` or a `<textarea>` (HTML-AAM's last name source).
+`mechanism` is `'label'`, `'legend'`, `'caption'`, `'placeholder'` or `'none'`. For rules
+on name-from-author-only roles (`role="textbox"`, `"slider"`, `"radiogroup"`, …) whose
+ARIA check does not read host markup, although the browser still computes it.
+
+### `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.
+
+### `hasSkipLinkWording(text)` → `boolean`
+Whether a link's text reads as a skip link ("Skip to content", "Aller au contenu",
+"Zum Inhalt", "Saltar al contenido", "本文へ"...), in the languages the engine ships.
+One list for every rule that looks for a skip link, core's `skip-link` and any a
+profile brings, so they recognise the same links; add a phrasing here, not in a
+rule.
+
+### `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`,
+`hasBackgroundImageOrGradient`, `hasBlendMode`, `hasFilter`, `computeOpacityProduct`,
+`getTextScan`, `isInactiveUiComponent`, plus small numeric/formatting utilities
+(`clamp01`, `clamp255`, `round2`, `toHex2`, `rgbToHex`, `rgbaToString`, `parsePx`,
+`normalizeFontWeight`, `pxToPt`, `fontWeightLabel`). That is the whole namespace,
+apart from `sharedCache`: a plain object that lives for one scan and lets the contrast
+rules reuse per-element work. Treat it as an optimisation, never as data a rule
+depends on: a key may be absent, and a rule stores only under keys of its own unless
+it computes exactly what that key's other users compute (`contrast-minimum`,
+`contrast-enhanced` and `contrast-computable`, and `contrast-minimum`'s variants,
+share `__elBgCache`, `__elFgCache` and `__elBlockerCache`,
+WeakMaps of each element's effective background, foreground and computability blocker;
+a variant with other thresholds keeps its own font and analysis caches, keyed by them). Backs the
+`contrast-*` rule family (`contrast-minimum` and its variants, `contrast-enhanced`,
+`contrast-computable`) — see `src/core/contrast-helpers.js`
+if you're extending that family specifically. `isLargeText(fontSizePx, fontWeightNum,
+boldLargeMinPx)` takes an optional third argument, the size from which bold text is large:
+WCAG's 14pt when it is left out, 18.5 for a standard that puts it there.
+
+### `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 130 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 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 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:
+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 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`.
@@ -33,7 +52,8 @@ Every rule that ran (regardless of whether it produced a result) is listed once
 | `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`. |
+| `tool.driver.rules[].properties.tags` | `accessibility`, `automatic`/`manual`, and a `wcag-<SC>` tag per WCAG Success Criterion in `meta.normativeMappings`. Understanding-document entries get no tag. Each EN 301 549 clause the result carries (only when the scan asked for them, see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#other-standards-mappings)) gets an `en301549-<clause>` tag, e.g. `en301549-9.1.1.1`: clause numbers are the same in every version that has them, so the tag carries no version. |
+| `runs[0].properties` | `wcagVersion`, `profile` and `optInRules` from the result's `engine`: the conformance target the run used, so a dashboard can tell a WCAG 2.1 run from a 2.2 one, and the opt-in rule tags it added beyond that target when it added any. Omitted for results from engines that predate those fields. |
 
 ## Locations
 

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 130.
+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 every one.
 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-33) 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 the composite section of [`RULE_CATALOG.md`](./RULE_CATALOG.md) 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
 
@@ -37,6 +37,8 @@ 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.
+`engineOptions.profile` (`wcag22-aa`, `en301549-v4.1.1`, `en301549-v3.2.1`, `section508`) does
+this for you; see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#conformance-profiles).
 
 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
@@ -44,6 +46,14 @@ only its own origin tag — so a full conformance target is a union of tag sets.
 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
@@ -53,12 +63,63 @@ you need the exact precedence.
 Omit `tags` entirely (the default) and every rule at every level runs, with no composite
 suppression.
 
+## EN 301 549
+
+Chapter 9 of EN 301 549 restates the WCAG Level A and AA Success Criteria as clauses numbered `9.` plus the criterion's own number: WCAG 1.4.3 is clause 9.1.4.3. When a scan asks for them, every atomic and composite result carries, after its WCAG entries in `meta.normativeMappings`, the clause for each of its criteria, once per version of the standard that includes that criterion. A scan asks with `engineOptions.mappings: ['en301549']` (both versions) or `['en301549:V3.2.1']` (one), or by targeting an EN 301 549 profile, which adds the version it names; by default results name WCAG only (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#other-standards-mappings)):
+
+| Version | Built on | Differs from the other in |
+|---|---|---|
+| V3.2.1 (2021-03) | WCAG 2.1 A and AA, 50 criteria | Includes 9.4.1.1 Parsing |
+| V4.1.1 (2026-09) | WCAG 2.2 A and AA, 55 criteria | Adds 2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8; 9.4.1.1 is void |
+
+Each clause entry also names the criterion it restates, as `wcagSc: ["1.4.3"]`, so a view grouped by criterion (JUnit's suites, the HTML report's rollup) puts it under the right one even on a rule mapped to several.
+
+AAA criteria have no clause in either version. The table lives in `src/coverage/en301549-map.js`, taken from the ETSI text; rules never declare these entries themselves, the build derives them from each rule's WCAG mapping. A rule added through `engineOptions.customRules` keeps exactly the mappings it declares. The catalogs name the clauses under the same options: `getChecksCatalog({ mappings: ['en301549'] })` in each entry's `normativeMappings`, and composite entries returned by `getRulesCatalog({ mappings: ['en301549'] })` as `meta.standardMappings`, so the clauses a criterion maps to can be read without running a scan. Called with no options, they name WCAG only, as a result does.
+
+The table is public as `@surea11y/core/en301549`, for tools that need the reverse view, such as which criteria a version requires that a scan did not cover:
+
+```js
+const { EN301549_CLAUSES, en301549ClausesForSc } = require('@surea11y/core/en301549');
+
+Object.keys(EN301549_CLAUSES['V3.2.1']);  // the 50 WCAG 2.1 A and AA criteria V3.2.1 restates
+en301549ClausesForSc('2.5.8');            // [{ version: 'V4.1.1', clause: '9.2.5.8', title: 'Target size (minimum)' }]
+```
+
+This is a correspondence between two published documents, not a conformance claim: a clause on a result says which EN 301 549 requirement that WCAG criterion is, nothing more. Which version a given law requires is outside the engine.
+
+## Adding another standard
+
+EN 301 549 is an entry in a registry, `src/coverage/standards.js`. The build, the runner, the rule catalog and the reporters read it, so a new standard goes the same way. Where its entry lives depends on the standard:
+
+- A standard that restates WCAG one criterion at a time, as EN 301 549 does, only renumbers WCAG's verdicts. Its table goes in `src/coverage/<name>-map.js` and its entry in `NORMATIVE_STANDARDS`, next to EN 301 549's.
+- A standard with verdicts of its own is a **profile**: a folder under `profiles/` holding its entry, its tables, and the scripts and tests that go with them, listed in `profiles/index.js`. The registry appends each profile's entry after its own. `npm run profile:new -- <key>` creates one, working and empty, to fill in. See [`profiles/README.md`](../profiles/README.md) for the layout.
+
+Either way, the entry needs:
+
+1. A table taken from the published text, with a function that returns a rule's entries given the rule's id and WCAG criteria. Each entry is `{ standard, version, requirement, title, wcagSc }`, where `wcagSc` lists the WCAG criteria that requirement corresponds to. A standard that restates WCAG derives its entries from the criteria. One organised differently looks the rule up by id, in a table of the rules it maps.
+2. Its `key` (what `engineOptions.mappings` accepts, and the SARIF tag prefix and JUnit property name), its `standard` (the name its entries carry and the report shows), its `versions`, and that function as `mappingsFor`.
+
+The rest is optional, and the comment at the top of the registry describes each field:
+
+- `profiles`: named conformance targets. Each gives the WCAG tags it runs and the version it targets, and switches that version's mappings on. With `mappedRules: true` it also runs every rule the standard maps, which matters when the standard requires things WCAG leaves to best practice. With `exclude: { rules, criteria }` it leaves rules out: the rules it names, and the WCAG criteria a standard narrower than WCAG waives (their WCAG rollups, and every rule that checks nothing else). The build refuses an unknown rule or criterion, and a rule the profile both maps and excludes. A standard that replaces a WCAG check with a stricter one of its own excludes the WCAG rule and maps its own.
+- `ruleTag`: a tag for rules that check requirements only this standard makes. Another standard may not map them or derive variants from them; the build refuses it, so standards stay independent of each other, and a rule two of them need belongs in core. These rules are opt-in (see [`RULE_AUTHORING.md`](./RULE_AUTHORING.md)), so a WCAG scan never runs them. In a profile, they go in its `rules/` folder, which its `index.js` exports as `rulesDir`.
+- `ruleMapped: true`: the entries come from each rule rather than from its WCAG criterion, so a WCAG rollup names only the entries of the rules that decided its outcome. A standard mapped that way for some requirements and restating WCAG for others lists the prefixes of the restating ones in `restatedPrefixes` (`['A.']`): a rollup names those whatever decided it, as it names EN 301 549's.
+- `composites()`: rollups of the standard's own, such as one per requirement. They carry the rule tag, so only a run that asks for the standard produces them, and the HTML report shows them in a section of their own.
+- `report`: the dictionary key of the note above that section (`noteKey`), and the language of the rollup titles when it is not the scan's (`titleLang`).
+- `validate(rules)`: checks the standard's own tables against the rules that exist. The build fails on any problem it returns.
+
+A standard built on a WCAG version reads that version from `@surea11y/core/wcag` (`src/wcag.js`) rather than keeping its own copy: `wcagCriteria('2.1', { levels: ['A', 'AA'] })` lists the criteria in force in 2.1 with their 2.1 titles and levels (4.1.1 Parsing is Level A there, and gone in 2.2), `wcagCriterion(sc, version)` looks one up, and `wcagTags('2.1')` gives the rule tags a profile on 2.1 A and AA selects, as EN 301 549's profiles do. It is the one core module a profile's own tables may require (see [`profiles/README.md`](../profiles/README.md#what-a-profile-may-use)).
+
+`tests/coverage/standards.test.js` holds every registered standard to the contract. What stays per standard is its table, its tests, its rules, and a public export if tools need the reverse view, as `@surea11y/core/en301549` does.
+
+A standard is compiled into the engine. At run time, a custom rule (`engineOptions.customRules`) can name any standard in its own `normativeMappings`, and the result keeps those entries as written, but only registered standards get a profile, a `mappings` switch, opt-in rules, rollups, or a place in SARIF, JUnit and the HTML report.
+
 ## 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 of the standard and version you targeted — never a guess. By default that standard is WCAG: a rule for a requirement only another standard makes (a rule for a national standard's own requirement, say) is opt-in and runs only when you target that standard ([`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#opt-in-rules)), so a WCAG scan never fails a page for something WCAG does not require. The one exception is a run that asks for every rule (`engineOptions.optInRules`): it targets no single standard, and says so in `engine.optInRules`.
 - 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.