forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/proofRun.js

@@ -0,0 +1,412 @@
+/**
+ * What `forgebook proof` runs: where a change started and the change, each drawn in this run on this machine, and their
+ * pictures compared.
+ *
+ * @remarks
+ * Nothing is stored between runs, so there is no baseline for anyone to approve: the "before" is drawn from the merge base
+ * here, in a checkout of its own with its own install and its own `forgebook dev`, and thrown away. The folder of baselines
+ * a project may keep is never read. Pictures from one machine in one job leave rendering out of the difference, and what
+ * still differs is pictured a second time from the same code: a state that differs then too is `unstable`, and proves
+ * nothing. The code under review runs in this job and could lie about all of this, so the answer names the files that make
+ * the proof whenever the change edits them, for a person to read.
+ *
+ * @module
+ */
+import { execFile, spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { promisify } from "node:util";
+import { isStoriesDocument } from "../../src/vite/agentApi.js";
+import { AGENT_API } from "../../src/vite/agentRoutes.js";
+import { findConfigFile } from "../../src/vite/configFile.js";
+import { changeBase, gitOutput, noBaseReason } from "../../src/vite/gitChange.js";
+import { installCommandOf } from "./proofWorkflow.js";
+import { runStoriesDiff, runStoriesShot, testingFunction } from "./storyCheckRun.js";
+const run = promisify(execFile);
+/** How long the base's server may take to answer, in ms: a first start builds its programs and prebundles. */
+const BASE_READY_MS = 300_000;
+/** How much of what the base's server says is kept, in characters. */
+const SERVER_WORDS = 1500;
+/** How long an install may take, in ms. */
+const INSTALL_MS = 900_000;
+/** The files that make the proof, not what it shows: an edit to them is read by a person, whatever the pictures say. */
+export const MAKES_THE_PROOF = /^(?:\.github\/|patches\/|.*(?:forgebook\.(?:config|preview)\.[^/]+|vite\.config\.[^/]+|package\.json|package-lock\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|bun\.lock|\.npmrc|\.yarnrc\.yml|\.pnpmfile\.c?js)$)/;
+/**
+ * The listed stories' ids in a catalogue's answer.
+ *
+ * @param document - the answer.
+ */
+export const listedIds = (document) => document.components.flatMap((component) => component.stories.filter((story) => !story.isUnlisted).map((story) => story.id));
+/**
+ * Every story's id in a catalogue's answer, those listed nowhere among them.
+ *
+ * @param document - the answer.
+ */
+export const allIds = (document) => document.components.flatMap((component) => component.stories.map((story) => story.id));
+/** A port free right now. */
+const freePort = () => new Promise((resolvePort, reject) => {
+    const probe = createServer();
+    probe.once("error", reject);
+    probe.listen(0, "127.0.0.1", () => {
+        const address = probe.address();
+        const port = typeof address === "object" && address !== null ? address.port : 0;
+        probe.close(() => resolvePort(port));
+    });
+});
+/** Waits until a server answers with its stories, or says why it will not. */
+const serverStories = async (origin, server) => {
+    const deadline = Date.now() + BASE_READY_MS;
+    while (Date.now() < deadline) {
+        // a server stopped by a signal has no exit code, and would be waited for to the end
+        if (server.exitCode !== null || server.signalCode !== null)
+            return `A forgebook dev started for this run stopped (${server.exitCode ?? server.signalCode})`;
+        const body = await fetch(`${origin}${AGENT_API}stories`)
+            .then((response) => response.json())
+            .catch(() => undefined);
+        if (isStoriesDocument(body))
+            return body;
+        await new Promise((wake) => {
+            setTimeout(wake, 500);
+        });
+    }
+    return `A forgebook dev started for this run did not answer in ${BASE_READY_MS / 1000} s`;
+};
+/** The base's picture of a state, copied beside the others, and the marked one, moved: what a reviewer downloads. */
+const stateOf = (result, out, isUnstable) => {
+    const pictures = join(out, "pictures");
+    const keep = (file, name) => {
+        if (file === undefined || !existsSync(file))
+            return undefined;
+        const kept = join(pictures, `${name}-${basename(file)}`);
+        copyFileSync(file, kept);
+        return relative(out, kept).replaceAll("\\", "/");
+    };
+    const before = result.status === "new" ? undefined : keep(result.baseline, "before");
+    const after = result.status === "removed" ? undefined : keep(result.current, "after");
+    const marked = keep(result.diff, "marked");
+    return {
+        storyId: result.storyId,
+        view: result.view,
+        status: isUnstable ? "unstable" : result.status,
+        percent: result.percent,
+        pictures: {
+            ...(before === undefined ? {} : { before }),
+            ...(after === undefined ? {} : { after }),
+            ...(marked === undefined ? {} : { marked })
+        }
+    };
+};
+/** A state's key in a comparison. */
+const keyOf = (result) => `${result.storyId}\n${result.view}`;
+/** What the change edits of what makes the proof. */
+const ownFilesOf = async (dir, base) => {
+    const listed = await gitOutput(dir, "diff", "--no-ext-diff", "--no-relative", "--name-only", "-z", base, "--");
+    return listed.split("\0").filter((file) => file !== "" && MAKES_THE_PROOF.test(file));
+};
+/** What was not checked, in words. */
+const notCheckedOf = (verified, ownFiles, leftOut, states, isQuick) => {
+    const unstable = states.filter((state) => state.status === "unstable").length;
+    const broken = states.filter((state) => state.status === "broken").length;
+    return [
+        // first: a comment's cap cuts from the end, and this is what must not be lost
+        ...(ownFiles.length === 0
+            ? []
+            : [`this change edits what makes this proof, so read these yourself: ${ownFiles.join(", ")}`]),
+        ...verified.skipped,
+        ...verified.uiFiles.flatMap((file) => file.coverage === "none" ? [`${file.file}: ${file.reason ?? "no story reaches it"}`] : []),
+        ...verified.notVerified.map((each) => `${each.storyId} (${each.view}): ${each.notVerified}`),
+        ...(leftOut.length === 0
+            ? []
+            : [`${leftOut.length} stories not pictured, past the limit: ${leftOut.slice(0, 20).join(", ")}`]),
+        ...(unstable === 0
+            ? []
+            : [`${unstable} states differ between two pictures of the same code: their difference proves nothing`]),
+        ...(broken === 0 ? [] : [`${broken} states did not draw, so their pictures prove nothing`]),
+        ...(isQuick ? ["only the default view pictured: --quick"] : []),
+        "real pages of the application, and anything no story shows"
+    ];
+};
+/** The file a manifest's `forgebook` command starts. */
+const binOf = (manifest) => {
+    const read = JSON.parse(readFileSync(manifest, "utf8"));
+    const bin = typeof read === "object" && read !== null && "bin" in read ? read.bin : undefined;
+    const file = typeof bin === "object" && bin !== null && "forgebook" in bin ? bin.forgebook : undefined;
+    return typeof file === "string" ? join(dirname(manifest), file) : undefined;
+};
+/**
+ * The file that starts a checkout's own `forgebook`, looked for as Node looks for a package: its manifest is not among
+ * what it exports, so it cannot be asked for by name.
+ *
+ * @param dir - the catalogue's folder in the checkout.
+ * @returns the file; none when no Forgebook is installed there.
+ */
+const forgebookEntry = (dir) => {
+    let folder = dir;
+    while (dirname(folder) !== folder) {
+        const manifest = join(folder, "node_modules", "forgebook", "package.json");
+        if (existsSync(manifest))
+            return binOf(manifest);
+        folder = dirname(folder);
+    }
+    return undefined;
+};
+/**
+ * Starts a checkout's own `forgebook dev`, and waits until it answers.
+ *
+ * @param dir - the catalogue's folder.
+ * @param entry - the file that starts its `forgebook`.
+ * @param configFile - the configuration file named on the command line, relative to the folder.
+ * @returns the server, or why it would not answer.
+ */
+const servedSide = async (dir, entry, configFile) => {
+    const port = await freePort();
+    const origin = `http://localhost:${port}`;
+    const named = configFile === undefined ? [] : ["--config", configFile];
+    const server = spawn(process.execPath, [entry, "dev", "--port", String(port), ...named], {
+        cwd: dir,
+        stdio: ["ignore", "ignore", "pipe"]
+    });
+    // the end of what it says is why it stopped, which a run in CI has no other way to tell
+    let said = "";
+    server.stderr?.on("data", (part) => {
+        said = `${said}${part.toString()}`.slice(-SERVER_WORDS);
+    });
+    const stories = await serverStories(origin, server);
+    if (typeof stories !== "string")
+        return {
+            origin,
+            stories,
+            // waited for: the checkout it serves is removed next
+            close: () => new Promise((done) => {
+                server.once("exit", () => done());
+                server.kill();
+            })
+        };
+    server.kill();
+    return `${stories}${said === "" ? "" : `: ${said.trim()}`}`;
+};
+/**
+ * Draws stories once and throws the pictures away. On a cold server the bundler finds a dependency mid-load and reloads the
+ * page, and a frame then pictured nearly empty (a page 19 px tall where the same commit draws 1,068) reads as a change that
+ * is not there.
+ *
+ * @param config - the side's configuration.
+ * @param origin - its server.
+ * @param input - the stories.
+ * @param folder - where to throw them.
+ */
+const warmed = async (config, origin, input, folder) => {
+    const shot = await runStoriesShot(config, origin, input, folder);
+    return typeof shot === "string" ? shot : undefined;
+};
+/**
+ * Pictures the base from its own checkout, install and server.
+ *
+ * @param reach - the change's catalogue.
+ * @param input - what is asked.
+ * @param commit - the commit to draw.
+ * @param ids - the stories wanted.
+ * @param headIds - every story the change has: one the base has and it does not was removed.
+ * @param folder - where its pictures go.
+ * @returns what it could draw, or why it could not run.
+ */
+const pictureBase = async (reach, input, commit, ids, headIds, folder) => {
+    const { config, say } = reach;
+    const root = (await gitOutput(config.dir, "rev-parse", "--show-toplevel")).trim();
+    const work = mkdtempSync(join(input.work ?? tmpdir(), "forgebook-proof-"));
+    const checkout = join(work, "base");
+    let served;
+    try {
+        await gitOutput(root, "worktree", "add", "--quiet", "--detach", checkout, commit);
+        const install = input.install ?? installCommandOf(checkout);
+        if (install !== undefined && install !== "") {
+            say(`Installing the base: ${install}`);
+            await run(install, { cwd: checkout, shell: true, timeout: INSTALL_MS, maxBuffer: 64 * 1024 * 1024 });
+        }
+        // as the server will name it, or the client would not know it for this catalogue: a temporary folder is often a link
+        const dir = join(realpathSync(checkout), relative(realpathSync(root), realpathSync(config.dir)));
+        const entry = existsSync(dir) && findConfigFile(dir) !== undefined ? forgebookEntry(dir) : undefined;
+        if (entry === undefined)
+            return { undrawn: [], removed: [], isWithoutCatalogue: true };
+        const side = await servedSide(dir, entry, reach.configFile);
+        if (typeof side === "string")
+            return side;
+        served = side;
+        const all = new Set(allIds(side.stories));
+        const known = ids.filter((id) => all.has(id));
+        const gone = listedIds(side.stories).filter((id) => !headIds.has(id));
+        const wanted = [...known, ...gone];
+        if (wanted.length === 0)
+            return { undrawn: [], removed: [] };
+        // the change's testing package and browser for both, or two versions would differ by themselves
+        const stories = { ids: wanted, isAllVariants: !input.isQuick };
+        say("Picturing the base");
+        const cold = await warmed(config, side.origin, stories, join(work, "warm"));
+        if (cold !== undefined)
+            return cold;
+        const shot = await runStoriesShot(config, side.origin, stories, folder);
+        if (typeof shot === "string")
+            return shot;
+        const isGone = new Set(gone);
+        return {
+            undrawn: [
+                ...new Set(shot.shots.filter((each) => each.status !== undefined).map((each) => each.storyId))
+            ],
+            removed: shot.shots.filter((each) => isGone.has(each.storyId))
+        };
+    }
+    finally {
+        await served?.close();
+        await gitOutput(root, "worktree", "remove", "--force", checkout).catch(() => "");
+        rmSync(work, { recursive: true, force: true, maxRetries: 3 });
+    }
+};
+/**
+ * Pictures both sides of the stories wanted, then what differs a second time. The change is served as the base is, by its
+ * own `forgebook dev` and warmed the same way, so the two pictures differ by the change and not by how they were made.
+ *
+ * @param reach - the change's catalogue.
+ * @param input - what is asked.
+ * @param base - the commit the change started from.
+ * @param ids - the stories.
+ * @param headIds - every story the change has.
+ * @param work - a folder to keep the pictures in while this runs.
+ */
+const comparedSides = async (reach, input, base, ids, headIds, work) => {
+    const { say } = reach;
+    const isAllVariants = !input.isQuick;
+    const before = join(work, "before");
+    const after = join(work, "after");
+    mkdirSync(before);
+    const pictured = await pictureBase(reach, input, base, ids, headIds, before);
+    if (typeof pictured === "string")
+        return pictured;
+    const dir = realpathSync(reach.config.dir);
+    const config = { ...reach.config, dir };
+    const entry = forgebookEntry(dir);
+    if (entry === undefined)
+        return "This catalogue's folder has no Forgebook installed";
+    const side = await servedSide(dir, entry, reach.configFile);
+    if (typeof side === "string")
+        return side;
+    try {
+        const stories = { ids, isAllVariants };
+        say(`Picturing ${ids.length} stories with the change`);
+        const cold = await warmed(config, side.origin, stories, join(work, "warm"));
+        if (cold !== undefined)
+            return cold;
+        const report = await runStoriesDiff(config, side.origin, stories, { baselines: before, outDir: after });
+        if (typeof report === "string")
+            return report;
+        const differing = report.results.filter((each) => each.status === "changed" || each.status === "resized");
+        if (differing.length === 0)
+            return { report, unstable: new Set(), side: pictured };
+        // the same code again: what moves now is noise, and says nothing of the change
+        say(`Picturing ${differing.length} differing states a second time`);
+        const again = await runStoriesDiff(config, side.origin, { ids: [...new Set(differing.map((each) => each.storyId))], isAllVariants }, { baselines: after, outDir: join(work, "control") });
+        if (typeof again === "string")
+            return again;
+        const unstable = new Set(again.results.filter((each) => each.status !== "same").map(keyOf));
+        return { report, unstable, side: pictured };
+    }
+    finally {
+        await side.close();
+    }
+};
+/**
+ * Compares a change with where it started, and writes the proof.
+ *
+ * @param reach - the change's catalogue.
+ * @param input - what is asked.
+ * @returns the proof, or why there can be none.
+ */
+export const runProof = async (reach, input) => {
+    const { config, say } = reach;
+    const testing = await testingFunction(config.dir, "@forgebook/testing/diff", "diffStories");
+    if (typeof testing === "string")
+        return testing;
+    const base = await changeBase(config.dir, input.base);
+    if (base === undefined)
+        return noBaseReason(config.dir, input.base);
+    const head = (await gitOutput(config.dir, "rev-parse", "HEAD")).trim();
+    say("Verifying the change");
+    const verified = await reach.verify(input.base);
+    if (typeof verified === "string")
+        return verified;
+    const stories = await reach.stories();
+    if (typeof stories === "string")
+        return stories;
+    const reached = input.isAll ? listedIds(stories) : await reach.changedIds(input.base);
+    if (typeof reached === "string")
+        return reached;
+    const ids = reached.slice(0, input.maxStories);
+    const leftOut = reached.slice(input.maxStories);
+    const headIds = new Set(allIds(stories));
+    const work = mkdtempSync(join(input.work ?? tmpdir(), "forgebook-pictures-"));
+    mkdirSync(join(input.out, "pictures"), { recursive: true });
+    try {
+        const compared = ids.length === 0
+            ? {
+                report: { schema: 1, results: [] },
+                unstable: new Set(),
+                side: { undrawn: [], removed: [] }
+            }
+            : await comparedSides(reach, input, base, ids, headIds, work);
+        if (typeof compared === "string")
+            return compared;
+        const { report, unstable, side } = compared;
+        const states = [
+            ...report.results.flatMap((each) => each.status === "same"
+                ? []
+                : [stateOf({ ...each, status: each.status }, input.out, unstable.has(keyOf(each)))]),
+            ...side.removed.map((shot) => stateOf({
+                storyId: shot.storyId,
+                view: shot.view,
+                status: "removed",
+                changedPixels: 0,
+                percent: 100,
+                baseline: shot.file,
+                current: ""
+            }, input.out, false))
+        ];
+        return {
+            schema: 1,
+            base,
+            head,
+            verdict: verified.verdict,
+            summary: verified.summary,
+            states,
+            same: report.results.filter((each) => each.status === "same").length,
+            checked: [
+                `pictures of ${ids.length} stories, ${input.isQuick ? "default view" : "every variant"}, from two builds in this run`,
+                `check-code: ${verified.code.checked.join(", ") || "nothing"}`,
+                `${verified.ran} story and view pairs through the checks (accessibility, spills, overlays, page errors)`
+            ],
+            notChecked: [
+                ...notCheckedOf(verified, await ownFilesOf(config.dir, base), leftOut, states, input.isQuick),
+                ...(side.undrawn.length === 0
+                    ? []
+                    : [`did not draw at the base, so their "before" proves nothing: ${side.undrawn.join(", ")}`]),
+                ...(side.isWithoutCatalogue === true
+                    ? ["the base has no catalogue to draw, or no Forgebook installed: every state reads as new"]
+                    : [])
+            ]
+        };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true, maxRetries: 3 });
+    }
+};
+/**
+ * Writes a proof's files.
+ *
+ * @param out - the folder.
+ * @param files - each file's name and text.
+ */
+export const writeProofFiles = (out, files) => {
+    mkdirSync(out, { recursive: true });
+    for (const [name, text] of Object.entries(files))
+        writeFileSync(join(out, name), text);
+};

