@surea11y/core 1.0.0

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

@@ -0,0 +1,218 @@
+'use strict';
+
+/**
+ * @check link-in-text-block
+ * @atomic true
+ * @summary Links surrounded by text must be distinguishable from that text by non-color means
+ * @standard WCAG 2.2
+ * @sc 1.4.1
+ * @applicability
+ *   Applies to <a href> elements whose immediate parent element also has
+ *   at least one direct-child text node with non-whitespace content
+ *   (i.e. the link sits inline within a run of plain text, not as a
+ *   standalone item — e.g. not the sole content of a <li> nav item).
+ * @expectation
+ *   A link inside a text block must be visually distinguishable from the
+ *   surrounding text by at least one non-color means:
+ *     - text-decoration: underline, OR
+ *     - a different font-weight than the surrounding text, OR
+ *     - a different font-style than the surrounding text, OR
+ *     - a contrast ratio of at least 3:1 between the link's text color and
+ *       the surrounding text's color (WCAG technique G183's threshold —
+ *       sufficient contrast alone is an accepted alternative to underline).
+ *   Fails only when none of the above hold AND the color contrast between
+ *   link and surrounding text is confidently computable and below 3:1 —
+ *   i.e. color is demonstrably the only cue.
+ * @implementation-notes
+ * - "Surrounding text style" is approximated as the link's immediate
+ *   parent element's own computed style, not a full inline-context walk
+ *   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.
+ * - Reuses the shared `helpers.contrast` subsystem (same
+ *   computeEffectiveForeground/Background, getComputabilityBlocker,
+ *   contrastRatio helpers as `contrast-minimum`), rather than re-deriving
+ *   color math independently.
+ * - Scoped to `a[href]` only (not `area[href]` or `[role="link"]`) —
+ *   matches the common real-world shape of this issue (prose links).
+ */
+
+const id = 'link-in-text-block';
+
+const meta = {
+  title: 'Links in text blocks must be distinguishable from surrounding text without relying on color alone',
+  description:
+    'Checks that a link inside a run of text is visually distinguishable from the surrounding text by underline, a font-weight/style difference, or a sufficient (>=3:1) color-contrast difference — not by color alone.',
+  i18n: {
+    titleKey: 'linkInTextBlock_title',
+    descriptionKey: 'linkInTextBlock_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag141', 'navigation', 'color', 'links', 'contrast', 'atomic', 'automatic', 'dom'],
+  wcagSc: ['1.4.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.4.1', title: 'Use of Color', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.4.1': ['link-in-text-block'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule, engineOptions } = ctx;
+  const safeRoot = root || document;
+
+  function safeComputedStyle(el) {
+    try {
+      if (!el || el.nodeType !== 1) return null;
+      if (helpers && typeof helpers.computedStyle === 'function') {
+        const cs = helpers.computedStyle(el);
+        if (cs) return cs;
+      }
+      const view = (el.ownerDocument && el.ownerDocument.defaultView) ? el.ownerDocument.defaultView : null;
+      if (view && typeof view.getComputedStyle === 'function') return view.getComputedStyle(el);
+    } catch {}
+    return null;
+  }
+
+  function decorationTokens(cs) {
+    const raw = `${(cs && cs.textDecorationLine) || ''} ${(cs && cs.textDecoration) || ''}`.toLowerCase();
+    return raw.split(/\s+/).filter(Boolean);
+  }
+
+  function hasUnderline(cs) {
+    return decorationTokens(cs).includes('underline');
+  }
+
+  function hasSurroundingText(el, parent) {
+    if (!parent || !parent.childNodes) return false;
+    for (let i = 0; i < parent.childNodes.length; i++) {
+      const n = parent.childNodes[i];
+      if (n === el) continue;
+      if (n.nodeType === 3 && n.nodeValue && n.nodeValue.trim().length > 0) return true;
+    }
+    return false;
+  }
+
+  const contrastOpts = engineOptions && typeof engineOptions.contrast === 'object' && engineOptions.contrast
+    ? engineOptions.contrast
+    : {};
+  const mode = contrastOpts.mode === 'auditorAssist' ? 'auditorAssist' : 'strictConformance';
+  const rootCanvasFallback =
+    typeof contrastOpts.rootCanvasFallback === 'string' && contrastOpts.rootCanvasFallback.trim()
+      ? contrastOpts.rootCanvasFallback.trim()
+      : '#ffffff';
+
+  const c = helpers && helpers.contrast ? helpers.contrast : null;
+
+  const selector = 'a[href]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  const occurrences = [];
+  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 parent = el.parentElement;
+    if (!hasSurroundingText(el, parent)) continue;
+
+    applicableCount += 1;
+
+    const linkCs = safeComputedStyle(el);
+    const parentCs = safeComputedStyle(parent);
+
+    if (hasUnderline(linkCs)) continue;
+
+    const linkWeight = c && linkCs ? c.normalizeFontWeight(linkCs.fontWeight) : 400;
+    const parentWeight = c && parentCs ? c.normalizeFontWeight(parentCs.fontWeight) : 400;
+    if (linkWeight !== parentWeight) continue;
+
+    const linkStyle = (linkCs && linkCs.fontStyle) || 'normal';
+    const parentStyle = (parentCs && parentCs.fontStyle) || 'normal';
+    if (linkStyle !== parentStyle) continue;
+
+    if (!c) continue;
+
+    let flagged = false;
+    let ratio = null;
+    let fgLinkHex = '';
+    let fgParentHex = '';
+
+    try {
+      const blocker = c.getComputabilityBlocker(el);
+      if (blocker && blocker.ok === false) {
+        // Not confidently computable — skip (benefit of the doubt).
+      } else {
+        const bg = c.computeEffectiveBackground(el, { contrast: { mode, rootCanvasFallback }, collectStack: false });
+        const fgLink = c.computeEffectiveForeground(el);
+        const fgParent = c.computeEffectiveForeground(parent);
+
+        if (bg && bg.ok && bg.rgba && fgLink && fgLink.rgba && fgParent && fgParent.rgba) {
+          const fgLinkOpaque = fgLink.rgba.a < 1 ? c.compositeRgba(fgLink.rgba, bg.rgba) : { r: fgLink.rgba.r, g: fgLink.rgba.g, b: fgLink.rgba.b, a: 1 };
+          const fgParentOpaque = fgParent.rgba.a < 1 ? c.compositeRgba(fgParent.rgba, bg.rgba) : { r: fgParent.rgba.r, g: fgParent.rgba.g, b: fgParent.rgba.b, a: 1 };
+
+          ratio = c.contrastRatio(fgLinkOpaque, fgParentOpaque);
+          fgLinkHex = c.rgbToHex ? c.rgbToHex(fgLinkOpaque) : '';
+          fgParentHex = c.rgbToHex ? c.rgbToHex(fgParentOpaque) : '';
+
+          if (!(ratio >= 3)) flagged = true;
+        }
+        // else: not confidently computable — skip.
+      }
+    } catch {
+      // no-throw: treat as not computable, skip.
+    }
+
+    if (!flagged) continue;
+
+    const eligInfo = helpers.getEligibilityInfo ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const tag = (el.tagName || '').toLowerCase();
+    const ratioStr = c.round2 ? c.round2(ratio) : String(ratio);
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
+      hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
+      i18n: {
+        summaryKey: 'linkInTextBlock_summary_fail',
+        hintKey: 'linkInTextBlock_hint_fail',
+        params: { element: tag, ratio: String(ratioStr), threshold: '3' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: {
+          reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
+          metrics: { ratio, threshold: 3 },
+          colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+        }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -0,0 +1,114 @@
+'use strict';
+
+const id = 'link-name-present';
+
+const meta = {
+  title: 'Links have an accessible name',
+  description: 'Checks that links expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'linkNamePresent_title',
+    descriptionKey: 'linkNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'links', 'name'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  // IMPORTANT: update your facets registry to include "link-name-present" under 4.1.2
+  coverage: { facetsBySc: { '4.1.2': ['link-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  function getConservativeSubtreeText(container) {
+    // "Name from content" — recurses into descendants and uses each one's
+    // own accessible name (img alt, aria-label/aria-labelledby, title) when
+    // it has one, not just literal text nodes. See getContentNameInfo's
+    // header comment in src/core/dom-helpers.js for the full rationale
+    // (this replaced a text-node-only TreeWalker that missed the common
+    // "<a><img alt='...'></a>" logo-link pattern).
+    if (helpers.getContentNameInfo) {
+      const info = helpers.getContentNameInfo(container, ctx);
+      return info && info.present ? info.value : '';
+    }
+    const t = (container && container.textContent) ? String(container.textContent) : '';
+    return t.replace(/\s+/g, ' ').trim();
+  }
+
+  const selector = 'a[href], area[href], [role="link"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+  for (const el of nodes) {
+    // isAccTreeEligible returns { eligible, reasons }, not a boolean.
+    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    const eligible = typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    if (!eligible) continue;
+
+    applicableCount += 1;
+
+    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
+    const programmaticName = (nameInfo && typeof nameInfo.value === 'string') ? nameInfo.value : '';
+
+    const contentName = programmaticName.trim().length === 0 ? getConservativeSubtreeText(el) : '';
+    const finalName = (programmaticName.trim().length ? programmaticName : contentName).trim();
+
+    if (finalName.length === 0) {
+      // Only compute the richer eligibility-info payload (used solely for
+      // the occurrence's visibilityFilter) once we know an occurrence is
+      // actually being built, rather than for every applicable element.
+      const eligInfo = helpers.getEligibilityInfo ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+      const tag = (el.tagName || '').toLowerCase();
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+
+        // Human fallbacks (allowed)
+        summary: 'This link has no accessible name.',
+        hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
+
+        // Validator requires these keys to exist in the English dictionary
+        i18n: {
+          summaryKey: 'linkNamePresent_summary_fail',
+          hintKey: 'linkNamePresent_hint_fail',
+          params: { element: tag }
+        },
+
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'name_missing',
+            metrics: {
+              programmaticNameLength: programmaticName.trim().length,
+              contentNameLength: contentName.trim().length
+            },
+            refs: { accessibleName: nameInfo || null }
+          }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/list-children-valid.js

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * @check list-children-valid
+ * @atomic true
+ * @summary <ul>/<ol> must only directly contain <li>, <script>, or <template>
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   Applies to <ul>/<ol> elements that have at least one direct element
+ *   child.
+ * @expectation
+ *   Every direct element child is <li>, <script>, or <template> — UNLESS it
+ *   has an explicit `role` attribute, in which case the explicit role wins
+ *   over the tag entirely: a child is valid iff that role is "listitem"
+ *   (so `<li role="presentation">`/`<li role="menuitem">` are invalid
+ *   despite the <li> tag, and conversely a non-<li> element explicitly
+ *   given `role="listitem"` is valid). A wrapper <div> used for styling
+ *   (no role at all) still breaks list semantics the same as before.
+ * @implementation-notes
+ * - Checked via el.children, which already excludes text/comment nodes —
+ *   no whitespace-node filtering needed.
+ * - Distinct, atomic decision from listitem-parent-valid (the
+ *   inverse relationship: does a given <li> have a valid parent).
+ * - Direct children that are not exposed to the accessibility tree (e.g.
+ *   display:none, [hidden], aria-hidden="true") are excluded from
+ *   consideration entirely — matching a widely-used reference engine's own
+ *   `only-listitems` check, which likewise skips non-AT-visible children. Confirmed against
+ *   two real sites: Spotify's newsroom has a stray `<input type="hidden">`
+ *   as a direct <ul> child (UA-stylesheet display:none by spec for
+ *   input[type=hidden]), and Stanford's main nav interleaves `<li>` with
+ *   `<span style="display:none">` hydration markers. Neither is reachable
+ *   by assistive technology, so neither breaks the list semantics a screen
+ *   reader actually announces.
+ * - The explicit-role-overrides-tag behavior above was added after reading
+ *   a widely-used reference engine's ACTUAL `only-listitems` evaluate function
+ *   directly (`invalidChildrenEvaluate`/`getInvalidSelector` — note this is a
+ *   DIFFERENT function from the similarly-named, unused `onlyListitemsEvaluate`
+ *   elsewhere in that engine's source; don't confuse the two when re-verifying). Its
+ *   exact rule: if a child has an explicit role, only `validRoles` (here,
+ *   `['listitem']`) is consulted — the tag name is never checked. Only
+ *   without an explicit role does the tag name (`validNodeNames`) matter.
+ *   Found via two real sites: Notion's footer nav lists include a
+ *   `<li role="none">` used purely to host the list's own visually-hidden
+ *   label (referenced by the `<ul>`'s `aria-labelledby`), and LinkedIn has
+ *   both an all-`<li role="menuitem">` menu list and a footer list mixing
+ *   real `<li>`s with one `<li role="presentation">` — that reference engine
+ *   correctly flags all of these, surea11y's tag-only check missed them entirely.
+ */
+
+const id = 'list-children-valid';
+
+const meta = {
+  title: 'Lists must only directly contain list items',
+  description: 'Checks that <ul>/<ol> elements only have <li>, <script>, or <template> as direct children.',
+  i18n: {
+    titleKey: 'listChildrenValid_title',
+    descriptionKey: 'listChildrenValid_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'list'],
+  wcagSc: ['1.3.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.3.1': ['list-children-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const ALLOWED_CHILD_TAGS = new Set(['li', 'script', 'template']);
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('ul, ol', safeRoot) : helpers.queryAll('ul, ol', safeRoot);
+
+  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isExposedToAt(el) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.children) continue;
+    if (!el.children.length) continue;
+
+    applicableCount += 1;
+
+    const invalidTags = [];
+    for (const child of el.children) {
+      if (!child || !child.tagName) continue;
+      if (!isExposedToAt(child)) continue;
+      const tag = child.tagName.toLowerCase();
+
+      const roleAttr = child.getAttribute ? String(child.getAttribute('role') || '').trim() : '';
+      const explicitRole = roleAttr ? (roleAttr.split(/\s+/)[0] || '').toLowerCase() : '';
+
+      // An explicit role always wins over the tag — see the header
+      // comment's Notion/LinkedIn examples.
+      const valid = explicitRole ? explicitRole === 'listitem' : ALLOWED_CHILD_TAGS.has(tag);
+
+      if (!valid) invalidTags.push(tag);
+    }
+
+    if (!invalidTags.length) continue;
+
+    const tag = el.tagName.toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This list contains a direct child that is not a list item.',
+      hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
+      i18n: {
+        summaryKey: 'listChildrenValid_summary_fail',
+        hintKey: 'listChildrenValid_hint_fail',
+        params: { element: tag, invalidChildren: invalidTags.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };