@surea11y/core 1.4.0 → 1.5.0

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

@@ -82,24 +82,22 @@ function runInPage(ctx) {
 
     if (info.allowed) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This role is not permitted on this element.',
-      hint: 'Use a role permitted for this element, or change the host element.',
-      i18n: {
-        summaryKey: 'ariaAllowedRole_summary_fail',
-        hintKey: 'ariaAllowedRole_hint_fail',
-        params: { role, element: tag }
-      },
-      data: {
-        details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This role is not permitted on this element.',
+        hint: 'Use a role permitted for this element, or change the host element.',
+        i18n: {
+          summaryKey: 'ariaAllowedRole_summary_fail',
+          hintKey: 'ariaAllowedRole_hint_fail',
+          params: { role, element: tag }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -119,29 +119,27 @@ function runInPage(ctx) {
 
     if (!missing.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
     for (const m of missing) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-        hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
-        i18n: {
-          summaryKey: 'ariaBrailleEquivalent_summary_fail',
-          hintKey: 'ariaBrailleEquivalent_hint_fail',
-          params: { element: tag, attr: m.attr, requires: m.requires }
-        },
-        data: {
-          details: {
-            reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
-            attr: m.attr,
-            requires: m.requires
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
+          hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
+          i18n: {
+            summaryKey: 'ariaBrailleEquivalent_summary_fail',
+            hintKey: 'ariaBrailleEquivalent_hint_fail',
+            params: { element: tag, attr: m.attr, requires: m.requires }
+          },
+          data: {
+            details: {
+              reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
+              attr: m.attr,
+              requires: m.requires
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -86,28 +86,26 @@ function runInPage(ctx) {
     const invalidValue = trim(el.getAttribute('aria-invalid')).toLowerCase();
     if (TRUTHY_INVALID_VALUES.has(invalidValue)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
-      hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'ariaConditionalAttr_summary_fail',
-        hintKey: 'ariaConditionalAttr_hint_fail',
-        params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
-          ariaInvalid: invalidValue
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
+        hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'ariaConditionalAttr_summary_fail',
+          hintKey: 'ariaConditionalAttr_hint_fail',
+          params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
+            ariaInvalid: invalidValue
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -5,30 +5,36 @@
 /**
  * @check aria-deprecated-role
  * @atomic true
- * @summary An explicit role attribute must not use a deprecated or author-prohibited ARIA role
+ * @summary An explicit role attribute should not use a deprecated or author-discouraged ARIA role
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
  *   Applies to any element whose role attribute's first (used) token is a
- *   valid, non-abstract ARIA role that authors must never explicitly
+ *   valid, non-abstract ARIA role that authors should not explicitly
  *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
- *   superseded by role="list") or because it's reserved for user-agent-
- *   internal use only, not a spec deprecation but the same "valid token,
- *   prohibited for authors" shape (role="generic" — per WAI-ARIA 1.2 and
- *   MDN's "It should not be used by web authors" guidance).
+ *   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).
  * @expectation
- *   The role in use is neither deprecated nor author-prohibited. This is a
- *   distinct, atomic decision from aria-roles-valid (existence/
- *   abstractness): a role can be perfectly valid and non-abstract while
- *   still being off-limits for explicit author use.
+ *   The role in use is neither deprecated nor reserved. Graded by the
+ *   strength of the rule ARIA states:
+ *   - CANTTELL at SHOULD NOT, which leaves the usage conforming, so the
+ *     author decides whether it matters: a deprecated role ("directory") or
+ *     one reserved for user agents ("generic").
+ *   - FAIL at MUST NOT. No ARIA 1.2 or 1.3 role carries an author MUST NOT
+ *     outside the abstract roles, so this outcome is reserved for a later
+ *     revision promoting a role to that strength.
+ *   Distinct, atomic decision from aria-roles-valid (existence/
+ *   abstractness): a role can be valid and non-abstract while still being
+ *   discouraged in explicit author use.
  */
 
 const id = 'aria-deprecated-role';
 
 const meta = {
-  title: 'role attribute must not use a deprecated or author-prohibited ARIA role',
+  title: 'role attribute should not use a deprecated or author-discouraged ARIA role',
   description:
-    'Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use only (e.g. role="generic").',
+    'Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use (e.g. role="generic").',
   i18n: {
     titleKey: 'ariaDeprecatedRole_title',
     descriptionKey: 'ariaDeprecatedRole_description'
@@ -64,12 +70,43 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('[role]')
     : helpers.queryAll('[role]');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
+  // A role on an element hidden from assistive technology has no effect, so
+  // ACT 674b10 does not apply to it.
+  function isHidden(el) {
+    try {
+      if (typeof helpers.isDomVisibleEligible === 'function') {
+        if (!helpers.isDomVisibleEligible(el, ctx)) return true;
+      }
+      // Walk the composed tree, not parentElement: that stops at a shadow
+      // root, so a host carrying aria-hidden or inert would never be seen
+      // from inside its own shadow content.
+      const up =
+        typeof helpers.composedParent === 'function'
+          ? helpers.composedParent
+          : (n) => n.parentElement;
+
+      // A shadow root has no getAttribute, so skip past it rather than
+      // stopping: the host one step further up is the node that matters.
+      for (let n = el; n; n = up(n)) {
+        if (!n.getAttribute) continue;
+        if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+        if (n.hasAttribute && n.hasAttribute('inert')) return true;
+      }
+    } catch {
+      return false;
+    }
+    return false;
+  }
+
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
+    if (isHidden(el)) continue;
+
     const role = ariaHelpers.getExplicitRole(el);
     if (!role) continue;
 
@@ -79,42 +116,86 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    if (!ariaHelpers.isDeprecatedRole(role)) continue;
+    const deprecated = ariaHelpers.isDeprecatedRole(role);
+    const discouraged =
+      typeof ariaHelpers.isAuthorDiscouragedRole === 'function' &&
+      ariaHelpers.isAuthorDiscouragedRole(role);
+    const prohibited =
+      typeof ariaHelpers.isAuthorProhibitedRole === 'function' &&
+      ariaHelpers.isAuthorProhibitedRole(role);
+    if (!deprecated && !discouraged && !prohibited) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const guidance = ariaHelpers.getDeprecatedRoleGuidance
       ? ariaHelpers.getDeprecatedRoleGuidance(role)
-      : 'Replace the deprecated role with its recommended replacement.';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This element uses role="${role}", which authors must not explicitly declare.`,
-      hint: guidance,
-      i18n: {
-        summaryKey: 'ariaDeprecatedRole_summary_fail',
-        hintKey: 'ariaDeprecatedRole_hint_fail',
-        params: { role, guidance }
-      },
-      data: {
-        details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
-      }
-    });
+      : {
+          key: 'ariaDeprecatedRole_guidance_default',
+          text: 'Replace the deprecated role with its recommended replacement.'
+        };
+
+    if (prohibited) {
+      // Author MUST NOT: the usage is non-conforming, not merely discouraged.
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which authors must not explicitly declare.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'fail',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_fail',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance: guidance.text }
+          }
+        })
+      );
+    } else if (discouraged) {
+      // Reserved for user-agent-internal use, at SHOULD NOT strength.
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
+          }
+        })
+      );
+    } else {
+      // Deprecated but still valid: surfaced for the author to decide.
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
+          }
+        })
+      );
+    }
   }
 
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -86,15 +86,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html,
+    helpers.reportOccurrence(body, {
       summary:
         'The document body has aria-hidden="true", which hides the entire page from assistive technologies.',
       hint: 'Remove aria-hidden from <body>. Hide specific elements instead, if that was the intent.',
@@ -106,7 +99,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'ARIA_HIDDEN_BODY' }
       }
-    }
+    })
   ];
 
   return {

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

@@ -146,6 +146,54 @@ function runInPage(ctx) {
     return false;
   }
 
+  // An open modal is expected to trap focus, so a focusable background behind
+  // it may be unreachable; that can't be proven statically, so the finding is
+  // downgraded to cantTell instead of fail. A modal that is display:none is
+  // not open, so it does not count.
+  function isRenderedForModal(node) {
+    if (!node) return false;
+    if (!isDomVisibleEligible) return true;
+    try {
+      const vis = isDomVisibleEligible(node, ctx, {
+        visibilityMode: 'styleOnly',
+        disableGeometry: true
+      });
+      if (vis && vis.eligible === false) return false;
+    } catch {
+      // treat as rendered
+    }
+    return true;
+  }
+
+  // Native <dialog>, aria-modal="true", or a dialog/alertdialog role, so
+  // libraries that leave aria-modal off (e.g. Angular Material defaults to
+  // aria-modal="false") still count as an open modal.
+  function collectOpenModalCandidates() {
+    const nodes = qAll('dialog[open],[aria-modal="true"],[role="dialog"],[role="alertdialog"]');
+    const out = [];
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      if (!n || !n.getAttribute) continue;
+      if (!isRenderedForModal(n)) continue;
+      out.push(n);
+    }
+    return out;
+  }
+
+  // Only a modal in a separate subtree is the "hidden background behind an
+  // open dialog" case. A modal inside the aria-hidden subtree (or an
+  // aria-hidden root inside the modal) is a genuine defect, so keep it a fail.
+  function hasSeparateOpenModal(rootEl, candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+      const m = candidates[i];
+      if (!m || m === rootEl) continue;
+      if (isWithinComposedSubtree(m, rootEl)) continue;
+      if (isWithinComposedSubtree(rootEl, m)) continue;
+      return true;
+    }
+    return false;
+  }
+
   function getDeepActiveElement() {
     let cur = document && document.activeElement ? document.activeElement : null;
     let guard = 0;
@@ -713,6 +761,8 @@ function runInPage(ctx) {
     entry.rootIsFocusable = isActuallyFocusable(el);
   }
 
+  const modalCandidates = collectOpenModalCandidates();
+
   // 3) Report one occurrence per aria-hidden root that contains focusable content.
   const failOccurrences = [];
   const uncertainOccurrences = [];
@@ -765,24 +815,56 @@ function runInPage(ctx) {
         : `aria-hidden ${tagName} is focusable (${totalFocusable} focusable element(s)).`
       : `aria-hidden ${tagName} contains ${totalFocusable} focusable element(s).`;
 
-    const runtimeProbe = probeImmediateFocusRedirect(entry);
-    const downgradedToCantTell = !!(runtimeProbe && runtimeProbe.redirected);
-
-    const cantTellSummary = `aria-hidden ${tagName} received focus but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`;
+    // A modal takes precedence over the redirect probe; skip the probe when a
+    // modal already explains the background.
+    const modalOpenOutside = modalCandidates.length
+      ? hasSeparateOpenModal(el, modalCandidates)
+      : false;
+
+    const runtimeProbe = modalOpenOutside ? null : probeImmediateFocusRedirect(entry);
+    const downgradedByRedirect = !!(runtimeProbe && runtimeProbe.redirected);
+    const downgradedByModal = modalOpenOutside;
+    const downgradedToCantTell = downgradedByModal || downgradedByRedirect;
+
+    const cantTellRedirectSummary = `aria-hidden ${tagName} received focus but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`;
+    const cantTellModalSummary = `aria-hidden ${tagName} contains ${totalFocusable} focusable element(s) while a modal dialog is open. If the modal keeps keyboard focus trapped they may be unreachable; verify focus cannot land on them.`;
+
+    let occSummary;
+    let occHint;
+    let occSummaryKey;
+    let occHintKey;
+    let occReasonCode;
+
+    if (downgradedByModal) {
+      occSummary = cantTellModalSummary;
+      occHint =
+        'A modal dialog appears to be open. Prefer making the background inert (or a native <dialog> opened with showModal()) so it leaves the tab order, then verify keyboard focus stays within the dialog.';
+      occSummaryKey = 'ariaHidden_focus_summary_cantTell_modal';
+      occHintKey = 'ariaHidden_focus_hint_cantTell_modal';
+      occReasonCode = 'ariaHiddenFocusable_modalOpen_needsReview';
+    } else if (downgradedByRedirect) {
+      occSummary = cantTellRedirectSummary;
+      occHint =
+        'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.';
+      occSummaryKey = 'ariaHidden_focus_summary_cantTell_redirect';
+      occHintKey = 'ariaHidden_focus_hint_cantTell_redirect';
+      occReasonCode = 'ariaHiddenFocusable_runtimeRedirect_needsReview';
+    } else {
+      occSummary = summaryText;
+      occHint =
+        'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.';
+      occSummaryKey = summaryKey;
+      occHintKey = 'ariaHidden_focus_hint_fail';
+      occReasonCode = reasonCode;
+    }
 
     const baseOccurrence = {
-      summary: downgradedToCantTell ? cantTellSummary : summaryText,
-      hint: downgradedToCantTell
-        ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.'
-        : 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      summary: occSummary,
+      hint: occHint,
       occurrenceOutcome: downgradedToCantTell ? 'cantTell' : 'fail',
       i18n: {
-        summaryKey: downgradedToCantTell
-          ? 'ariaHidden_focus_summary_cantTell_redirect'
-          : summaryKey,
-        hintKey: downgradedToCantTell
-          ? 'ariaHidden_focus_hint_cantTell_redirect'
-          : 'ariaHidden_focus_hint_fail',
+        summaryKey: occSummaryKey,
+        hintKey: occHintKey,
         params: {
           element: tagName,
           focusableCount: String(totalFocusable),
@@ -795,15 +877,14 @@ function runInPage(ctx) {
       },
       data: {
         details: {
-          reasonCode: downgradedToCantTell
-            ? 'ariaHiddenFocusable_runtimeRedirect_needsReview'
-            : reasonCode,
+          reasonCode: occReasonCode,
           metrics: {
             focusableTotal: totalFocusable,
             focusableDescendants: descendantFocusable,
             rootIsFocusable: selfFocusable,
             offendersCaptured: entry.offenders.length,
-            visibilityHints: hintsArr.slice(0)
+            visibilityHints: hintsArr.slice(0),
+            modalOpen: !!downgradedByModal
           },
           runtimeProbe: runtimeProbe || null,
           offenders: entry.offenders.slice(0)

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

@@ -167,25 +167,22 @@ function runInPage(ctx) {
 
     if (!present.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const attr of present) {
-      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: {
-          summaryKey: 'ariaProhibitedAttr_summary_fail',
-          hintKey: 'ariaProhibitedAttr_hint_fail',
-          params: { attr, role }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_PROHIBITED', attr, role }
-        }
-      });
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          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: {
+            summaryKey: 'ariaProhibitedAttr_summary_fail',
+            hintKey: 'ariaProhibitedAttr_hint_fail',
+            params: { attr, role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_PROHIBITED', attr, role }
+          }
+        })
+      );
     }
   }
 
@@ -361,47 +358,49 @@ function runInPage(ctx) {
       String(nameInfo.value || '').trim() !== ''
     );
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const attr of present) {
       if (hasContentFallback) {
-        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: {
-            summaryKey: 'ariaProhibitedAttr_summary_cantTell_roleless',
-            hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
-            params: { attr, element: tag }
-          },
-          data: {
-            details: {
-              reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',
-              attr,
-              role: null,
-              element: tag
+        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.`,
+            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',
+              hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
+              params: { attr, element: tag }
+            },
+            data: {
+              details: {
+                reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',
+                attr,
+                role: null,
+                element: tag
+              }
             }
-          }
-        });
+          })
+        );
       } else {
-        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: {
-            summaryKey: 'ariaProhibitedAttr_summary_fail_roleless',
-            hintKey: 'ariaProhibitedAttr_hint_fail_roleless',
-            params: { attr, element: tag }
-          },
-          data: {
-            details: { reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS', attr, role: null, element: tag }
-          }
-        });
+        failOccurrences.push(
+          helpers.reportOccurrence(el, {
+            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: {
+              summaryKey: 'ariaProhibitedAttr_summary_fail_roleless',
+              hintKey: 'ariaProhibitedAttr_hint_fail_roleless',
+              params: { attr, element: tag }
+            },
+            data: {
+              details: {
+                reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS',
+                attr,
+                role: null,
+                element: tag
+              }
+            }
+          })
+        );
       }
     }
   }