@binclusive/a11y 0.1.0

package/src/eslint-plugin-jsx-a11y.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient types for `eslint-plugin-jsx-a11y`, which ships no `.d.ts` and has
+ * no `@types/` package on npm. We only consume it as an ESLint flat-config
+ * plugin, so we type it precisely against ESLint's own `ESLint.Plugin` shape
+ * rather than reaching for `any` (which the repo bans).
+ */
+declare module "eslint-plugin-jsx-a11y" {
+  import type { ESLint } from "eslint";
+  const plugin: ESLint.Plugin;
+  export default plugin;
+}

package/src/evidence.ts

@@ -0,0 +1,308 @@
+import baselineCatalog from "../data/baseline-rules.json" with { type: "json" };
+import type { AxeImpact, Finding } from "./core";
+
+export type { AxeImpact };
+
+/**
+ * The evidence attached to a finding — a DISCRIMINATED UNION on `source`. The
+ * engine is pure detection: it cross-references a finding against the coverage
+ * catalog (axe-core's published per-rule metadata) and nothing else. Audit
+ * frequency is platform-derived (ADR 0041 §G — the corpus left the engine), so
+ * there is no `audit` variant and no finding carries a frequency `tier`.
+ *
+ *   - `"baseline"` — axe-core's baseline catalog (`data/baseline-rules.json`)
+ *                    knows the rule. Coverage, NOT audit-frequency data: carries
+ *                    axe's `impact` + standard `fix` + `helpUrl`. Matched by the
+ *                    finding's SC, OR — for axe best-practice rules that carry no
+ *                    WCAG SC tag (`region`, `landmark-unique`, …) — by the axe
+ *                    ruleId, in which case `sc` is null and `bestPractice` is true
+ *                    (`sc === null` ⇔ `bestPractice`). An axe recommendation must
+ *                    never be dressed up with a fabricated SC.
+ *   - `"none"`     — the finding's ruleId is genuinely absent from the catalog
+ *                    (and no SC matched). It carries NO catalog evidence at all;
+ *                    any impact/helpUrl to display comes off the finding's own
+ *                    runtime axe metadata (read via {@link evidenceImpact} /
+ *                    {@link evidenceHelpUrl}), not off this variant.
+ *
+ * The axe-vs-SC DISPLAY policy ("for axe findings show the rule's own help, not
+ * the SC-generic fix") lives in exactly one place — {@link resolveDisplay} — not
+ * on this type and not in its consumers.
+ */
+export type Evidence =
+  | {
+      readonly source: "baseline";
+      readonly sc: string | null;
+      readonly impact: AxeImpact;
+      readonly fix: string;
+      readonly helpUrl: string | null;
+      /** `sc === null` ⇔ `bestPractice` — an axe rule with no WCAG SC tag. */
+      readonly bestPractice: boolean;
+    }
+  | { readonly source: "none" };
+
+/** A finding plus its coverage-catalog cross-reference. */
+export interface EnrichedFinding extends Finding {
+  readonly corpus: Evidence;
+}
+
+/**
+ * A baseline-catalog rule, narrowed from `data/baseline-rules.json`. Mirrors the
+ * generator's `BaselineRule` shape. This is the COVERAGE source of truth (axe's
+ * published per-rule metadata); it never carries an org count or a frequency tier.
+ */
+interface BaselineRuleEntry {
+  readonly ruleId: string;
+  readonly sc: readonly string[];
+  readonly impact: AxeImpact;
+  readonly help: string;
+  readonly helpUrl: string;
+}
+
+/**
+ * Narrow the baseline catalog (loaded as `unknown` at the JSON boundary) into
+ * two indexes: by axe ruleId (for axe findings, the exact rule) and by SC (for
+ * source-pass findings, which carry an SC but no axe ruleId). For an SC mapped by
+ * several rules, the first in the catalog's deterministic (ruleId-sorted) order
+ * wins — stable across regenerations. Each entry is validated structurally so a
+ * malformed file fails loud rather than smuggling `any` inward.
+ */
+function readBaseline(raw: unknown): {
+  byRule: ReadonlyMap<string, BaselineRuleEntry>;
+  bySc: ReadonlyMap<string, BaselineRuleEntry>;
+} {
+  const byRule = new Map<string, BaselineRuleEntry>();
+  const bySc = new Map<string, BaselineRuleEntry>();
+  const isImpact = (s: unknown): s is AxeImpact =>
+    s === "minor" || s === "moderate" || s === "serious" || s === "critical";
+
+  if (typeof raw !== "object" || raw === null || !("rules" in raw)) return { byRule, bySc };
+  const list = (raw as { rules: unknown }).rules;
+  if (!Array.isArray(list)) return { byRule, bySc };
+
+  for (const r of list) {
+    if (typeof r !== "object" || r === null) continue;
+    const { ruleId, sc, impact, help, helpUrl } = r as Record<string, unknown>;
+    if (
+      typeof ruleId !== "string" ||
+      !Array.isArray(sc) ||
+      !isImpact(impact) ||
+      typeof help !== "string" ||
+      typeof helpUrl !== "string"
+    ) {
+      continue;
+    }
+    const scList = sc.filter((s): s is string => typeof s === "string");
+    const entry: BaselineRuleEntry = { ruleId, sc: scList, impact, help, helpUrl };
+    byRule.set(ruleId, entry);
+    for (const oneSc of scList) {
+      if (!bySc.has(oneSc)) bySc.set(oneSc, entry);
+    }
+  }
+  return { byRule, bySc };
+}
+
+const BASELINE = readBaseline(baselineCatalog);
+
+/**
+ * Find the first of a finding's SCs that the baseline catalog knows, with the
+ * matched entry. Source-pass findings (jsx-a11y / enforce) and WCAG-tagged axe
+ * findings resolve here. Finding order is preserved (first known SC wins).
+ */
+function baselineBySc(finding: Finding): { sc: string; entry: BaselineRuleEntry } | null {
+  for (const sc of finding.wcag) {
+    const entry = BASELINE.bySc.get(sc);
+    if (entry !== undefined) return { sc, entry };
+  }
+  return null;
+}
+
+/**
+ * Cross-reference a finding against the coverage catalog, most-authoritative
+ * first, so every finding surfaces with an impact and a fix instead of
+ * dead-ending at null:
+ *
+ *   1. BASELINE (by SC) — coverage for the finding's WCAG SCs. axe's published
+ *      per-rule impact + standard fix + helpUrl. → `source: "baseline"`,
+ *      `bestPractice: false`.
+ *   2. BASELINE (by ruleId) — the axe best-practice rules that carry NO WCAG SC
+ *      tag (`region`, `landmark-unique`, …). Matched by the finding's axe ruleId,
+ *      reported honestly: `sc: null`, `bestPractice: true`, still carrying
+ *      impact + fix + helpUrl. → `source: "baseline"`.
+ *   3. NONE — the ruleId is genuinely absent from the catalog (and no SC
+ *      matched). An axe finding may still surface its own runtime impact/helpUrl.
+ *
+ * For axe findings the runtime impact already on the finding always wins over
+ * the catalog's static impact.
+ */
+export function enrich(finding: Finding): EnrichedFinding {
+  // 1. BASELINE by SC — coverage for the finding's WCAG SCs. Runtime axe impact
+  //    (most accurate) wins over the catalog default.
+  const bySc = baselineBySc(finding);
+  if (bySc !== null) {
+    return withEvidence(finding, {
+      source: "baseline",
+      sc: bySc.sc,
+      fix: bySc.entry.help,
+      impact: finding.impact ?? bySc.entry.impact,
+      helpUrl: finding.helpUrl ?? bySc.entry.helpUrl,
+      bestPractice: false,
+    });
+  }
+
+  // 2. BASELINE by ruleId — axe best-practice rules with NO WCAG SC tag. The
+  //    catalog knows the rule even though `bySc` missed; report it honestly with
+  //    `sc: null` + `bestPractice: true` rather than dropping to NONE. (A catalog
+  //    rule WITH an SC would have matched by SC above.)
+  const byRule = BASELINE.byRule.get(finding.ruleId);
+  if (byRule !== undefined) {
+    return withEvidence(finding, {
+      source: "baseline",
+      sc: byRule.sc[0] ?? null,
+      fix: byRule.help,
+      impact: finding.impact ?? byRule.impact,
+      helpUrl: finding.helpUrl ?? byRule.helpUrl,
+      bestPractice: byRule.sc.length === 0,
+    });
+  }
+
+  // 3. NONE — the ruleId is absent from the catalog and no SC matched. No catalog
+  //    evidence; any displayable impact/helpUrl comes off the finding.
+  return withEvidence(finding, { source: "none" });
+}
+
+/** Attach an evidence variant to a finding. The one place the two join. */
+function withEvidence(finding: Finding, evidence: Evidence): EnrichedFinding {
+  return { ...finding, corpus: evidence };
+}
+
+/** Enrich a batch of findings. */
+export function enrichAll(findings: readonly Finding[]): EnrichedFinding[] {
+  return findings.map(enrich);
+}
+
+/** The SC-keyed fix where one exists (baseline), else null. */
+export function evidenceFix(c: Evidence): string | null {
+  switch (c.source) {
+    case "baseline":
+      return c.fix;
+    case "none":
+      return null;
+  }
+}
+
+/**
+ * The impact to display for a finding: the catalog/runtime value the variant
+ * carries, falling back to the finding's own runtime axe impact for `none`.
+ */
+export function evidenceImpact(f: EnrichedFinding): AxeImpact | null {
+  const c = f.corpus;
+  switch (c.source) {
+    case "baseline":
+      return c.impact;
+    case "none":
+      return f.impact ?? null;
+  }
+}
+
+/**
+ * The Deque help URL to display for a finding: the catalog/runtime value the
+ * variant carries, falling back to the finding's own runtime URL for `none`.
+ */
+export function evidenceHelpUrl(f: EnrichedFinding): string | null {
+  const c = f.corpus;
+  switch (c.source) {
+    case "baseline":
+      return c.helpUrl;
+    case "none":
+      return f.helpUrl ?? null;
+  }
+}
+
+/** Whether this is an axe best-practice recommendation (no WCAG SC). */
+export function evidenceBestPractice(c: Evidence): boolean {
+  return c.source === "baseline" && c.bestPractice;
+}
+
+/**
+ * The resolved DISPLAY contract for a finding — the SOLE owner of the axe-vs-SC
+ * policy. Every consumer (the CLI `detailLines` printer, the MCP `CheckFinding`)
+ * reads this instead of re-deriving the policy, so they can never disagree.
+ *
+ * The policy: for a `provenance === "axe"` (rendered-DOM) finding the baseline
+ * `fix` is SC-GENERIC, so for axe findings we show the rule's own per-rule help
+ * (`message`)/`ref` instead. For source findings (`jsx-a11y` / `enforce`) the
+ * rule↔SC mapping is clean via wcag-map, so the baseline `fix` is rule-accurate
+ * and shown verbatim.
+ */
+export interface DisplayContract {
+  /** Uppercased impact for the `impact:` line, or null to omit it. */
+  readonly impactLabel: string | null;
+  /** Text for the CLI `fix:` line, or null to suppress it. */
+  readonly fixLine: string | null;
+  /**
+   * The rule-accurate fix string for API emission (MCP `CheckFinding.fix`): axe
+   * findings get axe's per-rule help (`message`); source findings get the
+   * baseline `fix`. Unlike `fixLine` this is never suppressed.
+   */
+  readonly fix: string | null;
+  /** The Deque help URL to render as a `ref:` line, or null to omit it. */
+  readonly refUrl: string | null;
+}
+
+export function resolveDisplay(f: EnrichedFinding): DisplayContract {
+  const c = f.corpus;
+  const isAxe = f.provenance === "axe";
+  const impact = evidenceImpact(f);
+  // axe → rule-accurate help (its own message); source → SC-keyed baseline fix.
+  const ruleFix = isAxe ? (f.message ?? null) : evidenceFix(c);
+  // A baseline fix is axe's per-rule help (rule-accurate), so it is shown for axe
+  // and source alike; `none` never carries a fix line.
+  const fixLine = evidenceFix(c);
+  // `ref:` shows for every axe finding, and for every finding carrying a help URL.
+  const refUrl = evidenceHelpUrl(f);
+  return {
+    impactLabel: impact === null ? null : impact.toUpperCase(),
+    fixLine,
+    fix: ruleFix,
+    refUrl,
+  };
+}
+
+/**
+ * A baseline-catalog rule surfaced for `get_a11y_rules`: axe's published
+ * per-rule data (ruleId, SC, impact, standard fix, helpUrl) for ANY axe/WCAG
+ * rule. Carries NO org count and NO frequency tier (it is not audit data).
+ */
+export interface BaselineRuleInfo {
+  readonly ruleId: string;
+  readonly sc: readonly string[];
+  readonly impact: AxeImpact;
+  readonly fix: string;
+  readonly helpUrl: string;
+}
+
+/**
+ * Look up baseline rules by axe ruleId substring and/or WCAG SC. With no filter,
+ * returns the whole catalog (already ruleId-sorted, deterministic). Pure read
+ * over `baseline-rules.json`.
+ */
+export function baselineRules(filter: { ruleId?: string; sc?: string } = {}): BaselineRuleInfo[] {
+  const toInfo = (e: BaselineRuleEntry): BaselineRuleInfo => ({
+    ruleId: e.ruleId,
+    sc: e.sc,
+    impact: e.impact,
+    fix: e.help,
+    helpUrl: e.helpUrl,
+  });
+
+  let entries = [...BASELINE.byRule.values()];
+  const ruleNeedle = filter.ruleId?.trim().toLowerCase();
+  if (ruleNeedle !== undefined && ruleNeedle !== "") {
+    entries = entries.filter((e) => e.ruleId.toLowerCase().includes(ruleNeedle));
+  }
+  const scNeedle = filter.sc?.trim();
+  if (scNeedle !== undefined && scNeedle !== "") {
+    entries = entries.filter((e) => e.sc.includes(scNeedle));
+  }
+  return entries.map(toInfo);
+}

