ultra11y 2.22.0

package/src/rules/cross-registry.ts

@@ -0,0 +1,264 @@
+// The cross-file rule set + runner. Two raise findings the graph makes visible,
+// two suppress single-file findings the graph proves are false positives. Findings
+// fold into the same AuditResult; suppressions are applied (by ruleId + line) to
+// the same Doc's single-file findings in audit.ts.
+import type { Doc, El } from "../parse/html.js";
+import type { Finding } from "../types.js";
+import { attr, hasAttr, visibleText } from "../parse/html.js";
+import { isIntrinsic } from "../parse/jsx-bridge.js";
+import { isFullDocument } from "./rule.js";
+import { type CrossRule, type Suppression, crossToFinding } from "./cross-rule.js";
+import { type DepGraph, resolveUsage, idDefinedAnywhere, htmlLangProvidedFor } from "../graph/graph.js";
+import { NOTE_CATALOG } from "../messages.js";
+
+const SEVERITY_ORDER: Record<string, number> = { bloquant: 0, majeur: 1, mineur: 2 };
+const NAME_PROPS = ["aria-label", "aria-labelledby", "title", "label", "alt"];
+
+// A JSX component usage (PascalCase / namespaced); excludes intrinsic tags and #fragment.
+function isComponentUsage(el: El): boolean {
+  return !isIntrinsic(el.tag) && el.tag !== "#fragment";
+}
+
+// Could this component usage already be carrying an accessible name?
+function usageHasName(el: El): boolean {
+  if (el.spread) return true; // {...props} may inject a name — stay conservative
+  if (visibleText(el) !== "") return true;
+  return NAME_PROPS.some((p) => (attr(el, p) ?? "").trim() !== "");
+}
+
+function isNameableControl(el: El): boolean {
+  if (el.tag === "button" || el.tag === "select" || el.tag === "textarea") return true;
+  if (el.tag === "a" && hasAttr(el, "href")) return true;
+  if (el.tag === "input" || el.tag === "img") return true;
+  return false;
+}
+
+// 1) An icon-only component that CAN be named (spread/aria-prop/{children}) but is
+//    used without a name → flag at the usage, point at the definition.
+const crossIconOnlyUnnamed: CrossRule = {
+  id: "cross-icon-only-unnamed",
+  criteria: ["4.1.2"],
+  severity: "bloquant",
+  run(doc, graph) {
+    const findings = [];
+    for (const el of doc.elements) {
+      if (!isComponentUsage(el)) continue;
+      const def = resolveUsage(graph, doc.file, el.tag);
+      if (!def?.rendersIconOnlyControl || !def.acceptsName) continue;
+      if (usageHasName(el)) continue;
+      findings.push({
+        criteriaId: "4.1.2",
+        el,
+        msgId: "cross-icon-only-unnamed",
+        params: { tag: el.tag, defName: def.name },
+        related: {
+          file: def.file,
+          line: def.line,
+          col: def.col,
+          selectorHint: def.name,
+          note: NOTE_CATALOG["related.icon-component-def"]!.en,
+          noteId: "related.icon-component-def",
+        },
+      });
+    }
+    return { findings, suppress: [] };
+  },
+};
+
+// 2) A document whose <html> has no lang, but a wrapper/layout it imports declares
+//    one → suppress the missing-lang false positive.
+const crossPageLang: CrossRule = {
+  id: "cross-page-lang",
+  criteria: ["3.1.1"],
+  severity: "bloquant",
+  run(doc, graph) {
+    const suppress: Suppression[] = [];
+    const html = doc.elements.find((e) => e.tag === "html");
+    if (html && (attr(html, "lang") ?? "") === "" && htmlLangProvidedFor(graph, doc.file)) {
+      suppress.push({ ruleId: "html-lang-missing", line: html.line, reason: "lang fourni par un layout/wrapper importé" });
+    }
+    return { findings: [], suppress };
+  },
+};
+
+// 3) An intrinsic control/img that spreads {...props} can be named by its parent →
+//    suppress single-file name-missing findings on it (the component def site).
+const SUPPRESSIBLE_BY_SPREAD = ["icon-only-control-unnamed", "button-empty-name", "link-empty-name", "control-label-missing", "img-alt-missing"];
+const crossAriaForwarding: CrossRule = {
+  id: "cross-aria-forwarding",
+  criteria: ["4.1.2"],
+  severity: "bloquant",
+  run(doc) {
+    const suppress: Suppression[] = [];
+    for (const el of doc.elements) {
+      if (!el.spread || !isNameableControl(el)) continue;
+      for (const ruleId of SUPPRESSIBLE_BY_SPREAD) suppress.push({ ruleId, line: el.line, reason: "nommable via {...props} au point d'utilisation" });
+    }
+    return { findings: [], suppress };
+  },
+};
+
+// 4) A skip-link target that lives in another file (imported layout/component) →
+//    suppress the in-page "broken anchor" false positive. Only on full documents
+//    (mirrors skip-link-target-missing's page scope). A target defined NOWHERE is
+//    left to the single-file rule (true positive).
+const crossSkipLinkTarget: CrossRule = {
+  id: "cross-skip-link-target",
+  criteria: ["2.4.1"],
+  severity: "majeur",
+  run(doc, graph) {
+    const suppress: Suppression[] = [];
+    if (!isFullDocument(doc)) return { findings: [], suppress };
+    const sameDocHas = (id: string): boolean => doc.byId.has(id) || doc.elements.some((e) => attr(e, "name") === id);
+    for (const el of doc.elements) {
+      if (el.tag !== "a") continue;
+      const href = attr(el, "href") ?? "";
+      if (!href.startsWith("#") || href === "#") continue;
+      let id = href.slice(1);
+      try {
+        id = decodeURIComponent(id);
+      } catch {
+        /* keep raw */
+      }
+      if (sameDocHas(id)) continue; // single-file rule won't fire anyway
+      if (idDefinedAnywhere(graph, id))
+        suppress.push({ ruleId: "skip-link-target-missing", line: el.line, reason: `cible #${id} définie dans un autre fichier du graphe` });
+    }
+    return { findings: [], suppress };
+  },
+};
+
+// 5) A component usage passes a name-bearing prop, but the resolved component renders a
+//    control that neither spreads {...props} nor forwards a name to it → the prop-drilled
+//    accessible name is lost across the boundary. Raise at the usage, point at the control.
+const NAME_PROPS_PASSED = ["aria-label", "aria-labelledby", "title", "label"];
+const crossPropDrilledNameLost: CrossRule = {
+  id: "cross-prop-drilled-name-lost",
+  criteria: ["4.1.2"],
+  severity: "majeur",
+  run(doc, graph) {
+    const findings = [];
+    for (const el of doc.elements) {
+      if (!isComponentUsage(el)) continue;
+      const passed = NAME_PROPS_PASSED.find((p) => (attr(el, p) ?? "").trim() !== "");
+      if (!passed) continue;
+      const def = resolveUsage(graph, doc.file, el.tag);
+      // Fire only when the control would otherwise be NAMELESS: it must render a control,
+      // not accept a name from props, AND not already carry a literal name (else the passed
+      // prop is dead code, not a real 4.1.2 non-conformity).
+      if (!def?.hasControl || def.acceptsName || def.controlHasName) continue;
+      findings.push({
+        criteriaId: "4.1.2",
+        el,
+        msgId: "cross-prop-drilled-name-lost",
+        params: { tag: el.tag, passed, defName: def.name },
+        related: {
+          file: def.file,
+          line: def.line,
+          col: def.col,
+          selectorHint: def.name,
+          note: NOTE_CATALOG["related.name-drop-def"]!.en,
+          noteId: "related.name-drop-def",
+        },
+      });
+    }
+    return { findings, suppress: [] };
+  },
+};
+
+// 6) An aria-*by / aria-controls reference whose target id is defined in ANOTHER file of
+//    the graph → suppress the single-file aria-ref-missing-id false positive. Conservative:
+//    suppress only when EVERY in-page-missing id on the element resolves elsewhere, so a
+//    genuinely-dangling reference is never hidden.
+const ARIA_IDREFS = [
+  "aria-labelledby",
+  "aria-describedby",
+  "aria-controls",
+  "aria-owns",
+  "aria-details",
+  "aria-errormessage",
+  "aria-flowto",
+  "aria-activedescendant",
+];
+const crossAriaRefCrossFile: CrossRule = {
+  id: "cross-aria-ref-cross-file",
+  criteria: ["4.1.2"],
+  severity: "majeur",
+  run(doc, graph) {
+    const suppress: Suppression[] = [];
+    for (const el of doc.elements) {
+      const missing: string[] = [];
+      for (const a of ARIA_IDREFS) {
+        const v = (attr(el, a) ?? "").trim();
+        if (!v || v.includes("{")) continue; // dynamic JSX expression — not a literal id list
+        for (const id of v.split(/\s+/).filter(Boolean)) if (!doc.byId.has(id)) missing.push(id);
+      }
+      if (!missing.length) continue; // the single-file rule won't fire on this element
+      if (missing.every((id) => idDefinedAnywhere(graph, id)))
+        suppress.push({ ruleId: "aria-ref-missing-id", line: el.line, reason: "cible(s) définie(s) dans un autre fichier du graphe" });
+    }
+    return { findings: [], suppress };
+  },
+};
+
+// 7) A <label for="x"> or an empty heading named via aria-labelledby whose target id lives
+//    in ANOTHER file of the graph → suppress the single-file label-for-dangling /
+//    empty-heading false positive (the field / label is rendered by an imported component).
+//    Mirrors cross-aria-ref-cross-file's conservatism: only when the id resolves elsewhere.
+const HEADING_TAG = /^h[1-6]$/;
+const crossNameRefCrossFile: CrossRule = {
+  id: "cross-name-ref-cross-file",
+  criteria: ["1.3.1"],
+  severity: "majeur",
+  run(doc, graph) {
+    const suppress: Suppression[] = [];
+    for (const el of doc.elements) {
+      if (el.tag === "label") {
+        const f = (attr(el, "for") ?? "").trim();
+        if (f && !f.includes("{") && !doc.byId.has(f) && idDefinedAnywhere(graph, f))
+          suppress.push({ ruleId: "label-for-dangling", line: el.line, reason: `cible #${f} définie dans un autre fichier du graphe` });
+      }
+      const isHeading = HEADING_TAG.test(el.tag) || (attr(el, "role") ?? "") === "heading";
+      if (isHeading) {
+        const lb = (attr(el, "aria-labelledby") ?? "").trim();
+        const ids = lb.includes("{") ? [] : lb.split(/\s+/).filter(Boolean);
+        if (ids.length && ids.every((id) => !doc.byId.has(id) && idDefinedAnywhere(graph, id)))
+          suppress.push({ ruleId: "empty-heading", line: el.line, reason: "intitulé fourni par un aria-labelledby défini dans un autre fichier" });
+      }
+    }
+    return { findings: [], suppress };
+  },
+};
+
+export const CROSS_RULES: CrossRule[] = [
+  crossIconOnlyUnnamed,
+  crossPageLang,
+  crossAriaForwarding,
+  crossSkipLinkTarget,
+  crossPropDrilledNameLost,
+  crossAriaRefCrossFile,
+  crossNameRefCrossFile,
+];
+
+/** Rule ids that can raise a finding (for dataset/registry cross-checks). Suppressors
+ *  raise none and are intentionally excluded. */
+export function crossRuleIds(): string[] {
+  return ["cross-icon-only-unnamed", "cross-prop-drilled-name-lost"];
+}
+
+export interface CrossRunResult {
+  findings: Finding[];
+  suppress: Suppression[];
+}
+
+export function runCrossRules(doc: Doc, graph: DepGraph): CrossRunResult {
+  const findings: Finding[] = [];
+  const suppress: Suppression[] = [];
+  for (const rule of CROSS_RULES) {
+    const r = rule.run(doc, graph);
+    for (const cf of r.findings) findings.push(crossToFinding(doc, rule.id, rule.severity, cf));
+    suppress.push(...r.suppress);
+  }
+  findings.sort((a, b) => a.line - b.line || a.col - b.col || SEVERITY_ORDER[a.severity]! - SEVERITY_ORDER[b.severity]!);
+  return { findings, suppress };
+}

