@surea11y/core 1.4.1 → 1.6.0

package/docs/RULE_TAXONOMY.md

@@ -24,7 +24,7 @@ Manual rules MUST NOT make normative failure decisions.
 ### 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 +43,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/TROUBLESHOOTING.md

@@ -2,7 +2,7 @@
 
 ## "I passed `runOnly: ['some-rule-id']` but every rule still ran"
 
-`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). This is easy to get wrong if you're coming from another engine that does accept a bare array.
+`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). A bare array is easy to reach for, so this is worth checking first.
 
 Fix:
 
@@ -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?"
@@ -41,7 +41,7 @@ Treat it as "needs a human to look" — it's neither pass nor fail by design. Mo
 
 ## "What happens if a locale is only partially translated?"
 
-Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Both shipped locales (`en`, `fr`) are at full parity as of this writing, but that's not guaranteed to stay true automatically: adding a new rule adds a new key to `en.js`, and unless the same key is added to `fr.js` (or any other locale file you maintain), that string falls back to English until it is.
+Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Key parity is enforced rather than hoped for: `npm run i18n:sync` carries any new or renamed `en.json` key into every other locale file, and the build fails if one is out of step. A key it adds holds the English text until someone translates it, so a locale can be behind on wording without ever being behind on keys.
 
 ## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
 

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,17 +25,33 @@ 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.
+
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -25,9 +25,6 @@
     "vitest"
   ],
   "main": "src/index.js",
-  "bin": {
-    "surea11y-core": "bin/surea11y-core.js"
-  },
   "exports": {
     ".": "./src/index.js",
     "./baseline": "./src/baseline.js",
@@ -59,8 +56,8 @@
     "src/report.js",
     "src/sarif.js",
     "src/checks/**/*.js",
-    "bin/surea11y-core.js",
     "surea11y.browser.js",
+    "surea11y.i18n.*.js",
     "docs/**/*.md",
     "README.md",
     "LICENSE",
@@ -73,8 +70,8 @@
   "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",
@@ -87,11 +84,15 @@
     "test:typography-helpers": "node tests/contrast-typography.test.js",
     "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",
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
     "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
+    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
     "i18n:new": "node scripts/i18n-scaffold.js",
+    "i18n:sync": "node scripts/i18n-sync.js",
+    "i18n:check": "node scripts/i18n-sync.js --check",
     "i18n:report": "node scripts/i18n-report.js"
   },
   "devDependencies": {

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'

package/src/checks/automatic/aria-allowed-attr.js

@@ -9,8 +9,10 @@
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   Applies to elements with an explicit, valid, non-abstract role that
- *   also carry at least one recognized aria-* attribute.
+ *   Applies to elements carrying at least one recognized, non-global
+ *   aria-* attribute, judged against the role they actually have: an
+ *   explicit valid role, else the implicit role of their tag, else, for
+ *   the elements HTML-AAM maps to no role at all, nothing.
  * @expectation
  *   Every recognized aria-* attribute present is either: (a) globally
  *   supported on any element (the "global" ARIA states/properties, e.g.
@@ -20,10 +22,19 @@
  *   still allowed: it is reported as CANTTELL (see helpers.aria.isDeprecatedAttr)
  *   so the author decides, not as a not-allowed FAIL.
  * @implementation-notes
- * - Only evaluated for elements with an explicit role, since the global
- *   set already covers implicit-role elements without asserting anything
- *   role-specific; scope kept deliberately narrow to avoid false positives
- *   on implicit-role ARIA-in-HTML edge cases not modeled here.
+ * - Three tiers of role resolution, in order: an explicit `role`; the
+ *   implicit role of the tag (IMPLICIT_ROLE_BY_ELEMENT, generated only for
+ *   elements whose role is the same in every context, see
+ *   `scripts/generate-aria-tables.js` for what is excluded and why); and
+ *   ROLELESS_ELEMENTS, the tags HTML-AAM gives no role at all. A
+ *   role-specific attribute on one of those is supported by nothing, which
+ *   is exactly ACT 5c01ea's `<audio controls aria-orientation="horizontal">`.
+ *   An element whose role is context-dependent (`<a>`, `<section>`,
+ *   `<td>`, ...) is still skipped rather than guessed at.
+ * - `<div>`/`<span>` resolve to `generic`, whose supported set is empty, so
+ *   `<div aria-expanded="true">` is reported: the attribute announces
+ *   nothing on an element with no widget semantics, which is a real defect
+ *   and not a spec technicality.
  * - SUPPORTED_ATTRS_BY_ROLE holds unambiguous, well-established ARIA facts:
  *   subclass relationships like `searchbox`==`textbox`; same-family widget
  *   properties like `columnheader`/`rowheader` sort/col-row-index/span
@@ -82,7 +93,7 @@ function runInPage(ctx) {
   // Global ARIA states/properties supported on (almost) any element,
   // regardless of role, per the WAI-ARIA "Global States and Properties" list.
   // Declared inside runInPage (rather than at module scope) because the
-  // build inlines only this function's own source text — see
+  // build inlines only this function's own source text, see
   // scripts/build-core.js header ("runInPage MUST be self-contained").
   // <generated:aria-global-attrs>
   const GLOBAL_ATTRS = [
@@ -109,8 +120,8 @@ function runInPage(ctx) {
   ];
   // </generated:aria-global-attrs>
 
-  // Per-role supported (non-global) states/properties. Deliberately
-  // conservative — see src/core/aria-helpers.js file header for the same
+  // Per-role supported (non-global) states/properties.
+  // conservative, see src/core/aria-helpers.js file header for the same
   // confidence-scoping rationale; only well-established, unambiguous
   // role/attribute pairings from the WAI-ARIA role definitions are listed.
   // <generated:aria-implicit-roles>
@@ -125,6 +136,7 @@ function runInPage(ctx) {
     details: 'group',
     dfn: 'term',
     dialog: 'dialog',
+    div: 'generic',
     dt: 'term',
     em: 'emphasis',
     fieldset: 'group',
@@ -149,6 +161,7 @@ function runInPage(ctx) {
     p: 'paragraph',
     progress: 'progressbar',
     strong: 'strong',
+    span: 'generic',
     sub: 'subscript',
     sup: 'superscript',
     textarea: 'textbox',
@@ -173,6 +186,10 @@ function runInPage(ctx) {
     '[aria-activedescendant], [aria-autocomplete], [aria-checked], [aria-colcount], [aria-colindex], [aria-colspan], [aria-disabled], [aria-errormessage], [aria-expanded], [aria-haspopup], [aria-invalid], [aria-level], [aria-modal], [aria-multiline], [aria-multiselectable], [aria-orientation], [aria-placeholder], [aria-posinset], [aria-pressed], [aria-readonly], [aria-required], [aria-rowcount], [aria-rowindex], [aria-rowspan], [aria-selected], [aria-setsize], [aria-sort], [aria-valuemax], [aria-valuemin], [aria-valuenow], [aria-valuetext]';
   // </generated:aria-implicit-roles>
 
+  // <generated:aria-roleless-elements>
+  const ROLELESS_ELEMENTS = new Set(['audio', 'video']);
+  // </generated:aria-roleless-elements>
+
   // <generated:aria-role-attrs>
   const SUPPORTED_ATTRS_BY_ROLE = {
     alert: [],
@@ -806,6 +823,39 @@ function runInPage(ctx) {
   const cantTellOccurrences = [];
   let applicableCount = 0;
 
+  // An element HTML-AAM maps to no role has nothing to support a
+  // role-specific attribute, so every non-global one present is reported.
+  // Returns how many recognized aria-* attributes it carried, for the
+  // applicable count.
+  function rolelessOccurrences(el, tag) {
+    let seen = 0;
+    const attrs = el.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = String(attrs[i].name || '').toLowerCase();
+      if (name.slice(0, 5) !== 'aria-') continue;
+      if (!ariaHelpers.isValidAriaAttrName(name)) continue; // aria-valid-attr's concern
+
+      seen += 1;
+      if (globalSet.has(name)) continue;
+
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `<${tag}> has no ARIA role, so nothing supports the ${name} attribute on it.`,
+          hint: `Remove ${name}, or move it to an element whose role supports it. A role-specific ARIA attribute on an element with no role is ignored by assistive technology.`,
+          i18n: {
+            summaryKey: 'ariaAllowedAttr_summary_fail_roleless',
+            hintKey: 'ariaAllowedAttr_hint_fail_roleless',
+            params: { attr: name, element: tag }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED_ROLELESS', attr: name, element: tag }
+          }
+        })
+      );
+    }
+    return seen;
+  }
+
   for (const el of nodes) {
     if (!el || !el.attributes) continue;
 
@@ -824,6 +874,14 @@ function runInPage(ctx) {
       role = Object.prototype.hasOwnProperty.call(IMPLICIT_ROLE_BY_ELEMENT, key)
         ? IMPLICIT_ROLE_BY_ELEMENT[key]
         : '';
+      // No role from either source: for a tag HTML-AAM maps to no role at
+      // all, that IS the answer. Nothing supports a role-specific
+      // attribute here. Any other tag has a role this table does not model
+      // (context-dependent ones), so it stays out of scope.
+      if (!role && ROLELESS_ELEMENTS.has(tag)) {
+        applicableCount += rolelessOccurrences(el, tag);
+        continue;
+      }
     }
     if (!role || !ariaHelpers.isValidConcreteRole(role)) continue; // aria-roles-valid's concern
 
@@ -858,49 +916,46 @@ function runInPage(ctx) {
 
     if (!disallowed || !disallowed.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const name of disallowed) {
       // A property ARIA deprecated (rather than prohibited) on this role is
-      // still allowed — surfaced as cantTell for the author to decide, not a
+      // still allowed, surfaced as cantTell for the author to decide, not a
       // not-allowed fail.
       const deprecated =
         typeof ariaHelpers.isDeprecatedAttr === 'function' &&
         ariaHelpers.isDeprecatedAttr(name, role);
       if (deprecated) {
-        cantTellOccurrences.push({
-          selector: stableSelector,
-          html,
-          summary: 'This ARIA attribute is deprecated for this element’s role.',
-          hint: 'It is still allowed but discouraged; remove it or use a role that supports it, as a future ARIA version may disallow it.',
-          occurrenceOutcome: 'cantTell',
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: 'This ARIA attribute is deprecated for this element’s role.',
+            hint: 'It is still allowed but discouraged; remove it or use a role that supports it, as a future ARIA version may disallow it.',
+            occurrenceOutcome: 'cantTell',
+            i18n: {
+              summaryKey: 'ariaAllowedAttr_summary_cantTell',
+              hintKey: 'ariaAllowedAttr_hint_cantTell',
+              params: { attr: name, role }
+            },
+            data: {
+              details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
+            }
+          })
+        );
+        continue;
+      }
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This ARIA attribute is not permitted for this element’s role.',
+          hint: 'Remove this attribute, or use a role that supports it.',
+          occurrenceOutcome: 'fail',
           i18n: {
-            summaryKey: 'ariaAllowedAttr_summary_cantTell',
-            hintKey: 'ariaAllowedAttr_hint_cantTell',
+            summaryKey: 'ariaAllowedAttr_summary_fail',
+            hintKey: 'ariaAllowedAttr_hint_fail',
             params: { attr: name, role }
           },
           data: {
-            details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
+            details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED', attr: name, role }
           }
-        });
-        continue;
-      }
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This ARIA attribute is not permitted for this element’s role.',
-        hint: 'Remove this attribute, or use a role that supports it.',
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'ariaAllowedAttr_summary_fail',
-          hintKey: 'ariaAllowedAttr_hint_fail',
-          params: { attr: name, role }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED', attr: name, role }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/aria-allowed-role.js

@@ -17,9 +17,9 @@
  *   The explicit role is one of the roles the ARIA-in-HTML specification
  *   permits for that host element.
  * @implementation-notes
- * - Deliberately scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
+ * - Scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
  *   elements without an asserted constraint are treated as "no constraint"
- *   (not flagged) rather than guessed at — see that table's header comment.
+ *   (not flagged) rather than guessed at, see that table's header comment.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
@@ -82,24 +82,22 @@ function runInPage(ctx) {
 
     if (info.allowed) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This role is not permitted on this element.',
-      hint: 'Use a role permitted for this element, or change the host element.',
-      i18n: {
-        summaryKey: 'ariaAllowedRole_summary_fail',
-        hintKey: 'ariaAllowedRole_hint_fail',
-        params: { role, element: tag }
-      },
-      data: {
-        details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This role is not permitted on this element.',
+        hint: 'Use a role permitted for this element, or change the host element.',
+        i18n: {
+          summaryKey: 'ariaAllowedRole_summary_fail',
+          hintKey: 'ariaAllowedRole_hint_fail',
+          params: { role, element: tag }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/aria-braille-equivalent.js

@@ -27,7 +27,7 @@
  * - `aria-braillelabel`/`aria-brailleroledescription` do not participate
  *   in the standard accessible-name computation, so
  *   `helpers.getAccessibleNameInfo` already reflects only the "regular"
- *   (non-braille) name — no special-casing needed there.
+ *   (non-braille) name, no special-casing needed there.
  */
 
 const id = 'aria-braille-equivalent';
@@ -67,7 +67,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -119,29 +119,27 @@ function runInPage(ctx) {
 
     if (!missing.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
     for (const m of missing) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-        hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
-        i18n: {
-          summaryKey: 'ariaBrailleEquivalent_summary_fail',
-          hintKey: 'ariaBrailleEquivalent_hint_fail',
-          params: { element: tag, attr: m.attr, requires: m.requires }
-        },
-        data: {
-          details: {
-            reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
-            attr: m.attr,
-            requires: m.requires
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
+          hint: `${m.attr} is a Braille-specific supplement, not a replacement, so also provide ${m.requires}.`,
+          i18n: {
+            summaryKey: 'ariaBrailleEquivalent_summary_fail',
+            hintKey: 'ariaBrailleEquivalent_hint_fail',
+            params: { element: tag, attr: m.attr, requires: m.requires }
+          },
+          data: {
+            details: {
+              reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
+              attr: m.attr,
+              requires: m.requires
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/aria-conditional-attr.js

@@ -16,17 +16,17 @@
  *   other than `"false"` (i.e. `"true"`, `"grammar"`, or `"spelling"`).
  *   An element with `aria-errormessage` but `aria-invalid` absent or
  *   `"false"` silently drops the error message from the accessibility
- *   tree — authors almost always intend it to be exposed.
+ *   tree, authors almost always intend it to be exposed.
  * @implementation-notes
- * - This is deliberately narrow: the broader space is a table of many
+ * - This is narrow: the broader space is a table of many
  *   attribute/condition pairs. This rule implements only the one pairing
  *   (`aria-errormessage` / `aria-invalid`) that is unambiguous and
- *   explicitly stated in the ARIA spec, to keep `fail` high-confidence —
+ *   explicitly stated in the ARIA spec, to keep `fail` high-confidence,
  *   matches this repo's established pattern (see `aria-required-attr`/
  *   `aria-prohibited-attr` for the same "narrow but zero false positives"
  *   trade-off).
  * - Does not check whether the `aria-errormessage` ID reference itself
- *   resolves to an existing element — that is `aria-valid-attr-value`'s
+ *   resolves to an existing element. That's `aria-valid-attr-value`'s
  *   concern, not this rule's.
  */
 
@@ -35,7 +35,7 @@ const id = 'aria-conditional-attr';
 const meta = {
   title: 'aria-errormessage requires aria-invalid to be set to a non-false value',
   description:
-    'Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling" — otherwise the error message is dropped from the accessibility tree.',
+    'Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling"; otherwise the error message is dropped from the accessibility tree.',
   i18n: {
     titleKey: 'ariaConditionalAttr_title',
     descriptionKey: 'ariaConditionalAttr_description'
@@ -86,28 +86,26 @@ function runInPage(ctx) {
     const invalidValue = trim(el.getAttribute('aria-invalid')).toLowerCase();
     if (TRUTHY_INVALID_VALUES.has(invalidValue)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
-      hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'ariaConditionalAttr_summary_fail',
-        hintKey: 'ariaConditionalAttr_hint_fail',
-        params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
-          ariaInvalid: invalidValue
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
+        hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'ariaConditionalAttr_summary_fail',
+          hintKey: 'ariaConditionalAttr_hint_fail',
+          params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
+            ariaInvalid: invalidValue
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {