ultra11y 2.22.0

package/src/parse/jsx-bridge.ts

@@ -0,0 +1,247 @@
+// Lower a real JSX/TSX Babel AST into the engine's existing Doc/El model so all
+// static rules run unchanged on accurate trees. Casing routes the work for free:
+// intrinsic elements (div, img, input) are lowercased — existing tag-literal
+// rules apply; component elements (Button, IconButton) keep their original case —
+// existing rules skip them, only cross-file rules (which resolve the component to
+// its definition) look at them. Offsets index the ORIGINAL source, so the Doc is
+// not lossy and `fix` can edit by range.
+import type { AstNode, AstFile } from "./jsx-ast.js";
+import type { Doc, El, HNode } from "./html.js";
+import { lineStartsOf } from "./html.js";
+
+// React → HTML attribute spellings the rules look for (matches parse/jsx.ts).
+// Applied AFTER lowercasing, so e.g. tabIndex→tabindex falls out of lowercasing
+// and only className/htmlFor need an explicit remap.
+const RENAME: Record<string, string> = { classname: "class", htmlfor: "for" };
+
+function asNode(v: unknown): AstNode | undefined {
+  return v && typeof v === "object" && !Array.isArray(v) ? (v as AstNode) : undefined;
+}
+function asNodes(v: unknown): AstNode[] {
+  return Array.isArray(v) ? (v as AstNode[]) : [];
+}
+
+export function jsxName(name: AstNode | undefined): string {
+  if (!name) return "unknown";
+  if (name.type === "JSXIdentifier") return typeof name.name === "string" ? name.name : "unknown";
+  if (name.type === "JSXNamespacedName") {
+    const ns = asNode(name.namespace);
+    const nm = asNode(name.name);
+    return `${ns?.name ?? ""}:${nm?.name ?? ""}`;
+  }
+  if (name.type === "JSXMemberExpression") {
+    const parts: string[] = [];
+    let n: AstNode | undefined = name;
+    while (n && n.type === "JSXMemberExpression") {
+      const prop = asNode(n.property);
+      if (prop && typeof prop.name === "string") parts.unshift(prop.name);
+      n = asNode(n.object);
+    }
+    if (n && typeof n.name === "string") parts.unshift(n.name);
+    return parts.join(".");
+  }
+  return "unknown";
+}
+
+// Intrinsic (HTML) names start lowercase; components are Capitalized; for member
+// expressions (motion.div, S.Button) the head decides.
+export function isIntrinsic(tag: string): boolean {
+  const head = tag.split(".")[0] ?? tag;
+  const first = head[0] ?? "";
+  return first === first.toLowerCase();
+}
+
+export function normAttrName(raw: string): string {
+  const lower = raw.toLowerCase();
+  return RENAME[lower] ?? lower;
+}
+
+function attribsOf(opening: AstNode, source: string): Record<string, string> {
+  const attribs: Record<string, string> = {};
+  for (const a of asNodes(opening.attributes)) {
+    if (a.type === "JSXSpreadAttribute") continue; // {...props} — tracked by the graph, not an attr
+    if (a.type !== "JSXAttribute") continue;
+    const name = normAttrName(jsxName(asNode(a.name)));
+    if (name in attribs) continue; // first wins, like htmlparser2
+    const value = asNode(a.value);
+    if (!value) {
+      attribs[name] = ""; // boolean attribute (present)
+    } else if (value.type === "StringLiteral") {
+      attribs[name] = typeof value.value === "string" ? value.value : "";
+    } else if (value.type === "JSXExpressionContainer") {
+      // A container wrapping a LITERAL (tabIndex={5}, aria-label={"Save"}, {-1}) carries a
+      // known value — unwrap it (no braces) so value-based rules read "5"/"Save", not "{5}".
+      // Anything else (identifiers, calls, ternaries) stays the raw `{…}` slice = dynamic.
+      const expr = asNode(value.expression);
+      if (expr && (expr.type === "NumericLiteral" || (expr.type === "UnaryExpression" && asNode(expr.argument)?.type === "NumericLiteral"))) {
+        attribs[name] = source.slice(expr.start ?? 0, expr.end ?? 0); // "5" / "-1"
+      } else if (expr && expr.type === "StringLiteral") {
+        attribs[name] = typeof expr.value === "string" ? expr.value : "";
+      } else {
+        attribs[name] = source.slice(value.start ?? 0, value.end ?? 0); // dynamic expression — keep raw {…}
+      }
+    } else {
+      // <jsx/> value or other → keep the raw source slice ("present / non-empty name").
+      attribs[name] = source.slice(value.start ?? 0, value.end ?? 0);
+    }
+  }
+  return attribs;
+}
+
+// A JSX node collected from inside an expression, tagged with the conditional arm it
+// belongs to (mutually-exclusive arms get distinct tags; "" = unconditional).
+interface Collected {
+  node: AstNode;
+  arm: string;
+}
+
+// Collect JSXElement/JSXFragment nodes nested inside an arbitrary expression
+// (e.g. {cond && <img/>} or {items.map(i => <li/>)}) without descending into the
+// matched node (convert() handles its subtree). Ternary consequent/alternate and the
+// right operand of `&&`/`||` are tagged as distinct arms so order-sensitive rules can
+// tell two elements are mutually exclusive (never both rendered). `seq` mints unique
+// conditional ids across the whole doc so arms from different conditionals never collide.
+function collectJsx(node: unknown, out: Collected[], arm: string, seq: { n: number }): void {
+  if (Array.isArray(node)) {
+    for (const item of node) collectJsx(item, out, arm, seq);
+    return;
+  }
+  const n = asNode(node);
+  if (!n || typeof n.type !== "string") return;
+  if (n.type === "JSXElement" || n.type === "JSXFragment") {
+    out.push({ node: n, arm });
+    return;
+  }
+  if (n.type === "ConditionalExpression") {
+    const id = seq.n++;
+    collectJsx(n.test, out, arm, seq);
+    collectJsx(n.consequent, out, `${arm}/c${id}T`, seq);
+    collectJsx(n.alternate, out, `${arm}/c${id}F`, seq);
+    return;
+  }
+  if (n.type === "LogicalExpression") {
+    const id = seq.n++;
+    collectJsx(n.left, out, arm, seq);
+    collectJsx(n.right, out, `${arm}/c${id}R`, seq);
+    return;
+  }
+  for (const key in n) {
+    if (key === "loc" || key === "start" || key === "end" || key === "range" || key === "type") continue;
+    collectJsx(n[key], out, arm, seq);
+  }
+}
+
+export function jsxAstToDoc(ast: AstFile, source: string, file: string): Doc {
+  const lineStarts = lineStartsOf(source);
+  const elements: El[] = [];
+  const byId = new Map<string, El>();
+  const roots: HNode[] = [];
+  const seq = { n: 0 }; // doc-wide counter for unique conditional-arm ids
+
+  const convert = (node: AstNode, parent: El | null, arm = ""): El => {
+    let tag = "#fragment";
+    let attribs: Record<string, string> = {};
+    let spread = false;
+    if (node.type === "JSXElement") {
+      const opening = asNode(node.openingElement);
+      const raw = jsxName(opening ? asNode(opening.name) : undefined);
+      tag = isIntrinsic(raw) ? raw.toLowerCase() : raw;
+      if (opening) {
+        attribs = attribsOf(opening, source);
+        spread = asNodes(opening.attributes).some((a) => a.type === "JSXSpreadAttribute");
+      }
+    }
+    const el: El = {
+      type: "element",
+      tag,
+      attribs,
+      children: [],
+      parent,
+      line: node.loc?.start.line ?? 1,
+      col: (node.loc?.start.column ?? 0) + 1,
+      start: node.start ?? 0,
+      end: node.end ?? 0,
+      ...(spread ? { spread: true } : {}),
+      ...(arm ? { branchArm: arm } : {}),
+    };
+    elements.push(el);
+    const id = attribs.id;
+    if (id && !byId.has(id)) byId.set(id, el);
+
+    for (const c of asNodes(node.children)) {
+      if (c.type === "JSXText") {
+        const data = typeof c.value === "string" ? c.value : "";
+        if (data.trim() !== "") el.children.push({ type: "text", data, parent: el });
+      } else if (c.type === "JSXElement" || c.type === "JSXFragment") {
+        el.children.push(convert(c, el, arm));
+      } else if (c.type === "JSXExpressionContainer" || c.type === "JSXSpreadChild") {
+        // Keep the raw `{…}` as text (non-empty content for name/empty rules)…
+        el.children.push({ type: "text", data: source.slice(c.start ?? 0, c.end ?? 0), parent: el });
+        // …and surface any JSX rendered inside the expression as real children, tagged
+        // with the conditional arm they came from (so heading-order won't cross arms).
+        const nested: Collected[] = [];
+        collectJsx(c.expression ?? c, nested, arm, seq);
+        for (const j of nested) el.children.push(convert(j.node, el, j.arm));
+      }
+    }
+    return el;
+  };
+
+  // Walk the whole program. The first time a JSX node is reached it becomes a
+  // root and convert() consumes its whole subtree; visit() then returns without
+  // descending, so nested JSX is never re-rooted (the AST is a tree).
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    const n = asNode(node);
+    if (!n || typeof n.type !== "string") return;
+    if (n.type === "JSXElement" || n.type === "JSXFragment") {
+      roots.push(convert(n, null));
+      return;
+    }
+    for (const key in n) {
+      if (key === "loc" || key === "start" || key === "end" || key === "range" || key === "type") continue;
+      visit(n[key]);
+    }
+  };
+  visit(ast.program);
+
+  const opaqueComponents = opaqueLibrarySpecifiers(ast, elements);
+  return { file, source, lossy: false, kind: "jsx-ast", roots, elements, byId, lineStarts, ...(opaqueComponents.length ? { opaqueComponents } : {}) };
+}
+
+// A specifier resolved from node_modules (a real package), not a relative path or
+// a project path-alias (./x, ../x, /x, @/x, ~/x).
+function isLibrarySpecifier(spec: string): boolean {
+  if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("@/") || spec.startsWith("~")) return false;
+  if (/^@[a-zA-Z][^/]*\/.+/.test(spec)) return true; // scoped package: @scope/name
+  return /^[a-zA-Z]/.test(spec); // bare package: react, lodash…
+}
+
+// The library specifiers whose components are actually rendered in this file. Maps
+// each used component's head binding (Button, motion in motion.div…) to its import
+// source and keeps the bare/library ones.
+function opaqueLibrarySpecifiers(ast: AstFile, elements: El[]): string[] {
+  const importSrc = new Map<string, string>();
+  const body = asNodes((asNode(ast.program) ?? ast).body);
+  for (const stmt of body) {
+    if (stmt.type !== "ImportDeclaration") continue;
+    const source = asNode(stmt.source);
+    const spec = source && typeof source.value === "string" ? source.value : "";
+    if (!spec) continue;
+    for (const s of asNodes(stmt.specifiers)) {
+      const local = asNode(s.local);
+      if (local && typeof local.name === "string") importSrc.set(local.name, spec);
+    }
+  }
+  const opaque = new Set<string>();
+  for (const el of elements) {
+    if (isIntrinsic(el.tag) || el.tag === "#fragment") continue;
+    const head = el.tag.split(".")[0] ?? el.tag;
+    const spec = importSrc.get(head);
+    if (spec && isLibrarySpecifier(spec)) opaque.add(spec);
+  }
+  return [...opaque].sort();
+}

package/src/parse/jsx.ts

@@ -0,0 +1,19 @@
+// Best-effort JSX/TSX → HTML-ish normalisation so the HTML pipeline + rules can
+// run on React components. This is deliberately lossy (flagged in the Doc): JSX
+// expression children become text, surrounding TS code may leave noise tags, and
+// PascalCase components are lowercased. It is enough to catch the structural
+// a11y issues the static rules target (missing alt, clickable div, unlabeled
+// field…), never a substitute for auditing rendered output.
+export function jsxToHtml(source: string): string {
+  let s = source;
+  // {/* JSX comments */}
+  s = s.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ");
+  // React attribute names → HTML names the rules look for
+  s = s.replace(/\bclassName=/g, "class=");
+  s = s.replace(/\bhtmlFor=/g, "for=");
+  s = s.replace(/\btabIndex=/g, "tabindex=");
+  // {expr} attribute values stay as a present, non-empty token so "attribute
+  // present" checks (alt={x}, aria-label={t}) are honoured. htmlparser2 reads
+  // `attr={expr}` as attr="{expr}" already; nothing to do here.
+  return s;
+}

package/src/parse/source.ts

@@ -0,0 +1,75 @@
+// Detect the input kind and normalise it into a position-aware Doc the engine
+// walks. HTML is parsed directly. JSX/TSX is parsed into a real Babel AST and
+// lowered to the same Doc model (accurate offsets, not lossy); only if that hard
+// fails do we fall back to the best-effort lossy regex transform, so an audit
+// always produces a result.
+import { parseHtml, type Doc } from "./html.js";
+import { jsxToHtml } from "./jsx.js";
+import { parseJsxAst, type AstFile } from "./jsx-ast.js";
+import { jsxAstToDoc } from "./jsx-bridge.js";
+import { parseCaptureProvenance } from "../capture.js";
+
+export type SourceKind = "html" | "jsx" | "sfc";
+
+export function detectKind(file: string, forceJsx = false): SourceKind {
+  if (forceJsx) return "jsx";
+  if (/\.(jsx|tsx)$/i.test(file)) return "jsx";
+  // Single-file components: parsed via the HTML path but with component case
+  // preserved (so PascalCase components keep their identity and rules skip them).
+  if (/\.(vue|svelte|astro)$/i.test(file)) return "sfc";
+  return "html"; // .html/.htm/.xhtml, stdin, and unknown extensions default to HTML
+}
+
+const ASTRO_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+
+/** Astro's `---\n…\n---` code fence at the top of the file (component script:
+ *  imports, props, data prep) — NOT markup. Returns the frontmatter's own source
+ *  (for the graph to parse as a script AST, see graph/build.ts) and a `blanked`
+ *  variant of the full file with every frontmatter character except newlines
+ *  replaced by a space: same length, same line count, same byte offsets as the
+ *  original — so `parseHtml` never mistakes frontmatter TS syntax for markup
+ *  (`Array<string>` reads as a `<string>` tag unstripped) while every finding's
+ *  line number AND byte offset (`fix`'s range-based codemods) stay exact. Absent
+ *  frontmatter (no leading `---` fence) returns the source unchanged. */
+export function splitAstroFrontmatter(source: string): { frontmatter: string; blanked: string } {
+  const m = ASTRO_FRONTMATTER_RE.exec(source);
+  if (!m) return { frontmatter: "", blanked: source };
+  const fence = m[0];
+  const frontmatter = fence.replace(/^---\r?\n/, "").replace(/\r?\n---\r?\n?$/, "");
+  const blanked = fence.replace(/[^\n\r]/g, " ") + source.slice(fence.length);
+  return { frontmatter, blanked };
+}
+
+export function parseSource(source: string, file: string, opts: { forceJsx?: boolean } = {}): Doc {
+  return parseSourceWithAst(source, file, opts).doc;
+}
+
+/** `parseSource` plus the Babel AST it built on the way (null for HTML/SFC templates,
+ *  and for a JSX file that only survived the lossy fallback). The dependency-graph pass
+ *  needs BOTH — the Doc to extract markup facts and the AST to extract imports/exports —
+ *  and going through this one function is what lets the graph hand its already-parsed
+ *  Docs to the audit loop instead of every markup file being read and parsed twice. */
+export function parseSourceWithAst(source: string, file: string, opts: { forceJsx?: boolean } = {}): { doc: Doc; ast: AstFile | null } {
+  const kind = detectKind(file, opts.forceJsx);
+  if (kind === "jsx") {
+    const ast = parseJsxAst(source);
+    if (ast) return { doc: jsxAstToDoc(ast, source, file), ast };
+    // Catastrophic parse failure → lossy fallback (flagged lossy in the Doc).
+    return { doc: parseHtml(jsxToHtml(source), file, true), ast: null };
+  }
+  // .astro's frontmatter fence is stripped (blanked) before HTML parsing — see
+  // splitAstroFrontmatter. .vue/.svelte have no such fence (their <script> block
+  // parses cleanly as an ordinary — if foreign-cased — element).
+  const isAstro = kind === "sfc" && /\.astro$/i.test(file);
+  const htmlSource = isAstro ? splitAstroFrontmatter(source).blanked : source;
+  // SFC templates parse as HTML but keep component case (preserveCase) and a
+  // distinct kind so the injected-content guards treat them like JSX, not HTML.
+  const doc = parseHtml(htmlSource, file, false, kind === "sfc");
+  // A rendered capture is real HTML (kind "html"): attach its provenance so findings
+  // are re-attributed to the source component. SFC/JSX are source, never captures.
+  if (kind === "html") {
+    const capture = parseCaptureProvenance(source);
+    if (capture) doc.capture = capture;
+  }
+  return { doc, ast: null };
+}