package/src/rules/cross-rule.ts

@@ -0,0 +1,83 @@
+// Contract for cross-file rules. Unlike a single-file Rule (which sees one Doc),
+// a CrossRule also sees the dependency graph, and can BOTH raise findings (anchored
+// at a usage site, with the related definition site attached) AND suppress
+// single-file findings that the graph proves are false positives (e.g. a skip-link
+// target that lives in an imported layout). Cross findings fold into the same
+// Finding/AuditResult as everything else.
+import type { Doc, El } from "../parse/html.js";
+import type { Finding, Severity } from "../types.js";
+import { snippet } from "../parse/html.js";
+import { selectorOf } from "./rule.js";
+import { MSG_CATALOG, type MsgParams } from "../messages.js";
+import type { DepGraph } from "../graph/graph.js";
+
+export interface RelatedSite {
+  file: string;
+  line: number;
+  col: number;
+  selectorHint: string;
+  // Canonical baked ENGLISH prose (mirrors Finding.message/remediation); `noteId` is an
+  // optional key into src/messages.ts's NOTE_CATALOG, resolved at render time by
+  // `resolveNote` — see types.ts `Finding.related` for the full contract.
+  note: string;
+  noteId?: string;
+}
+
+export interface CrossFinding {
+  criteriaId: string;
+  el: El; // anchor (the usage site) for line/col/snippet/selector
+  /** catalog key into MSG_CATALOG (src/messages.ts) — mirrors RuleFinding.msgId. */
+  msgId: string;
+  params?: MsgParams;
+  severity?: Severity;
+  selectorHint?: string;
+  related?: RelatedSite; // the OTHER site (definition) that explains the finding
+}
+
+// Drop a single-file finding the graph proves is a false positive. Matched on the
+// same Doc by ruleId + anchor line.
+export interface Suppression {
+  ruleId: string;
+  line: number;
+  reason: string;
+}
+
+export interface CrossRuleResult {
+  findings: CrossFinding[];
+  suppress: Suppression[];
+}
+
+export interface CrossRule {
+  id: string;
+  criteria: string[];
+  severity: Severity;
+  run(doc: Doc, graph: DepGraph): CrossRuleResult;
+}
+
+/** Normalise a CrossFinding into a Finding (mirrors rule.ts toFinding, plus related). */
+export function crossToFinding(doc: Doc, ruleId: string, def: Severity, cf: CrossFinding): Finding {
+  const entry = MSG_CATALOG[cf.msgId];
+  if (!entry) {
+    throw new Error(`crossToFinding: msgId "${cf.msgId}" (rule "${ruleId}") is not in MSG_CATALOG — add it to src/messages.ts.`);
+  }
+  const params = cf.params ?? {};
+  return {
+    ruleId,
+    criteriaId: cf.criteriaId,
+    file: doc.file,
+    line: cf.el.line,
+    col: cf.el.col,
+    selectorHint: cf.selectorHint ?? selectorOf(cf.el),
+    severity: cf.severity ?? def,
+    message: entry.message.en(params),
+    remediation: entry.remediation.en(params),
+    msg: cf.params ? { id: cf.msgId, params: cf.params } : { id: cf.msgId },
+    snippet: snippet(doc, cf.el),
+    ...(doc.lossy ? {} : { sourceStart: cf.el.start, sourceEnd: cf.el.end }),
+    // Mirror toFinding: an SFC/lossy-JSX source is less trustworthy (slots/dynamic content /
+    // regex transform), so its cross-file findings are provisional too — otherwise a cross
+    // finding reads as definitive while the per-doc findings in the same file are preliminary.
+    ...(doc.kind === "sfc" || doc.kind === "jsx-lossy" ? { preliminary: true } : {}),
+    ...(cf.related ? { related: cf.related } : {}),
+  };
+}