forgebook 0.3.3 → 0.4.0

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

@@ -0,0 +1,63 @@
+/**
+ * What `forgebook verify` and its MCP tool run: asks the catalogue what the change is and adds, runs the stories that
+ * reach it on one browser, and concludes (`verifyVerdict.ts`).
+ *
+ * @remarks
+ * A check that cannot run does not stop the answer: the coverage and the code check still say what they found, and the
+ * stories that did not run cover nothing, so a project with no browser is told it is not verified rather than given only
+ * an error. Tokens files it cannot read leave the code unchecked, which the verdict says. Only a commit that names nothing
+ * ends it, since then there is no change to speak of.
+ *
+ * @module
+ */
+import type { StoryCheckReport } from "../../src/storyCheck.ts";
+import type { VerifyDocument } from "../../src/vite/agent.types.ts";
+import type { Ask } from "./mcpToolParts.ts";
+import type { StoriesCheckInput } from "./storyCheckRun.ts";
+import type { BaseRun } from "./verifyBase.ts";
+/** What a verification reaches the catalogue through. */
+export type VerifyReach = {
+    /** The catalogue's folder, in the repository. */
+    readonly dir: string;
+    /** Asks the catalogue. */
+    readonly ask: Ask;
+    /** Runs the checks on stories: the report, or why it could not run. */
+    readonly check: (input: StoriesCheckInput) => Promise<StoryCheckReport | string>;
+    /** Runs stories on the base commit, for the problems that were there before; none to count every problem. */
+    readonly checkBase?: (base: string, input: StoriesCheckInput) => Promise<BaseRun>;
+};
+/** What a verification is asked. */
+export type VerifyInput = {
+    /** The commit to compare with; the default branch when none. */
+    readonly since: string | undefined;
+    /** Only the default view of each story. */
+    readonly isQuick: boolean;
+    /** Count every problem the stories have, not only those the change brought (`--all-problems`). */
+    readonly isAllProblems?: boolean;
+    /**
+     * What is wrong with the catalogue's configuration that leaves the answer not verified, said with it: a story pattern
+     * that matches nothing. None by default.
+     */
+    readonly configProblems?: readonly string[];
+};
+/**
+ * The message of an answer that is an error.
+ *
+ * @param body - the answer's body.
+ * @param status - its status.
+ */
+export declare const errorOf: (body: unknown, status: number) => string;
+/**
+ * Whether an answer means the change is not done: what `verify` exits non-zero on.
+ *
+ * @param document - the answer.
+ */
+export declare const isVerifyFailure: (document: VerifyDocument) => boolean;
+/**
+ * Answers whether a change is verified.
+ *
+ * @param reach - what it reaches the catalogue through.
+ * @param input - what to compare with, and how much to run.
+ * @returns the answer, or why there can be none.
+ */
+export declare const runVerify: (reach: VerifyReach, { since, isQuick, isAllProblems, configProblems }: VerifyInput) => Promise<VerifyDocument | string>;

package/dist/bin/forgebook/verifyRun.js

@@ -0,0 +1,108 @@
+import { isChangedStoriesDocument, isCheckedCodeDocument } from "../../src/vite/agentApi.js";
+import { isVisibilityDocument } from "../../src/vite/agentVisibility.js";
+import { branchStart, changeBase, noBaseReason } from "../../src/vite/gitChange.js";
+import { verifyDocument } from "./verifyVerdict.js";
+/** What a catalogue answers when it runs an older version than this command. */
+const UNEXPECTED_SHAPE = "The catalogue's answer has an unexpected shape: restart forgebook dev if it runs another version";
+/**
+ * The message of an answer that is an error.
+ *
+ * @param body - the answer's body.
+ * @param status - its status.
+ */
+export const errorOf = (body, status) => typeof body === "object" && body !== null && "error" in body && typeof body.error === "string"
+    ? body.error
+    : `The catalogue answered ${status}`;
+/**
+ * Whether an answer means the change is not done: what `verify` exits non-zero on.
+ *
+ * @param document - the answer.
+ */
+export const isVerifyFailure = (document) => document.verdict === "failed" || document.verdict === "not-verified";
+/** The stories with a problem in a report, each once. */
+const failingIds = (report) => [
+    ...new Set(report.results.filter((result) => result.problems.length > 0).map((result) => result.storyId))
+];
+/** Runs the stories' check, a thrown failure (a browser that will not start) being a reason as any other. */
+const checked = async (reach, input) => {
+    try {
+        return await reach.check(input);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+};
+/**
+ * The stories that found something run again on the base: a change with none needs no base.
+ *
+ * @param reach - what it reaches the catalogue through.
+ * @param base - the base commit.
+ * @param run - the stories' check on the change.
+ * @param isAllVariants - whether every variant runs, as on the change.
+ */
+const baseRunOf = async (reach, base, run, isAllVariants) => {
+    const failing = typeof run === "object" ? failingIds(run) : [];
+    return failing.length === 0 || reach.checkBase === undefined
+        ? undefined
+        : reach.checkBase(base, { ids: failing, isAllVariants });
+};
+/**
+ * Answers whether a change is verified.
+ *
+ * @param reach - what it reaches the catalogue through.
+ * @param input - what to compare with, and how much to run.
+ * @returns the answer, or why there can be none.
+ */
+export const runVerify = async (reach, { since, isQuick, isAllProblems = false, configProblems = [] }) => {
+    const named = since ?? (await branchStart(reach.dir));
+    const base = await changeBase(reach.dir, named);
+    if (base === undefined)
+        return noBaseReason(reach.dir, named);
+    const params = new URLSearchParams({ since: named });
+    const code = await reach.ask("check-code", params);
+    if (code.status === 200 && !isCheckedCodeDocument(code.body))
+        return UNEXPECTED_SHAPE;
+    const changed = await reach.ask("changed", params);
+    if (changed.status !== 200)
+        return errorOf(changed.body, changed.status);
+    if (!isChangedStoriesDocument(changed.body))
+        return UNEXPECTED_SHAPE;
+    const seen = await reach.ask("visibility", params);
+    if (seen.status === 200 && !isVisibilityDocument(seen.body))
+        return UNEXPECTED_SHAPE;
+    const ids = changed.body.stories.map((story) => story.id);
+    const run = ids.length === 0 ? undefined : await checked(reach, { ids, isAllVariants: !isQuick });
+    const baseRun = isAllProblems ? undefined : await baseRunOf(reach, base, run, !isQuick);
+    // tokens that cannot be read leave the code unchecked, which the verdict says, and do not stop the rest
+    const codeBody = isCheckedCodeDocument(code.body)
+        ? code.body
+        : {
+            schema: 1,
+            since: named,
+            checked: [],
+            skipped: [`colours, sizes and turned-off checks not checked: ${errorOf(code.body, code.status)}`],
+            problems: []
+        };
+    return verifyDocument({
+        since: named,
+        base,
+        changed: changed.body,
+        code: codeBody,
+        // what cannot be told of agents does not stop the rest, and the verdict says it
+        visibility: isVisibilityDocument(seen.body)
+            ? seen.body
+            : {
+                schema: 1,
+                packages: [],
+                checked: 0,
+                unseen: [],
+                skipped: [`what agents see not checked: ${errorOf(seen.body, seen.status)}`]
+            },
+        report: typeof run === "object" ? run : undefined,
+        notRun: typeof run === "string" ? run : undefined,
+        isQuick,
+        isSinceNamed: since !== undefined,
+        configProblems,
+        ...(baseRun === undefined ? {} : { baseRun: { base, run: baseRun } })
+    });
+};

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

@@ -0,0 +1,40 @@
+import type { StoryCheckReport } from "../../src/storyCheck.ts";
+import type { ChangedStoriesDocument, CheckedCodeDocument, VerifyDocument, VisibilityDocument } from "../../src/vite/agent.types.ts";
+import { type BaseRun } from "./verifyBase.ts";
+/** What `verifyDocument` reads. */
+export type VerifyFindings = {
+    /** What the change is measured from, as named. */
+    readonly since: string;
+    /** The commit that is. */
+    readonly base: string;
+    /** The catalogue's answer on the change. */
+    readonly changed: ChangedStoriesDocument;
+    /** The catalogue's answer on what the change adds. */
+    readonly code: CheckedCodeDocument;
+    /** The catalogue's answer on the published components the change touches. */
+    readonly visibility: VisibilityDocument;
+    /** The stories' report; none when none ran. */
+    readonly report: StoryCheckReport | undefined;
+    /** Why they did not run, when they were to. */
+    readonly notRun: string | undefined;
+    /** Only the default view was asked for. */
+    readonly isQuick: boolean;
+    /** Whether a commit was named: with none, an empty change may only mean the work is where this cannot look. */
+    readonly isSinceNamed: boolean;
+    /** The failing stories run again on the base, when they were: what the base had too is not the change's. */
+    readonly baseRun?: {
+        readonly base: string;
+        readonly run: BaseRun;
+    };
+    /**
+     * What is wrong with the catalogue's configuration: the answer is not verified when the change has a UI file, whatever
+     * else it found, and only says it when the change has none.
+     */
+    readonly configProblems?: readonly string[];
+};
+/**
+ * The answer to whether a change is verified.
+ *
+ * @param input - what was found.
+ */
+export declare const verifyDocument: (input: VerifyFindings) => VerifyDocument;

package/dist/bin/forgebook/verifyVerdict.js

@@ -0,0 +1,297 @@
+/**
+ * What `verify` concludes from the change, its code check and its stories' run: the document, and the one line that says
+ * it.
+ *
+ * @remarks
+ * Pure, so the rule the whole command exists for can be read and tested apart: a change is verified only if every changed
+ * UI file reached a story that actually ran, and what was not checked is never counted as passed. A story that was
+ * listed and did not run covers nothing, so the coverage is read from the results and not from the graph, and a story
+ * whose frame gave up on what it loads did not run: no check saw it in its final state. A changed file
+ * that no one sees does not fail, whatever it reaches; what `check-code` finds in it (a turned-off check, a deleted test)
+ * is said as a note. A published component the change touches that an agent cannot find or read (`unseen`,
+ * `agentVisibility.ts`) leaves it not verified: what is checked but cannot be found gets rebuilt. An empty change passes only against a commit someone named: with none, the work may simply be
+ * committed where this cannot look (a shallow clone, a default branch it does not know).
+ *
+ * @module
+ */
+import { shellWord } from "../../src/shellWord.js";
+import { splitByBase } from "./verifyBase.js";
+/** A sheet, whose fix is not a story of its own. */
+const SHEET_FILE = /\.(?:css|scss|sass|less)$/;
+/** A story file, whose stories have to load. */
+const STORY_FILE = /\.stories\.[^/]+$/;
+/** A template, which has no props to write a story from. */
+const TEMPLATE_FILE = /\.html$/;
+/** How many stories an answer lists. */
+const STORIES_LISTED = 20;
+/** What to do about a file no story reaches. */
+const fixOf = (file) => {
+    if (STORY_FILE.test(file.file))
+        return `npx forgebook stories --json says why it does not load; add it to the catalogue's stories if it is not listed`;
+    if (SHEET_FILE.test(file.file) || TEMPLATE_FILE.test(file.file))
+        return "use it from a component that has stories, or import the sheet in forgebook.preview.ts";
+    return `npx forgebook new ${shellWord(file.path)}`;
+};
+/** A UI file, by the stories that ran. */
+const verifiedFile = (file, ran, notRun) => {
+    const stories = file.stories.filter((id) => ran.has(id)).length;
+    if (stories > 0)
+        return { file: file.file, coverage: file.coverage, stories };
+    return {
+        file: file.file,
+        coverage: "none",
+        stories: 0,
+        ...(file.stories.length > 0
+            ? {
+                reason: `its stories did not run: ${notRun ?? "the check left them out, or never saw them in their final state"}`
+            }
+            : { reason: "no story reaches it.", fix: fixOf(file) })
+    };
+};
+/** A count with its noun. */
+const counted = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+/** What a line's first part says of the UI files. */
+const coverageWords = (files) => {
+    const covered = files.filter((each) => each.coverage !== "none").length;
+    const through = files.filter((each) => each.coverage === "through").length;
+    const parts = through === 0 ? "" : ` (${through} through another component's)`;
+    return `${counted(files.length, "changed UI file")}, ${covered} with stories${parts}`;
+};
+/** The verdict, the worst that holds. */
+const verdictOf = (files, problems, skipped, catalogueProblems, isBlind, notVerified) => {
+    if (problems > 0)
+        return "failed";
+    if (notVerified > 0 || files.some((each) => each.coverage === "none"))
+        return "not-verified";
+    if (isBlind || catalogueProblems.length > 0)
+        return "not-verified";
+    if (files.length === 0)
+        return "nothing-to-verify";
+    return skipped.length > 0 ? "partly-verified" : "verified";
+};
+/** A changed file the stories do reach, whose values were compared with nothing: outside the catalogue's folder. */
+const notComparedLine = ({ changed, code }) => {
+    const compared = new Set(code.notCompared);
+    return changed.uiFiles.some((file) => compared.has(file.file))
+        ? ["colours and sizes of a file outside this catalogue's folder not checked"]
+        : [];
+};
+/** What was not checked, in the words a person reads. */
+const skippedOf = (input, notRun) => {
+    const { changed, code, report, isQuick, isSinceNamed, since } = input;
+    const hasUi = changed.uiFiles.length > 0;
+    const hasStories = changed.stories.length > 0;
+    const notAwaited = new Set((report?.results ?? []).filter((each) => each.isNotAwaited === true).map((each) => each.storyId));
+    return [
+        // a story may mean it, and a preview that sets it for all of them turns the wait off: either way, said
+        ...(notAwaited.size === 0
+            ? []
+            : [
+                `${notAwaited.size === 1 ? "1 story" : `${notAwaited.size} stories`} checked without waiting for what it loads: parameters.suspense.expected`
+            ]),
+        // nothing a token names was touched when no UI file changed, so its absence said nothing about the change
+        ...(hasUi ? code.skipped : []),
+        ...notComparedLine(input),
+        ...(report?.a11y === "off" && hasStories
+            ? ["accessibility not checked: the catalogue sets a11y: false"]
+            : []),
+        ...(isQuick && hasStories ? ["only the default view checked: --quick"] : []),
+        ...(!hasUi && hasStories && notRun !== undefined ? [`stories not run: ${notRun}`] : []),
+        ...(!hasUi ? changed.problems.filter((problem) => !changed.unread?.includes(problem)) : []),
+        // committed work on a branch would not show: compared with the commit itself, only what is not committed does
+        ...(!isSinceNamed && since === "HEAD" && changed.files.length > 0
+            ? ["committed work not compared: no default branch found here, give --since"]
+            : []),
+        ...(changed.outside.length > 0
+            ? [
+                `${counted(changed.outside.length, "UI file")} of another catalogue not checked: ${changed.outside.join(", ")}`
+            ]
+            : [])
+    ];
+};
+/** A base run that found no story of the change's: every problem is the change's, as with a base that has none. */
+const NO_STORY = /^No story or component /;
+/**
+ * The report on the change with the problems the base had too taken out, and those problems; the report as it is when
+ * no base ran or it could not, with why.
+ */
+const comparedWithBase = (report, baseRun) => {
+    if (report === undefined || baseRun === undefined)
+        return { report, existing: [], isCompared: false, unseen: 0 };
+    const { run } = baseRun;
+    if (typeof run === "string" && !NO_STORY.test(run))
+        return {
+            report,
+            existing: [],
+            isCompared: false,
+            unseen: 0,
+            notCompared: `not compared with ${baseRun.base.slice(0, 12)}: ${run}`
+        };
+    if (typeof run === "string")
+        return { report, existing: [], isCompared: true, unseen: 0 };
+    return { ...splitByBase(report, run.report, [run.root, run.folder]), isCompared: true };
+};
+/** What a line says of a change with no UI file. */
+const noUiWords = ({ files, ran, problems, notVerified, unseen }) => {
+    const stories = ran === 0 ? "" : `, ${ran} checks of the stories they reach`;
+    const found = [
+        ...(problems === 0 ? [] : [counted(problems, "problem")]),
+        ...(notVerified.length === 0 ? [] : [`${notVerified.length} not verified`]),
+        ...(unseen.length === 0 ? [] : [`${counted(unseen.length, "published component")} agents cannot see`])
+    ].join(", ");
+    return `No changed UI file (${counted(files.length, "other file")}${stories})${found === "" ? "" : `: ${found}`}`;
+};
+/** What a line says after the coverage. */
+const outcomeWords = ({ verdict, uiFiles, problems, variants, ran, notVerified: unseen, outdated, unseen: cannotBeSeen }, catalogueProblems) => {
+    const notVerified = unseen.length > 0 ||
+        cannotBeSeen.length > 0 ||
+        uiFiles.some((each) => each.coverage === "none") ||
+        catalogueProblems.length > 0;
+    const where = variants === "all" ? "in every variant" : "in the default view";
+    return [
+        ...(notVerified ? ["not verified"] : []),
+        ...(unseen.length > 0 ? [`${unseen.length} not seen in its final state: the frame gave up`] : []),
+        ...(cannotBeSeen.length > 0
+            ? [`${counted(cannotBeSeen.length, "published component")} agents cannot see`]
+            : []),
+        ...(problems > 0 ? [counted(problems, "problem")] : []),
+        ...(outdated === undefined ? [] : [`${counted(outdated.length, "story file")} written for other props`]),
+        ...(verdict === "verified" || verdict === "partly-verified"
+            ? [`verified ${where} (${counted(ran, "check")})`]
+            : [])
+    ].join(", ");
+};
+/**
+ * The verdict's line.
+ *
+ * @param document - the document so far.
+ * @param catalogueProblems - what the catalogue could not read.
+ */
+const summaryOf = (document, catalogueProblems) => {
+    const { verdict, uiFiles, files, since, code, skipped } = document;
+    const isBlind = files.length === 0 && catalogueProblems.length === 0;
+    const notes = code.notes.length === 0 ? [] : [`${counted(code.notes.length, "note")} from check-code`];
+    const said = [...skipped, ...notes];
+    const tail = said.length === 0 ? "" : `; ${said.join("; ")}`;
+    if (files.length === 0) {
+        const notVerified = isBlind
+            ? "not verified. If your work is committed, give --since <ref>"
+            : "not verified";
+        const ending = verdict === "not-verified" ? notVerified : "nothing to verify";
+        return `Nothing changed since ${since}: ${ending}${tail}`;
+    }
+    if (uiFiles.length === 0) {
+        const ending = catalogueProblems.length === 0 ? "" : ": not verified";
+        return `${noUiWords(document)}${ending}${tail}`;
+    }
+    return `${coverageWords(uiFiles)}: ${outcomeWords(document, catalogueProblems)}${tail}`;
+};
+/**
+ * The pairs that found a problem, each with the links that open its story.
+ *
+ * @param results - the pairs that ran.
+ * @param links - the links of the change's stories, by id.
+ */
+const failuresOf = (results, links) => results
+    .filter((result) => result.problems.length > 0)
+    .map(({ storyId, view, problems: found }) => {
+    const storyLinks = links.get(storyId);
+    return { storyId, view, problems: found, ...(storyLinks === undefined ? {} : { links: storyLinks }) };
+});
+/** What the comparison with the base leaves unchecked: a base that could not run, stories it never saw. */
+const baseSkips = (compared) => [
+    ...(compared.notCompared === undefined
+        ? []
+        : [`${compared.notCompared}; every problem the stories have is counted`]),
+    ...(compared.unseen === 0
+        ? []
+        : [
+            `${counted(compared.unseen, "story")} not seen on the base in its final state: every problem of it counted`
+        ])
+];
+/**
+ * The answer to whether a change is verified.
+ *
+ * @param input - what was found.
+ */
+export const verifyDocument = (input) => {
+    const { since, base, changed, code, visibility, notRun, isQuick, isSinceNamed } = input;
+    const compared = comparedWithBase(input.report, input.baseRun);
+    const { report } = compared;
+    const results = report?.results ?? [];
+    // a story not seen in a view is left out of what ran there; seen in another it still covers its file, and the verdict
+    // says not verified from `notVerified` either way
+    const seenResults = results.filter((result) => result.notVerified === undefined);
+    const ran = new Set(seenResults.map((result) => result.storyId));
+    const uiFiles = changed.uiFiles.map((file) => verifiedFile(file, ran, notRun));
+    const links = new Map(changed.stories.map((story) => [story.id, story.links]));
+    const failures = failuresOf(results, links);
+    const notVerified = results.flatMap(({ storyId, view, notVerified: reason }) => {
+        if (reason === undefined)
+            return [];
+        const storyLinks = links.get(storyId);
+        return [
+            { storyId, view, notVerified: reason, ...(storyLinks === undefined ? {} : { links: storyLinks }) }
+        ];
+    });
+    // a change no one sees does not fail; what the code check found in it is still said
+    const seen = new Set(changed.uiFiles.map((file) => file.file));
+    const codeProblems = code.problems.filter((problem) => seen.has(problem.file));
+    const outside = new Set(changed.outside);
+    const notes = code.problems.filter((problem) => !seen.has(problem.file) && !outside.has(problem.file));
+    // stories written for props the component no longer has pass a check they no longer mean: each is a problem
+    const outdated = changed.outdated ?? [];
+    const problems = failures.reduce((sum, each) => sum + each.problems.length, codeProblems.length + outdated.length);
+    const existingProblems = compared.existing.reduce((sum, each) => sum + each.problems.length, 0);
+    const hasUiFiles = changed.uiFiles.length > 0;
+    // a change with no UI file is not the gate's business: a configuration problem, a story pattern that matches nothing
+    // in a catalogue with no story yet, is said and does not stop it; a story file the pattern misses is a UI file itself
+    const configProblems = input.configProblems ?? [];
+    const skipped = [
+        ...skippedOf(input, notRun),
+        ...baseSkips(compared),
+        ...(hasUiFiles ? [] : configProblems)
+    ];
+    // a story file that cannot be read may be the change, whatever else changed
+    const catalogueProblems = hasUiFiles
+        ? [...configProblems, ...changed.problems]
+        : [...(changed.unread ?? [])];
+    const isBlind = changed.files.length === 0 && !isSinceNamed;
+    const { unseen } = visibility;
+    const verdict = verdictOf(uiFiles, problems, [...skipped, ...visibility.skipped], catalogueProblems, isBlind, notVerified.length + unseen.length);
+    const allSkipped = [...skipped, ...catalogueProblems, ...visibility.skipped];
+    const variants = isQuick ? "default" : "all";
+    const body = {
+        since,
+        base,
+        variants,
+        files: changed.files,
+        uiFiles,
+        storyCount: changed.stories.length,
+        stories: changed.stories.slice(0, STORIES_LISTED),
+        ran: seenResults.length,
+        failures,
+        notVerified,
+        code: {
+            checked: code.checked,
+            problems: codeProblems,
+            notes,
+            ...(code.tokenSources === undefined ? {} : { tokenSources: code.tokenSources }),
+            ...(code.tokenNotes === undefined ? {} : { tokenNotes: code.tokenNotes }),
+            ...(code.excused === undefined ? {} : { excused: code.excused }),
+            ...(code.advice === undefined ? {} : { advice: code.advice })
+        },
+        ...(outdated.length === 0 ? {} : { outdated }),
+        problems,
+        ...(compared.isCompared
+            ? { existing: { problems: existingProblems, failures: failuresOf(compared.existing, links) } }
+            : {}),
+        unseen
+    };
+    // problems the base had too are not a check left undone: said in the line, never in skipped
+    const old = existingProblems === 0
+        ? ""
+        : `; ${counted(existingProblems, "problem")} the stories had before the change not counted (existing; --all-problems counts them)`;
+    const summary = `${summaryOf({ ...body, verdict, skipped: allSkipped }, catalogueProblems)}${old}`;
+    return { schema: 2, verdict, summary, skipped: allSkipped, ...body };
+};

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

@@ -0,0 +1,23 @@
+/**
+ * The GitHub Actions the workflows Forgebook writes in a project use: `init --agents`' verify workflow and
+ * `proof --write-workflow`'s.
+ *
+ * @remarks
+ * Each is pinned to the commit of its newest release, with the release in a comment, as Dependabot reads and moves it: a
+ * tag can be moved under a workflow, and an old major runs on a Node that GitHub's runners no longer support. One place, so
+ * both workflows move together.
+ *
+ * @module
+ */
+/** Checks the repository out. */
+export declare const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+/** Installs Node. */
+export declare const SETUP_NODE = "actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0";
+/** Keeps a run's files as an artefact. */
+export declare const UPLOAD = "actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2";
+/** Fetches an artefact in another job. */
+export declare const DOWNLOAD = "actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2";
+/** Installs pnpm. */
+export declare const SETUP_PNPM = "pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1";
+/** Installs Bun. */
+export declare const SETUP_BUN = "oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0";

package/dist/bin/forgebook/workflowActions.js

@@ -0,0 +1,23 @@
+/**
+ * The GitHub Actions the workflows Forgebook writes in a project use: `init --agents`' verify workflow and
+ * `proof --write-workflow`'s.
+ *
+ * @remarks
+ * Each is pinned to the commit of its newest release, with the release in a comment, as Dependabot reads and moves it: a
+ * tag can be moved under a workflow, and an old major runs on a Node that GitHub's runners no longer support. One place, so
+ * both workflows move together.
+ *
+ * @module
+ */
+/** Checks the repository out. */
+export const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+/** Installs Node. */
+export const SETUP_NODE = "actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0";
+/** Keeps a run's files as an artefact. */
+export const UPLOAD = "actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2";
+/** Fetches an artefact in another job. */
+export const DOWNLOAD = "actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2";
+/** Installs pnpm. */
+export const SETUP_PNPM = "pnpm/action-setup@73e46992e05b19abd31f2f3c20e0e7370d762115 # v6.1.1";
+/** Installs Bun. */
+export const SETUP_BUN = "oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0";

package/dist/bin/forgebook-docs/catalogueMarkdown.js

@@ -1,8 +1,19 @@
 import { pageSlug } from "../../src/pageAddress.js";
 /** The props whose keys are the parts. */
 const PART_MAPS = ["classNames", "styles", "refs"];
-/** A prop in short. */
+/**
+ * A prop in short, ending with when it can be passed for a variant's prop (`href:string[kind=link]`), a `?` after the
+ * discriminant when the prop also applies with it left out (`onPick[mode?=single]`).
+ */
 const shortProp = (prop) => {
+    const { onlyWhen } = prop;
+    const condition = onlyWhen === undefined
+        ? ""
+        : `[${onlyWhen.prop}${onlyWhen.orOmitted === true ? "?" : ""}=${onlyWhen.values.map(String).join("|")}]`;
+    return `${propText(prop)}${condition}`;
+};
+/** A prop in short, without its condition. */
+const propText = (prop) => {
     const required = prop.isRequired ? "!" : "";
     switch (prop.kind) {
         case "choice":

package/dist/src/addressArgs.d.ts

@@ -10,7 +10,9 @@
  * have set it: a prop the panel lets the person set (the component's props with the story's `argTypes` laid over them,
  * or an arg only the `argTypes` or the story's own args name), with a value of that prop's type. Everything else is
  * left out and reported. A value that is code never comes from an address: a named value is looked up among the
- * source's own entries only, never through an object's prototype (`constructor`). Pure.
+ * source's own entries only, never through an object's prototype (`constructor`). An object's names are checked the
+ * same way, against its type (`valueShape.ts`). The panel's "no value" (`UnsetArg`) passes for any prop the panel sets:
+ * the story receives `undefined`, which any prop may. Pure.
  *
  * A frame takes values from one kind of message only, whichever frame it is (the stage's, an embed's, a plugin's aside),
  * so `checkedArgsMessage` builds it, from nothing but what this check sealed (`AcceptedArgs`): a page that skipped the
@@ -36,8 +38,11 @@ export type ArgDeclaration = {
     /** The values the source names for types the panel cannot write. */
     readonly namedValues: NamedValues;
 };
-/** Why a value of the address was left out: its name is not one the panel sets, or its value is not of the prop's type. */
-export type DroppedArgReason = "undeclared" | "type";
+/**
+ * Why a value of the address was left out: its name is not one the panel sets, its value is not of the prop's type, its
+ * text could not be read as a value at all, or its custom control refuses it or cannot load.
+ */
+export type DroppedArgReason = "undeclared" | "type" | "unreadable" | "control" | "markup";
 /** A value of the address left out. */
 export type DroppedArg = {
     /** The arg's name, as the address wrote it. */
@@ -51,6 +56,8 @@ export type CheckedArgs = {
     readonly accepted: PanelArgs;
     /** The values left out, in the address's order. */
     readonly dropped: readonly DroppedArg[];
+    /** Whether a value waits for what checks it: it is neither taken nor left out yet. */
+    readonly isWaiting: boolean;
     /** The values the story receives, as a frame can be told them. */
     readonly sealed: AcceptedArgs;
 };
@@ -73,6 +80,19 @@ export declare const NO_ACCEPTED_ARGS: AcceptedArgs;
  * @param declaration - what the story declares.
  */
 export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly PanelProp[];
+/** What checks a custom control's value, by control: gives what is wrong with it. A control missing here refuses all. */
+export type CustomChecks = Readonly<Record<string, (value: ArgValue) => string | undefined>>;
+/** What checks a structured value: `shapeValues.ts` and each control's schema, loaded with the first prop that needs them. */
+export type ArgChecks = Pick<typeof import("./shapeValues.ts"), "isValueOfShape" | "isFileList"> & {
+    /** What checks a custom control's value; none refuses them all. */
+    readonly custom?: CustomChecks;
+};
+/**
+ * Whether a prop's values are checked by `shapeValues.ts`.
+ *
+ * @param prop - a prop the panel sets.
+ */
+export declare const needsShapeChecks: (prop: PanelProp) => boolean;
 /**
  * Whether a value is one the panel could set for a prop: of the control the `argTypes` name, otherwise of the prop's
  * kind.
@@ -80,15 +100,19 @@ export declare const declaredArgProps: (declaration: ArgDeclaration) => readonly
  * @param prop - a prop the panel sets.
  * @param value - the address's value.
  * @param namedValues - the source's named values.
+ * @param shapes - what checks a value against a shape; none refuses a prop that needs it.
  */
-export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues) => boolean;
+export declare const isValueOfProp: (prop: PanelProp, value: ArgValue, namedValues: NamedValues, shapes?: ArgChecks) => boolean;
 /**
  * The address's values the story receives, and those left out with the reason.
  *
  * @param args - the values the address names.
  * @param declaration - what the story declares.
+ * @param typeValue - types a value for its prop, for a link whose form does not say (`storybookArgs.ts`); none takes each
+ *   as written.
+ * @param checks - what checks a structured value, a custom control's among them; none leaves such a value waiting.
  */
-export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration) => CheckedArgs;
+export declare const checkedAddressArgs: (args: PanelArgs, declaration: ArgDeclaration, typeValue?: (prop: PanelProp, value: ArgValue) => ArgValue, checks?: ArgChecks) => CheckedArgs;
 /**
  * The message that gives a frame its values.
  *