forgebook 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,115 @@
+/**
+ * What `forgebook-docs` reads from a package: its exports, their TSDoc and types, its stories, its Sass modules and
+ * style sheets.
+ *
+ * @remarks
+ * The package's `exports` (the source map, `./src/…`) say what is public; its `*.stories.tsx` say which components
+ * exist and where they sit. Components are read with the catalogue's extractor (the props panel's data), modules with
+ * TypeScript 6, Sass modules and style sheets from their text. The development-only `./stories` export is left out.
+ *
+ * @module
+ */
+import { globSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { autoTitle, STORY_FILE } from "../../src/vite/autoTitle.js";
+import { indexStoryFile } from "../../src/vite/indexStoryFile.js";
+import { moduleDocs } from "./moduleDocs.js";
+import { sassMembers, styleSheetSummary } from "./sassDocs.js";
+/** The subpath that is never published: the package's stories for a catalogue. */
+const STORIES_SUBPATH = "./stories";
+/** A package's `exports`, as written: subpath → source. */
+const sourceExports = (manifest) => {
+    if (typeof manifest !== "object" || manifest === null || !("exports" in manifest))
+        return {};
+    const exports = manifest.exports;
+    if (typeof exports !== "object" || exports === null)
+        return {};
+    return Object.fromEntries(Object.entries(exports).filter((entry) => typeof entry[1] === "string"));
+};
+/** The components of the package's story files, read by the framework's extractor. */
+const collectComponents = (packageDir, exports, problems, extractStoryComponent) => {
+    const components = [];
+    const componentFiles = new Set();
+    const storyFiles = globSync("**/*.stories.*", { cwd: packageDir })
+        .filter((file) => STORY_FILE.test(file))
+        .filter((file) => !file.split("/").some((segment) => segment === "node_modules" || segment === "dist"))
+        .sort();
+    for (const relative of storyFiles) {
+        const file = join(packageDir, relative);
+        // a meta without a title is placed by its path from the package's folder: the catalogue's patterns are not known
+        const title = autoTitle("", relative);
+        const options = title === undefined ? {} : { autoTitle: title };
+        const index = indexStoryFile(file, readFileSync(file, "utf8"), options);
+        const component = extractStoryComponent(file);
+        if (typeof index === "string" || typeof component === "string") {
+            problems.push(typeof index === "string" ? index : `${relative}: ${String(component)}`);
+            continue;
+        }
+        if (!("file" in component))
+            continue;
+        const subpath = Object.entries(exports).find(([, source]) => resolve(packageDir, source) === component.file)?.[0];
+        // a component no subpath exports is a story's own (a foundations page), not part of the package
+        if (subpath === undefined)
+            continue;
+        componentFiles.add(component.file);
+        components.push({
+            title: index.title,
+            subpath,
+            docs: component.docs,
+            stories: index.stories.map((story) => story.name ?? story.exportName)
+        });
+    }
+    return { components, componentFiles };
+};
+/** Reads one export: a Sass module, a style sheet or a module. */
+const readExport = (subpath, source, file) => {
+    if (source.startsWith("./src/scss/")) {
+        return { kind: "sass", docs: { subpath, members: sassMembers(readFileSync(file, "utf8")) } };
+    }
+    if (subpath.endsWith(".css")) {
+        return { kind: "sheet", docs: { subpath, summary: styleSheetSummary(readFileSync(file, "utf8")) } };
+    }
+    if (!/\.tsx?$/.test(source))
+        return { kind: "other" };
+    const docs = moduleDocs(file);
+    return typeof docs === "string"
+        ? { kind: "problem", message: docs }
+        : { kind: "module", docs: { subpath, exports: docs } };
+};
+/**
+ * Reads a package for its catalogue.
+ *
+ * @param packageDir - the package's folder.
+ * @param extractStoryComponent - the framework's reading of a story file's component (its docs module).
+ */
+export const collectDocs = (packageDir, extractStoryComponent) => {
+    const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+    const packageName = typeof manifest === "object" &&
+        manifest !== null &&
+        "name" in manifest &&
+        typeof manifest.name === "string"
+        ? manifest.name
+        : packageDir;
+    const exports = sourceExports(manifest);
+    const problems = [];
+    const { components, componentFiles } = collectComponents(packageDir, exports, problems, extractStoryComponent);
+    const modules = [];
+    const sassModules = [];
+    const styleSheets = [];
+    for (const [subpath, source] of Object.entries(exports)) {
+        const file = resolve(packageDir, source);
+        if (subpath === STORIES_SUBPATH || componentFiles.has(file))
+            continue;
+        const entry = readExport(subpath, source, file);
+        if (entry.kind === "sass")
+            sassModules.push(entry.docs);
+        if (entry.kind === "sheet")
+            styleSheets.push(entry.docs);
+        if (entry.kind === "module")
+            modules.push(entry.docs);
+        if (entry.kind === "problem")
+            problems.push(entry.message);
+    }
+    return { data: { packageName, components, modules, sassModules, styleSheets }, problems };
+};
+//# sourceMappingURL=collectDocs.js.map

package/dist/bin/forgebook-docs/collectDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectDocs.js","sourceRoot":"","sources":["../../../bin/forgebook-docs/collectDocs.ts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-docs/forgebook-docs.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=forgebook-docs.d.mts.map

package/dist/bin/forgebook-docs/forgebook-docs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-docs.d.mts","sourceRoot":"","sources":["../../../bin/forgebook-docs/forgebook-docs.mts"],"names":[],"mappings":""}

package/dist/bin/forgebook-docs/forgebook-docs.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * The `forgebook-docs` command: writes a package's `CATALOG.md` from its exports, their TSDoc and its stories, or
+ * checks that it is up to date.
+ *
+ * @remarks
+ * Usage: `forgebook-docs --help` (generated by `@ensiria/cli-kit`). A package with stories declares
+ * `forgebook` as a development dependency and runs it on itself (`"catalog": "forgebook-docs --package ."`;
+ * D-62, D-67).
+ *
+ * @module
+ */
+import { createRequire } from "node:module";
+import { join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readFileSafe, writeIfChanged } from "@ensiria/cli-kit/files";
+import { plural } from "@ensiria/cli-kit/format";
+import { defineScript, ScriptError } from "@ensiria/cli-kit/script";
+import { isDocsModule } from "../../src/vite/adapter.js";
+import { catalogueMarkdown } from "./catalogueMarkdown.js";
+import { collectDocs } from "./collectDocs.js";
+/** The command, as the hints print it. */
+const COMMAND = "forgebook-docs";
+/**
+ * The framework's reading of a story file's component: the docs module of `@forgebook/<framework>`, resolved from the
+ * package, which declares that framework package.
+ *
+ * @param packageDir - the package's folder.
+ * @param framework - the framework's name (`react`).
+ * @throws a `ScriptError` when the package cannot resolve it or the module is not a docs module.
+ */
+const extractorOf = async (packageDir, framework) => {
+    const specifier = `@forgebook/${framework}/docs`;
+    let file;
+    try {
+        file = createRequire(join(packageDir, "package.json")).resolve(specifier);
+    }
+    catch {
+        throw new ScriptError(`${specifier} is not installed in this package`, {
+            hint: `Add @forgebook/${framework} to its devDependencies`
+        });
+    }
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    if (!isDocsModule(module))
+        throw new ScriptError(`${specifier} exports no extractStoryComponent`);
+    return module.extractStoryComponent;
+};
+await defineScript({
+    name: "forgebook-docs",
+    command: COMMAND,
+    summary: "Write a package's CATALOG.md from its exports, their TSDoc and its stories.",
+    icon: "docs",
+    json: true,
+    description: "Reads the package's exports (components from its stories, modules with TypeScript 6, Sass modules and style sheets from their text) and writes CATALOG.md in its folder: one dense line per entry, for agents to read before writing a component, hook or helper.",
+    options: {
+        package: {
+            type: "string",
+            required: true,
+            valueName: "folder",
+            description: "The package's folder (packages/design-system)."
+        },
+        framework: {
+            type: "string",
+            default: "react",
+            valueName: "name",
+            description: "The framework the stories are written for: its package, @forgebook/<name>, reads the components' props."
+        },
+        check: {
+            type: "boolean",
+            short: "c",
+            description: "Change nothing; fail when CATALOG.md is stale or a file cannot be read (CI)."
+        }
+    },
+    examples: [
+        { command: `${COMMAND} --package .`, description: "Rewrite the CATALOG.md of the package you are in." },
+        { command: `${COMMAND} --package . --check`, description: "Check it in CI." }
+    ],
+    run: async ({ options, log }) => {
+        const packageDir = resolve(options.package);
+        const file = join(packageDir, "CATALOG.md");
+        const shownFile = relative(process.cwd(), file);
+        const { data, problems } = collectDocs(packageDir, await extractorOf(packageDir, options.framework));
+        for (const problem of problems)
+            log.error(problem);
+        const text = catalogueMarkdown(data);
+        const counts = {
+            components: data.components.length,
+            modules: data.modules.length,
+            sassModules: data.sassModules.length,
+            styleSheets: data.styleSheets.length
+        };
+        if (options.check) {
+            if (problems.length > 0)
+                throw new ScriptError(`${plural(problems.length, "file")} could not be read`);
+            if (readFileSafe(file) !== text)
+                throw new ScriptError(`${shownFile} is stale`, {
+                    hint: `Run ${COMMAND} --package ${relative(process.cwd(), packageDir)}`
+                });
+            log.success(`${shownFile} is up to date`);
+            return { status: "valid", file: shownFile, counts, problems };
+        }
+        const isWritten = writeIfChanged(file, text);
+        log.success(`${shownFile} ${isWritten ? "written" : "already up to date"}`);
+        return { status: isWritten ? "written" : "up-to-date", file: shownFile, counts, problems };
+    }
+}).run();
+//# sourceMappingURL=forgebook-docs.mjs.map

package/dist/bin/forgebook-docs/forgebook-docs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-docs.mjs","sourceRoot":"","sources":["../../../bin/forgebook-docs/forgebook-docs.mts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-docs/moduleDocs.d.ts

@@ -0,0 +1,9 @@
+import type { ExportDocs } from "./catalogueDocs.types.ts";
+/**
+ * The exports of a module.
+ *
+ * @param file - the module's absolute path.
+ * @returns its exports in the module's order, or a message saying why it cannot be read.
+ */
+export declare const moduleDocs: (file: string) => ExportDocs[] | string;
+//# sourceMappingURL=moduleDocs.d.ts.map

package/dist/bin/forgebook-docs/moduleDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleDocs.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/moduleDocs.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAkC3D;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,UAAU,EAAE,GAAG,MAWxD,CAAC"}

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

@@ -0,0 +1,62 @@
+/**
+ * A module's exports with their kind, parameters and summary, read with TypeScript 6's compiler API.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { programFor, summaryOf } from "../../src/vite/docsProgram.js";
+/**
+ * A parameter's own name: a destructured one (`({ name, ...props })`, which TypeScript calls `__0`) takes the name
+ * its `@param` tag gives it, or `{…}` without one.
+ */
+const ownName = (parameter, declaration) => {
+    if (ts.isIdentifier(declaration.name))
+        return parameter.getName();
+    const tag = ts.getJSDocParameterTags(declaration)[0];
+    return tag === undefined ? "{…}" : tag.name.getText();
+};
+/** A parameter's name as the catalogue writes it: `...rest`, `name?`, `name`. */
+const parameterName = (parameter) => {
+    const declaration = parameter.valueDeclaration;
+    if (declaration === undefined || !ts.isParameter(declaration))
+        return parameter.getName();
+    const name = ownName(parameter, declaration);
+    if (declaration.dotDotDotToken !== undefined)
+        return `...${name}`;
+    if (declaration.questionToken !== undefined || declaration.initializer !== undefined)
+        return `${name}?`;
+    return name;
+};
+/** One export's docs. */
+const exportDocs = (exported, checker, location) => {
+    const symbol = exported.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(exported) : exported;
+    const name = exported.getName();
+    const summary = summaryOf(symbol, checker);
+    if (symbol.flags & (ts.SymbolFlags.TypeAlias | ts.SymbolFlags.Interface))
+        return { name, kind: "type", summary };
+    const [signature] = checker.getTypeOfSymbolAtLocation(symbol, location).getCallSignatures();
+    if (signature === undefined)
+        return { name, kind: "value", summary };
+    return { name, kind: "function", parameters: signature.parameters.map(parameterName), summary };
+};
+/**
+ * The exports of a module.
+ *
+ * @param file - the module's absolute path.
+ * @returns its exports in the module's order, or a message saying why it cannot be read.
+ */
+export const moduleDocs = (file) => {
+    const program = programFor(file);
+    if (typeof program === "string")
+        return program;
+    const source = program.program.getSourceFile(file);
+    const moduleSymbol = source === undefined ? undefined : program.checker.getSymbolAtLocation(source);
+    if (source === undefined || moduleSymbol === undefined)
+        return `${file} has no exports`;
+    const position = (symbol) => symbol.declarations?.[0]?.getStart() ?? 0;
+    return program.checker
+        .getExportsOfModule(moduleSymbol)
+        .sort((left, right) => position(left) - position(right))
+        .map((symbol) => exportDocs(symbol, program.checker, source));
+};
+//# sourceMappingURL=moduleDocs.js.map

package/dist/bin/forgebook-docs/moduleDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleDocs.js","sourceRoot":"","sources":["../../../bin/forgebook-docs/moduleDocs.ts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-docs/sassDocs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The mixins and functions of a public Sass module, with the first line of their `///` comment, and the summary of a
+ * style sheet: read from the text, no Sass compiler needed.
+ *
+ * @module
+ */
+import type { SassMemberDocs } from "./catalogueDocs.types.ts";
+/**
+ * The documented members of a Sass module.
+ *
+ * @param text - the module's source.
+ */
+export declare const sassMembers: (text: string) => SassMemberDocs[];
+/**
+ * The first sentence of a style sheet's leading `//` comment.
+ *
+ * @param text - the style sheet's source.
+ */
+export declare const styleSheetSummary: (text: string) => string;
+//# sourceMappingURL=sassDocs.d.ts.map

package/dist/bin/forgebook-docs/sassDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sassDocs.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-docs/sassDocs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAK/D;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,cAAc,EA2BxD,CAAC;AAyBF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAShD,CAAC"}

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

@@ -0,0 +1,77 @@
+/** A mixin or function declaration and its parameter list. */
+const MEMBER = /^@(mixin|function)\s+([\w-]+)\s*(?:\(([^)]*)\))?/;
+/**
+ * The documented members of a Sass module.
+ *
+ * @param text - the module's source.
+ */
+export const sassMembers = (text) => {
+    const members = [];
+    let comment = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("///")) {
+            comment.push(trimmed.slice(3).trim());
+            continue;
+        }
+        // a declaration may span lines: its first line is enough for the name, the parameters come from the whole text
+        const match = MEMBER.exec(trimmed);
+        if (match !== null) {
+            const [, kind = "mixin", name = ""] = match;
+            const parameterText = parametersAfter(text, name);
+            members.push({
+                kind: kind === "function" ? "function" : "mixin",
+                name,
+                parameters: parameterText
+                    .split(",")
+                    .map((parameter) => parameter.split(":")[0]?.trim() ?? "")
+                    .filter((parameter) => parameter.startsWith("$")),
+                summary: summaryOfComment(comment)
+            });
+        }
+        comment = [];
+    }
+    return members;
+};
+/** A `///` comment's summary: its lines up to the first blank line or tag, joined. */
+const summaryOfComment = (comment) => {
+    const end = comment.findIndex((entry) => entry === "" || entry.startsWith("@"));
+    return comment
+        .slice(0, end === -1 ? comment.length : end)
+        .join(" ")
+        .trim();
+};
+/** The parameter list of a declaration, across lines. */
+const parametersAfter = (text, name) => {
+    const start = text.search(new RegExp(`@(?:mixin|function)\\s+${name}\\s*\\(`));
+    if (start === -1)
+        return "";
+    const open = text.indexOf("(", start);
+    let depth = 0;
+    for (let index = open; index < text.length; index++) {
+        if (text[index] === "(")
+            depth++;
+        if (text[index] === ")")
+            depth--;
+        if (depth === 0)
+            return text.slice(open + 1, index);
+    }
+    return "";
+};
+/**
+ * The first sentence of a style sheet's leading `//` comment.
+ *
+ * @param text - the style sheet's source.
+ */
+export const styleSheetSummary = (text) => {
+    const lines = [];
+    for (const line of text.split("\n")) {
+        if (!line.startsWith("//"))
+            break;
+        lines.push(line.slice(2).trim());
+    }
+    const comment = lines.join(" ");
+    const end = comment.search(/\.(\s|$)/);
+    return end === -1 ? comment : comment.slice(0, end + 1);
+};
+//# sourceMappingURL=sassDocs.js.map

package/dist/bin/forgebook-docs/sassDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sassDocs.js","sourceRoot":"","sources":["../../../bin/forgebook-docs/sassDocs.ts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-texts/forgebook-texts.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=forgebook-texts.d.mts.map

package/dist/bin/forgebook-texts/forgebook-texts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-texts.d.mts","sourceRoot":"","sources":["../../../bin/forgebook-texts/forgebook-texts.mts"],"names":[],"mappings":""}

package/dist/bin/forgebook-texts/forgebook-texts.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * The `forgebook-texts` command: checks a package's story texts against the keys its stories use, and lists what each
+ * language still has to translate.
+ *
+ * @remarks
+ * Usage: `forgebook-texts --help` (generated by `@ensiria/cli-kit`). A package with stories runs it on itself
+ * (`"texts": "forgebook-texts --package ."`), with `--check` in CI.
+ *
+ * @module
+ */
+import { globSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { plural } from "@ensiria/cli-kit/format";
+import { defineScript, ScriptError } from "@ensiria/cli-kit/script";
+import { storyTextsReport } from "./storyTextsReport.js";
+/** The command, as the hints print it. */
+const COMMAND = "forgebook-texts";
+/** Where a package's story files and fixtures are, relative to it. */
+const SOURCE_PATTERNS = ["src/**/*.stories.tsx", "stories/**/*.{ts,tsx}"];
+/** A locale file's table, read as JSON. */
+const readTable = (file) => {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new ScriptError(`${file} is not an object of texts`);
+    }
+    const entries = Object.entries(value);
+    const bad = entries.find(([, text]) => typeof text !== "string");
+    if (bad !== undefined)
+        throw new ScriptError(`${file}: "${bad[0]}" is not a text`);
+    return Object.fromEntries(entries.map(([key, text]) => [key, String(text)]));
+};
+await defineScript({
+    name: "forgebook-texts",
+    command: COMMAND,
+    summary: "Check a package's story texts and list what each language still has to translate.",
+    icon: "check",
+    json: true,
+    description: 'Reads the keys the stories use (every text("key") in its story files and story fixtures) and the locale files (stories/locales/<id>.json by default, en holding every key), and reports keys missing in English, English keys no story uses, and, for each other language, the texts it lacks with their English, ready to translate.',
+    options: {
+        package: {
+            type: "string",
+            required: true,
+            valueName: "folder",
+            description: "The package's folder (packages/design-system)."
+        },
+        locales: {
+            type: "string",
+            default: "stories/locales",
+            valueName: "folder",
+            description: "The locale files' folder, relative to the package."
+        },
+        check: {
+            type: "boolean",
+            short: "c",
+            description: "Fail when a key is missing in English or an English key is unused (CI); untranslated texts do not fail."
+        }
+    },
+    examples: [
+        { command: `${COMMAND} --package .`, description: "Report the package's story texts." },
+        {
+            command: `${COMMAND} --package . --json`,
+            description: "The texts each language lacks, for a translator."
+        },
+        { command: `${COMMAND} --package . --check`, description: "Check them in CI." }
+    ],
+    run: ({ options, log }) => {
+        const packageDir = resolve(options.package);
+        const localesDir = join(packageDir, options.locales);
+        const sources = SOURCE_PATTERNS.flatMap((pattern) => globSync(pattern, { cwd: packageDir })).map((file) => readFileSync(join(packageDir, file), "utf8"));
+        const locales = Object.fromEntries(globSync("*.json", { cwd: localesDir }).map((file) => [
+            basename(file, ".json"),
+            readTable(join(localesDir, file))
+        ]));
+        if (locales["en"] === undefined && sources.length > 0) {
+            log.warn(`${relative(process.cwd(), localesDir)}/en.json does not exist: no story text is translatable yet`);
+        }
+        const report = storyTextsReport(sources, locales);
+        for (const key of report.missing)
+            log.error(`missing in en.json: ${key}`);
+        for (const key of report.unused)
+            log.warn(`unused in en.json: ${key}`);
+        for (const [language, texts] of Object.entries(report.untranslated)) {
+            if (texts.length > 0)
+                log.info(`${language}: ${plural(texts.length, "text")} to translate`);
+        }
+        if (options.check && (report.missing.length > 0 || report.unused.length > 0)) {
+            throw new ScriptError(`${plural(report.missing.length, "missing key")}, ${plural(report.unused.length, "unused key")}`, { hint: `Fix ${relative(process.cwd(), join(localesDir, "en.json"))} or the stories` });
+        }
+        log.success(`${plural(report.used, "key")} used, every one in en.json`);
+        return report;
+    }
+}).run();
+//# sourceMappingURL=forgebook-texts.mjs.map

