@binclusive/a11y 0.1.0

package/src/reporter/contract.ts

@@ -0,0 +1,154 @@
+/**
+ * The platform-adapter seam (issue #2235) — the ONE contract two CI platforms
+ * plug into, so a second platform is added behind this boundary instead of
+ * forking `entrypoint.sh`. It has two halves:
+ *
+ *   1. a DIFF-CONTEXT RESOLVER — "what changed + where to post", derived from the
+ *      platform's environment (the GitHub adapter reads `GITHUB_EVENT_PATH`-derived
+ *      env; a future GitLab/Buildkite adapter reads its own), and
+ *   2. a FINDINGS REPORTER — consumes the canonical `@binclusive/a11y-contract`
+ *      finding shape ({@link Finding}, the engine's `check --json` output) and
+ *      surfaces it on the platform's native review UI.
+ *
+ * An adapter pairs the two over ONE platform-native post-target type `Ctx`
+ * ({@link PlatformAdapter}). The `Ctx` never crosses the seam: {@link bindAdapter}
+ * erases it into a {@link BoundAdapter} by capturing the resolver's target in the
+ * closure it hands to the reporter, so a heterogeneous registry
+ * ({@link AdapterRegistry}) can store adapters of different `Ctx` types with no
+ * cast and no `any`.
+ *
+ * Opt-in by construction: when the resolver finds no PR/MR context (no token / not
+ * a PR event) it yields a `null` post-target, and {@link dispatch} no-ops the
+ * reporter — artifacts still emit, the gate still exits 0.
+ */
+import { type Finding, parseFindings } from "./finding";
+
+export { type Finding, parseFindings };
+export type { Impact } from "./finding";
+
+/** A best-effort logger; adapters log to stderr and never throw. */
+export type Logger = (msg: string) => void;
+
+/**
+ * Half 1 of the contract. Resolve the platform's change-context from the process
+ * env: the changed `.tsx` files to scan and the platform-native post-target, or
+ * `null` when there is no PR/MR context (⇒ the reporter no-ops). `Ctx` is the
+ * adapter's own post-target type — opaque to the seam.
+ */
+export interface DiffContextResolver<Ctx> {
+  resolve(env: NodeJS.ProcessEnv): DiffContext<Ctx>;
+}
+
+/** The resolved change-context: what changed + where to post (if anywhere). */
+export interface DiffContext<Ctx> {
+  /** Changed `.tsx` paths to scan; empty ⇒ the caller falls back to a wholesale scan. */
+  readonly changedTsx: readonly string[];
+  /**
+   * The platform-native surface findings post to, or `null` when no PR/MR context
+   * is present. `null` is the opt-in no-op signal — the reporter is never invoked.
+   */
+  readonly postTarget: Ctx | null;
+}
+
+/**
+ * Half 2 of the contract. Surface `findings` on the platform's native review UI,
+ * posting to the resolved `target`. Best-effort: an implementation logs and
+ * swallows failures rather than throwing, so a reporter error never fails the
+ * advisory gate.
+ */
+export interface FindingsReporter<Ctx> {
+  report(findings: readonly Finding[], target: Ctx, log: Logger): Promise<void>;
+}
+
+/** A platform adapter pairs the two halves over one post-target type `Ctx`. */
+export interface PlatformAdapter<Ctx> {
+  /** The explicit platform key used to select this adapter (e.g. `github`, `null`). */
+  readonly key: string;
+  readonly resolver: DiffContextResolver<Ctx>;
+  readonly reporter: FindingsReporter<Ctx>;
+}
+
+/**
+ * A reporter already bound to a resolved target — a thunk that posts `findings`,
+ * or `null` when there is no post-target (the opt-in no-op).
+ */
+export type BoundReporter = (findings: readonly Finding[], log: Logger) => Promise<void>;
+
+/** The Ctx-erased adapter the registry stores and {@link dispatch} drives. */
+export interface BoundAdapter {
+  readonly key: string;
+  /** Resolve change-context from env, returning changed files + a bound reporter (null ⇒ no-op). */
+  resolve(env: NodeJS.ProcessEnv): { readonly changedTsx: readonly string[]; readonly report: BoundReporter | null };
+}
+
+/**
+ * Erase an adapter's `Ctx` by pairing its resolver with its reporter in a
+ * closure: resolve the target once, then partially-apply the reporter into a
+ * {@link BoundReporter} that captures it. The `Ctx` never appears in
+ * {@link BoundAdapter}'s type, so adapters of different post-target types are
+ * assignment-compatible in one registry — with no cast (the narrowed `target`
+ * is captured in a const, not asserted).
+ */
+export function bindAdapter<Ctx>(adapter: PlatformAdapter<Ctx>): BoundAdapter {
+  return {
+    key: adapter.key,
+    resolve(env) {
+      const ctx = adapter.resolver.resolve(env);
+      if (ctx.postTarget === null) {
+        return { changedTsx: ctx.changedTsx, report: null };
+      }
+      const target = ctx.postTarget;
+      const report: BoundReporter = (findings, log) => adapter.reporter.report(findings, target, log);
+      return { changedTsx: ctx.changedTsx, report };
+    },
+  };
+}
+
+/** A registry of bound adapters, selectable by explicit platform key. */
+export class AdapterRegistry {
+  private readonly byKey: Map<string, BoundAdapter>;
+
+  constructor(adapters: readonly BoundAdapter[]) {
+    this.byKey = new Map(adapters.map((a) => [a.key, a]));
+  }
+
+  /** Select an adapter by its explicit platform key; `undefined` when unknown. */
+  select(key: string): BoundAdapter | undefined {
+    return this.byKey.get(key);
+  }
+
+  /** The keys of every registered adapter (for diagnostics / listing). */
+  keys(): string[] {
+    return [...this.byKey.keys()];
+  }
+}
+
+/**
+ * Drive one bound adapter: given the findings and the resolved change-context,
+ * invoke the reporter — or no-op when the resolver yielded no post-target. This
+ * is the dispatch the CLI runs; it locks the seam's opt-in contract in one place.
+ */
+export async function dispatch(
+  resolved: { readonly report: BoundReporter | null },
+  findings: readonly Finding[],
+  log: Logger,
+): Promise<void> {
+  if (resolved.report === null) {
+    log("no post context — reporter no-op (findings still emitted)");
+    return;
+  }
+  await resolved.report(findings, log);
+}
+
+/** The default platform when no explicit key is given — GitHub, so the shipped Action is behavior-preserving. */
+export const DEFAULT_PLATFORM_KEY = "github";
+
+/**
+ * Resolve the platform key from env (or a CLI flag value passed as `override`),
+ * defaulting to {@link DEFAULT_PLATFORM_KEY}. `A11Y_PLATFORM` is the explicit
+ * selector; a bare, empty, or unset value falls through to the default.
+ */
+export function resolvePlatformKey(env: NodeJS.ProcessEnv, override?: string): string {
+  const explicit = override && override !== "" ? override : env.A11Y_PLATFORM;
+  return explicit && explicit !== "" ? explicit : DEFAULT_PLATFORM_KEY;
+}

package/src/reporter/finding.ts

@@ -0,0 +1,87 @@
+/**
+ * The canonical finding shape a reporter consumes — the engine's `check --json`
+ * output (ADR 0039, `@binclusive/a11y-contract`). This is the platform-NEUTRAL
+ * input every {@link FindingsReporter} takes; it carries the source locators
+ * (`ruleId`/`file`/`line`) an inline review surface anchors on, which the
+ * metadata-only wire DTO (`emit-contract.ts`) deliberately drops.
+ *
+ * Lives here (not in a platform adapter) so the seam owns its own input type and
+ * no adapter is the canonical home of the shape all adapters share. `pr-comment.ts`
+ * re-exports these for its existing importers.
+ */
+
+import type { Impact } from "@binclusive/a11y-contract";
+
+/** The contract's canonical impact scale — the `Impact` enum in `@binclusive/a11y-contract`. */
+export type { Impact };
+
+/** The subset of an a11y finding a reporter renders from — the `check --json` shape. */
+export interface Finding {
+  readonly ruleId: string;
+  readonly file: string;
+  readonly line: number;
+  readonly message: string;
+  readonly wcag?: readonly string[];
+  /**
+   * The finding's contract impact, carried through from the report so a
+   * platform rollup can count by it. Optional: a report predating the field
+   * simply buckets the finding as unclassified.
+   */
+  readonly impact?: Impact;
+  /** The WCAG success-criterion id (contract `criterion`), e.g. "1.4.3". */
+  readonly criterion?: string;
+  /**
+   * The CSS selector of the offending rendered element, on axe/DOM findings only
+   * (source passes anchor by `file:line` and omit it). It is what distinguishes
+   * two same-rule findings co-located at one `file:line`.
+   */
+  readonly selector?: string;
+}
+
+/** Narrow an unknown report value to the contract's impact enum. */
+export function isImpact(value: unknown): value is Impact {
+  return (
+    value === "critical" ||
+    value === "serious" ||
+    value === "moderate" ||
+    value === "minor" ||
+    value === "unknown"
+  );
+}
+
+/**
+ * Boundary parse of the engine's findings JSON into the minimal shape a reporter
+ * renders from. Unknown in, narrowed out — a malformed entry is dropped rather
+ * than smuggling `any` inward (Parse-Don't-Validate at the reporter boundary).
+ */
+export function parseFindings(raw: unknown): Finding[] {
+  if (typeof raw !== "object" || raw === null) return [];
+  const findings = (raw as { findings?: unknown }).findings;
+  if (!Array.isArray(findings)) return [];
+  const out: Finding[] = [];
+  for (const item of findings) {
+    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;
+    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.
+    const selector = typeof f.selector === "string" ? f.selector : undefined;
+    const impact = isImpact(f.impact) ? f.impact : undefined;
+    // criterion is the contract's SC id; fall back to the first wcag tag so an
+    // older report (no criterion field) still yields a by-WCAG breakdown.
+    const criterion = typeof f.criterion === "string" && f.criterion !== "" ? f.criterion : wcag?.[0];
+    out.push({
+      ruleId: f.ruleId,
+      file: f.file,
+      line: f.line,
+      message: typeof f.message === "string" ? f.message : "",
+      ...(wcag ? { wcag } : {}),
+      ...(selector !== undefined ? { selector } : {}),
+      ...(impact !== undefined ? { impact } : {}),
+      ...(criterion !== undefined ? { criterion } : {}),
+    });
+  }
+  return out;
+}

