@surea11y/core 1.6.0 → 1.7.0

package/src/checks/automatic/link-in-text-block.js

@@ -31,13 +31,13 @@
  *   of the actual adjacent text node(s), a deliberate scope-down, since
  *   plain text nodes inherit their rendering from the parent in the
  *   overwhelming majority of real markup.
- * - When contrast is not confidently computable (background image/
- *   gradient, blend mode, filter, non-opaque ancestor, same blockers
- *   `contrast-minimum`/`contrast-computable` use), the link is silently
- *   skipped rather than flagged or reported as cantTell, to keep `fail`
- *   reserved for deterministic, high-confidence violations. This means
- *   the rule never emits cantTell, outcome is notApplicable/pass/fail
- *   only, matching this repo's other Tier 2 mechanical rules.
+ * - A candidate that cannot be evaluated reports cantTell, not pass:
+ *   contrast not confidently computable (the blockers `contrast-minimum`/
+ *   `contrast-computable` use), or `text-decoration` unreadable in both
+ *   the computed style and the CSSOM (see `decorationInfo`). `fail` stays
+ *   reserved for deterministic violations; this is the computability gate
+ *   RULE_TAXONOMY.md §1.1 allows automatic rules, as in `contrast-minimum`
+ *   and `target-size-minimum`.
  * - Reuses the shared `helpers.contrast` subsystem (same
  *   computeEffectiveForeground/Background, getComputabilityBlocker,
  *   contrastRatio helpers as `contrast-minimum`), rather than re-deriving
@@ -103,14 +103,176 @@ function runInPage(ctx) {
     return null;
   }
 
-  function decorationTokens(cs) {
-    const raw =
-      `${(cs && cs.textDecorationLine) || ''} ${(cs && cs.textDecoration) || ''}`.toLowerCase();
-    return raw.split(/\s+/).filter(Boolean);
+  // Whether the element is underlined, and whether the computed style can be
+  // trusted to say so. A conforming CSSOM serialises the `text-decoration`
+  // shorthand with the line value first, so it and `text-decoration-line`
+  // always agree on whether `underline` is present. jsdom does not cascade
+  // the property at all: the shorthand reads back as the UA's "underline"
+  // for every <a> whatever the author CSS says, and the longhand as "none"
+  // unless the author used the longhand. Either one taken alone is wrong in
+  // one direction, so disagreement is the signal to stop trusting both.
+  function decorationInfo(cs) {
+    if (!cs) return { underlined: false, trustworthy: false };
+
+    const lineRaw = String(cs.textDecorationLine || '')
+      .trim()
+      .toLowerCase();
+    const shortRaw = String(cs.textDecoration || '')
+      .trim()
+      .toLowerCase();
+
+    const lineTokens = lineRaw.split(/\s+/).filter(Boolean);
+    const shortTokens = shortRaw.split(/\s+/).filter(Boolean);
+
+    // Only one of the two exposed: nothing to cross-check against, take it.
+    if (!lineTokens.length) {
+      return { underlined: shortTokens.includes('underline'), trustworthy: shortTokens.length > 0 };
+    }
+    if (!shortTokens.length) {
+      return { underlined: lineTokens.includes('underline'), trustworthy: true };
+    }
+
+    const byLine = lineTokens.includes('underline');
+    const byShort = shortTokens.includes('underline');
+    return { underlined: byLine, trustworthy: byLine === byShort };
+  }
+
+  // Resolves `text-decoration` from the author stylesheets when the computed
+  // style is untrustworthy, reading the CSSOM as `css-orientation-lock` and
+  // `css-focus-indicator-suppressed` do. Without it the rule could not decide
+  // anything under a DOM emulator, which is how the CLI scans static HTML.
+  //
+  // A narrow cascade is enough: `text-decoration-line` is not inherited, so
+  // only declarations matching the element itself and its inline style apply,
+  // ordered by specificity. With no author declaration the UA default stands,
+  // and for a link that is an underline. Anything that would make the answer a
+  // guess yields `resolved: false` and the caller reports cantTell.
+  const CSS_STYLE_RULE = 1;
+  const MAX_NESTED_DEPTH = 8;
+
+  function splitSelectorList(selectorText) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(selectorText || '')) {
+      if (ch === '(') depth += 1;
+      if (ch === ')') depth = Math.max(0, depth - 1);
+      if (ch === ',' && depth === 0) {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      current += ch;
+    }
+    parts.push(current);
+    return parts.map((p) => p.trim()).filter(Boolean);
   }
 
