ultra11y 2.22.0

package/src/discover.ts

@@ -0,0 +1,203 @@
+// Smart file discovery for `audit` at scale. The static engine never needs to
+// hold a whole monorepo in memory — it focuses: only markup files, optionally
+// only what git says changed, ordered so the highest-value markup (layouts,
+// templates, shared components) is audited first. Dedup + the --max-files cap are
+// enforced by the streaming loop in audit.ts (single read per file). Zero deps:
+// just node:fs + node:child_process (git) + node:path.
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, relative } from "node:path";
+import { expandInputs, makeFilter, inScopeMatcher, toPosix, type ExpandOpts } from "./glob.js";
+
+export interface DiscoverOpts extends ExpandOpts {
+  changed?: boolean; // audit only files changed vs `since` (default HEAD)
+  since?: string; // git ref to diff against (implies changed)
+  staged?: boolean; // audit exactly the staged index snapshot (strict pre-commit scope)
+  onWarn?: (msg: string) => void;
+}
+
+export interface Discovery {
+  files: string[]; // ordered: priority tier, then path (deterministic)
+  changedMode: boolean;
+  gitUnavailable: boolean; // changed mode requested but not a git repo / no git
+  stagedContent?: Map<string, string>; // staged mode only: file → index blob content
+}
+
+function git(args: string[], maxBuffer?: number): string | null {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], ...(maxBuffer ? { maxBuffer } : {}) });
+  } catch {
+    return null;
+  }
+}
+
+/** Files changed vs `ref` (working tree + index + untracked), repo-root-relative
+ *  paths resolved to cwd-relative. null if git is unavailable / not a repo. */
+export function gitChangedFiles(ref?: string): string[] | null {
+  const top = git(["rev-parse", "--show-toplevel"]);
+  if (top === null) return null;
+  const repoRoot = top.trim();
+  const base = ref?.trim() ? ref.trim() : "HEAD";
+  const out = new Set<string>();
+  const add = (s: string | null): void => {
+    if (!s) return;
+    for (const line of s.split("\n")) {
+      const t = line.trim();
+      if (t) out.add(t);
+    }
+  };
+  // --diff-filter=d drops deletions: we never audit a file that no longer exists.
+  add(git(["diff", "--name-only", "--diff-filter=d", base]));
+  add(git(["diff", "--name-only", "--diff-filter=d", "--cached", base]));
+  add(git(["ls-files", "--others", "--exclude-standard"]));
+  const cwd = process.cwd();
+  return [...out].map((p) => relative(cwd, join(repoRoot, p)));
+}
+
+/** Staged (index) markup files: adds + modifications only (index vs HEAD) — NOT
+ *  untracked, NOT working-tree-only edits. --diff-filter=d drops staged deletions; a
+ *  rename surfaces as the new path. Repo-root-relative → cwd-relative. null if git is
+ *  unavailable / not a repo. */
+export function gitStagedFiles(): string[] | null {
+  const top = git(["rev-parse", "--show-toplevel"]);
+  if (top === null) return null;
+  const out = git(["diff", "--cached", "--name-only", "--diff-filter=d"]);
+  if (out === null) return null;
+  const repoRoot = top.trim();
+  const cwd = process.cwd();
+  return out
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((p) => relative(cwd, join(repoRoot, p)));
+}
+
+/** Exact bytes of the index (staged) blob for a path — what a commit would record,
+ *  including any .gitattributes clean filters. `:./` makes the pathspec cwd-relative.
+ *  null on any error (untracked path, or a blob larger than maxBuffer). */
+export function stagedContent(file: string): string | null {
+  return git(["show", `:./${toPosix(file)}`], 32 * 1024 * 1024);
+}
+
+/** Index blobs for MANY paths in ONE `git cat-file --batch` instead of one `git show`
+ *  process per file — the pre-commit hook's cost used to grow one spawn at a time.
+ *  Falls back to per-file `git show` when the batch is unavailable, so behaviour is
+ *  identical either way (a path with no index blob is simply absent from the map).
+ *
+ *  `--batch` answers each request with `<sha> <type> <size>\n<size bytes>\n`, or
+ *  `<request> missing\n`. Sizes are BYTE counts, so the stream is walked as a Buffer
+ *  and each blob decoded afterwards — slicing utf8 by character count would corrupt
+ *  any file containing non-ASCII. */
+export function stagedContents(files: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!files.length) return out;
+  const requests = files.map((f) => `:./${toPosix(f)}`);
+  let buf: Buffer | null = null;
+  try {
+    buf = execFileSync("git", ["cat-file", "--batch"], {
+      input: `${requests.join("\n")}\n`,
+      stdio: ["pipe", "pipe", "ignore"],
+      maxBuffer: 512 * 1024 * 1024,
+    });
+  } catch {
+    buf = null;
+  }
+  if (buf === null) {
+    for (const f of files) {
+      const c = stagedContent(f);
+      if (c !== null) out.set(f, c);
+    }
+    return out;
+  }
+  let pos = 0;
+  for (const file of files) {
+    const nl = buf.indexOf(0x0a, pos);
+    if (nl === -1) break; // truncated stream — the rest is simply not resolved
+    const header = buf.toString("utf8", pos, nl);
+    pos = nl + 1;
+    const m = /^[0-9a-f]{40,64} \w+ (\d+)$/.exec(header);
+    if (!m) continue; // "<request> missing" (or an ambiguous name): no index blob
+    const size = Number(m[1]);
+    out.set(file, buf.toString("utf8", pos, pos + size));
+    pos += size + 1; // blob + its trailing newline
+  }
+  return out;
+}
+
+/** True when the working tree differs from the index for `file` (unstaged edits).
+ *  A partially-staged file must never be auto-fixed + re-staged: writing index-derived
+ *  output over the working tree and `git add`-ing it would silently stage those edits. */
+export function hasUnstagedChanges(file: string): boolean {
+  return !!git(["diff", "--name-only", "--", file])?.trim();
+}
+
+/** Re-stage a file after a deterministic fix (only ever called on fully-staged files). */
+export function gitAdd(file: string): void {
+  git(["add", "--", file]);
+}
+
+// Audit the highest-value markup first so a partial / capped run still covers
+// what matters. Lower number = earlier.
+const TIER0 = /(^|\/)(layout|template|_app|_document|app|main|index)[.\-/]|(^|\/)(layouts?|templates?)\//i;
+const TIER1 = /(^|\/)(components?|shared|ui|design-system|ds|partials?|includes?)\//i;
+export function priority(file: string): number {
+  const rel = toPosix(file);
+  if (TIER0.test(rel)) return 0;
+  if (TIER1.test(rel)) return 1;
+  return 2;
+}
+
+/** Sort by priority tier, then path — deterministic, and the tier is computed ONCE per
+ *  file instead of twice per comparison (the two `priority()` regexes used to run
+ *  ~4·n·log n times on every discovery). */
+function sortByPriorityThenPath(files: string[]): string[] {
+  return files
+    .map((file) => ({ file, tier: priority(file) }))
+    .sort((a, b) => a.tier - b.tier || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0))
+    .map((d) => d.file);
+}
+
+/** Resolve inputs into an ordered candidate file list. In `--changed` mode this
+ *  starts from git's changed set (no full tree walk) filtered to the audited
+ *  scope; otherwise it expands inputs normally. */
+export function discover(inputs: string[], opts: DiscoverOpts = {}): Discovery {
+  const changedMode = !!(opts.changed || opts.since || opts.staged);
+  let files: string[];
+  let gitUnavailable = false;
+  let staged: Map<string, string> | undefined;
+
+  if (opts.staged) {
+    // Strict staged snapshot: audit exactly the index blobs (what a commit records),
+    // not the working-tree copy. --staged takes precedence over --changed/--since.
+    const stagedFiles = gitStagedFiles();
+    if (stagedFiles === null) {
+      gitUnavailable = true;
+      opts.onWarn?.("ultra11y: --staged requested but git is unavailable here — falling back to a full scan.");
+      files = expandInputs(inputs, opts);
+    } else {
+      const filter = makeFilter(opts);
+      const inScope = inScopeMatcher(inputs);
+      // No existsSync: a staged-added file may be edited/removed on disk, yet its index
+      // blob is exactly what the commit would record — audit that.
+      const scoped = stagedFiles.filter((f) => filter(f) && (!inScope || inScope(f)));
+      staged = stagedContents(scoped);
+      files = [...staged.keys()];
+    }
+  } else if (changedMode) {
+    const changed = gitChangedFiles(opts.since);
+    if (changed === null) {
+      gitUnavailable = true;
+      opts.onWarn?.("ultra11y: --changed requested but git is unavailable here — falling back to a full scan.");
+      files = expandInputs(inputs, opts);
+    } else {
+      const filter = makeFilter(opts);
+      const inScope = inScopeMatcher(inputs);
+      files = changed.filter((f) => existsSync(f) && filter(f) && (!inScope || inScope(f)));
+    }
+  } else {
+    files = expandInputs(inputs, opts);
+  }
+
+  files = sortByPriorityThenPath([...new Set(files)]);
+  return { files, changedMode, gitUnavailable, ...(staged ? { stagedContent: staged } : {}) };
+}

