@surea11y/core 1.2.0 → 1.4.0

package/src/checks/manual/page-title-patterns-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'page-title-patterns';
@@ -15,7 +17,13 @@ const meta = {
   tags: ['wcag2a', 'wcag242', 'titles', 'atomic', 'navigation', 'manual'],
   wcagSc: ['2.4.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '2.4.2', title: 'Page Titled', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.4.2',
+      title: 'Page Titled',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'minor',
   category: 'operable',
@@ -34,11 +42,13 @@ function applicability(ctx) {
 
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
-  const probes = ctx && ctx.inputs && ctx.inputs.probes && typeof ctx.inputs.probes === 'object'
+  const probes =
+    ctx && ctx.inputs && ctx.inputs.probes && typeof ctx.inputs.probes === 'object'
       ? ctx.inputs.probes
       : null;
 
-  const pageTitlesProbe = probes && probes['crawl.pageTitles'] && typeof probes['crawl.pageTitles'] === 'object'
+  const pageTitlesProbe =
+    probes && probes['crawl.pageTitles'] && typeof probes['crawl.pageTitles'] === 'object'
       ? probes['crawl.pageTitles']
       : null;
 
@@ -53,16 +63,16 @@ function runInPage(ctx) {
   // Cross-page pattern analysis (preferred) if crawl.pageTitles probe is provided
   // =========================
   if (pageTitlesProbe && Array.isArray(pageTitlesProbe.pages)) {
-    const pages = pageTitlesProbe.pages.filter(p => p && typeof p === 'object');
+    const pages = pageTitlesProbe.pages.filter((p) => p && typeof p === 'object');
 
     // Require enough data to avoid noisy conclusions
     const MIN_PAGES = 10;
     const analyzable = pages
-        .map(p => ({
-          url: p.url ? String(p.url) : null,
-          title: typeof p.title === 'string' ? p.title.replace(/\s+/g, ' ').trim() : ''
-        }))
-        .filter(p => p.url && p.title);
+      .map((p) => ({
+        url: p.url ? String(p.url) : null,
+        title: typeof p.title === 'string' ? p.title.replace(/\s+/g, ' ').trim() : ''
+      }))
+      .filter((p) => p.url && p.title);
 
     if (analyzable.length >= MIN_PAGES) {
       // Build normalized title groups (case-insensitive)
@@ -74,11 +84,11 @@ function runInPage(ctx) {
       }
 
       // Duplicate titles across distinct URLs is a strong "review" signal (not a guaranteed failure)
-      const dupGroups = Array.from(groups.values()).filter(g => g.urls.length >= 2);
+      const dupGroups = Array.from(groups.values()).filter((g) => g.urls.length >= 2);
 
       // Boilerplate-ish: detect a long common suffix/prefix across most titles.
       // Keep conservative: only flag if the common part is long and shared by many.
-      const titles = analyzable.map(p => p.title);
+      const titles = analyzable.map((p) => p.title);
       function commonPrefix(a, b) {
         const n = Math.min(a.length, b.length);
         let i = 0;
@@ -103,35 +113,41 @@ function runInPage(ctx) {
       const suffixLen = sharedSuffix.trim().length;
 
       const hasStrongTemplateSignal =
-          (prefixLen >= 12 || suffixLen >= 12) &&
-          (prefixLen >= 12 ? sharedPrefix.trim().length : 0) + (suffixLen >= 12 ? sharedSuffix.trim().length : 0) >= 12;
+        (prefixLen >= 12 || suffixLen >= 12) &&
+        (prefixLen >= 12 ? sharedPrefix.trim().length : 0) +
+          (suffixLen >= 12 ? sharedSuffix.trim().length : 0) >=
+          12;
 
       // If any cross-page signal exists, emit cantTell occurrence(s)
       if (dupGroups.length || hasStrongTemplateSignal) {
         const reasonCode = dupGroups.length
-            ? 'duplicateTitlesAcrossPages'
-            : 'templatedTitlesAcrossPages';
+          ? 'duplicateTitlesAcrossPages'
+          : 'templatedTitlesAcrossPages';
 
         // Deterministic example title for i18n params (lexicographic, case-insensitive)
         const exampleTitle = dupGroups.length
-            ? dupGroups
-            .map(g => String(g.title || '').replace(/\s+/g, ' ').trim())
-            .filter(Boolean)
-            .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }))[0] || ''
-            : '';
+          ? dupGroups
+              .map((g) =>
+                String(g.title || '')
+                  .replace(/\s+/g, ' ')
+                  .trim()
+              )
+              .filter(Boolean)
+              .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }))[0] || ''
+          : '';
 
         const summaryKey = dupGroups.length
-            ? 'pageTitlePatterns_summary_cantTell_duplicateAcrossPages'
-            : 'pageTitlePatterns_summary_cantTell_templatedAcrossPages';
+          ? 'pageTitlePatterns_summary_cantTell_duplicateAcrossPages'
+          : 'pageTitlePatterns_summary_cantTell_templatedAcrossPages';
 
         const i18nParams = dupGroups.length
-            ? {
+          ? {
               reasonCode,
               pagesAnalyzed: analyzable.length,
               duplicateGroups: dupGroups.length,
               exampleTitle
             }
-            : {
+          : {
               reasonCode,
               pagesAnalyzed: analyzable.length
             };
@@ -139,7 +155,8 @@ function runInPage(ctx) {
         const occBase = {
           selector: 'head > title',
           html: '',
-          summary: 'The set of page titles may not be descriptive enough to distinguish pages by topic or purpose.',
+          summary:
+            'The set of page titles may not be descriptive enough to distinguish pages by topic or purpose.',
           hint: 'Ensure each page title is sufficiently descriptive and helps users distinguish pages (avoid identical or overly templated titles across many pages).',
           i18n: {
             summaryKey,
@@ -152,12 +169,14 @@ function runInPage(ctx) {
               metrics: {
                 pagesAnalyzed: analyzable.length,
                 duplicateGroups: dupGroups.length,
-                largestDuplicateGroupSize: dupGroups.length ? Math.max(...dupGroups.map(g => g.urls.length)) : 0,
+                largestDuplicateGroupSize: dupGroups.length
+                  ? Math.max(...dupGroups.map((g) => g.urls.length))
+                  : 0,
                 sharedPrefix: prefixLen >= 12 ? sharedPrefix.trim() : '',
                 sharedSuffix: suffixLen >= 12 ? sharedSuffix.trim() : ''
               },
               refs: {
-                exampleDuplicateTitles: dupGroups.slice(0, 3).map(g => ({
+                exampleDuplicateTitles: dupGroups.slice(0, 3).map((g) => ({
                   title: g.title,
                   urls: g.urls.slice(0, 5)
                 }))
@@ -173,12 +192,20 @@ function runInPage(ctx) {
           // No node available: keep deterministic fallback snippet (no helper calls).
           occurrences.push({
             ...occBase,
-            html: titleEl && titleEl.outerHTML ? String(titleEl.outerHTML).slice(0, 2000) : '<title>(unknown)</title>'
+            html:
+              titleEl && titleEl.outerHTML
+                ? String(titleEl.outerHTML).slice(0, 2000)
+                : '<title>(unknown)</title>'
           });
         }
 
         // Cross-page analysis is authoritative when present; do not also run single-page heuristics.
-        return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+        return {
+          ruleId: rule.ruleId,
+          outcome: 'cantTell',
+          severity: rule.defaultSeverity || 'minor',
+          occurrences
+        };
       }
 
       // If we had enough pages and found no review signal, there is nothing
@@ -194,14 +221,7 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const GENERIC_TITLES = new Set([
-    'home',
-    'homepage',
-    'welcome',
-    'untitled',
-    'page',
-    'document'
-  ]);
+  const GENERIC_TITLES = new Set(['home', 'homepage', 'welcome', 'untitled', 'page', 'document']);
 
   // Conservative signals:
   // - very short title (likely non-descriptive)
@@ -210,27 +230,29 @@ function runInPage(ctx) {
   const isGeneric = GENERIC_TITLES.has(titleLc);
 
   // Template-like: "Brand | Home" or "Home - Brand" where the page-specific part is a generic token.
-  const templateLike = /\b(home|homepage|welcome)\b\s*(\||-|—|:)\s*.+/i.test(titleText) ||
-                       /.+\s*(\||-|—|:)\s*\b(home|homepage|welcome)\b/i.test(titleText);
+  const templateLike =
+    /\b(home|homepage|welcome)\b\s*(\||-|—|:)\s*.+/i.test(titleText) ||
+    /.+\s*(\||-|—|:)\s*\b(home|homepage|welcome)\b/i.test(titleText);
 
   if (isGeneric || isVeryShort || templateLike) {
     const reasonCode = isGeneric
       ? 'genericTitle'
-      : (isVeryShort ? 'veryShortTitle' : 'templateLikeTitle');
+      : isVeryShort
+        ? 'veryShortTitle'
+        : 'templateLikeTitle';
 
     const summaryKey =
-        reasonCode === 'genericTitle'
-            ? 'pageTitlePatterns_summary_cantTell_generic'
-            : (reasonCode === 'veryShortTitle'
-                ? 'pageTitlePatterns_summary_cantTell_veryShort'
-                : 'pageTitlePatterns_summary_cantTell_templateLike');
+      reasonCode === 'genericTitle'
+        ? 'pageTitlePatterns_summary_cantTell_generic'
+        : reasonCode === 'veryShortTitle'
+          ? 'pageTitlePatterns_summary_cantTell_veryShort'
+          : 'pageTitlePatterns_summary_cantTell_templateLike';
     const occBase = {
       selector: 'head > title',
       html: '',
       summary:
-          'The page title may not be descriptive enough to identify the page topic or purpose.',
-      hint:
-          'Use a more specific title that identifies the page topic or purpose (for example, include the section name or task).',
+        'The page title may not be descriptive enough to identify the page topic or purpose.',
+      hint: 'Use a more specific title that identifies the page topic or purpose (for example, include the section name or task).',
       i18n: {
         summaryKey,
         hintKey: 'pageTitlePatterns_hint_cantTell',
@@ -250,7 +272,10 @@ function runInPage(ctx) {
     } else {
       occurrences.push({
         ...occBase,
-        html: titleEl && titleEl.outerHTML ? String(titleEl.outerHTML).slice(0, 2000) : '<title>(unknown)</title>'
+        html:
+          titleEl && titleEl.outerHTML
+            ? String(titleEl.outerHTML).slice(0, 2000)
+            : '<title>(unknown)</title>'
       });
     }
   }
@@ -261,7 +286,12 @@ function runInPage(ctx) {
 
   if (occurrences.length) {
     // Patterns are review signals: cantTell rather than fail.
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
 
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -1,16 +1,17 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check presentation-role-conflict
  * @atomic true
  * @summary role="presentation"/"none" must not be combined with a global ARIA naming attribute or focusability
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies to elements with an explicit role="presentation" or
  *   role="none", OR an <img alt=""> (empty alt gives an <img> an implicit
  *   presentation role per HTML-AAM, even with no explicit role attribute
- *   at all — verified against a widely-used reference engine's own selector
- *   for this exact check, `img[alt=''], [role="none"], [role="presentation"]`).
+ *   at all — `img[alt=''], [role="none"], [role="presentation"]`).
  * @expectation
  *   The element does not also carry a WAI-ARIA *global* state/property
  *   (aria-label, aria-hidden, aria-describedby, aria-live, aria-current,
@@ -25,28 +26,27 @@
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - The conflicting-attribute set matches a widely-used reference engine's
- *   own `none: ['is-element-focusable', 'has-global-aria-attribute']` condition
- *   exactly — `has-global-aria-attribute` checks against the full list of
- *   ARIA attributes marked `global: true` in that engine's own standards data
- *   (confirmed by reading `standards.ariaAttrs` directly at runtime, not
- *   guessed), which is much broader than the 3-attribute naming-only list
- *   this rule originally checked (added 2026-07-20, then widened
- *   2026-07-20 after a real page — Slack's homepage has
- *   `<img alt="" aria-hidden="">`, both gaps at once: the img[alt=''] case
- *   wasn't in the applicability selector at all, and aria-hidden wasn't in
- *   the conflicting-attribute set even if it had been).
- * - Deliberately NOT replicating that reference engine's
- *   `hasImplicitChromiumRoleMatches` applicability gate, which (per direct
- *   probing of the reference engine's runtime) makes its own check
- *   inapplicable to role="presentation" on elements with no
- *   native implicit role to suppress in the first place (e.g.
- *   `<div role="presentation" aria-hidden="true">` — a <div> has no native
- *   role, so there's nothing for the presentational role to "conflict"
- *   with per that engine's own scope decision). Replicating that would require a
- *   full native-implicit-role table and isn't evidenced by any real false
- *   positive in this corpus yet — surea11y stays broader/more cautious
- *   here rather than narrower, which is the safer direction to diverge in.
+ * - `aria-hidden="true"` (the exact valid truthy value) on the
+ *   presentational element itself is deliberately EXCLUDED as a trigger,
+ *   even though it's a global ARIA attribute: it removes the element from
+ *   the accessibility tree unconditionally, so the "role restoration"
+ *   this rule warns about never actually reaches assistive tech, making a
+ *   flag misleading. Any OTHER conflicting attribute present alongside
+ *   `aria-hidden="true"` is equally inert for the same reason and is not
+ *   flagged either. An `aria-hidden=""` (empty/invalid value, does NOT
+ *   hide) still triggers normally. Focusability is unaffected by this
+ *   exemption (see the code comment at the check site).
+ * - The conflicting-attribute set is the full list of ARIA attributes
+ *   marked `global: true`, not a narrower naming-only list.
+ * - Deliberately NOT applying an implicit-role applicability gate that
+ *   would make the check inapplicable to role="presentation" on elements
+ *   with no native implicit role to suppress (e.g. `<div
+ *   role="presentation" aria-hidden="true">` — a <div> has no native role,
+ *   so there's nothing for the presentational role to "conflict" with).
+ *   surea11y stays broader/more cautious here rather than narrower, which
+ *   is the safer direction to diverge in. The native-implicit-role table
+ *   needed to add that gate, if this scope decision is ever revisited, is
+ *   in ROADMAP.md §7 item 9.
  * - Focusability is computed via helpers.getFocusableInfo (native +
  *   tabindex), same helper aria-hidden-focus already relies on — a
  *   `:disabled` or otherwise non-focusable element is not flagged.
@@ -56,7 +56,8 @@ const id = 'presentation-role-conflict';
 
 const meta = {
   title: 'Presentational role must not conflict with a global ARIA attribute or focusability',
-  description: 'Checks that role="presentation"/"none" (including an <img alt=""> implicit presentation role) is not combined with a global ARIA attribute (aria-label, aria-hidden, aria-describedby, ...) or focusability (tabindex/native).',
+  description:
+    'Checks that role="presentation"/"none" (including an <img alt=""> implicit presentation role) is not combined with a global ARIA attribute (aria-label, aria-hidden, aria-describedby, ...) or focusability (tabindex/native).',
   i18n: {
     titleKey: 'presentationRoleConflict_title',
     descriptionKey: 'presentationRoleConflict_description'
@@ -73,25 +74,44 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   // The full set of ARIA attributes marked `global: true` per the WAI-ARIA
-  // spec (confirmed against a widely-used reference engine's own
-  // `standards.ariaAttrs` data at runtime, 2026-07-20) — any of these present on a presentational
-  // element restores its implicit role, not just the naming ones.
+  // spec — any of these present on a presentational element restores its
+  // implicit role, not just the naming ones.
   const CONFLICTING_ATTRS = [
-    'aria-atomic', 'aria-braillelabel', 'aria-brailleroledescription', 'aria-busy',
-    'aria-controls', 'aria-current', 'aria-describedby', 'aria-description', 'aria-details',
-    'aria-disabled', 'aria-dropeffect', 'aria-errormessage', 'aria-flowto', 'aria-grabbed',
-    'aria-haspopup', 'aria-hidden', 'aria-invalid', 'aria-keyshortcuts', 'aria-label',
-    'aria-labelledby', 'aria-live', 'aria-owns', 'aria-relevant', 'aria-roledescription'
+    'aria-atomic',
+    'aria-braillelabel',
+    'aria-brailleroledescription',
+    'aria-busy',
+    'aria-controls',
+    'aria-current',
+    'aria-describedby',
+    'aria-description',
+    'aria-details',
+    'aria-disabled',
+    'aria-dropeffect',
+    'aria-errormessage',
+    'aria-flowto',
+    'aria-grabbed',
+    'aria-haspopup',
+    'aria-hidden',
+    'aria-invalid',
+    'aria-keyshortcuts',
+    'aria-label',
+    'aria-labelledby',
+    'aria-live',
+    'aria-owns',
+    'aria-relevant',
+    'aria-roledescription'
   ];
 
-  const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
   const nodes = helpers.queryAllSmart
-      ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]')
-      : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]');
+    ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]')
+    : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -103,11 +123,32 @@ function runInPage(ctx) {
 
     // Presence, not value truthiness: the WAI-ARIA role-conflict-resolution
     // rule triggers on a global ARIA attribute being SPECIFIED at all, even
-    // with an empty value — found on a real site, Slack's homepage has
-    // <img alt="" aria-hidden="">, where aria-hidden="" (empty string) is
-    // still a specified attribute. A truthy-value check would have missed
-    // this even after aria-hidden was added to CONFLICTING_ATTRS above.
-    const present = CONFLICTING_ATTRS.filter((attr) => (el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null));
+    // with an empty value — e.g. <img alt="" aria-hidden="">, where
+    // aria-hidden="" (empty string) is still a specified attribute. A
+    // truthy-value check would miss this.
+    let present = CONFLICTING_ATTRS.filter((attr) =>
+      el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null
+    );
+
+    // aria-hidden="true" (the exact, valid truthy value — not the
+    // empty-string case above, which never actually hides anything) is a
+    // special case: it removes the element and its subtree from the
+    // accessibility tree unconditionally, independent of role. That makes
+    // the "role restoration" this rule warns about ("...which restores its
+    // implicit role and cancels the presentational intent") factually
+    // inert — no AT will ever expose the restored role OR any of the other
+    // conflicting attributes (aria-label, aria-describedby, ...) present
+    // alongside it, since the whole element stays out of the tree
+    // regardless. This pattern is extremely common (e.g. <svg
+    // role="presentation" aria-hidden="true"> decorative icons — a
+    // defensive belt-and-suspenders double-hide, not an authoring mistake).
+    // Focusability is NOT covered by this exemption — a keyboard user can
+    // still tab onto an aria-hidden="true" focusable element (the
+    // aria-hidden-focus anti-pattern), a real, independent hazard
+    // aria-hidden does nothing to prevent.
+    if (el.getAttribute('aria-hidden') === 'true') {
+      present = [];
+    }
 
     let isFocusable = false;
     if (getFocusableInfo) {
@@ -126,9 +167,12 @@ function runInPage(ctx) {
 
     // No explicit role attribute means this matched via the img[alt=""]
     // implicit-presentation case.
-    const role = String(el.getAttribute('role') || '').trim().toLowerCase() || 'presentation';
+    const role =
+      String(el.getAttribute('role') || '')
+        .trim()
+        .toLowerCase() || 'presentation';
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -141,7 +185,12 @@ function runInPage(ctx) {
         params: { role, attrs: parts.join(', ') }
       },
       data: {
-        details: { reasonCode: 'PRESENTATION_ROLE_CONFLICT', role, conflictingAttrs: present, focusable: isFocusable }
+        details: {
+          reasonCode: 'PRESENTATION_ROLE_CONFLICT',
+          role,
+          conflictingAttrs: present,
+          focusable: isFocusable
+        }
       }
     });
   }
@@ -150,7 +199,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }