@binclusive/a11y 0.1.1 → 0.1.2

package/README.md

@@ -7,6 +7,8 @@ A local accessibility checker for React/TSX code, grounded in a real-world audit
 This is a private review build. Clone it, point it at any React codebase (yours or ours), and see what it finds — no setup, no explanation needed.
 
 > **New here? Start with the [Getting Started](docs/GETTING-STARTED.md) walkthrough.** Zero to your first fix — install, `init`, wire your editor, read a finding, clear it, gate CI.
+>
+> **Just want it on your PRs?** The [CI Quickstart](docs/QUICKSTART-CI.md) is the 5-minute path — copy [`examples/github-actions/a11y.yml`](examples/github-actions/a11y.yml), open a PR, read the findings. No account, no secret.
 
 ---
 
@@ -134,9 +136,12 @@ jobs:
   a11y:
     runs-on: ubuntu-latest
     steps:
+      # fetch-depth: 0 — the a11y diff scan needs base history; a shallow clone finds 0 changed files (a11y#198)
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - id: a11y
-        uses: Binclusive/a11y@main
+        uses: Binclusive/a11y@v0.1.1
       - if: always()  # advisory gate exits 0; upload regardless of findings
         uses: github/codeql-action/upload-sarif@v3
         with:
@@ -148,11 +153,11 @@ provenance (`deterministic` vs `agent`) in the SARIF property bag. The SARIF
 file exists only to render on **your** GitHub — it carries file/line for local
 annotation and is never sent to the Binclusive dashboard.
 
-> **Pin for supply-chain safety.** The examples use `@main` for readability, but
-> production workflows should pin the Action to a commit SHA — `uses:
-> Binclusive/a11y@<sha>  # v0.1.0` — rather than a floating tag or
-> branch, so a compromised upstream tag can't silently change what runs in your
-> CI. Dependabot (`github-actions` ecosystem) will bump the pin for you.
+> **Pin for supply-chain safety.** The examples pin to the released tag
+> `@v0.1.1`. For production, pin to a commit SHA — `uses:
+> Binclusive/a11y@<sha>  # v0.1.1` — rather than a floating tag or branch, so a
+> moved tag can't silently change what runs in your CI. Dependabot
+> (`github-actions` ecosystem) will bump the pin for you.
 
 ### Optional — opt into a blocking check (default off)
 
@@ -169,7 +174,7 @@ way.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y@main
+        uses: Binclusive/a11y@v0.1.1
         with:
           fail-on: critical    # optional — block only on critical findings
           # max-violations: 0  # optional — block on any finding at all
@@ -194,7 +199,7 @@ means "lane off", never an error; the scan still exits 0.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y@main
+        uses: Binclusive/a11y@v0.1.1
         with:
           llm-api-key:  ${{ secrets.LLM_API_KEY }}  # optional — your BYOK model key
           llm-model:    ""                          # optional — override the model
@@ -224,7 +229,7 @@ does not, and nothing new crosses the wire.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y@main
+        uses: Binclusive/a11y@v0.1.1
         with:
           binclusive-app-id:          ${{ vars.BINCLUSIVE_APP_ID }}
           binclusive-app-private-key: ${{ secrets.BINCLUSIVE_APP_PRIVATE_KEY }}
@@ -244,7 +249,7 @@ artifact:
 
 ```sh
 docker run --rm -v "$PWD:/workspace" -w /workspace -e A11Y_PLATFORM=null \
-  ghcr.io/binclusive/a11y-checker:latest \
+  ghcr.io/binclusive/a11y:latest \
   check /workspace/src --ci --format sarif > a11y.sarif
 ```
 
@@ -265,6 +270,7 @@ native platform adapters build on, are in **[`docs/CI.md`](docs/CI.md)**.
 |---|---|
 | **Adopt it with your own design system** | **`WALKTHROUGH.md`** |
 | **Run it on any CI/CD (CircleCI / Jenkins / Drone / generic)** | **`docs/CI.md`** |
+| **Ready-made configs for GitLab / CircleCI / Buildkite / Jenkins / Bitbucket** | **[`examples/ci/`](examples/ci/)** |
 | **Audit a live URL or HTML page (non-React)** | **`docs/AUDIT-URL.md`** |
 | The pitch + the moat, with numbers | `docs/decks/numbers.html` |
 | Real findings on real OSS projects | `docs/decks/showcase.html` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@binclusive/a11y",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Local accessibility checker for React/TSX, grounded in axe-core's published rule catalog. Runs entirely on your machine — no network, no upload.",
   "main": "./src/index.ts",

