@surea11y/core 1.5.0 → 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

@@ -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,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.5.0",
+  "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,7 +56,6 @@
     "src/report.js",
     "src/sarif.js",
     "src/checks/**/*.js",
-    "bin/surea11y-core.js",
     "surea11y.browser.js",
     "surea11y.i18n.*.js",
     "docs/**/*.md",
@@ -74,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",

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
 
@@ -860,7 +918,7 @@ function runInPage(ctx) {
 
     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' &&

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.

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
@@ -125,7 +125,7 @@ function runInPage(ctx) {
       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 — also provide ${m.requires}.`,
+          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',

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'

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

@@ -11,7 +11,7 @@
  * @applicability
  *   Applies to any element whose role attribute's first (used) token is a
  *   valid, non-abstract ARIA role that authors should not explicitly
- *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
+ *   declare, either because WAI-ARIA has deprecated it (e.g. "directory",
  *   superseded by role="list") or because it is reserved for user-agent-
  *   internal use (role="generic", which ARIA 1.2 §5.4 says authors SHOULD
  *   NOT use in content).

package/src/checks/automatic/aria-hidden-body.js

@@ -10,13 +10,13 @@
  * @sc 1.3.1, 4.1.2
  * @applicability
  *   Always applicable to any HTML document with a <body> element,
- *   independent of contextSelector/root scoping — this is a whole-
+ *   independent of contextSelector/root scoping, this is a whole-
  *   document concern, matching page-title-present's pattern of
  *   evaluating document.body directly rather than the scoped root.
  * @expectation
  *   <body> does not have aria-hidden="true". Hiding the document body
  *   removes the entire page's content and structure from the
- *   accessibility tree at once — both 1.3.1 (Info and Relationships: the
+ *   accessibility tree at once, both 1.3.1 (Info and Relationships: the
  *   page's structure becomes entirely non-determinable) and 4.1.2 (Name,
  *   Role, Value: nothing in the document exposes a role/name/value any
  *   longer) apply.

package/src/checks/automatic/aria-hidden-focus.js

@@ -109,7 +109,7 @@ function runInPage(ctx) {
   }
 
   // Flat-tree ancestor walk (assignedSlot wins over parentNode, then shadow
-  // host) — shared with every other rule via ctx.helpers.composedParent
+  // host), shared with every other rule via ctx.helpers.composedParent
   // (src/core/dom-helpers.js), not reimplemented here, so a fix to the one
   // canonical definition can't drift out of sync with this rule's copy.
   const composedParent =
@@ -533,8 +533,8 @@ function runInPage(ctx) {
     if (isDisabledFormControl(el)) return false;
 
     // An explicit negative tabindex removes the element from the keyboard
-    // tab sequence entirely, regardless of tag — the standard, WAI-
-    // recommended technique for safely hiding focusable content behind
+    // tab sequence entirely, regardless of tag. It's the standard,
+    // WAI-recommended technique for safely hiding focusable content behind
     // aria-hidden (e.g. <button tabindex="-1"> / <a tabindex="-1"> inside
     // an aria-hidden container). This cares about tabbability, not raw
     // focusability. Such an element is still programmatically focusable
@@ -684,7 +684,7 @@ function runInPage(ctx) {
     // Cheap check first: a plain ancestor-attribute walk with no CSS
     // computation, vs. isActuallyFocusable's getComputedStyle-per-ancestor
     // cost. Both conditions are required (AND), so checking whichever is
-    // cheaper first cannot change which elements end up in the bucket —
+    // cheaper first cannot change which elements end up in the bucket,
     // it only skips the expensive check for the (typically vast) majority
     // of focusable candidates that were never inside an aria-hidden root
     // in the first place. On pages with many focusable candidates and a
@@ -903,7 +903,7 @@ function runInPage(ctx) {
 
   // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
   // a fail-tier finding never silently discards cantTell-tier findings from
-  // the same run — both are returned together when the outcome is 'fail'.
+  // the same run, both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     uncertainOccurrences,

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

@@ -14,20 +14,20 @@
  *   list for naming attributes (pure text-semantics / non-naming
  *   structural roles: caption, code, deletion, emphasis, generic,
  *   insertion, mark, none, paragraph, presentation, strong, subscript,
- *   suggestion, superscript, time), and (b) elements with no role at all —
+ *   suggestion, superscript, time), and (b) elements with no role at all:
  *   a curated set of native HTML tags verified to carry no implicit role
  *   (see ROLELESS_NATIVE_TAGS below), or any autonomous custom element (a
  *   hyphenated, author-defined tag per the Custom Elements spec; see
- *   isRolelessCustomElementTag below) — in both cases, only elements that
+ *   isRolelessCustomElementTag below). In both cases, only elements that
  *   also carry aria-label or aria-labelledby.
  * @expectation
  *   Prohibited attributes must not be present on (a); for (b), the naming
  *   attribute is at best unreliable (nothing accessible-name-aware to hang
- *   it off) and at worst silently ignored by assistive technology — see the
+ *   it off) and at worst silently ignored by assistive technology. See the
  *   roleless-branch implementation note below for the confidence split
  *   this produces.
  * @implementation-notes
- * - Deliberately scoped to the single, well-established prohibition class
+ * - Scoped to the single, well-established prohibition class
  *   (naming attributes on pure text-semantics roles) rather than an
  *   exhaustive per-role prohibited-attribute table; see
  *   src/core/aria-helpers.js file header for this engine's confidence-
@@ -41,7 +41,7 @@
  *   narrower, unambiguous naming-prohibition case fires as a hard,
  *   WCAG-normative fail instead, matching this engine's "one rule = one
  *   normative decision" pattern.
- * - Deliberately excludes `definition`/`term` despite both appearing on
+ * - Excludes `definition`/`term` on purpose, despite both appearing on
  *   MDN's aria-label "not supported" list: both support name from author
  *   (`nameFrom: ['author']` for definition, `['author', 'contents']` for
  *   term), and the W3C spec's §5.2.8.4 "Roles Supporting Name From Author"
@@ -50,9 +50,9 @@
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
  * - Second, independent branch: naming attributes on ROLELESS elements (no
- *   explicit role="", no implicit/native role either) — e.g. icon-only
+ *   explicit role="", no implicit/native role either), e.g. icon-only
  *   `<span aria-label="...">` tiles with no other accessible-name source.
- *   ROLELESS_NATIVE_TAGS below is a curated, deliberately conservative
+ *   ROLELESS_NATIVE_TAGS below is a curated, intentionally conservative
  *   list of native tags confirmed to carry no implicit role (common
  *   text-level tags like `<p>`/`<strong>`/`<em>`/`<code>`/`<mark>`/`<time>`
  *   resolve to role `null`, same as a bare `<div>`/`<span>`);
@@ -65,7 +65,7 @@
  *   already produces a non-empty accessible name from its content (via
  *   `helpers.getContentNameInfo`, same as
  *   link-name-present/button-name-present), the naming attribute might
- *   just be a redundant/intentional override — reported as `cantTell`, not
+ *   just be a redundant/intentional override, so it's reported as `cantTell`, not
  *   a hard fail. Only a roleless element with no other accessible-name
  *   source at all is a confident, deterministic `fail`. The
  *   widget-ancestor exemption (skip when the closest real ancestor role is
@@ -119,8 +119,8 @@ function runInPage(ctx) {
   // Roles whose WAI-ARIA 1.2 definition lists a "Prohibited ARIA States and
   // Properties" entry for naming attributes (these roles must never carry an
   // accessible name). Declared inside runInPage (rather than at module
-  // scope) because the build inlines only this function's own source text
-  // — see scripts/build-core.js header ("runInPage MUST be self-contained").
+  // scope) because the build inlines only this function's own source text.
+  // See scripts/build-core.js header ("runInPage MUST be self-contained").
   const ROLES_PROHIBITING_NAME = new Set([
     'caption',
     'code',
@@ -190,7 +190,7 @@ function runInPage(ctx) {
   // and how ROLELESS_NATIVE_TAGS/WIDGET_TYPE_ROLES were derived) ---
 
   // Small, curated set of native tags verified to carry no explicit or
-  // implicit ARIA role. Deliberately excludes <section>/<form>/<a> — all
+  // implicit ARIA role. Excludes <section>/<form>/<a>, which are
   // conditionally roleless too, but already handled with more nuance
   // elsewhere in this engine (see header comment).
   const ROLELESS_NATIVE_TAGS = new Set([
@@ -268,7 +268,7 @@ function runInPage(ctx) {
         };
 
   // Nearest ancestor's real role (explicit-if-valid, else native/implicit),
-  // skipping roleless/presentation/none ancestors — used only to check
+  // skipping roleless/presentation/none ancestors. Used only to check
   // whether that role is a "widget"-type one (the roleless-branch
   // exemption). Not the same helper as aria-required-parent's containment
   // walk: this one also accepts non-required-context roles.
@@ -296,7 +296,7 @@ function runInPage(ctx) {
 
   // A small, spec-reserved set of hyphenated tag names that are NOT
   // autonomous custom elements despite containing a hyphen (legacy SVG/
-  // MathML tags predating the Custom Elements spec) — see
+  // MathML tags predating the Custom Elements spec). See
   // https://html.spec.whatwg.org/#valid-custom-element-name's own
   // exclusion list. Excluded so this doesn't misclassify them as
   // always-roleless the same way a real custom element is.
@@ -336,8 +336,8 @@ function runInPage(ctx) {
     const tag = String(el.tagName || '').toLowerCase();
     if (!ROLELESS_NATIVE_TAGS.has(tag) && !isRolelessCustomElementTag(tag)) continue;
     const explicitRole = ariaHelpers.getExplicitRole(el);
-    if (explicitRole && ariaHelpers.isValidConcreteRole(explicitRole)) continue; // has a real, recognized role — Tier 1's concern (if in ROLES_PROHIBITING_NAME) or a role this rule has no opinion on. An INVALID role token (e.g. a typo) is ignored per spec, same as no role attribute at all, and must still fall through to this branch.
-    if (ariaHelpers.getNativeRoleForElement(el)) continue; // has a real implicit role after all — not this branch's concern
+    if (explicitRole && ariaHelpers.isValidConcreteRole(explicitRole)) continue; // has a real, recognized role: Tier 1's concern (if in ROLES_PROHIBITING_NAME) or a role this rule has no opinion on. An INVALID role token (e.g. a typo) is ignored per spec, same as no role attribute at all, and must still fall through to this branch.
+    if (ariaHelpers.getNativeRoleForElement(el)) continue; // has a real implicit role after all, not this branch's concern
 
     const present = [];
     for (const attr of PROHIBITED_NAMING_ATTRS) {
@@ -349,7 +349,7 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     const ancestorRole = getNearestAncestorRole(el);
-    if (ancestorRole && WIDGET_TYPE_ROLES.has(ancestorRole)) continue; // roleless helper node inside a real widget — not flagged
+    if (ancestorRole && WIDGET_TYPE_ROLES.has(ancestorRole)) continue; // roleless helper node inside a real widget, not flagged
 
     const nameInfo = helpers.getContentNameInfo ? helpers.getContentNameInfo(el, ctx) : null;
     const hasContentFallback = !!(
@@ -363,7 +363,7 @@ function runInPage(ctx) {
         cantTellOccurrences.push(
           helpers.reportOccurrence(el, {
             occurrenceOutcome: 'cantTell',
-            summary: `This ${tag} has no role, so ${attr} may not be exposed as its accessible name by assistive technology — but the element's own content already provides one.`,
+            summary: `This ${tag} has no role, so ${attr} may not be exposed as its accessible name by assistive technology, but the element's own content already provides one.`,
             hint: 'Verify whether the existing text content already serves as this element’s label; if so the naming attribute is redundant, otherwise give the element a role that supports naming (e.g. role="img").',
             i18n: {
               summaryKey: 'ariaProhibitedAttr_summary_cantTell_roleless',
@@ -411,7 +411,7 @@ function runInPage(ctx) {
 
   // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
   // a fail-tier finding never silently discards cantTell-tier findings from
-  // the same run — both are returned together when the outcome is 'fail'.
+  // the same run. Both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     cantTellOccurrences,