@surea11y/core 1.4.1 → 1.6.0

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

@@ -12,23 +12,38 @@
  *   Applies to elements with an explicit, valid role that is one of the
  *   container roles with a documented "required owned elements" entry
  *   (the same REQUIRED_OWNED_ROLES table aria-required-children
- *   uses — see src/core/aria-helpers.js).
+ *   uses, see src/core/aria-helpers.js).
  * @expectation
  *   Every accessible-tree-owned descendant of the container (after
  *   pruning role="none"/"presentation" elements and any "group"/
- *   "rowgroup" wrapper whose role is itself one of the required roles —
- *   both are structurally transparent, same as WAI-ARIA's own
- *   accessibility-tree construction) has a role from that same required-
- *   owned set. Nothing else is a structurally valid direct child of a
- *   composite/container role.
+ *   "rowgroup" wrapper, both always transparent for owned-element
+ *   matching per WAI-ARIA, regardless of whether "group"/"rowgroup" is
+ *   itself in the container's own required-owned-roles set) has a role
+ *   from that same required-owned set. Nothing else is a structurally
+ *   valid direct child of a composite/container role, where "allowed" is
+ *   the container's required-owned roles plus the small
+ *   ALLOWED_EXTRA_OWNED_ROLES set of roles it may own without being
+ *   required to (a separator between menu items, a caption on a grid). A
+ *   roleless wrapper
+ *   is descended into to reach the items a component library buries
+ *   inside it, but once one is found there the rest of that wrapper's
+ *   subtree is the item's own content and is not judged against the
+ *   container.
  * @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" — split per this repo's "one rule =
+ *   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.
+ * - The "allowed owned roles" set is REQUIRED_OWNED_ROLES plus
+ *   ALLOWED_EXTRA_OWNED_ROLES, because WAI-ARIA's "Required Owned
+ *   Elements" says what a container MUST contain, not the exhaustive list
+ *   of what it MAY contain. The extra table is kept small, and each entry
+ *   needs a source: ARIA giving the child a Required Context Role that
+ *   names this container (caption in table/grid), or the child role's own
+ *   definition placing it there (separator in menu/menubar). Recorded and
+ *   validated in scripts/generate-aria-tables.js. The two sets are
+ *   used for different questions: only a REQUIRED role makes a roleless
+ *   wrapper an item wrapper, while the allowed set decides the verdict.
  * - 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
@@ -42,16 +57,39 @@
  *   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.
+ * - A roleless wrapper is transparent only as a route to the items inside
+ *   it, never as a way to attribute the item's own content to the
+ *   container. Unlike role="none"/"presentation", a roleless element is
+ *   NOT removed from the accessibility tree: it is exposed as a generic
+ *   node, so strictly nothing inside it is the container's child at all.
+ *   The walk descends anyway, because component markup routinely buries
+ *   the real item several roleless levels down (an Angular Material card
+ *   whose radio sits at card > header > mat-radio-button > div > div >
+ *   input[type=radio]) and refusing to descend would report every such
+ *   container as owning nothing. Applied in both directions, that
+ *   leniency turned every role-bearing element anywhere in an item's
+ *   subtree into an owned child of the container: a `role="separator"`
+ *   dividing two columns inside a radio card was reported as a
+ *   prohibited child of the radiogroup. So when a roleless wrapper turns
+ *   out to hold a required item, only the items it holds are collected;
+ *   a wrapper holding no item at all is interposed content, and
+ *   everything found inside it is still reported.
  * - 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.
+ *   gets its own applicability pass as a container in the same rule run),
+ *   so its descendants are never misattributed to the outer container.
+ *   "group"/"rowgroup" are always transparent instead, for any container
+ *   role, not only the few (menu, menubar, tree) whose own required-owned
+ *   set names "group" as an acceptable leaf role. Confirmed by ACT
+ *   bc4a75's own examples, e.g. a `role="list"` (no "group" in its
+ *   required-owned set) still treating a `role="group"` wrapper as
+ *   transparent.
  * - Child-role resolution uses `ariaHelpers.getContainmentRole` (explicit
- *   role, falling back to the native-tag map — li/tr/td/th/tbody/ul/ol/
+ *   role, falling back to the native-tag map: li/tr/td/th/tbody/ul/ol/
  *   table/select/input[type=radio]), the same resolution