package/src/github-identity.ts

@@ -0,0 +1,201 @@
+/**
+ * The one identity resolver both PR-comment surfaces authenticate through (issue
+ * #2130). Inline per-finding comments (the GitHub reporter, `reporter/github-adapter.ts`)
+ * and the single rollup comment (`pr-summary-cli.ts`) MUST post under the *same*
+ * GitHub identity, so the auth decision lives here once rather than duplicated at each callsite.
+ *
+ * Default-safe by construction — the load-bearing invariant:
+ *
+ *   - Binclusive GitHub App credentials configured (App id + private key in env) →
+ *     mint a short-lived installation access token and post under the branded App
+ *     identity (name + avatar), not `github-actions[bot]`.
+ *   - App credentials ABSENT → return the Action's own `GITHUB_TOKEN` unchanged.
+ *     Unset ⇒ byte-for-byte the current behavior, so this is safe to merge before
+ *     the App exists.
+ *
+ * Non-blocking, always: any mint failure (a bad key, a missing installation, a
+ * network error, a non-2xx from GitHub) is logged and FALLS BACK to the default
+ * token — the resolver never throws, so a failed identity swap never gates the
+ * merge. A failed brand is a lost avatar, never a failed check.
+ *
+ * No new runtime dependency: the App JWT is RS256-signed with node's built-in
+ * `crypto`, and every GitHub call goes through the same global `fetch` the comment
+ * clients already use. The signer and fetch are injected ({@link MintDeps}) so both
+ * branches — App-configured and App-absent — are unit-testable without a real key
+ * or a live network.
+ */
+import { createSign } from "node:crypto";
+
+/** Which identity a resolved token posts under. */
+export type PostingIdentity = "binclusive-github-app" | "github-actions";
+
+/** A resolved posting token paired with the identity GitHub will attribute it to. */
+export interface TokenResolution {
+  /** The bearer token to authenticate the comment POST/PATCH/DELETE calls with. */
+  readonly token: string;
+  /** `binclusive-github-app` when a branded installation token was minted, else `github-actions`. */
+  readonly identity: PostingIdentity;
+}
+
+/**
+ * Binclusive GitHub App credentials, present only when the customer installed the
+ * App and supplied its id + private key. `installationId` is optional — when
+ * absent it is discovered from the repo the run targets.
+ */
+export interface AppConfig {
+  readonly appId: string;
+  readonly privateKey: string;
+  readonly installationId?: string;
+}
+
+/** The repo + API host a token is being resolved for. */
+export interface ResolveContext {
+  /** `owner/name`, from `GITHUB_REPOSITORY`. */
+  readonly repo: string;
+  /** The GitHub REST base, e.g. `https://api.github.com` (GHES uses a different host). */
+  readonly api: string;
+}
+
+/**
+ * Injected effects so both branches are testable offline: `fetchImpl` is the HTTP
+ * surface (real global `fetch` in prod, a fake in tests), and `mintJwt` produces
+ * the App JWT (real RS256 signer in prod, a stub in tests so no key is needed).
+ */
+export interface MintDeps {
+  readonly fetchImpl: typeof fetch;
+  readonly mintJwt: (appId: string, privateKey: string) => string;
+}
+
+const APP_ID_ENV = "BINCLUSIVE_APP_ID";
+const APP_KEY_ENV = "BINCLUSIVE_APP_PRIVATE_KEY";
+const APP_INSTALL_ENV = "BINCLUSIVE_APP_INSTALLATION_ID";
+
+/**
+ * Read the App credentials from the environment, or `null` when unconfigured
+ * (either secret missing/blank). `null` is the default-safe signal that routes
+ * the resolver straight to the `GITHUB_TOKEN` fallback — the App absence is the
+ * common case until Can creates and installs the App.
+ *
+ * The private key is stored in a secret as PEM; some secret stores collapse its
+ * newlines to the literal `\n` escape, so those are restored — a no-op on a key
+ * that already carries real newlines.
+ */
+export function readAppConfig(env: NodeJS.ProcessEnv): AppConfig | null {
+  const appId = env[APP_ID_ENV]?.trim();
+  const rawKey = env[APP_KEY_ENV];
+  if (!appId || !rawKey || rawKey.trim() === "") return null;
+  const privateKey = rawKey.includes("\\n") ? rawKey.replace(/\\n/g, "\n") : rawKey;
+  const installationId = env[APP_INSTALL_ENV]?.trim();
+  return { appId, privateKey, ...(installationId ? { installationId } : {}) };
+}
+
+function base64url(input: string): string {
+  return Buffer.from(input, "utf8").toString("base64url");
+}
+
+/**
+ * RS256-sign a GitHub App JWT (App-authentication credential) with node's built-in
+ * `crypto` — no JWT library. `iat` is backdated 60s to absorb clock skew between
+ * the runner and GitHub, and `exp` is capped at 10 minutes (GitHub rejects longer);
+ * the JWT is used only to immediately mint an installation token, then discarded.
+ */
+export function mintAppJwt(appId: string, privateKey: string, now: () => number = Date.now): string {
+  const iat = Math.floor(now() / 1000) - 60;
+  const exp = iat + 600;
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(JSON.stringify({ iat, exp, iss: appId }));
+  const signingInput = `${header}.${payload}`;
+  const signer = createSign("RSA-SHA256");
+  signer.update(signingInput);
+  signer.end();
+  const signature = signer.sign(privateKey).toString("base64url");
+  return `${signingInput}.${signature}`;
+}
+
+/** The real signer + global fetch — the production {@link MintDeps}. */
+export const defaultMintDeps: MintDeps = {
+  fetchImpl: (...args) => fetch(...args),
+  mintJwt: (appId, privateKey) => mintAppJwt(appId, privateKey),
+};
+
+function appJwtHeaders(jwt: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${jwt}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "User-Agent": "binclusive-a11y-agent",
+  };
+}
+
+/**
+ * Mint a short-lived installation access token for the App on `ctx.repo`. Throws on
+ * any failure (missing installation, non-2xx, unparseable body) so the caller's
+ * try/catch routes to the default-token fallback — this function never silently
+ * returns a bad token. When `installationId` is absent it is discovered from the
+ * repo, so a customer only needs to install the App, not look up its id.
+ */
+export async function mintInstallationToken(
+  app: AppConfig,
+  ctx: ResolveContext,
+  deps: MintDeps,
+): Promise<string> {
+  const jwt = deps.mintJwt(app.appId, app.privateKey);
+  const headers = appJwtHeaders(jwt);
+
+  let installationId = app.installationId;
+  if (!installationId) {
+    const res = await deps.fetchImpl(`${ctx.api}/repos/${ctx.repo}/installation`, { headers });
+    if (!res.ok) {
+      throw new Error(`installation lookup -> ${res.status} ${(await res.text().catch(() => "")).slice(0, 200)}`);
+    }
+    const body: unknown = await res.json();
+    const id = (body as { id?: unknown })?.id;
+    if (typeof id !== "number" && typeof id !== "string") {
+      throw new Error("installation lookup returned no id");
+    }
+    installationId = String(id);
+  }
+
+  const res = await deps.fetchImpl(`${ctx.api}/app/installations/${installationId}/access_tokens`, {
+    method: "POST",
+    headers,
+  });
+  if (!res.ok) {
+    throw new Error(`installation token -> ${res.status} ${(await res.text().catch(() => "")).slice(0, 200)}`);
+  }
+  const body: unknown = await res.json();
+  const token = (body as { token?: unknown })?.token;
+  if (typeof token !== "string" || token === "") {
+    throw new Error("installation token response carried no token");
+  }
+  return token;
+}
+
+/**
+ * The single entrypoint both comment surfaces call to decide *who* posts. Returns
+ * the branded App identity + a freshly minted installation token when the App is
+ * configured and the mint succeeds; otherwise the Action's own `GITHUB_TOKEN`
+ * under the `github-actions` identity — the zero-behavior-change default. Never
+ * throws: a mint failure logs and degrades to the default token so the run exits 0.
+ */
+export async function resolvePostingToken(
+  env: NodeJS.ProcessEnv,
+  ctx: ResolveContext,
+  log: (msg: string) => void = () => {},
+  deps: MintDeps = defaultMintDeps,
+): Promise<TokenResolution> {
+  const defaultToken = env.GITHUB_TOKEN ?? "";
+  const app = readAppConfig(env);
+  if (!app) {
+    return { token: defaultToken, identity: "github-actions" };
+  }
+  try {
+    const token = await mintInstallationToken(app, ctx, deps);
+    log("posting under the Binclusive GitHub App identity");
+    return { token, identity: "binclusive-github-app" };
+  } catch (e) {
+    // Non-blocking: a failed brand falls back to the default token, never the run.
+    log(`GitHub App token mint failed, falling back to GITHUB_TOKEN: ${e instanceof Error ? e.message : String(e)}`);
+    return { token: defaultToken, identity: "github-actions" };
+  }
+}