ultra11y 2.22.0

package/src/output.ts

@@ -0,0 +1,108 @@
+// Output helpers: a tiny fr/en string table and the human-readable `audit`
+// summary (the --json path prints the AuditResult verbatim instead).
+import type { AuditResult, Lang, Severity } from "./types.js";
+import type { CaptureCoverage } from "./capture.js";
+import { guidelineTitle } from "./wcag.js";
+import { resolveMessage } from "./messages.js";
+
+type Key =
+  | "summaryTitle"
+  | "files"
+  | "autoConformance"
+  | "guideline"
+  | "findingsTitle"
+  | "noFindings"
+  | "residualTitle"
+  | "manualNote"
+  | "renderedNote"
+  | "sfcNote"
+  | "capturesNote";
+
+const STR: Record<Lang, Record<Key, string>> = {
+  fr: {
+    summaryTitle: "Audit WCAG 2.2 AA (moteur statique ultra11y)",
+    files: "fichiers analysés",
+    autoConformance: "réussite automatique (vérifications statiques)",
+    guideline: "Règle WCAG",
+    findingsTitle: "Non-conformités détectées",
+    noFindings: "Aucune non-conformité détectée par le moteur statique.",
+    residualTitle: "À adjuger (jugement / rendu)",
+    manualNote: "critères non décidés par le moteur — à adjuger par l'agent IA (`verify --manual`, gaté), rendu via `scan`.",
+    renderedNote: "fichier(s) rendent des composants de bibliothèque non analysés en source — auditez le build (render) ou scan",
+    sfcNote:
+      "composant(s) .vue/.svelte/.astro audité(s) en SOURCE (template) — slots et liaisons dynamiques invisibles : verdict préliminaire, auditez le rendu (render/scan)",
+    capturesNote: "fichier(s) de capture rendus audités à pleine fidélité (DOM réel) — le vrai HTML produit",
+  },
+  en: {
+    summaryTitle: "WCAG 2.2 AA audit (ultra11y static engine)",
+    files: "files analysed",
+    autoConformance: "automatic static-check pass rate",
+    guideline: "WCAG guideline",
+    findingsTitle: "Non-conformities detected",
+    noFindings: "No non-conformity detected by the static engine.",
+    residualTitle: "To adjudicate (judgment / rendering)",
+    manualNote: "criteria the engine cannot decide — adjudicated by the AI agent (`verify --manual`, gated), rendering via `scan`.",
+    renderedNote: "file(s) render component-library output not analysed from source — audit the build (render) or scan",
+    sfcNote:
+      ".vue/.svelte/.astro file(s) audited as SOURCE (template) — slots and dynamic bindings are invisible: preliminary verdict, audit the rendered output (render/scan)",
+    capturesNote: "rendered capture file(s) audited at full fidelity (real DOM) — the true produced HTML",
+  },
+};
+
+export function t(lang: Lang, key: Key): string {
+  return STR[lang][key];
+}
+
+const ICON: Record<Severity, string> = { bloquant: "🔴", majeur: "🟠", mineur: "🟡" };
+
+export function auditSummary(r: AuditResult, lang: Lang): string {
+  const lines: string[] = [];
+  lines.push(`${t(lang, "summaryTitle")} — ${r.date}`);
+  lines.push(`${r.scope.files} ${t(lang, "files")} · ${r.conformancePct}% ${t(lang, "autoConformance")}`);
+  lines.push("");
+  lines.push(`${t(lang, "guideline")}        C  NC  NA  ⏳`);
+  for (const g of r.guidelines) {
+    // `g.title` is the baked-in English title (JSON back-compat); resolve by key + lang.
+    const name = `${g.key} ${guidelineTitle(g.key, lang) ?? g.title}`.padEnd(28).slice(0, 28);
+    lines.push(`${name} ${String(g.c).padStart(2)}  ${String(g.nc).padStart(2)}  ${String(g.na).padStart(2)}  ${String(g.manual).padStart(2)}`);
+  }
+  lines.push("");
+  if (r.findings.length === 0) {
+    lines.push(t(lang, "noFindings"));
+  } else {
+    lines.push(`${t(lang, "findingsTitle")} (${r.findings.length}) :`);
+    for (const f of r.findings.slice(0, 20)) {
+      lines.push(`  ${ICON[f.severity]} [${f.criteriaId}] ${f.file}:${f.line}  ${resolveMessage(f, lang)}`);
+    }
+    if (r.findings.length > 20) lines.push(`  … (+${r.findings.length - 20})`);
+  }
+  lines.push("");
+  lines.push(`${t(lang, "residualTitle")} : ${r.residualRisks.length} ${t(lang, "manualNote")}`);
+  if (r.scope.rendered) lines.push(`🧩 ${r.scope.rendered.files} ${t(lang, "renderedNote")} (${r.scope.rendered.opaqueLibraries.join(", ")}).`);
+  if (r.scope.sourceTemplate) lines.push(`🧩 ${r.scope.sourceTemplate.files} ${t(lang, "sfcNote")} (${r.scope.sourceTemplate.extensions.join(", ")}).`);
+  if (r.scope.captures) lines.push(`✅ ${r.scope.captures.files} ${t(lang, "capturesNote")}.`);
+  return lines.join("\n");
+}
+
+/** Human-readable rendered-capture coverage: covered vs opaque-source-only blind spots.
+ *  Reused by `audit --require-captures` (as a gate note) and `render --coverage`. */
+export function captureCoverageSummary(cov: CaptureCoverage, lang: Lang): string {
+  const fr = lang === "fr";
+  const lines: string[] = [];
+  if (cov.total === 0) {
+    lines.push(fr ? "Couverture captures : aucun composant à couvrir dans le périmètre." : "Capture coverage: no components to cover in scope.");
+  } else {
+    lines.push(
+      fr
+        ? `Couverture captures : ${cov.covered.length}/${cov.total} composant(s) couvert(s) par un rendu.`
+        : `Capture coverage: ${cov.covered.length}/${cov.total} component(s) covered by a render.`,
+    );
+    if (cov.blindSpots.length) {
+      lines.push(fr ? "Angles morts (audités sur source opaque uniquement) :" : "Blind spots (audited from opaque source only):");
+      for (const k of cov.blindSpots) lines.push(`  · ${k}`);
+    }
+  }
+  if (cov.unattributed)
+    lines.push(fr ? `${cov.unattributed} capture(s) sans provenance (non rattachée·s).` : `${cov.unattributed} capture(s) without provenance (unattributed).`);
+  return lines.join("\n");
+}