package/src/cli.ts

@@ -21,7 +21,6 @@ import { runHookCli } from "./hook";
 import { type PhoneHomeDeps, phoneHome } from "./phone-home";
 import { formatSarif } from "./sarif";
 import {
-  GATE_ADVISORY,
   GATE_OFF,
   type GateConfig,
   gateExitCode,
@@ -470,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
@@ -629,7 +659,12 @@ export async function runCheckUrl(
  * 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);
@@ -644,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),
+    },
+  );
 }
 
 /**
@@ -669,47 +710,49 @@ export async function runCheckShopify(
   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 (format !== "text") {
-    // Route the Liquid scan through the SAME canonical emit path `check` uses
-    // (#163): SARIF or the JSON report + `toContractFinding` phone-home projection,
-    // so a Shopify scan hands real `@binclusive/a11y-contract` findings to a real
-    // consumer instead of a bespoke `buildJsonReport`→stdout report. Liquid carries
-    // no component resolver (zeroed coverage) and the whole scanned set is analyzed.
-    // Non-blocking (`GATE_ADVISORY`): the stack scan reports, it doesn't gate (exit
-    // 0 even with findings) — the opt-in blocking gate is a noted follow-up (#163 AC).
-    await emitFindings(format, findings, {
+  // 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,
       runId,
       filesScanned: files.length,
       coverage: EMPTY_COVERAGE,
       analyzedFiles: files,
-      gate: GATE_ADVISORY,
+      gate,
       phoneHome: phoneHomeOverrides,
-    });
-    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),
-  });
+    },
+    {
+      // 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),
+    },
+  );
 }
 
 /**
@@ -722,33 +765,31 @@ export async function runCheckShopify(
  * 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;
-  }
-
-  console.log(`a11y-checker — scanning Unity Force-Text scenes under ${root}\n`);
-
-  renderReport(findings, {
-    emptyMessage: "No Unity a11y violations found.",
-    groupKey: (f) => f.file,
-    groupHeader: (file) => relative(root, file),
-    formatItem: (f) => formatFinding(f, root),
-  });
+  // 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),
+    },
+  );
 }
 
 /**
@@ -760,18 +801,31 @@ async function runCheckUnity(dir: string, json = false): Promise<void> {
  * 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): Promise<void> {
-  const { root, findings: raw } = await scanAndroidXml(dir);
-  console.log(`a11y-checker — scanning res/layout XML under ${root} for Android a11y\n`);
-
+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 Android XML 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> {
@@ -951,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(
@@ -989,49 +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"),
-    sarif: Options.boolean("sarif"),
-    format: formatOption,
-    runId: Options.text("run-id").pipe(Options.withDefault("local")),
-  },
-  ({ dir, json, sarif, format, runId }) =>
-    // Reuse the CANONICAL `--format text|json|sarif` selector (`--json`/`--sarif`
-    // aliases) the default `check` uses, so the Shopify scan reaches SARIF + the
-    // phone-home contract projection through the SAME path, not a bespoke flag (#163).
-    Effect.promise(() => runCheckShopify(dir, resolveFormat(format, json, sarif), runId)),
+  { 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; --format text|json|sarif, canonical — routes findings through the same canonical contract wire path as `check`)",
+    "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; --json: machine-readable)",
+    "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 },
-  ({ dir }) => Effect.promise(() => runCheckAndroid(dir)),
+  { 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 Android res/layout XML for accessibility findings (static, in-process — no browser, no toolchain)",
+    "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`)",
   ),
 );
 

package/src/diff-scope.ts

@@ -38,18 +38,50 @@ function isGitRepo(workspace: string): boolean {
   }
 }
 
-function gitDiffNames(workspace: string, baseSha: string, headSha: string): string[] {
+/**
+ * Names touched between base and head, honoring extra diff flags (deletion
+ * filter, rename detection).
+ *
+ * Prefers the THREE-dot `base...head` range — the PR-diff semantic GitHub's own
+ * PR view uses (changes since the merge-base, excluding commits added to base
+ * after the branch point). On a SHALLOW checkout the merge-base commit is usually
+ * absent, so three-dot fails hard with "no merge base" (#198). Rather than swallow
+ * that as an empty scope — the silent-empty-green trap: 0 files → 0 findings → a
+ * GREEN check on a scan that saw NOTHING — degrade to the TWO-dot `base..head`
+ * tree comparison, which needs only the two endpoint commits (both guaranteed
+ * present — `entrypoint.sh` self-fetches the base before scoping). Two-dot is a
+ * strict superset of the three-dot change set, so it can only OVER-scan (extra
+ * files a drifted base changed), never HIDE a PR-touched file — the safe
+ * direction for an advisory gate.
+ */
+function gitDiffRange(
+  workspace: string,
+  baseSha: string,
+  headSha: string,
+  extraArgs: readonly string[],
+): string[] {
+  const run = (range: string): string =>
+    execFileSync("git", ["-C", workspace, "diff", ...extraArgs, "--name-only", range], {
+      encoding: "utf8",
+    });
+  let out: string;
   try {
-    const out = execFileSync(
-      "git",
-      ["-C", workspace, "diff", "--name-only", `${baseSha}...${headSha}`],
-      { encoding: "utf8" },
-    );
-    return out.split("\n").filter((p) => p !== "");
+    out = run(`${baseSha}...${headSha}`);
   } catch {
-    // Advisory gate: a git failure is an empty scope, never a throw.
-    return [];
+    try {
+      out = run(`${baseSha}..${headSha}`);
+    } catch {
+      // Advisory gate: both ranges failed (e.g. head unresolvable) is an empty
+      // scope, never a throw. A missing BASE is caught earlier, and loud, in
+      // entrypoint.sh — this path never sees a bad base.
+      return [];
+    }
   }
+  return out.split("\n").filter((p) => p !== "");
+}
+
+function gitDiffNames(workspace: string, baseSha: string, headSha: string): string[] {
+  return gitDiffRange(workspace, baseSha, headSha, []);
 }
 
 /**
@@ -63,17 +95,7 @@ function gitDiffNames(workspace: string, baseSha: string, headSha: string): stri
  * Paths are repo-root-relative, forward-slash (git's native output).
  */
 function gitDeletedNames(workspace: string, baseSha: string, headSha: string): string[] {
-  try {
-    const out = execFileSync(
-      "git",
-      ["-C", workspace, "diff", "--diff-filter=D", "--find-renames", "--name-only", `${baseSha}...${headSha}`],
-      { encoding: "utf8" },
-    );
-    return out.split("\n").filter((p) => p !== "");
-  } catch {
-    // Advisory gate: a git failure is an empty deletion set, never a throw.
-    return [];
-  }
+  return gitDiffRange(workspace, baseSha, headSha, ["--diff-filter=D", "--find-renames"]);
 }
 
 /**

package/src/pr-comment.ts

@@ -34,10 +34,20 @@ export { type Finding, type Impact, parseFindings };
 export interface ReviewComment {
   readonly id: number;
   readonly body: string;
+  /**
+   * The comment author's login (GitHub `user.login`), when the platform supplies
+   * it. Feeds the {@link reconcile} author guard: our marker is public text anyone
+   * could paste, so a marker on a comment authored by someone other than us is not
+   * actually ours. Absent ⇒ the guard falls back to marker-only matching.
+   */
+  readonly author?: string;
 }
 
 const MARKER_TAG = "binclusive-a11y-agent";