- *   aria-required-children's descendant matching uses — not
+ *   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
@@ -67,14 +105,14 @@
  *   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
+ *   `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
- *   about a container that already has extra/disallowed owned elements —
- *   that scenario isn't this rule's concern.
+ *   about a container that already has extra/disallowed owned elements.
+ *   That scenario isn't this rule's concern.
  */
 
 const id = 'aria-prohibited-children';
@@ -82,7 +120,7 @@ const id = 'aria-prohibited-children';
 const meta = {
   title: 'Container roles must not own a child with a disallowed role',
   description:
-    "Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role's allowed owned roles — the same set as its required owned roles.",
+    "Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role's allowed owned roles.",
   i18n: {
     titleKey: 'ariaProhibitedChildren_title',
     descriptionKey: 'ariaProhibitedChildren_description'
@@ -128,7 +166,7 @@ function runInPage(ctx) {
   }
 
   // The WAI-ARIA "Global States and Properties" set (same list as
-  // aria-allowed-attr.js's GLOBAL_ATTRS — duplicated, not imported, since
+  // aria-allowed-attr.js's GLOBAL_ATTRS, duplicated rather than 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, not a transparent wrapper.
@@ -167,21 +205,41 @@ function runInPage(ctx) {
     return null;
   }
 
+  // Roles a container may own beyond its REQUIRED owned elements. WAI-ARIA's
+  // "Required Owned Elements" says what a container must contain, not the
+  // exhaustive list of what it may contain; using the required set as both
+  // reported a separator between menu items, and a caption on a grid, as
+  // prohibited children. Generated from scripts/generate-aria-tables.js, which
+  // documents the source for every entry and validates each against
+  // aria-query's Required Context Role data.
+  // <generated:aria-allowed-extra-owned-roles>
+  const ALLOWED_EXTRA_OWNED_ROLES = {
+    grid: ['caption'],
+    menu: ['separator'],
+    menubar: ['separator'],
+    table: ['caption']
+  };
+  // </generated:aria-allowed-extra-owned-roles>
+
   const MAX_DEPTH = 40;
 
   // Collects this container's owned-role entries, pruning role="none"/
-  // "presentation" and required-matching "group"/"rowgroup" wrappers as
-  // transparent (recursing through them), and stopping at the first
-  // 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.
+  // "presentation" and "group"/"rowgroup" wrappers as transparent
+  // (recursing through them unconditionally, see header comment), and
+  // stopping at the first non-transparent role boundary otherwise. A
+  // roleless wrapper is transparent too, but only as a way to reach the
+  // items buried inside it: once one is found there, the rest of that
+  // wrapper's subtree belongs to the item, not to this container (see the
+  // roleless branch below). A roleless descendant is 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.
   // 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) {
+  function collectOwnedRoles(el, out, depth, requiredSet) {
     if (depth > MAX_DEPTH) return;
     const kids = el.children ? Array.prototype.slice.call(el.children) : [];
     for (const kid of kids) {
@@ -190,8 +248,7 @@ function runInPage(ctx) {
 
       const kidRole = ariaHelpers.getContainmentRole(kid);
       const isPresentational = kidRole === 'presentation' || kidRole === 'none';
-      const isTransparentGroup =
-        (kidRole === 'group' || kidRole === 'rowgroup') && requiredSet.has(kidRole);
+      const isTransparentGroup = kidRole === 'group' || kidRole === 'rowgroup';
 
       if (!kidRole && !isPresentational) {
         const globalAttr = getGlobalAriaAttr(kid);
@@ -207,7 +264,7 @@ function runInPage(ctx) {
         }
         if (globalAttr || mechanism !== 'none') {
           // `mechanism` distinguishes an actual tabindex="" attribute from
-          // native focusability (e.g. <a href>, <button>, <input>) — these
+          // native focusability (e.g. <a href>, <button>, <input>): these
           // are different facts and must not be reported as the same
           // "carries tabindex" claim (a native anchor with no tabindex
           // attribute at all is not "carrying tabindex").
@@ -217,8 +274,37 @@ function runInPage(ctx) {
         }
       }
 
-      if (!kidRole || isPresentational || isTransparentGroup) {
-        collectOwnedRoles(kid, requiredSet, out, depth + 1);
+      if (isPresentational || isTransparentGroup) {
+        // role="none"/"presentation" really is removed from the accessibility
+        // tree, and its children are promoted to this container, so whatever
+        // is inside becomes an owned child in its own right. group/rowgroup stay
+        // unconditionally transparent for the reason in the header comment.
+        collectOwnedRoles(kid, out, depth + 1, requiredSet);
+        continue;
+      }
+
+      if (!kidRole) {
+        // A roleless wrapper is NOT removed from the accessibility tree: it is
+        // exposed as a generic node, so strictly speaking nothing inside it is
+        // this container's child at all. The walk descends anyway, because a
+        // component library routinely buries the real item several roleless
+        // levels down (an Angular Material card whose radio sits at
+        // card > header > mat-radio-button > div > div > input[type=radio]),
+        // and refusing to descend would report every such container as
+        // missing its items.
+        //
+        // That leniency has to run one way only. If the wrapper turns out to
+        // hold a required item, the wrapper is an item wrapper and everything
+        // else inside it is the ITEM's content, not the container's children:
+        // a mat-divider sitting in the card body beside the radio is not an
+        // owned child of the radiogroup, and reporting it as one is a false
+        // positive on ordinary component markup. Only the items are collected
+        // in that case. A wrapper holding no item at all is pure interposed
+        // content, so everything found in it is still reported.
+        const nested = [];
+        collectOwnedRoles(kid, nested, depth + 1, requiredSet);
+        const items = nested.filter((entry) => entry.role && requiredSet.has(entry.role));
+        for (const entry of items.length ? items : nested) out.push(entry);
         continue;
       }
 
@@ -249,17 +335,20 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
+    // Two different sets on purpose. requiredSet drives the item-wrapper
+    // detection in collectOwnedRoles: only a REQUIRED role makes a roleless
+    // wrapper an item wrapper, so a wrapper holding nothing but a separator is
+    // still interposed content. allowedRoles decides the verdict, and includes
+    // the roles a container may own without being required to.
     const requiredSet = new Set(requiredOwned);
+    const allowedRoles = requiredOwned.concat(ALLOWED_EXTRA_OWNED_ROLES[role] || []);
+    const allowedSet = new Set(allowedRoles);
     const owned = [];
-    collectOwnedRoles(el, requiredSet, owned, 0);
+    collectOwnedRoles(el, owned, 0, requiredSet);
 
     for (const entry of owned) {
-      if (entry.role && requiredSet.has(entry.role)) continue;
+      if (entry.role && allowedSet.has(entry.role)) continue;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(entry.el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(entry.el)
-        : entry.el.outerHTML || '';
       const containerSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
 
       const isRoleless = !entry.role;
@@ -281,34 +370,38 @@ function runInPage(ctx) {
         hintKey = 'ariaProhibitedChildren_hint_fail_roleless';
       } else {
         summary = `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
