@binclusive/a11y 0.1.0 → 0.1.2

package/src/detect-stack.ts

@@ -12,8 +12,8 @@
  * builds) so detection and scanning agree on what a "component import" is.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
 import type { Language, Router, Stack } from "./contract";
 import { familyLabel, isFrameworkPrimitive, isOwnModule, packageNameOf } from "./module-scope";
 import { resolveComponents } from "./resolve-components";
@@ -125,6 +125,67 @@ function detectLanguage(dir: string): Language {
   return findUp(dir, "tsconfig.json") !== null ? "ts" : "js";
 }
 
+/** Build/output dirs not worth descending into when sniffing for Android markers. */
+const ANDROID_SCAN_SKIP = new Set([
+  "node_modules",
+  ".git",
+  ".gradle",
+  "build",
+  "dist",
+  ".idea",
+]);
+
+/**
+ * Bounded find-down for an Android marker — an `AndroidManifest.xml` or a
+ * `res/layout…` resource directory — within `maxDepth` levels of `dir`. Android
+ * projects nest these under `app/src/main/…`, so a pure package-up probe (used
+ * for tsconfig) would miss them; a shallow, skip-pruned descent is the cheap,
+ * reliable signal. Short-circuits on the first marker found.
+ */
+function hasAndroidMarker(dir: string, maxDepth: number): boolean {
+  let entries: ReturnType<typeof readdirSync>;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "AndroidManifest.xml") return true;
+    if (entry.isDirectory()) {
+      // a `layout` / `layout-…` dir whose parent is `res` is a layout resource dir
+      if ((entry.name === "layout" || entry.name.startsWith("layout-")) && dir.endsWith(`${sep}res`)) {
+        return true;
+      }
+    }
+  }
+  if (maxDepth <= 0) return false;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || ANDROID_SCAN_SKIP.has(entry.name)) continue;
+    if (hasAndroidMarker(join(dir, entry.name), maxDepth - 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when `dir` is an Android project: a Gradle root (a `build.gradle` /
+ * `settings.gradle`, in Groovy or Kotlin DSL) paired with an Android marker
+ * (`AndroidManifest.xml` or a `res/layout*` dir) reachable a few levels down.
+ * Requiring BOTH keeps a plain JVM Gradle project (no Android UI) from being
+ * misread as Android.
+ */
+export function detectAndroid(dir: string): boolean {
+  const gradle =
+    existsSync(join(dir, "build.gradle")) ||
+    existsSync(join(dir, "build.gradle.kts")) ||
+    existsSync(join(dir, "settings.gradle")) ||
+    existsSync(join(dir, "settings.gradle.kts"));
+  if (!gradle && !existsSync(join(dir, "AndroidManifest.xml"))) {
+    // No gradle root and no manifest right here — not the root of an Android repo.
+    return false;
+  }
+  return hasAndroidMarker(dir, 5);
+}
+
 /**
  * The repo's design system: the published package that contributes the most
  * components RESOLVING TO A KNOWN INTERACTIVE HOST (registry or traced). That
@@ -193,6 +254,13 @@ export function detectDesignSystem(tsxFiles: readonly string[], rootDir?: string
  * signal; see the per-field helpers for what each reads.
  */
 export function detectStack(dir: string, tsxFiles: readonly string[]): Stack {
+  // Android is a distinct platform from the React/TSX path: an Android repo has
+  // no `package.json`/tsconfig to read, and its UI is `res/layout*` XML, not
+  // `.tsx`. Detect it first so it routes to the Android XML collector instead of
+  // degrading to a `framework: unknown · custom · js` web stack.
+  if (detectAndroid(dir)) {
+    return { framework: "android", router: null, designSystem: "android-views", language: "android-xml" };
+  }
   // Package-up: a scan pointed at a nested `src/` finds the app's package.json
   // (and the on-disk app/pages layout) one or more levels above.
   const pkgRoot = findUp(dir, "package.json") ?? dir;

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/enforce.ts

@@ -605,36 +605,48 @@ interface EnforceRule {
   readonly message: string;
 }
 
+/**
+ * Every finding message — here and in the jsx-a11y wrapper (see {@link
+ * import("./finding-voice")}) — leads with the IMPACT-FIRST template:
+ *
+ *   [who is affected] can't [do what] because [cause], so [fix].
+ *
+ * The lead names the harmed user and the human consequence (#14), not the rule
+ * id. The rule id, WCAG SC, and corpus "seen-in-the-wild" frequency are SECONDARY
+ * lines the report renders separately ({@link import("./cli").detailLines}), so
+ * the message carries NO `(corpus: …)` suffix — that data is not dropped, it just
+ * lives on its own line rather than inline in the impact sentence.
+ */
 const RULES: Record<string, EnforceRule> = {
   buttonNoName: {
     ruleId: "enforce/button-no-name",
     wcag: ["4.1.2"],
     message:
-      "Control resolves to a button but has no accessible name: children are empty or icon-only and there is no aria-label/aria-labelledby/title. Give it discernible text or an aria-label (corpus: 4.1.2-button-no-name).",
+      "Screen-reader users can't tell what this button does because it has no accessible name — its children are empty or icon-only and there is no aria-label, aria-labelledby, or title, so add visible text or an aria-label that names its action.",
   },
   imageNoAlt: {
     ruleId: "enforce/image-no-alt",
     wcag: ["1.1.1"],
     message:
-      'Control resolves to an image but has no alt and no aria-label/aria-labelledby. Add an alt that conveys the image\'s meaning, or alt="" if decorative (corpus: 1.1.1).',
+      'Blind users can\'t perceive this image because it has no text alternative — no alt and no aria-label/aria-labelledby, so add an alt that conveys its meaning, or alt="" if it is purely decorative.',
   },
   linkNoName: {
     ruleId: "enforce/link-no-name",
     wcag: ["2.4.4"],
     message:
-      "Control resolves to a link but has no discernible name: no text child and no aria-label/aria-labelledby/title. Give the link visible text or an aria-label that names its destination (corpus: 2.4.4-link-no-name).",
+      "Screen-reader users can't tell where this link goes because it has no discernible name — no text child and no aria-label, aria-labelledby, or title, so give it visible text or an aria-label that names its destination.",
   },
   dialogNoName: {
     ruleId: "enforce/dialog-no-name",
     wcag: ["4.1.2", "1.3.1"],
     message:
-      "Control resolves to a dialog/modal but has no accessible name: no aria-label/aria-labelledby, no title/label prop, and no nested title subcomponent. Name the dialog so assistive tech announces it (corpus: 4.1.2).",
+      "Screen-reader users can't tell what this dialog is for because it has no accessible name — no aria-label/aria-labelledby, no title or label prop, and no nested title subcomponent, so name the dialog and assistive tech will announce it on open.",
   },
   inputNoName: {
     ruleId: "enforce/input-no-name",
     wcag: ["1.3.1", "3.3.2"],
     message:
-      "Control resolves to a form input but has no associated label: no aria-label/aria-labelledby, no label/title prop, and no id to pair with a <label for>. Associate a real label (corpus: 1.3.1 / 3.3.2-form-control-no-name).",
+      "Screen-reader users can't tell what to enter in this field because it has no associated label — no aria-label/aria-labelledby, no label or title prop, and no id to pair with a <label for>, so associate a real label and the field will be announced.",
   },
 };
 
@@ -703,7 +715,7 @@ function preferTagOverRole(
     const line = sf.getLineAndCharacterOfPosition(attr.getStart(sf)).line + 1;
     return {
       line,
-      message: `This <${tag}> sets role="${value}", which ${native.suggest} conveys natively. Use ${native.suggest} instead of the role so the semantics work without ARIA (corpus: 1.3.1-prefer-tag-over-role).`,
+      message: `Assistive-tech users get fragile semantics here because <${tag}> hand-sets role="${value}" instead of using the native element ${native.suggest} that conveys it, so switch to ${native.suggest} and the role works without relying on ARIA.`,
     };
   }
   return null;

package/src/finding-voice.ts

@@ -0,0 +1,66 @@
+/**
+ * Impact-first message voice (#14).
+ *
+ * Every finding a11y-checker surfaces leads with one consistent shape:
+ *
+ *   [who is affected] can't [do what] because [cause], so [fix].
+ *
+ * The lead names the harmed user and the human consequence — the first thing a
+ * reader sees — rather than a rule id or SC number. The rule id, WCAG SC, and
+ * corpus "seen-in-the-wild" frequency stay, but as SECONDARY lines the report
+ * renders separately (see `cli.ts` `detailLines`), never inline in the sentence.
+ *
+ * The enforce content rules (`enforce.ts`) author their own messages in this
+ * shape. The jsx-a11y structural pass does NOT — its findings come straight from
+ * eslint-plugin-jsx-a11y, whose upstream messages lead with the rule requirement
+ * ("Buttons must have discernible text"), not the impacted user. This module is
+ * the wrapper that rewrites those upstream messages into the same impact-first
+ * voice, keyed by jsx-a11y rule id. It covers exactly the rules we score
+ * (`core.ts` `SCORED_RULES`); any rule not mapped here falls back to its upstream
+ * message unchanged, so the remap can only improve voice, never blank a finding.
+ *
+ * This is a display-only rewrite: it changes the `message` string, nothing about
+ * detection, the rule id, the WCAG mapping, the corpus enrichment, or the matrix
+ * baseline (which records file/line/ruleId, not message text).
+ */
+
+/**
+ * Impact-first messages for the jsx-a11y rules we score. Keyed by the bare rule
+ * name (no `jsx-a11y/` prefix) — the caller strips the namespace before lookup.
+ * Each follows the [who] can't [do what] because [cause], so [fix] template.
+ */
+const JSX_A11Y_IMPACT_MESSAGES: Readonly<Record<string, string>> = {
+  "label-has-associated-control":
+    "Screen-reader users can't tell what to enter in this field because its control has no associated <label>, so pair the control with a <label> (htmlFor + id, or wrap it) and the field will be announced.",
+  "alt-text":
+    'Blind users can\'t perceive this image because it has no alt text, so add an alt that conveys its meaning, or alt="" if it is purely decorative.',
+  "anchor-has-content":
+    "Screen-reader users can't tell where this link goes because it has no discernible content, so give the anchor visible text or an aria-label that names its destination.",
+  "anchor-is-valid":
+    "Keyboard and screen-reader users can't reliably follow this link because it has no valid href, so give it a real href — or use a <button> if it triggers an action rather than navigating.",
+  "aria-props":
+    "Assistive tech can't interpret this element because it carries an attribute that isn't a valid aria-* property, so remove or correct the invalid ARIA attribute.",
+  "role-has-required-aria-props":
+    "Screen-reader users can't fully operate this control because its role is missing ARIA properties that role requires, so add the required aria-* attributes for the role.",
+  "role-supports-aria-props":
+    "Screen-reader users can't rely on this element because it has an aria-* attribute its role doesn't support, so remove the unsupported attribute or change the role.",
+  "interactive-supports-focus":
+    "Keyboard users can't reach this control because it is interactive but not focusable, so make it focusable (use a native control, or add tabIndex) and it can be operated without a mouse.",
+  "click-events-have-key-events":
+    "Keyboard users can't activate this element because it has a click handler but no keyboard handler, so add a key handler — or use a <button> — and it will work without a mouse.",
+  "no-static-element-interactions":
+    "Keyboard and screen-reader users can't operate this element because a click handler sits on a non-interactive element with no role, so use a native control, or add an interactive role plus keyboard support.",
+  "heading-has-content":
+    "Screen-reader users can't navigate by this heading because it has no text content, so give the heading discernible text (or remove it if it is not really a heading).",
+};
+
+/**
+ * Rewrite a jsx-a11y finding's upstream eslint message into the impact-first
+ * voice. `ruleId` is the full id (`jsx-a11y/alt-text`); `fallback` is the
+ * upstream message used verbatim when the rule isn't in the map — so a finding
+ * always carries a message, and an unmapped rule degrades to its original text.
+ */
+export function impactFirstJsxA11yMessage(ruleId: string, fallback: string): string {
+  const bare = ruleId.startsWith("jsx-a11y/") ? ruleId.slice("jsx-a11y/".length) : ruleId;
+  return JSX_A11Y_IMPACT_MESSAGES[bare] ?? fallback;
+}

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