package/src/reporter/github-adapter.ts

@@ -0,0 +1,183 @@
+/**
+ * The GitHub platform adapter — the FIRST adapter behind the reporter seam
+ * (issue #2235). It is the existing inline PR-comment behavior refactored to fit
+ * the contract, so the shipped Action is byte-for-byte behavior-preserving:
+ *
+ *   - the RESOLVER reads the same `GITHUB_REPOSITORY` / `PR_NUMBER` / `HEAD_SHA` /
+ *     `GITHUB_API_URL` env `entrypoint.sh` exports (from `GITHUB_EVENT_PATH`) and
+ *     the same `CHANGED_FILES` / `BASE_SHA` / `HEAD_SHA` diff scope, and
+ *   - the REPORTER is the former `pr-comment-cli.ts` body: it resolves the posting
+ *     identity (branded App, else `GITHUB_TOKEN` — issue #2130) and reconciles the
+ *     PR's inline review comments through {@link syncCommentsBestEffort} (#2131).
+ *
+ * Opt-in: the resolver yields a `null` post-target — so the reporter no-ops — when
+ * the PR context is incomplete OR no credential is present (no `GITHUB_TOKEN` and
+ * no App configured), matching the old `entrypoint.sh` skip guard.
+ */
+import { scopeChangedTsxFromEnv } from "../diff-scope";
+import { resolvePostingToken } from "../github-identity";
+import {
+  type Finding,
+  type PrCommentClient,
+  renderBody,
+  type ReviewComment,
+  syncCommentsBestEffort,
+} from "../pr-comment";
+import type { DiffContext, DiffContextResolver, FindingsReporter, Logger, PlatformAdapter } from "./contract";
+
+/** The GitHub-native surface an inline review comment posts to. */
+export interface GithubPostTarget {
+  /** `owner/name`, from `GITHUB_REPOSITORY`. */
+  readonly repo: string;
+  /** The PR number, from `PR_NUMBER`. */
+  readonly pr: string;
+  /** The head commit the RIGHT-side comment anchors on, from `HEAD_SHA`. */
+  readonly commitId: string;
+  /** The GitHub REST base (public API, or a GHES host). */
+  readonly api: string;
+  /**
+   * The process env the reporter resolves its posting token from — the branded
+   * App credentials (`BINCLUSIVE_APP_*`) or the Action's `GITHUB_TOKEN`. Carried
+   * on the target so token resolution (an async mint) stays in the reporter half.
+   */
+  readonly env: NodeJS.ProcessEnv;
+}
+
+const nonEmpty = (v: string | undefined): v is string => v !== undefined && v !== "";
+
+/** True when SOME posting credential is present — a token or a configured App. */
+function hasCredential(env: NodeJS.ProcessEnv): boolean {
+  if (nonEmpty(env.GITHUB_TOKEN)) return true;
+  return nonEmpty(env.BINCLUSIVE_APP_ID) && nonEmpty(env.BINCLUSIVE_APP_PRIVATE_KEY);
+}
+
+/** Resolve the GitHub change-context: changed `.tsx` + a post-target, or `null` when no PR context/credential. */
+export const githubResolver: DiffContextResolver<GithubPostTarget> = {
+  resolve(env): DiffContext<GithubPostTarget> {
+    const changedTsx = scopeChangedTsxFromEnv(env);
+    const repo = env.GITHUB_REPOSITORY;
+    const pr = env.PR_NUMBER;
+    const commitId = env.HEAD_SHA;
+    // Opt-in: a complete PR context AND a credential are both required to post —
+    // otherwise no target, so the reporter no-ops (the old entrypoint skip guard).
+    if (!nonEmpty(repo) || !nonEmpty(pr) || !nonEmpty(commitId) || !hasCredential(env)) {
+      return { changedTsx, postTarget: null };
+    }
+    const api = nonEmpty(env.GITHUB_API_URL) ? env.GITHUB_API_URL : "https://api.github.com";
+    return { changedTsx, postTarget: { repo, pr, commitId, api, env } };
+  },
+};
+
+/**
+ * Build the GitHub REST reconcile client for a resolved target. Inline review
+ * comments live under two endpoints: the PR-scoped collection (list + create) and
+ * the repo-scoped single-comment resource (update + delete). Every call is
+ * best-effort — a failure is logged and swallowed so one bad comment never aborts
+ * the sync.
+ */
+function makeClient(target: GithubPostTarget, token: string, log: Logger): PrCommentClient {
+  const { repo, pr, commitId, api } = target;
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "User-Agent": "binclusive-a11y-agent",
+    "Content-Type": "application/json",
+  };
+  return {
+    async list(): Promise<ReviewComment[]> {
+      const out: ReviewComment[] = [];
+      for (let page = 1; ; page++) {
+        const url = `${api}/repos/${repo}/pulls/${pr}/comments?per_page=100&page=${page}`;
+        let res: Response;
+        // A page failure must ABORT the whole sync (throw), not `break` with a
+        // partial list: reconciling against a truncated view reads comments on the
+        // unfetched pages as absent and re-CREATEs them → duplicates.
+        try {
+          res = await fetch(url, { headers });
+        } catch (e) {
+          throw new Error(`list page ${page} fetch failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!res.ok) {
+          throw new Error(`list page ${page} -> ${res.status} ${(await res.text().catch(() => "")).slice(0, 200)}`);
+        }
+        let batch: unknown;
+        try {
+          batch = await res.json();
+        } catch (e) {
+          throw new Error(`list page ${page} JSON parse failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (!Array.isArray(batch) || batch.length === 0) break;
+        for (const c of batch) {
+          if (
+            c &&
+            typeof c === "object" &&
+            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 });
+          }
+        }
+        if (batch.length < 100) break;
+      }
+      return out;
+    },
+
+    async create(f: Finding): Promise<void> {
+      // side:"RIGHT" anchors the comment on the head (post-change) version of the
+      // file — the line only exists there when it is part of the PR diff.
+      const payload = { body: renderBody(f), commit_id: commitId, path: f.file, line: f.line, side: "RIGHT" };
+      const url = `${api}/repos/${repo}/pulls/${pr}/comments`;
+      try {
+        const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload) });
+        if (!res.ok) log(`create ${f.file}:${f.line} -> ${res.status} ${(await res.text()).slice(0, 200)}`);
+      } catch (e) {
+        log(`create failed for ${f.file}:${f.line}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    },
+
+    async update(id: number, f: Finding): Promise<void> {
+      const url = `${api}/repos/${repo}/pulls/comments/${id}`;
+      try {
+        const res = await fetch(url, { method: "PATCH", headers, body: JSON.stringify({ body: renderBody(f) }) });
+        if (!res.ok) log(`update ${id} -> ${res.status} ${(await res.text()).slice(0, 200)}`);
+      } catch (e) {
+        log(`update failed for comment ${id}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    },
+
+    async remove(id: number): Promise<void> {
+      const url = `${api}/repos/${repo}/pulls/comments/${id}`;
+      try {
+        const res = await fetch(url, { method: "DELETE", headers });
+        if (!res.ok && res.status !== 404) log(`remove ${id} -> ${res.status} ${(await res.text()).slice(0, 200)}`);
+      } catch (e) {
+        log(`remove failed for comment ${id}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    },
+  };
+}
+
+/** Post inline PR review comments, de-duplicating across pushes (the #2131 reconcile). */
+export const githubReporter: FindingsReporter<GithubPostTarget> = {
+  async report(findings, target, log): Promise<void> {
+    // Resolve WHO posts once: branded App identity when configured, else GITHUB_TOKEN.
+    // Never throws — a mint failure degrades to the default token.
+    const { token, identity } = await resolvePostingToken(target.env, { repo: target.repo, api: target.api }, log);
+    if (!token) {
+      log("no posting token (no GitHub App configured and no GITHUB_TOKEN); skipping");
+      return;
+    }
+    log(`posting inline comments as ${identity}`);
+    const client = makeClient(target, token, log);
+    // Best-effort by contract: swallows any throw so the entrypoint always exits 0.
+    await syncCommentsBestEffort(findings, client, log);
+  },
+};
+
+/** The GitHub adapter: the diff-context resolver + the inline-comment reporter, keyed `github`. */
+export const githubAdapter: PlatformAdapter<GithubPostTarget> = {
+  key: "github",
+  resolver: githubResolver,
+  reporter: githubReporter,
+};

package/src/reporter/null-adapter.ts

@@ -0,0 +1,51 @@
+/**
+ * The null / stdout adapter — the "generic, no native review UI" platform, and
+ * the TRIVIAL SECOND adapter that proves the reporter seam holds ≥ 2 platforms
+ * (issue #2235). It is deliberately not GitHub-shaped: no PR identity, no
+ * credential, no de-dup reconcile — it just writes each finding to a sink.
+ *
+ * This is the seam's proof-of-generality, and the seed the future generic `--ci`
+ * mode (#2236) and the Buildkite/GitLab adapters (#2237/#2238) build on. Its
+ * post-target is always present (a sink is always available), so — unlike the
+ * GitHub adapter — it always reports; the no-context no-op path is exercised by
+ * the GitHub resolver instead.
+ */
+import { scopeChangedTsxFromEnv } from "../diff-scope";
+import type { DiffContext, DiffContextResolver, Finding, FindingsReporter, PlatformAdapter } from "./contract";
+
+/** A line sink — where the generic reporter writes. Injected so it is testable. */
+export type LineSink = (line: string) => void;
+
+/** The null adapter's post-target: just the line sink it writes findings to. */
+export interface NullPostTarget {
+  readonly write: LineSink;
+}
+
+/** One finding as a single stdout line — the generic, UI-less rendering. */
+export function renderLine(f: Finding): string {
+  const wcag = (f.wcag ?? []).length > 0 ? ` [${(f.wcag ?? []).map((s) => `WCAG ${s}`).join(", ")}]` : "";
+  const impact = f.impact ? `${f.impact}: ` : "";
+  return `${f.file}:${f.line} ${impact}${f.ruleId}${wcag} — ${f.message}`;
+}
+
+/** Build a null adapter over `sink` (defaults to stdout). */
+export function makeNullAdapter(sink: LineSink = (line) => process.stdout.write(line)): PlatformAdapter<NullPostTarget> {
+  const resolver: DiffContextResolver<NullPostTarget> = {
+    resolve(env): DiffContext<NullPostTarget> {
+      // A sink is always available, so the generic reporter always has a target.
+      return { changedTsx: scopeChangedTsxFromEnv(env), postTarget: { write: sink } };
+    },
+  };
+
+  const reporter: FindingsReporter<NullPostTarget> = {
+    async report(findings, target, log): Promise<void> {
+      for (const f of findings) target.write(`${renderLine(f)}\n`);
+      log(`generic reporter: wrote ${findings.length} finding(s) to the sink`);
+    },
+  };
+
+  return { key: "null", resolver, reporter };
+}
+
+/** The default null adapter — writes to stdout. */
+export const nullAdapter: PlatformAdapter<NullPostTarget> = makeNullAdapter();

package/src/reporter/registry.ts

@@ -0,0 +1,22 @@
+/**
+ * The default adapter registry — the two shipped platforms bound behind the seam
+ * (issue #2235): `github` (the first adapter, real inline PR comments) and `null`
+ * (the generic stdout adapter, the ≥ 2 proof). New platforms (#2237 Buildkite,
+ * #2238 GitLab) register here; nothing else changes.
+ *
+ * Each adapter is Ctx-erased through {@link bindAdapter} at registration, so the
+ * registry stores platforms of different post-target types in one map with no cast.
+ */
+import { AdapterRegistry, bindAdapter, type BoundAdapter } from "./contract";
+import { githubAdapter } from "./github-adapter";
+import { nullAdapter } from "./null-adapter";
+
+/** The bound adapters shipped by default. Order is irrelevant — selection is by key. */
+export function defaultBoundAdapters(): BoundAdapter[] {
+  return [bindAdapter(githubAdapter), bindAdapter(nullAdapter)];
+}
+
+/** The default registry: `github` + `null`, selectable by explicit platform key. */
+export function defaultRegistry(): AdapterRegistry {
+  return new AdapterRegistry(defaultBoundAdapters());
+}

package/src/reporter-cli.ts

@@ -0,0 +1,48 @@
+/**
+ * The thin CLI over the reporter-adapter seam (issue #2235) that `entrypoint.sh`
+ * invokes (through the root `report.mjs` tsx wrapper) after a scan. It selects the
+ * platform adapter by explicit key (`A11Y_PLATFORM`, defaulting to `github` so the
+ * shipped Action is behavior-preserving), resolves the platform's post-context
+ * from env, parses the engine's findings JSON, and dispatches to the reporter.
+ *
+ * Best-effort by design: any missing context, unknown platform, failed read, or
+ * failed API call is logged to stderr and skipped — never thrown — so the calling
+ * entrypoint always exits 0 (the gate is advisory). When the resolver finds no
+ * PR/MR post-context, the reporter no-ops and the artifacts still emit.
+ *
+ * Args: <report-path>. Env: A11Y_PLATFORM (optional; default `github`), plus each
+ * adapter's own env (GitHub: GITHUB_REPOSITORY / PR_NUMBER / HEAD_SHA / GITHUB_TOKEN
+ * / GITHUB_API_URL / BINCLUSIVE_APP_*).
+ */
+import { readFileSync } from "node:fs";
+import { dispatch, type Finding, parseFindings, resolvePlatformKey } from "./reporter/contract";
+import { defaultRegistry } from "./reporter/registry";
+
+const log = (msg: string): void => console.error(`reporter: ${msg}`);
+
+const reportPath = process.argv[2];
+if (!reportPath) {
+  log("no report path argument; skipping");
+  process.exit(0);
+}
+
+const key = resolvePlatformKey(process.env);
+const adapter = defaultRegistry().select(key);
+if (!adapter) {
+  log(`unknown platform "${key}"; skipping`);
+  process.exit(0);
+}
+log(`platform: ${key}`);
+
+const loadFindings = (path: string): Finding[] => {
+  try {
+    return parseFindings(JSON.parse(readFileSync(path, "utf8")));
+  } catch (e) {
+    log(`could not read findings JSON: ${e instanceof Error ? e.message : String(e)}`);
+    return [];
+  }
+};
+
+const findings = loadFindings(reportPath);
+const resolved = adapter.resolve(process.env);
+await dispatch(resolved, findings, log);