package/src/fix/codemods.ts

@@ -0,0 +1,76 @@
+// Maps each rule to how `fix` may repair it, keyed by ruleId (NOT a field on the
+// Rule objects — keeps the registry's 36-rule invariant + rule purity intact, and
+// centralises the risky edit logic here). Three classes:
+//  - auto:        deterministic, no judgment — safe to write unattended.
+//  - placeholder: insert a syntactically-valid attribute with a TODO sentinel the
+//                 agent fills with a real, context-appropriate value.
+//  - proposal:    judgment only — the engine never invents the content; the agent
+//                 writes it (alt text relevance, link purpose, table structure…).
+import { type Edit, setAttr, removeAttr, getAttr, openTag } from "./edits.js";
+
+export type Fixability = "auto" | "placeholder" | "proposal";
+
+export const PLACEHOLDER = "TODO"; // sentinel the agent replaces with a real value
+// `lang` needs a VALID BCP-47 value or the lang-invalid rule fires (swapping one NC
+// for another). "und" = ISO 639-2 "undetermined": valid, and a clear fill-me signal.
+export const LANG_PLACEHOLDER = "und";
+
+export interface Codemod {
+  fixability: Fixability;
+  build?: (source: string, start: number) => Edit[];
+  // Safe to apply to a real JSX/TSX AST (kind === "jsx-ast")? True only when the
+  // edit removes an attribute by range or inserts an attribute whose HTML spelling
+  // is also a valid React DOM prop (alt/lang/title/aria-label/role). A codemod that
+  // REWRITES an existing attribute is unsafe in JSX (it would lowercase the React
+  // spelling, e.g. tabIndex={5} → tabindex="0"), so it stays off for JSX in v1.
+  jsxSafe?: boolean;
+}
+
+const one =
+  (fn: (s: string, start: number) => Edit | null) =>
+  (s: string, start: number): Edit[] => {
+    const e = fn(s, start);
+    return e ? [e] : [];
+  };
+
+// Re-enable zoom: drop user-scalable=no/0 and any maximum-scale that blocks 200%.
+function viewportFix(source: string, start: number): Edit[] {
+  const content = getAttr(source, start, "content");
+  if (content === null) return [];
+  const kept = content
+    .split(/[,;]/)
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .filter((p) => {
+      const [k, v] = p.split("=").map((x) => x.trim().toLowerCase());
+      if (k === "user-scalable") return false;
+      if (k === "maximum-scale") return Number(v) >= 2;
+      return true;
+    });
+  const e = setAttr(source, start, "content", kept.join(", "));
+  return e ? [e] : [];
+}
+
+// Native <img>/<area> take alt; a role="img" on something else takes aria-label.
+function altFix(source: string, start: number): Edit[] {
+  const tag = openTag(source, start)?.tagName;
+  const name = tag === "img" || tag === "area" ? "alt" : "aria-label";
+  const e = setAttr(source, start, name, PLACEHOLDER);
+  return e ? [e] : [];
+}
+
+export const CODEMODS: Record<string, Codemod> = {
+  // auto
+  "positive-tabindex": { fixability: "auto", build: one((s, st) => setAttr(s, st, "tabindex", "0")) },
+  "redundant-aria": { fixability: "auto", jsxSafe: true, build: one((s, st) => removeAttr(s, st, "role")) },
+  "meta-viewport-zoom-block": { fixability: "auto", build: viewportFix },
+  // placeholder (inserts a valid attribute; alt/lang/title/aria-label are valid React DOM props)
+  "iframe-title-missing": { fixability: "placeholder", jsxSafe: true, build: one((s, st) => setAttr(s, st, "title", PLACEHOLDER)) },
+  "html-lang-missing": { fixability: "placeholder", jsxSafe: true, build: one((s, st) => setAttr(s, st, "lang", LANG_PLACEHOLDER)) },
+  "img-alt-missing": { fixability: "placeholder", jsxSafe: true, build: altFix },
+  "control-label-missing": { fixability: "placeholder", jsxSafe: true, build: one((s, st) => setAttr(s, st, "aria-label", PLACEHOLDER)) },
+};
+
+export function fixabilityOf(ruleId: string): Fixability {
+  return CODEMODS[ruleId]?.fixability ?? "proposal";
+}

