@surea11y/core 1.1.2 → 1.3.0

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -27,7 +27,8 @@ const id = 'html-xml-lang-mismatch';
 
 const meta = {
   title: 'lang and xml:lang must not disagree',
-  description: 'Checks that the <html> element\'s lang and xml:lang attributes declare the same primary language, when both are present.',
+  description:
+    "Checks that the <html> element's lang and xml:lang attributes declare the same primary language, when both are present.",
   i18n: {
     titleKey: 'htmlXmlLangMismatch_title',
     descriptionKey: 'htmlXmlLangMismatch_description'
@@ -36,7 +37,13 @@ const meta = {
   tags: ['wcag2a', 'wcag311', 'structure', 'language', 'atomic', 'automatic'],
   wcagSc: ['3.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '3.1.1', title: 'Language of Page', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '3.1.1',
+      title: 'Language of Page',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'understandable',
@@ -45,11 +52,19 @@ const meta = {
   coverage: { facetsBySc: { '3.1.1': ['html-xml-lang-mismatch'] } }
 };
 
+// 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 html = document && document.documentElement;
-  const tag = (html && html.tagName) ? String(html.tagName).toLowerCase() : '';
+  const tag = html && html.tagName ? String(html.tagName).toLowerCase() : '';
   if (!html || tag !== 'html') {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
@@ -68,24 +83,33 @@ function runInPage(ctx) {
   }
 
   const stableSelector = helpers.buildSelector ? helpers.buildSelector(html) : 'html';
-  const htmlSnippet = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(html) : (html.outerHTML || '').slice(0, 200);
+  const htmlSnippet = helpers.getOuterHtmlSnippet
+    ? helpers.getOuterHtmlSnippet(html)
+    : (html.outerHTML || '').slice(0, 200);
 
-  const occurrences = [{
-    selector: stableSelector,
-    html: htmlSnippet,
-    summary: `The lang ("${lang}") and xml:lang ("${xmlLang}") attributes declare different languages.`,
-    hint: 'Make lang and xml:lang declare the same primary language, or remove the deprecated xml:lang attribute.',
-    i18n: {
-      summaryKey: 'htmlXmlLangMismatch_summary_fail',
-      hintKey: 'htmlXmlLangMismatch_hint_fail',
-      params: { lang, xmlLang }
-    },
-    data: {
-      details: { reasonCode: 'HTML_XML_LANG_MISMATCH', lang, xmlLang }
+  const occurrences = [
+    {
+      selector: stableSelector,
+      html: htmlSnippet,
+      summary: `The lang ("${lang}") and xml:lang ("${xmlLang}") attributes declare different languages.`,
+      hint: 'Make lang and xml:lang declare the same primary language, or remove the deprecated xml:lang attribute.',
+      i18n: {
+        summaryKey: 'htmlXmlLangMismatch_summary_fail',
+        hintKey: 'htmlXmlLangMismatch_hint_fail',
+        params: { lang, xmlLang }
+      },
+      data: {
+        details: { reasonCode: 'HTML_XML_LANG_MISMATCH', lang, xmlLang }
+      }
     }
-  }];
+  ];
 
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'serious',
+    occurrences
+  };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/automatic/iframe-focusable-content.js

@@ -36,7 +36,8 @@ const id = 'iframe-focusable-content';
 
 const meta = {
   title: 'Frames with tabindex="-1" must not contain focusable content',
-  description: 'Checks that same-origin <iframe>/<frame> elements with tabindex="-1" do not contain focusable content, since browsers do not propagate that restriction into the frame’s embedded document.',
+  description:
+    'Checks that same-origin <iframe>/<frame> elements with tabindex="-1" do not contain focusable content, since browsers do not propagate that restriction into the frame’s embedded document.',
   i18n: {
     titleKey: 'iframeFocusableContent_title',
     descriptionKey: 'iframeFocusableContent_description'
@@ -45,7 +46,13 @@ const meta = {
   tags: ['wcag2a', 'wcag211', 'structure', 'atomic', 'automatic', 'keyboard', 'iframe'],
   wcagSc: ['2.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '2.1.1', title: 'Keyboard', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.1.1',
+      title: 'Keyboard',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'moderate',
   category: 'operable',
@@ -55,15 +62,15 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   function hasFocusableCandidate(doc) {
     if (!doc || !doc.querySelectorAll) return false;
-    let els = [];
+    let els;
     try {
       els = doc.querySelectorAll(
         'a[href], area[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), ' +
-        'select:not([disabled]), textarea:not([disabled]), iframe, [contenteditable="true"], [tabindex]'
+          'select:not([disabled]), textarea:not([disabled]), iframe, [contenteditable="true"], [tabindex]'
       );
     } catch {
       return false;
@@ -87,7 +94,9 @@ function runInPage(ctx) {
     return !Number.isNaN(n) && n < 0;
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame') : helpers.queryAll('iframe, frame');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('iframe, frame')
+    : helpers.queryAll('iframe, frame');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -96,7 +105,7 @@ function runInPage(ctx) {
     if (!el || !el.getAttribute) continue;
     if (!getNegativeTabIndex(el)) continue;
 
-    let contentDoc = null;
+    let contentDoc;
     try {
       contentDoc = el.contentDocument || null;
     } catch {
@@ -110,12 +119,13 @@ function runInPage(ctx) {
 
     const tag = el.tagName.toLowerCase();
     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,
       html,
-      summary: 'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
+      summary:
+        'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
       hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
       i18n: {
         summaryKey: 'iframeFocusableContent_summary_fail',
@@ -132,9 +142,14 @@ function runInPage(ctx) {
     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: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/iframe-name-present.js

@@ -25,7 +25,8 @@ const id = 'iframe-name-present';
 
 const meta = {
   title: 'Frames have an accessible name',
-  description: 'Checks that <iframe>/<frame> elements expose a non-empty accessible name via aria-label, aria-labelledby, or the title attribute.',
+  description:
+    'Checks that <iframe>/<frame> elements expose a non-empty accessible name via aria-label, aria-labelledby, or the title attribute.',
   i18n: {
     titleKey: 'iframeNamePresent_title',
     descriptionKey: 'iframeNamePresent_description'
@@ -34,7 +35,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'structure', 'atomic', 'automatic', 'name', 'iframe'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -44,9 +51,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame') : helpers.queryAll('iframe, frame');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('iframe, frame')
+    : helpers.queryAll('iframe, frame');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -62,15 +71,23 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 }) : null;
+    const nameInfo = helpers.getAccessibleNameInfo
+      ? helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 })
+      : null;
     if (nameInfo && nameInfo.present && nameInfo.value) continue;
 
     const eligInfo = helpers.getEligibilityInfo
-      ? (() => { try { return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+      ? (() => {
+          try {
+            return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
       : null;
     const tag = el.tagName.toLowerCase();
     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,
@@ -93,9 +110,14 @@ function runInPage(ctx) {
     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: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/iframe-title-unique.js

@@ -28,7 +28,8 @@ const id = 'iframe-title-unique';
 
 const meta = {
   title: 'Frame titles must be unique',
-  description: 'Checks that no two <iframe>/<frame> elements in scope share the same title attribute value.',
+  description:
+    'Checks that no two <iframe>/<frame> elements in scope share the same title attribute value.',
   i18n: {
     titleKey: 'iframeTitleUnique_title',
     descriptionKey: 'iframeTitleUnique_description'
@@ -37,7 +38,13 @@ const meta = {
   tags: ['wcag2a', 'wcag412', 'structure', 'atomic', 'automatic', 'name', 'iframe'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'moderate',
   category: 'robust',
@@ -47,9 +54,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('iframe, frame') : helpers.queryAll('iframe, frame');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('iframe, frame')
+    : helpers.queryAll('iframe, frame');
 
   const groups = new Map(); // trimmed title -> elements[]
   let applicableCount = 0;
@@ -79,7 +88,9 @@ function runInPage(ctx) {
     for (const el of els) {
       const tag = el.tagName.toLowerCase();
       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,
@@ -92,16 +103,26 @@ function runInPage(ctx) {
           params: { element: tag, title }
         },
         data: {
-          details: { reasonCode: 'IFRAME_TITLE_DUPLICATE', element: tag, title, duplicateCount: els.length }
+          details: {
+            reasonCode: 'IFRAME_TITLE_DUPLICATE',
+            element: tag,
+            title,
+            duplicateCount: els.length
+          }
         }
       });
     }
   }
 
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/img-alt-present.js

@@ -20,7 +20,8 @@ const id = 'img-alt-present';
 
 const meta = {
   title: '<img> must have an alt attribute',
-  description: 'Checks that <img> elements provide an alt attribute to support a text alternative mechanism.',
+  description:
+    'Checks that <img> elements provide an alt attribute to support a text alternative mechanism.',
   i18n: {
     titleKey: 'img_altPresent_title',
     descriptionKey: 'img_altPresent_description'
@@ -29,7 +30,13 @@ const meta = {
   tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'atomic', 'automatic'],
   wcagSc: ['1.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -46,12 +53,17 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
-  const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
-  const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
 
   // Prefer tagName collection when available (cheap), otherwise fall back.
   function getImgsCollection() {
@@ -73,7 +85,8 @@ function runInPage(ctx) {
     }
 
     try {
-      if (safeRoot && typeof safeRoot.querySelectorAll === 'function') return safeRoot.querySelectorAll('img');
+      if (safeRoot && typeof safeRoot.querySelectorAll === 'function')
+        return safeRoot.querySelectorAll('img');
     } catch {
       // fall through
     }
@@ -94,19 +107,6 @@ function runInPage(ctx) {
   // Helper-safe trim
   const trim = (v) => (v == null ? '' : String(v)).trim();
 
-  // Deterministic tabindex fallback (only used if helper missing)
-  function isFocusableFallback(el) {
-    try {
-      const tabindex = el.getAttribute('tabindex');
-      if (tabindex == null) return false;
-      const s = String(tabindex).trim();
-      if (!s) return false;
-      return !Number.isNaN(Number(s));
-    } catch {
-      return false;
-    }
-  }
-
   for (let i = 0; i < imgLen; i++) {
     const el = imgs[i];
     if (!el || !el.getAttribute) continue;
@@ -125,7 +125,7 @@ function runInPage(ctx) {
     }
 
     // Role (presentation/none) exclusion only when NOT focusable.
-    let role = '';
+    let role;
     try {
       role = trim(el.getAttribute('role')).toLowerCase();
     } catch {
@@ -133,17 +133,13 @@ function runInPage(ctx) {
     }
 
     if (role === 'presentation' || role === 'none') {
-      let focusable = false;
-      if (getFocusableInfo) {
-        try {
-          const fi = getFocusableInfo(el, ctx);
-          // Preserve existing behavior: prefer fi.focusable; fall back to fi.tabbable if present.
-          focusable = !!(fi && (fi.focusable || fi.tabbable));
-        } catch {
-          focusable = false;
-        }
-      } else {
-        focusable = isFocusableFallback(el);
+      let focusable;
+      try {
+        const fi = getFocusableInfo(el, ctx);
+        // Preserve existing behavior: prefer fi.focusable; fall back to fi.tabbable if present.
+        focusable = !!(fi && (fi.focusable || fi.tabbable));
+      } catch {
+        focusable = false;
       }
 
       if (!focusable) continue;
@@ -153,7 +149,7 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     // alt attribute presence check (empty allowed)
-    let hasAlt = false;
+    let hasAlt;
     try {
       hasAlt = el.getAttribute('alt') !== null;
     } catch {
@@ -167,7 +163,7 @@ function runInPage(ctx) {
     // image with a non-empty ARIA name is not missing a text alternative
     // just because it lacks an alt attribute.
     if (getAriaNameInfo) {
-      let ariaName = null;
+      let ariaName;
       try {
         ariaName = getAriaNameInfo(el, ctx);
       } catch {
@@ -188,7 +184,15 @@ function runInPage(ctx) {
     const title = trim(el.getAttribute('title'));
     if (title) continue;
 
-    const eligInfo = getEligibilityInfo ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })() : null;
+    const eligInfo = getEligibilityInfo
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
 
     const baseOccurrence = {
       summary: 'Missing alt attribute on <img>.',
@@ -201,12 +205,7 @@ function runInPage(ctx) {
       data: { visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] } }
     };
 
-    if (helpers && typeof helpers.reportOccurrence === 'function') {
-      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-    } else {
-      // Never compute selector/snippet in the rule.
-      occurrences.push({ __node: el, selector: '', html: '', ...baseOccurrence });
-    }
+    occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
   }
 
   if (applicableCount === 0) {
@@ -217,7 +216,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'fail',
+    severity: rule.defaultSeverity || 'minor',
+    occurrences
+  };
 }
 
 module.exports = { id, meta, runInPage };