@surea11y/core 1.5.0 → 1.7.0

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

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

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

@@ -6,8 +6,7 @@
  * @check aria-allowed-role
  * @atomic true
  * @summary Explicit role must be permitted by the ARIA-in-HTML spec for its host element
- * @standard WCAG 2.2
- * @sc 4.1.2
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with an explicit, valid, non-abstract role, where
  *   the host element/attribute combination has an asserted permitted-roles
@@ -16,10 +15,21 @@
  * @expectation
  *   The explicit role is one of the roles the ARIA-in-HTML specification
  *   permits for that host element.
+ *   Reported at CANTTELL rather than FAIL: ARIA-in-HTML's permitted-roles
+ *   table is an author conformance requirement with no ACT rule and no WCAG
+ *   mapping in any source. The role the author asked for is still the role
+ *   assistive technology exposes, so whether the combination harms anyone
+ *   depends on the widget, not on the table.
  * @implementation-notes
- * - Deliberately scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
+ * - Not WCAG-normative. ARIA-in-HTML's permitted-roles table is an author
+ *   conformance requirement of that specification; no ACT rule covers it and
+ *   no source maps it to a Success Criterion, so the rule reports the
+ *   violation without claiming a criterion is failed. Deterministic all the
+ *   same, so it stays `type: 'automatic'` and keeps deciding rather than
+ *   deferring to a reviewer -- see docs/RULE_TAXONOMY.md 1.1.
+ * - Scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
  *   elements without an asserted constraint are treated as "no constraint"
