@graphty/visual-review 0.0.1 → 0.1.1

package/trusted/lib/compare.mjs

@@ -0,0 +1,203 @@
+/**
+ * Comparison: is a capture the same as its baseline, and what does a story's pair of captures say?
+ *
+ * The SHA-256 of the PNG bytes decides first; only when the bytes differ are both images decoded
+ * and compared with pixelmatch at the story's threshold. A bounding box is [x, y, width, height].
+ */
+
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+// ponytail: pngjs until milestone 3 needs a dependency-free decoder
+import { PNG } from "pngjs";
+
+import pixelmatch from "../vendor/pixelmatch.mjs";
+
+/** Chromatic's default `diffThreshold`, used when a story sets none. */
+export const DEFAULT_THRESHOLD = 0.063;
+
+/**
+ * Hashes PNG bytes; equal hashes mean the images are identical without decoding either.
+ * @param {Buffer} bytes the file's bytes
+ * @returns {string} the hex SHA-256 of the bytes
+ */
+export const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+/** The first line of every Git LFS pointer file. */
+const LFS_POINTER = "version https://git-lfs.github.com/spec/";
+
+/**
+ * Whether bytes are a Git LFS pointer file rather than the image it stands for.
+ * @param {Buffer} bytes a file's bytes
+ * @returns {boolean} true for a pointer
+ */
+export const isLfsPointer = (bytes) => bytes.subarray(0, LFS_POINTER.length).toString("latin1") === LFS_POINTER;
+
+/**
+ * Reads a baseline PNG. Baselines are stored in Git LFS; a checkout without `git lfs pull` holds
+ * pointer files, and comparing a pointer would report every image as changed, so it throws.
+ * @param {string} path the baseline's path
+ * @returns {Promise<Buffer | null>} its bytes, or null when there is no baseline
+ */
+export async function readBaseline(path) {
+    const bytes = await readFile(path).catch((e) => {
+        if (e.code === "ENOENT") {
+            return null;
+        }
+        throw e;
+    });
+    if (bytes && isLfsPointer(bytes)) {
+        throw new Error(`${path}: baseline is an LFS pointer; run git lfs pull`);
+    }
+    return bytes;
+}
+
+/**
+ * Compares a capture with its baseline.
+ * @param {Buffer} baseline PNG bytes
+ * @param {Buffer} capture PNG bytes
+ * @param {{ threshold: number, includeAA: boolean }} options pixelmatch's threshold (0..1) and
+ *     whether anti-aliased pixels count as changed
+ * @returns {{ status: "unchanged" | "changed", baseline: string, capture: string,
+ *     size: number[] | null, baselineSize: number[] | null, changedPixels: number,
+ *     bbox: number[] | null }} sizes are [width, height]
+ */
+export function compareImages(baseline, capture, { threshold, includeAA }) {
+    const hashes = { baseline: sha256(baseline), capture: sha256(capture) };
+    if (hashes.baseline === hashes.capture) {
+        const size = pngSize(capture);
+        return { status: "unchanged", ...hashes, size, baselineSize: size, changedPixels: 0, bbox: null };
+    }
+    const a = PNG.sync.read(baseline);
+    const b = PNG.sync.read(capture);
+    const { changedPixels, bbox } = diffPixels(a, b, { threshold, includeAA });
+    return {
+        status: changedPixels === 0 ? "unchanged" : "changed",
+        ...hashes,
+        size: [b.width, b.height],
+        baselineSize: [a.width, a.height],
+        changedPixels,
+        bbox,
+    };
+}
+
+/**
+ * Counts the pixels that differ. Images of different sizes are compared over their top-left
+ * overlap, and every pixel of the larger canvas outside that overlap counts as changed.
+ * @param {PNG} a the decoded baseline
+ * @param {PNG} b the decoded capture
+ * @param {{ threshold: number, includeAA: boolean }} options pixelmatch's settings
+ * @returns {{ changedPixels: number, bbox: number[] | null }} the count and the box around them
+ */
+function diffPixels(a, b, options) {
+    const w = Math.min(a.width, b.width);
+    const h = Math.min(a.height, b.height);
+    const W = Math.max(a.width, b.width);
+    const H = Math.max(a.height, b.height);
+    const mask = Buffer.alloc(w * h * 4);
+    let changedPixels = pixelmatch(crop(a, w, h), crop(b, w, h), mask, w, h, { ...options, diffMask: true });
+
+    let [x0, y0, x1, y1] = [W, H, -1, -1];
+    const grow = (x, y) => {
+        x0 = Math.min(x0, x);
+        y0 = Math.min(y0, y);
+        x1 = Math.max(x1, x);
+        y1 = Math.max(y1, y);
+    };
+    if (changedPixels > 0) {
+        // With diffMask, pixelmatch paints only the counted pixels, so opaque means changed.
+        for (let i = 3; i < mask.length; i += 4) {
+            if (mask[i] !== 0) {
+                grow(((i - 3) / 4) % w, Math.floor((i - 3) / 4 / w));
+            }
+        }
+    }
+    const padding = W * H - w * h;
+    if (padding > 0) {
+        changedPixels += padding;
+        // The padding is the canvas outside the overlap: right of it, below it, or both.
+        if (W > w) {
+            grow(w, 0);
+            grow(W - 1, H - 1);
+        }
+        if (H > h) {
+            grow(0, h);
+            grow(W - 1, H - 1);
+        }
+    }
+    return { changedPixels, bbox: x1 < 0 ? null : [x0, y0, x1 - x0 + 1, y1 - y0 + 1] };
+}
+
+/**
+ * Copies out the top-left corner of an image, or returns its data when it is already that size.
+ * @param {PNG} img the decoded image
+ * @param {number} w the width to keep
+ * @param {number} h the height to keep
+ * @returns {Buffer} the RGBA of the top-left w x h of the image
+ */
+function crop(img, w, h) {
+    if (img.width === w && img.height === h) {
+        return img.data;
+    }
+    const out = Buffer.alloc(w * h * 4);
+    for (let y = 0; y < h; y++) {
+        img.data.copy(out, y * w * 4, y * img.width * 4, (y * img.width + w) * 4);
+    }
+    return out;
+}
+
+/**
+ * Classifies one story and mode from its baseline and up to two captures. A second capture is
+ * taken, in a fresh browser context, only when the first differs from the baseline or there is
+ * no baseline; without one (a local run) the first capture stands alone.
+ *
+ * A story with no baseline is `unseeded` ("no baseline yet") when its capture matches
+ * `reference`, master's newest capture of it: the pull request did not change it, so it needs no
+ * review here. It is `new` when it differs from master's, or master has none (a new story).
+ *
+ * `moved` says the baseline is another story id's, named in the project's renames.json: a story
+ * that only moved (same image, new id) is `moved` rather than `unchanged`, so it still needs an
+ * accept, which writes its baseline under the new name.
+ * @param {{ baseline: Buffer | null, first: Buffer | null, second?: Buffer | null,
+ *     reference?: Buffer | null, threshold: number, includeAA: boolean, moved?: boolean }} input
+ *     `first` is null when the story is gone
+ * @returns {{ status: "unchanged" | "moved" | "changed" | "new" | "unseeded" | "removed" | "unstable", flaky: boolean,
+ *     baseline: string | null, capture: string | null, size: number[] | null,
+ *     baselineSize: number[] | null, changedPixels: number | null, bbox: number[] | null }}
+ *     `capture` is the hash of the capture the status describes: the second one when flaky
+ */
+export function classify({ baseline, first, second = null, reference = null, threshold, includeAA, moved = false }) {
+    const options = { threshold, includeAA };
+    const matched = (r, flaky) => ({ ...r, status: moved ? "moved" : "unchanged", flaky });
+    const none = { flaky: false, size: null, baselineSize: null, changedPixels: null, bbox: null };
+    if (first === null) {
+        return { status: "removed", ...none, baseline: sha256(baseline), capture: null };
+    }
+    const agree = () => second === null || compareImages(first, second, options).status === "unchanged";
+    if (baseline === null) {
+        const same = reference !== null && compareImages(reference, first, options).status === "unchanged";
+        const status = same ? "unseeded" : agree() ? "new" : "unstable";
+        return { status, ...none, baseline: null, capture: sha256(first), size: pngSize(first) };
+    }
+    const vsFirst = compareImages(baseline, first, options);
+    if (vsFirst.status === "unchanged") {
+        return matched(vsFirst, false);
+    }
+    if (second === null) {
+        return { ...vsFirst, flaky: false };
+    }
+    const vsSecond = compareImages(baseline, second, options);
+    if (vsSecond.status === "unchanged") {
+        return matched(vsSecond, true);
+    }
+    return { ...vsFirst, status: agree() ? "changed" : "unstable", flaky: false };
+}
+
+/**
+ * Reads a PNG's dimensions.
+ * @param {Buffer} bytes PNG bytes
+ * @returns {number[]} [width, height], read from the IHDR chunk without decoding the image
+ */
+function pngSize(bytes) {
+    return [bytes.readUInt32BE(16), bytes.readUInt32BE(20)];
+}

package/trusted/lib/config.mjs

@@ -0,0 +1,168 @@
+/**
+ * The consuming repository's settings: `visual-review.config.json` at the root of its git
+ * checkout. Everything that differs from one repository to the next (its Storybooks, where the
+ * baselines live, its default branch, the workflow that captures, its commit and label
+ * conventions) is read from here, so the tool itself assumes none of it. The README's
+ * "Configuration" section documents every key. Standard library only: the gate reads it too.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CONFIG_FILE = "visual-review.config.json";
+
+const DEFAULTS = {
+    defaultBranch: "main",
+    workflow: "visual-review.yml",
+    baselines: "visual-baselines",
+    workDir: ".visual-review",
+    commitPrefix: "test",
+    issueLabels: ["bug"],
+};
+
+// Project ids name artifacts, jobs, directories and regular expressions, so they stay plain.
+const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// A path inside the repository: relative, no "..", no backslashes.
+const REPO_PATH = /^(?!\/)(?!.*(^|\/)\.\.(\/|$))[^\\]+$/;
+
+/**
+ * Checks a parsed config and fills in the defaults.
+ * @param {unknown} input the parsed JSON
+ * @returns {{ defaultBranch: string, workflow: string, baselines: string, workDir: string,
+ *     commitPrefix: string, issueLabels: string[], projects: Record<string, { storybook: string,
+ *     build: string | null, workers: number, seedFromDefaultBranch: boolean, waitFor: { selector:
+ *     string, method: string, failOnConsole: string | null } | null }> }} the settings
+ */
+export function normalizeConfig(input) {
+    const raw = /** @type {any} */ (input);
+    const fail = (msg) => {
+        throw new Error(`${CONFIG_FILE}: ${msg}`);
+    };
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        fail("must be a JSON object");
+    }
+    /** @type {any} */
+    const out = { ...DEFAULTS };
+    for (const key of ["defaultBranch", "workflow", "baselines", "workDir", "commitPrefix"]) {
+        if (raw[key] !== undefined) {
+            if (typeof raw[key] !== "string" || raw[key] === "") {
+                fail(`${key} must be a non-empty string`);
+            }
+            out[key] = raw[key];
+        }
+    }
+    for (const key of ["baselines", "workDir"]) {
+        if (!REPO_PATH.test(out[key])) {
+            fail(`${key} must be a path inside the repository, relative and without ".."`);
+        }
+        out[key] = out[key].replace(/\/+$/, "");
+    }
+    if (raw.issueLabels !== undefined) {
+        if (!Array.isArray(raw.issueLabels) || raw.issueLabels.some((l) => typeof l !== "string")) {
+            fail("issueLabels must be an array of strings");
+        }
+        out.issueLabels = raw.issueLabels;
+    }
+    const projects = raw.projects;
+    if (typeof projects !== "object" || projects === null || Object.keys(projects).length === 0) {
+        fail('projects must name at least one Storybook, e.g. { "web": { "storybook": "storybook-static" } }');
+    }
+    out.projects = {};
+    for (const [id, p] of Object.entries(projects)) {
+        const where = `projects.${id}`;
+        if (!PROJECT_ID.test(id)) {
+            fail(`${where}: a project id is letters, digits, ".", "_" and "-"`);
+        }
+        if (typeof p !== "object" || p === null) {
+            fail(`${where} must be an object`);
+        }
+        if (typeof p.storybook !== "string" || !REPO_PATH.test(p.storybook)) {
+            fail(`${where}.storybook must be the built Storybook's directory, relative to the repository`);
+        }
+        if (p.build !== undefined && typeof p.build !== "string") {
+            fail(`${where}.build must be a shell command`);
+        }
+        const workers = p.workers ?? 4;
+        if (!Number.isInteger(workers) || workers < 1) {
+            fail(`${where}.workers must be a positive integer`);
+        }
+        if (p.seedFromDefaultBranch !== undefined && typeof p.seedFromDefaultBranch !== "boolean") {
+            fail(`${where}.seedFromDefaultBranch must be true or false`);
+        }
+        let waitFor = null;
+        if (p.waitFor !== undefined && p.waitFor !== null) {
+            const w = p.waitFor;
+            if (typeof w?.selector !== "string" || typeof w?.method !== "string") {
+                fail(`${where}.waitFor needs a "selector" and a "method" to call on each matching element`);
+            }
+            waitFor = { selector: w.selector, method: w.method, failOnConsole: w.failOnConsole ?? null };
+        }
+        out.projects[id] = {
+            storybook: p.storybook.replace(/\/+$/, ""),
+            build: p.build ?? null,
+            workers,
+            seedFromDefaultBranch: p.seedFromDefaultBranch ?? true,
+            waitFor,
+        };
+    }
+    return out;
+}
+
+/**
+ * The root of the git checkout holding a directory.
+ * @param {string} [cwd] where to start
+ * @returns {string} the repository's top level
+ */
+export function repoRoot(cwd = process.cwd()) {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+        throw new Error(`${cwd} is not inside a git repository: run visual-review in your repository`);
+    }
+}
+
+/**
+ * Reads and checks the config of a checkout.
+ * @param {string} root the repository's top level
+ * @returns {ReturnType<typeof normalizeConfig>} the settings
+ */
+export function loadConfig(root) {
+    const file = join(root, CONFIG_FILE);
+    if (!existsSync(file)) {
+        throw new Error(`no ${CONFIG_FILE} in ${root}: run \`visual-review init\` there first`);
+    }
+    return parse(readFileSync(file, "utf8"));
+}
+
+/**
+ * Reads the config as it is at a git ref, falling back to the working tree when the ref has none
+ * (the pull request that adds visual review). The gate uses this with the base branch tip, so a
+ * pull request cannot move the baselines directory out from under the gate.
+ * @param {string} ref the ref
+ * @param {string} root the repository's top level
+ * @returns {ReturnType<typeof normalizeConfig>} the settings
+ */
+export function loadConfigAt(ref, root) {
+    let text;
+    try {
+        text = execFileSync("git", ["show", `${ref}:${CONFIG_FILE}`], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    } catch {
+        return loadConfig(root);
+    }
+    return parse(text);
+}
+
+function parse(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    } catch (e) {
+        throw new Error(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+    }
+    return normalizeConfig(raw);
+}

package/trusted/lib/github.mjs

@@ -0,0 +1,231 @@
+/**
+ * Everything the review page needs from GitHub, through the `gh` CLI with the reviewer's login:
+ * open pull requests, the CI run for a head, the `visual` job's outcome, the capture artifacts,
+ * and the comment, issue and pull request that a Finish writes. CI uses one of these too: a pull
+ * request's capture downloads master's newest capture with `newestMasterCapture`.
+ *
+ * Only `gh api` and `gh run download` are used, because they exist in every gh release still in
+ * use (Ubuntu 22.04 ships gh 2.4, which lacks `gh run list --commit` and most `--json` fields).
+ * `{owner}/{repo}` is filled in by gh from the repository's remote.
+ */
+
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { validateResults } from "./results.mjs";
+
+/**
+ * Runs a program and resolves with its trimmed stdout.
+ * @param {string} cmd the program
+ * @param {string[]} args its arguments
+ * @param {{ cwd?: string, input?: string, env?: object }} [options] stdin and environment
+ * @returns {Promise<string>} stdout; rejects with an Error whose message is the program's stderr
+ */
+export function exec(cmd, args, { cwd, input, env } = {}) {
+    return new Promise((resolve, reject) => {
+        const child = execFile(cmd, args, { cwd, env, encoding: "utf8", maxBuffer: 64 << 20 }, (err, out, stderr) => {
+            if (err) {
+                reject(new Error(stderr.trim() || err.message));
+            } else {
+                resolve(out.trim());
+            }
+        });
+        // A program that exits without reading stdin closes the pipe; its exit status reports that.
+        child.stdin.on("error", () => {});
+        child.stdin.end(input ?? "");
+    });
+}
+
+/**
+ * The real gh, run in the repository so `{owner}/{repo}` resolves.
+ * @param {string} cwd the repository
+ * @returns {(args: string[], input?: string) => Promise<string>} runs gh and returns its stdout
+ */
+export const ghRunner = (cwd) => (args, input) => exec("gh", args, { cwd, input });
+
+const api = async (gh, path) => JSON.parse(await gh(["api", path]));
+
+/**
+ * Open pull requests, newest first.
+ * @param {Function} gh the gh runner
+ * @returns {Promise<{ number: number, title: string, url: string, headSha: string, branch: string }[]>}
+ *     the pull requests
+ */
+export async function openPullRequests(gh) {
+    const pulls = await api(gh, "repos/{owner}/{repo}/pulls?state=open&per_page=100");
+    return pulls.map((p) => ({
+        number: p.number,
+        title: p.title,
+        url: p.html_url,
+        headSha: p.head.sha,
+        branch: p.head.ref,
+    }));
+}
+
+const toRun = (r) => ({
+    id: r.id,
+    attempt: r.run_attempt,
+    status: r.status,
+    conclusion: r.conclusion,
+    url: r.html_url,
+    headSha: r.head_sha,
+});
+
+/**
+ * The newest run of the capturing workflow for a head commit.
+ * @param {Function} gh the gh runner
+ * @param {string} sha the pull request's head
+ * @param {{ workflow: string }} config the workflow file that captures (the config's `workflow`)
+ * @returns {Promise<object | null>} the run, or null when CI never ran on it
+ */
+export async function newestCiRun(gh, sha, { workflow }) {
+    const { workflow_runs: runs } = await api(
+        gh,
+        `repos/{owner}/{repo}/actions/workflows/${encodeURIComponent(workflow)}/runs?head_sha=${sha}&per_page=1`,
+    );
+    return runs.length > 0 ? toRun(runs[0]) : null;
+}
+
+/**
+ * One run by id.
+ * @param {Function} gh the gh runner
+ * @param {number} id the run id
+ * @returns {Promise<object>} the run
+ */
+export const getRun = async (gh, id) => toRun(await api(gh, `repos/{owner}/{repo}/actions/runs/${id}`));
+
+/**
+ * The `visual` matrix job of each project in one attempt of a run.
+ * @param {Function} gh the gh runner
+ * @param {{ id: number }} run the run
+ * @param {number} attempt the attempt
+ * @param {string[]} projects project ids
+ * @returns {Promise<Record<string, { conclusion: string | null, url: string } | undefined>>} by project
+ */
+export async function visualJobs(gh, run, attempt, projects) {
+    const { jobs } = await api(gh, `repos/{owner}/{repo}/actions/runs/${run.id}/attempts/${attempt}/jobs?per_page=100`);
+    const visual = jobs.filter((j) => /^visual\b/.test(j.name));
+    return Object.fromEntries(
+        projects.map((p) => {
+            const job = visual.find((j) => j.name.includes(p));
+            return [p, job && { conclusion: job.conclusion, url: job.html_url }];
+        }),
+    );
+}
+
+/**
+ * Downloads each project's capture artifact from the highest attempt that uploaded one, into
+ * `<tmp>/<run>-<attempt>/<project>/`. An artifact already downloaded is not fetched again.
+ * @param {Function} gh the gh runner
+ * @param {{ id: number }} run the run
+ * @param {string[]} projects project ids
+ * @param {string} tmp the download root
+ * @returns {Promise<Record<string, { dir: string, attempt: number } | null>>} null for a project
+ *     with no unexpired artifact
+ */
+export async function downloadCaptures(gh, run, projects, tmp) {
+    const { artifacts } = await api(gh, `repos/{owner}/{repo}/actions/runs/${run.id}/artifacts?per_page=100`);
+    /** @type {Record<string, { dir: string, attempt: number } | null>} */
+    const out = {};
+    for (const project of projects) {
+        const pattern = new RegExp(`^visual-${project}-(\\d+)$`);
+        const newest = artifacts
+            .filter((a) => !a.expired && pattern.test(a.name))
+            .map((a) => ({ name: a.name, attempt: Number(pattern.exec(a.name)[1]) }))
+            .sort((a, b) => b.attempt - a.attempt)[0];
+        if (!newest) {
+            out[project] = null;
+            continue;
+        }
+        const dir = join(tmp, `${run.id}-${newest.attempt}`, project);
+        if (!existsSync(join(dir, "results.json"))) {
+            await gh(["run", "download", String(run.id), "-n", newest.name, "-D", dir]);
+        }
+        out[project] = { dir, attempt: newest.attempt };
+    }
+    return out;
+}
+
+/**
+ * Downloads the default branch's newest complete capture of one project: the reference a pull
+ * request's capture compares stories without a baseline against.
+ * ponytail: the newest default-branch run with a complete capture, not the run of the pull
+ * request's exact base; a story changed there since then shows as `new` (it blocks, never passes).
+ * @param {Function} gh the gh runner
+ * @param {string} project the project id
+ * @param {string} tmp the download root
+ * @param {{ workflow: string, defaultBranch: string }} config the capturing workflow and the branch
+ * @returns {Promise<string | null>} the capture's directory, or null when no run has one
+ */
+export async function newestMasterCapture(gh, project, tmp, { workflow, defaultBranch }) {
+    // The branch's newest commits, then each one's run: GitHub's list of a workflow's runs filtered
+    // by branch now and then answers with a stale page (runs from weeks ago), which made a pull
+    // request compare with an old capture or none. Commits and a run by head sha answer consistently.
+    const commits = await api(gh, `repos/{owner}/{repo}/commits?sha=${encodeURIComponent(defaultBranch)}&per_page=10`);
+    for (const { sha } of commits) {
+        const run = await newestCiRun(gh, sha, { workflow });
+        if (!run) {
+            continue;
+        }
+        const dir = (await downloadCaptures(gh, run, [project], tmp))[project]?.dir;
+        let results = null;
+        try {
+            results = dir ? JSON.parse(readFileSync(join(dir, "results.json"), "utf8")) : null;
+        } catch {
+            // An unreadable capture is skipped like a missing one.
+        }
+        if (results && validateResults(results).length === 0 && results.complete && results.project === project) {
+            return dir;
+        }
+    }
+    return null;
+}
+
+/**
+ * Opens an issue.
+ * @param {Function} gh the gh runner
+ * @param {{ title: string, body: string, labels: string[] }} issue what to open
+ * @returns {Promise<string>} its URL
+ */
+export async function createIssue(gh, { title, body, labels }) {
+    const input = JSON.stringify({ title, body, labels });
+    return JSON.parse(await gh(["api", "repos/{owner}/{repo}/issues", "--input", "-"], input)).html_url;
+}
+
+/**
+ * Posts a comment on a pull request.
+ * @param {Function} gh the gh runner
+ * @param {number} pr the pull request
+ * @param {string} body Markdown
+ * @returns {Promise<void>}
+ */
+export async function commentOnPullRequest(gh, pr, body) {
+    await gh(["api", `repos/{owner}/{repo}/issues/${pr}/comments`, "--input", "-"], JSON.stringify({ body }));
+}
+
+/**
+ * Sets the "Visual review" commit status on one commit. Finish posts it once, when it completes,
+ * never per decision.
+ * @param {Function} gh the gh runner
+ * @param {string} sha the commit
+ * @param {{ state: "success" | "failure" | "pending", description: string }} status what to post;
+ *     GitHub cuts the description at 140 characters
+ * @returns {Promise<void>}
+ */
+export async function postStatus(gh, sha, { state, description }) {
+    const input = JSON.stringify({ state, context: "Visual review", description: description.slice(0, 140) });
+    await gh(["api", `repos/{owner}/{repo}/statuses/${sha}`, "--input", "-"], input);
+}
+
+/**
+ * Opens a pull request.
+ * @param {Function} gh the gh runner
+ * @param {{ title: string, head: string, base: string, body: string }} pr what to open, and the
+ *     branch it merges into
+ * @returns {Promise<string>} its URL
+ */
+export async function createPullRequest(gh, { title, head, base, body }) {
+    const input = JSON.stringify({ title, head, base, body });
+    return JSON.parse(await gh(["api", "repos/{owner}/{repo}/pulls", "--input", "-"], input)).html_url;
+}