@binclusive/a11y 0.1.0

package/src/collect-dom.ts

@@ -0,0 +1,119 @@
+/**
+ * The rendered-DOM collector: the live-URL counterpart to `collect.ts` + the
+ * `scan` in `core.ts`. Where that path needs `.tsx` on disk and reads a JSX AST,
+ * this one renders a URL in a real browser and runs axe-core against the
+ * resulting DOM — so it covers the ~half of real audited sites that are NOT
+ * React (ASP.NET/Razor, server-rendered, jQuery) AND the React ones we only
+ * have a live URL for, never the source.
+ *
+ * It is deliberately a SECOND PRODUCER into the same `Finding` shape, not a
+ * second product: the findings it emits flow through the exact same SC-keyed
+ * `enrichAll` corpus cross-ref and enforcement gate as the source passes. The
+ * only bridge needed is reading the WCAG SC off axe's `tags` (`wcag111` →
+ * `1.1.1`) — no rule-id crosswalk, because the corpus enriches by SC.
+ *
+ * Render engine is Playwright (real Chromium) by decision 0001: a real layout
+ * is what lets axe run color-contrast / target-size / reflow and resolve
+ * computed ARIA roles — exactly the categories a headless DOM (jsdom) is blind
+ * to, and a huge share of real WCAG failures.
+ */
+
+import { AxeBuilder } from "@axe-core/playwright";
+import { chromium } from "playwright";
+import { enforcementFor } from "./config-scan";
+import type { Finding } from "./core";
+import { scFromTags } from "./wcag-tags";
+
+// Re-exported so the historical `import { scFromTags } from "./collect-dom"`
+// keeps working; the implementation now lives in the browser-free `wcag-tags.ts`
+// so the offline baseline generator can share it without pulling in playwright.
+export { scFromTags };
+
+/** The result of rendering one URL and running axe over it. */
+export interface DomScanResult {
+  readonly url: string;
+  readonly findings: readonly Finding[];
+}
+
+/** Options for {@link scanUrl}. */
+export interface DomScanOptions {
+  /** Max ms to wait for navigation + the `load` event. Default 30_000. */
+  readonly timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Flatten an axe node target into a single CSS selector string. axe reports
+ * `target` as an array — one entry per frame for cross-frame nodes — so we join
+ * with the iframe-descent ` >>> ` marker axe itself uses. Nested arrays (shadow
+ * DOM) are flattened the same way.
+ */
+function selectorOf(target: readonly unknown[]): string {
+  return target.flat(Infinity).map(String).join(" >>> ");
+}
+
+/**
+ * Render `url` in a real browser and return its accessibility findings as
+ * `Finding[]` — the same shape the source passes emit, so callers run the
+ * identical `enrichAll` + report path. Each axe violation expands to one finding
+ * per offending node (so the report points at the actual elements). WCAG SC is
+ * read from the violation's tags; enforcement is the zero-config default
+ * (`block`) since a live URL has no `binclusive.json`.
+ *
+ * The browser is always closed, even on error. The caller owns the URL's
+ * trustworthiness — this navigates to and executes whatever the page serves.
+ */
+export async function scanUrl(url: string, opts: DomScanOptions = {}): Promise<DomScanResult> {
+  const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const browser = await chromium.launch();
+  try {
+    // @axe-core/playwright 4.11.x rejects pages from the implicit default
+    // context — it requires an explicit browser.newContext().
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    // A typo'd or unreachable URL (or a nav timeout) rejects raw inside goto;
+    // re-throw it as an actionable Error that names the URL, the cause, and the
+    // most common real-world fix (pointing at a running server, not a raw
+    // template file). The caller prints just this message — no stack.
+    try {
+      await page.goto(url, { waitUntil: "load", timeout });
+    } catch (cause) {
+      // Playwright's message embeds a multi-line "Call log:" block; keep only the
+      // first line so the actionable Error reads as one clean line, not a dump.
+      const raw = cause instanceof Error ? cause.message : String(cause);
+      const reason = raw.split("\n")[0];
+      throw new Error(
+        `Failed to load ${url}: ${reason}. Check the URL is reachable; server-side templates (.cshtml etc.) only render via a running server — point check-url at localhost.`,
+      );
+    }
+    const results = await new AxeBuilder({ page }).analyze();
+
+    const findings: Finding[] = [];
+    for (const v of results.violations) {
+      const wcag = scFromTags(v.tags);
+      const enforcement = enforcementFor(wcag, null);
+      for (const node of v.nodes) {
+        // axe's runtime IMPACT is the most accurate signal: it is computed
+        // against the actual rendered node. Prefer the per-node impact; fall
+        // back to the violation-level impact when axe leaves the node's null.
+        const impact = node.impact ?? v.impact ?? undefined;
+        findings.push({
+          file: url,
+          line: 0,
+          selector: selectorOf(node.target),
+          ruleId: v.id,
+          message: v.help,
+          wcag,
+          enforcement,
+          provenance: "axe",
+          ...(impact != null ? { impact } : {}),
+          helpUrl: v.helpUrl,
+        });
+      }
+    }
+    return { url, findings };
+  } finally {
+    await browser.close();
+  }
+}

package/src/collect-liquid.ts

@@ -0,0 +1,103 @@
+/**
+ * The Liquid STATIC collector — L3 of the Shopify/Liquid producer (issue #50),
+ * the 5th producer of {@link Finding}s, parallel to the jsx-a11y structural pass
+ * (`core.ts`), the corpus enforce pass (`enforce.ts`), the rendered-DOM/axe pass
+ * (`collect-dom.ts`), and the SwiftUI static pass (`collect-swift.ts`).
+ *
+ * Unlike the SwiftUI collector, the analysis is IN-process: L1 (`liquid-ast.ts`)
+ * parses each `.liquid` file with `@shopify/liquid-html-parser` and L2
+ * (`liquid-rules.ts`) applies the structural-absence rules. This module is the
+ * THIN file walk + boundary: collect the `.liquid` files under a dir, parse each
+ * (skipping — never crashing on — a malformed file), run the rules, and stamp the
+ * contract-derived enforcement level onto every finding. The result mirrors
+ * `scanSwift`'s shape so the `check-shopify` CLI runner is a sibling of
+ * `runCheckSwift`.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { contractForFiles, enforcementFor } from "./config-scan";
+import type { Finding } from "./core";
+import { parseLiquid } from "./liquid-ast";
+import { runLiquidRules } from "./liquid-rules";
+
+/** Build/vendor dirs that are not theme source — skipped on the walk, same set
+ * the `.tsx` walk (`collect.ts`) and the SwiftUI walk skip. */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".cache"]);
+
+/**
+ * Recursively collect `.liquid` files under `dir`, skipping build/vendor dirs.
+ * A missing or unreadable directory yields `[]` rather than throwing — a
+ * non-existent scan target is an empty scan, the same forgiving contract the
+ * other collectors give the CLI.
+ */
+export async function collectLiquidFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...(await collectLiquidFiles(full)));
+    } else if (entry.isFile() && entry.name.endsWith(".liquid")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** One file the parser could not handle — surfaced as a skipped-count line in the
+ * report, never as a crash (the precision invariant: one bad file must not take
+ * down a whole-theme scan). */
+export interface LiquidParseError {
+  readonly file: string;
+  readonly message: string;
+}
+
+/** The result of a `.liquid` theme scan — mirrors `SwiftScanResult` plus the
+ * parse-error list the in-process parser can produce. */
+export interface LiquidScanResult {
+  readonly root: string;
+  readonly files: readonly string[];
+  readonly findings: readonly Finding[];
+  readonly parseErrors: readonly LiquidParseError[];
+}
+
+/**
+ * Scan `.liquid` theme source under `dir` for static structural a11y findings.
+ *
+ * Collects the files, finds the governing `binclusive.json` (package-up, the same
+ * rule the jsx-a11y and SwiftUI scans use — with no contract every finding is
+ * `block`), then for each file parses + runs the L2 rules and stamps the
+ * contract-derived enforcement onto each finding (per-finding, exactly like
+ * `scanSwift`). A file the parser rejects is recorded in `parseErrors` and
+ * skipped — it never aborts the scan.
+ */
+export async function scanLiquid(dir: string): Promise<LiquidScanResult> {
+  const root = resolve(dir);
+  const files = await collectLiquidFiles(root);
+  const contract = contractForFiles(files);
+
+  const findings: Finding[] = [];
+  const parseErrors: LiquidParseError[] = [];
+
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    const parsed = parseLiquid(source);
+    if (!parsed.ok) {
+      parseErrors.push({ file, message: parsed.error.message });
+      continue;
+    }
+    const raw = runLiquidRules(parsed.ast, { file, source, enforcement: "block" });
+    for (const finding of raw) {
+      findings.push({ ...finding, enforcement: enforcementFor(finding.wcag, contract) });
+    }
+  }
+
+  return { root, files, findings, parseErrors };
+}

package/src/collect-swift.ts

@@ -0,0 +1,227 @@
+/**
+ * The SwiftUI STATIC collector — the 4th producer of {@link Finding}s, parallel
+ * to the jsx-a11y structural pass (`core.ts`) and the corpus enforce pass
+ * (`enforce.ts`).
+ *
+ * The accessibility analysis itself lives OUT of process, in a SwiftPM binary
+ * (`swift/A11ySwiftScan`) that parses `.swift` source with SwiftSyntax and applies
+ * the static rules from `plugin/skills/swiftui-a11y/SKILL.md` — crucially with the
+ * ancestor-climb heuristic that stops a label on the enclosing
+ * Button/NavigationLink/toolbar item from reading as a false positive. We can't run
+ * SwiftSyntax from Node, so this module is the THIN boundary: spawn the engine, read
+ * its JSON array from stdout, and map each raw record into a full `Finding` carrying
+ * `provenance: "swiftui"` and the contract-derived enforcement level — exactly the
+ * external-engine→Finding shape an out-of-process DOM/axe collector would use.
+ *
+ * Two invocation strategies, tried in order:
+ *   1. the prebuilt release binary (`swift build -c release` was run once) — fast,
+ *      no compile on every scan;
+ *   2. `swift run --package-path …` — a fallback that compiles on first use, so the
+ *      collector still works on a machine where the release build hasn't been made.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { contractForFiles, enforcementFor } from "./config-scan";
+import type { Finding } from "./core";
+
+/** The two SwiftUI static rule ids the engine emits — the contract with it. */
+type SwiftRuleId = "swiftui/image-no-label" | "swiftui/control-no-name";
+
+/**
+ * One raw finding as the Swift engine prints it. Mirrors `Finding.swift` exactly:
+ * `{ file, line, ruleId, message, wcag: ["1.1.1"], severity: "serious"|"critical" }`.
+ * Validated structurally at the process boundary before it becomes a `Finding`.
+ */
+interface SwiftFinding {
+  readonly file: string;
+  readonly line: number;
+  readonly ruleId: SwiftRuleId;
+  readonly message: string;
+  readonly wcag: readonly string[];
+  readonly severity: "serious" | "critical";
+}
+
+/**
+ * Resolve `dir` to a canonical, symlink-free absolute path — the same namespace
+ * the Swift engine emits its `file` paths in (it walks via macOS `FileManager`,
+ * which resolves symlinks). Both the engine input and the `root` returned in
+ * {@link SwiftScanResult} derive from this, so the CLI's `relative(root, …)`
+ * always agrees with the engine's emitted paths. Falls back to a plain `resolve`
+ * when the path doesn't exist yet (the engine then reports the empty scan).
+ *
+ * Module-private: the canonical root is an INTERNAL namespace decision the
+ * collector owns. It is not exported — the CLI receives the root it must render
+ * against on {@link SwiftScanResult.root}, so no path helper crosses the seam.
+ */
+function canonicalRoot(dir: string): string {
+  const abs = resolve(dir);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+}
+
+/** The in-repo location of the Swift package, resolved relative to this file. */
+function packageRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // src/collect-swift.ts -> <repo>/swift/A11ySwiftScan
+  return resolve(here, "..", "swift", "A11ySwiftScan");
+}
+
+/** The prebuilt release binary path, or `null` when it hasn't been built yet. */
+function releaseBinary(): string | null {
+  const bin = join(packageRoot(), ".build", "release", "A11ySwiftScan");
+  return existsSync(bin) ? bin : null;
+}
+
+/**
+ * Build the command+args to run the engine against `dir`. Prefers the prebuilt
+ * release binary; falls back to `swift run --package-path` so a fresh checkout
+ * works without a manual build step (it just compiles on first use).
+ */
+function engineInvocation(dir: string): { command: string; args: string[] } {
+  const bin = releaseBinary();
+  if (bin !== null) {
+    return { command: bin, args: [dir] };
+  }
+  return {
+    command: "swift",
+    // `--` ends `swift run`'s own option parsing so a `dir` that starts with `-`
+    // is passed through to the engine as a positional, never read as a flag.
+    args: ["run", "-c", "release", "--package-path", packageRoot(), "A11ySwiftScan", "--", dir],
+  };
+}
+
+/** Spawn the engine and resolve with its raw stdout (the JSON array text). */
+function runEngine(dir: string): Promise<string> {
+  const { command, args } = engineInvocation(dir);
+  return new Promise<string>((resolvePromise, reject) => {
+    const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolvePromise(stdout);
+      } else {
+        reject(
+          new Error(
+            `A11ySwiftScan exited with code ${code ?? "null"}` +
+              (stderr.trim() !== "" ? `:\n${stderr.trim()}` : ""),
+          ),
+        );
+      }
+    });
+  });
+}
+
+/**
+ * Boundary-parse the engine's stdout into validated {@link SwiftFinding}s. A
+ * malformed record is dropped rather than smuggling untyped data inward — the
+ * engine is trusted, but this is the one place its output crosses into TS, so we
+ * narrow it explicitly (the same discipline `corpus.ts` uses at the JSON
+ * boundary).
+ */
+export function parseSwiftFindings(raw: string): SwiftFinding[] {
+  const text = raw.trim();
+  if (text === "") return [];
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch (err) {
+    // The engine contract is a JSON array on stdout. Non-JSON here means the
+    // engine misbehaved (a stray log line, a partial write, a crash banner) —
+    // fail loud with a one-line, actionable error instead of letting a raw
+    // SyntaxError bubble untyped across the boundary.
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`A11ySwiftScan produced non-JSON output (${detail})`);
+  }
+  if (!Array.isArray(data)) return [];
+  const out: SwiftFinding[] = [];
+  for (const item of data) {
+    if (typeof item !== "object" || item === null) continue;
+    const r = item as Record<string, unknown>;
+    if (
+      typeof r.file === "string" &&
+      typeof r.line === "number" &&
+      (r.ruleId === "swiftui/image-no-label" || r.ruleId === "swiftui/control-no-name") &&
+      typeof r.message === "string" &&
+      Array.isArray(r.wcag) &&
+      r.wcag.every((w) => typeof w === "string") &&
+      (r.severity === "serious" || r.severity === "critical")
+    ) {
+      out.push({
+        file: r.file,
+        line: r.line,
+        ruleId: r.ruleId,
+        message: r.message,
+        wcag: r.wcag as readonly string[],
+        severity: r.severity,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * The full output of a SwiftUI scan, parallel to `scan`: the findings plus the
+ * canonical, symlink-free `root` the collector actually scanned in. The CLI
+ * renders `relative(root, …)` against THIS — so the collector owns its path
+ * namespace end-to-end and the CLI imports no path helper from here.
+ */
+export interface SwiftScanResult {
+  readonly root: string;
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * Scan `.swift` source under `dir` for static SwiftUI accessibility findings.
+ *
+ * Shells to the Swift engine, parses its JSON, and maps each raw record into a
+ * full {@link Finding} — `provenance: "swiftui"`, the engine's `file`/`line`/
+ * `ruleId`/`message`/`wcag`, and the enforcement level the governing
+ * `binclusive.json` assigns to that finding's WCAG SC (or `block` with no
+ * contract, the historical default). The engine's own `severity` is folded into
+ * the message so it survives into the report without widening the `Finding`
+ * shape — the TS side stays a pure mirror of the existing collectors.
+ */
+export async function scanSwift(dir: string): Promise<SwiftScanResult> {
+  // Canonicalize: the engine walks the tree via macOS `FileManager`, which
+  // resolves symlinks (e.g. `/tmp` → `/private/tmp`), so every emitted `file`
+  // is a real path. Feeding it the real root keeps the engine's output and the
+  // report's `relative(root, …)` base in the same namespace — otherwise a
+  // symlinked root renders broken `../../private/…` paths. We return this `root`
+  // so the CLI renders against the exact namespace the engine emitted in.
+  const root = canonicalRoot(dir);
+  const raw = await runEngine(root);
+  const swiftFindings = parseSwiftFindings(raw);
+
+  // The contract that governs these files, found by walking up from them — same
+  // package-up rule the jsx-a11y scan uses (`contractForFiles`). With no
+  // `binclusive.json` every finding is `block`.
+  const contract = contractForFiles(swiftFindings.map((f) => f.file));
+
+  const findings: Finding[] = swiftFindings.map((f) => ({
+    file: f.file,
+    line: f.line,
+    ruleId: f.ruleId,
+    // Carry the engine's severity in the message so the existing report path
+    // (which has no `severity` field) still surfaces it.
+    message: `[${f.severity}] ${f.message}`,
+    wcag: f.wcag,
+    enforcement: enforcementFor(f.wcag, contract),
+    provenance: "swiftui",
+  }));
+
+  return { root, findings };
+}

package/src/collect-unity.ts

@@ -0,0 +1,99 @@
+/**
+ * The Unity STATIC collector — L3 of the Unity producer (issue #71, ADR 0004), the
+ * analog of `collect-liquid.ts` for the Unity ecosystem.
+ *
+ * This is the THIN file walk + boundary: collect the `.prefab` / `.unity` assets
+ * under a project dir, parse each into a node graph (or an OPAQUE state) via L1
+ * (`unity-ast.ts`), and hand back a per-asset result the structural-absence rules
+ * (later children #70/#72/#73) will walk. Identity resolution rides on the built-in
+ * widget GUID registry (`unity-guid-registry.ts`).
+ *
+ * Mirrors `scanLiquid`'s shape: a forgiving walk (a missing dir is an empty scan),
+ * and one bad/binary asset is recorded as opaque, never a crash — opaque is reported,
+ * not silently skipped (ADR 0004). This slice emits no `Finding`s yet (the rules are
+ * separate children); it stands up the producer + graph the rules attach to.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parseUnityDocument, type UnityParseResult } from "./unity-ast";
+
+/** Build/library dirs that are not project source — skipped on the walk. `Library`
+ * and `Temp` are Unity's generated caches; the rest match the other collectors. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".cache",
+  "Library",
+  "Temp",
+  "obj",
+]);
+
+/** The Unity serialized-asset extensions this slice reads: uGUI prefab YAML and
+ * scene YAML. (`.uxml`/`.inputactions` are out of scope — ADR 0004 / #71.) */
+const UNITY_EXTENSIONS = [".prefab", ".unity"] as const;
+
+const isUnityAsset = (name: string): boolean =>
+  UNITY_EXTENSIONS.some((ext) => name.endsWith(ext));
+
+/**
+ * Recursively collect `.prefab` / `.unity` files under `dir`, skipping build/library
+ * dirs. A missing or unreadable directory yields `[]` rather than throwing — a
+ * non-existent scan target is an empty scan, the forgiving contract the other
+ * collectors give the CLI.
+ */
+export async function collectUnityFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...(await collectUnityFiles(full)));
+    } else if (entry.isFile() && isUnityAsset(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** One scanned asset and its parse outcome — a walkable graph, or an OPAQUE state
+ * (binary / unparseable) surfaced rather than skipped. */
+export interface UnityAsset {
+  readonly file: string;
+  readonly parse: UnityParseResult;
+}
+
+/** The result of a Unity project scan — mirrors `LiquidScanResult`'s shape with
+ * per-asset parse outcomes in place of findings (rules are later children). */
+export interface UnityScanResult {
+  readonly root: string;
+  readonly files: readonly string[];
+  readonly assets: readonly UnityAsset[];
+}
+
+/**
+ * Scan Unity serialized source under `dir`. Collects the assets, then parses each into
+ * a graph or an opaque state. A binary (non-Force-Text) or unparseable asset is
+ * recorded as `{ kind: "opaque", … }` on its `UnityAsset` and the scan continues — one
+ * bad asset never aborts the scan, and the opaque state is reported, not hidden.
+ */
+export async function scanUnity(dir: string): Promise<UnityScanResult> {
+  const root = resolve(dir);
+  const files = await collectUnityFiles(root);
+
+  const assets: UnityAsset[] = [];
+  for (const file of files) {
+    const source = await readFile(file, "utf8");
+    assets.push({ file, parse: parseUnityDocument(source) });
+  }
+
+  return { root, files, assets };
+}

package/src/collect.ts

@@ -0,0 +1,54 @@
+/**
+ * Recursively collect the `.tsx` source files under a directory — the scan
+ * target set shared by the `check` command and stack detection. Build and
+ * generated dirs are skipped: generated Relay artifacts (`__generated__`) are
+ * not source and would only add noise.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".next",
+  ".turbo",
+  "__generated__",
+  ".git",
+  "dist",
+  // Test scaffolding is not shipped UI — its `.tsx` files are fixtures/specs,
+  // not pages a visitor ever loads. Skipping the dir keeps both the scan and
+  // stack detection focused on production code (Saleor's findings were ~20%
+  // test scaffolding before this).
+  "__tests__",
+  "__mocks__",
+]);
+
+/**
+ * A test/spec file by name: `Foo.test.tsx`, `Foo.spec.tsx`, and the `stories`
+ * variants. These ship in the repo but never render to a real visitor, so an
+ * a11y finding in one is noise, not a defect. Matched on the filename so it
+ * holds regardless of directory layout.
+ */
+function isTestFile(name: string): boolean {
+  return /\.(test|spec|stories)\.tsx$/.test(name);
+}
+
+/**
+ * Recursively collect `.tsx` files under `dir`, skipping build/generated dirs
+ * and test scaffolding (`*.test.tsx` / `*.spec.tsx`, `__tests__/`). Shipped UI
+ * only — the unit under accessibility test.
+ */
+export async function collectTsx(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...(await collectTsx(full)));
+    } else if (entry.isFile() && entry.name.endsWith(".tsx") && !isTestFile(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}