@surea11y/core 1.0.0

package/src/checks/manual/form-control-programmatic-label-quality-manual.js

@@ -0,0 +1,291 @@
+'use strict';
+
+/**
+ * @check form-control-programmatic-label-quality
+ * @atomic true
+ * @summary Form controls should not rely on placeholder or title as the primary label
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to labelable native form controls exposed to assistive technologies:
+ *     - input (excluding type=hidden|submit|reset|button|image)
+ *     - select
+ *     - textarea
+ *   role="presentation"/"none" are excluded only when not focusable.
+ * @expectation
+ *   If a control has a programmatic name, it should not rely ONLY on:
+ *     - placeholder (non-empty)
+ *     - title (non-empty)
+ *   Prefer an associated <label> or aria-labelledby.
+ * @note
+ *   This is a quality/best-practice signal. Controls may still meet SC 4.1.2
+ *   while relying on placeholder/title; this rule surfaces that risk as cantTell.
+ */
+
+const id = 'form-control-programmatic-label-quality';
+
+const meta = {
+    title: 'Form controls should not rely on placeholder or title as the primary label',
+    description:
+        'Flags form controls whose computed accessible name relies on placeholder or title as the primary labeling method. Prefer <label> or aria-labelledby.',
+    i18n: {
+        titleKey: 'formControl_programmaticLabelQuality_title',
+        descriptionKey: 'formControl_programmaticLabelQuality_description'
+    },
+    helpUrl: null,
+    tags: ['wcag2a', 'wcag412', 'forms', 'labels', 'quality', 'atomic', 'manual'],
+    wcagSc: ['4.1.2'],
+    normativeMappings: [
+        { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    ],
+    defaultSeverity: 'moderate',
+    category: 'robust',
+    type: 'manual',
+    defaultConfidence: 'medium',
+    coverage: {
+        facetsBySc: {
+            '4.1.2': ['form-control-name-quality']
+        }
+    }
+};
+
+function runInPage(ctx) {
+    const { document, root, helpers, rule } = ctx;
+    const safeRoot = root || document;
+
+    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+
+    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+
+    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+    const getAriaLabelInfo = helpers && typeof helpers.getAriaLabelInfo === 'function' ? helpers.getAriaLabelInfo : null;
+    const getAriaLabelledByInfo = helpers && typeof helpers.getAriaLabelledByInfo === 'function' ? helpers.getAriaLabelledByInfo : null;
+
+    const getAttributeInfo = helpers && typeof helpers.getAttributeInfo === 'function' ? helpers.getAttributeInfo : null;
+
+    // Optional helper; we validate/normalize if present.
+    const getLabelMethod = helpers && typeof helpers.getLabelMethod === 'function' ? helpers.getLabelMethod : null;
+
+    const trim = (v) => (v == null ? '' : String(v)).trim();
+
+    const metrics = {
+        applicableCount: 0,
+        flaggedCount: 0,
+        byMethod: { label: 0, 'aria-labelledby': 0, 'aria-label': 0, title: 0, placeholder: 0, none: 0 }
+    };
+
+    function safeQueryAll(sel) {
+        try {
+            if (queryAllSmart) return Array.from(queryAllSmart(sel) || []);
+            return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : [];
+        } catch {
+            return [];
+        }
+    }
+
+    function isEligibleAcc(el) {
+        if (!isAccTreeEligible) return true;
+        try {
+            const r = isAccTreeEligible(el, ctx);
+            if (typeof r === 'boolean') return r;
+            return !!(r && r.eligible);
+        } catch {
+            return true;
+        }
+    }
+
+    function isFocusable(el) {
+        if (!getFocusableInfo) return false;
+        try {
+            const fi = getFocusableInfo(el, ctx);
+            return !!(fi && fi.focusable);
+        } catch {
+            return false;
+        }
+    }
+
+    function getNonEmptyAttr(el, name) {
+        if (!getAttributeInfo) return '';
+        try {
+            const info = getAttributeInfo(el, name);
+            return info && info.present ? trim(info.value) : '';
+        } catch {
+            return '';
+        }
+    }
+
+    function hasLabelAssociation(el) {
+        // 1) Native labels API
+        try {
+            if (el && 'labels' in el && el.labels && el.labels.length) return true;
+        } catch {}
+
+        // 2) Wrapped by <label>
+        try {
+            if (el && el.closest) {
+                const wrap = el.closest('label');
+                if (wrap) return true;
+            }
+        } catch {}
+
+        // 3) <label for="id">
+        try {
+            const idAttr = el && el.getAttribute ? trim(el.getAttribute('id')) : '';
+            if (!idAttr || !document || !document.querySelector) return false;
+
+            const esc = idAttr.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const sel = `label[for="${esc}"]`;
+            return !!document.querySelector(sel);
+        } catch {
+            return false;
+        }
+    }
+
+    function computeLabelMethodFallback(el) {
+        // Deterministic priority order:
+        // label > aria-labelledby > aria-label > title > placeholder
+        if (hasLabelAssociation(el)) return { method: 'label', value: '' };
+
+        if (getAriaLabelledByInfo) {
+            try {
+                const info = getAriaLabelledByInfo(el, ctx, { maxRefs: 8 });
+                const v = info && info.present ? trim(info.value) : '';
+                if (v) return { method: 'aria-labelledby', value: v };
+            } catch {}
+        }
+
+        if (getAriaLabelInfo) {
+            try {
+                const info = getAriaLabelInfo(el, ctx);
+                const v = info && info.present ? trim(info.value) : '';
+                if (v) return { method: 'aria-label', value: v };
+            } catch {}
+        }
+
+        const titleV = getNonEmptyAttr(el, 'title');
+        if (titleV) return { method: 'title', value: titleV };
+
+        const phV = getNonEmptyAttr(el, 'placeholder');
+        if (phV) return { method: 'placeholder', value: phV };
+
+        return { method: 'none', value: '' };
+    }
+
+    function getLabelMethodSafe(el) {
+        if (getLabelMethod) {
+            try {
+                const r = getLabelMethod(el, ctx);
+                const m = r && typeof r.method === 'string' ? r.method : 'none';
+                const v = r && r.value != null ? trim(r.value) : '';
+                if (!Object.prototype.hasOwnProperty.call(metrics.byMethod, m)) return { method: 'none', value: '' };
+                return { method: m, value: v };
+            } catch {
+                // fall through
+            }
+        }
+        return computeLabelMethodFallback(el);
+    }
+
+    // Native controls only (same as your current rule)
+    const selector =
+        'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
+
+    const nodes = safeQueryAll(selector);
+
+    if (!nodes.length) {
+        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
+    }
+
+    const occurrences = [];
+
+    for (const el of nodes) {
+        if (!el || !el.getAttribute) continue;
+
+        if (!isEligibleAcc(el)) continue;
+
+        const role = (() => {
+            try {
+                return trim(el.getAttribute('role')).toLowerCase();
+            } catch {
+                return '';
+            }
+        })();
+
+        let fi = null;
+        if (getFocusableInfo) {
+            try { fi = getFocusableInfo(el, ctx); } catch { fi = null; }
+        }
+        const tabbable = !!(fi && fi.tabbable);
+
+        if ((role === 'presentation' || role === 'none') && !tabbable) continue;
+
+        metrics.applicableCount += 1;
+
+        const label = getLabelMethodSafe(el);
+        const method = label && typeof label.method === 'string' ? label.method : 'none';
+        if (Object.prototype.hasOwnProperty.call(metrics.byMethod, method)) metrics.byMethod[method] += 1;
+        else metrics.byMethod.none += 1;
+
+        // Flag only when the *primary* (best) method is title/placeholder
+        const isWeakPrimary = method === 'title' || method === 'placeholder';
+        if (!isWeakPrimary) continue;
+
+        metrics.flaggedCount += 1;
+
+        const vf = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const reasonCode = method === 'title' ? 'label_from_title_primary' : 'label_from_placeholder_primary';
+        const methodLabel =
+            method === 'title' ? 'title'
+                : method === 'placeholder' ? 'placeholder'
+                    : 'title or placeholder';
+
+        const baseOccurrence = {
+            summary: 'Form control’s primary label is derived from title or placeholder.',
+            hint: 'Prefer a persistent <label> or aria-labelledby. Avoid relying on placeholder/title as the primary label.',
+            i18n: {
+                summaryKey: 'formControl_programmaticLabelQuality_summary_cantTell',
+                hintKey: 'formControl_programmaticLabelQuality_hint_cantTell',
+                params: { element: (el.tagName || '').toLowerCase(), method, methodLabel }
+            },
+            data: {
+                visibilityFilter: vf || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details: {
+                    reasonCode,
+                    labelMethod: method,
+                    labelStrength: 'weak',
+                    recommendedMethods: ['label', 'aria-labelledby'],
+                    sourceText: (label && label.value ? String(label.value).slice(0, 120) : '')
+                }
+            }
+        };
+
+        if (helpers && typeof helpers.reportOccurrence === 'function') {
+            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+        } else {
+            occurrences.push({ selector: '', html: '', ...baseOccurrence });
+        }
+    }
+
+    if (metrics.applicableCount === 0) {
+        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
+    }
+
+    if (occurrences.length) {
+        return {
+            ruleId: rule.ruleId,
+            outcome: 'cantTell',
+            severity: rule.defaultSeverity || 'minor',
+            occurrences,
+            data: { details: { metrics } }
+        };
+    }
+
+    // Manual rules may only emit cantTell/notApplicable (never pass/fail) —
+    // no applicable control relied on a weak (title/placeholder) primary
+    // label, so there is nothing to flag for review.
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/heading-order-manual.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * @check heading-order
+ * @atomic true
+ * @summary Heading levels must not skip a level going deeper
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies whenever the page contains two or more heading elements
+ *   (native <h1>-<h6>, or explicit role="heading" with aria-level —
+ *   default level 2 per the ARIA spec when aria-level is absent/invalid).
+ * @expectation
+ *   In document order, each heading's level is no more than one greater
+ *   than the highest heading level seen so far. Jumping deeper by more
+ *   than one level (e.g. an <h1> followed directly by an <h3>, skipping
+ *   <h2>) breaks the document outline assistive technology users rely on
+ *   when navigating by heading. Going back to a shallower level at any
+ *   point is always fine.
+ * @implementation-notes
+ * - 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.
+ * - Tracks the highest level reached so far (not just the immediately
+ *   previous heading's level), so a sequence like h1, h2, h3, h2, h4 is
+ *   correctly treated as valid (the h4 follows an h3 having already been
+ *   reached, even though the immediately preceding heading was h2).
+ */
+
+const id = 'heading-order';
+
+const meta = {
+  title: 'Heading levels must not skip a level',
+  description: 'Checks that heading levels increase by at most one at a time in document order.',
+  i18n: {
+    titleKey: 'headingOrder_title',
+    descriptionKey: 'headingOrder_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'headings', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getExplicitRoleToken(el) {
+    const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
+    if (!raw) return '';
+    return raw.split(/\s+/)[0].toLowerCase();
+  }
+
+  function getHeadingLevel(el) {
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) {
+      if (explicit !== 'heading') return 0;
+      const raw = normalizeWs(el.getAttribute && el.getAttribute('aria-level'));
+      const n = parseInt(raw, 10);
+      return (Number.isFinite(n) && n >= 1) ? n : 2;
+    }
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    const m = /^h([1-6])$/.exec(tag);
+    return m ? parseInt(m[1], 10) : 0;
+  }
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('h1, h2, h3, h4, h5, h6, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const headings = [];
+  const seen = new Set();
+  for (const el of nodes) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    const level = getHeadingLevel(el);
+    if (level > 0) headings.push({ el, level });
+  }
+
+  if (headings.length < 2) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let highestSoFar = headings[0].level;
+
+  for (let i = 1; i < headings.length; i += 1) {
+    const { el, level } = headings[i];
+
+    if (level > highestSoFar + 1) {
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: `This heading jumps from level ${highestSoFar} to level ${level}, skipping a level.`,
+        hint: 'Use consecutive heading levels (do not skip a level when going deeper) so the document outline stays predictable.',
+        i18n: {
+          summaryKey: 'headingOrder_summary_cantTell',
+          hintKey: 'headingOrder_hint_cantTell',
+          params: { fromLevel: String(highestSoFar), toLevel: String(level) }
+        },
+        data: {
+          details: { reasonCode: 'HEADING_ORDER_SKIPPED_LEVEL', fromLevel: highestSoFar, toLevel: level }
+        }
+      });
+    }
+
+    if (level > highestSoFar) highestSoFar = level;
+  }
+
+  if (occurrences.length) {
+    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 };

package/src/checks/manual/identical-links-same-purpose-manual.js

@@ -0,0 +1,142 @@
+'use strict';
+
+/**
+ * @check identical-links-same-purpose
+ * @atomic true
+ * @summary Links with the same accessible name should lead to the same destination
+ * @standard WCAG 2.2
+ * @sc 2.4.9
+ * @applicability
+ *   Any `a[href]` with a non-empty accessible name, grouped by that name
+ *   (trimmed, whitespace-collapsed, case-folded).
+ * @expectation
+ *   Within a page, links that share the same accessible name are expected
+ *   to serve the same purpose (i.e. resolve to the same destination — the
+ *   full resolved URL, including any fragment). Same-text-different-
+ *   destination links are common and frequently intentional in real
+ *   sites (e.g. repeated "Read more" links per article card), so this is
+ *   authored as `type: 'manual'` (cantTell-capped, never fail) rather
+ *   than a hard fail — flagging a real name/destination mismatch for
+ *   human judgment instead of guessing intent.
+ * @implementation-notes
+ * - Destination comparison uses the DOM `.href` property (already
+ *   resolved to an absolute URL by the engine/browser), not the raw
+ *   `href` attribute — so relative vs. absolute forms of the same target
+ *   are correctly treated as identical.
+ * - Only flags when a name group actually contains more than one
+ *   distinct destination; a name reused for links that all point to the
+ *   same place is not flagged.
+ */
+
+const id = 'identical-links-same-purpose';
+
+const meta = {
+  title: 'Links with the same accessible name should lead to the same destination',
+  description:
+    'Flags groups of links that share the same accessible name but resolve to more than one distinct destination, for manual review of whether they serve the same purpose.',
+  i18n: {
+    titleKey: 'identicalLinksSamePurpose_title',
+    descriptionKey: 'identicalLinksSamePurpose_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2aaa', 'wcag249', 'navigation', 'atomic', 'manual'],
+  wcagSc: ['2.4.9'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.4.9', title: 'Link Purpose (Link Only)', conformanceLevel: 'AAA' }
+  ],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'low',
+  coverage: { facetsBySc: { '2.4.9': ['identical-links-same-purpose-evidence'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function normName(s) {
+    return (s == null ? '' : String(s)).replace(/\s+/g, ' ').trim().toLowerCase();
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]', safeRoot) : helpers.queryAll('a[href]', safeRoot);
+
+  const groups = new Map(); // normName -> [{ el, href }]
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    const eligible = typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    if (!eligible) continue;
+
+    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
+    const rawName = (nameInfo && typeof nameInfo.value === 'string' && nameInfo.value.trim())
+      ? nameInfo.value
+      : (el.textContent || '');
+    const name = normName(rawName);
+    if (!name) continue;
+
+    let href = '';
+    try { href = String(el.href || ''); } catch { href = ''; }
+    if (!href) continue;
+
+    applicableCount += 1;
+
+    if (!groups.has(name)) groups.set(name, []);
+    groups.get(name).push({ el, href });
+  }
+
+  const occurrences = [];
+
+  for (const [name, entries] of groups) {
+    const distinctHrefs = new Set(entries.map((e) => e.href));
+    if (distinctHrefs.size <= 1) continue;
+
+    for (const { el, href } of entries) {
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+      const baseOccurrence = {
+        selector: stableSelector,
+        html,
+        summary: 'This link shares an accessible name with other links on the page that lead to a different destination.',
+        hint: 'Ensure links with the same text serve the same purpose, or make the link text distinct enough to describe each destination.',
+        i18n: {
+          summaryKey: 'identicalLinksSamePurpose_summary_cantTell',
+          hintKey: 'identicalLinksSamePurpose_hint_cantTell',
+          params: { name, destinationCount: String(distinctHrefs.size) }
+        },
+        data: {
+          details: {
+            reasonCode: 'SAME_NAME_DIFFERENT_DESTINATION',
+            name,
+            href,
+            distinctDestinationCount: distinctHrefs.size
+          }
+        }
+      };
+
+      if (helpers && typeof helpers.reportOccurrence === 'function') {
+        occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+      } else {
+        occurrences.push(baseOccurrence);
+      }
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+
+  // Manual rules may only emit cantTell/notApplicable (never pass/fail):
+  // every name group already resolves to a single shared destination.
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * @check image-redundant-alt
+ * @atomic true
+ * @summary An image's alt text must not duplicate adjacent visible text
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to <img> elements with non-empty alt text whose immediate
+ *   parent element also has other visible text content (i.e. text nodes
+ *   besides the image itself — commonly an <a> or <button> wrapping both
+ *   an icon image and a text label).
+ * @expectation
+ *   The image's alt text is not the same (case-insensitive, normalized)
+ *   as the other visible text already in the same parent. When both are
+ *   present, assistive technology announces the same words twice for a
+ *   single control (e.g. an icon-plus-text link where the icon's alt
+ *   duplicates the link text).
+ * @implementation-notes
+ * - 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.
+ * - Deliberately scoped to the immediate parent only (not the whole
+ *   ancestor chain or arbitrary siblings), to keep the "redundant"
+ *   judgment high-confidence and avoid false positives from unrelated
+ *   text elsewhere on the page that coincidentally matches.
+ */
+
+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.',
+  i18n: {
+    titleKey: 'imageRedundantAlt_title',
+    descriptionKey: 'imageRedundantAlt_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'images', 'nontext', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getOwnTextExcludingImg(parent, imgEl) {
+    let text = '';
+    for (const child of parent.childNodes || []) {
+      if (child === imgEl) continue;
+      if (child.nodeType === 3) {
+        text += ' ' + (child.nodeValue || '');
+      } else if (child.nodeType === 1 && child !== imgEl) {
+        text += ' ' + (child.textContent || '');
+      }
+    }
+    return normalizeWs(text);
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img[alt]', safeRoot) : helpers.queryAll('img[alt]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const alt = normalizeWs(el.getAttribute('alt'));
+    if (!alt) continue;
+
+    const parent = el.parentElement;
+    if (!parent) continue;
+
+    const otherText = getOwnTextExcludingImg(parent, el);
+    if (!otherText) continue;
+
+    applicableCount += 1;
+
+    if (otherText.toLowerCase() !== alt.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 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',
+        hintKey: 'imageRedundantAlt_hint_cantTell',
+        params: { alt }
+      },
+      data: {
+        details: { reasonCode: 'IMAGE_ALT_REDUNDANT', alt }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    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: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };