ultra11y 2.22.0

package/src/rules/tables.ts

@@ -0,0 +1,264 @@
+// Theme 5 — Data tables (+ layout-table heuristic to avoid false positives).
+import type { Doc, El } from "../parse/html.js";
+import { attr, hasAttr, hasBoundAttr, descendants, ancestors, visibleText } from "../parse/html.js";
+import { mayInjectContent } from "../name.js";
+import type { Rule, RuleFinding } from "./rule.js";
+
+const declaredLayout = (t: El): boolean => ["presentation", "none"].includes((attr(t, "role") ?? "").trim());
+const named = (t: El): boolean => !!(attr(t, "aria-label") ?? "").trim() || hasAttr(t, "aria-labelledby");
+
+// Heuristic: treat a table as LAYOUT (skip data-table rules) when it declares
+// role=presentation/none, OR nests another table (data tables don't nest), OR is
+// a trivial single-row table with no <th>/<caption>. Cuts the classic
+// table-based-layout false positive without missing real data tables.
+function isLayoutTable(t: El): boolean {
+  if (declaredLayout(t)) return true;
+  const desc = descendants(t);
+  if (desc.some((d) => d.tag === "table")) return true;
+  const hasTh = desc.some((d) => d.tag === "th");
+  const hasCaption = t.children.some((c) => c.type === "element" && c.tag === "caption");
+  const rows = desc.filter((d) => d.tag === "tr").length;
+  return !hasTh && !hasCaption && rows <= 1;
+}
+
+const dataTableNoHeaders: Rule = {
+  id: "data-table-no-headers",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const t of doc.elements) {
+      if (t.tag !== "table" || isLayoutTable(t)) continue;
+      const desc = descendants(t);
+      // No statically-visible rows/cells means the body is injected dynamically
+      // ({children}/slot — e.g. a generic <table> wrapper component) or simply absent;
+      // we cannot tell whether headers exist, so we do not assert a definite NC.
+      if (!desc.some((d) => d.tag === "tr" || d.tag === "td" || d.tag === "th")) continue;
+      const ths = desc.filter((d) => d.tag === "th");
+      const hasTh = ths.length > 0;
+      // hasBoundAttr also matches a dynamic :scope / v-bind:scope binding (Vue/Svelte).
+      const hasAssoc = desc.some((d) => (d.tag === "td" || d.tag === "th") && (hasBoundAttr(d, "scope") || hasBoundAttr(d, "headers")));
+      // Implicit scope per HTML's header-association algorithm (WCAG technique H51): a simple
+      // table needs no explicit scope= when its headers sit in <thead>, OR form one complete
+      // header ROW (column headers), OR are the first cell of every row (row headers).
+      // (Order-independent: descendants() is not in document order.)
+      const rows = desc.filter((d) => d.tag === "tr");
+      const cellsOf = (tr: El): El[] => tr.children.filter((c): c is El => c.type === "element" && (c.tag === "th" || c.tag === "td"));
+      const allThInThead = hasTh && ths.every((th) => ancestors(th).some((a) => a.tag === "thead"));
+      const headerRow = rows.find((r) => {
+        const cells = cellsOf(r);
+        return cells.length > 0 && cells.every((c) => c.tag === "th");
+      });
+      const allThInHeaderRow = hasTh && headerRow !== undefined && ths.every((th) => cellsOf(headerRow).includes(th));
+      const allThFirstCol =
+        hasTh &&
+        ths.every((th) => {
+          const tr = ancestors(th).find((a) => a.tag === "tr");
+          return tr !== undefined && cellsOf(tr)[0] === th;
+        });
+      if (hasTh && (hasAssoc || allThInThead || allThInHeaderRow || allThFirstCol)) continue;
+      if (!hasTh) {
+        out.push({
+          criteriaId: "1.3.1",
+          el: t,
+          msgId: "data-table-no-headers.no-th",
+        });
+      } else if (!hasAssoc) {
+        out.push({
+          criteriaId: "1.3.1",
+          el: t,
+          msgId: "data-table-no-headers.no-assoc",
+        });
+      }
+    }
+    return out;
+  },
+};
+
+const tableCaptionMissing: Rule = {
+  id: "table-caption-missing",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const t of doc.elements) {
+      if (t.tag !== "table" || isLayoutTable(t)) continue;
+      const hasCaption = t.children.some((c) => c.type === "element" && c.tag === "caption");
+      if (hasCaption || named(t)) continue;
+      out.push({
+        criteriaId: "1.3.1",
+        el: t,
+        msgId: "table-caption-missing",
+      });
+    }
+    return out;
+  },
+};
+
+const layoutTableDataMarkup: Rule = {
+  id: "layout-table-data-markup",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const t of doc.elements) {
+      if (t.tag !== "table" || !declaredLayout(t)) continue;
+      const desc = descendants(t);
+      const dataMarkup =
+        desc.some((d) => d.tag === "th") ||
+        t.children.some((c) => c.type === "element" && c.tag === "caption") ||
+        desc.some((d) => hasAttr(d, "scope") || hasAttr(d, "headers"));
+      if (!dataMarkup) continue;
+      out.push({
+        criteriaId: "1.3.1",
+        el: t,
+        msgId: "layout-table-data-markup",
+        params: { role: attr(t, "role") ?? "" },
+      });
+    }
+    return out;
+  },
+};
+
+// A sortable column header that doesn't expose its sort state. When a <th>
+// (or role=columnheader) contains a real sort control (button/link) AND signals
+// sorting (a sort/tri class or label) but carries no aria-sort, AT cannot restitute
+// the current sort order (WCAG 1.3.1). Layout tables are skipped.
+const SORT_SIGNAL = /sort|trier|tri\b/i;
+const isSortControl = (e: El): boolean => e.tag === "button" || (e.tag === "a" && hasAttr(e, "href")) || (attr(e, "role") ?? "").trim() === "button";
+const signalsSort = (e: El): boolean => SORT_SIGNAL.test(`${attr(e, "class") ?? ""} ${attr(e, "aria-label") ?? ""}`) || hasAttr(e, "data-sort");
+
+const sortableHeaderNoAriaSort: Rule = {
+  id: "sortable-header-no-aria-sort",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      const isHeader = el.tag === "th" || (attr(el, "role") ?? "").trim() === "columnheader";
+      if (!isHeader) continue;
+      if (hasAttr(el, "aria-sort")) continue; // already declares sort state (any value)
+      const table = ancestors(el).find((a) => a.tag === "table");
+      if (table && isLayoutTable(table)) continue;
+      const desc = descendants(el);
+      if (!isSortControl(el) && !desc.some(isSortControl)) continue; // no actual sort control
+      if (!signalsSort(el) && !desc.some(signalsSort)) continue; // nothing marks it as sortable
+      out.push({
+        criteriaId: "1.3.1",
+        el,
+        msgId: "sortable-header-no-aria-sort",
+      });
+    }
+    return out;
+  },
+};
+
+// ADVISORY (auditor recommendation, never an NC): an empty data cell — or one reduced to
+// a lone "-" — is announced as "blank" by screen readers. The recommendation is to add
+// sr-only text stating the absence of a value. Conservative: only bare <td>s in a data
+// table with no name, no element children, and no injected content.
+const tableEmptyDataCell: Rule = {
+  id: "table-empty-data-cell",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  advisory: true,
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const t of doc.elements) {
+      if (t.tag !== "table" || isLayoutTable(t)) continue;
+      for (const cell of descendants(t)) {
+        if (cell.tag !== "td") continue;
+        if (mayInjectContent(cell)) continue; // value supplied via slot/component/{expr}
+        if (cell.children.some((c) => c.type === "element")) continue; // holds an icon/img/control — not blank
+        if ((attr(cell, "aria-label") ?? "").trim() || hasAttr(cell, "aria-labelledby")) continue; // named another way
+        const txt = visibleText(cell);
+        if (txt !== "" && txt !== "-") continue;
+        out.push({ criteriaId: "1.3.1", el: cell, msgId: "table-empty-data-cell", advisory: true });
+      }
+    }
+    return out;
+  },
+};
+
+/** The <table> a cell belongs to (nearest table ancestor), or undefined. */
+function ownerTable(el: El, doc: Doc): El | undefined {
+  return ancestors(el).find((a) => a.tag === "table");
+}
+
+// A `headers` attribute pointing at ids that are not header cells OF THE SAME TABLE builds
+// no association at all: the screen reader announces the cell with no header context, which
+// is exactly the situation `headers` was added to prevent.
+const headersAttrDangling: Rule = {
+  id: "headers-attr-dangling",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "td" && el.tag !== "th") continue;
+      const raw = (attr(el, "headers") ?? "").trim();
+      if (!raw || raw.includes("{")) continue;
+      const table = ownerTable(el, doc);
+      if (!table) continue;
+      const inTable = new Map(
+        descendants(table)
+          .filter((d) => d.tag === "th" || d.tag === "td")
+          .map((d) => [attr(d, "id") ?? "", d]),
+      );
+      const bad = raw
+        .split(/\s+/)
+        .filter(Boolean)
+        .filter((id) => {
+          const target = inTable.get(id);
+          return !target || target === el; // absent from this table, or the cell itself
+        });
+      if (!bad.length) continue;
+      out.push({ criteriaId: "1.3.1", el, msgId: "headers-attr-dangling", params: { ids: bad.join(" ") } });
+    }
+    return out;
+  },
+};
+
+// A header cell that heads NOTHING — no data cell resolves to it, by scope or by `headers`.
+// It is announced as a header for an empty set, and the columns it looks like it covers are
+// in fact unheaded.
+const thNoDataCells: Rule = {
+  id: "th-no-data-cells",
+  criteria: ["1.3.1"],
+  severity: "mineur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const table of doc.elements) {
+      if (table.tag !== "table" || isLayoutTable(table)) continue;
+      const cells = descendants(table).filter((d) => d.tag === "td" || d.tag === "th");
+      const headers = cells.filter((c) => c.tag === "th");
+      if (!headers.length) continue;
+      const dataCells = cells.filter((c) => c.tag === "td");
+      // A table with no data cells at all is a heading-only skeleton — nothing to assign,
+      // and data-table-no-headers already owns that shape.
+      if (!dataCells.length) continue;
+      // Only a FULLY headers-wired table can be judged here: as soon as one data cell
+      // relies on implicit row/column position, an unreferenced header may still head it,
+      // and deciding that needs a real table model (colspan, rowspan, header rows).
+      if (!dataCells.every((c) => (attr(c, "headers") ?? "").trim() !== "")) continue;
+      const referenced = new Set(dataCells.flatMap((c) => (attr(c, "headers") ?? "").split(/\s+/).filter(Boolean)));
+      for (const th of headers) {
+        if (mayInjectContent(th) || !visibleText(th).trim()) continue; // empty/injected: other rules own it
+        const id = attr(th, "id") ?? "";
+        if (id && referenced.has(id)) continue; // explicitly referenced by a data cell
+        out.push({ criteriaId: "1.3.1", el: th, msgId: "th-no-data-cells" });
+      }
+    }
+    return out;
+  },
+};
+
+export const tablesRules: Rule[] = [
+  dataTableNoHeaders,
+  tableCaptionMissing,
+  layoutTableDataMarkup,
+  sortableHeaderNoAriaSort,
+  tableEmptyDataCell,
+  headersAttrDangling,
+  thNoDataCells,
+];