package/src/fix/diff.ts

@@ -0,0 +1,64 @@
+// A tiny, zero-dependency unified-diff renderer for `fix --dry-run` previews.
+// LCS over lines with context collapsing; guarded against pathological inputs
+// (minified bundles) so it never blows up memory on a giant single line.
+
+interface Op {
+  t: " " | "-" | "+";
+  line: string;
+}
+
+export function unifiedDiff(file: string, before: string, after: string, ctx = 2): string {
+  if (before === after) return "";
+  const a = before.split("\n");
+  const b = after.split("\n");
+  const header = `--- a/${file}\n+++ b/${file}`;
+  if (a.length > 4000 || b.length > 4000) return `${header}\n@@ diff omitted (large file): ${a.length} → ${b.length} lines @@`;
+
+  const n = a.length;
+  const m = b.length;
+  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i]![j] = a[i] === b[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+    }
+  }
+
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push({ t: " ", line: a[i]! });
+      i++;
+      j++;
+    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
+      ops.push({ t: "-", line: a[i]! });
+      i++;
+    } else {
+      ops.push({ t: "+", line: b[j]! });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ t: "-", line: a[i++]! });
+  while (j < m) ops.push({ t: "+", line: b[j++]! });
+
+  const show = new Array<boolean>(ops.length).fill(false);
+  for (let k = 0; k < ops.length; k++) {
+    if (ops[k]!.t !== " ") for (let d = -ctx; d <= ctx; d++) if (k + d >= 0 && k + d < ops.length) show[k + d] = true;
+  }
+
+  const out = [header];
+  let k = 0;
+  while (k < ops.length) {
+    if (!show[k]) {
+      k++;
+      continue;
+    }
+    let e = k;
+    while (e < ops.length && show[e]) e++;
+    out.push(`@@ ${k + 1},${e - k} @@`);
+    for (let x = k; x < e; x++) out.push(`${ops[x]!.t}${ops[x]!.line}`);
+    k = e;
+  }
+  return out.join("\n");
+}

package/src/fix/edits.ts

@@ -0,0 +1,126 @@
+// Source-range edit primitives for `fix`. The parser gives us each element's
+// [start, end) byte range (open+close, end EXCLUSIVE) but NO per-attribute or
+// text-node offsets, and `end` points at the CLOSING tag. So codemods never splice
+// blindly on start/end: they re-scan the *opening tag* locally from `start` to find
+// the `>` and any attribute span. Edits are applied back-to-front so earlier offsets
+// stay valid; overlapping edits on the same element are dropped, not mis-applied.
+
+export interface Edit {
+  start: number;
+  end: number;
+  replacement: string;
+}
+
+interface OpenTag {
+  tagName: string;
+  gt: number; // index of the '>' that closes the opening tag
+  selfClose: boolean; // '/>' form
+}
+
+/** Locate the opening tag starting at `start` (must point at '<'), scanning to the
+ *  first '>' that is not inside a quoted attribute value. */
+export function openTag(source: string, start: number): OpenTag | null {
+  if (source[start] !== "<") return null;
+  let i = start + 1;
+  let name = "";
+  while (i < source.length && /[A-Za-z0-9:_-]/.test(source[i]!)) {
+    name += source[i]!;
+    i++;
+  }
+  if (!name) return null;
+  let quote: string | null = null;
+  for (; i < source.length; i++) {
+    const ch = source[i]!;
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === ">") {
+      return { tagName: name.toLowerCase(), gt: i, selfClose: source[i - 1] === "/" };
+    }
+  }
+  return null;
+}
+
+interface AttrSpan {
+  attrStart: number; // includes the leading whitespace
+  attrEnd: number;
+  value: string | null; // unquoted value, if present
+}
+
+/** Find a whole attribute (name + optional value) inside the opening tag. */
+export function findAttr(source: string, start: number, gt: number, name: string): AttrSpan | null {
+  const seg = source.slice(start, gt);
+  // The negative lookahead stops `alt` from matching inside `alt_backup`/`data-alt`:
+  // the name must be a whole attribute token (next char is not name-continuing).
+  const re = new RegExp(`(\\s+)(${name})(?![A-Za-z0-9_:-])(\\s*=\\s*("[^"]*"|'[^']*'|[^\\s>]+))?`, "i");
+  const m = re.exec(seg);
+  if (!m) return null;
+  const attrStart = start + m.index;
+  const attrEnd = attrStart + m[0].length;
+  let value: string | null = null;
+  if (m[4]) {
+    const raw = m[4];
+    value = raw.startsWith('"') || raw.startsWith("'") ? raw.slice(1, -1) : raw;
+  }
+  return { attrStart, attrEnd, value };
+}
+
+export function getAttr(source: string, start: number, name: string): string | null {
+  const ot = openTag(source, start);
+  if (!ot) return null;
+  return findAttr(source, start, ot.gt, name)?.value ?? null;
+}
+
+/** Set (rewrite if present, else insert before '>') an attribute on the element
+ *  whose opening tag begins at `start`. */
+export function setAttr(source: string, start: number, name: string, value: string): Edit | null {
+  const ot = openTag(source, start);
+  if (!ot) return null;
+  const existing = findAttr(source, start, ot.gt, name);
+  if (existing) return { start: existing.attrStart, end: existing.attrEnd, replacement: ` ${name}="${value}"` };
+  const insertAt = ot.selfClose ? ot.gt - 1 : ot.gt;
+  return { start: insertAt, end: insertAt, replacement: ` ${name}="${value}"` };
+}
+
+/** Remove an attribute (and its leading whitespace) from the element at `start`. */
+export function removeAttr(source: string, start: number, name: string): Edit | null {
+  const ot = openTag(source, start);
+  if (!ot) return null;
+  const span = findAttr(source, start, ot.gt, name);
+  if (!span) return null;
+  return { start: span.attrStart, end: span.attrEnd, replacement: "" };
+}
+
+export interface ApplyResult {
+  output: string;
+  applied: number;
+  conflicts: number;
+}
+
+/** Apply edits back-to-front; drop any edit that overlaps an already-applied
+ *  (higher-offset) one so we never corrupt the source. */
+export function applyEdits(source: string, edits: Edit[]): ApplyResult {
+  const sorted = [...edits].sort((a, b) => b.start - a.start || b.end - a.end);
+  let out = source;
+  let lastStart = Infinity;
+  const insertedAt = new Set<number>();
+  let applied = 0;
+  let conflicts = 0;
+  for (const e of sorted) {
+    // Ranges are half-open [start, end): `>` allows ADJACENT edits (one ending where
+    // the next begins) but rejects true overlap into the already-applied region.
+    // Zero-width insertions don't trip that test, so a second insertion at the same
+    // point is caught separately.
+    const isInsertion = e.start === e.end;
+    if (e.end > lastStart || (isInsertion && insertedAt.has(e.start))) {
+      conflicts++;
+      continue;
+    }
+    out = out.slice(0, e.start) + e.replacement + out.slice(e.end);
+    lastStart = e.start;
+    if (isInsertion) insertedAt.add(e.start);
+    applied++;
+  }
+  return { output: out, applied, conflicts };
+}