- *   (not flagged) rather than guessed at — see that table's header comment.
+ *   (not flagged) rather than guessed at, see that table's header comment.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
@@ -36,22 +46,14 @@ const meta = {
     descriptionKey: 'ariaAllowedRole_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
-  wcagSc: ['4.1.2'],
-  normativeMappings: [
-    {
-      standard: 'WCAG',
-      version: '2.2',
-      requirement: '4.1.2',
-      title: 'Name, Role, Value',
-      conformanceLevel: 'A'
-    }
-  ],
+  tags: ['best-practice', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: [],
+  normativeMappings: [],
   defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
-  coverage: { facetsBySc: { '4.1.2': ['aria-role-allowed-for-element'] } }
+  coverage: {}
 };
 
 function runInPage(ctx) {
@@ -93,6 +95,16 @@ function runInPage(ctx) {
           hintKey: 'ariaAllowedRole_hint_fail',
           params: { role, element: tag }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the role misstates this element to assistive technology in practice.',
+          evidence: {
+            role,
+            element: tag,
+            source: 'ARIA in HTML permitted-roles table',
+            wcagSc: []
+          }
+        },
         data: {
           details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
         }
@@ -103,15 +115,12 @@ function runInPage(ctx) {
   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(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -23,11 +23,16 @@
  *   Using either braille-specific attribute as the ONLY naming mechanism
  *   leaves non-braille assistive technology (most screen readers, voice
  *   control, etc.) with no accessible name/role description at all.
+ *   Reported at CANTTELL rather than FAIL: aria-brailleroledescription
+ *   without aria-roledescription reaches no user at all, and a missing
+ *   accessible name is the naming rules' decision for the roles that require
+ *   one. The braille attribute being unpaired is worth surfacing, but it is
+ *   not itself a criterion failing.
  * @implementation-notes
  * - `aria-braillelabel`/`aria-brailleroledescription` do not participate
  *   in the standard accessible-name computation, so
  *   `helpers.getAccessibleNameInfo` already reflects only the "regular"
- *   (non-braille) name — no special-casing needed there.
+ *   (non-braille) name, no special-casing needed there.
  */
 
 const id = 'aria-braille-equivalent';
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -67,7 +72,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -125,12 +130,18 @@ function runInPage(ctx) {
       occurrences.push(
         helpers.reportOccurrence(el, {
           summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-          hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
+          hint: `${m.attr} is a Braille-specific supplement, not a replacement, so also provide ${m.requires}.`,
           i18n: {
             summaryKey: 'ariaBrailleEquivalent_summary_fail',
             hintKey: 'ariaBrailleEquivalent_hint_fail',
             params: { element: tag, attr: m.attr, requires: m.requires }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether any user reaches this attribute, given no braille equivalent is exposed.',
+            evidence: { element: tag, attribute: m.attr, requires: m.requires }
+          },
           data: {
             details: {
               reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
@@ -146,15 +157,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -16,17 +16,22 @@
  *   other than `"false"` (i.e. `"true"`, `"grammar"`, or `"spelling"`).
  *   An element with `aria-errormessage` but `aria-invalid` absent or
  *   `"false"` silently drops the error message from the accessibility
- *   tree — authors almost always intend it to be exposed.
+ *   tree, authors almost always intend it to be exposed.
+ *   Reported at CANTTELL rather than FAIL: aria-errormessage is only
+ *   exposed once aria-invalid is set, so the reference is currently inert.
+ *   Whether that costs the user anything depends on whether the message is
+ *   conveyed some other way (visible text next to the field, aria-describedby),
+ *   which static markup does not settle.
  * @implementation-notes
- * - This is deliberately narrow: the broader space is a table of many
+ * - This is narrow: the broader space is a table of many
  *   attribute/condition pairs. This rule implements only the one pairing
  *   (`aria-errormessage` / `aria-invalid`) that is unambiguous and
- *   explicitly stated in the ARIA spec, to keep `fail` high-confidence —
+ *   explicitly stated in the ARIA spec, to keep `fail` high-confidence,
  *   matches this repo's established pattern (see `aria-required-attr`/
  *   `aria-prohibited-attr` for the same "narrow but zero false positives"
  *   trade-off).
  * - Does not check whether the `aria-errormessage` ID reference itself
- *   resolves to an existing element — that is `aria-valid-attr-value`'s
+ *   resolves to an existing element. That's `aria-valid-attr-value`'s
  *   concern, not this rule's.
  */
 
@@ -35,7 +40,7 @@ const id = 'aria-conditional-attr';
 const meta = {
   title: 'aria-errormessage requires aria-invalid to be set to a non-false value',
   description:
-    'Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling" — otherwise the error message is dropped from the accessibility tree.',
+    'Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling"; otherwise the error message is dropped from the accessibility tree.',
   i18n: {
     titleKey: 'ariaConditionalAttr_title',
     descriptionKey: 'ariaConditionalAttr_description'
@@ -52,7 +57,7 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
@@ -98,6 +103,11 @@ function runInPage(ctx) {
           hintKey: 'ariaConditionalAttr_hint_fail',
           params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
         },
+        uncertainty: {
+          code: 'spec-only',
+          needed: 'Whether the field is ever in an invalid state that should expose this message.',
+          evidence: { element: tag, ariaInvalid: invalidValue || null }
+        },
         data: {
           details: {
             reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
@@ -111,15 +121,12 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    occurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

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

@@ -11,7 +11,7 @@
  * @applicability
  *   Applies to any element whose role attribute's first (used) token is a
  *   valid, non-abstract ARIA role that authors should not explicitly
- *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
+ *   declare, either because WAI-ARIA has deprecated it (e.g. "directory",
  *   superseded by role="list") or because it is reserved for user-agent-
  *   internal use (role="generic", which ARIA 1.2 §5.4 says authors SHOULD
  *   NOT use in content).
@@ -161,6 +161,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether this user-agent-reserved role misleads the assistive technology in use.',
+            evidence: { role, ariaStatus: 'discouraged-for-authors' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
           }
@@ -178,6 +184,12 @@ function runInPage(ctx) {
             hintKey: guidance.key,
             params: { role }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed:
+              'Whether the deprecated role is still honoured, and what it should be replaced with.',
+            evidence: { role, ariaStatus: 'deprecated' }
+          },
           data: {
             details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
           }

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

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

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

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

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

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