package/dist/bin/forgebook/proofText.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What `forgebook proof` writes for a person: the pull request's comment and a page of pictures.
+ *
+ * @remarks
+ * Pure. Everything here comes from the branch under review, whose author may be an agent or a stranger: a file or a story
+ * can be named anything. This is what the command prints and the run's summary shows; the pull request's comment is written
+ * by a job that trusts none of it (`proofWorkflow.ts`). A name only ever appears in a code span or a fenced block, where Markdown does not make a link,
+ * an image or a mention of it, and in the page it is escaped. The comment's size is held under what GitHub accepts, cutting
+ * whole lines and saying so. A comment that showed only what differs would read as all clear, so what was not checked
+ * has a section of its own, always there.
+ *
+ * @module
+ */
+import type { ProofDocument } from "../../src/vite/agent.types.ts";
+/** What the workflow replaces with the address of the run's pictures, known only once they are uploaded. */
+export declare const ARTIFACT_PLACEHOLDER = "__FORGEBOOK_PROOF_ARTIFACT__";
+/**
+ * A name as a Markdown code span, whatever it holds: no line break, a fence longer than any run of backticks in it, and
+ * nothing a table reads as a new cell.
+ *
+ * @param text - the name.
+ */
+export declare const codeSpan: (text: string) => string;
+/**
+ * The pull request's comment.
+ *
+ * @param document - the proof.
+ * @returns its Markdown, with `ARTIFACT_PLACEHOLDER` where the pictures' address goes.
+ */
+export declare const proofComment: (document: ProofDocument) => string;
+/**
+ * The page a reviewer opens from the run's pictures: every state side by side, what was not checked above them.
+ *
+ * @param document - the proof.
+ */
+export declare const proofPage: (document: ProofDocument) => string;

package/dist/bin/forgebook/proofText.js

@@ -0,0 +1,131 @@
+/** What the workflow replaces with the address of the run's pictures, known only once they are uploaded. */
+export const ARTIFACT_PLACEHOLDER = "__FORGEBOOK_PROOF_ARTIFACT__";
+/** The longest comment written, in characters: GitHub refuses over 65,536. */
+const MAX_COMMENT = 60_000;
+/** What ends a comment that had to be cut. */
+const CUT_ENDING = "\n\nCut here to fit a comment: the rest is in the pictures' `proof.json`.\n";
+/** The most states a comment lists: the rest are in the page. */
+const MAX_LISTED = 40;
+/** The longest name kept in a code span. */
+const MAX_NAME = 120;
+/** A status in the words of a person reading a review. */
+const STATUS_WORDS = {
+    changed: "changed",
+    resized: "changed size",
+    new: "new",
+    broken: "did not draw",
+    removed: "removed",
+    unstable: "unstable: differs between two pictures of the same code"
+};
+/**
+ * A name as a Markdown code span, whatever it holds: no line break, a fence longer than any run of backticks in it, and
+ * nothing a table reads as a new cell.
+ *
+ * @param text - the name.
+ */
+export const codeSpan = (text) => {
+    const flat = text.replace(/[\r\n\t|]+/g, " ").slice(0, MAX_NAME);
+    const longest = Math.max(0, ...(flat.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(longest + 1);
+    return `${fence} ${flat} ${fence}`;
+};
+/**
+ * Lines as a fenced block, whatever they hold: the fence is longer than any run of backticks in them.
+ *
+ * @param lines - the lines.
+ */
+const fenced = (lines) => {
+    const text = lines.join("\n");
+    const longest = Math.max(2, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+    const fence = "`".repeat(longest + 1);
+    return `${fence}text\n${text}\n${fence}`;
+};
+/** One state as a table's row. */
+const stateRow = (state) => `| ${codeSpan(state.storyId)} | ${codeSpan(state.view || "default")} | ${STATUS_WORDS[state.status]} | ${state.percent.toFixed(2)} % |`;
+/** The section listing the states the change touched. */
+const statesSection = (document) => {
+    const { states, same } = document;
+    if (states.length === 0)
+        return [`No picture differs: ${same} compared and the same.`];
+    const listed = states.slice(0, MAX_LISTED);
+    return [
+        `${states.length} differ, ${same} the same.`,
+        "",
+        "| Story | View | Compared with the base | Pixels |",
+        "|---|---|---|---|",
+        ...listed.map(stateRow),
+        ...(states.length > listed.length
+            ? ["", `And ${states.length - listed.length} more, in the pictures.`]
+            : [])
+    ];
+};
+/**
+ * The pull request's comment.
+ *
+ * @param document - the proof.
+ * @returns its Markdown, with `ARTIFACT_PLACEHOLDER` where the pictures' address goes.
+ */
+export const proofComment = (document) => {
+    const text = [
+        "### Forgebook proof",
+        "",
+        `Built in this run from ${codeSpan(document.base.slice(0, 12))} and ${codeSpan(document.head.slice(0, 12))}, with no stored picture. [Before and after pictures](${ARTIFACT_PLACEHOLDER}) (open \`index.html\` in the download).`,
+        "",
+        "#### States touched",
+        "",
+        ...statesSection(document),
+        "",
+        "#### Checked",
+        "",
+        fenced([`verdict: ${document.verdict}`, document.summary, ...document.checked]),
+        "",
+        "#### Not checked",
+        "",
+        document.notChecked.length === 0 ? "Nothing this run knows of." : fenced(document.notChecked),
+        ""
+    ].join("\n");
+    if (text.length <= MAX_COMMENT)
+        return text;
+    const cut = text.slice(0, MAX_COMMENT);
+    const whole = cut.slice(0, cut.lastIndexOf("\n"));
+    const fences = whole.match(/^`{3,}/gm) ?? [];
+    // an unclosed fence would swallow the ending
+    return `${whole}${fences.length % 2 === 1 ? `\n${fences.at(-1) ?? "```"}` : ""}${CUT_ENDING}`;
+};
+/** Text as HTML. */
+const escaped = (text) => text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+/** One picture of a state in the page, when it has it and it is one of the run's own: `pictures/…`. */
+const pictureCell = (label, file) => file === undefined || !/^pictures\/[^/]+\.png$/.test(file)
+    ? ""
+    : `<figure><figcaption>${label}</figcaption><a href="${escaped(file)}"><img loading="lazy" alt="${label}" src="${escaped(file)}"></a></figure>`;
+/** One state in the page. */
+const stateBlock = (state) => [
+    `<section><h2>${escaped(state.storyId)} <small>${escaped(state.view || "default")}: ${STATUS_WORDS[state.status]}, ${state.percent.toFixed(2)} %</small></h2><div>`,
+    pictureCell("Before", state.pictures.before),
+    pictureCell("After", state.pictures.after),
+    pictureCell("Marked", state.pictures.marked),
+    "</div></section>"
+].join("");
+/**
+ * The page a reviewer opens from the run's pictures: every state side by side, what was not checked above them.
+ *
+ * @param document - the proof.
+ */
+export const proofPage = (document) => [
+    '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Forgebook proof</title>',
+    // no script runs here, whatever a branch's run wrote in the names of its files
+    `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src 'self'; style-src 'unsafe-inline'">`,
+    '<meta name="viewport" content="width=device-width">',
+    "<style>:root{color-scheme:light dark;font:14px system-ui}section div{display:flex;flex-wrap:wrap;gap:12px}figure{margin:0;max-width:32%;min-width:240px}img{max-width:100%;border:1px solid #8888}small{font-weight:400}</style>",
+    `</head><body><h1>Forgebook proof</h1><p>${escaped(document.base.slice(0, 12))} to ${escaped(document.head.slice(0, 12))}: ${escaped(document.summary)}</p>`,
+    "<h2>Not checked</h2><ul>",
+    ...document.notChecked.map((each) => `<li>${escaped(each)}</li>`),
+    "</ul>",
+    ...document.states.map(stateBlock),
+    `<p>${document.same} more compared and the same.</p></body></html>\n`
+].join("");

package/dist/bin/forgebook/proofWorkflow.d.ts

@@ -0,0 +1,29 @@
+/** Where the workflow is written, from the repository's folder. */
+export declare const WORKFLOW_FILE = ".github/workflows/forgebook-proof.yml";
+/** What finds the comment again, so a new push replaces it. */
+export declare const COMMENT_MARKER = "<!-- forgebook-proof -->";
+/**
+ * The command that installs what a checkout locks; none when no lockfile says.
+ *
+ * @param root - the checkout's folder.
+ */
+export declare const installCommandOf: (root: string) => string | undefined;
+/**
+ * The comment, written from the proof by a job that trusts none of it, as jq reads it: `$files` are the edits GitHub names,
+ * `$run` the run's address, `$pictures` the pictures' address once checked. Backticks are written `\u0060` so this stays
+ * one template literal.
+ */
+export declare const COMMENT_FILTER: string;
+/**
+ * The job that posts, the same for every project.
+ *
+ * @param download - the action that fetches the proof, as `uses` writes it.
+ */
+export declare const commentJob: (download: string) => string;
+/**
+ * The workflow's text.
+ *
+ * @param root - the repository's folder, whose lockfile names the package manager.
+ * @param catalogue - the catalogue's folder, relative to it; empty when it is the repository's.
+ */
+export declare const proofWorkflow: (root: string, catalogue: string) => string;