package/src/fix.ts

@@ -0,0 +1,215 @@
+// `fix` — put the fixes in place. Hybrid by design (anti-hallucination first):
+//   • auto codemods are applied deterministically;
+//   • placeholders insert a valid attribute with a TODO sentinel the agent fills;
+//   • proposals are judgment-only and never auto-written.
+// --dry-run (default) prints a unified diff; --write applies, but ONLY after a
+// re-audit proves no NEW non-conformity was introduced (regression gate). JSX/TSX
+// parsed to a real AST is editable (jsxSafe codemods only); the lossy JSX fallback
+// stays proposal-only (its offsets index the transformed string, not the file).
+import { writeFileSync } from "node:fs";
+import type { Finding, Lang } from "./types.js";
+import { discover, hasUnstagedChanges, gitAdd } from "./discover.js";
+import { parseSource } from "./parse/source.js";
+import { runRules } from "./rules/registry.js";
+import { readText } from "./util.js";
+import { applyEdits, type Edit } from "./fix/edits.js";
+import { CODEMODS, fixabilityOf, type Fixability } from "./fix/codemods.js";
+import { unifiedDiff } from "./fix/diff.js";
+
+export interface FixInput {
+  inputs: string[];
+  stdin?: string;
+  forceJsx?: boolean;
+  include?: string[];
+  exclude?: string[];
+  ext?: string[];
+  changed?: boolean;
+  since?: string;
+  staged?: boolean; // fix exactly the staged index snapshot; re-stage written files
+  safe?: boolean; // apply only genuinely-automatic codemods (skip placeholder/proposal)
+  only?: string[]; // limit to these ruleIds
+  write?: boolean; // default false → dry-run
+  noDefaultExcludes?: boolean; // also fix test/spec/story/__tests__ markup
+  onWarn?: (m: string) => void;
+}
+
+export interface FixItem {
+  ruleId: string;
+  criteriaId: string;
+  line: number;
+  selectorHint: string;
+  fixability: Fixability;
+}
+
+export interface FileFix {
+  file: string;
+  lossy: boolean;
+  items: FixItem[];
+  diff: string;
+  applied: number; // edits applied (auto + placeholder)
+  written: boolean;
+  regression: boolean; // gate tripped → not written
+  restaged?: boolean; // staged mode: written fix re-staged (git add)
+  skippedPartialStage?: boolean; // staged mode: had unstaged edits → not written (unsafe to re-stage)
+}
+
+export interface FixResult {
+  files: FileFix[];
+  totals: {
+    auto: number;
+    placeholder: number;
+    proposal: number;
+    filesWritten: number;
+    regressions: number;
+    filesRestaged: number;
+    partialStageSkipped: number;
+  };
+}
+
+function itemOf(f: Finding): FixItem {
+  return { ruleId: f.ruleId, criteriaId: f.criteriaId, line: f.line, selectorHint: f.selectorHint, fixability: fixabilityOf(f.ruleId) };
+}
+
+function fixOne(file: string, source: string, opts: FixInput, canWrite = true): FileFix {
+  const doc = parseSource(source, file, { forceJsx: opts.forceJsx });
+  // Rendered captures are GENERATED output (serialized DOM). A codemod on them is
+  // meaningless and would be clobbered on the next test run — and in --staged mode we
+  // must never rewrite/re-stage a capture. Skip entirely (no items, no edits).
+  if (doc.capture) return { file, lossy: doc.lossy, items: [], diff: "", applied: 0, written: false, regression: false };
+  const findings = runRules(doc);
+  const items = findings.map(itemOf);
+
+  const edits: Edit[] = [];
+  // Real-AST docs (HTML or jsx-ast) carry accurate file offsets, so codemods edit
+  // by range. On jsx-ast we apply only codemods marked jsxSafe (attribute removal /
+  // insertion of React-valid props); name-rewriting codemods stay off so we never
+  // turn tabIndex={5} into tabindex="0". The lossy fallback (jsx-lossy) edits nothing.
+  const isJsxAst = doc.kind === "jsx-ast";
+  if (!doc.lossy) {
+    for (const f of findings) {
+      if (opts.only && !opts.only.includes(f.ruleId)) continue;
+      // --safe: apply only genuinely-automatic codemods. Placeholder inserts (alt="TODO",
+      // lang="und", title="TODO") mechanically clear a finding with a stub that still
+      // needs a human/AI value — so skip them here, leaving those findings for the gate.
+      if (opts.safe && fixabilityOf(f.ruleId) !== "auto") continue;
+      const cm = CODEMODS[f.ruleId];
+      if (!cm?.build || f.sourceStart === undefined) continue;
+      if (isJsxAst && !cm.jsxSafe) continue;
+      edits.push(...cm.build(source, f.sourceStart));
+    }
+  } else if (opts.write && findings.some((f) => CODEMODS[f.ruleId]?.build)) {
+    opts.onWarn?.(`ultra11y fix: ${file} is JSX/TSX (lossy parse fallback) — fixes are proposal-only here; edit the source by hand.`);
+  }
+
+  let diff = "";
+  let applied = 0;
+  let written = false;
+  let regression = false;
+  let skippedPartialStage = false;
+
+  if (edits.length) {
+    const { output, applied: n } = applyEdits(source, edits);
+    applied = n;
+    diff = unifiedDiff(file, source, output);
+    // regression gate: re-audit the fixed text; a fix must never add an NC — not
+    // just in total count, but also no NEW kind of finding (catches one-NC-for-another
+    // swaps, e.g. a bad placeholder value that trips a different rule).
+    const after = runRules(parseSource(output, file, { forceJsx: opts.forceJsx }));
+    const beforeKinds = new Set(findings.map((f) => f.ruleId));
+    regression = after.length > findings.length || after.some((f) => !beforeKinds.has(f.ruleId));
+    if (opts.write && !regression && file !== "<stdin>") {
+      if (canWrite) {
+        writeFileSync(file, output);
+        written = true;
+      } else {
+        // Staged mode + unstaged edits: writing index-derived output over the working
+        // tree (and re-staging it) would silently stage those edits. Leave it to a human.
+        skippedPartialStage = true;
+        opts.onWarn?.(`ultra11y fix: ${file} has unstaged edits — not auto-fixed/re-staged; fix and stage it manually.`);
+      }
+    }
+    if (regression) opts.onWarn?.(`ultra11y fix: ${file} not written — fix would introduce a new non-conformity (regression gate).`);
+  }
+
+  return { file, lossy: doc.lossy, items, diff, applied, written, regression, ...(skippedPartialStage ? { skippedPartialStage } : {}) };
+}
+
+export function runFix(opts: FixInput): FixResult {
+  const { files, gitUnavailable, stagedContent } = discover(opts.inputs, {
+    include: opts.include,
+    exclude: opts.exclude,
+    ext: opts.ext,
+    changed: opts.changed,
+    since: opts.since,
+    staged: opts.staged,
+    noDefaultExcludes: opts.noDefaultExcludes,
+    onWarn: opts.onWarn,
+  });
+  const useStaged = opts.staged === true && !gitUnavailable;
+
+  const out: FileFix[] = [];
+  for (const file of files) {
+    let src: string;
+    if (useStaged) {
+      const c = stagedContent?.get(file);
+      if (c === undefined) continue;
+      src = c;
+    } else {
+      try {
+        src = readText(file);
+      } catch {
+        continue;
+      }
+    }
+    // Only auto-fix + re-stage files whose working tree already matches the index;
+    // a partially-staged file is left untouched (its findings keep the gate blocking).
+    const canWrite = !(useStaged && hasUnstagedChanges(file));
+    const ff = fixOne(file, src, opts, canWrite);
+    if (useStaged && ff.written) {
+      gitAdd(file);
+      ff.restaged = true;
+    }
+    out.push(ff);
+  }
+  if (opts.inputs.includes("-") && opts.stdin !== undefined) {
+    out.push(fixOne("<stdin>", opts.stdin, { ...opts, write: false }));
+  }
+
+  const totals = { auto: 0, placeholder: 0, proposal: 0, filesWritten: 0, regressions: 0, filesRestaged: 0, partialStageSkipped: 0 };
+  for (const ff of out) {
+    for (const it of ff.items) totals[it.fixability]++;
+    if (ff.written) totals.filesWritten++;
+    if (ff.regression) totals.regressions++;
+    if (ff.restaged) totals.filesRestaged++;
+    if (ff.skippedPartialStage) totals.partialStageSkipped++;
+  }
+  return { files: out, totals };
+}
+
+const FIX_LABEL: Record<Fixability, { fr: string; en: string }> = {
+  auto: { fr: "auto", en: "auto" },
+  placeholder: { fr: "à compléter", en: "fill-in" },
+  proposal: { fr: "jugement", en: "judgment" },
+};
+
+/** Human summary for the CLI. */
+export function fixSummary(r: FixResult, lang: Lang = "fr", write = false): string {
+  const out: string[] = [];
+  const t = r.totals;
+  const head =
+    lang === "fr"
+      ? `${write ? "Corrections appliquées" : "Corrections proposées (dry-run)"} : ${t.auto} auto, ${t.placeholder} à compléter, ${t.proposal} jugement · ${t.filesWritten} fichier(s) écrit(s)${t.filesRestaged ? `, ${t.filesRestaged} re-stagé(s)` : ""}${t.regressions ? `, ${t.regressions} bloqué(s) par le garde anti-régression` : ""}${t.partialStageSkipped ? `, ${t.partialStageSkipped} ignoré(s) (modifs non-stagées)` : ""}.`
+      : `${write ? "Fixes applied" : "Proposed fixes (dry-run)"}: ${t.auto} auto, ${t.placeholder} fill-in, ${t.proposal} judgment · ${t.filesWritten} file(s) written${t.filesRestaged ? `, ${t.filesRestaged} re-staged` : ""}${t.regressions ? `, ${t.regressions} blocked by the regression gate` : ""}${t.partialStageSkipped ? `, ${t.partialStageSkipped} skipped (unstaged edits)` : ""}.`;
+  out.push(head, "");
+  for (const ff of r.files) {
+    const fixable = ff.items.filter((i) => i.fixability !== "proposal");
+    if (!fixable.length && !ff.items.length) continue;
+    out.push(`### ${ff.file}${ff.lossy ? " (JSX/TSX — " + (lang === "fr" ? "proposition seule" : "proposal-only") + ")" : ""}`);
+    for (const it of ff.items)
+      out.push(`- [${FIX_LABEL[it.fixability][lang]}] ${it.ruleId} (WCAG ${it.criteriaId}) — \`${it.selectorHint}\` @ ${ff.file}:${it.line}`);
+    if (ff.diff) out.push("", "```diff", ff.diff, "```");
+    if (ff.regression) out.push(`> ⚠️ ${lang === "fr" ? "non écrit : régression détectée" : "not written: regression detected"}`);
+    out.push("");
+  }
+  return out.join("\n");
+}