@surea11y/core 1.6.0 → 1.7.0

package/src/checks/automatic/css-orientation-lock.js

@@ -240,6 +240,7 @@ function runInPage(ctx) {
 
   const findings = [];
   let sheetCount = 0;
+  let unreadableSheetCount = 0;
 
   try {
     const sheets = document.styleSheets || [];
@@ -248,7 +249,10 @@ function runInPage(ctx) {
       try {
         rules = sheet && sheet.cssRules ? sheet.cssRules : null;
       } catch {
-        continue; // cross-origin stylesheet, not inspectable
+        // Cross-origin, not inspectable. Counted, since a lock could be
+        // declared there and a `pass` would claim more than was checked.
+        unreadableSheetCount += 1;
+        continue;
       }
       if (!rules) continue;
       sheetCount += 1;
@@ -264,15 +268,48 @@ function runInPage(ctx) {
     // no-throw: treat as no accessible stylesheets
   }
 
-  if (sheetCount === 0) {
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
-  }
+  const scanTarget = document.documentElement || document.body || null;
 
+  // A lock found in a readable sheet is still a lock, so `fail` outranks the
+  // uncertainty below.
   if (!findings.length) {
+    if (unreadableSheetCount > 0) {
+      return {
+        ruleId: rule.ruleId,
+        outcome: 'cantTell',
+        severity: rule.defaultSeverity || 'serious',
+        confidence: 'low',
+        occurrences: [
+          helpers.reportOccurrence(scanTarget, {
+            summary: `${unreadableSheetCount} stylesheet(s) could not be read, so whether this page locks its orientation could not be determined.`,
+            hint: 'Cross-origin stylesheets are not inspectable from the page. Check any third-party CSS for an orientation media query containing a rotate() transform, or re-run the scan with those stylesheets served same-origin.',
+            i18n: {
+              summaryKey: 'cssOrientationLock_summary_cantTell_unreadableSheets',
+              hintKey: 'cssOrientationLock_hint_cantTell_unreadableSheets',
+              params: { count: String(unreadableSheetCount) }
+            },
+            uncertainty: {
+              code: 'not-computable',
+              needed: 'The contents of the stylesheets this scan could not read.',
+              evidence: { unreadableSheetCount, reasonCode: 'STYLESHEETS_NOT_READABLE' }
+            },
+            data: {
+              details: {
+                reasonCode: 'STYLESHEETS_NOT_READABLE',
+                unreadableSheetCount
+              }
+            }
+          })
+        ]
+      };
+    }
+    if (sheetCount === 0) {
+      return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const target = document.documentElement || document.body || null;
+  const target = scanTarget;
   const occurrences = findings.map((f) =>
     helpers.reportOccurrence(target, {
       summary: f.selectorText

package/src/checks/automatic/duplicate-id-aria.js

@@ -128,6 +128,11 @@ function runInPage(ctx) {
             hintKey: 'duplicateIdAria_hint_cantTell',
             params: { id: refId, duplicateCount: String(els.length) }
           },
+          uncertainty: {
+            code: 'judgement-required',
+            needed: 'Whether the first element carrying this id is the intended target.',
+            evidence: { id: refId, duplicateCount: els.length, resolvesTo: 'first' }
+          },
           data: {
             details: {
               reasonCode: 'DUPLICATE_ID_ARIA_REFERENCED',

package/src/checks/automatic/duplicate-id.js

@@ -19,14 +19,19 @@
  *   two different shadow roots is not a duplicate.
  * @implementation-notes
  * - WCAG-VERSION SCOPED. SC 4.1.1 Parsing was removed in WCAG 2.2, so this
- *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`. A
- *   consumer targeting WCAG 2.2 excludes it with
- *   `excludeTags: ['wcag22-removed']`; one targeting 2.0 or 2.1 keeps it
- *   and gets a real 4.1.1 result. The alternative, dropping the SC
- *   mapping entirely, would have made a genuine 2.0/2.1 failure
- *   invisible to anyone conformance-testing against those versions. See
- *   `docs/ENGINE_OPTIONS.md` for the tag, and `docs/DESIGN_CHALLENGES.md`
- *   for the decision this reverses.
+ *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`.
+ *   The engine acts on that tag itself: under a 2.2 target, which is the
+ *   default, this rule still runs and still reports every duplicate it
+ *   finds, but its fail is coerced to `cantTell` with a `wcagVersionScope`
+ *   field saying why (see scopeOutcomeToWcagVersion in
+ *   `src/core/dom-runner.js`). A consumer targeting 2.0 or 2.1
+ *   (`engineOptions.wcagVersion`, or a tag set that implies it) gets the
+ *   real 4.1.1 failure; one that would rather not see the rule at all
+ *   under 2.2 still excludes it with `excludeTags: ['wcag22-removed']`.
+ *   The alternative, dropping the SC mapping entirely, would have made a
+ *   genuine 2.0/2.1 failure invisible to anyone conformance-testing
+ *   against those versions. See `docs/ENGINE_OPTIONS.md` for the option
+ *   and the tag, and `docs/DESIGN_CHALLENGES.md` for the decision history.
  * - The defect outlives its Success Criterion: a duplicate id breaks
  *   `<label for>` association, fragment navigation, `getElementById`, and
  *   every ID-reference attribute, none of which stopped mattering when

package/src/checks/automatic/form-control-single-label.js

@@ -173,6 +173,15 @@ function runInPage(ctx) {
             hintKey: 'formControlSingleLabel_hint_cantTell',
             params: { element: tag, labelCount: String(eligibleLabels.size) }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed: 'Whether the empty label is filled in at runtime or is simply redundant.',
+            evidence: {
+              element: tag,
+              labelCount: eligibleLabels.size,
+              contributingLabelCount: contributing.length
+            }
+          },
           data: {
             details: {
               reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',

package/src/checks/automatic/identical-iframes-same-purpose.js

@@ -0,0 +1,229 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check identical-iframes-same-purpose
+ * @atomic true
+ * @summary Frames sharing an accessible name must embed the same resource
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to each set of two or more <iframe>/<frame> elements that are
+ *   included in the accessibility tree and share the same non-empty
+ *   accessible name, compared with whitespace collapsed. A frame named
+ *   only by a mechanism that names nothing, or hidden from the
+ *   accessibility tree, is not part of a set; a set needs two surviving
+ *   members to exist at all.
+ * @expectation
+ *   Every frame in a set resolves to the same resource. A shared name
+ *   describes one resource, so two frames answering to it must embed the
+ *   same one.
+ * @implementation-notes
+ * - Distinct from iframe-title-unique, which asks the stricter question of
+ *   whether the title ATTRIBUTE repeats at all, and answers it from static
+ *   markup. This rule keys on the computed accessible name and judges the
+ *   resource behind it.
+ * - src values are compared as resolved absolute URLs with the fragment
+ *   removed and a trailing slash normalised away, so a directory written
+ *   both with and without one is a single resource.
+ * - Frames that resolve to different URLs are reported cantTell, never
+ *   fail. Different resources can still be equivalent — differently worded
+ *   copies of one page, or two adverts serving the same purpose — and
+ *   nothing in the markup settles it. Comparing the embedded documents
+ *   would not settle it either, since content differing is exactly what
+ *   those equivalent cases look like.
+ */
+
+const id = 'identical-iframes-same-purpose';
+
+const meta = {
+  title: 'Frames with the same name embed the same resource',
+  description:
+    'Checks that <iframe>/<frame> elements sharing an accessible name embed the same resource, since one name can only describe one resource.',
+  i18n: {
+    titleKey: 'identicalIframesSamePurpose_title',
+    descriptionKey: 'identicalIframesSamePurpose_description'
+  },
+  helpUrl: null,
+  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'
+    }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '4.1.2': ['identical-iframes-same-purpose'] } }
+};
+
+function runInPage(ctx) {
+  const { helpers, rule } = ctx;
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('iframe, frame')
+    : helpers.queryAll('iframe, frame');
+
+  function normalizedName(el) {
+    if (!helpers.getAccessibleNameInfo) return '';
+    let info;
+    try {
+      info = helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 });
+    } catch {
+      return '';
+    }
+    if (!info || !info.present || !info.value) return '';
+    return String(info.value).replace(/\s+/g, ' ').trim();
+  }
+
+  // A light-DOM child of a shadow host with no slot to land in is absent from
+  // the flat tree and so renders nowhere, which the shared eligibility helper
+  // does not model.
+  function isUnslotted(el) {
+    try {
+      let cur = el;
+      let guard = 0;
+      while (cur && cur.nodeType === 1 && guard++ < 100) {
+        const parent = cur.parentNode;
+        if (!parent || parent.nodeType !== 1) return false;
+        if (parent.shadowRoot && cur.assignedSlot == null) return true;
+        cur = parent;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  function inAccessibilityTree(el) {
+    if (isUnslotted(el)) return false;
+    if (!helpers.isIncludedInAccessibilityTree) return true;
+    try {
+      return !!helpers.isIncludedInAccessibilityTree(el);
+    } catch {
+      return false;
+    }
+  }
+
+  // A directory written with and without its trailing slash is one resource,
+  // and a fragment selects within a resource rather than naming another.
+  function resourceKey(el) {
+    let raw;
+    try {
+      raw = el.getAttribute('src');
+    } catch {
+      return null;
+    }
+    if (raw == null || !String(raw).trim()) return null;
+
+    const doc = (ctx && ctx.document) || (el.ownerDocument ? el.ownerDocument : null);
+    const base = doc && doc.baseURI ? doc.baseURI : undefined;
+    try {
+      const u = new URL(String(raw).trim(), base);
+      let pathname = u.pathname;
+      if (pathname.length > 1 && pathname.charAt(pathname.length - 1) === '/') {
+        pathname = pathname.slice(0, -1);
+      }
+      return u.protocol + '//' + u.host + pathname + u.search;
+    } catch {
+      return null;
+    }
+  }
+
+  const groups = new Map();
+
+  for (const el of nodes) {
+    if (!el || !el.tagName) continue;
+    if (!inAccessibilityTree(el)) continue;
+
+    const name = normalizedName(el);
+    if (!name) continue;
+
+    const list = groups.get(name);
+    if (list) list.push(el);
+    else groups.set(name, [el]);
+  }
+
+  const sets = [];
+  for (const [name, els] of groups) {
+    if (els.length >= 2) sets.push([name, els]);
+  }
+
+  if (!sets.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const [name, els] of sets) {
+    const keys = els.map(resourceKey);
+    const resolved = keys.filter((k) => k != null);
+    const allResolved = resolved.length === keys.length;
+    const allSame = allResolved && resolved.every((k) => k === resolved[0]);
+    if (allSame) continue;
+
+    for (let i = 0; i < els.length; i++) {
+      const el = els[i];
+      const tag = el.tagName.toLowerCase();
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This frame shares its accessible name with another frame that embeds a different resource.',
+          hint: 'Give each frame a name describing the resource it embeds, or point them at the same resource.',
+          i18n: {
+            summaryKey: 'identicalIframesSamePurpose_summary_cantTell',
+            hintKey: 'identicalIframesSamePurpose_hint_cantTell',
+            params: { element: tag, name }
+          },
+          uncertainty:
+            keys[i] == null
+              ? {
+                  code: 'not-computable',
+                  needed: 'A resolvable src for this frame.',
+                  evidence: { element: tag, name, setSize: els.length }
+                }
+              : {
+                  code: 'equivalence-unknown',
+                  needed: 'Whether the two resources serve the same purpose despite differing.',
+                  evidence: {
+                    element: tag,
+                    name,
+                    resource: keys[i],
+                    otherResources: resolved.filter((k) => k !== keys[i]),
+                    setSize: els.length
+                  }
+                },
+          data: {
+            details: {
+              reasonCode:
+                keys[i] == null ? 'IFRAME_RESOURCE_UNRESOLVED' : 'IFRAME_RESOURCE_DIFFERS',
+              element: tag,
+              name,
+              resource: keys[i],
+              setSize: els.length
+            }
+          }
+        })
+      );
+    }
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -390,6 +390,11 @@ function runInPage(ctx) {
             'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
           hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
           i18n: null,
+          uncertainty: {
+            code: 'runtime-dependent',
+            needed: 'Whether a keyboard user can reach this frame’s content in a real browser.',
+            evidence: { element: tag, focusRedirected: true }
+          },
           data: {
             details: {
               reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',

package/src/checks/automatic/label-in-name.js

@@ -254,55 +254,22 @@ function runInPage(ctx) {
     return parts.join(' ').replace(/\s+/g, ' ').trim();
   }
 
+  // Real <label> elements associated with a native form control -- the
+  // shared dom-helpers.js implementation (a `for`-attribute index plus a
+  // bounded closest('label') walk), not the native `.labels`/`.control`
+  // pair: jsdom implements those as a whole-document walk on every access
+  // (see that function's own header comment for the full explanation),
+  // real cost this engine's Node/jsdom runtime pays, not just a browser
+  // realm this code happens to also run in.
   function getAssociatedLabelElements(control) {
-    const labels = [];
-    try {
-      if (control && control.labels && typeof control.labels.length === 'number') {
-        for (const l of control.labels) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // Fallback: wrapped label
-    try {
-      const w = control && control.closest ? control.closest('label') : null;
-      if (w) labels.push(w);
-    } catch {
-      // ignore
-    }
-
-    // Fallback: label[for=id]. Uses `document` directly rather than
-    // ctx.root -- label[for] association is a document-wide relationship
-    // (IDs are document-unique), not bounded by whatever contextSelector
-    // region happens to be scanned, and ctx.root is an array (multi-region
-    // contextSelector support), not a single element with its own
-    // .querySelector to call directly.
-    try {
-      const idAttribute = control && control.getAttribute ? control.getAttribute('id') || '' : '';
-      const key = String(idAttribute || '').trim();
-      if (key && document && document.querySelector) {
-        const l = document.querySelector('label[for="' + CSS.escape(key) + '"]');
-        if (l) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // De-dupe in document order
-    const seen = new Set();
-    const out = [];
-    for (const l of labels) {
+    if (helpers && typeof helpers.getAssociatedLabelElements === 'function') {
       try {
-        if (!l || !l.tagName) continue;
-        if (seen.has(l)) continue;
-        seen.add(l);
-        out.push(l);
+        return helpers.getAssociatedLabelElements(control) || [];
       } catch {
-        // ignore
+        return [];
       }
     }
-    return out;
+    return [];
   }
 
   function getVisibleTextLabelInfo(el) {
@@ -490,44 +457,45 @@ function runInPage(ctx) {
     // character) is not something markup settles: the author may have meant
     // either. Report without asserting a defect instead of failing or
     // staying silent.
-    let uncertainty = '';
+    let uncertainReason = '';
     if (!contains) {
       if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
-        uncertainty = 'HYPHENATION_DIFFERS';
+        uncertainReason = 'HYPHENATION_DIFFERS';
       } else {
         const abbreviated = abbreviatedWords(visibleLabel);
         if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated)) {
-          uncertainty = 'POSSIBLE_ABBREVIATION';
+          uncertainReason = 'POSSIBLE_ABBREVIATION';
         } else if ((labelInfo.sourceElements || []).some(isIconFontElement)) {
-          uncertainty = 'POSSIBLE_ICON_FONT_GLYPH';
+          uncertainReason = 'POSSIBLE_ICON_FONT_GLYPH';
         } else if (isSingleSymbolicCharacter(visibleLabel, accNorm)) {
-          uncertainty = 'POSSIBLE_SYMBOLIC_CHARACTER';
+          uncertainReason = 'POSSIBLE_SYMBOLIC_CHARACTER';
         }
       }
     }
 
     const isSymbolicUncertainty =
-      uncertainty === 'POSSIBLE_ICON_FONT_GLYPH' || uncertainty === 'POSSIBLE_SYMBOLIC_CHARACTER';
+      uncertainReason === 'POSSIBLE_ICON_FONT_GLYPH' ||
+      uncertainReason === 'POSSIBLE_SYMBOLIC_CHARACTER';
 
     if (!contains) {
       occurrences.push(
         helpers.reportOccurrence(el, {
-          ...(uncertainty ? { outcome: 'cantTell' } : null),
-          summary: uncertainty
+          ...(uncertainReason ? { outcome: 'cantTell' } : null),
+          summary: uncertainReason
             ? 'Accessible name may not contain the visible label text.'
             : 'Accessible name does not contain the visible label text.',
-          hint: !uncertainty
+          hint: !uncertainReason
             ? 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).'
             : isSymbolicUncertainty
               ? 'Check by hand: the visible text may render as an icon or symbol rather than literal words, which markup cannot settle.'
               : 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.',
           i18n: {
-            summaryKey: !uncertainty
+            summaryKey: !uncertainReason
               ? 'labelInName_summary_fail'
               : isSymbolicUncertainty
                 ? 'labelInName_summary_cantTell_symbolic'
                 : 'labelInName_summary_cantTell',
-            hintKey: !uncertainty
+            hintKey: !uncertainReason
               ? 'labelInName_hint_fail'
               : isSymbolicUncertainty
                 ? 'labelInName_hint_cantTell_symbolic'
@@ -539,9 +507,23 @@ function runInPage(ctx) {
               nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
             }
           },
+          ...(uncertainReason
+            ? {
+                uncertainty: {
+                  code: 'equivalence-unknown',
+                  needed:
+                    'Whether the accessible name and the visible label say the same thing to a user.',
+                  evidence: {
+                    visibleLabel,
+                    accessibleName: accName,
+                    difference: uncertainReason
+                  }
+                }
+              }
+            : null),
           data: {
             details: {
-              reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+              reasonCode: uncertainReason || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
               visibleLabel,
               accessibleName: accName,
               normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },