@surea11y/core 1.0.0

package/src/checks/manual/tabindex-manual.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * @check tabindex
+ * @atomic true
+ * @summary tabindex should not be greater than 0
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to elements with a tabindex attribute whose value parses as
+ *   a valid integer.
+ * @expectation
+ *   The tabindex value is 0 or negative. A positive tabindex reorders
+ *   keyboard tab order explicitly, which is fragile to maintain as a
+ *   page changes and usually indicates the natural DOM order should be
+ *   fixed instead.
+ * @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 = 'tabindex';
+
+const meta = {
+  title: 'tabindex should not be greater than 0',
+  description: 'Checks that tabindex values are 0 or negative, not a positive number.',
+  i18n: {
+    titleKey: 'tabindex_title',
+    descriptionKey: 'tabindex_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'keyboard', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('[tabindex]');
+  } catch {
+    nodes = [];
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('tabindex') || '').trim();
+    if (!raw) continue;
+    const n = Number(raw);
+    if (!Number.isInteger(n)) continue;
+
+    applicableCount += 1;
+
+    if (n <= 0) 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 element has a positive tabindex, overriding the natural tab order.',
+      hint: 'Use tabindex="0" (or a negative value to remove from tab order) instead of a positive number; fix the DOM order if a different tab order is needed.',
+      i18n: {
+        summaryKey: 'tabindex_summary_cantTell',
+        hintKey: 'tabindex_hint_cantTell',
+        params: { value: String(n) }
+      },
+      data: {
+        details: { reasonCode: 'TABINDEX_POSITIVE', value: n }
+      }
+    });
+  }
+
+  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/table-duplicate-name-manual.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * @check table-duplicate-name
+ * @atomic true
+ * @summary A table's caption must not duplicate its summary attribute
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to <table> elements that have both a <caption> with text
+ *   content and a (deprecated but still encountered) summary attribute.
+ * @expectation
+ *   The caption text and the summary attribute text are not identical
+ *   (case-insensitive, normalized). When both are present and say the
+ *   same thing, assistive technology that surfaces both announces the
+ *   same text twice for one table.
+ * @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.
+ * - Narrowly scoped to caption-vs-summary duplication specifically
+ *   (matching a reference engine's table-duplicate-name check), not a general "table
+ *   name quality" check.
+ */
+
+const id = 'table-duplicate-name';
+
+const meta = {
+  title: 'Table caption must not duplicate its summary attribute',
+  description: 'Checks that a <table>\'s <caption> text is not identical to its (deprecated) summary attribute.',
+  i18n: {
+    titleKey: 'tableDuplicateName_title',
+    descriptionKey: 'tableDuplicateName_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'tables', 'structure', '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();
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table[summary]', safeRoot) : helpers.queryAll('table[summary]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const summary = normalizeWs(el.getAttribute('summary'));
+    if (!summary) continue;
+
+    const captionEl = el.querySelector ? el.querySelector('caption') : null;
+    const captionText = captionEl ? normalizeWs(captionEl.textContent) : '';
+    if (!captionText) continue;
+
+    applicableCount += 1;
+
+    if (captionText.toLowerCase() !== summary.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 table\'s caption duplicates its summary attribute.',
+      hint: 'Remove the redundant summary attribute, or make it provide different information than the caption.',
+      i18n: {
+        summaryKey: 'tableDuplicateName_summary_cantTell',
+        hintKey: 'tableDuplicateName_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'TABLE_CAPTION_SUMMARY_DUPLICATE' }
+      }
+    });
+  }
+
+  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/table-fake-caption-manual.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * @check table-fake-caption
+ * @atomic true
+ * @summary A table's first row should not stand in for a real <caption>
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   `<table>` elements with no `<caption>` child, at least two rows, and
+ *   a first row containing exactly one non-empty-text cell while at
+ *   least one other row has more than one cell.
+ * @expectation
+ *   A single lone cell in the first row, sitting above rows that clearly
+ *   have multiple columns, strongly suggests the author is using it as a
+ *   visual caption/title rather than as a real table cell. Structure
+ *   conveyed only through this positional convention is not
+ *   programmatically associated with the table the way a real
+ *   `<caption>` element is (1.3.1).
+ * @implementation-notes
+ * - Heuristic (a legitimately narrow first data row is possible, if
+ *   uncommon), so authored as `type: 'manual'` (cantTell-capped, never
+ *   fail) rather than a hard fail — same conservative posture as
+ *   `p-as-heading`.
+ * - Does not attempt full colspan/rowspan-aware column counting; "more
+ *   than one cell" on another row is used as the multi-column signal,
+ *   which is simple, deterministic, and sufficient for the heuristic's
+ *   purpose without risking a wrong column-index computation.
+ */
+
+const id = 'table-fake-caption';
+
+const meta = {
+  title: "A table's first row should not stand in for a real <caption>",
+  description: 'Flags tables with no <caption> whose first row has a single non-empty cell while other rows have multiple cells, for manual review of whether that cell is acting as a fake caption.',
+  i18n: {
+    titleKey: 'tableFakeCaption_title',
+    descriptionKey: 'tableFakeCaption_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': ['table-fake-caption-evidence'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table', safeRoot) : helpers.queryAll('table', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const table of nodes) {
+    if (!table || !table.rows) continue;
+
+    const hasCaption = !!(table.querySelector && table.querySelector('caption'));
+    if (hasCaption) continue;
+
+    const rows = Array.from(table.rows);
+    if (rows.length < 2) continue;
+
+    applicableCount += 1;
+
+    const firstRow = rows[0];
+    const firstRowCells = Array.from(firstRow.cells || []);
+    if (firstRowCells.length !== 1) continue;
+
+    const candidateCell = firstRowCells[0];
+    const candidateText = trim(candidateCell.textContent || '');
+    if (!candidateText) continue;
+
+    const hasMultiCellRow = rows.slice(1).some((r) => Array.from(r.cells || []).length > 1);
+    if (!hasMultiCellRow) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(table) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(table) : (table.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: 'This table has no <caption>, but its first row is a single cell sitting above multi-cell rows — it may be acting as a fake caption.',
+      hint: 'If this cell is meant to describe the table, use a real <caption> element instead of a lone first-row cell.',
+      i18n: {
+        summaryKey: 'tableFakeCaption_summary_cantTell',
+        hintKey: 'tableFakeCaption_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'SINGLE_CELL_FIRST_ROW_NO_CAPTION' }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(table, 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/video-caption-manual.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * @check video-caption
+ * @atomic true
+ * @summary Prerecorded <video> should provide a captions track
+ * @standard WCAG 2.2
+ * @sc 1.2.2
+ * @applicability
+ *   Any <video> element in the composed DOM.
+ * @expectation
+ *   SC 1.2.2 requires captions for prerecorded synchronized media, but
+ *   only when the video actually has an audio track that conveys
+ *   information (a silent/decorative video needs none) — which cannot be
+ *   verified from static markup alone (jsdom does not decode media).
+ *   This rule is therefore `type: 'manual'` (cantTell-capped, never
+ *   fail), matching the precedent set by
+ *   `media-alternative-transcript-evidence` for the same class
+ *   of "normatively mapped but not staticaly verifiable" gap. A <video>
+ *   with a `<track kind="captions">` (or `kind="subtitles"`, commonly
+ *   used interchangeably in the wild even though captions and subtitles
+ *   serve technically distinct purposes) whose `src` is non-empty is not
+ *   flagged; everything else is flagged for human review.
+ * @implementation-notes
+ * - Does not attempt to verify the referenced track file's content —
+ *   only that a captions/subtitles track is declared with a non-empty
+ *   `src`.
+ */
+
+const id = 'video-caption';
+
+const meta = {
+  title: 'Prerecorded video should provide a captions track',
+  description:
+    'Flags <video> elements with no <track kind="captions"|"subtitles"> child, for manual review of whether the video has an audio track that needs captions.',
+  i18n: {
+    titleKey: 'videoCaption_title',
+    descriptionKey: 'videoCaption_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag122', 'media', 'timebasedmedia', 'atomic', 'manual'],
+  wcagSc: ['1.2.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.2.2', title: 'Captions (Prerecorded)', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'low',
+  coverage: { facetsBySc: { '1.2.2': ['video-captions-track-evidence'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('video', safeRoot) : helpers.queryAll('video', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.querySelectorAll) continue;
+
+    applicableCount += 1;
+
+    let hasCaptionsTrack = false;
+    const tracks = el.querySelectorAll('track');
+    for (const t of tracks) {
+      const kind = (t.getAttribute('kind') || '').trim().toLowerCase();
+      const src = (t.getAttribute('src') || '').trim();
+      if ((kind === 'captions' || kind === 'subtitles') && src) {
+        hasCaptionsTrack = true;
+        break;
+      }
+    }
+
+    if (hasCaptionsTrack) 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 video has no captions (or subtitles) track.',
+      hint: 'If this video has an audio track that conveys information, add a <track kind="captions" src="..."> with the captioned content.',
+      i18n: {
+        summaryKey: 'videoCaption_summary_cantTell',
+        hintKey: 'videoCaption_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'CAPTIONS_TRACK_NOT_DETECTED' }
+      }
+    };
+
+    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 <video> already has a captions/subtitles track.
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual-review.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * @check manual-review
+ * Manual review for keyboard navigation and focus order.
+ */
+
+const id = 'manual-review';
+
+const meta = {
+  ruleId: 'manual-review',
+  title: 'Manual review: keyboard navigation and focus order',
+  description: 'Flags that a manual review of keyboard navigation and focus order is required.',
+  i18n: { titleKey: 'manualReview_title', descriptionKey: 'manualReview_description' },
+
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag2aa', 'wcag211', 'wcag243', 'wcag247', 'nontext', 'atomic', 'manual'],
+  defaultSeverity: 'moderate',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '2.1.1', title: 'Keyboard', conformanceLevel: 'A', url: 'https://www.w3.org/TR/WCAG22/#keyboard' },
+    { standard: 'WCAG', version: '2.2', requirement: '2.4.3', title: 'Focus Order', conformanceLevel: 'A', url: 'https://www.w3.org/TR/WCAG22/#focus-order' },
+    { standard: 'WCAG', version: '2.2', requirement: '2.4.7', title: 'Focus Visible', conformanceLevel: 'AA', url: 'https://www.w3.org/TR/WCAG22/#focus-visible' },
+
+    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.1.1', title: 'Keyboard' },
+    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.4.3', title: 'Focus Order' },
+    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.4.7', title: 'Focus Visible' },
+
+    { standard: 'WCAG', version: '2.2', type: 'Understanding', requirement: '2.1.1', title: 'Understanding Keyboard', url: 'https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html' },
+    { standard: 'WCAG', version: '2.2', type: 'Understanding', requirement: '2.4.3', title: 'Understanding Focus Order', url: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html' },
+    { standard: 'WCAG', version: '2.2', type: 'Understanding', requirement: '2.4.7', title: 'Understanding Focus Visible', url: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html' }
+  ]
+};
+
+/**
+ * NOTE (engine constraint):
+ * runInPage() is serialized and executed from source (fnSource) by a11yCore-core,
+ * so it must NOT reference outer-scope variables like `meta` or `id`.
+ * Only use `ctx.*`, locals, and DOM APIs.
+ */
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+
+  const getOuterHtmlSnippet = helpers && helpers.getOuterHtmlSnippet
+      ? helpers.getOuterHtmlSnippet
+      : (el) => (el && el.outerHTML) || '';
+
+  const contextSelector = ctx.contextSelector || null;
+
+  let rootEl = root || null;
+
+  if (!rootEl) {
+    if (contextSelector) {
+      try {
+        rootEl = document.querySelector(contextSelector);
+      } catch {
+        // invalid selector, fallback to full document
+        rootEl = null;
+      }
+    }
+    if (!rootEl) {
+      rootEl = document.documentElement || document.body || document.querySelector('html');
+    }
+  }
+
+  const fallbackRoot =
+      rootEl ||
+      document.documentElement ||
+      document.body ||
+      document.querySelector('html');
+
+  const html = getOuterHtmlSnippet(fallbackRoot);
+
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'moderate',
+    occurrences: [
+      {
+        selector: contextSelector || 'html',
+        html,
+        summary: 'Manual review required for keyboard navigation and focus order.',
+        i18n: { summaryKey: 'manualReview_summary_cantTell', hintKey: 'manualReview_hint_cantTell', params: {} },
+      }
+    ]
+  };
+}
+
+module.exports = {
+  id,
+  meta,
+  runInPage
+};

package/src/checks/rules-and-tags.full.csv

@@ -0,0 +1,19 @@
+ruleId,type,title,tags,file
+area-alt-decorative,manual,<area> with alt=\,wcag2a wcag111 nontext images imagemap manual atomic,area-alt-decorative-manual.js
+area-alt-present,automatic,&lt;area&gt; must have an alt attribute,wcag2a wcag111 nontext images imagemap atomic automatic,area-alt-present.js
+area-alt-quality,manual,<area> alt text must be appropriate (manual review),wcag2a wcag111 nontext images imagemap manual atomic,area-alt-quality-manual.js
+canvas-text-alternative-present,automatic,<canvas> must provide a text alternative,wcag2a wcag111 nontext canvas atomic automatic,canvas-text-alternative-present.js
+canvas-text-alternative-quality,manual,<canvas> text alternative must be appropriate (manual review),wcag2a wcag111 nontext canvas manual atomic,canvas-text-alternative-quality-manual.js
+embed-text-alternative-present,automatic,<embed> must provide a text alternative,wcag2a wcag111 nontext embed atomic automatic,embed-text-alternative-present.js
+embed-text-alternative-quality,manual,<embed> text alternative must be appropriate (manual review),wcag2a wcag111 nontext embed manual atomic,embed-text-alternative-quality-manual.js
+img-alt-decorative,manual,<img> with alt=\,wcag2a wcag111 nontext images manual atomic,img-alt-decorative-manual.js
+img-alt-present,automatic,<img> must have an alt attribute,wcag2a wcag111 nontext images atomic automatic,img-alt-present.js
+img-alt-quality,manual,<img> alt text must be appropriate (manual review),wcag2a wcag111 nontext images manual atomic,img-alt-quality-manual.js
+input-image-alt-decorative,manual,<input type=\,wcag2a wcag111 forms images manual atomic,input-image-alt-decorative-manual.js
+input-image-alt-present,automatic,<input type=,wcag2a wcag111 nontext images atomic automatic,input-image-alt-present.js
+input-image-alt-quality,manual,<input type=\,wcag2a wcag111 forms images manual atomic,input-image-alt-quality-manual.js
+object-text-alternative-present,automatic,<object> must provide a text alternative,wcag2a wcag111 nontext object atomic automatic,object-text-alternative-present.js
+object-text-alternative-quality,manual,<object> text alternative must be appropriate (manual review),wcag2a wcag111 nontext object manual atomic,object-text-alternative-quality-manual.js
+svg-image-text-alternative-present,automatic,SVG <image> must have a text alternative,wcag2a wcag111 nontext svg image atomic automatic,svg-image-text-alternative-present.js
+svg-text-alternative-present,automatic,<svg> must provide a text alternative,wcag2a wcag111 svg nontext images atomic automatic,svg-text-alternative-present.js
+video-poster-text-alternative-present,automatic,<video> poster must have a text alternative,wcag2a wcag111 media video atomic automatic,video-poster-text-alternative-present.js