-        hint = `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+        hint = `Remove or change this role so it matches one of the container's allowed owned roles (${allowedRoles.join(', ')}), or move this element outside the ${role} container.`;
         summaryKey = 'ariaProhibitedChildren_summary_fail';
         hintKey = 'ariaProhibitedChildren_hint_fail';
       }
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary,
-        hint,
-        i18n: {
-          summaryKey,
-          hintKey,
-          params: isRoleless
-            ? { attr: entry.attr, containerRole: role }
-            : { childRole: entry.role, containerRole: role, allowedRoles: requiredOwned.join(', ') }
-        },
-        data: {
-          details: {
-            reasonCode: isRoleless ? 'ARIA_PROHIBITED_CHILD_ROLELESS' : 'ARIA_PROHIBITED_CHILD',
-            childRole: entry.role,
-            attr: entry.attr,
-            containerRole: role,
-            containerSelector,
-            allowedOwnedRoles: requiredOwned
+      occurrences.push(
+        helpers.reportOccurrence(entry.el, {
+          summary,
+          hint,
+          i18n: {
+            summaryKey,
+            hintKey,
+            params: isRoleless
+              ? { attr: entry.attr, containerRole: role }
+              : {
+                  childRole: entry.role,
+                  containerRole: role,
+                  allowedRoles: allowedRoles.join(', ')
+                }
+          },
+          data: {
+            details: {
+              reasonCode: isRoleless ? 'ARIA_PROHIBITED_CHILD_ROLELESS' : 'ARIA_PROHIBITED_CHILD',
+              childRole: entry.role,
+              attr: entry.attr,
+              containerRole: role,
+              containerSelector,
+              allowedOwnedRoles: allowedRoles
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -12,24 +12,36 @@
  *   Applies to elements with an explicit, valid, non-abstract role that is
  *   also one of the small set of roles with a documented, context-
  *   independent required state/property (checkbox, combobox, heading,
- *   menuitemcheckbox, menuitemradio, meter, radio, scrollbar, slider,
- *   switch).
+ *   menuitemcheckbox, menuitemradio, meter, radio, scrollbar, separator,
+ *   slider, switch) -- except when that explicit role is identical to the
+ *   element's own native/implicit role (ACT 4e8ab6: e.g.
+ *   <input type="checkbox" role="checkbox">, which is exempt because the
+ *   native control's own state exposure already covers it; no aria-checked
+ *   is required. helpers.aria.getNativeRoleForElement resolves this).
  * @expectation
  *   Every required aria-* attribute for that role is present (and non-empty).
  * @implementation-notes
- * - Deliberately scoped to REQUIRED_PROPS_BY_ROLE in src/core/aria-helpers.js,
+ * - 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.
- * - `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.
+ *   context-independent, see that file's header for the rationale.
+ * - `meter`'s `aria-valuenow` is required. NOT required
+ *   unconditionally: `progressbar`'s `aria-valuenow` (a legitimately
+ *   indeterminate progressbar omits it) and `combobox`'s `aria-controls`
+ *   (only required once the popup is actually displayed). ACT 4e8ab6's own
+ *   test corpus confirms the conditional trigger: a role="combobox" with
+ *   aria-expanded="true" and no (or empty) aria-controls fails, so that
+ *   specific combination is checked directly below rather than through
+ *   REQUIRED_PROPS_BY_ROLE's unconditional table. `separator`'s
+ *   `aria-valuenow` is conditional in the same way: a plain separator is a
+ *   structural divider that needs no value, but a focusable one is a
+ *   splitter the user can move, and WAI-ARIA requires the value then. ACT
+ *   4e8ab6 fails exactly that shape (`<div role="separator" tabindex="0">`
+ *   with no aria-valuenow), so focusability is read from
+ *   helpers.getFocusableInfo at the same point.
  * - Gated on isAccTreeEligible for the element itself: unlike a syntax-
  *   level check (attribute name/value validity), "does this element
  *   currently carry its required state attribute" is not fixed once
- *   written — checkbox/switch/radio's aria-checked and slider/scrollbar's
+ *   written, checkbox/switch/radio's aria-checked and slider/scrollbar's
  *   aria-valuenow are exactly the kind of live-widget-state attribute
  *   component libraries set during hydration/mount, at the same moment
  *   the element becomes exposed. Same false-positive shape as
@@ -95,6 +107,21 @@ function runInPage(ctx) {
     }
   }
 
+  // Focusability decides whether a separator is a widget; the same helper
+  // aria-hidden-focus and nested-interactive-controls-absent rely on, so
+  // :disabled, inert and invalid tabindex values are already accounted for.
+  function isFocusable(el) {
+    const fn =
+      helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+    if (!fn) return false;
+    try {
+      const info = fn(el, ctx);
+      return !!(info && info.focusable);
+    } catch {
+      return false;
+    }
+  }
+
   function isMarkedBusy(el) {
     const v = el.getAttribute('aria-busy');
     return v != null && String(v).trim().toLowerCase() === 'true';
@@ -113,7 +140,28 @@ function runInPage(ctx) {
     const role = ariaHelpers.getExplicitRole(el);
     if (!role || !ariaHelpers.isValidConcreteRole(role)) continue; // aria-roles-valid's concern
 
-    const required = ariaHelpers.getRequiredAttrsForRole(role);
+    // ACT 4e8ab6: an explicit role identical to the element's own native
+    // role is exempt -- the native control's own state exposure already
+    // covers it (e.g. <input type="checkbox" role="checkbox"> needs no
+    // aria-checked; the browser exposes .checked natively).
+    if (ariaHelpers.getNativeRoleForElement && ariaHelpers.getNativeRoleForElement(el) === role) {
+      continue;
+    }
+
+    const required = ariaHelpers.getRequiredAttrsForRole(role).slice();
+
+    // combobox's aria-controls is required only once the popup is actually
+    // displayed (aria-expanded="true") -- see this file's header comment.
+    if (role === 'combobox' && String(el.getAttribute('aria-expanded') || '').trim() === 'true') {
+      required.push('aria-controls');
+    }
+
+    // A separator only carries a value when it is focusable, i.e. a
+    // splitter the user can move -- see this file's header comment.
+    if (role === 'separator' && isFocusable(el)) {
+      required.push('aria-valuenow');
+    }
+
     if (!required.length) continue;
 
     if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
@@ -129,24 +177,21 @@ function runInPage(ctx) {
 
     if (!missing.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const attr of missing) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This attribute is required for this element’s role, but is missing.',
-        hint: 'Add this attribute with a valid value for this role.',
-        i18n: {
-          summaryKey: 'ariaRequiredAttr_summary_fail',
-          hintKey: 'ariaRequiredAttr_hint_fail',
-          params: { attr, role }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_REQUIRED_MISSING', attr, role }
-        }
-      });
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This attribute is required for this element’s role, but is missing.',
+          hint: 'Add this attribute with a valid value for this role.',
+          i18n: {
+            summaryKey: 'ariaRequiredAttr_summary_fail',
+            hintKey: 'ariaRequiredAttr_hint_fail',
+            params: { attr, role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_REQUIRED_MISSING', attr, role }
+          }
+        })
+      );
     }
   }
 

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

@@ -17,7 +17,7 @@
  *   At least one descendant, or one aria-owns-referenced element, has one
  *   of the acceptable owned roles for that container role.
  * @implementation-notes
- * - Deliberately scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
+ * - Scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
  *   (see that file's header for the conservative-scope rationale).
  * - Owned-role matching uses ariaHelpers.getContainmentRole, which combines
  *   explicit role="" attributes with a small, curated native-HTML-tag
@@ -28,12 +28,20 @@
  * - Only one qualifying descendant/owned element is required (per
  *   WAI-ARIA "required owned elements": any one acceptable role satisfies
  *   the requirement); the full subtree is scanned without excluding nested
- *   containers with their own differing role, favoring simplicity — this
+ *   containers with their own differing role, favoring simplicity, this
  *   can only under-report (recall), never over-report (fail integrity).
+ * - "At least one required child exists" is the whole of this rule's
+ *   decision. Whether every owned child is ALLOWED is
+ *   aria-prohibited-children's, and that rule does walk the owned graph
+ *   exclusively, with group/rowgroup transparency. ACT bc4a75 asks both
+ *   questions at once, which is why the mapping lists the two rules as a
+ *   family: read on its own, this rule looks like it under-reports a
+ *   container mixing valid and invalid children, and the sibling is what
+ *   catches it.
  * - Gated on isAccTreeEligible for the container itself: unlike this
  *   file's sibling attribute/role-validity checks (e.g. aria-roles-valid),
  *   "does this container currently have a required child" is not a fact
- *   that stays fixed once written — it is routinely filled in by the same
+ *   that stays fixed once written, it is routinely filled in by the same
  *   script/interaction that reveals the container (a closed flyout menu
  *   or <dialog> populated on open). Flagging it while the container isn't
  *   currently exposed to the accessibility tree is a false positive; such
@@ -44,16 +52,16 @@
  *   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).
+ *   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>
  *   anywhere in its subtree does it fall back to a composed-tree walk that
- *   expands <slot> elements via assignedElements({flatten:true}) — plain
+ *   expands <slot> elements via assignedElements({flatten:true}). Plain
  *   querySelectorAll only sees a <slot>'s unrendered fallback content, never
- *   what's actually distributed into it. Deliberately scoped to slot
+ *   what's actually distributed into it. Scoped to slot
  *   expansion only, not a general "also descend into any nested custom
- *   element's own shadow root" walk — no known case needs that yet.
+ *   element's own shadow root" walk, no known case needs that yet.
  */
 
 const id = 'aria-required-children';
@@ -114,7 +122,7 @@ function runInPage(ctx) {
   // Candidate selector for descendant scanning: explicit role attributes,
   // plus every native tag ariaHelpers.getContainmentRole() recognizes
   // (kept in sync with aria-helpers.js NATIVE_CONTAINMENT_ROLE_BY_ELEMENT).
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const CANDIDATE_SELECTOR =
     '[role], li, option, tr, td, th, thead, tbody, tfoot, ul, ol, table, select, input[type="radio"]';
@@ -130,11 +138,11 @@ function runInPage(ctx) {
   // light-DOM subtree, so a container whose real owned children are
   // distributed via <slot> (e.g. a shadow-DOM role="list" wrapping
   // <slot></slot>, with the actual role="listitem" elements living in the
-  // light DOM and projected in) would never find them there — same class
+  // 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.
   //
-  // Deliberately scoped to slot expansion only — does NOT separately
+  // 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
@@ -192,9 +200,8 @@ function runInPage(ctx) {
     let found = false;
 
     // Fast path first: native querySelectorAll over the curated candidate
-    // selector, exactly as before this fix — covers the overwhelming
-    // majority of containers (no shadow DOM involved at all) with zero
-    // added cost.
+    // selector. Covers the overwhelming majority of containers (no shadow
+    // DOM involved at all) with zero added cost.
     let descendants;
     try {
       descendants = el.querySelectorAll(CANDIDATE_SELECTOR);
@@ -210,7 +217,7 @@ function runInPage(ctx) {
     }
 
     // Slow path only when the fast path found nothing AND there's an actual
-    // <slot> somewhere in the subtree to expand — bounds the extra cost to
+    // <slot> somewhere in the subtree to expand, bounds the extra cost to
     // exactly the containers that could possibly need it.
     if (!found) {
       let hasSlot;
@@ -253,27 +260,24 @@ function runInPage(ctx) {
 
     if (found) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This container role has no owned child with a required role.',
-      hint: 'Add a descendant (or aria-owns-referenced element) with one of the required owned roles.',
-      i18n: {
-        summaryKey: 'ariaRequiredChildren_summary_fail',
-        hintKey: 'ariaRequiredChildren_hint_fail',
-        params: { role, requiredRoles: requiredOwned.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_REQUIRED_CHILD_MISSING',
-          role,
-          requiredOwnedRoles: requiredOwned
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This container role has no owned child with a required role.',
+        hint: 'Add a descendant (or aria-owns-referenced element) with one of the required owned roles.',
+        i18n: {
+          summaryKey: 'ariaRequiredChildren_summary_fail',
+          hintKey: 'ariaRequiredChildren_hint_fail',
+          params: { role, requiredRoles: requiredOwned.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_REQUIRED_CHILD_MISSING',
+            role,
+            requiredOwnedRoles: requiredOwned
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {