forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/newStories.js

@@ -1,4 +1,18 @@
+import { propsMarkerLine, propsSignature } from "../../src/propsSignature.js";
 import { WORST_NUMBER, WORST_TEXT } from "../../src/worstCase.js";
+/** The meta's decorators that draw every story inside the wrappers, outermost first; empty with none. */
+const decoratorsCode = (wrappers) => {
+    if (wrappers.length === 0)
+        return "";
+    const open = wrappers.map((wrapper) => `<${wrapper.name}>`).join("");
+    const close = [...wrappers]
+        .reverse()
+        .map((wrapper) => `</${wrapper.name}>`)
+        .join("");
+    return `, decorators: [(Story) => ${open}<Story />${close}]`;
+};
+/** How many stories the uses add, the most telling first: past these, a file is long and says little more. */
+const MAX_USE_STORIES = 3;
 /** A prop's name in words, for a text's value (`helperText` → `Helper text`). */
 const words = (name) => {
     const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
@@ -45,12 +59,37 @@ const argsCode = (args) => {
     const line = `{ ${pairs.join(", ")} }`;
     return line.length <= LINE_WIDTH ? line : `{\n${pairs.map((pair) => `    ${pair}`).join(",\n")}\n  }`;
 };
-/** The required props' args, and the ones the type checker must point at, as comments. */
-const requiredArgs = (props) => {
+/** The value the uses give a prop most often, the first met on a tie; none when no use gives it. */
+const mostUsed = (uses, name) => {
+    const counts = new Map();
+    for (const use of uses) {
+        const value = use.args[name];
+        if (value !== undefined)
+            counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    let best;
+    for (const [value, count] of counts)
+        if (best === undefined || count > (counts.get(best) ?? 0))
+            best = value;
+    return best;
+};
+/**
+ * The main story's args, and the props the type checker must point at, as comments: each required prop with the value
+ * the application gives it most, else one from its kind; and each other prop at least half the uses give, so the story
+ * shows the component as most pages draw it.
+ */
+const mainArgs = (props, uses) => {
     const args = [];
     const todo = [];
-    for (const prop of props.filter((each) => each.isRequired)) {
-        const value = requiredCode(prop);
+    for (const prop of props) {
+        const used = mostUsed(uses, prop.name);
+        const given = uses.filter((use) => use.args[prop.name] !== undefined).length;
+        if (!prop.isRequired) {
+            if (used !== undefined && given * 2 >= uses.length)
+                args.push([prop.name, used]);
+            continue;
+        }
+        const value = used ?? requiredCode(prop);
         if (value === undefined)
             todo.push(`${prop.name}: ${prop.type}`);
         else
@@ -58,6 +97,31 @@ const requiredArgs = (props) => {
     }
     return { args, todo };
 };
+/**
+ * The args a use gives, only those the component declares, over the main story's required ones: an optional value the
+ * main story took from other uses is not this use's.
+ */
+const useArgs = (main, use, declared, required) => {
+    const given = Object.entries(use.args).filter(([name]) => declared.has(name));
+    return [...main.filter(([name]) => required.has(name) && use.args[name] === undefined), ...given];
+};
+/** A set of args as one key, whatever their order. */
+const argsKey = (args) => args
+    .map(([name, value]) => `${name}=${value}`)
+    .sort()
+    .join("\n");
+/** A use's story name, from the file that draws it (`src/pages/Checkout.tsx` → `InCheckout`), unique in the file. */
+const useStoryName = (file, taken) => {
+    const base = `In${pascal(file
+        .split("/")
+        .pop()
+        ?.replace(/\.[^.]+$/, "") ?? "") || "Use"}`;
+    let name = base;
+    for (let index = 2; taken.has(name); index += 1)
+        name = `${base}${index}`;
+    taken.add(name);
+    return name;
+};
 /**
  * The story file's text.
  *
@@ -68,7 +132,8 @@ export const newStories = (input) => {
     const { docs } = input;
     const name = docs.name;
     const type = `Story<typeof ${name}>`;
-    const { args, todo } = requiredArgs(docs.props);
+    const uses = input.uses ?? [];
+    const { args, todo } = mainArgs(docs.props, uses);
     const todoLine = todo.length === 0 ? [] : [`  // TODO: give ${todo.join(", ")}`];
     const story = (exportName, summary, storyArgs, parameters) => [
         `/** ${summary} */`,
@@ -81,6 +146,27 @@ export const newStories = (input) => {
     ];
     const choice = docs.props.find((prop) => prop.kind === "choice" && (prop.choices?.length ?? 0) > 1);
     const choiceStories = (choice?.choices ?? []).flatMap((value) => story(`${pascal(choice?.name ?? "")}${pascal(String(value))}`, `With ${choice?.name} ${JSON.stringify(value)}.`, [...args.filter(([prop]) => prop !== choice?.name), [choice?.name ?? "", JSON.stringify(value)]]));
+    // one story per distinct way the application draws it, the uses that give the most props first
+    const declared = new Set(docs.props.map((prop) => prop.name));
+    const required = new Set(docs.props.filter((prop) => prop.isRequired).map((prop) => prop.name));
+    const seen = new Set([argsKey(args)]);
+    const choiceNames = (choice?.choices ?? []).map((value) => `${pascal(choice?.name ?? "")}${pascal(String(value))}`);
+    const taken = new Set(["Default", "WorstCase", ...choiceNames]);
+    const declaredCount = (use) => Object.keys(use.args).filter((name) => declared.has(name)).length;
+    const useStories = [...uses]
+        .sort((left, right) => declaredCount(right) - declaredCount(left))
+        .flatMap((use) => {
+        const storyArgs = useArgs(args, use, declared, required);
+        const key = argsKey(storyArgs);
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return [{ use, storyArgs }];
+    })
+        .slice(0, MAX_USE_STORIES)
+        .flatMap(({ use, storyArgs }) => 
+    // the path goes in a comment as a quoted string, so a name with `*/` or a line break in it stays text
+    story(useStoryName(use.file, taken), `As ${JSON.stringify(use.file).replaceAll("*/", "*\\/")} draws it.`, storyArgs));
     const worst = docs.props.flatMap((prop) => {
         if (prop.kind === "text" || prop.canTakeText === true)
             return [[prop.name, JSON.stringify(WORST_TEXT)]];
@@ -89,22 +175,26 @@ export const newStories = (input) => {
         return [];
     });
     const worstArgs = [...args.filter(([prop]) => !worst.some(([each]) => each === prop)), ...worst];
-    return [
+    const parts = [
         "/**",
-        ` * The stories of ${name}, written by \`forgebook new\` from its props: complete them by hand.`,
+        uses.length === 0
+            ? ` * The stories of ${name}, written by \`forgebook new\` from its props: complete them by hand.`
+            : ` * The stories of ${name}, written by \`forgebook new\` from its props and from where the application draws it: complete them by hand.`,
         " *",
         " * @module",
         " */",
+        propsMarkerLine(propsSignature(docs.props)),
         `import type { Meta, Story } from ${JSON.stringify(input.typesModule)};`,
         "",
         input.importStatement,
+        ...(input.wrappers ?? []).map((wrapper) => wrapper.importStatement),
         "",
-        `export default { title: ${JSON.stringify(input.title)}, component: ${name} } satisfies Meta<typeof ${name}>;`,
+        `export default { title: ${JSON.stringify(input.title)}, component: ${name}${decoratorsCode(input.wrappers ?? [])} } satisfies Meta<typeof ${name}>;`,
         "",
         ...story("Default", `${name} as most pages use it.`, args, "{ main: true }"),
+        ...useStories,
         ...choiceStories,
         ...story("WorstCase", `Long texts and huge numbers, to see where ${name} breaks.`, worstArgs, '{ group: "worst-case" }')
-    ]
-        .join("\n")
-        .replace(/\n+$/, "\n");
+    ];
+    return `${parts.join("\n").trimEnd()}\n`;
 };

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

@@ -1,9 +1,14 @@
+import { type StoryWrapper } from "./newStories.ts";
 /** A component's first stories, ready to write. */
 export type NewStoriesFile = {
     /** Where they go: `<Component>.stories.tsx` beside the component, or the framework's own extension. */
     readonly file: string;
     /** The file's text. */
     readonly text: string;
+    /** How many places in the application draw the component, whose values the stories took. */
+    readonly uses: number;
+    /** Why the application's uses could not be read, when they could not: the stories are then written from props alone. */
+    readonly usesProblem?: string;
 };
 /**
  * A component's first stories.
@@ -11,7 +16,21 @@ export type NewStoriesFile = {
  * @param componentFile - the component's file, absolute.
  * @param exportName - the export to read; the file's only component when none.
  * @param framework - the framework the stories are written for (`react`); the catalogue's when none.
+ * @param wrappers - components every story is drawn inside (`--repair`); none by default.
  * @throws a `ScriptError` when the file is in no package, the framework cannot read it, or it exports no single
  *   component.
  */
-export declare const newStoriesFile: (componentFile: string, exportName: string | undefined, framework: string | undefined) => Promise<NewStoriesFile>;
+export declare const newStoriesFile: (componentFile: string, exportName: string | undefined, framework: string | undefined, wrappers?: readonly StoryWrapper[]) => Promise<NewStoriesFile>;
+/**
+ * What `new --json` answers: the file written, and how many of the application's uses it took values from.
+ *
+ * @param written - the stories written.
+ * @param shown - the file as the command names it.
+ */
+export declare const newStoriesDocument: (written: NewStoriesFile, shown: string) => Readonly<Record<string, unknown>>;
+/**
+ * The end of the line that says a file was written, when its values came from the application.
+ *
+ * @param uses - how many places draw the component.
+ */
+export declare const usesWords: (uses: number) => string;

package/dist/bin/forgebook/newStoriesFile.js

@@ -31,16 +31,31 @@ const catalogueFramework = async (packageDir) => {
     const config = findConfigFile(packageDir);
     return config === undefined ? "react" : (await loadConfigFile(config)).framework.name;
 };
+/**
+ * Where the application draws a component; why not, when the framework cannot say or reading failed: the stories are then
+ * written from its props alone rather than not at all.
+ */
+const callSites = (docsModule, file, name) => {
+    if (docsModule.extractCallSites === undefined)
+        return [];
+    try {
+        return docsModule.extractCallSites(file, name);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+};
 /**
  * A component's first stories.
  *
  * @param componentFile - the component's file, absolute.
  * @param exportName - the export to read; the file's only component when none.
  * @param framework - the framework the stories are written for (`react`); the catalogue's when none.
+ * @param wrappers - components every story is drawn inside (`--repair`); none by default.
  * @throws a `ScriptError` when the file is in no package, the framework cannot read it, or it exports no single
  *   component.
  */
-export const newStoriesFile = async (componentFile, exportName, framework) => {
+export const newStoriesFile = async (componentFile, exportName, framework, wrappers = []) => {
     const manifest = findUp("package.json", dirname(componentFile));
     if (manifest === undefined)
         throw new ScriptError(`${componentFile} is in no package`);
@@ -60,16 +75,40 @@ export const newStoriesFile = async (componentFile, exportName, framework) => {
     const importPath = `./${basename(componentFile).replace(/\.[cm]?[jt]sx?$/, "")}`;
     const shape = docsModule.storyFileShape?.(name, componentFile) ?? {
         extension: ".stories.tsx",
-        importStatement: `import { ${name} } from ${JSON.stringify(importPath)};`
+        importStatement: `import ${component.isDefaultExport === true ? name : `{ ${name} }`} from ${JSON.stringify(importPath)};`
     };
     const file = join(dirname(componentFile), `${name}${shape.extension}`);
     // the title is read by `/`, so the path is written with them on Windows too
     const title = autoTitle(await titleBase(packageDir, file), VITE_PATHS.relative(packageDir, file)) ?? name;
+    // where the application draws it gives values a reader recognises, where props alone give their names
+    const found = callSites(docsModule, componentFile, exportName ?? (component.isDefaultExport === true ? "default" : name));
+    const self = VITE_PATHS.normalize(componentFile);
+    const uses = typeof found === "string" ? [] : found.filter((site) => VITE_PATHS.normalize(site.file) !== self);
     const text = newStories({
         docs: component.docs,
         importStatement: shape.importStatement,
         title,
-        typesModule: docsModule.storyTypesModule ?? `@forgebook/${frameworkName}`
+        typesModule: docsModule.storyTypesModule ?? `@forgebook/${frameworkName}`,
+        wrappers,
+        uses: uses.map((site) => ({ file: VITE_PATHS.relative(packageDir, site.file), args: site.args }))
     });
-    return { file, text };
+    return { file, text, uses: uses.length, ...(typeof found === "string" ? { usesProblem: found } : {}) };
 };
+/**
+ * What `new --json` answers: the file written, and how many of the application's uses it took values from.
+ *
+ * @param written - the stories written.
+ * @param shown - the file as the command names it.
+ */
+export const newStoriesDocument = (written, shown) => ({
+    schema: 1,
+    file: VITE_PATHS.normalize(shown),
+    uses: written.uses,
+    ...(written.usesProblem === undefined ? {} : { usesProblem: written.usesProblem })
+});
+/**
+ * The end of the line that says a file was written, when its values came from the application.
+ *
+ * @param uses - how many places draw the component.
+ */
+export const usesWords = (uses) => uses === 0 ? "" : `, with the values of ${uses} place${uses === 1 ? "" : "s"} that draw it`;

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

@@ -13,7 +13,9 @@ export declare const unresolvedOf: (error: unknown) => string[];
  * Vite's `optimizeDeps` fails on an import it cannot resolve (stories that import a package not installed), where a
  * dev server only warns and pre-bundles the rest. So a failure that names such imports is tried once more with them
  * left out too, kept in a file every later server of the catalogue reads (`unresolvedFile`), which is what the server
- * would have done; any other failure is thrown, and the server does the work, as it always could. What an earlier
+ * would have done; any other failure is thrown, and the server does the work, as it always could. The first scan is a
+ * quick one, which leaves every script but the story files to the scanner (`ScanFindings.isQuick`); when it fails, a
+ * careful one reads every script past one that does not parse and names it. What an earlier
  * pre-bundling left out stays out unless it is forced: it is part of the pre-bundle's hash.
  *
  * @param config - the catalogue's configuration, read.

package/dist/bin/forgebook/prebundleRun.js

@@ -26,7 +26,9 @@ export const unresolvedOf = (error) => error instanceof Error
  * Vite's `optimizeDeps` fails on an import it cannot resolve (stories that import a package not installed), where a
  * dev server only warns and pre-bundles the rest. So a failure that names such imports is tried once more with them
  * left out too, kept in a file every later server of the catalogue reads (`unresolvedFile`), which is what the server
- * would have done; any other failure is thrown, and the server does the work, as it always could. What an earlier
+ * would have done; any other failure is thrown, and the server does the work, as it always could. The first scan is a
+ * quick one, which leaves every script but the story files to the scanner (`ScanFindings.isQuick`); when it fails, a
+ * careful one reads every script past one that does not parse and names it. What an earlier
  * pre-bundling left out stays out unless it is forced: it is part of the pre-bundle's hash.
  *
  * @param config - the catalogue's configuration, read.
@@ -36,14 +38,32 @@ export const prebundle = async (config, isForced) => {
     const { optimizeDeps, resolveConfig } = await import("vite");
     if (isForced)
         rmSync(unresolvedFile(config.dir), { force: true });
+    const optimize = async (isQuick) => {
+        await optimizeDeps(await resolveConfig(await catalogueVite(config, {}, "serve", false, isQuick), "serve"), isForced);
+    };
+    // what a failure names as unresolved is left out from then on; whether it named any
+    const leavesOut = (error) => {
+        const unresolved = unresolvedOf(error);
+        if (unresolved.length > 0)
+            keepUnresolved(config.dir, [...new Set([...unresolvedImports(config.dir), ...unresolved])]);
+        return unresolved.length > 0;
+    };
+    // once more without what a failure names as unresolved, as the server would have left it out
+    const attempt = async (isQuick) => {
+        try {
+            await optimize(isQuick);
+        }
+        catch (error) {
+            if (!leavesOut(error))
+                throw error;
+            await optimize(isQuick);
+        }
+    };
     try {
-        await optimizeDeps(await resolveConfig(await catalogueVite(config, {}), "serve"), isForced);
+        await attempt(true);
     }
-    catch (error) {
-        const unresolved = unresolvedOf(error);
-        if (unresolved.length === 0)
-            throw error;
-        keepUnresolved(config.dir, [...new Set([...unresolvedImports(config.dir), ...unresolved])]);
-        await optimizeDeps(await resolveConfig(await catalogueVite(config, {}), "serve"), isForced);
+    catch {
+        // a script that does not parse stops the quick scan: the careful one reads past it and names it
+        await attempt(false);
     }
 };

package/dist/bin/forgebook/proofCommand.d.mts

@@ -0,0 +1,15 @@
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * Stories named after a changed file first, then the rest, each in the catalogue's order.
+ *
+ * @param ids - the stories' ids.
+ * @param files - the changed files.
+ */
+export declare const orderedByName: (ids: readonly string[], files: readonly string[]) => readonly string[];
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const proofCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/proofCommand.mjs

@@ -0,0 +1,212 @@
+/**
+ * `forgebook proof`: a pull request's states against where it started, drawn in one run, for a comment made by CI.
+ *
+ * @remarks
+ * It exits zero once it has something to say, whatever a picture shows, since a picture that changed is for a person to
+ * judge. `--fail-on-verdict` holds it to `verify`'s verdict, so the workflow's check is not green on a failing one.
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { isChangedStoriesDocument, isStoriesDocument } from "../../src/vite/agentApi.js";
+import { gitOutput } from "../../src/vite/gitChange.js";
+import { catalogueClient } from "./agentClient.js";
+import { COMMAND, configWithStoriesOf } from "./catalogueCommands.js";
+import { runProof, writeProofFiles } from "./proofRun.js";
+import { proofComment, proofPage } from "./proofText.js";
+import { proofWorkflow, WORKFLOW_FILE } from "./proofWorkflow.js";
+import { runStoriesCheck } from "./storyCheckRun.js";
+import { runVerify } from "./verifyRun.js";
+/** The most stories pictured unless told otherwise: a change to a shared sheet reaches them all. */
+const MAX_STORIES = "30";
+/** Writes the workflow into the repository the catalogue is in. */
+const writeWorkflow = async (dir) => {
+    const root = (await gitOutput(dir, "rev-parse", "--show-toplevel")).trim();
+    const file = join(root, WORKFLOW_FILE);
+    if (existsSync(file))
+        throw new ScriptError(`${WORKFLOW_FILE} is already there: delete it to write it again`);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, proofWorkflow(root, relative(root, dir).replaceAll("\\", "/")));
+};
+/** The catalogue's stories, or why it gave none. */
+const storiesOf = async (client) => {
+    const answer = await client.ask("stories", new URLSearchParams());
+    return isStoriesDocument(answer.body)
+        ? answer.body
+        : `The catalogue answered ${answer.status} for its stories`;
+};
+/**
+ * Every story a change reaches, or why the catalogue gave none. A sheet every component imports reaches every story, and
+ * only the first are pictured, so those named after a changed file come first: they are the ones that show it.
+ */
+const changedIdsOf = async (client, since) => {
+    const answer = await client.ask("changed", new URLSearchParams({ since }));
+    if (!isChangedStoriesDocument(answer.body))
+        return `The catalogue answered ${answer.status} for what the change reaches`;
+    const ids = answer.body.stories.map((story) => story.id);
+    return orderedByName(ids, answer.body.files);
+};
+/**
+ * Stories named after a changed file first, then the rest, each in the catalogue's order.
+ *
+ * @param ids - the stories' ids.
+ * @param files - the changed files.
+ */
+export const orderedByName = (ids, files) => {
+    const plain = (text) => text.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+    const names = files
+        .flatMap((file) => {
+        const parts = file.split("/");
+        const stem = (parts.at(-1) ?? "").split(".")[0] ?? "";
+        return [stem === "index" ? "" : stem, parts.at(-2) ?? ""];
+    })
+        .map(plain)
+        .filter((name) => name.length > 2);
+    const isNamed = (id) => names.some((name) => plain(id).includes(name));
+    return [...ids.filter(isNamed), ...ids.filter((id) => !isNamed(id))];
+};
+/** Stops with a failure when the verdict is one a pipeline stops on and it was asked to. */
+const stopOnVerdict = (document, isAsked) => {
+    if (isAsked && (document.verdict === "failed" || document.verdict === "not-verified"))
+        throw new ScriptError(document.summary, { exitCode: EXIT.failure, isReported: true });
+};
+/** Writes a proof's files, and gives its comment. */
+const writtenProof = (out, document) => {
+    const comment = proofComment(document);
+    writeProofFiles(out, {
+        "proof.json": formatJson(document),
+        "comment.md": comment,
+        "index.html": proofPage(document)
+    });
+    return comment;
+};
+/** A count an option gives. */
+const wholeCount = (text) => {
+    const count = Number(text);
+    if (!Number.isInteger(count) || count < 1)
+        throw new ScriptError("--max-stories takes a whole number from 1");
+    return count;
+};
+/** An option's folder, absolute, when it gives one. */
+const resolved = (folder) => folder === undefined ? undefined : resolve(folder);
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const proofCommands = (forgebook) => ({
+    proof: forgebook.command({
+        summary: "Compare a change's states with where it started, both drawn in this run with nothing stored, and write the pull request's comment and pictures. A changed picture never fails it; --fail-on-verdict stops on verify's verdict.",
+        json: true,
+        options: {
+            base: {
+                type: "string",
+                valueName: "ref",
+                description: "The ref to compare with, from where the branch left it; required unless writing the workflow."
+            },
+            out: {
+                type: "string",
+                default: "forgebook-proof",
+                valueName: "folder",
+                description: "The folder for comment.md, proof.json, index.html and the pictures."
+            },
+            work: {
+                type: "string",
+                valueName: "folder",
+                description: "Where the base's checkout goes, while it runs; the system's temporary folder by default."
+            },
+            install: {
+                type: "string",
+                valueName: "command",
+                description: "What installs the base's checkout; the one its lockfile names by default."
+            },
+            all: {
+                type: "boolean",
+                description: "Every listed story, not only those the change reaches. With --base HEAD, shows whether two builds of one commit draw the same."
+            },
+            quick: { type: "boolean", description: "Only the default view of each story; the proof says so." },
+            "fail-on-verdict": {
+                type: "boolean",
+                description: "Exit non-zero, the proof written, when verify's verdict is not-verified or failed."
+            },
+            "max-stories": {
+                type: "string",
+                default: MAX_STORIES,
+                valueName: "count",
+                description: "The most stories pictured; the proof names those past it as not checked."
+            },
+            "write-workflow": {
+                type: "boolean",
+                description: `Write ${WORKFLOW_FILE}, for this repository's package manager and this catalogue, and stop.`
+            },
+            url: {
+                type: "string",
+                env: "FORGEBOOK_URL",
+                valueName: "address",
+                description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+            }
+        },
+        examples: [
+            { command: `${COMMAND} proof --write-workflow`, description: "Set it up on a repository." },
+            {
+                command: `${COMMAND} proof --base origin/main --fail-on-verdict`,
+                description: "What the workflow runs."
+            },
+            {
+                command: `${COMMAND} proof --base HEAD --all`,
+                description: "Whether this project's pictures hold still between two builds."
+            }
+        ],
+        run: async ({ options, io, log, isJson }) => {
+            const config = await configWithStoriesOf(options.config);
+            if (options["write-workflow"] === true) {
+                await writeWorkflow(config.dir);
+                log.success(`${WORKFLOW_FILE} written`);
+                return;
+            }
+            const { base } = options;
+            if (base === undefined)
+                throw new ScriptError("Name the ref to compare with: --base origin/main");
+            const maxStories = wholeCount(options["max-stories"]);
+            const out = resolve(options.out);
+            const isQuick = options.quick === true;
+            const client = await catalogueClient(config, options.url);
+            try {
+                const document = await runProof({
+                    config,
+                    configFile: options.config,
+                    say: (text) => log.info(text),
+                    verify: (since) => runVerify({
+                        dir: config.dir,
+                        ask: client.ask,
+                        check: (input) => runStoriesCheck(config, options.url, input)
+                    }, { since, isQuick }),
+                    stories: () => storiesOf(client),
+                    changedIds: (since) => changedIdsOf(client, since)
+                }, {
+                    base,
+                    out,
+                    work: resolved(options.work),
+                    install: options.install,
+                    isAll: options.all === true,
+                    isQuick,
+                    maxStories
+                });
+                if (typeof document === "string")
+                    throw new ScriptError(document);
+                const comment = writtenProof(out, document);
+                io.stdout.write(isJson ? formatJson(document) : comment);
+                for (const each of isJson ? document.notChecked : [])
+                    log.warn(each);
+                stopOnVerdict(document, options["fail-on-verdict"] === true);
+            }
+            finally {
+                await client.close();
+            }
+        }
+    })
+});

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

@@ -0,0 +1,63 @@
+import type { ProofDocument, StoriesDocument, VerifyDocument } from "../../src/vite/agent.types.ts";
+import { type ResolvedConfig } from "../../src/vite/configFile.ts";
+/** The files that make the proof, not what it shows: an edit to them is read by a person, whatever the pictures say. */
+export declare const MAKES_THE_PROOF: RegExp;
+/** What `runProof` is asked. */
+export type ProofInput = {
+    /** The ref the change is compared with. */
+    readonly base: string;
+    /** The folder the proof is written in, absolute. */
+    readonly out: string;
+    /** Where the base's checkout goes, absolute; the system's temporary folder by default. */
+    readonly work: string | undefined;
+    /** The command that installs the base's checkout; from its lockfile by default. */
+    readonly install: string | undefined;
+    /** Every story, not only those the change reaches: what shows whether two builds of one commit draw the same. */
+    readonly isAll: boolean;
+    /** Only the default view of each story. */
+    readonly isQuick: boolean;
+    /** The most stories pictured; those past it are named as not checked. */
+    readonly maxStories: number;
+};
+/** What `runProof` reaches the change's catalogue through. */
+export type ProofReach = {
+    /** The catalogue's configuration. */
+    readonly config: ResolvedConfig;
+    /** The configuration file named on the command line: each side's server is told the same. */
+    readonly configFile: string | undefined;
+    /** Answers whether the change is verified. */
+    readonly verify: (since: string) => Promise<VerifyDocument | string>;
+    /** Every story the catalogue lists. */
+    readonly stories: () => Promise<StoriesDocument | string>;
+    /** Every story a change reaches, by id: `verify` lists only the first of them. */
+    readonly changedIds: (since: string) => Promise<readonly string[] | string>;
+    /** Writes progress for a person. */
+    readonly say: (text: string) => void;
+};
+/**
+ * The listed stories' ids in a catalogue's answer.
+ *
+ * @param document - the answer.
+ */
+export declare const listedIds: (document: StoriesDocument) => readonly string[];
+/**
+ * Every story's id in a catalogue's answer, those listed nowhere among them.
+ *
+ * @param document - the answer.
+ */
+export declare const allIds: (document: StoriesDocument) => readonly string[];
+/**
+ * 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 declare const runProof: (reach: ProofReach, input: ProofInput) => Promise<ProofDocument | string>;
+/**
+ * Writes a proof's files.
+ *
+ * @param out - the folder.
+ * @param files - each file's name and text.
+ */
+export declare const writeProofFiles: (out: string, files: Readonly<Record<string, string>>) => void;