@surea11y/core 1.2.0 → 1.3.0

package/src/checks/manual/image-redundant-alt-manual.js

@@ -30,7 +30,8 @@ const id = 'image-redundant-alt';
 
 const meta = {
   title: 'Image alt text must not duplicate adjacent visible text',
-  description: 'Checks that an <img> alt text is not identical to other visible text already present in its immediate parent element.',
+  description:
+    'Checks that an <img> alt text is not identical to other visible text already present in its immediate parent element.',
   i18n: {
     titleKey: 'imageRedundantAlt_title',
     descriptionKey: 'imageRedundantAlt_description'
@@ -47,10 +48,12 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getOwnTextExcludingImg(parent, imgEl) {
@@ -66,7 +69,9 @@ function runInPage(ctx) {
     return normalizeWs(text);
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img[alt]') : helpers.queryAll('img[alt]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('img[alt]')
+    : helpers.queryAll('img[alt]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -87,12 +92,12 @@ function runInPage(ctx) {
     if (otherText.toLowerCase() !== alt.toLowerCase()) continue;
 
     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 image\'s alt text duplicates other visible text right next to it.',
+      summary: "This image's alt text duplicates other visible text right next to it.",
       hint: 'Make the alt text empty (alt="") if the image is purely decorative alongside the text, or remove the redundant duplication.',
       i18n: {
         summaryKey: 'imageRedundantAlt_summary_cantTell',
@@ -109,7 +114,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: [] };
 }

package/src/checks/manual/img-alt-decorative-manual.js

@@ -11,20 +11,27 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "img-alt-decorative";
+const id = 'img-alt-decorative';
 
 const meta = {
-  title: "<img> with alt=\"\" must be decorative (manual review)",
-  description: "Flags <img> elements with empty alt for human review that they are purely decorative.",
+  title: '<img> with alt="" must be decorative (manual review)',
+  description:
+    'Flags <img> elements with empty alt for human review that they are purely decorative.',
   i18n: {
-    titleKey: "img_altDecorative_title",
-    descriptionKey: "img_altDecorative_description"
+    titleKey: 'img_altDecorative_title',
+    descriptionKey: 'img_altDecorative_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag111", "nontext", "images", "manual", "atomic"],
+  tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'manual', 'atomic'],
   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: 'minor',
   category: 'perceivable',
@@ -38,111 +45,139 @@ const meta = {
 };
 
 function runInPage(ctx) {
-
-    const { document, root, helpers, rule } = ctx;
-    const safeRoot = root || document;
-
-    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-    const queryAll = helpers && typeof helpers.queryAll === 'function'
-        ? helpers.queryAll
-        : (sel) => {
-            try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
-            catch { return []; }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
         };
 
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-        ? helpers.isAccTreeEligible
-        : null;
-
-    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
-        ? helpers.getFocusableInfo
-        : null;
-
-    function isRolePresentationExcluded(el) {
-        const role = (() => {
-            try { return String(el.getAttribute('role') || '').trim().toLowerCase(); }
-            catch { return ''; }
-        })();
-        if (role !== 'presentation' && role !== 'none') return false;
-
-        // Exclude only when NOT focusable (mirrors img-alt-present policy)
-        let focusable = false;
-        if (getFocusableInfo) {
-            const fi = (() => { try { return getFocusableInfo(el, ctx); } catch { return null; } })();
-            focusable = !!(fi && fi.focusable);
-        } else {
-            const tabindex = el.getAttribute('tabindex');
-            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  function isRolePresentationExcluded(el) {
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (role !== 'presentation' && role !== 'none') return false;
+
+    // Exclude only when NOT focusable (mirrors img-alt-present policy)
+    let focusable;
+    if (getFocusableInfo) {
+      const fi = (() => {
+        try {
+          return getFocusableInfo(el, ctx);
+        } catch {
+          return null;
         }
-        return !focusable;
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      const tabindex = el.getAttribute('tabindex');
+      focusable =
+        tabindex != null &&
+        String(tabindex).trim() !== '' &&
+        !Number.isNaN(Number(String(tabindex).trim()));
     }
+    return !focusable;
+  }
 
-    const els = (() => {
-        // Only likely candidates:
-        // - alt="" (exact)
-        // - alt that starts/ends with space (to catch whitespace-only like "   ")
-        const sel = 'img[alt=""], img[alt^=" "], img[alt$=" "]';
-        try { return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []); }
-        catch { return queryAll(sel); }
-    })();
-    const uniqueEls = [];
-    const seen = new Set();
-    for (const el of els) {
-        if (!seen.has(el)) { seen.add(el); uniqueEls.push(el); }
+  const els = (() => {
+    // Only likely candidates:
+    // - alt="" (exact)
+    // - alt that starts/ends with space (to catch whitespace-only like "   ")
+    const sel = 'img[alt=""], img[alt^=" "], img[alt$=" "]';
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []);
+    } catch {
+      return queryAll(sel);
     }
-
-    if (!els.length) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  })();
+  const uniqueEls = [];
+  const seen = new Set();
+  for (const el of els) {
+    if (!seen.has(el)) {
+      seen.add(el);
+      uniqueEls.push(el);
     }
+  }
 
-    const occurrences = [];
-    let applicableCount = 0;
-
-    for (const el of uniqueEls) {
-        if (!el || !el.getAttribute) continue;
+  if (!els.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-        if (isAccTreeEligible) {
-            const elig = (() => {
-                try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
-            })();
-            if (elig && elig.eligible === false) continue;
-        }
+  const occurrences = [];
+  let applicableCount = 0;
 
-        if (isRolePresentationExcluded(el)) continue;
-
-        // Rule-specific applicability (only elements that already have a text alternative mechanism)
-        const rawAlt = el.getAttribute('alt');
-        if (rawAlt == null) continue;
-        if (String(rawAlt).trim() !== '') continue;
-
-        applicableCount += 1;
-
-        const baseOccurrence = {
-            summary: 'Review whether <img> is decorative (alt="").',
-            hint: 'Confirm the image is purely decorative. If it conveys information or function, provide meaningful alt text.',
-            i18n: {
-                summaryKey: 'img_altDecorative_summary_cantTell',
-                hintKey: 'img_altDecorative_hint_cantTell',
-                params: { element: 'img' }
-            },
-            data: {
-                visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] },
-                details: null
-            }
-        };
+  for (const el of uniqueEls) {
+    if (!el || !el.getAttribute) continue;
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
         }
+      })();
+      if (elig && elig.eligible === false) continue;
     }
 
-    if (applicableCount === 0) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    if (isRolePresentationExcluded(el)) continue;
+
+    // Rule-specific applicability (only elements that already have a text alternative mechanism)
+    const rawAlt = el.getAttribute('alt');
+    if (rawAlt == null) continue;
+    if (String(rawAlt).trim() !== '') continue;
+
+    applicableCount += 1;
+
+    const baseOccurrence = {
+      summary: 'Review whether <img> is decorative (alt="").',
+      hint: 'Confirm the image is purely decorative. If it conveys information or function, provide meaningful alt text.',
+      i18n: {
+        summaryKey: 'img_altDecorative_summary_cantTell',
+        hintKey: 'img_altDecorative_hint_cantTell',
+        params: { element: 'img' }
+      },
+      data: {
+        visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: null
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/manual/img-alt-quality-manual.js

@@ -11,20 +11,26 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "img-alt-quality";
+const id = 'img-alt-quality';
 
 const meta = {
-  title: "<img> alt text must be appropriate (manual review)",
-  description: "Flags <img> elements with non-empty alt text for human review of appropriateness.",
+  title: '<img> alt text must be appropriate (manual review)',
+  description: 'Flags <img> elements with non-empty alt text for human review of appropriateness.',
   i18n: {
-    titleKey: "img_altQuality_title",
-    descriptionKey: "img_altQuality_description"
+    titleKey: 'img_altQuality_title',
+    descriptionKey: 'img_altQuality_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag111", "nontext", "images", "manual", "atomic"],
+  tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'manual', 'atomic'],
   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: 'minor',
   category: 'perceivable',
@@ -38,145 +44,188 @@ const meta = {
 };
 
 function runInPage(ctx) {
-    const { document, root, helpers, rule } = ctx;
-    const safeRoot = root || document;
-
-    // Cap occurrences to keep manual “quality” checks fast on large pages.
-    // Deterministic: we keep DOM order, just stop collecting after N.
-    const MAX_OCCURRENCES = 50;
-
-    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-    const queryAll = helpers && typeof helpers.queryAll === 'function'
-        ? helpers.queryAll
-        : (sel) => {
-            try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
-            catch { return []; }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  // Cap occurrences to keep manual “quality” checks fast on large pages.
+  // Deterministic: we keep DOM order, just stop collecting after N.
+  const MAX_OCCURRENCES = 50;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
         };
 
-    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;
-
-    function isRolePresentationExcluded(el) {
-        const role = (() => {
-            try { return String(el.getAttribute('role') || '').trim().toLowerCase(); }
-            catch { return ''; }
-        })();
-        if (role !== 'presentation' && role !== 'none') return false;
-
-        // Exclude only when NOT focusable (mirrors img-alt-present policy)
-        let focusable = false;
-        if (getFocusableInfo) {
-            const fi = (() => { try { return getFocusableInfo(el, ctx); } catch { return null; } })();
-            focusable = !!(fi && fi.focusable);
-        } else {
-            const tabindex = el.getAttribute('tabindex');
-            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
-        }
-        return !focusable;
-    }
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-    const selector = 'img[alt]:not([alt=""])';
-    const els = (() => {
-        try { return Array.from((queryAllSmart ? queryAllSmart(selector) : queryAll(selector)) || []); }
-        catch { return queryAll(selector); }
-    })();
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
-    if (!els.length) {
-        return {
-            ruleId: rule.ruleId,
-            outcome: 'notApplicable',
-            severity: 'minor',
-            occurrences: [],
-            data: { details: { applicableCount: 0, reportedCount: 0, maxOccurrences: MAX_OCCURRENCES, truncated: false } }
-        };
-    }
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
-    const occurrences = [];
-    let applicableCount = 0;  // total applicable elements
-    let collectedCount = 0;   // how many occurrences we actually reported
+  function isRolePresentationExcluded(el) {
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (role !== 'presentation' && role !== 'none') return false;
+
+    // Exclude only when NOT focusable (mirrors img-alt-present policy)
+    let focusable;
+    if (getFocusableInfo) {
+      const fi = (() => {
+        try {
+          return getFocusableInfo(el, ctx);
+        } catch {
+          return null;
+        }
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      const tabindex = el.getAttribute('tabindex');
+      focusable =
+        tabindex != null &&
+        String(tabindex).trim() !== '' &&
+        !Number.isNaN(Number(String(tabindex).trim()));
+    }
+    return !focusable;
+  }
 
-    for (const el of els) {
-        if (!el || !el.getAttribute) continue;
+  const selector = 'img[alt]:not([alt=""])';
+  const els = (() => {
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart(selector) : queryAll(selector)) || []);
+    } catch {
+      return queryAll(selector);
+    }
+  })();
 
-        if (isAccTreeEligible) {
-            const elig = (() => {
-                try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
-            })();
-            if (elig && elig.eligible === false) continue;
+  if (!els.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'notApplicable',
+      severity: 'minor',
+      occurrences: [],
+      data: {
+        details: {
+          applicableCount: 0,
+          reportedCount: 0,
+          maxOccurrences: MAX_OCCURRENCES,
+          truncated: false
         }
+      }
+    };
+  }
 
-        if (isRolePresentationExcluded(el)) continue;
-
-        // Rule-specific applicability: non-empty alt
-        const alt = (() => {
-            try { return String(el.getAttribute('alt') || '').trim(); } catch { return ''; }
-        })();
-        if (!alt) continue;
-
-        applicableCount += 1;
-
-        // IMPORTANT: stop doing expensive occurrence building after we hit the cap
-        if (collectedCount >= MAX_OCCURRENCES) continue;
-
-        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
-        const baseOccurrence = {
-            summary: 'Review alt text on <img> for accuracy and appropriateness.',
-            hint: 'Ensure the alt text conveys the image’s purpose/information in context (not redundant, not filename-like).',
-            i18n: {
-                summaryKey: 'img_altQuality_summary_cantTell',
-                hintKey: 'img_altQuality_hint_cantTell',
-                params: { element: 'img' }
-            },
-            data: {
-                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-                details: null
-            }
-        };
+  const occurrences = [];
+  let applicableCount = 0; // total applicable elements
+  let collectedCount = 0; // how many occurrences we actually reported
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
-        }
+  for (const el of els) {
+    if (!el || !el.getAttribute) continue;
 
-        collectedCount += 1;
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
+      if (elig && elig.eligible === false) continue;
     }
 
-    if (applicableCount === 0) {
-        return {
-            ruleId: rule.ruleId,
-            outcome: 'notApplicable',
-            severity: 'minor',
-            occurrences: [],
-            data: { details: { applicableCount: 0, reportedCount: 0, maxOccurrences: MAX_OCCURRENCES, truncated: false } }
-        };
+    if (isRolePresentationExcluded(el)) continue;
+
+    // Rule-specific applicability: non-empty alt
+    const alt = (() => {
+      try {
+        return String(el.getAttribute('alt') || '').trim();
+      } catch {
+        return '';
+      }
+    })();
+    if (!alt) continue;
+
+    applicableCount += 1;
+
+    // IMPORTANT: stop doing expensive occurrence building after we hit the cap
+    if (collectedCount >= MAX_OCCURRENCES) continue;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+    const baseOccurrence = {
+      summary: 'Review alt text on <img> for accuracy and appropriateness.',
+      hint: 'Ensure the alt text conveys the image’s purpose/information in context (not redundant, not filename-like).',
+      i18n: {
+        summaryKey: 'img_altQuality_summary_cantTell',
+        hintKey: 'img_altQuality_hint_cantTell',
+        params: { element: 'img' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: null
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
 
-    const truncated = applicableCount > collectedCount;
+    collectedCount += 1;
+  }
 
+  if (applicableCount === 0) {
     return {
-        ruleId: rule.ruleId,
-        outcome: 'cantTell',
-        severity: 'minor',
-        occurrences,
-        data: {
-            details: {
-                applicableCount,
-                reportedCount: collectedCount,
-                maxOccurrences: MAX_OCCURRENCES,
-                truncated
-            }
+      ruleId: rule.ruleId,
+      outcome: 'notApplicable',
+      severity: 'minor',
+      occurrences: [],
+      data: {
+        details: {
+          applicableCount: 0,
+          reportedCount: 0,
+          maxOccurrences: MAX_OCCURRENCES,
+          truncated: false
         }
+      }
     };
+  }
+
+  const truncated = applicableCount > collectedCount;
+
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: 'minor',
+    occurrences,
+    data: {
+      details: {
+        applicableCount,
+        reportedCount: collectedCount,
+        maxOccurrences: MAX_OCCURRENCES,
+        truncated
+      }
+    }
+  };
 }
 
 module.exports = { id, meta, runInPage };