@surea11y/core 1.1.2 → 1.3.0

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

@@ -15,7 +15,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',
@@ -24,13 +30,23 @@ const meta = {
   coverage: { facetsBySc: { '2.4.2': ['page-title-patterns'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 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;
 
@@ -45,16 +61,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)
@@ -66,11 +82,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;
@@ -95,35 +111,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
             };
@@ -131,7 +153,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,
@@ -144,12 +167,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)
                 }))
@@ -165,12 +190,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
@@ -186,14 +219,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)
@@ -202,27 +228,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',
@@ -242,7 +270,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>'
       });
     }
   }
@@ -253,10 +284,15 @@ 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: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -43,10 +43,14 @@
  *   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.
+ *   with per that engine's own scope decision). surea11y stays
+ *   broader/more cautious here rather than narrower, which is the safer
+ *   direction to diverge in, and no real false positive from staying
+ *   broad has surfaced in any corpus round to date.
+ * - The native-implicit-role table needed to replicate that gate (if this
+ *   scope decision is ever revisited) has since been produced — see
+ *   ROADMAP.md §7 item 9 (2026-07-31) for the full table and the open
+ *   maintainer decision; not implemented here pending that call.
  * - 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 +60,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 +78,45 @@ 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.
   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;
@@ -107,7 +132,9 @@ function runInPage(ctx) {
     // <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));
+    const present = CONFLICTING_ATTRS.filter((attr) =>
+      el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null
+    );
 
     let isFocusable = false;
     if (getFocusableInfo) {
@@ -126,9 +153,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 +171,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 +185,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: [] };
 }