package/src/rules/timing.ts

@@ -0,0 +1,55 @@
+// Theme 13 — Timing & moving content (the statically-checkable slice): timed meta
+// refresh/redirect (WCAG 2.2.1) and the legacy <blink>/<marquee> auto-motion (2.2.2).
+import type { Doc } from "../parse/html.js";
+import { attr } from "../parse/html.js";
+import type { Rule, RuleFinding } from "./rule.js";
+
+const metaRefreshRedirect: Rule = {
+  id: "meta-refresh-redirect",
+  criteria: ["2.2.1"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    // Only the FIRST `http-equiv="refresh"` in document order takes effect; any later one
+    // never runs, so reporting it would be a defect that cannot happen.
+    const first = doc.elements.find((e) => e.tag === "meta" && (attr(e, "http-equiv") ?? "").toLowerCase() === "refresh");
+    for (const el of first ? [first] : []) {
+      const content = (attr(el, "content") ?? "").trim();
+      // The delay must be a bare non-negative integer. `+5`, `-5` and `5.5` are invalid
+      // per the HTML parsing rules, so the browser ignores the directive entirely —
+      // Number.parseInt would happily read "+5" as 5 and invent a time limit.
+      if (!/^\d+\s*(?:[;,]|$)/.test(content)) continue;
+      const seconds = Number.parseInt(content, 10);
+      if (!Number.isFinite(seconds) || seconds <= 0) continue; // non-numeric / instant (0s) handled elsewhere
+      if (seconds > 72000) continue; // WCAG 2.2.1 exception: a time limit longer than 20 hours is exempt
+      out.push({
+        criteriaId: "2.2.1",
+        el,
+        msgId: "meta-refresh-redirect",
+        params: { content, seconds },
+      });
+    }
+    return out;
+  },
+};
+
+const blinkMarquee: Rule = {
+  id: "blink-marquee",
+  criteria: ["2.2.2"],
+  severity: "majeur",
+  run(doc: Doc): RuleFinding[] {
+    const out: RuleFinding[] = [];
+    for (const el of doc.elements) {
+      if (el.tag !== "blink" && el.tag !== "marquee") continue;
+      out.push({
+        criteriaId: "2.2.2",
+        el,
+        msgId: "blink-marquee",
+        params: { tag: el.tag },
+      });
+    }
+    return out;
+  },
+};
+
+export const timingRules: Rule[] = [metaRefreshRedirect, blinkMarquee];