package/dist/bin/forgebook-texts/forgebook-texts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"forgebook-texts.mjs","sourceRoot":"","sources":["../../../bin/forgebook-texts/forgebook-texts.mts"],"names":[],"mappings":"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"}

package/dist/bin/forgebook-texts/storyTextsReport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The logic of `forgebook-texts`: the keys the stories use, read from their source, set against the package's locale
+ * files.
+ *
+ * @remarks
+ * A story names a text with a string literal, `text("key")` (from `useStoryText()` or `context.text`) or
+ * `storyText("key")` in its args, so every key is found in the source without running it; a key built at run time is not seen, which the format forbids. Pure:
+ * texts in, report out.
+ *
+ * @module
+ */
+import type { StoryTextsReport } from "./storyTextsReport.types.ts";
+/**
+ * The keys a source text uses.
+ *
+ * @param source - a story file's or a fixture's text.
+ */
+export declare const usedKeys: (source: string) => string[];
+/**
+ * The report of a package's story texts.
+ *
+ * @param sources - the text of every story file and fixture.
+ * @param locales - the locale files by language id; `en` is the one every key is in.
+ */
+export declare const storyTextsReport: (sources: readonly string[], locales: Readonly<Record<string, Readonly<Record<string, string>>>>) => StoryTextsReport;
+//# sourceMappingURL=storyTextsReport.d.ts.map

