forgebook 0.3.2 → 0.4.0

package/dist/bin/forgebook/appBuild/appViteConfig.js

@@ -0,0 +1,320 @@
+/**
+ * The app's Vite configuration, as a catalogue reads it: loaded as `vite dev` loads it, then what is about how modules
+ * and style sheets resolve and compile is kept, and what is about the app's page, server and output is not.
+ *
+ * @remarks
+ * Loading it runs the project's code, and later its plugins' hooks. That is on purpose: every command that starts a
+ * catalogue already runs the project's `forgebook.config.ts` and its components, and this is the file the person runs
+ * with `vite dev` every day. `forgebook init` never loads it; `appBuild: false` turns it off.
+ *
+ * A plugin stays unless it is on one of two lists. The framework's own plugin is the adapter's to give, and two of them
+ * compile each file twice. The others build or serve an app, not components: a route table, a service worker, a
+ * source-map upload, a certificate, a type checker. A person who needs one back names it in `appBuild.keepPlugins`.
+ *
+ * The lists go by name in this package rather than through the adapters, so a project whose adapter is a version older
+ * than this core still never runs its framework's plugin twice.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import { dirname, join, resolve } from "node:path";
+/** The names a Vite configuration may have, in the order Vite looks for them. */
+const VITE_CONFIG_FILES = [
+    "vite.config.js",
+    "vite.config.mjs",
+    "vite.config.ts",
+    "vite.config.cjs",
+    "vite.config.mts",
+    "vite.config.cts"
+];
+/** The plugins each framework's adapter gives itself, by the adapter's name. */
+const FRAMEWORK_PLUGINS = {
+    react: /^(?:vite:react|@vitejs\/plugin-react|@rolldown\/plugin-babel$)/,
+    "react-native-web": /^(?:vite:react|@vitejs\/plugin-react)/,
+    preact: /^(?:preact:|vite:preact|prefresh)/,
+    vue: /^vite:vue$/,
+    svelte: /^vite-plugin-svelte(?:[-:]|$)/,
+    solid: /^solid$/
+};
+/** What builds or serves an app and has no part in drawing a component, by its plugin's name. */
+const APP_ONLY_PLUGINS = /^(?:react-router|remix|tanstack|@tanstack|vinext|vike|vite-plugin-ssr|vite-plugin-pwa|vite:legacy|vite-plugin-checker|vite-plugin-inspect|vite-plugin-vue-devtools|vite-plugin-vue-inspector|visualizer|rollup-plugin-visualizer|sentry|@sentry|codecov|vite-plugin-compression|vite-plugin-dts|dts$|unplugin-dts|vite-plugin-electron|electron|laravel|vite-plugin-ruby|@cloudflare|cloudflare|vercel|netlify|nitro|vite-plugin-node|vite:basic-ssl|vite-plugin-mkcert|vite-plugin-eslint|vite-plugin-stylelint|vite-plugin-static-copy|vite-plugin-html|vite-plugin-mock-dev-server|forgebook)/;
+/** What reads a project's `paths` a second way: Vite's own reading takes its place. */
+const TSCONFIG_PATHS_PLUGIN = /^vite-tsconfig-paths$|^vite:tsconfig-paths$/;
+/** What a `vite.config` can import and still give a catalogue nothing: Vite's, and the framework's own plugin. */
+const FRAMEWORK_IMPORTS = new Set([
+    "vite",
+    "vitest/config",
+    "@vitejs/plugin-react",
+    "@vitejs/plugin-react-swc",
+    "@vitejs/plugin-vue",
+    "@sveltejs/vite-plugin-svelte",
+    "vite-plugin-solid",
+    "@preact/preset-vite"
+]);
+/** A module a script loads, by `from`, a bare `import`, `import()` or `require()`. */
+const LOADED_MODULE = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["'`]([^"'`\n]+)["'`]/g;
+/** A word naming one of the settings a catalogue takes. */
+const TAKEN_SETTING = /\b(?:resolve|alias|css|define|esbuild|oxc|optimizeDeps|envPrefix|envDir|publicDir|assetsInclude|json|dedupe|conditions|mainFields|extensions|tsconfigPaths|name|transform|load|resolveId|configureServer|enforce|jsxImportSource|babel)\b/;
+/**
+ * Whether a `vite.config` can hold nothing for a catalogue, as its text shows: it loads only Vite and the framework's
+ * plugin, and names none of the settings taken nor anything a plugin written in the file would hold.
+ *
+ * @remarks
+ * The usual configuration of a new project is exactly this, and loading it means bundling it and starting the module
+ * graph it imports, which a project with nothing to read must not pay. The check only ever errs towards loading: a word
+ * in a comment loads a file that gives nothing.
+ *
+ * @param text - the file's text.
+ */
+export const holdsNothingForCatalogue = (text) => !TAKEN_SETTING.test(text) &&
+    [...text.matchAll(LOADED_MODULE)].every((match) => {
+        const name = match[1] ?? "";
+        return FRAMEWORK_IMPORTS.has(name) || isBuiltin(name);
+    });
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a value is one of Vite's plugins. */
+const isPlugin = (value) => isRecord(value) && typeof value["name"] === "string";
+/**
+ * A configuration's plugins as one list: Vite takes nested lists and promises of plugins.
+ *
+ * @param plugins - the plugins, as the configuration writes them.
+ */
+const flatPlugins = async (plugins) => {
+    const value = await plugins;
+    if (Array.isArray(value))
+        return (await Promise.all(value.map(flatPlugins))).flat();
+    return isPlugin(value) ? [value] : [];
+};
+/**
+ * The app's Vite configuration file, from the catalogue's folder, or none.
+ *
+ * @param dir - the catalogue's folder.
+ * @param asked - `appBuild.viteConfig`.
+ */
+export const viteConfigFile = (dir, asked) => {
+    if (asked === false)
+        return undefined;
+    if (asked !== undefined)
+        return asked;
+    return VITE_CONFIG_FILES.find((name) => existsSync(join(dir, name)));
+};
+/**
+ * Whether the app's Vite configuration is worth loading.
+ *
+ * @param dir - the catalogue's folder.
+ * @param file - the file, from there.
+ */
+export const isWorthLoading = (dir, file) => {
+    try {
+        return !holdsNothingForCatalogue(readFileSync(resolve(dir, file), "utf8"));
+    }
+    catch {
+        // loading it says why it cannot be read, in the words the person is told
+        return true;
+    }
+};
+/**
+ * Whether one of the app's plugins goes into the catalogue.
+ *
+ * @param name - the plugin's name.
+ * @param framework - the adapter's name.
+ * @param options - what the catalogue's configuration asks.
+ * @param isReadingPaths - whether Vite reads `tsconfig` paths here, which a plugin that does the same is then not needed for.
+ */
+export const keepsAppPlugin = (name, framework, options, isReadingPaths = true) => {
+    if (options.skipPlugins.includes(name))
+        return false;
+    if (options.keepPlugins.includes(name))
+        return true;
+    if (FRAMEWORK_PLUGINS[framework]?.test(name) === true)
+        return false;
+    return !APP_ONLY_PLUGINS.test(name) && !(isReadingPaths && TSCONFIG_PATHS_PLUGIN.test(name));
+};
+/** What is taken of `resolve`. */
+const resolveFields = (given) => ({
+    ...(given.alias === undefined ? {} : { alias: given.alias }),
+    ...(given.dedupe === undefined ? {} : { dedupe: given.dedupe }),
+    ...(given.conditions === undefined ? {} : { conditions: given.conditions }),
+    ...(given.mainFields === undefined ? {} : { mainFields: given.mainFields }),
+    ...(given.extensions === undefined ? {} : { extensions: given.extensions }),
+    ...(given.tsconfigPaths === undefined ? {} : { tsconfigPaths: given.tsconfigPaths })
+});
+/** Lightning CSS's options but its visitor. */
+const withoutVisitor = ({ visitor: _visitor, ...rest }) => rest;
+/** What is taken of `css`: its visitor stays Forgebook's, since the forced states are a rewrite of the style sheets. */
+const cssFields = (given) => ({
+    ...(given.preprocessorOptions === undefined ? {} : { preprocessorOptions: given.preprocessorOptions }),
+    ...(given.preprocessorMaxWorkers === undefined
+        ? {}
+        : { preprocessorMaxWorkers: given.preprocessorMaxWorkers }),
+    ...(given.lightningcss === undefined ? {} : { lightningcss: withoutVisitor(given.lightningcss) })
+});
+/** What is taken of `optimizeDeps`. */
+const optimizeFields = (given) => ({
+    ...(given.include === undefined ? {} : { include: given.include }),
+    ...(given.exclude === undefined ? {} : { exclude: given.exclude })
+});
+/** The `define` names that replace a whole environment. */
+const WHOLE_ENVIRONMENT = new Set(["process.env", "import.meta.env"]);
+/**
+ * Whether a `define` value is empty: `process.env: {}` is a common way to keep code that reads it from failing, and holds
+ * nothing.
+ */
+const isEmptyDefine = (value) => value === "{}" || (typeof value === "object" && value !== null && Object.keys(value).length === 0);
+/**
+ * A `define` without a whole environment written out: a catalogue bundles code the app does not (Testing Library reads
+ * `process.env`), so what the app kept out of its bundles would reach the catalogue's.
+ *
+ * @param define - the configuration's.
+ */
+export const withoutWholeEnvironment = (define) => Object.fromEntries(Object.entries(define).filter(([name, value]) => !WHOLE_ENVIRONMENT.has(name) || isEmptyDefine(value)));
+/** What is taken of how code compiles and what it reads. */
+const compileFields = (config) => ({
+    ...(config.define === undefined ? {} : { define: withoutWholeEnvironment(config.define) }),
+    ...(config.assetsInclude === undefined ? {} : { assetsInclude: config.assetsInclude }),
+    ...(config.json === undefined ? {} : { json: config.json }),
+    ...(config.esbuild === undefined ? {} : { esbuild: config.esbuild }),
+    ...(config.oxc === undefined ? {} : { oxc: config.oxc }),
+    ...(config.envPrefix === undefined ? {} : { envPrefix: config.envPrefix })
+});
+/** The folders it names, absolute: the catalogue's root is not the one they are written against. */
+const folderFields = ({ envDir, publicDir }, root) => ({
+    ...(typeof envDir === "string" ? { envDir: resolve(root, envDir) } : {}),
+    ...(typeof publicDir === "string" ? { publicDir: resolve(root, publicDir) } : {}),
+    ...(publicDir === false ? { publicDir: false } : {})
+});
+/**
+ * What a catalogue takes of the app's configuration besides its plugins: what decides how a module resolves and
+ * compiles. `root`, `base`, `build`, `server`, `preview` and `test` are about the app's page and output.
+ *
+ * @param config - the configuration, loaded.
+ * @param dir - the catalogue's folder, which its relative paths are read against when it names no root.
+ */
+export const appConfigFields = (config, dir) => {
+    const resolved = resolveFields(config.resolve ?? {});
+    const css = cssFields(config.css ?? {});
+    const optimizeDeps = optimizeFields(config.optimizeDeps ?? {});
+    return {
+        ...(Object.keys(resolved).length === 0 ? {} : { resolve: resolved }),
+        ...(Object.keys(css).length === 0 ? {} : { css }),
+        ...(Object.keys(optimizeDeps).length === 0 ? {} : { optimizeDeps }),
+        ...compileFields(config),
+        ...folderFields(config, resolve(dir, config.root ?? "."))
+    };
+};
+/**
+ * The PostCSS plugins of a configuration's `css.postcss`, when it writes them there rather than in a file.
+ *
+ * @param config - the configuration, loaded.
+ */
+const inlinePostcssPlugins = (config) => {
+    const postcss = config.css?.postcss;
+    return isRecord(postcss) && Array.isArray(postcss["plugins"]) ? postcss["plugins"] : undefined;
+};
+/** A hook's function, from the function or the function with its order. */
+const handlerOf = (hook) => typeof hook === "object" && hook !== null && "handler" in hook ? hook.handler : hook;
+/** A hook's order, when it names one. */
+const orderOf = (hook) => {
+    const order = typeof hook === "object" && hook !== null && "order" in hook ? hook.order : undefined;
+    return order === "pre" || order === "post" ? { order } : {};
+};
+/** A plugin's `config`, what it returns filtered. */
+const guardedConfig = (hook, dir) => {
+    const handler = handlerOf(hook);
+    return {
+        ...orderOf(hook),
+        async handler(config, env) {
+            const returned = await Reflect.apply(handler, this, [config, env]);
+            return returned === null || returned === undefined ? null : appConfigFields(returned, dir);
+        }
+    };
+};
+/** A plugin's `transformIndexHtml`, for the frames' page alone. */
+const guardedHtml = (hook) => {
+    const handler = handlerOf(hook);
+    return {
+        ...orderOf(hook),
+        handler(html, context) {
+            return context.path.endsWith("frame.html") ? Reflect.apply(handler, this, [html, context]) : html;
+        }
+    };
+};
+/**
+ * One of the app's plugins, kept from reaching past what a catalogue takes of an app.
+ *
+ * @remarks
+ * What its `config` returns goes through the same filter as the file's, or a plugin could set the host, `fs.strict` or the
+ * output. Its `configureServer` runs at the normal time, after the middlewares that keep each origin to itself: `order: "pre"`
+ * would answer ahead of them. Its `transformIndexHtml` reaches the frames and not the catalogue's page, whose origin holds the
+ * agent API: a story's frame is what the app's page stands for. A one-shot command's server runs no `configureServer` at all:
+ * that hook is where a plugin starts a backend or a watcher of its own, whose output on an inherited stdout would break a
+ * command's `--json`, and nothing a story asks for in the moment it is checked needs what it sets up for edits.
+ *
+ * @param plugin - the plugin.
+ * @param dir - the folder its relative paths are read against.
+ * @param isOneShot - whether the server is a one-shot command's.
+ */
+export const guardedAppPlugin = (plugin, dir, isOneShot = false) => {
+    const { config, configureServer: serverHook, transformIndexHtml, ...rest } = plugin;
+    return {
+        ...rest,
+        ...(config === undefined ? {} : { config: guardedConfig(config, dir) }),
+        ...(serverHook === undefined || isOneShot ? {} : { configureServer: handlerOf(serverHook) }),
+        ...(transformIndexHtml === undefined ? {} : { transformIndexHtml: guardedHtml(transformIndexHtml) })
+    };
+};
+/**
+ * What a configuration sets that a catalogue cannot do: stories would differ from the app without a word otherwise.
+ *
+ * @param config - the configuration, loaded.
+ * @param environment - what it was loaded for.
+ * @param text - the file's text.
+ */
+const configNotes = (config, environment, text) => [
+    ...(config.css?.modules !== undefined && config.css.modules !== false
+        ? [
+            "css.modules is not read: a catalogue compiles CSS modules with Lightning CSS, so localsConvention and the like do not apply; set css.lightningcss.cssModules"
+        ]
+        : []),
+    ...(/\bjsxImportSource\b/.test(text)
+        ? [
+            "jsxImportSource is not read from the framework's plugin, which the adapter makes itself: give it to the adapter in the catalogue's configuration (react({ jsxImportSource }))"
+        ]
+        : []),
+    ...(environment.command === "build" &&
+        Object.keys(config.define ?? {}).some((name) => WHOLE_ENVIRONMENT.has(name)) &&
+        Object.keys(withoutWholeEnvironment(config.define ?? {})).length !== Object.keys(config.define ?? {}).length
+        ? ["define writes out a whole environment (process.env), which is left out of the catalogue's build"]
+        : [])
+];
+/**
+ * Loads the app's Vite configuration, and takes what a catalogue takes of it.
+ *
+ * @param dir - the catalogue's folder.
+ * @param file - the file, from there.
+ * @param environment - the command and the mode it is loaded for: a configuration may be a function of them.
+ * @param framework - the adapter's name.
+ * @param options - what the catalogue's configuration asks.
+ * @param isReadingPaths - whether Vite reads `tsconfig` paths here.
+ * @param isOneShot - whether the server is a one-shot command's.
+ * @throws what the file throws when it loads.
+ */
+export const loadAppViteConfig = async (dir, file, environment, framework, options, isReadingPaths, isOneShot) => {
+    const { loadConfigFromFile } = await import("vite");
+    const path = resolve(dir, file);
+    const loaded = await loadConfigFromFile(environment, path, dir, "silent");
+    const config = loaded?.config ?? {};
+    const written = await flatPlugins(config.plugins);
+    const isKept = (plugin) => keepsAppPlugin(plugin.name, framework, options, isReadingPaths);
+    const home = dirname(path);
+    return {
+        file,
+        fields: appConfigFields(config, home),
+        plugins: written.filter(isKept).map((plugin) => guardedAppPlugin(plugin, home, isOneShot)),
+        leftOut: [...new Set(written.filter((plugin) => !isKept(plugin)).map((plugin) => plugin.name))],
+        postcssPlugins: inlinePostcssPlugins(config),
+        notes: configNotes(config, environment, readFileSync(path, "utf8"))
+    };
+};

package/dist/bin/forgebook/appBuild/tsconfigPaths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The files a `tsconfig`'s text points to: its `extends` and `references`, those a path names (a package's are left out,
+ * since a package's shared configuration has no `paths` of the project's).
+ *
+ * @param text - the file's text.
+ * @returns the paths as written.
+ */
+export declare const namedTsconfigs: (text: string) => readonly string[];
+/**
+ * Whether a project's `tsconfig` files declare `paths`.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const hasTsconfigPaths: (dir: string) => boolean;

package/dist/bin/forgebook/appBuild/tsconfigPaths.js

@@ -0,0 +1,80 @@
+/**
+ * Whether a project's `tsconfig.json` declares `paths`, so a catalogue can turn on Vite's reading of them only for a
+ * project that has some.
+ *
+ * @remarks
+ * Vite resolves them itself (`resolve.tsconfigPaths`), and asks the resolver to look for a `tsconfig` for every module,
+ * so a project with no `paths` is not made to pay. Nothing here runs: the files are searched as text, comments and all,
+ * because the compiler is far too slow to load for one question and a false yes only costs that small price. A template
+ * often keeps `paths` in a file the main one names under `references` or `extends` (`tsconfig.app.json`,
+ * a monorepo's `tsconfig.base.json`), so those are followed.
+ *
+ * @module
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** The files a project's search starts from. */
+const STARTING_FILES = ["tsconfig.json", "tsconfig.app.json"];
+/** How many files a search reads: a chain is short, and the files are the project's to write. */
+const MAX_FILES = 32;
+/** The largest file read, in bytes. */
+const MAX_FILE_SIZE = 1_000_000;
+/** A `paths` key, or a `baseUrl`, which Vite resolves through as well. */
+const PATHS_KEY = /"(?:paths|baseUrl)"\s*:/;
+/** The value of an `extends` key, one path or a list. */
+const EXTENDS_VALUE = /"extends"\s*:\s*("[^"\n]+"|\[[^\]]*\])/;
+/** The list under a `references` key. */
+const REFERENCES_VALUE = /"references"\s*:\s*\[([^\]]*)\]/;
+/** A text in JSON. */
+const QUOTED = /"([^"\n]+)"/g;
+/** A `path` key of a reference. */
+const REFERENCE_PATH = /"path"\s*:\s*"([^"\n]+)"/g;
+/**
+ * The files a `tsconfig`'s text points to: its `extends` and `references`, those a path names (a package's are left out,
+ * since a package's shared configuration has no `paths` of the project's).
+ *
+ * @param text - the file's text.
+ * @returns the paths as written.
+ */
+export const namedTsconfigs = (text) => {
+    const extended = [...(text.match(EXTENDS_VALUE)?.[1] ?? "").matchAll(QUOTED)].flatMap((each) => each[1] === undefined ? [] : [each[1]]);
+    const referenced = [...(text.match(REFERENCES_VALUE)?.[1] ?? "").matchAll(REFERENCE_PATH)].flatMap((each) => (each[1] === undefined ? [] : [each[1]]));
+    // a bare `extends` is a package's; a bare reference is a file beside this one
+    return [...extended.filter((path) => path.startsWith(".")), ...referenced];
+};
+/**
+ * The file a path in a `tsconfig` names: the path itself, its `.json`, or a folder's `tsconfig.json`.
+ *
+ * @param from - the folder of the file that names it.
+ * @param path - the path as written.
+ */
+const namedFile = (from, path) => {
+    const named = resolve(from, path);
+    return [named, `${named}.json`, join(named, "tsconfig.json")].find((file) => existsSync(file) && statSync(file).isFile());
+};
+/**
+ * Whether a project's `tsconfig` files declare `paths`.
+ *
+ * @param dir - the project's folder.
+ */
+export const hasTsconfigPaths = (dir) => {
+    const queue = STARTING_FILES.map((name) => join(dir, name)).filter((file) => existsSync(file));
+    const seen = new Set(queue);
+    for (const file of queue) {
+        if (seen.size > MAX_FILES)
+            return false;
+        if (statSync(file).size > MAX_FILE_SIZE)
+            continue;
+        const text = readFileSync(file, "utf8");
+        if (PATHS_KEY.test(text))
+            return true;
+        for (const path of namedTsconfigs(text)) {
+            const named = namedFile(dirname(file), path);
+            if (named !== undefined && !seen.has(named)) {
+                seen.add(named);
+                queue.push(named);
+            }
+        }
+    }
+    return false;
+};

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

@@ -0,0 +1,8 @@
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const auditCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/auditCommand.mjs

@@ -0,0 +1,75 @@
+/**
+ * `forgebook audit`: the values and components a project actually uses, with no catalogue and no configuration.
+ *
+ * @module
+ */
+import { 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 { parsedColor } from "../../src/vite/nearestToken.js";
+import { auditDocument, auditSitesDocument, auditText, printable } from "./auditRun.js";
+import { COMMAND } from "./catalogueCommands.js";
+/** A list's limit, when it can be one. */
+const checkedLimit = (limit) => {
+    if (limit !== undefined && !(Number.isInteger(limit) && limit > 0)) {
+        throw new ScriptError("--limit takes a whole number above 0", { exitCode: EXIT.usage });
+    }
+    return limit;
+};
+/** A value to look for, when it can be read: a word that is neither would answer that it is not there. */
+const checkedValue = (value) => {
+    if (parsedColor(value) === undefined && !/^-?\d*\.?\d+(?:px|rem)?$/.test(value)) {
+        throw new ScriptError(`Cannot read "${value}" as a colour or a size: write it as code does`, {
+            exitCode: EXIT.usage
+        });
+    }
+    return value;
+};
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const auditCommands = (forgebook) => ({
+    audit: forgebook.command({
+        summary: "Report the colours, sizes and components a project actually uses, with what to do next.",
+        json: true,
+        positionals: [{ name: "folder", description: "The project's folder; the current one by default." }],
+        options: {
+            value: {
+                type: "string",
+                valueName: "value",
+                description: "List where this value is written by hand, instead of the report."
+            },
+            limit: {
+                type: "number",
+                valueName: "n",
+                description: "How many values each list gives; 10 by default."
+            }
+        },
+        examples: [
+            { command: `${COMMAND} audit`, description: "What this project uses." },
+            {
+                command: `${COMMAND} audit --json`,
+                description: "The same with `actions`, the next steps, for an agent."
+            },
+            {
+                command: `${COMMAND} audit --value "#64748b" --json`,
+                description: "Every place to edit for one of them."
+            }
+        ],
+        run: ({ positionals, options, io, isJson }) => {
+            const dir = resolve(positionals[0] ?? ".");
+            if (options.value === undefined) {
+                const document = auditDocument(dir, checkedLimit(options.limit), positionals[0] ?? ".");
+                io.stdout.write(isJson ? formatJson(document) : `${printable(auditText(document))}\n`);
+                return;
+            }
+            const found = auditSitesDocument(dir, checkedValue(options.value));
+            const lines = found.sites.map(({ file, line, text }) => `${file}:${line}  ${text}`);
+            const text = printable(lines.join("\n")) || `${options.value} is not written by hand.`;
+            io.stdout.write(isJson ? formatJson(found) : `${text}\n`);
+        }
+    })
+});

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

@@ -0,0 +1,95 @@
+/**
+ * What `forgebook audit` does: reads a project's files, with no catalogue and no configuration, and reports the values and
+ * components it actually uses, with what to do next.
+ *
+ * @remarks
+ * Nothing of the project runs and nothing is written. It is meant for a project with no design system: the first question
+ * there is what the system already is in practice, and that needs no setup. A report is not a verdict, so it exits 0
+ * whatever it finds; `check-code` is what fails.
+ *
+ * @module
+ */
+import { type AuditSite, type AuditSystem, type ValueAudit } from "../../src/vite/appAudit.ts";
+import { type LookAlike } from "../../src/vite/lookAlikes.ts";
+import { type CoverageComponent, type StoryCoverage, type UnusedStoriedComponent } from "../../src/vite/storyCoverage.ts";
+/** The next step a report proposes. */
+export type AuditAction = {
+    /** What kind of step. */
+    readonly kind: "use-token" | "name-value" | "merge-values" | "merge-components" | "write-stories" | "check-unused";
+    /** What to do, in a sentence. */
+    readonly message: string;
+    /** How many places it touches. */
+    readonly count: number;
+    /** The command that lists them, when one does: to read, since quoting differs between shells. */
+    readonly command?: string;
+    /** The same command as its words, to run without a shell. */
+    readonly args?: readonly string[];
+    /** The components it is about, with where they are. */
+    readonly members?: readonly CoverageComponent[];
+};
+/** What `forgebook audit` answers. */
+export type AuditDocument = ValueAudit & {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** The system the report read. */
+    readonly system: AuditSystem;
+    /** The components. */
+    readonly components: {
+        /** How many were found. */
+        readonly count: number;
+        /** Those that look like one, the surest first. */
+        readonly lookAlikes: readonly LookAlike[];
+        /** How many story files were read. */
+        readonly storyFileCount: StoryCoverage["storyFileCount"];
+        /** How many exported components some story is about. */
+        readonly withStories: StoryCoverage["withStories"];
+        /** Exported components no story file is about; pages, layouts and routes left out. */
+        readonly withoutStories: readonly CoverageComponent[];
+        /** Components with stories that no file other than a story or a test imports or draws. */
+        readonly storiesUnused: readonly UnusedStoriedComponent[];
+        /** Components with stories not judged unused because their package is published, so used outside. */
+        readonly publishedWithStories: StoryCoverage["published"];
+    };
+    /** What to do next, the largest gain first. */
+    readonly actions: readonly AuditAction[];
+};
+/** What `forgebook audit --value` answers. */
+export type AuditSitesDocument = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** The value asked about. */
+    readonly value: string;
+    /** Where it is written by hand. */
+    readonly sites: readonly AuditSite[];
+    /** What could not be read, so the list may be short. */
+    readonly notes: readonly string[];
+};
+/**
+ * The report on a project.
+ *
+ * @param dir - its folder.
+ * @param top - how many values a list gives.
+ * @param folder - the folder as the command was given it, for the commands an answer proposes.
+ */
+export declare const auditDocument: (dir: string, top: number | undefined, folder?: string) => AuditDocument;
+/**
+ * Where a value is written by hand.
+ *
+ * @param dir - the project's folder.
+ * @param value - the value.
+ */
+export declare const auditSitesDocument: (dir: string, value: string) => AuditSitesDocument;
+/**
+ * A text from a project's files as a terminal may show it: a newline or an escape in a file's name could otherwise draw
+ * a line of this report.
+ *
+ * @param text - the text.
+ */
+export declare const printable: (text: string) => string;
+/**
+ * The report as a person reads it. What a project's files hold is data for whoever reads this: it says what is there and is
+ * not an instruction, which holds for an agent reading `--json` too.
+ *
+ * @param document - the report.
+ */
+export declare const auditText: (document: AuditDocument) => string;