@surea11y/core 1.0.0

package/src/checks/manual/no-autoplay-audio-manual.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * @check no-autoplay-audio
+ * @atomic true
+ * @summary Autoplaying, unmuted <audio>/<video> should provide a pause/stop or volume-control mechanism
+ * @standard WCAG 2.2
+ * @sc 1.4.2
+ * @applicability
+ *   Any <audio autoplay> or <video autoplay> element that is not `muted`.
+ * @expectation
+ *   SC 1.4.2 only applies when audio plays automatically for MORE than 3
+ *   seconds; clip duration is not knowable from static markup (jsdom does
+ *   not decode media), so this rule cannot determine whether the SC even
+ *   applies to a given element. It is deliberately authored as `type:
+ *   'manual'` (cantTell-capped, never fail) rather than guessing: an
+ *   autoplaying unmuted element with no `controls` attribute (the native,
+ *   statically-verifiable mechanism to pause/stop or adjust volume) is
+ *   flagged for human review rather than treated as a deterministic
+ *   violation.
+ * @implementation-notes
+ * - Elements with `controls` present are not flagged: native controls
+ *   provide pause/stop and volume adjustment, satisfying the SC's
+ *   mechanism requirement regardless of duration.
+ * - Elements with `muted` present are not flagged: muted playback is not
+ *   audible, so the SC's condition ("plays automatically... audio")
+ *   does not apply.
+ * - Custom (JS-built) controls that don't use the native `controls`
+ *   attribute cannot be detected statically — a documented limitation,
+ *   same class as `iframe-focusable-content`'s `contentDocument` gap.
+ * - Not gated on `isAccTreeEligible`: unlike most rules, a `display:none`
+ *   or `aria-hidden` audio/video element still plays audible sound in a
+ *   real browser, so visual/AT-tree eligibility is not a relevant filter
+ *   here.
+ */
+
+const id = 'no-autoplay-audio';
+
+const meta = {
+  title: 'Autoplaying audio should provide a pause/stop or volume-control mechanism',
+  description:
+    'Flags <audio>/<video> elements that autoplay unmuted with no native controls attribute, for manual review against the 3-second exemption in WCAG 1.4.2.',
+  i18n: {
+    titleKey: 'noAutoplayAudio_title',
+    descriptionKey: 'noAutoplayAudio_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag142', 'media', 'atomic', 'manual'],
+  wcagSc: ['1.4.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.4.2', title: 'Audio Control', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'low',
+  coverage: { facetsBySc: { '1.4.2': ['no-autoplay-audio-evidence'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('audio[autoplay], video[autoplay]', safeRoot) : helpers.queryAll('audio[autoplay], video[autoplay]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.hasAttribute) continue;
+    if (el.hasAttribute('muted')) continue;
+
+    applicableCount += 1;
+
+    if (el.hasAttribute('controls')) continue;
+
+    const mediaTag = (el.tagName || '').toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: 'This element autoplays audio without a native pause/stop or volume-control mechanism.',
+      hint: 'If this clip plays for more than 3 seconds, add a `controls` attribute (or an equivalent custom mechanism) so users can pause/stop it or control its volume independently of the system volume.',
+      i18n: {
+        summaryKey: 'noAutoplayAudio_summary_cantTell',
+        hintKey: 'noAutoplayAudio_hint_cantTell',
+        params: { element: mediaTag }
+      },
+      data: {
+        details: { reasonCode: 'AUTOPLAY_NO_CONTROLS_MECHANISM', mediaTag }
+      }
+    };
+
+    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 || 'moderate', occurrences };
+  }
+
+  // Manual rules may only emit cantTell/notApplicable (never pass/fail):
+  // every applicable autoplaying element already has a controls mechanism.
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/object-text-alternative-quality-manual.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * @check object-text-alternative-quality
+ * @atomic true
+ * @summary Manual review: text alternative appropriateness (WCAG 1.1.1)
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @type manual
+ * @expectation
+ *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ */
+
+const id = "object-text-alternative-quality";
+
+const meta = {
+    title: "<object> text alternative must be appropriate (manual review)",
+    description: "Flags <object> elements with detected fallback or name for human review of equivalence and appropriateness.",
+    i18n: {
+        titleKey: "object_textAltQuality_title",
+        descriptionKey: "object_textAltQuality_description"
+    },
+    helpUrl: null,
+    tags: ["wcag2a", "wcag111", "nontext", "object", "manual", "atomic"],
+    wcagSc: ['1.1.1'],
+    normativeMappings: [
+        {standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A'}
+    ],
+    defaultSeverity: 'minor',
+    category: 'perceivable',
+    type: 'manual',
+    defaultConfidence: 'medium',
+    coverage: {
+        facetsBySc: {
+            '1.1.1': ['text-alternative-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 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 els = (() => {
+        try {
+            return Array.from((queryAllSmart ? queryAllSmart('object') : queryAll('object')) || []);
+        } catch {
+            return queryAll('object');
+        }
+    })();
+
+    if (!els.length) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) continue;
+
+        if (isAccTreeEligible) {
+            const elig = (() => {
+                try {
+                    return isAccTreeEligible(el, ctx);
+                } catch {
+                    return {eligible: true, reasons: []};
+                }
+            })();
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        const trim = (v) => (v == null ? '' : String(v)).trim();
+
+        let fallbackText = '';
+        let ariaLabel = '';
+        let ariaLabelledBy = '';
+        let title = '';
+        let labelledByText = '';
+
+        try {
+            fallbackText = trim(el.textContent || '');
+            ariaLabel = trim(el.getAttribute('aria-label'));
+            ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
+            title = trim(el.getAttribute('title'));
+        } catch {}
+
+// Only resolve idrefs if needed/present
+        if (!ariaLabel && ariaLabelledBy && helpers && typeof helpers.getTextFromIdRefs === 'function') {
+            try {
+                const t = helpers.getTextFromIdRefs(ariaLabelledBy, ctx);
+                labelledByText = trim(t && t.text);
+            } catch {}
+        }
+
+        const details = {
+            fallbackText: fallbackText || null,
+            ariaLabel: ariaLabel || null,
+            ariaLabelledBy: ariaLabelledBy || null,
+            ariaLabelledByText: labelledByText || null,
+            title: title || null
+        };
+
+        const hasMechanism = !!(details.fallbackText || details.ariaLabel || details.ariaLabelledByText || details.title);
+        if (!hasMechanism) continue;
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+        const baseOccurrence = {
+            summary: 'Review text alternative for <object> for equivalence and appropriateness.',
+            hint: 'Confirm the fallback content or ARIA name provides an equivalent alternative for the embedded content.',
+            i18n: {
+                summaryKey: 'object_textAltQuality_summary_cantTell',
+                hintKey: 'object_textAltQuality_hint_cantTell',
+                params: { element: 'object' }
+            },
+            data: {
+                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+                details
+            }
+        };
+
+        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};
+}
+
+module.exports = {id, meta, runInPage};

package/src/checks/manual/p-as-heading-manual.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * @check p-as-heading
+ * @atomic true
+ * @summary A <p> styled to look like a heading should probably be a real heading
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   `<p>` elements with short (<=120 char), non-empty trimmed text
+ *   content that is entirely bold (the `<p>`'s own computed
+ *   `font-weight` >= 700, OR its entire text is wrapped in a single
+ *   `<strong>`/`<b>` child) and rendered at >=18px.
+ * @expectation
+ *   Text styled to visually read as a heading (bold, larger-than-body
+ *   size, short) should be marked up with a real heading element
+ *   (`<h1>`-`<h6>` or `role="heading"`) so its structural role is
+ *   programmatically determinable — the same 1.3.1 concern as any other
+ *   "structure conveyed through presentation only" issue.
+ * @implementation-notes
+ * - This is a stylistic heuristic (bold + large + short), not a
+ *   deterministic structural check — a short bold sentence is not
+ *   necessarily wrong as a `<p>`. Authored as `type: 'manual'`
+ *   (cantTell-capped, never fail) to avoid false-flagging legitimate
+ *   emphasis, matching this repo's other heuristic-heavy Tier 2/3
+ *   rules (e.g. `scrollable-region-focusable`).
+ * - Uses an absolute 18px size threshold rather than comparing against
+ *   surrounding text (unlike `link-in-text-block`) — deliberately
+ *   simpler, since "looks like a heading" is closer to an absolute
+ *   judgment than a relative-contrast one.
+ */
+
+const id = 'p-as-heading';
+
+const meta = {
+  title: 'A <p> styled to look like a heading should probably be a real heading',
+  description: 'Flags short <p> elements whose entire text is bold and rendered at >=18px, for manual review of whether a real heading element should be used instead.',
+  i18n: {
+    titleKey: 'pAsHeading_title',
+    descriptionKey: 'pAsHeading_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'manual'],
+  wcagSc: ['1.3.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'low',
+  coverage: { facetsBySc: { '1.3.1': ['p-as-heading-evidence'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const MAX_HEADING_LIKE_CHARS = 120;
+  const MIN_FONT_SIZE_PX = 18;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  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 isBoldWeight(cs) {
+    if (!cs) return false;
+    const w = trim(cs.fontWeight).toLowerCase();
+    if (w === 'bold' || w === 'bolder') return true;
+    const n = Number.parseInt(w, 10);
+    return Number.isFinite(n) && n >= 700;
+  }
+
+  function isEntirelyBold(p, text) {
+    const cs = safeComputedStyle(p);
+    if (isBoldWeight(cs)) return true;
+
+    // A single <strong>/<b> child that wraps the whole text also counts.
+    const children = Array.from(p.children || []);
+    const boldWrap = children.find((c) => {
+      const tag = (c.tagName || '').toLowerCase();
+      return tag === 'strong' || tag === 'b';
+    });
+    if (boldWrap && children.length === 1) {
+      const wrapText = trim(boldWrap.textContent || '');
+      if (wrapText && wrapText === text) return true;
+    }
+    return false;
+  }
+
+  function getFontSizePx(p) {
+    const cs = safeComputedStyle(p);
+    if (!cs) return 0;
+    const px = Number.parseFloat(cs.fontSize);
+    return Number.isFinite(px) ? px : 0;
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('p', safeRoot) : helpers.queryAll('p', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const text = trim(el.textContent || '');
+    if (!text || text.length > MAX_HEADING_LIKE_CHARS) continue;
+
+    applicableCount += 1;
+
+    if (!isEntirelyBold(el, text)) continue;
+
+    const fontSizePx = getFontSizePx(el);
+    if (fontSizePx < MIN_FONT_SIZE_PX) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: 'This paragraph is entirely bold and rendered at a heading-like size.',
+      hint: 'If this text introduces a new section, use a real heading element (<h1>-<h6> or role="heading") instead of styling a paragraph to look like one.',
+      i18n: {
+        summaryKey: 'pAsHeading_summary_cantTell',
+        hintKey: 'pAsHeading_hint_cantTell',
+        params: { fontSizePx: String(fontSizePx) }
+      },
+      data: {
+        details: { reasonCode: 'BOLD_LARGE_PARAGRAPH', fontSizePx }
+      }
+    };
+
+    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 };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/page-has-heading-one-manual.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * @check page-has-heading-one
+ * @atomic true
+ * @summary The page should have at least one level-one heading
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Always applicable to any HTML document with a <body> element —
+ *   "does the page have an h1" is a whole-page concern, matching
+ *   bypass-blocks-present's pattern of evaluating the document
+ *   directly.
+ * @expectation
+ *   At least one heading with level 1 exists (native <h1>, or
+ *   role="heading" with aria-level="1"). A page with no top-level
+ *   heading has no clear entry point for assistive technology users
+ *   navigating by heading.
+ * @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.
+ */
+
+const id = 'page-has-heading-one';
+
+const meta = {
+  title: 'Page should have a level-one heading',
+  description: 'Checks that the page has at least one level-one heading (<h1> or role="heading" with aria-level="1").',
+  i18n: {
+    titleKey: 'pageHasHeadingOne_title',
+    descriptionKey: 'pageHasHeadingOne_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;
+
+  const body = document && document.body ? document.body : null;
+  if (!body) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  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 isLevelOneHeading(el) {
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) {
+      if (explicit !== 'heading') return false;
+      const raw = normalizeWs(el.getAttribute && el.getAttribute('aria-level'));
+      return raw === '1';
+    }
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    return tag === 'h1';
+  }
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('h1, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const hasH1 = Array.from(nodes).some((el) => el && isLevelOneHeading(el));
+
+  if (hasH1) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
+  const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(body) : (body.outerHTML || '').slice(0, 200);
+
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'minor',
+    occurrences: [{
+      selector: stableSelector,
+      html,
+      summary: 'This page has no level-one heading.',
+      hint: 'Add a level-one heading (<h1> or role="heading" aria-level="1") that identifies the page\'s main content.',
+      i18n: {
+        summaryKey: 'pageHasHeadingOne_summary_cantTell',
+        hintKey: 'pageHasHeadingOne_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'HEADING_ONE_MISSING' }
+      }
+    }]
+  };
+}
+
+module.exports = { id, meta, runInPage };