forgebook 0.3.3 → 0.4.1

package/dist/bin/forgebook/newProject/projectPackages.js

@@ -0,0 +1,178 @@
+/**
+ * What the written configuration needs installed, and what a project has of it: the packages to add, and the ones it
+ * has declared too old for Forgebook to draw with.
+ *
+ * @remarks
+ * A package's folder is looked for in the `node_modules` folders going up rather than resolved: many packages' `exports`
+ * leave out `package.json`, which would read as not installed, and `NODE_PATH`, which a package manager's shims set, is
+ * something Vite does not read. A declared version is the project's decision, so one too old is
+ * a stop, while a version found only in `node_modules` came with something else and is simply not the project's yet.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isRecord, projectManifest } from "../importers/storybook.js";
+import { FORGEBOOK_PEERS, PROJECT_FRAMEWORKS } from "./projectFrameworks.js";
+/** The longest range read, so a planted one costs nothing. */
+const MAX_RANGE_LENGTH = 256;
+/** A version's numbers. */
+const numbersOf = (parts) => parts.map((part) => Number(part ?? 0) || 0);
+/** Whether one version's numbers come before another's. */
+const isBelow = (version, floor) => {
+    for (const [index, number] of version.entries()) {
+        const other = floor[index] ?? 0;
+        if (number !== other)
+            return number < other;
+    }
+    return false;
+};
+/** A version as text: one that names no number reads as zero. */
+const parsedVersion = (text) => {
+    const match = text.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    return numbersOf([match?.[1], match?.[2], match?.[3]]);
+};
+/** The first version a plain range does not take; none when it has no such end. */
+const rangeEnd = (operator, major, minor, patch) => {
+    const isWild = (part) => part === undefined || part === "x" || part === "*";
+    const minorNumber = Number(minor) || 0;
+    if (operator === "^")
+        return major > 0 ? [major + 1, 0, 0] : [0, minorNumber + 1, 0];
+    if (isWild(minor))
+        return [major + 1, 0, 0];
+    return operator === "~" || isWild(patch)
+        ? [major, minorNumber + 1, 0]
+        : [major, minorNumber, (Number(patch) || 0) + 1];
+};
+/**
+ * Whether one alternative of a range can give a version at or above a floor. What names no version (`workspace:*`,
+ * `latest`) can, since only the package manager can read it.
+ */
+const canReach = (alternative, floor) => {
+    const text = alternative.trim();
+    const upper = text.match(/<(=?)\s*(\d[\d.]*)/);
+    if (upper !== null) {
+        const end = parsedVersion(upper[2] ?? "");
+        return upper[1] === "=" ? !isBelow(end, floor) : isBelow(floor, end);
+    }
+    if (text.startsWith(">"))
+        return true;
+    const match = text.match(/^([\^~]|=|v)?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?/);
+    if (match === null)
+        return true;
+    const end = rangeEnd(match[1] ?? "", Number(match[2]), match[3], match[4]);
+    return isBelow(floor, end);
+};
+/**
+ * Whether what a project wrote or has installed cannot reach a floor: `^8.0.1` can reach `8.3.4`, `^18.3.0` cannot reach
+ * `19.0.0`, and a range counts by its best alternative, since a library's `^18 || ^19` takes the floor's major too.
+ *
+ * @param version - the version or the range.
+ * @param floor - the lowest version taken.
+ */
+export const isBelowFloor = (version, floor) => {
+    const floorNumbers = parsedVersion(floor);
+    return !version
+        .slice(0, MAX_RANGE_LENGTH)
+        .split("||")
+        .some((alternative) => canReach(alternative, floorNumbers));
+};
+/**
+ * The packages a project declares, with their versions as written: a design system's framework is a peer.
+ *
+ * @param projectDir - the project's folder.
+ */
+export const declaredPackages = (projectDir) => {
+    const manifest = projectManifest(projectDir);
+    return new Map(["peerDependencies", "devDependencies", "dependencies"].flatMap((field) => {
+        const list = manifest[field];
+        return isRecord(list)
+            ? Object.entries(list).flatMap(([name, version]) => typeof version === "string" ? [[name, version]] : [])
+            : [];
+    }));
+};
+/**
+ * How the install command names a package: Angular's own at the project's major, since the latest of one beside the
+ * rest at an older major does not install.
+ *
+ * @param name - the package.
+ * @param declared - the packages the project declares.
+ */
+export const installSpecifier = (name, declared) => {
+    const major = declared.get("@angular/core")?.match(/\d+/)?.[0];
+    return name.startsWith("@angular/") && major !== undefined ? `${name}@^${major}.0.0` : name;
+};
+/** The nearest `node_modules` copy of a package, going up from a folder. */
+const nearestManifest = (dir, name) => {
+    const manifest = join(dir, "node_modules", name, "package.json");
+    if (existsSync(manifest))
+        return manifest;
+    const parent = dirname(dir);
+    return parent === dir ? undefined : nearestManifest(parent, name);
+};
+/**
+ * The version of a package a folder can load, read from its `package.json`.
+ *
+ * @param dir - the folder.
+ * @param name - the package.
+ * @returns its version, `""` for one that names none, or none when it is not installed.
+ */
+export const installedVersion = (dir, name) => {
+    const manifest = nearestManifest(dir, name);
+    if (manifest === undefined)
+        return undefined;
+    const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+    const version = typeof parsed === "object" && parsed !== null && "version" in parsed ? parsed.version : undefined;
+    return typeof version === "string" ? version : "";
+};
+/**
+ * The packages a configuration needs with the lowest version of each: `forgebook`, the adapter, what either asks the
+ * project for, and what the adapter's options add (no floor, written as `0.0.0`). Forgebook's own Vite is its dependency,
+ * so a project's is no concern here.
+ *
+ * @param framework - the framework.
+ * @param extraPeers - what its options add.
+ */
+export const requiredPackages = (framework, extraPeers) => {
+    const required = new Map([
+        ["forgebook", "0.0.0"],
+        [`@forgebook/${framework}`, "0.0.0"]
+    ]);
+    for (const peers of [FORGEBOOK_PEERS, PROJECT_FRAMEWORKS[framework].peers]) {
+        for (const [name, floor] of Object.entries(peers)) {
+            const known = required.get(name);
+            if (known === undefined || isBelowFloor(known, floor))
+                required.set(name, floor);
+        }
+    }
+    for (const name of extraPeers)
+        if (!required.has(name))
+            required.set(name, "0.0.0");
+    return required;
+};
+/**
+ * What a project has of the packages a configuration needs.
+ *
+ * @param dir - the project's folder.
+ * @param declared - the packages it declares, with their versions as written.
+ * @param required - the packages needed, with the lowest version of each.
+ */
+export const packageState = (dir, declared, required) => {
+    const missing = [];
+    const tooOld = [];
+    let hasUninstalled = false;
+    for (const [name, floor] of required) {
+        const written = declared.get(name);
+        const installed = installedVersion(dir, name);
+        const found = installed === undefined || installed === "" ? written : installed;
+        // an alias (`npm:@preact/compat`) has a version of its own package's, which says nothing of this one's
+        const isOld = found !== undefined && written?.startsWith("npm:") !== true && isBelowFloor(found, floor);
+        if (written !== undefined && isOld)
+            tooOld.push({ name, found: found ?? written, floor });
+        else if (written === undefined && (installed === undefined || isOld))
+            missing.push(name);
+        else if (installed === undefined)
+            hasUninstalled = true;
+    }
+    return { missing, tooOld, hasUninstalled };
+};

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

@@ -0,0 +1,45 @@
+import type { StoryCheckReport } from "../../src/storyCheck.ts";
+import type { StoryWrapper } from "./newStories.ts";
+/** How many times the stories are drawn again after a repair. */
+export declare const MAX_ROUNDS = 2;
+/**
+ * The components a report's failures say their stories must be drawn inside, each once, in the order met.
+ *
+ * @param report - the new stories' check.
+ * @returns the names; a context's provider (`Theme.Provider`) is left out, since its value cannot be made up.
+ */
+export declare const neededWrappers: (report: StoryCheckReport) => string[];
+/**
+ * The component of the application a story must be drawn inside, as a wrapper the story file imports.
+ *
+ * @param componentFile - the component's file, absolute.
+ * @param storyFile - the story file the import is written in, absolute.
+ * @param name - the component's name, as the error gives it.
+ * @returns the wrapper; none when the application exports no such component, or several in places equally near.
+ */
+export declare const wrapperFor: (componentFile: string, storyFile: string, name: string) => StoryWrapper | undefined;
+/** What a repair round did. */
+export type RepairOutcome = {
+    /** The wrappers the stories are now drawn inside, outermost first. */
+    readonly wrappers: readonly StoryWrapper[];
+    /**
+     * The components an error named that the application does not export as a component it can draw with no props, in the
+     * component's package, or that the last draw still names: for a person or an agent to give in a decorator.
+     */
+    readonly notFound: readonly string[];
+    /** The last check's report; a text when the stories could not be drawn. */
+    readonly report: StoryCheckReport | string;
+};
+/**
+ * Draws the new stories, adds what their errors name as wrappers, writes them again and draws them again.
+ *
+ * @param input - the files, how to check the stories, and how to write them with wrappers.
+ */
+export declare const repairRounds: (input: {
+    readonly componentFile: string;
+    readonly storyFile: string;
+    readonly check: () => Promise<StoryCheckReport | string>;
+    readonly write: (wrappers: readonly StoryWrapper[]) => Promise<void>;
+    readonly find?: (name: string) => StoryWrapper | undefined;
+    readonly packageDir?: string;
+}) => Promise<RepairOutcome>;

package/dist/bin/forgebook/newRepair.js

@@ -0,0 +1,157 @@
+/**
+ * The repair round of `forgebook new --repair`: the new stories are drawn, and a story whose component says it needs to
+ * be drawn inside another one (`useSidebar must be used within a SidebarProvider`) gets that component as a decorator,
+ * found in the application by its name; then they are drawn again, at most `MAX_ROUNDS` times.
+ *
+ * @remarks
+ * Only what the error names is added, and only a component the application exports: a context's value (`X.Provider`)
+ * or a store cannot be made up, so those are named for a person or an agent to give. The browser run is the caller's
+ * (`check`), so the round itself is tested without one.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { programFor } from "../../src/vite/docsProgram.js";
+import { VITE_PATHS } from "../../src/vite/vitePaths.js";
+/** How many times the stories are drawn again after a repair. */
+export const MAX_ROUNDS = 2;
+/**
+ * The component an error says the story must be drawn inside: the words React libraries and applications use for it
+ * ("must be used within", "can only be used inside", "is missing a parent"), then the component's name.
+ */
+const NEEDED_WRAPPER = /(?:must be (?:used|placed|rendered|wrapped)|can only be used|may be used only|should be used|has to be used|only be used|used outside)\s*(?:within|in|inside|with|by|under)?\s*(?:the context of\s+)?(?:the\s+|an?\s+|a descendant of\s+)?[`<"']?([A-Z][\w.]*)/;
+/** Names a wrapper cannot have in a story file: they are the file's own (`Story`, `Meta`) or the component's. */
+const RESERVED = new Set(["Story", "Meta", "React"]);
+/** A file that is not the application: a story, a test, a declaration, a dependency. */
+const NOT_APPLICATION = /\.(?:stories|story|test|spec)\.[cm]?[jt]sx?$|\.d\.[cm]?ts$|[\\/]node_modules[\\/]/;
+/**
+ * The components a report's failures say their stories must be drawn inside, each once, in the order met.
+ *
+ * @param report - the new stories' check.
+ * @returns the names; a context's provider (`Theme.Provider`) is left out, since its value cannot be made up.
+ */
+export const neededWrappers = (report) => {
+    const names = report.results.flatMap((result) => result.problems.flatMap((problem) => {
+        const name = NEEDED_WRAPPER.exec(problem.message)?.[1]?.replace(/\.$/, "");
+        return name === undefined || name.includes(".") || RESERVED.has(name) ? [] : [name];
+    }));
+    return [...new Set(names)];
+};
+/** Whether a symbol's value is a component: a function, or a class. */
+const isComponent = (symbol, checker) => {
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (declaration === undefined)
+        return false;
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    return type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0;
+};
+/** The props a function component must be given besides its children: a wrapper written with none would not draw. */
+const requiredProps = (symbol, checker) => {
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (declaration === undefined)
+        return [];
+    const [signature] = checker.getTypeOfSymbolAtLocation(symbol, declaration).getCallSignatures();
+    const [props] = signature?.getParameters() ?? [];
+    if (props === undefined)
+        return [];
+    return checker
+        .getTypeOfSymbolAtLocation(props, declaration)
+        .getProperties()
+        .filter((prop) => (prop.flags & ts.SymbolFlags.Optional) === 0 && prop.getName() !== "children")
+        .map((prop) => prop.getName());
+};
+/** The name a declaration gives its symbol: `SidebarProvider` for `export default function SidebarProvider()`. */
+const declaredName = (symbol) => {
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    const name = declaration === undefined ? undefined : ts.getNameOfDeclaration(declaration);
+    return name !== undefined && ts.isIdentifier(name) ? name.text : symbol.getName();
+};
+/** The application's exports of a component by a name, from the component's program read whole. */
+const exportsNamed = (componentFile, name) => {
+    const program = programFor(componentFile, { reach: "whole" });
+    if (typeof program === "string")
+        return [];
+    const { checker } = program;
+    return program.program.getSourceFiles().flatMap((source) => {
+        if (NOT_APPLICATION.test(source.fileName) || program.program.isSourceFileFromExternalLibrary(source))
+            return [];
+        if (!source.text.includes(name))
+            return [];
+        const moduleSymbol = checker.getSymbolAtLocation(source);
+        if (moduleSymbol === undefined)
+            return [];
+        return checker.getExportsOfModule(moduleSymbol).flatMap((each) => {
+            const symbol = (each.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(each) : each;
+            const isNamed = each.getName() === name;
+            const isDefaultNamed = each.getName() === "default" && declaredName(symbol) === name;
+            if ((!isNamed && !isDefaultNamed) || !isComponent(symbol, checker))
+                return [];
+            // a barrel's re-export is the same component: it is imported from where it is declared
+            const declaredIn = symbol.valueDeclaration?.getSourceFile().fileName ?? source.fileName;
+            const isOwn = declaredIn === source.fileName;
+            return isOwn || !isNamed
+                ? [{ file: source.fileName, isDefault: !isNamed, required: requiredProps(symbol, checker) }]
+                : [];
+        });
+    });
+};
+/**
+ * The component of the application a story must be drawn inside, as a wrapper the story file imports.
+ *
+ * @param componentFile - the component's file, absolute.
+ * @param storyFile - the story file the import is written in, absolute.
+ * @param name - the component's name, as the error gives it.
+ * @returns the wrapper; none when the application exports no such component, or several in places equally near.
+ */
+export const wrapperFor = (componentFile, storyFile, name) => {
+    const found = exportsNamed(componentFile, name);
+    const component = VITE_PATHS.normalize(componentFile);
+    const folder = VITE_PATHS.dirname(component);
+    // the nearest wins: the component's own file (a compound's parts), then its folder, then the only one
+    const chosen = found.find((each) => VITE_PATHS.normalize(each.file) === component) ??
+        found.find((each) => VITE_PATHS.dirname(VITE_PATHS.normalize(each.file)) === folder) ??
+        (found.length === 1 ? found[0] : undefined);
+    if (chosen === undefined)
+        return undefined;
+    const relative = VITE_PATHS.relative(VITE_PATHS.dirname(VITE_PATHS.normalize(storyFile)), chosen.file);
+    const path = (relative.startsWith(".") ? relative : `./${relative}`).replace(/\.[cm]?[jt]sx?$/, "");
+    return {
+        name,
+        importStatement: chosen.isDefault
+            ? `import ${name} from ${JSON.stringify(path)};`
+            : `import { ${name} } from ${JSON.stringify(path)};`
+    };
+};
+/**
+ * Draws the new stories, adds what their errors name as wrappers, writes them again and draws them again.
+ *
+ * @param input - the files, how to check the stories, and how to write them with wrappers.
+ */
+export const repairRounds = async (input) => {
+    const find = input.find ??
+        ((name) => wrapperFor(input.componentFile, input.storyFile, name));
+    let wrappers = [];
+    const notFound = new Set();
+    let report = await input.check();
+    for (let round = 0; round < MAX_ROUNDS && typeof report !== "string"; round += 1) {
+        const names = neededWrappers(report).filter((name) => !notFound.has(name) && !wrappers.some((each) => each.name === name));
+        const added = names.flatMap((name) => {
+            const wrapper = find(name);
+            if (wrapper === undefined)
+                notFound.add(name);
+            return wrapper === undefined ? [] : [wrapper];
+        });
+        if (added.length === 0)
+            break;
+        // what an inner wrapper needs goes around it
+        wrappers = [...added, ...wrappers];
+        await input.write(wrappers);
+        report = await input.check();
+    }
+    // what the last draw still names was never tried: it is said with what was not found
+    if (typeof report !== "string")
+        for (const name of neededWrappers(report))
+            if (!wrappers.some((each) => each.name === name))
+                notFound.add(name);
+    return { wrappers, notFound: [...notFound], report };
+};

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

@@ -0,0 +1,69 @@
+import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+import { type RepairOutcome } from "./newRepair.ts";
+import type { StoryWrapper } from "./newStories.ts";
+import { type NewStoriesFile } from "./newStoriesFile.ts";
+/**
+ * The catalogue a component's new stories are repaired in, when they can be: a wrapper is written as JSX, so only a
+ * framework whose story files hold JSX takes one.
+ *
+ * @param written - the stories about to be written.
+ * @param configFile - the configuration file given; none to look in the current folder.
+ * @throws a `ScriptError` for a story file that holds no JSX, or a configuration that cannot be read.
+ */
+export declare const repairable: (written: NewStoriesFile, configFile: string | undefined) => Promise<ResolvedConfig>;
+/**
+ * Repairs a component's new stories.
+ *
+ * @param storyFile - the stories file written, absolute.
+ * @param componentFile - the component's file, absolute.
+ * @param config - the catalogue's configuration.
+ * @param write - writes the stories again with wrappers.
+ */
+export declare const repairNew: (storyFile: string, componentFile: string, config: ResolvedConfig, write: (wrappers: readonly StoryWrapper[]) => Promise<NewStoriesFile>) => Promise<RepairOutcome>;
+/**
+ * What `new --json` answers: the file and its uses, and with `--repair` what the round added and found.
+ *
+ * @param written - the stories written.
+ * @param shown - the file as the command names it.
+ * @param repaired - the round's outcome, when one ran.
+ */
+export declare const newDocument: (written: NewStoriesFile, shown: string, repaired: RepairOutcome | undefined) => Readonly<Record<string, unknown>>;
+/**
+ * What the command says of a repair round.
+ *
+ * @param repaired - the round's outcome.
+ */
+export declare const repairLines: (repaired: RepairOutcome) => string[];
+/** What `new` was given. */
+export type NewOptions = {
+    /** The component to read, when the file exports several. */
+    readonly export?: string | undefined;
+    /** The framework the stories are written for; the catalogue's when none. */
+    readonly framework?: string | undefined;
+    /** Print the file instead of writing it. */
+    readonly print?: boolean | undefined;
+    /** Replace a stories file that exists. */
+    readonly force?: boolean | undefined;
+    /** Draw the stories and repair them. */
+    readonly repair?: boolean | undefined;
+    /** The configuration file; the current folder's when none. */
+    readonly config?: string | undefined;
+};
+/** What `new` prints: the file's text with `--print`, else the answer and the lines to log with their tone. */
+export type NewOutcome = {
+    /** The file's text, with `--print`. */
+    readonly printed?: string;
+    /** What `--json` answers. */
+    readonly document: Readonly<Record<string, unknown>>;
+    /** The lines to log, each with its tone. */
+    readonly lines: readonly (readonly ["success" | "info" | "warn", string])[];
+};
+/**
+ * Writes a component's first stories, and repairs them with `--repair`.
+ *
+ * @param componentFile - the component's file, absolute.
+ * @param options - what the command was given.
+ * @throws a `ScriptError` on a usage the command refuses, a file that exists without `--force`, or what writing the
+ *   stories throws.
+ */
+export declare const runNew: (componentFile: string, options: NewOptions) => Promise<NewOutcome>;

package/dist/bin/forgebook/newRepairRun.js

@@ -0,0 +1,148 @@
+/**
+ * What `forgebook new --repair` runs around the repair round (`newRepair.ts`): the stories checked in a browser through
+ * the catalogue, the file written again with each round's wrappers, and what the command says and answers.
+ *
+ * @module
+ */
+import { existsSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { VITE_PATHS } from "../../src/vite/vitePaths.js";
+import { configOf } from "./catalogueCommands.js";
+import { repairRounds } from "./newRepair.js";
+import { newStoriesDocument, newStoriesFile, usesWords } from "./newStoriesFile.js";
+import { runStoriesCheck } from "./storyCheckRun.js";
+/**
+ * The catalogue a component's new stories are repaired in, when they can be: a wrapper is written as JSX, so only a
+ * framework whose story files hold JSX takes one.
+ *
+ * @param written - the stories about to be written.
+ * @param configFile - the configuration file given; none to look in the current folder.
+ * @throws a `ScriptError` for a story file that holds no JSX, or a configuration that cannot be read.
+ */
+export const repairable = async (written, configFile) => {
+    if (!JSX_STORY_FILE.test(written.file))
+        throw new ScriptError(`--repair draws stories inside providers as JSX, which ${written.file} cannot hold`, {
+            hint: "Give the providers in a decorator of the file, or in the preview",
+            exitCode: EXIT.usage
+        });
+    return configOf(configFile);
+};
+/** A story file that holds JSX. */
+const JSX_STORY_FILE = /\.stories\.[jt]sx$/;
+/** What a run that found no story of the file says: the file is not listed, or does not load. */
+const NO_STORY = /^No story or component /;
+/**
+ * Repairs a component's new stories.
+ *
+ * @param storyFile - the stories file written, absolute.
+ * @param componentFile - the component's file, absolute.
+ * @param config - the catalogue's configuration.
+ * @param write - writes the stories again with wrappers.
+ */
+export const repairNew = async (storyFile, componentFile, config, write) => {
+    const outcome = await repairRounds({
+        componentFile,
+        storyFile,
+        packageDir: config.dir,
+        check: () => runStoriesCheck(config, undefined, {
+            ids: [],
+            files: [storyFile],
+            isAllVariants: false,
+            isOwnServer: true
+        }),
+        write: async (wrappers) => {
+            writeFileSync(storyFile, (await write(wrappers)).text);
+        }
+    });
+    return typeof outcome.report === "string" && NO_STORY.test(outcome.report)
+        ? {
+            ...outcome,
+            report: `the catalogue lists no story of ${VITE_PATHS.relative(config.dir, storyFile)}: its stories' patterns (${config.stories.join(", ")}) do not match it, or it does not load (npx forgebook stories --json says why)`
+        }
+        : outcome;
+};
+/**
+ * What `new --json` answers: the file and its uses, and with `--repair` what the round added and found.
+ *
+ * @param written - the stories written.
+ * @param shown - the file as the command names it.
+ * @param repaired - the round's outcome, when one ran.
+ */
+export const newDocument = (written, shown, repaired) => ({
+    ...newStoriesDocument(written, shown),
+    ...(repaired === undefined
+        ? {}
+        : {
+            repair: {
+                wrappers: repaired.wrappers.map((each) => each.name),
+                notFound: repaired.notFound,
+                ...(typeof repaired.report === "string"
+                    ? { notRun: repaired.report }
+                    : {
+                        stories: repaired.report.results.length,
+                        failing: repaired.report.results.filter((result) => result.problems.length > 0).length
+                    })
+            }
+        })
+});
+/**
+ * What the command says of a repair round.
+ *
+ * @param repaired - the round's outcome.
+ */
+export const repairLines = (repaired) => {
+    const { report, wrappers, notFound } = repaired;
+    if (typeof report === "string")
+        return [`The stories were not drawn: ${report}`];
+    const failing = report.results.filter((result) => result.problems.length > 0).length;
+    return [
+        ...(wrappers.length === 0 ? [] : [`Drawn inside ${wrappers.map((each) => each.name).join(", ")}`]),
+        ...(notFound.length === 0
+            ? []
+            : [
+                `Needs ${notFound.join(", ")}, which the application does not export as a component: give it in a decorator`
+            ]),
+        `${report.results.length - failing} of ${report.results.length} stories draw with no problem`
+    ];
+};
+/**
+ * Writes a component's first stories, and repairs them with `--repair`.
+ *
+ * @param componentFile - the component's file, absolute.
+ * @param options - what the command was given.
+ * @throws a `ScriptError` on a usage the command refuses, a file that exists without `--force`, or what writing the
+ *   stories throws.
+ */
+export const runNew = async (componentFile, options) => {
+    if (options.print === true && options.repair === true)
+        throw new ScriptError("--repair draws the file it writes, and --print writes none", {
+            exitCode: EXIT.usage
+        });
+    const written = await newStoriesFile(componentFile, options.export, options.framework);
+    // read first: a configuration that cannot be read must not leave a file written and the command failed
+    const config = options.repair === true ? await repairable(written, options.config) : undefined;
+    if (options.print === true)
+        return { printed: written.text, document: {}, lines: [] };
+    const shown = relative(process.cwd(), written.file);
+    if (existsSync(written.file) && options.force !== true)
+        throw new ScriptError(`${shown} exists`, { hint: "Give --force to replace it, or --print to see it" });
+    writeFileSync(written.file, written.text);
+    const repaired = config === undefined
+        ? undefined
+        : await repairNew(written.file, componentFile, config, (wrappers) => newStoriesFile(componentFile, options.export, options.framework, wrappers));
+    const problemLines = written.usesProblem === undefined ? [] : [["warn", `Its uses were not read: ${written.usesProblem}`]];
+    const title = written.text.match(/title: "([^"]*)"/)?.[1] ?? "";
+    return {
+        document: newDocument(written, shown, repaired),
+        lines: [
+            ["success", `${shown} written${usesWords(written.uses)}`],
+            ...problemLines,
+            ...(repaired === undefined
+                ? []
+                : repairLines(repaired).map((line) => ["info", line])),
+            ["info", `npx forgebook stories --component ${title} lists them`]
+        ]
+    };
+};

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

@@ -1,11 +1,19 @@
 /**
  * The first stories of a component, written from its props as the docs extractor reads them (`forgebook new`): the
  * meta, the main story with the required props filled, one story per value of its first choice prop, and the worst
- * case. Args only, so the file is the same for any framework but its type import. Pure: docs in, text out.
+ * case. Args only, so the file is the same for any framework but its type import. The file carries the signature of
+ * the props it was written for (`propsSignature.ts`), so `verify` can say when they change. Pure: docs in, text out.
  *
  * @module
  */
 import type { ComponentDocs } from "../../src/componentDocs.ts";
+/** A place the application draws the component, as the file is written from it. */
+export type StoryUse = {
+    /** The file that draws it, relative to the package: the story's summary names it. */
+    readonly file: string;
+    /** The props it gives a literal value, as code. */
+    readonly args: Readonly<Record<string, string>>;
+};
 /** What the file is written from. */
 export type NewStoriesInput = {
     /** The component's docs (its props). */
@@ -16,6 +24,20 @@ export type NewStoriesInput = {
     readonly title: string;
     /** The module the story types come from (`@forgebook/react`). */
     readonly typesModule: string;
+    /**
+     * Components every story is drawn inside, outermost first, each with its import: the providers a first draw said the
+     * component needs (`forgebook new --repair`); none by default. Written as JSX, for a JSX framework's story file.
+     */
+    readonly wrappers?: readonly StoryWrapper[];
+    /** Where the application draws it, for realistic values and a story per way it is used; none by default. */
+    readonly uses?: readonly StoryUse[];
+};
+/** A component a story is drawn inside, and the statement that imports it. */
+export type StoryWrapper = {
+    /** The component's name in the file (`SidebarProvider`). */
+    readonly name: string;
+    /** The statement that imports it (`import { SidebarProvider } from "./sidebar";`). */
+    readonly importStatement: string;
 };
 /**
  * The story file's text.