package/src/sample.ts

@@ -0,0 +1,176 @@
+// Core, STANDARD-AGNOSTIC page-sample (échantillon) mechanics. A real accessibility audit
+// runs over a representative set of served pages (+ transverse elements), not the whole
+// file tree — this validates the `sample` block of an Ultra11yConfig (hard error on
+// malformed entries, mirroring the pack-loading validation style), projects it to the
+// storageState-free shape recorded in an AuditResult, and lints a configured sample against
+// a pack's NORMATIVE methodology (which required page kinds it covers).
+//
+// SECURITY: `storageState` values are FILE PATHS (Playwright session files). Their CONTENT
+// is NEVER read here nor embedded in any output/finding/report — only the path is validated
+// as a non-empty string (plus an existsSync advisory that cites the path, never the content).
+// The required-kinds LIST is standard-specific and lives in the pack
+// (src/standards/types.ts SampleMethodology), never in this core module.
+import { existsSync } from "node:fs";
+import type { SampleConfig, SamplePage, SampleScope } from "./types.js";
+import type { SampleMethodology, SampleRequiredKind } from "./standards/types.js";
+
+export interface SampleIssue {
+  path: string; // dotted path into the sample, e.g. "sample.pages[2].url"
+  message: string;
+}
+
+export interface SampleValidation {
+  ok: boolean;
+  issues: SampleIssue[];
+  // Advisory only (never block): e.g. a storageState PATH that does not exist on disk.
+  // The message cites the path string only — the file's CONTENT is never read.
+  warnings: SampleIssue[];
+  sample?: SampleConfig; // the normalized sample, present only when ok
+}
+
+/** A served URL (http(s)://) or a local HTML file path — the two things `scan` can target. */
+function looksLikeTarget(u: string): boolean {
+  return /^https?:\/\//i.test(u) || /^(\.\.?[/\\]|[/\\])/.test(u) || /\.x?html?$/i.test(u);
+}
+
+/** Validate an untrusted `sample` config block. Any malformed entry is a hard error; a
+ *  storageState path that does not exist on disk is a WARNING (advisory — the scan would
+ *  fail to load the session, but the config itself is well-formed). */
+export function validateSample(raw: unknown): SampleValidation {
+  const issues: SampleIssue[] = [];
+  const warnings: SampleIssue[] = [];
+  const err = (path: string, message: string) => issues.push({ path, message });
+  const warn = (path: string, message: string) => warnings.push({ path, message });
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    err("sample", "sample must be an object { pages: [...], transverse?: [...] }");
+    return { ok: false, issues, warnings };
+  }
+  const s = raw as Record<string, unknown>;
+  const pages = Array.isArray(s.pages) ? (s.pages as unknown[]) : null;
+  if (!pages || pages.length === 0) err("sample.pages", "sample.pages must be a non-empty array");
+  const ids = new Set<string>();
+  pages?.forEach((pg, i) => {
+    if (typeof pg !== "object" || pg === null || Array.isArray(pg)) {
+      err(`sample.pages[${i}]`, "each page must be an object { id, name, url, auth?, storageState?, notes? }");
+      return;
+    }
+    const p = pg as Record<string, unknown>;
+    const id = p.id;
+    if (typeof id !== "string" || id.trim() === "") {
+      err(`sample.pages[${i}].id`, "page id must be a non-empty string");
+    } else {
+      if (ids.has(id)) err(`sample.pages[${i}].id`, `duplicate page id "${id}"`);
+      ids.add(id);
+    }
+    if (typeof p.name !== "string" || p.name.trim() === "") err(`sample.pages[${i}].name`, "page name must be a non-empty string");
+    if (typeof p.url !== "string" || p.url.trim() === "") err(`sample.pages[${i}].url`, "page url must be a non-empty string");
+    else if (!looksLikeTarget(p.url)) err(`sample.pages[${i}].url`, `malformed url "${p.url}" (expected an http(s):// URL or an HTML file path)`);
+    if (p.auth !== undefined && typeof p.auth !== "boolean") err(`sample.pages[${i}].auth`, "auth must be a boolean");
+    if (p.storageState !== undefined && (typeof p.storageState !== "string" || p.storageState.trim() === "")) {
+      err(`sample.pages[${i}].storageState`, "storageState must be a non-empty file path string");
+    } else if (typeof p.storageState === "string" && p.storageState.trim() !== "" && !existsSync(p.storageState)) {
+      // Path string only in the message — the file's content is never read here or anywhere.
+      warn(
+        `sample.pages[${i}].storageState`,
+        `storageState path not found: "${p.storageState}" (resolved from the current directory) — the scan will not be able to load this session`,
+      );
+    }
+    if (p.notes !== undefined && typeof p.notes !== "string") err(`sample.pages[${i}].notes`, "notes must be a string");
+  });
+
+  if (s.transverse !== undefined) {
+    if (!Array.isArray(s.transverse)) {
+      err("sample.transverse", "transverse must be an array of strings");
+    } else {
+      (s.transverse as unknown[]).forEach((t, i) => {
+        if (typeof t !== "string" || t.trim() === "") err(`sample.transverse[${i}]`, "transverse entries must be non-empty strings");
+      });
+    }
+  }
+
+  const ok = issues.length === 0;
+  return { ok, issues, warnings, sample: ok ? normalizeSample(s) : undefined };
+}
+
+function normalizeSample(s: Record<string, unknown>): SampleConfig {
+  const pages = (s.pages as Record<string, unknown>[]).map((p) => ({
+    id: String(p.id),
+    name: String(p.name),
+    url: String(p.url),
+    ...(typeof p.auth === "boolean" ? { auth: p.auth } : {}),
+    ...(typeof p.storageState === "string" ? { storageState: p.storageState } : {}),
+    ...(typeof p.notes === "string" ? { notes: p.notes } : {}),
+  }));
+  const transverse = Array.isArray(s.transverse) ? (s.transverse as string[]).map(String) : undefined;
+  return { pages, ...(transverse?.length ? { transverse } : {}) };
+}
+
+/** Project a validated sample to the storageState-free shape recorded on an AuditResult /
+ *  DynamicResult. The Playwright session PATH is deliberately dropped — never persisted. */
+export function sampleScope(sample: SampleConfig): SampleScope {
+  return {
+    pages: sample.pages.map((p) => ({
+      id: p.id,
+      name: p.name,
+      url: p.url,
+      ...(p.auth !== undefined ? { auth: p.auth } : {}),
+      ...(p.notes ? { notes: p.notes } : {}),
+    })),
+    ...(sample.transverse?.length ? { transverse: sample.transverse } : {}),
+  };
+}
+
+export interface SampleLint {
+  missing: SampleRequiredKind[]; // required kinds not covered by any configured page
+}
+
+// Accent-insensitive, case-folded normalization for fuzzy matching (RGAA labels carry
+// diacritics and apostrophes; a user's page names rarely match verbatim).
+const norm = (s: string): string =>
+  s
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .replace(/['’]/g, " ")
+    .toLowerCase();
+
+// SHORT keywords (≤ 5 chars: aide, plan, faq, help, menu, home, index…) must match as a
+// WHOLE WORD — bare substring matching over-credited ("plaide" → aide, "planning" → plan).
+// Longer keywords keep substring matching so a stem still hits ("contact" → "contactez-nous").
+const SHORT_KEYWORD = 5;
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function keywordMatches(haystack: string, keyword: string): boolean {
+  if (keyword.length > SHORT_KEYWORD) return haystack.includes(keyword);
+  return new RegExp(`(^|[^a-z0-9])${escapeRe(keyword)}($|[^a-z0-9])`).test(haystack);
+}
+
+/** Lint a configured sample against a standard's normative methodology: which required page
+ *  KINDS does no configured page cover? Fuzzy — matches a kind's keywords against each
+ *  page's name/notes/url/id (accent-insensitive; whole-word for short keywords). Two
+ *  documented heuristic credits: the "transverse" kind is covered when the sample declares
+ *  any transverse element, and the "representative pages" kind is covered when the sample
+ *  holds ≥ 2 pages (any multi-page sample de facto carries representative pages beyond a
+ *  single entry point — this stops a constant false nag). Advisory output, never a gate. */
+export function lintSample(sample: SampleConfig, methodology: SampleMethodology): SampleLint {
+  const haystacks = sample.pages.map((p) => norm([p.name, p.notes ?? "", p.url, p.id].join(" ")));
+  const transverseHay = norm((sample.transverse ?? []).join(" "));
+  const hasTransverse = (sample.transverse ?? []).length > 0;
+  const missing: SampleRequiredKind[] = [];
+  for (const kind of methodology.requiredKinds) {
+    const kws = kind.keywords.map(norm).filter(Boolean);
+    const covered =
+      haystacks.some((h) => kws.some((k) => keywordMatches(h, k))) ||
+      (transverseHay !== "" && kws.some((k) => keywordMatches(transverseHay, k))) ||
+      (hasTransverse && /transverse/.test(kind.id)) ||
+      (/representative|representatif/.test(kind.id) && sample.pages.length >= 2);
+    if (!covered) missing.push(kind);
+  }
+  return { missing };
+}
+
+/** Localized label for a required kind (default-locale-first fallback). */
+export function kindLabel(kind: SampleRequiredKind, locale = "fr"): string {
+  return kind.label[locale] ?? Object.values(kind.label)[0] ?? kind.id;
+}
+
+export type { SamplePage };