package/dist/bin/forgebook-texts/storyTextsReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storyTextsReport.d.ts","sourceRoot":"","sources":["../../../bin/forgebook-texts/storyTextsReport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,6BAA6B,CAAC;AAKtF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,KAAG,MAAM,EACgB,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,SAAS,MAAM,EAAE,EAC1B,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAClE,gBAkBF,CAAC"}

package/dist/bin/forgebook-texts/storyTextsReport.js

@@ -0,0 +1,35 @@
+/** A call naming a text with a literal key: `text("key")`, `text('key', …)` or an arg's `storyText("key")`. */
+const TEXT_CALL = /\b(?:text|storyText)\(\s*(["'])([^"'\\]+)\1/g;
+/**
+ * The keys a source text uses.
+ *
+ * @param source - a story file's or a fixture's text.
+ */
+export const usedKeys = (source) => [...source.matchAll(TEXT_CALL)].map((match) => match[2] ?? "");
+/**
+ * The report of a package's story texts.
+ *
+ * @param sources - the text of every story file and fixture.
+ * @param locales - the locale files by language id; `en` is the one every key is in.
+ */
+export const storyTextsReport = (sources, locales) => {
+    const used = new Set(sources.flatMap(usedKeys));
+    const base = locales["en"] ?? {};
+    const untranslated = {};
+    for (const [language, table] of Object.entries(locales)) {
+        if (language === "en")
+            continue;
+        untranslated[language] = Object.entries(base)
+            .filter(([key]) => table[key] === undefined)
+            .map(([key, text]) => ({ key, text }));
+    }
+    return {
+        used: used.size,
+        missing: [...used].filter((key) => base[key] === undefined).sort(),
+        unused: Object.keys(base)
+            .filter((key) => !used.has(key))
+            .sort(),
+        untranslated
+    };
+};
+//# sourceMappingURL=storyTextsReport.js.map

package/dist/bin/forgebook-texts/storyTextsReport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storyTextsReport.js","sourceRoot":"","sources":["../../../bin/forgebook-texts/storyTextsReport.ts"],"names":[],"mappings":"AAaA,+GAA+G;AAC/G,MAAM,SAAS,GAAG,8CAA8C,CAAC;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAY,EAAE,CACnD,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,OAA0B,EAC1B,OAAmE,EACjD,EAAE;IACpB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,YAAY,GAAuC,EAAE,CAAC;IAC5D,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACxD,IAAI,QAAQ,KAAK,IAAI;YAAE,SAAS;QAChC,YAAY,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;aAC1C,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;aAC3C,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC,IAAI,EAAE;QAClE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;aACtB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;aAC/B,IAAI,EAAE;QACT,YAAY;KACb,CAAC;AACJ,CAAC,CAAC"}