-const MARKER_RE = /<!--\s*binclusive-a11y-agent:(.*?)\s*-->/;
+// Composed from MARKER_TAG so the tag lives in exactly one place — the marker we
+// WRITE (markerFor) and the marker we READ (keyOf) can never drift apart. Safe to
+// interpolate raw: MARKER_TAG is a fixed [a-z-] literal with no regex metachars.
+const MARKER_RE = new RegExp(`<!--\\s*${MARKER_TAG}:(.*?)\\s*-->`);
 
 /**
  * A live rendered element locator. Mirrors `emit-contract.ts`'s `hasSelector`:
@@ -99,7 +109,11 @@ export function markerFor(f: Finding): string {
  */
 export function keyOf(body: string): string | null {
   const m = MARKER_RE.exec(body);
-  return m && m[1] !== undefined ? m[1] : null;
+  // An empty/whitespace-only key (`<!-- ...agent: -->`) identifies no finding, so
+  // it can't be reconciled against one — treat it as not-ours rather than let a
+  // degenerate "" key collide in the reconcile maps.
+  if (!m || m[1] === undefined || m[1] === "") return null;
+  return m[1];
 }
 
 /** Render the full comment body for `f`, marker appended so it round-trips. */
@@ -130,10 +144,17 @@ export interface ReconcilePlan {
  * alone. A pre-dedup PR may hold several comments for one key (the old spamming
  * behavior); the canonical one (first seen) is kept/updated and the rest are
  * folded into `remove`, so the very first reconciling run also cleans up.
+ *
+ * `self` is the login we post under: when given, a marker comment authored by a
+ * DIFFERENT login is not treated as ours (someone pasted our marker) — we never
+ * update or delete it. Omitted, or a comment with no known author, keeps the
+ * marker-only behavior, so passing an unknown `self` can never make us skip our
+ * own comments and re-post duplicates.
  */
 export function reconcile(
   findings: readonly Finding[],
   existing: readonly ReviewComment[],
+  self?: string,
 ): ReconcilePlan {
   // Desired findings keyed by identity; first occurrence wins on collision.
   const desired = new Map<string, Finding>();
@@ -148,7 +169,9 @@ export function reconcile(
   const remove: number[] = [];
   for (const c of existing) {
     const k = keyOf(c.body);
-    if (k === null) continue; // not ours — never touch human comments
+    if (k === null) continue; // no marker — never touch human comments
+    // Author guard: a marker on a comment someone else authored is not ours.
+    if (self !== undefined && c.author !== undefined && c.author !== self) continue;
     if (ours.has(k)) remove.push(c.id);
     else ours.set(k, c);
   }
@@ -205,9 +228,10 @@ export async function syncComments(
   findings: readonly Finding[],
   client: PrCommentClient,
   log: (msg: string) => void = () => {},
+  self?: string,
 ): Promise<ReconcilePlan> {
   const existing = await client.list();
-  const plan = reconcile(findings, existing);
+  const plan = reconcile(findings, existing, self);
 
   for (const f of plan.create) {
     await client.create(f);
@@ -240,9 +264,10 @@ export async function syncCommentsBestEffort(
   findings: readonly Finding[],
   client: PrCommentClient,
   log: (msg: string) => void = () => {},
+  self?: string,
 ): Promise<ReconcilePlan | null> {
   try {
-    return await syncComments(findings, client, log);
+    return await syncComments(findings, client, log, self);
   } catch (e) {
     log(`sync aborted (best-effort, no-op): ${e instanceof Error ? e.message : String(e)}`);
     return null;

package/src/reporter/finding.ts

@@ -63,7 +63,12 @@ export function parseFindings(raw: unknown): Finding[] {
     if (typeof item !== "object" || item === null) continue;
     const f = item as Record<string, unknown>;
     if (typeof f.ruleId !== "string" || typeof f.file !== "string") continue;
-    if (typeof f.line !== "number") continue;
+    // A line must be a real number: NaN/Infinity would anchor a review comment on a
+    // nonexistent line, and `renderBody`/the marker would carry the junk value.
+    if (typeof f.line !== "number" || !Number.isFinite(f.line)) continue;
+    // Drop rather than synthesize an empty message: a comment with no body text is
+    // noise on the PR, and the boundary shouldn't invent content the report lacks.
+    if (typeof f.message !== "string" || f.message.trim() === "") continue;
     const wcag = Array.isArray(f.wcag) ? f.wcag.filter((w): w is string => typeof w === "string") : undefined;
     // Keep the selector across the boundary — it is what distinguishes co-located
     // same-rule findings; dropping it here reintroduces the collision.
@@ -76,7 +81,7 @@ export function parseFindings(raw: unknown): Finding[] {
       ruleId: f.ruleId,
       file: f.file,
       line: f.line,
-      message: typeof f.message === "string" ? f.message : "",
+      message: f.message,
       ...(wcag ? { wcag } : {}),
       ...(selector !== undefined ? { selector } : {}),
       ...(impact !== undefined ? { impact } : {}),

package/src/reporter/github-adapter.ts

@@ -115,7 +115,16 @@ function makeClient(target: GithubPostTarget, token: string, log: Logger): PrCom
             typeof (c as { id?: unknown }).id === "number" &&
             typeof (c as { body?: unknown }).body === "string"
           ) {
-            out.push({ id: (c as { id: number }).id, body: (c as { body: string }).body });
+            const user = (c as { user?: unknown }).user;
+            const author =
+              user && typeof user === "object" && typeof (user as { login?: unknown }).login === "string"
+                ? (user as { login: string }).login
+                : undefined;
+            out.push({
+              id: (c as { id: number }).id,
+              body: (c as { body: string }).body,
+              ...(author !== undefined ? { author } : {}),
+            });
           }
         }
         if (batch.length < 100) break;
@@ -170,8 +179,13 @@ export const githubReporter: FindingsReporter<GithubPostTarget> = {
     }
     log(`posting inline comments as ${identity}`);
     const client = makeClient(target, token, log);
+    // The author guard needs the login our comments carry. GITHUB_TOKEN posts as
+    // `github-actions[bot]` (statically known); the branded App's bot login is not
+    // known here, so leave `self` undefined for it — the guard degrades to
+    // marker-only rather than risk skipping our own App-authored comments.
+    const self = identity === "github-actions" ? "github-actions[bot]" : undefined;
     // Best-effort by contract: swallows any throw so the entrypoint always exits 0.
-    await syncCommentsBestEffort(findings, client, log);
+    await syncCommentsBestEffort(findings, client, log, self);
   },
 };
 

package/src/runner/runner.ts

@@ -175,6 +175,9 @@ export async function runAgentLane(input: RunInput): Promise<RunOutcome> {
   // (cross-dedup by file:line:sc) or that duplicates another discovery (self-dedup
   // by file:line:patternId). Reuse the engine's `dedupeRecall` verbatim — one dedup
   // discipline, not a second one. Survivors keep identity, so re-narrow to agent.
+  // Note (#2180): self-dedup keys on patternId, so two byte-identical PATTERNLESS
+  // discoveries at one file:line do NOT collapse here — each survives as its own
+  // agent finding (a patternless candidate has no identity to safely key on).
   const survivors = new Set(dedupeRecall(discoveries, input.findings));
   const agentFindings = discoveries.filter((d) => survivors.has(d));
 

package/src/sarif.ts

@@ -15,7 +15,7 @@
 import { relative } from "node:path";
 import type { Impact } from "@binclusive/a11y-contract";
 import { hasSelector, toContractProvenance } from "./emit-contract";
-import { evidenceHelpUrl, evidenceImpact, type EnrichedFinding } from "./evidence";
+import { evidenceHelpUrl, evidenceImpact, type EnrichedFinding, resolveDisplay } from "./evidence";
 import { type LocationOptions, resolveLocations } from "./source-identity";
 
 /**
@@ -48,6 +48,17 @@ interface SarifLocation {
   logicalLocations?: Array<{ fullyQualifiedName: string; kind: "element" }>;
 }
 
+// A `relatedLocations` entry: a location relevant to *understanding* a finding
+// but that is not where the finding IS (SARIF §3.27.22). Here it is the rendered
+// DOM node a SOURCE-anchored finding also names — a genuinely distinct second
+// node beyond the code site. A CSS selector has no source region, so it rides a
+// `logicalLocations` and carries no `physicalLocation` (§3.28 — all fields
+// optional). No `id`: nothing links to it, so the spec says omit it (§3.28.2).
+interface SarifRelatedLocation {
+  message: { text: string };
+  logicalLocations: Array<{ fullyQualifiedName: string; kind: "element" }>;
+}
+
 // GitHub code-scanning resolves a SARIF `uri` relative to the repo root, so when
 // a workspace `root` is given the source-file uri is relativized against it — a
 // scan of a staged mirror dir then still yields repo-relative `src/Foo.tsx`
@@ -59,26 +70,55 @@ function locationUri(file: string, root: string | undefined): string {
 }
 
 function findingLocations(f: EnrichedFinding, root: string | undefined): SarifLocation[] {
+  const hasRegion = f.line > 0;
   const location: SarifLocation = {
     physicalLocation: {
       artifactLocation: { uri: locationUri(f.file, root) },
-      ...(f.line > 0 ? { region: { startLine: f.line } } : {}),
+      ...(hasRegion ? { region: { startLine: f.line } } : {}),
     },
   };
-  if (hasSelector(f.selector)) {
+  // A PAGE finding (no source region — its `file` is the page URL) addresses its
+  // offending node by CSS selector, so the selector is that primary node's
+  // logical address (§3.28). A SOURCE finding's selector names a DISTINCT
+  // rendered node, not a qualifier of the code line, so it rides
+  // `relatedLocations` (see {@link findingRelatedLocations}) — never both.
+  if (!hasRegion && hasSelector(f.selector)) {
     location.logicalLocations = [{ fullyQualifiedName: f.selector, kind: "element" }];
   }
   return [location];
 }
 
+// A source-anchored finding (primary = `file:line`) that ALSO names a rendered
+// DOM node has a genuinely distinct second location worth surfacing: the code
+// line is where the finding IS; the element is context that helps understand it
+// (e.g. a corpus-agent discovery grounded in a `jsx-a11y` line that names an
+// `element`). A PAGE finding's selector is its PRIMARY node, not a related one,
+// so it never reaches here — the result is graceful-empty for every other shape.
+function findingRelatedLocations(f: EnrichedFinding): SarifRelatedLocation[] {
+  if (f.line > 0 && hasSelector(f.selector)) {
+    return [
+      {
+        message: { text: `Rendered element: ${f.selector}` },
+        logicalLocations: [{ fullyQualifiedName: f.selector, kind: "element" }],
+      },
+    ];
+  }
+  return [];
+}
+
 /**
  * Render a SARIF 2.1.0 log over the LOCAL findings. `runId` names the run in
  * `automationDetails` (e.g. a PR number or scan id). Rules are the deduped set
- * of fired rule ids; each result carries its impact level, source location,
- * and a `properties.provenance` tag (`deterministic` | `agent`) so the two
- * checker lanes stay distinguishable once both feed SARIF. `opts.root`, when
- * given, relativizes source-file uris against the scanned root — the form
- * GitHub code-scanning needs to anchor annotations on the PR diff.
+ * of fired rule ids; each carries the fix prose in `help`/`fullDescription` —
+ * the field Copilot Autofix reads to GENERATE an edit (it ignores
+ * `result.fixes[]`, which this renderer deliberately never emits: a valid SARIF
+ * fix requires fabricated `artifactChanges`, violating suggestions-not-patches).
+ * Each result carries its impact level, source location, the rationale in
+ * `message`, an optional `relatedLocations` entry when it names a distinct
+ * rendered node, and a `properties.provenance` tag (`deterministic` | `agent`)
+ * so the two checker lanes stay distinguishable once both feed SARIF.
+ * `opts.root`, when given, relativizes source-file uris against the scanned
+ * root — the form GitHub code-scanning needs to anchor annotations on the PR diff.
  *
  * A source result also carries `partialFingerprints.primaryLocationLineHash` so
  * code-scanning tracks the alert across commits as lines move (ADR 0042's "free
@@ -112,9 +152,18 @@ export function formatSarif(
             rules: ruleIds.map((id) => {
               const f = ruleById.get(id);
               const helpUri = f ? evidenceHelpUrl(f) : null;
+              // The rule-generic fix prose. Copilot Autofix reads `help`/
+              // `fullDescription` (NOT `result.fixes[]`) to GENERATE its edit, so
+              // this is the lever for auto-fixability — the SC/rule-accurate fix
+              // guidance, single-sourced through {@link resolveDisplay}. It stays
+              // prose (suggestions-not-patches): guidance to generate from, never a
+              // fabricated edit. Absent when a finding carries no fix (evidence
+              // `none`) — then Autofix falls back to the message + help URL.
+              const fixProse = f ? resolveDisplay(f).fix : null;
               return {
                 id,
                 ...(f ? { shortDescription: { text: f.message } } : {}),
+                ...(fixProse ? { fullDescription: { text: fixProse }, help: { text: fixProse } } : {}),
                 ...(helpUri ? { helpUri } : {}),
               };
             }),
@@ -122,11 +171,21 @@ export function formatSarif(
         },
         results: findings.map((f) => {
           const loc = located.get(f);
+          const related = findingRelatedLocations(f);
+          // The specific rationale/suggestion Autofix pulls snippets around. A
+          // DISCOVERY finding already folds observation+rationale+fix into
+          // `message`; an ENRICHED deterministic finding carries the suggestion
+          // separately in `agentNote`, so append it — prose, never a patch — so
+          // the SARIF message carries the agent's reasoning either way.
+          const message = f.agentNote !== undefined ? `${f.message} ${f.agentNote}` : f.message;
           return {
             ruleId: f.ruleId,
             level: impactToLevel(evidenceImpact(f) ?? "unknown"),
-            message: { text: f.message },
+            message: { text: message },
             locations: findingLocations(f, opts.root),
+            // Only present when a source-anchored finding names a distinct rendered
+            // node; graceful-empty (omitted) otherwise, never a fabricated spot.
+            ...(related.length > 0 ? { relatedLocations: related } : {}),
             // `<lineHash>:<index>` — the content hash lets code-scanning re-match the
             // alert when the line moves; `index` disambiguates identical lines within a
             // file, exactly as the finding identity does. A page finding has no source