package/src/pack.ts

@@ -0,0 +1,187 @@
+// `pack` — the standards-pack toolbox and the anti-hallucination GATE for AI-assisted
+// ingestion. `pack check <pack.json> [--guidance <g.json>]` validates a pack (via the
+// shared validatePack) and, if given, its guidance dataset: every entry must resolve to a
+// REAL pack criterion, map to well-formed SCs, and carry code examples that actually
+// parse. `pack scaffold` prints a minimal valid StandardPack skeleton to fill in. This is
+// how an external rule source (RGAA SocialGouv/etalab, or any other standard) is turned
+// into a pack the runtime `--pack` loader can trust: the agent drafts, the gate refuses
+// fabrication (a bogus criterion id or SC, or an unparseable example, fails loudly).
+import { existsSync } from "node:fs";
+import { readText } from "./util.js";
+import { validatePack, classifySc } from "./standards/validate.js";
+import { getCriterion } from "./standards/pack.js";
+import { ruleIds as engineRuleIds } from "./rules/registry.js";
+import type { StandardPack } from "./standards/types.js";
+import type { GuidanceDataset, GuidanceExample } from "./guidance/types.js";
+import { parseHtml } from "./parse/html.js";
+import { parseJsxAst } from "./parse/jsx-ast.js";
+
+export interface PackCheckResult {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/** Confirm a guidance code example actually parses (JSX via the real Babel parser; HTML
+ *  via htmlparser2). Returns an error message, or null when it parses. */
+function exampleParses(ex: GuidanceExample): string | null {
+  for (const code of [ex.bad, ex.good]) {
+    if (!code) continue;
+    if (ex.lang === "jsx") {
+      if (!parseJsxAst(code)) return `unparseable JSX example: ${code.slice(0, 48)}…`;
+    } else if (ex.lang === "html") {
+      try {
+        parseHtml(code, "<guidance>.html", false);
+      } catch (e) {
+        return `unparseable HTML example (${e instanceof Error ? e.message : String(e)})`;
+      }
+    }
+    // css: the engine only parses inline style — guidance css snippets are not gated.
+  }
+  return null;
+}
+
+/** Validate a guidance dataset against the (already-validated) pack it augments. Shared by
+ *  `pack check` and the runtime guidance loader (src/config.ts) so the same gate applies. */
+export function checkGuidance(ds: unknown, pack: StandardPack): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (typeof ds !== "object" || ds === null || !Array.isArray((ds as GuidanceDataset).entries)) {
+    errors.push("guidance: must be an object with an entries[] array");
+    return { errors, warnings };
+  }
+  const dataset = ds as GuidanceDataset;
+  if (dataset.pack && dataset.pack !== pack.key) warnings.push(`guidance: dataset.pack "${dataset.pack}" ≠ pack key "${pack.key}"`);
+  dataset.entries.forEach((e, i) => {
+    const at = `guidance.entries[${i}]${e.id ? ` (${e.id})` : ""}`;
+    const crit = e.criterionId ? getCriterion(pack, e.criterionId) : undefined;
+    if (!e.criterionId) {
+      errors.push(`${at}: criterionId is unresolved — resolve it to a real ${pack.key} criterion (no fabrication)`);
+    } else if (!crit) {
+      errors.push(`${at}: criterionId "${e.criterionId}" does not exist in ${pack.key}`);
+    }
+    if (!Array.isArray(e.wcag) || e.wcag.length === 0) {
+      errors.push(`${at}: must map to at least one WCAG SC`);
+    } else {
+      for (const sc of e.wcag) {
+        switch (classifySc(sc)) {
+          case "malformed":
+            errors.push(`${at}: malformed SC "${sc}"`);
+            break;
+          case "unknown":
+            errors.push(`${at}: SC "${sc}" is not a recognized WCAG success criterion — fabricated?`);
+            break;
+          case "out-of-core":
+            warnings.push(`${at}: SC "${sc}" is a real WCAG AAA success criterion, outside the WCAG 2.2 AA core`);
+            break;
+          case "removed":
+            warnings.push(`${at}: SC "${sc}" is a real but removed WCAG success criterion (obsolete)`);
+            break;
+        }
+      }
+      if (crit) {
+        const extra = e.wcag.filter((sc) => !crit.wcag.includes(sc));
+        if (extra.length) warnings.push(`${at}: SC(s) ${extra.join(", ")} not in criterion ${crit.id} mapping (${crit.wcag.join(", ")})`);
+      }
+    }
+    if (!Array.isArray(e.examples) || e.examples.length === 0) {
+      warnings.push(`${at}: no code examples`);
+    } else {
+      e.examples.forEach((ex, j) => {
+        const bad = exampleParses(ex);
+        if (bad) errors.push(`${at}.examples[${j}]: ${bad}`);
+      });
+    }
+  });
+  return { errors, warnings };
+}
+
+/** Run `pack check`: validate a pack file and (optionally) its guidance dataset. */
+export function runPackCheck(packPath: string, guidancePath: string | undefined): PackCheckResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (!existsSync(packPath)) return { ok: false, errors: [`pack file not found: ${packPath}`], warnings };
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readText(packPath));
+  } catch {
+    return { ok: false, errors: [`${packPath}: not valid JSON`], warnings };
+  }
+  // Lint the artifact's internal consistency — no registry-collision check (we are
+  // checking a file, not registering it), so the built-in rgaa.json passes `pack check`.
+  const v = validatePack(raw);
+  for (const issue of v.issues) (issue.severity === "error" ? errors : warnings).push(`${issue.path ? `${issue.path}: ` : ""}${issue.message}`);
+  // Advisory: an appliesTo ruleId unknown to the engine registry is a WARNING, not a hard
+  // error — a pack may target a renamed/future rule, and axe:*/dyn-*/agent:* namespaced ids
+  // (dynamic-tier + agent-adjudicated findings) are legitimately outside the static registry.
+  if (v.ok && v.pack) {
+    const known = new Set(engineRuleIds());
+    const isNamespaced = (r: string) => /^(axe:|dyn-|agent:)/.test(r);
+    // A pack's OWN declarative rules are legitimate ruleIds (`pack:<key>:<id>`).
+    const ownRuleIds = new Set((v.pack.rules ?? []).map((r) => `pack:${v.pack!.key}:${r.id}`));
+    const resolvable = (r: string) => isNamespaced(r) || known.has(r) || r.startsWith(`pack:${v.pack!.key}:`) || ownRuleIds.has(r);
+    for (const c of v.pack.criteria) {
+      for (const r of c.appliesTo?.ruleIds ?? []) {
+        if (!resolvable(r)) warnings.push(`criteria "${c.id}": appliesTo ruleId "${r}" is not a known engine rule (renamed/future?)`);
+      }
+    }
+    // Overrides target a finding ruleId — a core engine rule, an axe:/dyn-/agent: id, or
+    // one of this pack's own declarative rules. An unresolvable key is advisory (a pack may
+    // target a future rule), never a hard error.
+    for (const key of Object.keys(v.pack.overrides ?? {})) {
+      if (!resolvable(key)) warnings.push(`overrides: ruleId "${key}" is not a known engine rule or a rule of this pack (renamed/future?)`);
+    }
+  }
+  if (v.ok && v.pack && guidancePath) {
+    if (!existsSync(guidancePath)) {
+      errors.push(`guidance file not found: ${guidancePath}`);
+    } else {
+      let gRaw: unknown;
+      try {
+        gRaw = JSON.parse(readText(guidancePath));
+      } catch {
+        errors.push(`${guidancePath}: not valid JSON`);
+      }
+      if (gRaw !== undefined) {
+        const g = checkGuidance(gRaw, v.pack);
+        errors.push(...g.errors);
+        warnings.push(...g.warnings);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/** A minimal, valid StandardPack skeleton (for `pack scaffold` — the agent fills it). */
+export function packScaffold(): string {
+  return JSON.stringify(
+    {
+      key: "mypack",
+      name: "MyPack",
+      fullName: "My national accessibility standard",
+      org: "Org",
+      country: "XX",
+      baseVersion: "1.0",
+      wcagVersion: "2.2",
+      locales: ["en"],
+      defaultLocale: "en",
+      license: "…",
+      source: "https://…",
+      attribution: "… © …",
+      idPattern: "^\\d+\\.\\d+$",
+      vocabulary: {
+        theme: { en: "Theme" },
+        criterion: { en: "Criterion" },
+        test: { en: "Test" },
+        conformant: { en: "Conformant" },
+        nonConformant: { en: "Non-conformant" },
+        notApplicable: { en: "Not applicable" },
+        auditorHeading: { en: "Accessibility criterion" },
+      },
+      themes: [{ number: 1, name: { en: "Theme one" }, count: 1 }],
+      criteria: [{ id: "1.1", theme: 1, title: { en: "Criterion one" }, titlePlain: { en: "Criterion one" }, wcag: ["1.1.1"] }],
+    },
+    null,
+    2,
+  );
+}

package/src/parse/html.ts

@@ -0,0 +1,258 @@
+// A DOM-lite over htmlparser2: parse HTML into a flat, position-aware element
+// tree that the rules walk. Zero runtime deps beyond htmlparser2 (bundled).
+import { parseDocument } from "htmlparser2";
+import type { Document, ChildNode, Element as DhElement } from "domhandler";
+
+export interface El {
+  type: "element";
+  tag: string; // lowercased intrinsic, or original-cased JSX component name
+  attribs: Record<string, string>;
+  children: HNode[];
+  parent: El | null;
+  line: number; // 1-based
+  col: number; // 1-based
+  start: number; // source offset
+  end: number;
+  // JSX only: the element carries a {...spread} attribute (props could inject a
+  // name/aria). Undefined for HTML. Used by the cross-file rules.
+  spread?: boolean;
+  // JSX only: identity of the conditional arm this element was lowered from
+  // (`{cond ? <A/> : <B/>}` / `{cond && <A/>}`). Elements in different arms of the same
+  // conditional are mutually exclusive at runtime, so order-sensitive rules
+  // (heading-order-skip) must not compare across arms. Undefined = unconditional.
+  branchArm?: string;
+}
+export interface Txt {
+  type: "text";
+  data: string;
+  parent: El | null;
+}
+export type HNode = El | Txt;
+
+export interface Doc {
+  file: string;
+  source: string;
+  lossy: boolean;
+  // How the Doc was produced: a real HTML parse, a real JSX/TSX AST (offsets index
+  // the original file — fix-safe), the best-effort lossy JSX→HTML fallback, or a
+  // single-file component (.vue/.svelte/.astro) template — parsed as HTML but with
+  // component case PRESERVED (so PascalCase components are skipped like in JSX).
+  // Optional/additive so existing AuditResult JSON and direct parseHtml callers stay valid.
+  kind?: "html" | "jsx-ast" | "jsx-lossy" | "sfc";
+  // JSX only: import specifiers of component-LIBRARY components rendered in this
+  // file (e.g. "@codegouvfr/react-dsfr/Button"). Their real HTML output lives in
+  // node_modules and is invisible to source analysis — a source verdict is
+  // therefore incomplete for them (surfaced as a scope caveat, never silent).
+  opaqueComponents?: string[];
+  // Set when this Doc is a RENDERED capture file (real DOM serialized from a test/
+  // build) carrying a `<!-- ultra11y:capture … -->` provenance comment. Its findings
+  // are ground truth (not preliminary) and re-attributed to the source component via
+  // `Finding.origin`. Optional/additive; absent for ordinary source/HTML files.
+  capture?: CaptureProvenance;
+  roots: HNode[];
+  elements: El[];
+  byId: Map<string, El>;
+  lineStarts: number[];
+}
+
+// Provenance recorded in a rendered capture's leading HTML comment, linking the
+// serialized DOM back to the source component that produced it. All fields but the
+// format version are best-effort (the harvester derives them heuristically).
+export interface CaptureProvenance {
+  v: number; // provenance format version (starts at 1)
+  sourceFile?: string; // repo-relative source, e.g. "src/Button.tsx"
+  component?: string; // best-effort component name, e.g. "Button"
+  test?: string; // originating test file, e.g. "src/Button.test.tsx"
+  name?: string; // originating test title
+}
+
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+
+// Exported so the JSX-AST bridge (parse/jsx-bridge.ts) reuses the exact same
+// line/col arithmetic over the original source as the HTML path.
+export function lineStartsOf(source: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) if (source.charCodeAt(i) === 10) starts.push(i + 1);
+  return starts;
+}
+
+export function lineColAt(lineStarts: number[], offset: number): { line: number; col: number } {
+  // binary search for the greatest lineStart <= offset
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineStarts[mid]! <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return { line: lo + 1, col: offset - lineStarts[lo]! + 1 };
+}
+
+export function parseHtml(source: string, file: string, lossy = false, sfc = false): Doc {
+  const dom: Document = parseDocument(source, {
+    withStartIndices: true,
+    withEndIndices: true,
+    // SFC: keep tag case so PascalCase components stay non-intrinsic (rules skip
+    // them). Attribute names stay lowercased (HTML attrs are case-insensitive, and
+    // the dynamic-binding prefixes `:`/`v-bind:`/`bind:` are already lowercase).
+    lowerCaseTags: !sfc,
+    lowerCaseAttributeNames: true,
+    recognizeSelfClosing: true,
+  });
+  const lineStarts = lineStartsOf(source);
+  const elements: El[] = [];
+  const byId = new Map<string, El>();
+
+  const convert = (node: ChildNode, parent: El | null): HNode | null => {
+    if (node.type === "text") {
+      return { type: "text", data: (node as { data: string }).data, parent };
+    }
+    if (node.type === "tag" || node.type === "script" || node.type === "style") {
+      const dh = node as DhElement;
+      const start = dh.startIndex ?? 0;
+      const { line, col } = lineColAt(lineStarts, start);
+      const el: El = {
+        type: "element",
+        tag: sfc ? dh.name : dh.name.toLowerCase(),
+        attribs: { ...dh.attribs },
+        children: [],
+        parent,
+        line,
+        col,
+        start,
+        end: dh.endIndex ?? start,
+      };
+      elements.push(el);
+      const id = el.attribs.id;
+      if (id && !byId.has(id)) byId.set(id, el);
+      for (const child of dh.children) {
+        const c = convert(child, el);
+        if (c) el.children.push(c);
+      }
+      return el;
+    }
+    return null; // comments, directives, etc. are ignored
+  };
+
+  const roots: HNode[] = [];
+  for (const node of dom.children) {
+    const c = convert(node, null);
+    if (c) roots.push(c);
+  }
+  return { file, source, lossy, kind: sfc ? "sfc" : lossy ? "jsx-lossy" : "html", roots, elements, byId, lineStarts };
+}
+
+// ---- helpers used by rules
+
+export function attr(el: El, name: string): string | undefined {
+  return el.attribs[name.toLowerCase()];
+}
+
+export function hasAttr(el: El, name: string): boolean {
+  return name.toLowerCase() in el.attribs;
+}
+
+// Framework dynamic-binding prefixes: Vue `:x`/`v-bind:x`, Alpine `x-bind:x`,
+// Svelte `bind:x`. The HTML parser keeps these as literal attribute keys.
+const BIND_PREFIXES = ["", ":", "v-bind:", "x-bind:", "bind:"];
+
+/** Like `attr`, but also matches a dynamically-bound spelling (`:name`, `v-bind:name`,
+ *  …). Returns the (possibly expression) value; the caller treats it as "present but
+ *  value-unknown" so a missing-name/alt finding is suppressed rather than hallucinated. */
+export function boundAttr(el: El, name: string): string | undefined {
+  const lower = name.toLowerCase();
+  for (const p of BIND_PREFIXES) {
+    const k = p + lower;
+    if (k in el.attribs) return el.attribs[k];
+  }
+  return undefined;
+}
+
+export function hasBoundAttr(el: El, name: string): boolean {
+  return boundAttr(el, name) !== undefined;
+}
+
+/** The element carries a spread/shorthand that can inject arbitrary attributes at
+ *  runtime — React `{...props}`, Vue `v-bind="…"`, Svelte `{...rest}` / `{shorthand}`.
+ *  A "missing attribute/name" finding on such an element is unprovable, so rules skip it. */
+export function hasDynamicSpread(el: El): boolean {
+  if (el.spread) return true;
+  for (const k in el.attribs) if (k === "v-bind" || k.startsWith("{")) return true;
+  return false;
+}
+
+export function isVoid(tag: string): boolean {
+  return VOID.has(tag);
+}
+
+export function textContent(node: HNode): string {
+  if (node.type === "text") return node.data;
+  let out = "";
+  for (const c of node.children) out += textContent(c);
+  return out;
+}
+
+/** Visible text content, whitespace-collapsed and trimmed. */
+export function visibleText(el: El): string {
+  return textContent(el).replace(/\s+/g, " ").trim();
+}
+
+export function descendants(el: El): El[] {
+  const out: El[] = [];
+  const stack = [...el.children];
+  while (stack.length) {
+    const n = stack.pop()!;
+    if (n.type === "element") {
+      out.push(n);
+      stack.push(...n.children);
+    }
+  }
+  return out;
+}
+
+export function ancestors(el: El): El[] {
+  const out: El[] = [];
+  let p = el.parent;
+  while (p) {
+    out.push(p);
+    p = p.parent;
+  }
+  return out;
+}
+
+export function closest(el: El, pred: (e: El) => boolean): El | undefined {
+  let p: El | null = el;
+  while (p) {
+    if (pred(p)) return p;
+    p = p.parent;
+  }
+  return undefined;
+}
+
+export function elementsByTag(doc: Doc, ...tags: string[]): El[] {
+  const want = new Set(tags.map((t) => t.toLowerCase()));
+  return doc.elements.filter((e) => want.has(e.tag));
+}
+
+export function getById(doc: Doc, id: string): El | undefined {
+  return doc.byId.get(id);
+}
+
+/** All ids in the document, with duplicates preserved (for duplicate-id). */
+export function allIds(doc: Doc): { id: string; el: El }[] {
+  const out: { id: string; el: El }[] = [];
+  for (const el of doc.elements) {
+    const id = el.attribs.id;
+    if (id) out.push({ id, el });
+  }
+  return out;
+}
+
+/** The source line(s) the element starts on, trimmed and truncated. */
+export function snippet(doc: Doc, el: El, max = 120): string {
+  const lineStart = doc.lineStarts[el.line - 1] ?? 0;
+  let end = doc.source.indexOf("\n", lineStart);
+  if (end === -1) end = doc.source.length;
+  const raw = doc.source.slice(lineStart, end).trim();
+  return raw.length > max ? raw.slice(0, max - 1) + "…" : raw;
+}

package/src/parse/jsx-ast.ts

@@ -0,0 +1,67 @@
+// Parse JSX/TSX into a real Babel AST. Unlike the lossy regex transform
+// (parse/jsx.ts), this gives accurate node positions (start/end byte offsets +
+// loc) and a faithful tree — the basis for fix-safe ranges and the cross-file
+// dependency graph. @babel/parser is pure JS and bundled into the engine, so the
+// shipped scripts/ultra11y.mjs still runs with no install.
+import { parse } from "@babel/parser";
+
+// We deliberately describe only the node shape the bridge/graph read, instead of
+// depending on @babel/types. Every Babel node carries a string `type`, numeric
+// `start`/`end` offsets, and a `loc`; the rest is walked structurally.
+export interface AstNode {
+  type: string;
+  start: number | null;
+  end: number | null;
+  loc?: { start: { line: number; column: number }; end: { line: number; column: number } } | null;
+  [key: string]: unknown;
+}
+
+export interface AstFile extends AstNode {
+  type: "File";
+  program: AstNode; // Program; .body is AstNode[]
+  errors?: unknown[];
+}
+
+// Parse with error recovery so a single malformed expression never aborts the
+// audit. Returns null only on a catastrophic throw — the caller then falls back
+// to the lossy HTML transform, so an audit always produces a result.
+export function parseJsxAst(source: string): AstFile | null {
+  try {
+    return parse(source, {
+      sourceType: "module",
+      errorRecovery: true,
+      plugins: ["typescript", "jsx"],
+    }) as unknown as AstFile;
+  } catch {
+    return null;
+  }
+}
+
+// ---- generic AST helpers shared by the JSX bridge and the graph extractor
+
+// Structural keys we never recurse into (position/comment/token metadata).
+const SKIP_KEYS = new Set(["type", "start", "end", "loc", "range", "leadingComments", "trailingComments", "innerComments", "extra", "comments", "tokens"]);
+
+export function asNode(value: unknown): AstNode | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as AstNode) : undefined;
+}
+
+export function asNodes(value: unknown): AstNode[] {
+  return Array.isArray(value) ? (value as AstNode[]) : [];
+}
+
+/** Depth-first visit every AST node under `root` (arrays and child nodes), skipping
+ *  position/comment metadata. The visitor cannot prune; for scoped walks pass a subtree. */
+export function walkAst(root: unknown, visit: (node: AstNode) => void): void {
+  if (Array.isArray(root)) {
+    for (const item of root) walkAst(item, visit);
+    return;
+  }
+  const n = asNode(root);
+  if (!n || typeof n.type !== "string") return;
+  visit(n);
+  for (const key in n) {
+    if (SKIP_KEYS.has(key)) continue;
+    walkAst(n[key], visit);
+  }
+}