@graphty/visual-review 0.1.3 → 0.2.1

package/trusted/lib/accept.mjs

@@ -26,16 +26,19 @@ import { isLfsPointer } from "./compare.mjs";
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 
 /** The statuses an item can be accepted or rejected in; unstable and failed are only excluded. */
-const DECIDABLE = new Set(["changed", "moved", "new", "removed"]);
+const DECIDABLE = new Set(["changed", "moved", "new", "unseeded", "removed"]);
 const EXCLUDABLE = new Set([...DECIDABLE, "unstable", "failed"]);
 
 /**
  * Refused decisions and failed git commands; the message is shown to the owner as is.
  * `committed` is set when the accepts were already pushed and only the reject comment failed,
- * so the caller drops the accepts and keeps the rejects for a retry that only comments.
+ * so the caller drops the accepts and keeps the rejects for a retry that only comments. On
+ * master, `pullRequestMissing` is set too when opening the seed's pull request failed: the caller
+ * keeps the accepts, and the retry opens the pull request for the branch already pushed.
  */
 export class AcceptError extends Error {
     committed = null;
+    pullRequestMissing = false;
 }
 
 /**
@@ -48,6 +51,7 @@ export class AcceptError extends Error {
  * with it, so the hooks path points nowhere. Signing is left as the repository configures it, so
  * the commit carries the owner's identity and signature. GIT_LFS_SKIP_SMUDGE keeps the worktree's
  * checkout from downloading every baseline image: untouched baselines stay pointer files there.
+ * GIT_TERMINAL_PROMPT=0 makes a credential prompt fail instead of waiting on a terminal.
  * @param {string} cwd the repository or worktree
  * @param {string[]} args git's arguments
  * @param {string} [input] stdin
@@ -57,7 +61,7 @@ const git = (cwd, args, input) =>
     exec("git", ["-c", "core.hooksPath=/dev/null", ...args], {
         cwd,
         input,
-        env: { ...process.env, HUSKY: "0", GIT_LFS_SKIP_SMUDGE: "1" },
+        env: { ...process.env, HUSKY: "0", GIT_LFS_SKIP_SMUDGE: "1", GIT_TERMINAL_PROMPT: "0" },
     });
 
 /** Images per `git lfs push --object-id`, so a large seed reports its upload as it goes. */
@@ -185,6 +189,7 @@ function check(projects, decisions) {
  * @param {{ project: string, file: string, decision: string, reason: string | null }[]} input.decisions
  *     what the owner decided: accept, reject or exclude (checked here)
  * @param {number} [input.undecided] how many reviewable items are left undecided, for the status
+ * @param {string[]} [input.unloaded] the projects whose capture did not load, so nobody reviewed them
  * @param {Date} [input.now] the review time
  * @param {(step: string) => void} [input.progress] told each step as it starts, for the page
  * @param {ReturnType<typeof import("./config.mjs").normalizeConfig>} input.config the settings
@@ -200,6 +205,7 @@ export async function finish({
     projects,
     decisions,
     undecided = 0,
+    unloaded = [],
     now = new Date(),
     progress = () => {},
     config,
@@ -220,12 +226,22 @@ export async function finish({
         ({ commit, branch } = await commitAccepts({ repo, target, accepts, first, now, progress, config }));
         if (isMaster) {
             progress("opening the pull request");
-            pullRequest = await createPullRequest(gh, {
-                title: `${config.commitPrefix}: seed visual baselines`,
-                head: branch,
-                base: config.defaultBranch,
-                body: seedBody(first, accepts, rejects, config.defaultBranch),
-            });
+            try {
+                pullRequest = await createPullRequest(gh, {
+                    title: `${config.commitPrefix}: seed visual baselines`,
+                    head: branch,
+                    base: config.defaultBranch,
+                    body: seedBody(first, accepts, rejects, config.defaultBranch),
+                });
+            } catch (err) {
+                const e = new AcceptError(
+                    `${branch} was pushed as ${commit.slice(0, 10)}, but opening its pull request failed: ` +
+                        `${err.message}. Press Finish again to open it.`,
+                );
+                e.committed = commit;
+                e.pullRequestMissing = true;
+                throw e;
+            }
         }
     }
     if (rejects.length > 0) {
@@ -259,10 +275,10 @@ export async function finish({
     // none. A failure here does not undo what was pushed and posted; the page shows it.
     const accepted = accepts.filter((a) => a.decision === "accept").length;
     const excluded = accepts.length - accepted;
-    const state = rejects.length > 0 ? "failure" : undecided > 0 ? "pending" : "success";
+    const state = rejects.length > 0 ? "failure" : undecided > 0 || unloaded.length > 0 ? "pending" : "success";
     const status =
         `Reviewed: ${accepted} accepted, ${rejects.length} rejected, ${excluded} excluded, ` +
-        `${undecided} left undecided`;
+        `${undecided} left undecided${unloaded.length > 0 ? `, not loaded: ${unloaded.join(", ")}` : ""}`;
     let statusError = null;
     progress("posting the status");
     try {
@@ -287,7 +303,11 @@ export async function finish({
  */
 async function commitAccepts({ repo, target, accepts, first, now, progress, config }) {
     const { baselines, defaultBranch } = config;
-    const tracking = `refs/remotes/origin/${defaultBranch}`;
+    // Finish fetches into refs of its own, never the remote-tracking refs a page reload fetches
+    // into at the same time (two fetches of one ref fail on its lock).
+    const own = (b) => `refs/visual-review/origin/${b}`;
+    const fetch = (b) => git(repo, ["fetch", "-q", "--no-write-fetch-head", "origin", `+refs/heads/${b}:${own(b)}`]);
+    const tracking = own(defaultBranch);
     const isMaster = target.pr === null;
     const lfs = await lfsProblem(repo);
     if (lfs) {
@@ -319,19 +339,27 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
         }
     }
 
-    await git(repo, ["fetch", "-q", "origin", `+refs/heads/${defaultBranch}:${tracking}`]);
+    await fetch(defaultBranch);
     if (isMaster) {
         if ((await git(repo, ["ls-remote", "--heads", "origin", branch])) !== "") {
+            // A seed this tool pushed whose pull request failed to open is used as it is.
+            // ponytail: assumes the decisions did not change since that push; compare the trees if
+            // they can.
+            await fetch(branch);
+            const [subject, parent] = (await git(repo, ["log", "-1", "--format=%s%n%P", own(branch)])).split("\n");
+            if (subject === `${config.commitPrefix}: seed visual baselines` && parent === base) {
+                return { commit: await git(repo, ["rev-parse", own(branch)]), branch };
+            }
             throw new AcceptError(`${branch} already exists on origin: merge or delete it first`);
         }
     } else {
-        await git(repo, ["fetch", "-q", "origin", `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
-        if ((await git(repo, ["rev-parse", `refs/remotes/origin/${branch}`])) !== base) {
+        await fetch(branch);
+        if ((await git(repo, ["rev-parse", own(branch)])) !== base) {
             throw new AcceptError("capture is stale, wait for CI: the branch has moved past the captured head");
         }
     }
     for (const project of new Set(accepts.map((a) => a.project))) {
-        if (await behindMaster(repo, base, project, config)) {
+        if (await behindMaster(repo, base, project, config, tracking)) {
             throw new AcceptError(
                 `merge ${defaultBranch} into the branch first: ${defaultBranch} has newer ${project} baselines`,
             );
@@ -406,12 +434,22 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
         progress("uploading images to LFS (checking the commit has them all)");
         await git(tree, ["lfs", "push", "origin", "HEAD"]);
         progress("pushing");
-        await git(tree, ["push", "-q", "--no-verify", "origin", `HEAD:refs/heads/${branch}`]);
+        await git(tree, ["push", "-q", "--no-verify", "origin", `HEAD:refs/heads/${branch}`]).catch((err) => {
+            // git's own advice ("git pull") is wrong here: the capture no longer matches the branch.
+            throw /\[rejected\].*\((fetch first|non-fast-forward)\)/.test(err.message)
+                ? new AcceptError(
+                      "capture is stale, wait for CI: the branch moved past the captured head while Finish ran; nothing was pushed",
+                  )
+                : err;
+        });
         return { commit: await git(tree, ["rev-parse", "HEAD"]), branch };
     } catch (err) {
         throw err instanceof AcceptError ? err : new AcceptError(err.message);
     } finally {
-        await removeWorktree(repo, tree);
+        // A cleanup failure must not hide what was pushed; the next Finish removes the tree.
+        await removeWorktree(repo, tree).catch((err) =>
+            console.error(`visual-review: could not remove the accept worktree ${tree}: ${err.message}`),
+        );
     }
 }
 
@@ -421,17 +459,17 @@ async function commitAccepts({ repo, target, accepts, first, now, progress, conf
  * @param {string} head the captured head
  * @param {string} project the project id
  * @param {{ defaultBranch: string, baselines: string }} config the settings
+ * @param {string} [tracking] the fetched default branch
  * @returns {Promise<boolean>} true when the branch must merge the default branch before an accept
  */
-export async function behindMaster(repo, head, project, { defaultBranch, baselines }) {
-    const newest = await git(repo, [
-        "log",
-        "-1",
-        "--format=%H",
-        `refs/remotes/origin/${defaultBranch}`,
-        "--",
-        `${baselines}/${project}/`,
-    ]);
+export async function behindMaster(
+    repo,
+    head,
+    project,
+    { defaultBranch, baselines },
+    tracking = `refs/remotes/origin/${defaultBranch}`,
+) {
+    const newest = await git(repo, ["log", "-1", "--format=%H", tracking, "--", `${baselines}/${project}/`]);
     return newest !== "" && !(await gitOk(repo, ["merge-base", "--is-ancestor", newest, head]));
 }
 
@@ -487,7 +525,8 @@ async function put(path, data) {
 
 async function removeWorktree(repo, tree) {
     if (existsSync(tree)) {
-        await git(repo, ["worktree", "remove", "--force", tree]);
+        // Twice: a server killed during `worktree add` leaves the tree locked ("initializing").
+        await git(repo, ["worktree", "remove", "--force", "--force", tree]);
     }
     await git(repo, ["worktree", "prune"]);
 }

package/trusted/lib/config.mjs

@@ -21,8 +21,9 @@ const DEFAULTS = {
     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._-]*$/;
+// Project ids name artifacts, jobs, directories and regular expressions, so they stay plain; and
+// results.json allows only these.
+const PROJECT_ID = /^[a-z0-9][a-z0-9-]*$/;
 // A path inside the repository: relative, no "..", no backslashes.
 const REPO_PATH = /^(?!\/)(?!.*(^|\/)\.\.(\/|$))[^\\]+$/;
 
@@ -72,7 +73,7 @@ export function normalizeConfig(input) {
     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 "-"`);
+            fail(`${where}: a project id is lowercase letters, digits and "-"`);
         }
         if (typeof p !== "object" || p === null) {
             fail(`${where} must be an object`);
@@ -90,6 +91,9 @@ export function normalizeConfig(input) {
         if (p.seedFromDefaultBranch !== undefined && typeof p.seedFromDefaultBranch !== "boolean") {
             fail(`${where}.seedFromDefaultBranch must be true or false`);
         }
+        if (p.gate !== undefined) {
+            fail(`${where}.gate is not a setting: every project is gated, and every story needs an approved baseline`);
+        }
         let waitFor = null;
         if (p.waitFor !== undefined && p.waitFor !== null) {
             const w = p.waitFor;

package/trusted/lib/github.mjs

@@ -10,22 +10,29 @@
  */
 
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 import { validateResults } from "./results.mjs";
 
 /**
- * Runs a program and resolves with its trimmed stdout.
+ * Runs a program and resolves with its trimmed stdout. A program that runs longer than
+ * VISUAL_REVIEW_TIMEOUT_MS (10 minutes by default) is killed: a gh or git call that stalls on a
+ * dead network, or waits on a prompt nobody sees, would otherwise hold the page or Finish forever.
  * @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 } = {}) {
+    const timeout = Number(process.env.VISUAL_REVIEW_TIMEOUT_MS) || 600000;
     return new Promise((resolve, reject) => {
-        const child = execFile(cmd, args, { cwd, env, encoding: "utf8", maxBuffer: 64 << 20 }, (err, out, stderr) => {
-            if (err) {
+        // SIGTERM (the default) lets git remove its lock files as it exits.
+        const options = { cwd, env, encoding: /** @type {const} */ ("utf8"), maxBuffer: 64 << 20, timeout };
+        const child = execFile(cmd, args, options, (err, out, stderr) => {
+            if (err?.killed) {
+                reject(new Error(`${cmd} ${args.join(" ")} timed out after ${timeout / 1000} s and was stopped`));
+            } else if (err) {
                 reject(new Error(stderr.trim() || err.message));
             } else {
                 resolve(out.trim());
@@ -42,7 +49,40 @@ export function exec(cmd, args, { cwd, input, env } = {}) {
  * @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 });
+export const ghRunner = (cwd) => withRetries((args, input) => exec("gh", args, { cwd, input }));
+
+// How gh reports a network that failed (DNS, a dropped or refused connection, a transfer cut
+// short, a call exec stopped) or a GitHub server error. A 4xx, a missing artifact or any other gh
+// error is real and is never retried.
+const TRANSIENT =
+    /could not resolve host|no such host|error connecting to|connection (reset|refused|timed out)|i\/o timeout|TLS handshake timeout|HTTP 5\d\d|unexpected EOF|GOAWAY|stream error|context deadline exceeded|timed out after/i;
+
+/**
+ * Retries a gh runner's calls that failed on the network, after each delay in turn. A write
+ * (`--input`) is never retried: GitHub may have applied it before the connection dropped. Every
+ * failure and retry is logged to stderr, so the server's log shows what happened.
+ * @param {(args: string[], input?: string) => Promise<string>} gh the gh runner
+ * @param {number[]} [delays] milliseconds before each retry
+ * @returns {(args: string[], input?: string) => Promise<string>} the retrying runner
+ */
+export const withRetries =
+    (gh, delays = [2000, 5000, 15000]) =>
+    async (args, input) => {
+        for (let i = 0; ; i++) {
+            try {
+                return await gh(args, input);
+            } catch (err) {
+                const retry = i < delays.length && !args.includes("--input") && TRANSIENT.test(err.message);
+                // gh's arguments never hold a token (gh keeps its own login), so they are logged whole.
+                const next = retry ? `; retrying in ${delays[i] / 1000} s` : "";
+                console.error(`visual-review: gh ${args.join(" ")} failed${next}: ${err.message}`);
+                if (!retry) {
+                    throw err;
+                }
+                await new Promise((resolve) => setTimeout(resolve, delays[i]));
+            }
+        }
+    };
 
 const api = async (gh, path) => JSON.parse(await gh(["api", path]));
 
@@ -108,7 +148,8 @@ export async function visualJobs(gh, run, attempt, projects) {
     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));
+            // The exact name: "visual (graphty-element)" also contains "graphty".
+            const job = visual.find((j) => j.name === `visual (${p})`);
             return [p, job && { conclusion: job.conclusion, url: job.html_url }];
         }),
     );
@@ -129,14 +170,28 @@ const downloading = new Map();
  * @returns {Promise<void>} settles when `dir` is complete, or the artifact had no results.json
  */
 function download(gh, runId, name, dir) {
-    if (existsSync(join(dir, "results.json"))) {
-        return Promise.resolve();
+    if (!downloading.has(dir) && existsSync(join(dir, "results.json"))) {
+        try {
+            JSON.parse(readFileSync(join(dir, "results.json"), "utf8"));
+            return Promise.resolve();
+        } catch (err) {
+            // Damaged on this disk (CI uploads only results.json it wrote): download it again.
+            console.error(
+                `visual-review: ${join(dir, "results.json")} is unreadable, downloading again: ${err.message}`,
+            );
+        }
     }
     if (!downloading.has(dir)) {
         const done = (async () => {
-            // A directory without results.json is left over from before downloads were atomic.
+            // A directory without results.json is left over from before downloads were atomic,
+            // and a .part- sibling from a download a killed server never finished.
             rmSync(dir, { recursive: true, force: true });
             mkdirSync(dirname(dir), { recursive: true });
+            for (const f of readdirSync(dirname(dir))) {
+                if (f.startsWith(`${basename(dir)}.part-`)) {
+                    rmSync(join(dirname(dir), f), { recursive: true, force: true });
+                }
+            }
             const part = mkdtempSync(`${dir}.part-`);
             try {
                 await gh(["run", "download", String(runId), "-n", name, "-D", part]);
@@ -155,31 +210,51 @@ function download(gh, runId, name, dir) {
 /**
  * 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, and
- * concurrent calls for the same one share a single download.
+ * concurrent calls for the same one share a single download. A failed download fails only its
+ * project, which the next call tries again. An expired artifact is used from disk when it was
+ * downloaded before.
  * @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
+ * @param {string[]} [others] receives the projects the run captured that are not in `projects`
+ * @returns {Promise<Record<string, { dir: string | null, attempt: number, error?: string,
+ *     expired?: true } | null>>} null for a project with no artifact; `error` (and no `dir`) when
+ *     its download failed; `expired` (and no `dir`) when GitHub deleted it and it is not on disk
  */
-export async function downloadCaptures(gh, run, projects, tmp) {
+export async function downloadCaptures(gh, run, projects, tmp, others = []) {
     const { artifacts } = await api(gh, `repos/{owner}/{repo}/actions/runs/${run.id}/artifacts?per_page=100`);
-    /** @type {Record<string, { dir: string, attempt: number } | null>} */
+    for (const a of artifacts) {
+        const p = /^visual-(.+)-\d+$/.exec(a.name)?.[1];
+        if (p && !projects.includes(p) && !others.includes(p)) {
+            others.push(p);
+        }
+    }
+    /** @type {Record<string, { dir: string | null, attempt: number, error?: string, expired?: true } | 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]) }))
+            .filter((a) => pattern.test(a.name))
+            .map((a) => ({ name: a.name, expired: a.expired, 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);
-        await download(gh, run.id, newest.name, dir);
-        out[project] = { dir, attempt: newest.attempt };
+        if (newest.expired) {
+            out[project] = existsSync(join(dir, "results.json"))
+                ? { dir, attempt: newest.attempt }
+                : { dir: null, attempt: newest.attempt, expired: true };
+            continue;
+        }
+        try {
+            await download(gh, run.id, newest.name, dir);
+            out[project] = { dir, attempt: newest.attempt };
+        } catch (err) {
+            out[project] = { dir: null, attempt: newest.attempt, error: err.message };
+        }
     }
     return out;
 }
@@ -205,7 +280,12 @@ export async function newestMasterCapture(gh, project, tmp, { workflow, defaultB
         if (!run) {
             continue;
         }
-        const dir = (await downloadCaptures(gh, run, [project], tmp))[project]?.dir;
+        const got = (await downloadCaptures(gh, run, [project], tmp))[project];
+        if (got?.error) {
+            // Not skipped: an older capture would be compared instead of this one.
+            throw new Error(got.error);
+        }
+        const dir = got?.dir;
         let results = null;
         try {
             results = dir ? JSON.parse(readFileSync(join(dir, "results.json"), "utf8")) : null;