@surea11y/core 1.4.0 → 1.5.0

package/src/checks/manual/landmark-contentinfo-is-top-level-manual.js

@@ -22,12 +22,9 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent (this rule mirrors
  *   its structure with contentinfo/footer in place of banner/header).
- * - Candidate selection (`isContentinfoCandidate` below) is deliberately
- *   unconditional, instead of reusing the sectioning-ancestor suppression
- *   that the violation check itself depends on — same
- *   self-defeating-candidate-selection reasoning as
- *   landmark-banner-is-top-level (see that file's header comment for the
- *   full root cause).
+ * - Candidate selection (`isContentinfoCandidate`) requires the element to
+ *   really carry the contentinfo role, via the suppression-aware
+ *   `getLandmarkRole` — same reasoning as landmark-banner-is-top-level.
  */
 
 const id = 'landmark-contentinfo-is-top-level';
@@ -135,11 +132,11 @@ function runInPage(ctx) {
   // a candidate purely by tag + absence of any role attribute, independent
   // of whether sectioning-ancestor nesting would currently suppress its
   // implicit role; an explicit role="contentinfo" is always a candidate too.
+  // A candidate must actually have the contentinfo role — a <footer> inside
+  // article/aside/main/nav/section is not one, so flagging it as nested
+  // would report a landmark that does not exist.
   function isContentinfoCandidate(el) {
-    if (!el || !el.getAttribute) return false;
-    const explicit = getExplicitRoleToken(el);
-    if (explicit) return explicit === 'contentinfo';
-    return !!(el.tagName && el.tagName.toLowerCase() === 'footer');
+    return getLandmarkRole(el) === 'contentinfo';
   }
 
   function hasLandmarkAncestor(el) {
@@ -205,23 +202,20 @@ function runInPage(ctx) {
   for (const el of contentinfos) {
     if (!hasLandmarkAncestor(el)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This contentinfo landmark is nested inside another landmark region.',
-      hint: 'Move the contentinfo landmark (footer/role="contentinfo") so it is not contained by another landmark; contentinfo should be a top-level region of the page.',
-      i18n: {
-        summaryKey: 'landmarkContentinfoIsTopLevel_summary_cantTell',
-        hintKey: 'landmarkContentinfoIsTopLevel_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'LANDMARK_CONTENTINFO_NOT_TOP_LEVEL' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This contentinfo landmark is nested inside another landmark region.',
+        hint: 'Move the contentinfo landmark (footer/role="contentinfo") so it is not contained by another landmark; contentinfo should be a top-level region of the page.',
+        i18n: {
+          summaryKey: 'landmarkContentinfoIsTopLevel_summary_cantTell',
+          hintKey: 'landmarkContentinfoIsTopLevel_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'LANDMARK_CONTENTINFO_NOT_TOP_LEVEL' }
+        }
+      })
+    );
   }
 
   if (occurrences.length) {

package/src/checks/manual/landmark-main-is-top-level-manual.js

@@ -192,23 +192,20 @@ function runInPage(ctx) {
   for (const el of mains) {
     if (!hasLandmarkAncestor(el)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This main landmark is nested inside another landmark region.',
-      hint: 'Move the main landmark (<main>/role="main") so it is not contained by another landmark; main should be a top-level region of the page.',
-      i18n: {
-        summaryKey: 'landmarkMainIsTopLevel_summary_cantTell',
-        hintKey: 'landmarkMainIsTopLevel_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'LANDMARK_MAIN_NOT_TOP_LEVEL' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This main landmark is nested inside another landmark region.',
+        hint: 'Move the main landmark (<main>/role="main") so it is not contained by another landmark; main should be a top-level region of the page.',
+        i18n: {
+          summaryKey: 'landmarkMainIsTopLevel_summary_cantTell',
+          hintKey: 'landmarkMainIsTopLevel_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'LANDMARK_MAIN_NOT_TOP_LEVEL' }
+        }
+      })
+    );
   }
 
   if (occurrences.length) {

package/src/checks/manual/landmark-no-duplicate-banner-manual.js

@@ -171,12 +171,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = banners.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one banner landmark.',
       hint: 'Keep only one banner landmark (header/role="banner") per page.',
       i18n: {
@@ -187,7 +182,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_BANNER', count: banners.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-no-duplicate-contentinfo-manual.js

@@ -163,12 +163,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = contentinfos.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one contentinfo landmark.',
       hint: 'Keep only one contentinfo landmark (footer/role="contentinfo") per page.',
       i18n: {
@@ -179,7 +174,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_CONTENTINFO', count: contentinfos.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-no-duplicate-main-manual.js

@@ -108,12 +108,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = mains.map((el) => {
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    return helpers.reportOccurrence(el, {
       summary: 'This page has more than one main landmark.',
       hint: 'Keep only one main landmark (<main>/role="main") per page.',
       i18n: {
@@ -124,7 +119,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'LANDMARK_DUPLICATE_MAIN', count: mains.length }
       }
-    };
+    });
   });
 
   return {

package/src/checks/manual/landmark-one-main-manual.js

@@ -123,19 +123,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   return {
     ruleId: rule.ruleId,
     outcome: 'cantTell',
     severity: rule.defaultSeverity || 'minor',
     occurrences: [
-      {
-        selector: stableSelector,
-        html,
+      helpers.reportOccurrence(body, {
         summary: 'This page has no main landmark.',
         hint: 'Add a main landmark (<main> or role="main") around the page\'s primary content.',
         i18n: {
@@ -146,7 +139,7 @@ function runInPage(ctx) {
         data: {
           details: { reasonCode: 'LANDMARK_MAIN_MISSING' }
         }
-      }
+      })
     ]
   };
 }

package/src/checks/manual/landmark-unique-manual.js

@@ -219,34 +219,29 @@ function runInPage(ctx) {
       if (group.length <= 1) continue;
 
       for (const { el } of group) {
-        const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-        const html = helpers.getOuterHtmlSnippet
-          ? helpers.getOuterHtmlSnippet(el)
-          : el.outerHTML || '';
-
-        occurrences.push({
-          selector: stableSelector,
-          html,
-          summary: normalizedName
-            ? `This ${role} landmark shares its accessible name with another ${role} landmark.`
-            : `This ${role} landmark has no accessible name, and more than one unnamed ${role} landmark exists on this page.`,
-          hint: `Give each ${role} landmark a distinct name via aria-label or aria-labelledby.`,
-          i18n: {
-            summaryKey: normalizedName
-              ? 'landmarkUnique_summary_cantTell_duplicateName'
-              : 'landmarkUnique_summary_cantTell_bothUnnamed',
-            hintKey: 'landmarkUnique_hint_cantTell',
-            params: { role }
-          },
-          data: {
-            details: {
-              reasonCode: 'LANDMARK_NOT_UNIQUE',
-              role,
-              name: normalizedName,
-              groupSize: group.length
+        occurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: normalizedName
+              ? `This ${role} landmark shares its accessible name with another ${role} landmark.`
+              : `This ${role} landmark has no accessible name, and more than one unnamed ${role} landmark exists on this page.`,
+            hint: `Give each ${role} landmark a distinct name via aria-label or aria-labelledby.`,
+            i18n: {
+              summaryKey: normalizedName
+                ? 'landmarkUnique_summary_cantTell_duplicateName'
+                : 'landmarkUnique_summary_cantTell_bothUnnamed',
+              hintKey: 'landmarkUnique_hint_cantTell',
+              params: { role }
+            },
+            data: {
+              details: {
+                reasonCode: 'LANDMARK_NOT_UNIQUE',
+                role,
+                name: normalizedName,
+                groupSize: group.length
+              }
             }
-          }
-        });
+          })
+        );
       }
     }
   }

package/src/checks/manual/link-name-quality-manual.js

@@ -133,27 +133,25 @@ function runInPage(ctx) {
 
     if (!GENERIC_LINK_TEXT.has(normalized)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This link's accessible name ("${rawName.trim()}") is a generic, non-descriptive phrase.`,
-      hint: 'Make the link text itself describe its destination/purpose (e.g. "Download the 2026 pricing guide" instead of "Download"), or confirm the surrounding context already makes the purpose clear.',
-      i18n: {
-        summaryKey: 'linkNameQuality_summary_cantTell',
-        hintKey: 'linkNameQuality_hint_cantTell',
-        params: { name: rawName.trim() }
-      },
-      data: {
-        details: { reasonCode: 'GENERIC_LINK_TEXT', normalizedName: normalized },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This link's accessible name ("${rawName.trim()}") is a generic, non-descriptive phrase.`,
+        hint: 'Make the link text itself describe its destination/purpose (e.g. "Download the 2026 pricing guide" instead of "Download"), or confirm the surrounding context already makes the purpose clear.',
+        i18n: {
+          summaryKey: 'linkNameQuality_summary_cantTell',
+          hintKey: 'linkNameQuality_hint_cantTell',
+          params: { name: rawName.trim() }
+        },
+        data: {
+          details: { reasonCode: 'GENERIC_LINK_TEXT', normalizedName: normalized },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/meta-viewport-large-manual.js

@@ -104,23 +104,20 @@ function runInPage(ctx) {
 
     if (!reasons.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This viewport meta tag restricts zoom below the 500% best-practice target.',
-      hint: 'Remove user-scalable=no and raise maximum-scale to at least 5 (500%) if possible.',
-      i18n: {
-        summaryKey: 'metaViewportLarge_summary_cantTell',
-        hintKey: 'metaViewportLarge_hint_cantTell',
-        params: { reasons: reasons.join(', ') }
-      },
-      data: {
-        details: { reasonCode: 'VIEWPORT_ZOOM_BELOW_500', reasons }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This viewport meta tag restricts zoom below the 500% best-practice target.',
+        hint: 'Remove user-scalable=no and raise maximum-scale to at least 5 (500%) if possible.',
+        i18n: {
+          summaryKey: 'metaViewportLarge_summary_cantTell',
+          hintKey: 'metaViewportLarge_hint_cantTell',
+          params: { reasons: reasons.join(', ') }
+        },
+        data: {
+          details: { reasonCode: 'VIEWPORT_ZOOM_BELOW_500', reasons }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/mouse-only-event-handlers-manual.js

@@ -117,30 +117,28 @@ function runInPage(ctx) {
     const hasKeyboardEquiv = KEYBOARD_EQUIV_ATTRS.some((a) => trim(el.getAttribute(a)));
     if (hasKeyboardEquiv) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This element has ${presentMouseAttrs.join(', ')} but no keyboard-reachable equivalent handler.`,
-      hint: 'Add onkeydown/onkeyup/onkeypress (or onfocus/onblur for hover-triggered behavior) so this functionality is also reachable by keyboard.',
-      i18n: {
-        summaryKey: 'mouseOnlyEventHandlers_summary_cantTell',
-        hintKey: 'mouseOnlyEventHandlers_hint_cantTell',
-        params: { attrs: presentMouseAttrs.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'MOUSE_ONLY_HANDLER_NO_KEYBOARD_EQUIVALENT',
-          mouseAttrs: presentMouseAttrs
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This element has ${presentMouseAttrs.join(', ')} but no keyboard-reachable equivalent handler.`,
+        hint: 'Add onkeydown/onkeyup/onkeypress (or onfocus/onblur for hover-triggered behavior) so this functionality is also reachable by keyboard.',
+        i18n: {
+          summaryKey: 'mouseOnlyEventHandlers_summary_cantTell',
+          hintKey: 'mouseOnlyEventHandlers_hint_cantTell',
+          params: { attrs: presentMouseAttrs.join(', ') }
         },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+        data: {
+          details: {
+            reasonCode: 'MOUSE_ONLY_HANDLER_NO_KEYBOARD_EQUIVALENT',
+            mouseAttrs: presentMouseAttrs
+          },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/page-has-heading-one-manual.js

@@ -126,19 +126,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   return {
     ruleId: rule.ruleId,
     outcome: 'cantTell',
     severity: rule.defaultSeverity || 'minor',
     occurrences: [
-      {
-        selector: stableSelector,
-        html,
+      helpers.reportOccurrence(body, {
         summary: 'This page has no level-one heading.',
         hint: 'Add a level-one heading (<h1> or role="heading" aria-level="1") that identifies the page\'s main content.',
         i18n: {
@@ -149,7 +142,7 @@ function runInPage(ctx) {
         data: {
           details: { reasonCode: 'HEADING_ONE_MISSING' }
         }
-      }
+      })
     ]
   };
 }

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

@@ -171,28 +171,26 @@ function runInPage(ctx) {
       String(el.getAttribute('role') || '')
         .trim()
         .toLowerCase() || 'presentation';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
-      hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'presentationRoleConflict_summary_cantTell',
-        hintKey: 'presentationRoleConflict_hint_cantTell',
-        params: { role, attrs: parts.join(', ') }
-      },
-      data: {
-        details: {
-          reasonCode: 'PRESENTATION_ROLE_CONFLICT',
-          role,
-          conflictingAttrs: present,
-          focusable: isFocusable
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This role="${role}" element also has a conflicting condition (${parts.join(', ')}), which restores its implicit role and cancels the presentational intent.`,
+        hint: 'Remove the conflicting naming attribute(s) and/or focusability (tabindex/native) if the element should stay presentational, or remove role="presentation"/"none" if it should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'presentationRoleConflict_summary_cantTell',
+          hintKey: 'presentationRoleConflict_hint_cantTell',
+          params: { role, attrs: parts.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'PRESENTATION_ROLE_CONFLICT',
+            role,
+            conflictingAttrs: present,
+            focusable: isFocusable
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/region-manual.js

@@ -352,14 +352,11 @@ function runInPage(ctx) {
     }
   }
 
+  // Report the element itself: without a node reference the engine re-finds
+  // each one with document.querySelector to build its structuralPath.
   const occurrences = collapsed.map((el) => {
     const tag = el.tagName ? lower(el.tagName) : '';
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    return {
-      selector: stableSelector,
-      html,
+    const partial = {
       summary: 'This content is not contained within a landmark region.',
       hint: 'Move this content inside a landmark region (main, nav, aside, a labeled section, etc.).',
       i18n: {
@@ -371,6 +368,16 @@ function runInPage(ctx) {
         details: { reasonCode: 'CONTENT_OUTSIDE_LANDMARK', element: tag }
       }
     };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      return helpers.reportOccurrence(el, partial);
+    }
+
+    return {
+      selector: helpers.buildSelector ? helpers.buildSelector(el) : 'html',
+      html: helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '',
+      ...partial
+    };
   });
 
   if (occurrences.length === 0) {

package/src/checks/manual/scope-attr-valid-manual.js

@@ -61,23 +61,20 @@ function runInPage(ctx) {
 
     if (VALID_SCOPES.has(raw.toLowerCase())) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This scope attribute value is not recognized.',
-      hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
-      i18n: {
-        summaryKey: 'scopeAttrValid_summary_cantTell',
-        hintKey: 'scopeAttrValid_hint_cantTell',
-        params: { value: raw }
-      },
-      data: {
-        details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This scope attribute value is not recognized.',
+        hint: 'Use one of row, col, rowgroup, or colgroup for the scope attribute.',
+        i18n: {
+          summaryKey: 'scopeAttrValid_summary_cantTell',
+          hintKey: 'scopeAttrValid_hint_cantTell',
+          params: { value: raw }
+        },
+        data: {
+          details: { reasonCode: 'SCOPE_ATTR_INVALID', value: raw }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {