@surea11y/core 1.3.0 → 1.4.0

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -7,15 +9,17 @@
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   Applies to (a) elements whose explicit, valid role is one of the small
- *   set of WAI-ARIA 1.2 roles with a documented "Prohibited ARIA States and
- *   Properties" list (pure text-semantics / non-naming structural roles:
- *   caption, code, deletion, emphasis, generic, insertion, mark, none,
- *   paragraph, presentation, strong, subscript, suggestion, superscript,
- *   time), and (b) a small, curated set of native HTML tags verified to
- *   carry no explicit or implicit ARIA role at all (see ROLELESS_NATIVE_TAGS
- *   below) — in both cases, only elements that also carry aria-label or
- *   aria-labelledby.
+ *   Applies to (a) elements whose explicit, valid role is one of the ARIA
+ *   1.2 roles with a documented "Prohibited ARIA States and Properties"
+ *   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 —
+ *   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
+ *   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
@@ -24,97 +28,55 @@
  *   this produces.
  * @implementation-notes
  * - Deliberately scoped to the single, well-established prohibition class
- *   (naming attributes on pure text-semantics roles) rather than
- *   attempting an exhaustive per-role prohibited-attribute table; see
+ *   (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-
- *   scoping rationale.
- * - Role list widened 2026-07-19 (Tier 4) from 10 to 13 roles, adding
- *   `mark`, `suggestion`, and `time` — the other ARIA 1.2 "HTML-alignment"
- *   text-level roles that share the same documented prohibition as the
- *   original 10. Still deliberately not claiming full parity with a widely-used
- *   reference engine:
- *   only roles/attrs this engine has high confidence in from the spec
- *   text are included, per the file's own "wrong entries cause false-
- *   positive fails" caution.
- * - Widened again 2026-07-21 to add `presentation`/`none`, verified
- *   directly against a widely-used reference engine's own role data table
- *   (both have `prohibitedAttrs: ['aria-label', 'aria-labelledby']`), and
- *   corroborated by the W3C
- *   WAI-ARIA 1.2 spec's own §5.2.8.6 "Roles which cannot be named"
- *   listing `presentation` explicitly (`none` is `presentation`'s
- *   documented 1.2-introduced alias, identical semantics). The
- *   pre-existing `presentation-role-conflict` rule already treats
- *   aria-label/aria-labelledby as conflicting on these two roles, but at
- *   `manual`/cantTell confidence across a ~24-attribute general list —
- *   this addition lets the specific, unambiguous naming-prohibition case
- *   also fire as a hard, WCAG-normative `fail` via this rule, matching
- *   this engine's "one rule = one normative decision" pattern rather than
- *   only ever surfacing it as advisory.
- * - Investigated, but deliberately did NOT add, `definition`/`term`
- *   despite both appearing on MDN's aria-label reference page's
- *   "not supported" list: that MDN list is demonstrably wrong for these
- *   two — a widely-used reference engine's own role data explicitly declares
- *   `nameFrom: ['author']` (`definition`) / `nameFrom: ['author',
- *   'contents']` (`term`), and the W3C spec's own §5.2.8.4 "Roles
- *   Supporting Name From Author" index lists both by name; MDN's
- *   `definition_role` page even demonstrates `aria-labelledby` usage on
- *   it directly. A real, confirmed documentation bug on MDN's side, not
- *   a gap here.
+ *   scoping rationale. The 14-role list comes from the W3C WAI-ARIA 1.2
+ *   spec's §5.2.8.6 "Roles which cannot be named"; only roles/attrs with
+ *   high confidence from the spec text are included, since a wrong entry
+ *   here causes a false-positive fail.
+ * - The pre-existing presentation-role-conflict rule already treats
+ *   aria-label/aria-labelledby as conflicting on presentation/none, but at
+ *   manual/cantTell confidence across a broad attribute list; this rule's
+ *   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
+ *   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"
+ *   index lists both by name.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
- * - Widened 2026-07-31 to add a second, independent branch covering
- *   naming attributes on ROLELESS elements (no explicit role="", no
- *   implicit/native role either) — found on the emoji-mart demo page
- *   (missive.github.io/emoji-mart): hundreds of
- *   `<span aria-label="party_parrot" class="emoji-mart-emoji...">` tiles,
- *   plain roleless spans with no other accessible-name source, which this
- *   rule previously ignored entirely, since its own Tier-1 branch only ever
- *   looked at the EXPLICIT role="" attribute, never at "no role at all."
- *   Empirically determined (not guessed) which native tags genuinely carry
- *   no role at all, by resolving each candidate tag's role against a live
- *   Chromium page — several surprises: common text-level tags like `<p>`,
- *   `<strong>`, `<em>`, `<code>`, `<mark>`, `<time>` have no implicit role
- *   at all (their prohibited-attrs entries only ever matter for an
- *   EXPLICIT `role="paragraph"`/`role="strong"`/etc. restatement, a rare
- *   case — the native tag itself resolves to role `null`, same as a bare
- *   `<div>`/`<span>`, and falls into this same roleless branch). See
- *   ROLELESS_NATIVE_TAGS below for the resulting curated list —
- *   deliberately conservative: `<section>`/`<form>`/`<a>` are excluded
- *   even though they can also resolve to no role, because their native
- *   role is conditional (name-dependent/href-dependent) and already has
- *   dedicated, more nuanced handling elsewhere in this engine
- *   (`getElementRoleKey`'s `section`/`section[named]`/`header`/
- *   `header[toplevel]` branches) that this rule doesn't attempt to
- *   duplicate.
+ * - Second, independent branch: naming attributes on ROLELESS elements (no
+ *   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
+ *   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>`);
+ *   `<section>`/`<form>`/`<a>` are excluded even though they can also
+ *   resolve to no role, because their native role is conditional
+ *   (name-dependent/href-dependent) and already has dedicated handling in
+ *   `getElementRoleKey`'s `section`/`section[named]`/`header`/
+ *   `header[toplevel]` branches that this rule doesn't duplicate.
  *   Two confidence tiers instead of a flat fail: if the element's subtree
- *   ALREADY produces a non-empty accessible name from its content
- *   (computed the same way link-name-present/button-name-present do, via
- *   `helpers.getContentNameInfo`), the naming attribute might just be a
- *   redundant/intentional override — reported as `cantTell`, not a hard
- *   fail. Only a roleless element with NO other accessible-name source at
- *   all (the emoji-mart case: an icon-only span, background-image styled,
- *   no text anywhere in its subtree) is a confident, deterministic `fail`
- *   — nothing else could ever expose this element's name, and no role
- *   exists to make it a Name/Role/Value candidate in the first place.
- *   The widget-ancestor exemption (skip when the closest real ancestor role
- *   is a "widget"-type role) avoids over-flagging roleless helper
- *   spans/divs used as internal decoration inside a custom composite
- *   widget.
- * - Fixed 2026-07-31 (same day as introduced): the Tier-2 "already has a
- *   role, not this branch's concern" guard checked only whether `role=""`
- *   was present (`getExplicitRole`), not whether the value was a real,
- *   recognized ARIA role. An invalid/typo'd role token (e.g.
- *   `role="totally-bogus"`) therefore silently suppressed detection of an
- *   otherwise-flaggable roleless naming attribute — identical markup with
- *   the bogus role attribute removed entirely correctly failed, but with
- *   it present the element was skipped as if it had a real role. Per spec
- *   (and per this same file's own `getNearestAncestorRole` helper a few
- *   lines below, which already gets this right), an unrecognized role
- *   token is ignored by the accessibility tree, not honored — the element
- *   is still effectively roleless. Now validates via the existing
- *   `isValidConcreteRole` before treating an explicit role as real,
- *   matching `getNearestAncestorRole`'s own pattern.
+ *   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
+ *   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
+ *   a "widget"-type role) avoids over-flagging roleless helper spans/divs
+ *   used as internal decoration inside a custom composite widget.
+ * - The Tier-2 "already has a role, not this branch's concern" guard
+ *   validates the explicit role via `isValidConcreteRole` before treating
+ *   it as real (matching `getNearestAncestorRole`'s own pattern): an
+ *   unrecognized role token (e.g. `role="totally-bogus"`) is ignored by
+ *   the accessibility tree, not honored, so the element is still
+ *   effectively roleless and must still be checked by this branch.
  */
 
 const id = 'aria-prohibited-attr';
@@ -212,6 +174,7 @@ function runInPage(ctx) {
       failOccurrences.push({
         selector: stableSelector,
         html,
+        occurrenceOutcome: 'fail',
         summary: 'This attribute is prohibited on this element’s role.',
         hint: 'Remove this attribute; this role must not carry an accessible name.',
         i18n: {
@@ -229,11 +192,10 @@ function runInPage(ctx) {
   // --- Tier 2: no role at all (see header comment for the full rationale
   // and how ROLELESS_NATIVE_TAGS/WIDGET_TYPE_ROLES were derived) ---
 
-  // Small, curated set of native tags empirically verified (against a
-  // widely-used reference engine's own getRole() at runtime, not guessed)
-  // to carry no explicit or implicit ARIA role. Deliberately excludes
-  // <section>/<form>/<a> — all conditionally roleless too, but already
-  // handled with more nuance elsewhere in this engine (see header comment).
+  // Small, curated set of native tags verified to carry no explicit or
+  // implicit ARIA role. Deliberately excludes <section>/<form>/<a> — all
+  // conditionally roleless too, but already handled with more nuance
+  // elsewhere in this engine (see header comment).
   const ROLELESS_NATIVE_TAGS = new Set([
     'p',
     'b',
@@ -268,10 +230,8 @@ function runInPage(ctx) {
     'legend'
   ]);
 
-  // WAI-ARIA roles a widely-used reference engine's own role table types as
-  // "widget" (verified directly against its source, not the six-category
-  // WAI-ARIA taxonomy — this engine's algorithm branches on its own `type`
-  // field, so parity means matching that field exactly).
+  // WAI-ARIA roles typed as "widget" (the role set the roleless-branch
+  // exemption below branches on, not the six-category WAI-ARIA taxonomy).
   const WIDGET_TYPE_ROLES = new Set([
     'alert',
     'alertdialog',
@@ -337,6 +297,37 @@ function runInPage(ctx) {
     return '';
   }
 
+  // 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
+  // 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.
+  const RESERVED_HYPHENATED_TAGS = new Set([
+    'annotation-xml',
+    'color-profile',
+    'font-face',
+    'font-face-src',
+    'font-face-uri',
+    'font-face-format',
+    'font-face-name',
+    'missing-glyph'
+  ]);
+
+  // An autonomous custom element (author-defined tag, always containing a
+  // hyphen per the Custom Elements spec's naming grammar) has no implicit
+  // ARIA role at all -- unlike native tags, there is no conditional-role
+  // nuance to worry about here (a native <a>/<section>/<form> can gain an
+  // implicit role depending on other attributes, which is exactly why
+  // ROLELESS_NATIVE_TAGS is a hand-verified allowlist rather than a
+  // blanket rule; a custom element has no such spec-defined conditional
+  // role logic whatsoever). Covers e.g. a `<play-button aria-label="...">`
+  // or `<app-carousel aria-label="...">` with no other name source, which
+  // the fixed native-tag allowlist below would otherwise skip.
+  function isRolelessCustomElementTag(tag) {
+    return tag.includes('-') && !RESERVED_HYPHENATED_TAGS.has(tag);
+  }
+
   const namingSelector = '[aria-label],[aria-labelledby]';
   const namingNodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(namingSelector)
@@ -346,7 +337,7 @@ function runInPage(ctx) {
     if (!el || !el.getAttribute) continue;
 
     const tag = String(el.tagName || '').toLowerCase();
-    if (!ROLELESS_NATIVE_TAGS.has(tag)) continue;
+    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
@@ -378,6 +369,7 @@ function runInPage(ctx) {
         cantTellOccurrences.push({
           selector: stableSelector,
           html,
+          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.`,
           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: {
@@ -398,6 +390,7 @@ function runInPage(ctx) {
         failOccurrences.push({
           selector: stableSelector,
           html,
+          occurrenceOutcome: 'fail',
           summary: `This ${tag} has no role and no other accessible-name source, so ${attr} is not reliably exposed to assistive technology.`,
           hint: 'Give this element a role that supports an accessible name (e.g. role="img"/"button"), or remove this attribute if it serves no purpose without one.',
           i18n: {

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,86 +22,54 @@
  *   owned set. Nothing else is a structurally valid direct child of a
  *   composite/container role.
  * @implementation-notes
- * - A distinct atomic decision from aria-required-children (see
- *   that rule): "does at least one required child exist" vs "is every
- *   owned child one of the allowed roles." A widely-used reference engine
- *   bundles both under one check (`aria-required-children`); this repo's
- *   "one rule = one normative decision" principle splits them, matching
- *   the established pattern elsewhere of surea11y rules mapping
- *   many-to-one against a single check in that reference engine.
- * - The "allowed owned roles" set is exactly REQUIRED_OWNED_ROLES — not
- *   a separately authored, broader list. Verified directly against a
- *   widely-used reference engine's own ariaRequiredChildren/getOwnedRoles
- *   algorithm: an owned element is only considered allowed if its role is
- *   literally in the container's required set; that engine does not
- *   define a superset "allowed but not required" list for this purpose.
- *   Found and verified via a real page (Red Cross's homepage: a
- *   <nav role="region"> nested inside a <ul role="menubar"> through a
- *   role="none" <li> wrapper — a real violation that reference engine
- *   caught that aria-required-children's own scope (documented
- *   there as "can only under-report, never over-report") does not).
- * - Widened 2026-07-21 to also flag a ROLELESS descendant that has any
- *   global WAI-ARIA attribute or is focusable, matching a widely-used
- *   reference engine's own `getOwnedRoles` exactly (verified directly
- *   against its source: `hasGlobalAriaOrFocusable =
- *   !!globalAriaAttr || _isFocusable(vNode)` — such a descendant is
- *   pushed as an owned entry with `role: null`, which can never match a
- *   container's required-owned-roles set, so it's always "unallowed").
- *   Previously left out as riskier to replicate — re-evaluated given
- *   direct access to that engine's exact algorithm (not a guess) plus this
- *   engine's own already-existing, shared `helpers.getFocusableInfo` for
- *   the focusability half. Both signals (global-attribute presence,
- *   focusability) are static, declarative markup facts with no live-DOM/
- *   hydration risk, unlike e.g. `aria-checked-state-mismatch`'s DOM-
- *   property comparison.
- * - Fixed 2026-07-30: a roleless-but-focusable descendant's message and
- *   `data.details.attr` used to always claim "carries tabindex" even when
- *   the element had no tabindex attribute at all and was only focusable
- *   natively (e.g. an <a href> link). `helpers.getFocusableInfo`'s
- *   `mechanism` field ('tabindex' | 'native' | ...) is now used to tell
- *   the two apart, with a distinct `nativeFocusable` attr/message for the
- *   native case. Found via a real Angular app: a routerLink <a> inside a
- *   role="list" was reported as "carries tabindex" though the rendered
- *   markup had no such attribute.
- * - Recursion stops at the first non-transparent role boundary, same as
- *   that reference engine: a nested container with its own real role (e.g. a
- *   <div role="listbox"> inside a menubar) is evaluated as ITS OWN
- *   owned-role entry against the outer container (and, separately, gets
- *   its own applicability pass as a container in the same rule run) —
- *   its descendants are never misattributed to the outer container.
- * - Fixed 2026-07-31: child-role resolution used `ariaHelpers.getExplicitRole`
- *   (explicit role="" attribute only), unlike aria-required-children's
- *   descendant matching which uses `ariaHelpers.getContainmentRole` (explicit
+ * - A distinct atomic decision from aria-required-children (see that
+ *   rule): "does at least one required child exist" vs "is every owned
+ *   child one of the allowed roles" — split per this repo's "one rule =
+ *   one normative decision" principle.
+ * - The "allowed owned roles" set is exactly REQUIRED_OWNED_ROLES, not a
+ *   separately authored, broader list: an owned element is allowed only if
+ *   its role is literally in the container's required set.
+ * - A ROLELESS descendant that has any global WAI-ARIA attribute or is
+ *   focusable is also flagged: it's treated as an owned entry with
+ *   `role: null`, which can never match a container's required-owned-roles
+ *   set, so it's always "unallowed". Both signals
+ *   (global-attribute presence, focusability via the shared
+ *   `helpers.getFocusableInfo`) are static, declarative markup facts with
+ *   no live-DOM/hydration risk, unlike e.g.
+ *   `aria-checked-state-mismatch`'s DOM-property comparison.
+ *   `helpers.getFocusableInfo`'s `mechanism` field ('tabindex' | 'native' |
+ *   ...) distinguishes an explicit `tabindex` attribute from native
+ *   focusability (e.g. an `<a href>`), so the reported `data.details.attr`
+ *   and message correctly say `nativeFocusable` rather than claiming a
+ *   tabindex attribute that isn't actually present in the markup.
+ * - Recursion stops at the first non-transparent role boundary: a nested
+ *   container with its own real role
+ *   (e.g. a `<div role="listbox">` inside a menubar) is evaluated as its
+ *   own owned-role entry against the outer container (and, separately,
+ *   gets its own applicability pass as a container in the same rule run)
+ *   — its descendants are never misattributed to the outer container.
+ * - Child-role resolution uses `ariaHelpers.getContainmentRole` (explicit
  *   role, falling back to the native-tag map — li/tr/td/th/tbody/ul/ol/
- *   table/select/input[type=radio] — see that helper's own header comment).
- *   A bare `<li>` with no role="" attribute — the common CSS-reset
- *   workaround `<ul role="list"><li>...</li></ul>` that getContainmentRole
- *   exists specifically to handle — was therefore read as roleless here,
- *   making it structurally transparent: the walk recursed straight through
- *   the listitem boundary into its subtree and could report a focusable
- *   descendant several levels down as a disallowed owned child of the list,
- *   instead of stopping at the (implicit) listitem the way
- *   aria-required-children already does. Switched to getContainmentRole so
- *   both rules resolve an owned child's role identically. This is a general
- *   fix, not list/listitem-specific: it applies to every container role in
- *   REQUIRED_OWNED_ROLES whose native-tag counterpart the child map covers
- *   (e.g. a bare `<tr>`/`<td>` under a role="table"/"grid"/"row" container
- *   with no explicit role="" was subject to the same flattening bug). Found
- *   via a real Angular Material-style component library: an `<a routerlink>`
- *   several DOM levels inside a bare `<li>` under `<ul role="list">` was
- *   reported as an unallowed owned child of the list.
- * - Gated on isAccTreeEligible for the container itself, matching the fix
- *   applied to aria-required-children (see that rule's header): the
- *   original "not gated" note here just cited that rule's reasoning
- *   without re-deriving it, and that reasoning turned out not to hold —
- *   a closed dialog/flyout menu populated on open is a real false-positive
- *   shape. In this rule specifically the descendant-level eligibility gate
- *   already made the container-level gate redundant for correctness (an
- *   ineligible container has no eligible descendants either, so `owned`
- *   ends up empty and nothing fails) — but skipping the container up front
- *   reports `notApplicable` instead of a vacuous `pass`, which is the more
- *   accurate outcome for a container that isn't currently exposed at all,
- *   and avoids walking a subtree whose result is already known.
+ *   table/select/input[type=radio]), the same resolution
+ *   aria-required-children's descendant matching uses — not
+ *   `getExplicitRole`, which only sees an explicit role="" attribute. A
+ *   bare `<li>` with no role="" (the common CSS-reset workaround
+ *   `<ul role="list"><li>...</li></ul>`) must still resolve to the
+ *   implicit listitem role so the walk stops at that boundary instead of
+ *   recursing straight through it into the listitem's own subtree; the
+ *   same applies to every container role in REQUIRED_OWNED_ROLES whose
+ *   native-tag counterpart the child map covers (e.g. a bare
+ *   `<tr>`/`<td>` under a role="table"/"grid"/"row" container).
+ * - Gated on isAccTreeEligible for the container itself, matching
+ *   aria-required-children: a closed dialog/flyout menu populated on open
+ *   is a real false-positive shape otherwise. The descendant-level
+ *   eligibility gate alone would make the container-level gate redundant
+ *   for correctness (an ineligible container has no eligible descendants
+ *   either, so `owned` ends up empty and nothing fails), but skipping the
+ *   container up front reports `notApplicable` instead of a vacuous
+ *   `pass` — the more accurate outcome for a container that isn't
+ *   currently exposed at all — and avoids walking a subtree whose result
+ *   is already known.
  * - No aria-busy exemption here (unlike aria-required-children): the
  *   WAI-ARIA spec's aria-busy escape hatch is specifically about a
  *   container missing its required owned elements while loading, not
@@ -161,7 +131,7 @@ function runInPage(ctx) {
   // aria-allowed-attr.js's GLOBAL_ATTRS — duplicated, not imported, since
   // runInPage must be self-contained per scripts/build-core.js). A
   // roleless descendant carrying any of these is a real accessible-tree
-  // node a widely-used reference engine's getOwnedRoles also flags, not a transparent wrapper.
+  // node, not a transparent wrapper.
   const GLOBAL_ARIA_ATTRS = [
     'aria-atomic',
     'aria-braillelabel',
@@ -205,13 +175,12 @@ function runInPage(ctx) {
   // non-transparent role boundary otherwise — see header comment. A
   // roleless descendant is ALSO a non-transparent boundary (an owned
   // entry with role: null, which can never satisfy a required-role set)
-  // when it carries a global aria-* attribute or is focusable — matches
-  // a widely-used reference engine's own getOwnedRoles exactly (see header comment).
-  // kidRole comes from getContainmentRole, not getExplicitRole (see header
-  // comment's 2026-07-31 fix): "roleless" here means neither an explicit
-  // role="" NOR one of the native containment tags (li, tr, td, ...), so a
-  // bare <li>/<tr>/... is a real listitem/row boundary, not a transparent
-  // wrapper the walk should pass through.
+  // when it carries a global aria-* attribute or is focusable.
+  // kidRole comes from getContainmentRole, not getExplicitRole: "roleless"
+  // here means neither an explicit role="" NOR one of the native
+  // containment tags (li, tr, td, ...), so a bare <li>/<tr>/... is a real
+  // listitem/row boundary, not a transparent wrapper the walk should pass
+  // through.
   function collectOwnedRoles(el, requiredSet, out, depth) {
     if (depth > MAX_DEPTH) return;
     const kids = el.children ? Array.prototype.slice.call(el.children) : [];

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,13 +20,10 @@
  * - Deliberately scoped to REQUIRED_PROPS_BY_ROLE in src/core/aria-helpers.js,
  *   which only lists a required property when the spec is unambiguous and
  *   context-independent — see that file's header for the rationale.
- * - Widened 2026-07-21 to add `meter` (`aria-valuenow`), verified against
- *   a widely-used reference engine's own `requiredAttrs` table. Deliberately
- *   did NOT add two other entries from that same table: `progressbar`'s
- *   `aria-valuenow` (a legitimately indeterminate progressbar omits it —
- *   that engine itself excludes progressbar from its own table for this reason)
- *   and `combobox`'s `aria-controls` (confirmed via MDN's combobox role
- *   page to be conditional — only required once the popup is actually
+ * - `meter`'s `aria-valuenow` is required. Deliberately NOT required:
+ *   `progressbar`'s `aria-valuenow` (a legitimately indeterminate
+ *   progressbar omits it) and `combobox`'s `aria-controls` (conditional per
+ *   MDN's combobox role page — only required once the popup is actually
  *   displayed, not unconditionally). See src/core/aria-helpers.js's
  *   REQUIRED_PROPS_BY_ROLE comment for the full reasoning.
  * - Gated on isAccTreeEligible for the element itself: unlike a syntax-

package/src/checks/automatic/aria-required-children.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -42,9 +44,7 @@
  *   widget is missing required owned elements due to script execution or
  *   loading, authors MUST mark a containing element with aria-busy equal
  *   to true." A container carrying aria-busy="true" is skipped the same
- *   way — only the exact string "true" counts (absent/"false" do not),
- *   matching a widely-used reference engine's own aria-required-children
- *   behavior.
+ *   way — only the exact string "true" counts (absent/"false" do not).
  * - Descendant search tries a fast native querySelectorAll(CANDIDATE_
  *   SELECTOR) first (covers the light-DOM-only common case with no added
  *   cost); only when that finds nothing AND the container has a <slot>
@@ -53,8 +53,7 @@
  *   querySelectorAll only sees a <slot>'s unrendered fallback content, never
  *   what's actually distributed into it. Deliberately scoped to slot
  *   expansion only, not a general "also descend into any nested custom
- *   element's own shadow root" walk — no confirmed real-world case needs
- *   that yet.
+ *   element's own shadow root" walk — no known case needs that yet.
  */
 
 const id = 'aria-required-children';
@@ -133,17 +132,15 @@ function runInPage(ctx) {
   // <slot></slot>, with the actual role="listitem" elements living in the
   // light DOM and projected in) would never find them there — same class
   // of bug as aria-required-parent's ancestor search, just in the opposite
-  // (descendant) direction. Found via Adobe Spectrum Web Components'
-  // sp-sidenav-item: its shadow root's role="list" div owns its listitems
-  // only through slot projection.
+  // (descendant) direction.
   //
   // Deliberately scoped to slot expansion only — does NOT separately
   // descend into an unrelated nested custom element's own shadow root
   // (e.g. a <my-widget> child with no <slot> involvement at all). That's a
   // qualitatively different question (does an arbitrary component's own
   // internal structure count as this container's "owned children"?) with
-  // no confirmed real-world case driving it yet; slot projection is the
-  // shape actually observed.
+  // no known case driving it yet; slot projection is the shape that
+  // actually comes up.
   function collectComposedDescendants(node, out, seen, limit) {
     if (!node || !node.children) return;
     for (const child of Array.from(node.children)) {

package/src/checks/automatic/aria-required-parent.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -94,24 +96,20 @@ function runInPage(ctx) {
   }
 
   // Roles that may host a nested listitem/treeitem group without breaking
-  // the required-context chain (verified against a widely-used reference
-  // engine's own getMissingContext, which special-cases exactly these two
-  // roles via its ownGroupRoles option).
+  // the required-context chain — the group role is transparent for exactly
+  // these two roles.
   const GROUP_TRANSPARENT_FOR_ROLES = new Set(['listitem', 'treeitem']);
 
   // A real ancestor role — not "no role at all" and not the two roles that
   // strip an element from the accessibility tree's parent/child chain
-  // entirely (presentation/none) — stops the search, matching that reference
-  // engine's getMissingContext. This is stricter than "any ancestor with the right
-  // role anywhere up the tree": the required-context relationship is about
-  // the accessibility tree's actual PARENT, so an intervening ancestor with
-  // its OWN distinct real role (e.g. a plain <li>'s native "listitem" role)
-  // blocks the search even if a further-up ancestor has the correct role.
-  // Found via a real page — Le Monde's review-carousel tablist, where each
-  // <button role="tab"> sits inside a plain <li> (native listitem) inside
-  // <ul role="tablist">: that reference engine correctly fails this (the tablist is never the
-  // tab's accessible-tree parent, listitem is), which the old "walk every
-  // ancestor" version here missed entirely.
+  // entirely (presentation/none) — stops the search. This is stricter than
+  // "any ancestor with the right role anywhere up the tree": the
+  // required-context relationship is about the accessibility tree's actual
+  // PARENT, so an intervening ancestor with its OWN distinct real role
+  // (e.g. a plain <li>'s native "listitem" role) blocks the search even if
+  // a further-up ancestor has the correct role. E.g. a <button role="tab">
+  // inside a plain <li> (native listitem) inside <ul role="tablist"> fails:
+  // the tablist is never the tab's accessible-tree parent, the listitem is.
   function getRealContextRole(el) {
     const role = ariaHelpers.getContainmentRole(el);
     if (!role || role === 'presentation' || role === 'none') return '';
@@ -121,13 +119,11 @@ function runInPage(ctx) {
   // Flat-tree ancestor walk (ctx.helpers.composedParent — assignedSlot wins
   // over parentNode, then shadow host). A slotted light-DOM element's real
   // rendered ancestor is whatever the shadow tree wraps its <slot> in (e.g.
-  // a role="list" container), not its own light-DOM parentElement — found
-  // via Adobe Spectrum Web Components' <sp-sidenav-item role="listitem">,
-  // distributed via slot="descendant" into its parent's shadow root, which
-  // wraps that slot in a <div role="list">. composedParent can return a
-  // non-Element node (a ShadowRoot, nodeType 11) when climbing out of a
-  // shadow tree that has no further light-DOM parent — skip those and keep
-  // climbing rather than treating them as a (roleless) context.
+  // a role="list" container), not its own light-DOM parentElement.
+  // composedParent can return a non-Element node (a ShadowRoot, nodeType
+  // 11) when climbing out of a shadow tree that has no further light-DOM
+  // parent — skip those and keep climbing rather than treating them as a
+  // (roleless) context.
   const getComposedParent =
     helpers && typeof helpers.composedParent === 'function'
       ? helpers.composedParent
@@ -142,10 +138,9 @@ function runInPage(ctx) {
     // Mutable working copy: passing a transparent "group" ancestor also
     // makes the element's OWN role an acceptable context from that point on
     // (a nested treeitem-under-group-under-treeitem chain is a normal,
-    // arbitrarily-deep ARIA tree/list, not just one level) — mirroring that
-    // reference engine's getMissingContext, which pushes explicitRole into
-    // reqContext at the same point. Cloned lazily so the caller's Set (built
-    // once per element in runInPage) is never mutated.
+    // arbitrarily-deep ARIA tree/list, not just one level). Cloned lazily
+    // so the caller's Set (built once per element in runInPage) is never
+    // mutated.
     let roles = acceptableRoles;
     while (cur && guard++ < 200) {
       if (cur.nodeType !== 1) {

package/src/checks/automatic/aria-role-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**