@binclusive/a11y 0.1.0 → 0.1.2

package/src/cli.ts

@@ -6,6 +6,7 @@ import { Effect, Option } from "effect";
 import type { Impact } from "@binclusive/a11y-contract";
 import { type AgentLaneOverrides, augmentWithAgentLane } from "./agent-lane";
 import { collectTsx } from "./collect";
+import { scanAndroidXml } from "./collect-android-xml";
 // Type-only: the rendered-DOM lane (playwright/@axe-core) is loaded lazily inside
 // `runCheckUrl` so the static `check` path carries no eager browser-stack import
 // and the CI image can ship without it (issue #2133).
@@ -17,7 +18,7 @@ import { collectUnityFindings } from "./unity-findings";
 import { type FindingProvenance, scan } from "./core";
 import { type Evidence, type EnrichedFinding, enrichAll, evidenceImpact, resolveDisplay } from "./evidence";
 import { runHookCli } from "./hook";
-import { phoneHome } from "./phone-home";
+import { type PhoneHomeDeps, phoneHome } from "./phone-home";
 import { formatSarif } from "./sarif";
 import {
   GATE_OFF,
@@ -47,10 +48,14 @@ export function detailLines(f: EnrichedFinding): string[] {
         : f.provenance === "swiftui"
           ? "  (SwiftUI static)"
           : "";
+  // Impact-first voice (#14): the message LEADS — it names the harmed user and
+  // the human consequence, the first thing a reader sees under the location. The
+  // rule id and WCAG SC follow as SECONDARY lines (and the corpus block further
+  // below), so the identifiers frame the finding without burying the impact.
   const lines = [
+    `    ${f.message}`,
     `    rule:   ${f.ruleId}  [${f.enforcement}]${via}`,
     `    wcag:   ${scList}`,
-    `    ${f.message}`,
   ];
 
   // The display contract resolves the axe-vs-SC policy once (see resolveDisplay):
@@ -355,6 +360,66 @@ export function buildJsonReport(
   };
 }
 
+/**
+ * The zeroed coverage literal for a stack with no component resolver (Liquid,
+ * Unity) or an empty scan — the `--json`/`buildJsonReport` shape stays identical
+ * to `check` even when there is nothing to resolve.
+ */
+const EMPTY_COVERAGE: Coverage = {
+  total: 0,
+  declared: 0,
+  registry: 0,
+  traced: 0,
+  opaque: 0,
+  trusted: 0,
+  icons: 0,
+  structural: 0,
+  declare: 0,
+};
+
+/** The run context a machine-readable emit needs, threaded from each stack runner. */
+interface EmitContext {
+  readonly root: string;
+  readonly runId: string;
+  readonly filesScanned: number;
+  readonly coverage: Coverage;
+  /** ABSOLUTE paths this run analyzed — phone-home relativizes them into `scannedPaths` (ADR 0043). */
+  readonly analyzedFiles: readonly string[];
+  readonly gate: GateConfig;
+  /** Test-only seam: override phone-home transport deps to capture the projected wire batch (#163 tracer). */
+  readonly phoneHome?: Partial<PhoneHomeDeps>;
+}
+
+/**
+ * The ONE machine-readable emit path, shared by every stack runner (#163). SARIF
+ * and phone-home are the only two consumers that carry findings off the machine,
+ * and both narrow through the canonical `@binclusive/a11y-contract` vocabulary —
+ * so a new stack (`check-shopify`, and next `check-swift`/`check-unity`/…) reaches
+ * the wire by routing HERE, never by re-forking a bespoke `buildJsonReport`→stdout
+ * path. `text` is intentionally excluded: the human report differs per stack and
+ * stays in each runner.
+ */
+async function emitFindings(
+  format: "json" | "sarif",
+  findings: readonly EnrichedFinding[],
+  ctx: EmitContext,
+): Promise<void> {
+  if (format === "sarif") {
+    console.log(formatSarif(findings, ctx.runId, { root: ctx.root }));
+  } else {
+    console.log(JSON.stringify(buildJsonReport(ctx.root, ctx.filesScanned, ctx.coverage, findings), null, 2));
+    // OPTIONAL, non-blocking phone-home (#2108): file metadata-only findings to the
+    // dashboard when the CI env carries a `b8e_` token + org/project. Env-gated, so a
+    // local run silently skips; a failure is swallowed inside `phoneHome` and never
+    // changes the exit code. Inject this run's analyzed set (ADR 0043) as `scannedPaths`.
+    await phoneHome(findings, ctx.root, process.env, {
+      analyzedFiles: () => [...ctx.analyzedFiles],
+      ...ctx.phoneHome,
+    });
+  }
+  process.exitCode = gateExitCode(findings.map(toGateFinding), ctx.gate);
+}
+
 /**
  * The shared report tail for both runners (source + rendered-DOM): empty-state,
  * grouped findings, the totals rollup, and the blocking-gated exit code. Each
@@ -404,6 +469,37 @@ function renderReport(
   process.exitCode = gateExitCode(findings.map(toGateFinding), gate);
 }
 
+/**
+ * The ONE report+gate path every stack runner shares (issue #176). A machine
+ * format routes through {@link emitFindings} (SARIF / JSON + phone-home); `text`
+ * routes through the human {@link renderReport}. BOTH branches derive the exit
+ * code from the SAME `gate` on `ctx` (via `gateExitCode`), so a stack scan's exit
+ * is identical across text / --json / --sarif and honors --fail-on /
+ * --max-violations / --ci everywhere. The old format-dependent split (advisory
+ * exit on the machine branch, block-gated exit on the text branch) is
+ * unrepresentable here: there is one gate, threaded once.
+ */
+async function reportStack(
+  format: OutputFormat,
+  findings: readonly EnrichedFinding[],
+  ctx: EmitContext,
+  text: {
+    /** Human-report preamble (scan header / parse-skips) — printed for `text` only. */
+    readonly preamble: () => void;
+    readonly emptyMessage: string;
+    readonly groupKey: (f: EnrichedFinding) => string;
+    readonly groupHeader: (key: string) => string;
+    readonly formatItem: (f: EnrichedFinding) => string;
+  },
+): Promise<void> {
+  if (format !== "text") {
+    await emitFindings(format, findings, ctx);
+    return;
+  }
+  text.preamble();
+  renderReport(findings, text, ctx.gate);
+}
+
 /**
  * The `check` command's runner. The optional {@link AgentLaneOverrides} is the AI
  * lane's ONLY injection seam: the CLI handler never passes it (the lane resolves
@@ -430,14 +526,13 @@ export async function runCheck(
     // Non-blocking — agent findings are warn-only, so the block-gated exit is
     // computed on the augmented list and can only reflect the deterministic floor.
     const findings = await augmentWithAgentLane(deterministic, root, process.env, agentOverrides);
-    console.log(formatSarif(findings, runId, { root }));
-    process.exitCode = gateExitCode(findings.map(toGateFinding), gate);
+    await emitFindings("sarif", findings, { root, runId, filesScanned: files.length, coverage: EMPTY_COVERAGE, analyzedFiles: [], gate });
     return;
   }
 
   if (json) {
     if (files.length === 0) {
-      const report = buildJsonReport(root, 0, { total: 0, declared: 0, registry: 0, traced: 0, opaque: 0, trusted: 0, icons: 0, structural: 0, declare: 0 }, []);
+      const report = buildJsonReport(root, 0, EMPTY_COVERAGE, []);
       console.log(JSON.stringify(report, null, 2));
       return;
     }
@@ -445,18 +540,17 @@ export async function runCheck(
     const deterministic = enrichAll(result.findings);
     // AI lane (issue #2182): agent findings flow through the SAME JSON report and
     // phone-home envelope as the deterministic floor. When no key is present this
-    // returns `deterministic` unchanged.
+    // returns `deterministic` unchanged. Inject this run's true analyzed set (ADR
+    // 0043) so phone-home emits it as `scannedPaths` — 4b's reconcile keys on it.
     const findings = await augmentWithAgentLane(deterministic, root, process.env, agentOverrides);
-    const report = buildJsonReport(root, files.length, result.coverage, findings);
-    console.log(JSON.stringify(report, null, 2));
-    // OPTIONAL, non-blocking phone-home (#2108): file metadata-only findings to
-    // the dashboard when the CI env carries a `b8e_` token + org/project. Fully
-    // env-gated, so a local `check --json` (no such env) silently skips; a
-    // failure here is swallowed inside `phoneHome` and never changes exit code.
-    // Inject this run's true analyzed set (ADR 0043) so phone-home emits it as
-    // `scannedPaths` — the source-scan-scope coverage 4b's reconcile keys on.
-    await phoneHome(findings, root, process.env, { analyzedFiles: () => result.analyzedFiles });
-    process.exitCode = gateExitCode(findings.map(toGateFinding), gate);
+    await emitFindings("json", findings, {
+      root,
+      runId,
+      filesScanned: files.length,
+      coverage: result.coverage,
+      analyzedFiles: result.analyzedFiles,
+      gate,
+    });
     return;
   }
 
@@ -504,8 +598,16 @@ function normalizeTarget(target: string): string {
  * selectors instead of source lines. This is the source-less path — it inspects
  * what actually ships, so it covers non-React pages and anything the static
  * .tsx scan can't see (server-rendered markup, third-party widgets, runtime DOM).
+ *
+ * The optional {@link PhoneHomeDeps} overrides mirror `runCheck`'s `agentOverrides`
+ * seam: the CLI handler never passes them (phone-home resolves its config + fetch
+ * from the env), but the behavioral tracer test injects a stub `fetch` to prove a
+ * real rendered-URL finding reaches the wire as a page-shaped contract.
  */
-async function runCheckUrl(url: string): Promise<void> {
+export async function runCheckUrl(
+  url: string,
+  phoneHomeOverrides: Partial<PhoneHomeDeps> = {},
+): Promise<void> {
   const target = normalizeTarget(url);
   console.log(`a11y-checker — rendering ${target} and running axe-core\n`);
 
@@ -532,6 +634,21 @@ async function runCheckUrl(url: string): Promise<void> {
     groupHeader: (ruleId) => ruleId,
     formatItem: (f) => formatUrlFinding(f),
   });
+
+  // OPTIONAL, non-blocking phone-home (#2335): route the rendered-URL findings
+  // through the SAME emit seam the static `check --json` path uses. Inside
+  // `phoneHome`, `toFindingPayloadLenient` → `resolveLocations` branches each
+  // `^https?://` finding to the canonical page-shaped `{ location: { kind: "page",
+  // url }, … }` contract and POSTs it when the CI env carries a `b8e_` token +
+  // org/project. Fully env-gated, swallows its own failures, and never touches the
+  // exit code the gate above set. The scanned page IS the scanned target — the
+  // same `url` vocabulary platform-side scope-reconcile keys on (#2166). `root` is
+  // the cwd: page findings resolve their location from the URL, not `root`, and a
+  // URL scan analyzes no source files (`scannedPaths` stays the safe empty set).
+  await phoneHome(findings, process.cwd(), process.env, {
+    scanTargets: () => [target],
+    ...phoneHomeOverrides,
+  });
 }
 
 /**
@@ -542,7 +659,12 @@ async function runCheckUrl(url: string): Promise<void> {
  * exactly as `runCheck` does. The Swift toolchain may be missing — `scanSwift`
  * surfaces that as a one-line Error, handled like `runCheckUrl`'s launch failure.
  */
-async function runCheckSwift(dir: string): Promise<void> {
+async function runCheckSwift(
+  dir: string,
+  format: OutputFormat = "text",
+  runId = "local",
+  gate: GateConfig = GATE_OFF,
+): Promise<void> {
   let result: Awaited<ReturnType<typeof scanSwift>>;
   try {
     result = await scanSwift(dir);
@@ -557,16 +679,22 @@ async function runCheckSwift(dir: string): Promise<void> {
   // `root` it scanned in, so `relative(root, …)` here renders clean
   // `Sources/…/X.swift:line` locations that agree with the engine's emitted paths.
   const { root } = result;
-  console.log(`a11y-checker — scanning .swift under ${root} for SwiftUI a11y\n`);
-
   const findings = enrichAll(result.findings);
 
-  renderReport(findings, {
-    emptyMessage: "No SwiftUI a11y violations found.",
-    groupKey: (f) => f.file,
-    groupHeader: (file) => relative(root, file),
-    formatItem: (f) => formatFinding(f, root),
-  });
+  // Swift's engine reports findings, not a scanned-file list — filesScanned/coverage
+  // stay zeroed in the machine report, identical to Unity (no component resolver).
+  await reportStack(
+    format,
+    findings,
+    { root, runId, filesScanned: 0, coverage: EMPTY_COVERAGE, analyzedFiles: [], gate },
+    {
+      preamble: () => console.log(`a11y-checker — scanning .swift under ${root} for SwiftUI a11y\n`),
+      emptyMessage: "No SwiftUI a11y violations found.",
+      groupKey: (f) => f.file,
+      groupHeader: (file) => relative(root, file),
+      formatItem: (f) => formatFinding(f, root),
+    },
+  );
 }
 
 /**
@@ -577,42 +705,54 @@ async function runCheckSwift(dir: string): Promise<void> {
  * has no component resolver, so coverage is zeroed in the `--json` shape. A file
  * the parser rejects is skipped (surfaced as a count), never fatal.
  */
-async function runCheckShopify(dir: string, json = false): Promise<void> {
+export async function runCheckShopify(
+  dir: string,
+  format: OutputFormat = "text",
+  runId = "local",
+  phoneHomeOverrides: Partial<PhoneHomeDeps> = {},
+  gate: GateConfig = GATE_OFF,
+): Promise<void> {
   const { root, files, findings: raw, parseErrors } = await scanLiquid(dir);
   const findings = enrichAll(raw);
 
-  if (json) {
-    // Liquid carries no resolver coverage — emit the zeroed coverage literal so
-    // the JSON shape stays identical to `check`.
-    const report = buildJsonReport(
+  // Route through the SAME report+gate path as `check` (#163 for the wire, #176
+  // for the gate): SARIF / JSON + `toContractFinding` phone-home on the machine
+  // branch, the human report on text — both gated by the SAME `gate`, so the exit
+  // is format-independent (no more advisory-on-json vs block-on-text split). Liquid
+  // carries no component resolver (zeroed coverage) and the whole scanned set is
+  // analyzed.
+  await reportStack(
+    format,
+    findings,
+    {
       root,
-      files.length,
-      { total: 0, declared: 0, registry: 0, traced: 0, opaque: 0, trusted: 0, icons: 0, structural: 0, declare: 0 },
-      findings,
-    );
-    console.log(JSON.stringify(report, null, 2));
-    const blocking = findings.filter((f) => f.enforcement === "block").length;
-    process.exitCode = blocking > 0 ? 1 : 0;
-    return;
-  }
-
-  if (files.length === 0) {
-    console.log(`No .liquid files under ${root}`);
-    return;
-  }
-
-  console.log(`a11y-checker — scanned ${files.length} .liquid file(s) under ${root}`);
-  if (parseErrors.length > 0) {
-    console.log(`  (${parseErrors.length} file(s) skipped — could not parse)`);
-  }
-  console.log("");
-
-  renderReport(findings, {
-    emptyMessage: "No Liquid a11y violations found.",
-    groupKey: (f) => f.file,
-    groupHeader: (file) => relative(root, file),
-    formatItem: (f) => formatFinding(f, root),
-  });
+      runId,
+      filesScanned: files.length,
+      coverage: EMPTY_COVERAGE,
+      analyzedFiles: files,
+      gate,
+      phoneHome: phoneHomeOverrides,
+    },
+    {
+      // A theme with no .liquid files is a distinct, more specific empty-state than
+      // "no findings" — preserve it (and skip the scan-count header entirely).
+      preamble: () => {
+        if (files.length === 0) return;
+        console.log(`a11y-checker — scanned ${files.length} .liquid file(s) under ${root}`);
+        if (parseErrors.length > 0) {
+          console.log(`  (${parseErrors.length} file(s) skipped — could not parse)`);
+        }
+        console.log("");
+      },
+      emptyMessage:
+        files.length === 0
+          ? `No .liquid files under ${root}`
+          : "No Liquid a11y violations found.",
+      groupKey: (f) => f.file,
+      groupHeader: (file) => relative(root, file),
+      formatItem: (f) => formatFinding(f, root),
+    },
+  );
 }
 
 /**
@@ -625,33 +765,67 @@ async function runCheckShopify(dir: string, json = false): Promise<void> {
  * resolver, so coverage is zeroed in the `--json` shape — identical structure to
  * `check-shopify --json`.
  */
-async function runCheckUnity(dir: string, json = false): Promise<void> {
+async function runCheckUnity(
+  dir: string,
+  format: OutputFormat = "text",
+  runId = "local",
+  gate: GateConfig = GATE_OFF,
+): Promise<void> {
   const root = resolve(dir);
   const findings = enrichAll(await collectUnityFindings(root));
 
-  if (json) {
-    // Unity carries no resolver coverage — emit the zeroed coverage literal so the
-    // JSON shape stays identical to `check` / `check-shopify`.
-    const report = buildJsonReport(
-      root,
-      0,
-      { total: 0, declared: 0, registry: 0, traced: 0, opaque: 0, trusted: 0, icons: 0, structural: 0, declare: 0 },
-      findings,
-    );
-    console.log(JSON.stringify(report, null, 2));
-    const blocking = findings.filter((f) => f.enforcement === "block").length;
-    process.exitCode = blocking > 0 ? 1 : 0;
-    return;
-  }
+  // Unity carries no component resolver — coverage is zeroed so the machine report
+  // is identical in shape to `check` / `check-shopify`. Routing through the shared
+  // path (#176) replaces the old bespoke json-only exit with the SAME gate the text
+  // path uses, and adds the SARIF + phone-home wire the other stacks already reach.
+  await reportStack(
+    format,
+    findings,
+    { root, runId, filesScanned: 0, coverage: EMPTY_COVERAGE, analyzedFiles: [], gate },
+    {
+      preamble: () => console.log(`a11y-checker — scanning Unity Force-Text scenes under ${root}\n`),
+      emptyMessage: "No Unity a11y violations found.",
+      groupKey: (f) => f.file,
+      groupHeader: (file) => relative(root, file),
+      formatItem: (f) => formatFinding(f, root),
+    },
+  );
+}
 
-  console.log(`a11y-checker — scanning Unity Force-Text scenes under ${root}\n`);
+/**
+ * The Android counterpart to `runCheck`: statically scan an Android project's
+ * `res/layout*` XML in-process (`scanAndroidXml`), enrich through the SAME corpus
+ * cross-ref, and report findings anchored on `file:line` like every other
+ * producer. No browser, no network, no second toolchain — Android layouts are
+ * plain XML parsed in Node. A missing or unreadable project dir is an empty scan,
+ * never a throw. The collector returns the canonical `root` it scanned so
+ * `relative(root, …)` renders clean `app/src/main/res/layout/…:line` locations.
+ */
+async function runCheckAndroid(
+  dir: string,
+  format: OutputFormat = "text",
+  runId = "local",
+  gate: GateConfig = GATE_OFF,
+): Promise<void> {
+  const { root, files, findings: raw } = await scanAndroidXml(dir);
+  const findings = enrichAll(raw);
 
-  renderReport(findings, {
-    emptyMessage: "No Unity a11y violations found.",
-    groupKey: (f) => f.file,
-    groupHeader: (file) => relative(root, file),
-    formatItem: (f) => formatFinding(f, root),
-  });
+  // Android layouts are plain XML parsed in Node — the scanned file set is real,
+  // so filesScanned/analyzedFiles carry it (unlike Swift/Unity). No component
+  // resolver, so coverage is zeroed. Same shared report+gate path as every stack.
+  await reportStack(
+    format,
+    findings,
+    { root, runId, filesScanned: files.length, coverage: EMPTY_COVERAGE, analyzedFiles: files, gate },
+    {
+      preamble: () =>
+        console.log(`a11y-checker — scanning res/layout XML under ${root} for Android a11y\n`),
+      emptyMessage: "No Android XML a11y violations found.",
+      groupKey: (f) => f.file,
+      groupHeader: (file) => relative(root, file),
+      formatItem: (f) => formatFinding(f, root),
+    },
+  );
 }
 
 async function runInit(suggest: boolean, dirArg: string): Promise<void> {
@@ -831,26 +1005,52 @@ function resolveFormat(format: Option.Option<OutputFormat>, json: boolean, sarif
   return Option.getOrElse(format, (): OutputFormat => (sarif ? "sarif" : json ? "json" : "text"));
 }
 
+// The ONE gate + output-format flag set every `check*` command mounts (issue
+// #176). Sharing the exact same Options across `check` and each stack command
+// makes a divergent gate surface unrepresentable — no stack can quietly ship a
+// different exit-code policy than the reference `check` does.
+const gateOptions = {
+  json: Options.boolean("json"),
+  sarif: Options.boolean("sarif"),
+  format: formatOption,
+  ci: ciOption,
+  runId: Options.text("run-id").pipe(Options.withDefault("local")),
+  failOn: failOnOption,
+  maxViolations: maxViolationsOption,
+};
+
+/**
+ * Resolve the {@link GateConfig} from the parsed gate flags — the ONE gate every
+ * runner receives, so the exit-code policy (opt-in `--fail-on` / `--max-violations`
+ * over the non-blocking `--ci` baseline over the default block-gated exit) is
+ * decided identically for `check` and every stack command.
+ */
+function resolveGate(a: {
+  readonly failOn: Option.Option<Impact>;
+  readonly maxViolations: Option.Option<number>;
+  readonly ci: boolean;
+}): GateConfig {
+  return {
+    failOn: Option.getOrNull(a.failOn),
+    maxViolations: Option.getOrNull(a.maxViolations),
+    advisory: a.ci,
+  };
+}
+
 const checkCommand = Command.make(
   "check",
-  {
-    dir: dirArg,
-    json: Options.boolean("json"),
-    sarif: Options.boolean("sarif"),
-    format: formatOption,
-    ci: ciOption,
-    runId: Options.text("run-id").pipe(Options.withDefault("local")),
-    failOn: failOnOption,
-    maxViolations: maxViolationsOption,
-  },
+  { dir: dirArg, ...gateOptions },
   ({ dir, json, sarif, format, ci, runId, failOn, maxViolations }) => {
     const resolved = resolveFormat(format, json, sarif);
     return Effect.promise(() =>
-      runCheck(dir, resolved === "json", resolved === "sarif", runId, {}, {
-        failOn: Option.getOrNull(failOn),
-        maxViolations: Option.getOrNull(maxViolations),
-        advisory: ci,
-      }),
+      runCheck(
+        dir,
+        resolved === "json",
+        resolved === "sarif",
+        runId,
+        {},
+        resolveGate({ failOn, maxViolations, ci }),
+      ),
     );
   },
 ).pipe(
@@ -869,29 +1069,62 @@ const checkUrlCommand = Command.make(
   ),
 );
 
+// Every `check*` stack command mounts the SAME `gateOptions` and threads the SAME
+// `resolveFormat` + `resolveGate` as `check` (issue #176): one output-format
+// selector, one gate, one format-independent exit-code rule across all stacks.
+
 const checkSwiftCommand = Command.make(
   "check-swift",
-  { dir: dirArg },
-  ({ dir }) => Effect.promise(() => runCheckSwift(dir)),
-).pipe(Command.withDescription("scan .swift for SwiftUI accessibility findings (static)"));
+  { dir: dirArg, ...gateOptions },
+  ({ dir, json, sarif, format, ci, runId, failOn, maxViolations }) =>
+    Effect.promise(() =>
+      runCheckSwift(dir, resolveFormat(format, json, sarif), runId, resolveGate({ failOn, maxViolations, ci })),
+    ),
+).pipe(
+  Command.withDescription(
+    "scan .swift for SwiftUI accessibility findings (static; --format text|json|sarif; --ci / --fail-on / --max-violations gate identically to `check`)",
+  ),
+);
 
 const checkShopifyCommand = Command.make(
   "check-shopify",
-  { dir: dirArg, json: Options.boolean("json") },
-  ({ dir, json }) => Effect.promise(() => runCheckShopify(dir, json)),
+  { dir: dirArg, ...gateOptions },
+  ({ dir, json, sarif, format, ci, runId, failOn, maxViolations }) =>
+    // Reuse the CANONICAL `--format text|json|sarif` selector + gate the default
+    // `check` uses, so the Shopify scan reaches SARIF + the phone-home contract
+    // projection AND gates through the SAME path, not a bespoke flag (#163, #176).
+    Effect.promise(() =>
+      runCheckShopify(dir, resolveFormat(format, json, sarif), runId, {}, resolveGate({ failOn, maxViolations, ci })),
+    ),
 ).pipe(
   Command.withDescription(
-    "scan .liquid Shopify theme source for structural a11y findings (static, no browser; --json: machine-readable)",
+    "scan .liquid Shopify theme source for structural a11y findings (static, no browser; --format text|json|sarif — routes findings through the same canonical contract wire path AND gate as `check`)",
   ),
 );
 
 const checkUnityCommand = Command.make(
   "check-unity",
-  { dir: dirArg, json: Options.boolean("json") },
-  ({ dir, json }) => Effect.promise(() => runCheckUnity(dir, json)),
+  { dir: dirArg, ...gateOptions },
+  ({ dir, json, sarif, format, ci, runId, failOn, maxViolations }) =>
+    Effect.promise(() =>
+      runCheckUnity(dir, resolveFormat(format, json, sarif), runId, resolveGate({ failOn, maxViolations, ci })),
+    ),
+).pipe(
+  Command.withDescription(
+    "scan Unity Force-Text scenes (.prefab/.unity) for accessibility findings (static, no browser; --format text|json|sarif; --ci / --fail-on / --max-violations gate identically to `check`)",
+  ),
+);
+
+const checkAndroidCommand = Command.make(
+  "check-android",
+  { dir: dirArg, ...gateOptions },
+  ({ dir, json, sarif, format, ci, runId, failOn, maxViolations }) =>
+    Effect.promise(() =>
+      runCheckAndroid(dir, resolveFormat(format, json, sarif), runId, resolveGate({ failOn, maxViolations, ci })),
+    ),
 ).pipe(
   Command.withDescription(
-    "scan Unity Force-Text scenes (.prefab/.unity) for accessibility findings (static, no browser; --json: machine-readable)",
+    "scan Android res/layout XML for accessibility findings (static, in-process — no browser, no toolchain; --format text|json|sarif; --ci / --fail-on / --max-violations gate identically to `check`)",
   ),
 );
 
@@ -976,6 +1209,7 @@ const rootCommand = Command.make("a11y-checker", { dir: rootDir }, ({ dir }) =>
     checkSwiftCommand,
     checkShopifyCommand,
     checkUnityCommand,
+    checkAndroidCommand,
     initCommand,
     learnCommand,
     genCommand,