-  function hasUnderline(cs) {
-    return decorationTokens(cs).includes('underline');
+  // Approximate CSS specificity as a single sortable integer. Exactness is
+  // not required: this only orders declarations of one property against each
+  // other, and near-ties are broken by document order as the cascade does.
+  function specificityOf(selector) {
+    const s = String(selector || '');
+    const ids = (s.match(/#[\w-]+/g) || []).length;
+    const classesEtc = (s.match(/\.[\w-]+|\[[^\]]*\]|:(?!:)[\w-]+/g) || []).length;
+    const types = (s.match(/(^|[\s>+~])[a-z][\w-]*/gi) || []).length;
+    return ids * 10000 + classesEtc * 100 + types;
+  }
+
+  // A declaration wins if it is the last one, in (specificity, order), whose
+  // selector matches. `!important` outranks everything non-important.
+  function underlineFromDeclaration(style) {
+    if (!style || typeof style.getPropertyValue !== 'function') return null;
+    for (const prop of ['text-decoration-line', 'text-decoration']) {
+      const raw = String(style.getPropertyValue(prop) || '')
+        .trim()
+        .toLowerCase();
+      if (!raw) continue;
+      const important = String(style.getPropertyPriority(prop) || '') === 'important';
+      return { underlined: /\bunderline\b/.test(raw), important };
+    }
+    return null;
+  }
+
+  function resolveUnderlineFromCssom(el) {
+    const doc = el && el.ownerDocument ? el.ownerDocument : null;
+    if (!doc || typeof el.matches !== 'function') return { underlined: false, resolved: false };
+
+    let best = null; // { rank, order, underlined }
+    let order = 0;
+    let unreadableSheet = false;
+    let unparsableSelector = false;
+
+    function consider(cssRule) {
+      const decl = underlineFromDeclaration(cssRule.style);
+      if (!decl) return;
+      for (const part of splitSelectorList(cssRule.selectorText)) {
+        // A pseudo-element rule paints a box other than the link's own text.
+        if (/::[a-z-]+/i.test(part)) continue;
+        // A state the static DOM is not in (:hover/:focus/...) does not
+        // describe the link's resting appearance, which is what this rule is
+        // about.
+        if (/:(hover|focus|focus-visible|focus-within|active|target|visited)\b/i.test(part)) {
+          continue;
+        }
+        let matched;
+        try {
+          matched = el.matches(part);
+        } catch {
+          unparsableSelector = true;
+          continue;
+        }
+        if (!matched) continue;
+        order += 1;
+        const rank = (decl.important ? 1e9 : 0) + specificityOf(part);
+        if (!best || rank >= best.rank) best = { rank, order, underlined: decl.underlined };
+      }
+    }
+
+    function walk(rules, depth) {
+      if (!rules || depth > MAX_NESTED_DEPTH) return;
+      for (const cssRule of rules) {
+        if (!cssRule) continue;
+        if (cssRule.type === CSS_STYLE_RULE && cssRule.selectorText) {
+          consider(cssRule);
+          continue;
+        }
+        let nested;
+        try {
+          nested = cssRule.cssRules || null;
+        } catch {
+          nested = null;
+        }
+        if (nested) walk(nested, depth + 1);
+      }
+    }
+
+    try {
+      for (const sheet of doc.styleSheets || []) {
+        let rules = null;
+        try {
+          rules = sheet && sheet.cssRules ? sheet.cssRules : null;
+        } catch {
+          unreadableSheet = true; // cross-origin, not inspectable
+          continue;
+        }
+        if (rules) walk(rules, 0);
+      }
+    } catch {
+      return { underlined: false, resolved: false };
+    }
+
+    // The inline style attribute outranks every stylesheet declaration.
+    const inline = underlineFromDeclaration(el.style);
+    if (inline) return { underlined: inline.underlined, resolved: true };
+
+    if (best) return { underlined: best.underlined, resolved: true };
+
+    // No author declaration reached this element. If a sheet or selector was
+    // unreadable, one of them might have, so the answer is unknown; otherwise
+    // the UA default stands, and for a link that means underlined.
+    if (unreadableSheet || unparsableSelector) return { underlined: false, resolved: false };
+    return { underlined: true, resolved: true };
   }
 
   function hasSurroundingText(el, parent) {
@@ -141,7 +303,15 @@ function runInPage(ctx) {
     : helpers.queryAll(selector);
 
   const occurrences = [];
+  const undecided = [];
   let applicableCount = 0;
+  let decidedCount = 0;
+
+  // Applicable, but not evaluable. Held separately so the outcome below can
+  // tell "checked and sound" apart from "never decided".
+  function markUndecided(el, reasonCode) {
+    undecided.push({ el, reasonCode });
+  }
 
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
@@ -159,27 +329,40 @@ function runInPage(ctx) {
     const linkCs = safeComputedStyle(el);
     const parentCs = safeComputedStyle(parent);
 
-    if (hasUnderline(linkCs)) continue;
-
+    // Cues that do not depend on `text-decoration` come first, so a link
+    // carrying one is decided even where decoration is unreadable.
     const linkWeight = c && linkCs ? c.normalizeFontWeight(linkCs.fontWeight) : 400;
     const parentWeight = c && parentCs ? c.normalizeFontWeight(parentCs.fontWeight) : 400;
-    if (linkWeight !== parentWeight) continue;
+    if (linkWeight !== parentWeight) {
+      decidedCount += 1;
+      continue;
+    }
 
     const linkStyle = (linkCs && linkCs.fontStyle) || 'normal';
     const parentStyle = (parentCs && parentCs.fontStyle) || 'normal';
-    if (linkStyle !== parentStyle) continue;
+    if (linkStyle !== parentStyle) {
+      decidedCount += 1;
+      continue;
+    }
 
-    if (!c) continue;
+    if (!c) {
+      markUndecided(el, 'CONTRAST_HELPERS_UNAVAILABLE');
+      continue;
+    }
 
     let flagged = false;
+    let computed = false;
     let ratio = null;
     let fgLinkHex = '';
     let fgParentHex = '';
+    let undecidedReason = 'COLOR_NOT_COMPUTABLE';
 
     try {
       const blocker = c.getComputabilityBlocker(el);
       if (blocker && blocker.ok === false) {
-        // Not confidently computable, skip (benefit of the doubt).
+        // Not confidently computable: recorded below rather than skipped, so
+        // it cannot be mistaken for a clean result.
+        if (blocker.reasonCode) undecidedReason = String(blocker.reasonCode);
       } else {
         const bg = c.computeEffectiveBackground(el, {
           contrast: { mode, rootCanvasFallback },
@@ -202,15 +385,49 @@ function runInPage(ctx) {
           fgLinkHex = c.rgbToHex ? c.rgbToHex(fgLinkOpaque) : '';
           fgParentHex = c.rgbToHex ? c.rgbToHex(fgParentOpaque) : '';
 
+          computed = true;
           if (!(ratio >= 3)) flagged = true;
         }
-        // else: not confidently computable, skip.
+        // else: not confidently computable, recorded below.
       }
     } catch {
-      // no-throw: treat as not computable, skip.
+      // No-throw: treat as not computable and record it.
+      undecidedReason = 'ENGINE_EXCEPTION';
+    }
+
+    if (!computed) {
+      markUndecided(el, undecidedReason);
+      continue;
+    }
+
+    // Contrast alone is an accepted alternative to an underline (G183), so a
+    // link clearing 3:1 is distinguishable regardless of decoration.
+    if (!flagged) {
+      decidedCount += 1;
+      continue;
+    }
+
+    // Below 3:1, an underline is the last remaining cue -- and only now does
+    // it matter whether this environment can actually report one.
+    const decoration = decorationInfo(linkCs);
+    let underlined;
+    if (decoration.trustworthy) {
+      underlined = decoration.underlined;
+    } else {
+      const fromCssom = resolveUnderlineFromCssom(el);
+      if (!fromCssom.resolved) {
+        markUndecided(el, 'TEXT_DECORATION_NOT_RESOLVABLE');
+        continue;
+      }
+      underlined = fromCssom.underlined;
+    }
+
+    if (underlined) {
+      decidedCount += 1;
+      continue;
     }
 
-    if (!flagged) continue;
+    decidedCount += 1;
 
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
@@ -243,6 +460,9 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
+
+  // A proven violation outranks an undecided candidate, which outranks a clean
+  // one. The middle step keeps an unevaluable link out of `pass`.
   if (occurrences.length) {
     return {
       ruleId: rule.ruleId,
@@ -251,7 +471,43 @@ function runInPage(ctx) {
       occurrences
     };
   }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  if (undecided.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'serious',
+      confidence: 'low',
+      occurrences: undecided.map(({ el, reasonCode }) =>
+        helpers.reportOccurrence(el, {
+          summary:
+            'Whether this link is distinguishable from the surrounding text by non-color means could not be determined.',
+          hint: 'Confirm by eye that the link carries an underline, a font-weight or font-style difference, or at least 3:1 contrast against the surrounding text. Running the engine in a real browser rather than a DOM emulator resolves most cases automatically.',
+          i18n: {
+            summaryKey: 'linkInTextBlock_summary_cantTell',
+            hintKey: 'linkInTextBlock_hint_cantTell'
+          },
+          uncertainty: {
+            code: 'not-computable',
+            needed:
+              'Whether the link carries an underline, weight or style difference, or 3:1 contrast against its surrounding text.',
+            evidence: { reasonCode }
+          },
+          data: {
+            visibilityFilter: helpers.getEligibilityInfo
+              ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+              : { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode }
+          }
+        })
+      )
+    };
+  }
+
+  if (decidedCount > 0) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/target-size-minimum.js

@@ -293,14 +293,29 @@ function runInPage(ctx) {
     }
   }
 
+  // Per-run memoization: getComputedStyle is a real, non-trivial cost in an
+  // actual browser (unlike jsdom, which no-ops it), and hasSpacingConflict
+  // below calls getStyle on the SAME candidate element repeatedly -- once
+  // per undersized target it's compared against, via
+  // isInlineTextExceptionTarget/isInlineLinkTarget -- so with U undersized
+  // targets and N total candidates this was an uncached O(U * N)
+  // getComputedStyle call count. The DOM is read-only for the rest of this
+  // rule's run (no writes between reads), so caching per element here is
+  // safe -- style cannot change mid-run.
+  const __styleCache = new WeakMap();
   function getStyle(el) {
+    if (__styleCache.has(el)) return __styleCache.get(el);
+    let cs;
     try {
-      return document && document.defaultView && document.defaultView.getComputedStyle
-        ? document.defaultView.getComputedStyle(el)
-        : null;
+      cs =
+        document && document.defaultView && document.defaultView.getComputedStyle
+          ? document.defaultView.getComputedStyle(el)
+          : null;
     } catch {
-      return null;
+      cs = null;
     }
+    __styleCache.set(el, cs);
+    return cs;
   }
 
   function isPointerReachable(el) {
@@ -431,6 +446,46 @@ function runInPage(ctx) {
 
   const undersized = items.filter((it) => it.rect.width < MIN || it.rect.height < MIN);
 
+  // Spatial grid over ALL items, cell size = MIN (24px), so hasSpacingConflict's
+  // proximity check below doesn't have to compare every undersized target
+  // against every other item -- an O(items^2) cost that dominates real-browser
+  // (not jsdom -- see this rule's own perf note further down) runtime on a
+  // page with many small targets. A point can only be within MIN of another
+  // point that shares its grid cell or one of the 8 adjacent cells: cell size
+  // equals the search radius, so two points in cells 2+ apart on either axis
+  // are, on that axis alone, already >= MIN apart. Restricting the candidate
+  // set to that 3x3 neighborhood is therefore never a false negative -- the
+  // exact same dist() < MIN check still runs on every candidate it returns,
+  // just skipping candidates that are geometrically guaranteed too far away.
+  // This changes performance only, never which targets conflict.
+  const grid = new Map(); // "cx,cy" -> item[]
+  function cellKeyFor(cx, cy) {
+    return cx + ',' + cy;
+  }
+  for (const it of items) {
+    const cx = Math.floor(it.center.cx / MIN);
+    const cy = Math.floor(it.center.cy / MIN);
+    const key = cellKeyFor(cx, cy);
+    let bucket = grid.get(key);
+    if (!bucket) {
+      bucket = [];
+      grid.set(key, bucket);
+    }
+    bucket.push(it);
+  }
+  function nearbyItems(center) {
+    const cx = Math.floor(center.cx / MIN);
+    const cy = Math.floor(center.cy / MIN);
+    const out = [];
+    for (let dx = -1; dx <= 1; dx++) {
+      for (let dy = -1; dy <= 1; dy++) {
+        const bucket = grid.get(cellKeyFor(cx + dx, cy + dy));
+        if (bucket) for (const it of bucket) out.push(it);
+      }
+    }
+    return out;
+  }
+
   // --- spacing/occlusion evaluation ---
   function hasSpacingConflict(target) {
     // 0) Pure geometry: deterministic center-distance check against ANY
@@ -438,7 +493,7 @@ function runInPage(ctx) {
     // spacing exception depends on proximity to any adjacent target, so an
     // undersized target sitting flush against an adequately-sized one still
     // fails the exception, which an undersized-only comparison would miss.
-    for (const other of items) {
+    for (const other of nearbyItems(target.center)) {
       if (!other || !other.el || isRelated(target.el, other.el)) continue;
 
       // Ignore inline-text exception targets when evaluating spacing conflicts.
@@ -614,6 +669,14 @@ function runInPage(ctx) {
             hintKey: 'targetSizeMinimum_hint_cantTell_ambiguousSpacing',
             params: {}
           },
+          uncertainty: {
+            code: 'not-computable',
+            needed: 'A reliable measurement of the spacing between this target and its neighbour.',
+            evidence: {
+              measured: { width: it.rect.width, height: it.rect.height },
+              conflictHitCount: info.hitCount
+            }
+          },
           data: {
             details: {
               measured: { width: it.rect.width, height: it.rect.height },
@@ -643,6 +706,14 @@ function runInPage(ctx) {
               hintKey: 'targetSizeMinimum_hint_cantTell_plausiblyEssential',
               params: {}
             },
+            uncertainty: {
+              code: 'judgement-required',
+              needed: 'Whether this target’s size is essential, which WCAG exempts.',
+              evidence: {
+                measured: { width: it.rect.width, height: it.rect.height },
+                conflictHitCount: info.hitCount
+              }
+            },
             data: {
               details: {
                 measured: { width: it.rect.width, height: it.rect.height },
@@ -671,6 +742,14 @@ function runInPage(ctx) {
               hintKey: 'targetSizeMinimum_hint_cantTell_inlineLinkRun',
               params: {}
             },
+            uncertainty: {
+              code: 'judgement-required',
+              needed: 'Whether this target is a link in a sentence, which WCAG exempts.',
+              evidence: {
+                measured: { width: it.rect.width, height: it.rect.height },
+                conflictHitCount: info.hitCount
+              }
+            },
             data: {
               details: {
                 measured: { width: it.rect.width, height: it.rect.height },

package/src/checks/automatic/td-has-header.js

@@ -118,27 +118,28 @@ function runInPage(ctx) {
       return !!(cell && cell.tagName && cell.tagName.toLowerCase() === 'th' && isEligible(cell));
     }
 
-    function hasColumnHeaderAbove(r, c) {
-      for (let ri = 0; ri < r; ri++) {
-        const cell = rowCells[ri] && rowCells[ri][c];
-        if (isHeaderCell(cell)) return true;
-      }
-      return false;
-    }
-
-    function hasRowHeaderBefore(r, c) {
-      const cells = rowCells[r] || [];
-      for (let ci = 0; ci < c; ci++) {
-        if (isHeaderCell(cells[ci])) return true;
-      }
-      return false;
-    }
+    // "Was there a <th> above this cell's column" and "was there a <th>
+    // earlier in this cell's row" are both prefix questions over a scan
+    // already in progress (rows top to bottom, cells left to right within a
+    // row), so each is tracked incrementally instead of rescanning the
+    // rows/columns already passed for every cell: colHasHeaderAbove[c]
+    // carries forward across rows, rowHasHeaderBefore resets at the start
+    // of each row. One pass over every cell, not one rescan per cell.
+    const colHasHeaderAbove = new Array(maxCols).fill(false);
 
     for (let r = 0; r < rowCells.length; r++) {
       const cells = rowCells[r];
+      let rowHasHeaderBefore = false;
+
       for (let c = 0; c < cells.length; c++) {
         const cell = cells[c];
-        if (!cell || isHeaderCell(cell)) continue;
+        if (!cell) continue;
+
+        if (isHeaderCell(cell)) {
+          colHasHeaderAbove[c] = true;
+          rowHasHeaderBefore = true;
+          continue;
+        }
 
         // An aria-hidden data cell isn't exposed to AT either, so it has
         // no need for an accessible header association.
@@ -147,8 +148,8 @@ function runInPage(ctx) {
         const headersAttr = trim(cell.getAttribute('headers'));
         if (headersAttr) continue;
 
-        if (hasColumnHeaderAbove(r, c)) continue;
-        if (hasRowHeaderBefore(r, c)) continue;
+        if (colHasHeaderAbove[c]) continue;
+        if (rowHasHeaderBefore) continue;
 
         occurrences.push(
           helpers.reportOccurrence(cell, {