forgebook 0.3.2 → 0.4.0

package/dist/src/vite/storyCode.js

@@ -1,29 +1,25 @@
 /**
- * The code a story shows in the catalogue's Code card: each story's `render` as written in its file, read with Vite's
- * parser, never run.
+ * The code a story shows in the catalogue's Code card, read from its file with Vite's parser, never run: each story's
+ * `render` as written, and for a story drawn from its args, each arg the file writes as code.
  *
  * @remarks
- * A story without a `render` draws the meta's component with its args: the shell writes that JSX itself from the args
- * of the moment, so only the stories with a `render` need their text. A `render` written elsewhere (a helper the
- * story points to) shows as the name it is given, which is what the file says.
+ * A story's render is its own, else the meta's; a story written as a function (CSF 2), or bound from one
+ * (`Template.bind({})`), is its render. A render kept in a constant or a function of the file shows as that code; one
+ * imported from another file shows as its name, which is what the file says.
+ *
+ * A story without a render draws the meta's component with its args, and the shell writes that component in the
+ * framework's code from the args of the moment. Only plain data crosses from the frame, so a function, an element or
+ * any other code would be missing: this module gives the text of each such arg as written (`icon: <IconStar />`,
+ * `onClick: fn()`), the meta's args under the story's, following spreads of the file's constants and of another
+ * story's args. A plain literal is left to the value the frame reports, which is the same; a constant of the file is
+ * written by its value, an import by its name. What a spread or a value it cannot read may replace is forgotten, so
+ * the shell writes it from the value, never from a text the story does not draw. Pure: text in, texts out.
  *
  * @module
  */
+import { keyName, propertyValue, unwrapped } from "./indexFields.js";
 import { parseStoryFile } from "./storyParse.js";
-/** An expression without the TypeScript wrappers around it (`satisfies`, `as`, parentheses). */
-const unwrapped = (expression) => {
-    if (expression.type === "TSSatisfiesExpression" ||
-        expression.type === "TSAsExpression" ||
-        expression.type === "ParenthesizedExpression") {
-        return unwrapped(expression.expression);
-    }
-    return expression;
-};
-/** The `render` property of a story object, when it has one. */
-const renderOf = (object) => object.properties.find((property) => property.type === "Property" &&
-    !property.computed &&
-    property.key.type === "Identifier" &&
-    property.key.name === "render");
+import { metaObject, objectOf, storyExports, topLevelOf } from "./storyTopLevel.js";
 /**
  * Removes from every line past the first the indentation of the line the code starts on, so a `render` reads as if
  * written at the left edge.
@@ -42,19 +38,242 @@ const indentAt = (text, position) => {
     const line = text.slice(lineStart, position);
     return line.length - line.trimStart().length;
 };
-/** A story's `render` text, when the declaration is a story object with one. */
-const renderText = (declarator, text) => {
-    if (declarator.init === null || declarator.init === undefined)
+/** A node's text, as written, without the indentation of the line it starts on. */
+const textOf = ({ text }, node) => dedented(text.slice(node.start, node.end), indentAt(text, node.start));
+/** The functions the file declares at its top (`function renderGrid() {}`, exported or not), by name. */
+const declaredFunctions = (program) => {
+    const functions = new Map();
+    for (const statement of program.body) {
+        const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+        if (declaration?.type === "FunctionDeclaration" && declaration.id !== null)
+            functions.set(declaration.id.name, declaration);
+    }
+    return functions;
+};
+/** Whether an expression is a function written in place. */
+const isFunction = (expression) => expression.type === "ArrowFunctionExpression" || expression.type === "FunctionExpression";
+/**
+ * The function a name of the file holds: a constant written as one, or a function declaration.
+ *
+ * @param context - the file.
+ * @param name - the name.
+ */
+const functionNamed = (context, name) => {
+    const value = context.top.values.get(name);
+    if (value !== undefined && isFunction(value))
+        return value;
+    return context.functions.get(name);
+};
+/**
+ * The render a story's value is itself: a function (CSF 2), or one bound from a function of the file
+ * (`Template.bind({})`).
+ */
+const storyFunction = (context, value) => {
+    if (value === undefined)
+        return undefined;
+    if (isFunction(value))
+        return value;
+    if (value.type !== "CallExpression" || value.callee.type !== "MemberExpression")
+        return undefined;
+    const { object, property } = value.callee;
+    if (object.type !== "Identifier" || property.type !== "Identifier" || property.name !== "bind")
+        return undefined;
+    return functionNamed(context, object.name);
+};
+/** Whether an expression is `undefined`, which sets a field to none. */
+const isUndefined = (expression) => expression.type === "Identifier" && expression.name === "undefined";
+/**
+ * A field of a story by its local name (`args`, `render`): what is assigned to it after its declaration
+ * (`A.args = …`), else what its object holds. An assignment that reads the field itself (`A.args = { ...A.args }`)
+ * reads the object's, as it does when the file runs.
+ *
+ * @param context - the file.
+ * @param local - the story's local name.
+ * @param field - the field's name.
+ * @param seen - the places followed so far.
+ */
+const storyField = (context, local, field, seen) => {
+    const assignedPlace = `${local}.${field}=`;
+    const objectPlace = `${local}.${field}`;
+    const assigned = context.top.assigned.get(local)?.get(field);
+    if (assigned !== undefined && !seen.has(assignedPlace))
+        return { value: isUndefined(assigned) ? null : assigned, seen: new Set([...seen, assignedPlace]) };
+    const object = objectOf(context.top, context.top.values.get(local));
+    if (object === undefined || seen.has(objectPlace))
+        return { value: undefined, seen };
+    return objectField(context, object, field, new Set([...seen, objectPlace]));
+};
+/**
+ * A field a story object holds: its own property, else the field of the story a spread in it names, the later over
+ * the earlier, as the object has it when the file runs.
+ *
+ * @param context - the file.
+ * @param object - the story's object.
+ * @param field - the field's name.
+ * @param seen - the places followed so far.
+ */
+const objectField = (context, object, field, seen) => {
+    let read = { value: null, seen };
+    for (const property of object.properties) {
+        if (property.type === "SpreadElement") {
+            const argument = unwrapped(property.argument);
+            const spread = argument.type === "Identifier"
+                ? storyField(context, argument.name, field, seen)
+                : { value: undefined, seen };
+            if (spread.value !== null)
+                read = spread;
+        }
+        else if (!property.computed && keyName(property.key) === field) {
+            const value = unwrapped(property.value);
+            read = { value: isUndefined(value) ? null : value, seen };
+        }
+    }
+    return read;
+};
+/** Whether an arg's value is plain data the frame reports as written: a literal, or `undefined`. */
+const isPlainValue = (value) => (value.type === "Literal" && !("regex" in value && value.regex !== undefined) && !("bigint" in value)) ||
+    isUndefined(value);
+/**
+ * An expression's text as written; a method's function (`render(args) {…}`), whose text starts at its parameters, is
+ * written as the function expression it is (`function (args) {…}`), so it can stand on its own.
+ */
+const expressionText = (context, value) => {
+    const text = textOf(context, value);
+    if (value.type !== "FunctionExpression" || !text.startsWith("("))
+        return text;
+    return `${value.async ? "async " : ""}function${value.generator ? "*" : ""} ${text}`;
+};
+/** An arg's text: a constant of the file by its value, anything else as written; none for plain data. */
+const argText = (context, value) => {
+    if (isPlainValue(value))
+        return undefined;
+    const held = value.type === "Identifier" ? context.top.values.get(value.name) : undefined;
+    if (held !== undefined)
+        return isPlainValue(held) ? undefined : expressionText(context, held);
+    return expressionText(context, value);
+};
+/** Forgets every arg written so far: a spread or a value that cannot be read may replace any of them. */
+const forgetAll = (written) => {
+    for (const name of written.keys())
+        written.set(name, undefined);
+};
+/** The story whose args a member expression reads (`First.args`); none for any other. */
+const argsOwner = (member) => {
+    const { object, property } = member;
+    if (member.computed || object.type !== "Identifier" || property.type !== "Identifier")
         return undefined;
-    const init = unwrapped(declarator.init);
-    const render = init.type === "ObjectExpression" ? renderOf(init) : undefined;
-    if (render?.type !== "Property")
+    return property.name === "args" ? object.name : undefined;
+};
+/**
+ * Adds the args an object writes, in order: a later one replaces an earlier one in its place, as a spread does when
+ * the file runs.
+ *
+ * @param context - the file.
+ * @param object - the args' object.
+ * @param written - the args so far.
+ * @param seen - the places followed so far.
+ */
+const writeObjectArgs = (context, object, written, seen) => {
+    for (const property of object.properties) {
+        if (property.type === "SpreadElement") {
+            writeArgsOf(context, property.argument, written, seen);
+            continue;
+        }
+        const name = property.computed ? undefined : keyName(property.key);
+        if (name === undefined)
+            forgetAll(written);
+        else
+            written.set(name, argText(context, unwrapped(property.value)));
+    }
+};
+/**
+ * Adds the args a value writes to those written so far: an object in place or a constant of the file, or another
+ * story's (`First.args`); one that cannot be read forgets them all.
+ *
+ * @param context - the file.
+ * @param value - the args' value.
+ * @param written - the args so far.
+ * @param seen - the places followed so far.
+ */
+const writeArgsOf = (context, value, written, seen) => {
+    const plain = unwrapped(value);
+    if (plain.type === "MemberExpression") {
+        const story = argsOwner(plain);
+        const read = story === undefined ? { value: undefined, seen } : storyField(context, story, "args", seen);
+        if (read.value === undefined)
+            forgetAll(written);
+        else if (read.value !== null)
+            writeArgsOf(context, read.value, written, read.seen);
+        return;
+    }
+    const object = objectOf(context.top, plain);
+    if (object === undefined)
+        forgetAll(written);
+    else
+        writeObjectArgs(context, object, written, seen);
+};
+/**
+ * An args story's args written as code: the meta's, then the story's over them.
+ *
+ * @param context - the file.
+ * @param meta - the meta's object, when the file has one written plainly.
+ * @param local - the story's local name.
+ */
+const writtenArgsOf = (context, meta, local) => {
+    const written = new Map();
+    const metaArgs = meta === undefined ? undefined : propertyValue(meta, "args");
+    if (metaArgs !== undefined)
+        writeArgsOf(context, metaArgs, written, new Set());
+    const own = storyField(context, local, "args", new Set());
+    if (own.value === undefined)
+        forgetAll(written);
+    else if (own.value !== null)
+        writeArgsOf(context, own.value, written, own.seen);
+    return Object.fromEntries([...written].flatMap(([name, text]) => (text === undefined ? [] : [[name, text]])));
+};
+/** A render's text: the code a name of the file holds, else the expression as written, a method as a function. */
+const renderText = (context, render) => {
+    const held = render.type === "Identifier" ? functionNamed(context, render.name) : undefined;
+    return expressionText(context, held ?? render);
+};
+/**
+ * A story's render text, by its local name: its own `render` (assigned after it, in its object or in a story it
+ * spreads), else the story itself when it is a function, else the meta's; none for a story drawn from its args, or
+ * one whose render cannot be read (a helper's result), which is written from its values.
+ *
+ * @param context - the file.
+ * @param local - the story's local name.
+ * @param metaRender - the meta's render, when it has one.
+ */
+const storyRender = (context, local, metaRender) => {
+    const own = storyField(context, local, "render", new Set()).value;
+    if (own !== undefined && own !== null)
+        return renderText(context, own);
+    if (own === null)
+        return metaRender === undefined ? undefined : renderText(context, metaRender);
+    const value = context.top.values.get(local);
+    const asFunction = value === undefined ? context.functions.get(local) : storyFunction(context, value);
+    return asFunction === undefined ? undefined : textOf(context, asFunction);
+};
+/**
+ * One story's code: its render text, or its args written as code; none when reading it failed.
+ *
+ * @param context - the file.
+ * @param meta - the meta's object, when the file has one written plainly.
+ * @param local - the story's local name.
+ * @param metaRender - the meta's render, when it has one.
+ */
+const storyCodeOf = (context, meta, local, metaRender) => {
+    try {
+        return storyRender(context, local, metaRender) ?? writtenArgsOf(context, meta, local);
+    }
+    catch {
+        // a story the reader trips on is written from its values: the other stories of the file keep their code
         return undefined;
-    const { start, end } = render.value;
-    return dedented(text.slice(start, end), indentAt(text, start));
+    }
 };
 /**
- * Each story's `render` text in a story file.
+ * Each story's code in a story file: its render as written, or its args written as code.
  *
  * @param file - the file's path, for the parser (its extension decides TypeScript and JSX) and the messages.
  * @param text - the file's source.
@@ -65,15 +284,22 @@ export const storyCode = (file, text) => {
     const [error] = errors;
     if (error !== undefined)
         return `${file} does not parse: ${error.message}`;
-    const code = {};
-    for (const statement of program.body) {
-        if (statement.type !== "ExportNamedDeclaration" || statement.declaration?.type !== "VariableDeclaration")
+    const top = topLevelOf(program);
+    const context = { text, top, functions: declaredFunctions(program) };
+    const meta = metaObject(program, top);
+    const metaFields = (name) => meta === undefined ? undefined : propertyValue(meta, name);
+    const metaRender = metaFields("render");
+    const renders = {};
+    const args = {};
+    for (const { exportName, local } of storyExports(program, top, metaFields)) {
+        // a story from another file is read there: its code is the values of the moment
+        if (local === undefined)
             continue;
-        for (const declarator of statement.declaration.declarations) {
-            const render = renderText(declarator, text);
-            if (declarator.id.type === "Identifier" && render !== undefined)
-                code[declarator.id.name] = render;
-        }
+        const read = storyCodeOf(context, meta, local, metaRender);
+        if (typeof read === "string")
+            renders[exportName] = read;
+        else if (read !== undefined && Object.keys(read).length > 0)
+            args[exportName] = read;
     }
-    return code;
+    return { renders, args };
 };

package/dist/src/vite/storyCoverage.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which of a project's components have stories and which are drawn by its code: what `forgebook audit` reports as a
+ * catalogue's rot, components no story is about and stories of components nothing uses.
+ *
+ * @remarks
+ * Read from the files' text, with no program and no configuration, like the rest of the audit: it has to answer on a
+ * project with no catalogue, in a moment. A story file is about the components it imports; a component is used when a file
+ * that is neither a story nor a test imports it or writes its tag. Where an import cannot be followed (a barrel, an alias,
+ * a package's name), the imported name stands for every exported component of that name. Each guess leans the same way,
+ * towards "has stories" and "is used", so a component is listed only when nothing in the project could be it: a list here
+ * is worth reading, and a short one is not a promise. A component a framework loads by its file's place (a page, a layout)
+ * is in neither list, and stories of a published package's components never count as unused, since what uses them is
+ * outside the repository.
+ *
+ * @module
+ */
+import type { ScannedComponent } from "./componentScan.ts";
+import type { ProjectFile } from "./projectFiles.ts";
+/** A component as a list of the report names it. */
+export type CoverageComponent = Pick<ScannedComponent, "name" | "file" | "line">;
+/** A component with stories that nothing outside stories and tests draws. */
+export type UnusedStoriedComponent = CoverageComponent & {
+    /** The story files about it. */
+    readonly storyFiles: readonly string[];
+};
+/** Which components have stories, and which of those the project draws. */
+export type StoryCoverage = {
+    /** How many story files were read. */
+    readonly storyFileCount: number;
+    /** How many exported components some story is about. */
+    readonly withStories: number;
+    /** Exported components no story file is about, pages and layouts 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[];
+    /** How many components with stories were not judged unused because their package is published. */
+    readonly published: number;
+};
+/** A story file, in any language a catalogue reads. */
+export declare const STORY_FILE: RegExp;
+/**
+ * Which of a project's components have stories, and which of those its code draws.
+ *
+ * @param components - the project's components (`projectComponents`).
+ * @param files - every file read: components, story files and scripts that may import them.
+ * @param isPublished - whether a file belongs to a package the repository publishes.
+ */
+export declare const storyCoverage: (components: readonly ScannedComponent[], files: readonly ProjectFile[], isPublished: (file: string) => boolean) => StoryCoverage;

package/dist/src/vite/storyCoverage.js

@@ -0,0 +1,179 @@
+import { exportAliasesOf, importsOf } from "./importedNames.js";
+/** A story file, in any language a catalogue reads. */
+export const STORY_FILE = /\.(?:stories|story)\.[cm]?[jt]sx?$|\.(?:stories|story)\.(?:vue|svelte|astro)$/;
+/**
+ * What is never the project's own use of a component: test files by their names, and the folders only tools read. A folder
+ * merely named `tests` may be the application's own (a quiz's `tests/`), so only a file's name says it is a test.
+ */
+const NOT_A_USE = /\.(?:test|spec|e2e|cy)\.|(?:^|\/)(?:__tests__|__stories__|__mocks__|\.storybook|\.forgebook)\//;
+/**
+ * A file a framework loads by its place: a route, a page, a layout, an application's entry. Nothing imports it, and no one
+ * owes it a story.
+ */
+const LOADED_BY_PLACE = /(?:^|\/)(?:pages|routes|layouts)\/|(?:^|\/)(?:\+page|\+layout|\+error|page|layout|template|loading|error|not-found|default|global-error|_app|_document|App|app|main|root|entry\.client|entry\.server)\.[^/]+$/;
+/** The extensions an import may leave out, in the order a bundler tries them. */
+const EXTENSIONS = ["", ".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs", ".vue", ".svelte", ".astro"];
+/** A prefix projects give their source folder in imports: `@/components/Button`. */
+const ALIAS = /^(?:@|~|~~|@@|#|\$lib)\//;
+/** A tag written in markup: `<Button`, `<my-button`; a namespace's `<UI.Button>` is read with its import. */
+const TAG = /<([A-Z][\w$]*|[a-z][\w]*(?:-[\w]+)+)/g;
+/** An extension an ES module's import writes for a TypeScript file: `./Button.js` is `Button.tsx`. */
+const WRITTEN_EXTENSION = /\.[cm]?jsx?$/;
+/** A path with its `.` and `..` folded away. */
+const folded = (path) => {
+    const parts = [];
+    for (const part of path.split("/")) {
+        if (part === "..")
+            parts.pop();
+        else if (part !== "." && part !== "")
+            parts.push(part);
+    }
+    return parts.join("/");
+};
+/** A path without its extension, as an import may write it. */
+const bare = (file) => file.replace(/\.[^./]+$/, "").replace(/\/index$/, "");
+/**
+ * The project file an import names, when one can be told: a relative path, or an alias whose path one file ends with.
+ *
+ * @param specifier - the import's module.
+ * @param from - the importing file.
+ * @param known - the project's files.
+ * @param bySuffix - the project's files by every tail of their path without extension.
+ */
+const resolved = (specifier, from, known, bySuffix) => {
+    if (specifier.startsWith(".")) {
+        const written = folded(`${from.split("/").slice(0, -1).join("/")}/${specifier}`);
+        const bases = WRITTEN_EXTENSION.test(written)
+            ? [written, written.replace(WRITTEN_EXTENSION, "")]
+            : [written];
+        for (const form of bases.flatMap((base) => [base, `${base}/index`])) {
+            for (const extension of EXTENSIONS)
+                if (known.has(`${form}${extension}`))
+                    return `${form}${extension}`;
+        }
+        return undefined;
+    }
+    if (!ALIAS.test(specifier))
+        return undefined;
+    const files = bySuffix.get(bare(specifier.replace(ALIAS, "").replace(WRITTEN_EXTENSION, ""))) ?? [];
+    return files.length === 1 ? files[0] : undefined;
+};
+/** The project's files by every tail of their path without extension, `a/b/c` under `a/b/c`, `b/c` and `c`. */
+const suffixIndex = (files) => {
+    const index = new Map();
+    for (const file of files) {
+        const parts = bare(file).split("/");
+        for (let start = 0; start < parts.length; start += 1) {
+            const suffix = parts.slice(start).join("/");
+            const listed = index.get(suffix);
+            if (listed === undefined)
+                index.set(suffix, [file]);
+            else if (!listed.includes(file))
+                listed.push(file);
+        }
+    }
+    return index;
+};
+/** A key for a component: its file and name. */
+const keyOf = ({ file, name }) => `${file}\0${name}`;
+/** A kebab tag's component name: `my-button` is `MyButton`. */
+const pascal = (tag) => tag
+    .split("-")
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join("");
+/** The components an import of one file reaches, by what the file declares and, failing that, by name. */
+const reached = (name, target, lookup) => {
+    const { inFile, byName } = lookup;
+    const declared = target === undefined ? [] : (inFile.get(target) ?? []);
+    if (name.imported === "*" && declared.length > 0)
+        return declared;
+    // `export { Root as Dialog }`: the scan knows the component as Root
+    const local = (target === undefined ? undefined : lookup.aliasesOf(target).get(name.imported)) ?? name.imported;
+    const own = declared.filter((each) => name.imported === "default" ? each.isDefault === true || declared.length === 1 : each.name === local);
+    if (own.length > 0)
+        return own;
+    // a barrel, an alias or a package: the name stands for every exported component of that name
+    const asNamed = name.imported === "default" || name.imported === "*" ? name.local : name.imported;
+    return byName.get(asNamed) ?? [];
+};
+/** Groups a list by a key. */
+const grouped = (items, key) => {
+    const groups = new Map();
+    for (const item of items) {
+        const group = groups.get(key(item));
+        if (group === undefined)
+            groups.set(key(item), [item]);
+        else
+            group.push(item);
+    }
+    return groups;
+};
+/** The components a file imports. */
+const importedComponents = (file, text, lookup) => importsOf(text).flatMap(({ specifier, names }) => {
+    const target = resolved(specifier, file, lookup.known, lookup.bySuffix);
+    return names.flatMap((name) => reached(name, target, lookup));
+});
+/** The components a file writes the tag of, among those exported and its own. */
+const taggedComponents = (file, text, lookup) => [...text.matchAll(TAG)].flatMap((match) => {
+    const tag = match[1] ?? "";
+    const name = tag.includes("-") ? pascal(tag) : tag;
+    return [...(lookup.byName.get(name) ?? []), ...(lookup.inFile.get(file) ?? [])].filter((component) => component.name === name);
+});
+/** Which story files are about each component, and which components the rest of the files use, by key. */
+const readUses = (files, lookup) => {
+    const storiedBy = new Map();
+    const used = new Set();
+    for (const { file, text } of files) {
+        if (STORY_FILE.test(file)) {
+            for (const component of importedComponents(file, text, lookup)) {
+                const key = keyOf(component);
+                storiedBy.set(key, (storiedBy.get(key) ?? new Set()).add(file));
+            }
+        }
+        else if (!NOT_A_USE.test(file)) {
+            for (const component of importedComponents(file, text, lookup))
+                used.add(keyOf(component));
+            for (const component of taggedComponents(file, text, lookup))
+                used.add(keyOf(component));
+        }
+    }
+    return { storiedBy, used };
+};
+/** A component as a list names it. */
+const listed = ({ name, file, line }) => ({ name, file, line });
+/**
+ * Which of a project's components have stories, and which of those its code draws.
+ *
+ * @param components - the project's components (`projectComponents`).
+ * @param files - every file read: components, story files and scripts that may import them.
+ * @param isPublished - whether a file belongs to a package the repository publishes.
+ */
+export const storyCoverage = (components, files, isPublished) => {
+    const known = new Set(files.map(({ file }) => file));
+    const texts = new Map(files.map(({ file, text }) => [file, text]));
+    const aliases = new Map();
+    const aliasesOf = (file) => {
+        const found = aliases.get(file) ?? exportAliasesOf(texts.get(file) ?? "");
+        aliases.set(file, found);
+        return found;
+    };
+    const { storiedBy, used } = readUses(files, {
+        known,
+        bySuffix: suffixIndex(known),
+        aliasesOf,
+        inFile: grouped(components, ({ file }) => file),
+        byName: grouped(components.filter(({ isExported }) => isExported), ({ name }) => name)
+    });
+    const hasStories = (each) => storiedBy.has(keyOf(each));
+    const placed = components.filter(({ file }) => !LOADED_BY_PLACE.test(file));
+    const unused = placed.filter((each) => hasStories(each) && !used.has(keyOf(each)));
+    return {
+        storyFileCount: files.filter(({ file }) => STORY_FILE.test(file)).length,
+        withStories: components.filter((each) => each.isExported && hasStories(each)).length,
+        withoutStories: placed.filter((each) => each.isExported && !hasStories(each)).map(listed),
+        storiesUnused: unused
+            .filter(({ file }) => !isPublished(file))
+            .map((each) => ({ ...listed(each), storyFiles: [...(storiedBy.get(keyOf(each)) ?? [])].toSorted() })),
+        published: unused.filter(({ file }) => isPublished(file)).length
+    };
+};

package/dist/src/vite/storyFilesModule.d.ts

@@ -91,6 +91,24 @@ export type IndexedStoryFile = {
     /** Its index. */
     readonly index: StoryFileIndex;
 };
+/** A story file a group lists whose index cannot be read: the others still draw. */
+export type RefusedStoryFile = {
+    /** Its path relative to the declaring module. */
+    readonly key: string;
+    /** The group's first pattern that lists it. */
+    readonly pattern: string;
+    /** Its absolute path. */
+    readonly file: string;
+    /** Why, naming the file (with its line and column when they are known). */
+    readonly problem: string;
+};
+/** A group's story files read: those indexed, and those that cannot be. */
+export type StoryFilesRead = {
+    /** The story files indexed. */
+    readonly files: readonly IndexedStoryFile[];
+    /** The story files that cannot be. */
+    readonly refused: readonly RefusedStoryFile[];
+};
 /** A group's index as it is kept between starts, by file key. */
 export type KeptIndex = Readonly<Record<string, StoryFileIndex>>;
 /** Whether what a cache file holds is a group's index. */
@@ -106,14 +124,31 @@ export declare const isKeptIndex: (value: unknown) => value is KeptIndex;
  */
 export declare const storyFileIndex: (root: string, pattern: string, key: string) => StoryFileIndex | string;
 /**
- * Every story file a group's patterns list, indexed.
+ * Every story file a group's patterns list, indexed, and those that cannot be. Only the former are kept between starts:
+ * the stamps of the others would only say what is already known, and their next read costs one file.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the patterns (`storyFileKeys`).
+ * @param watch - adds a file whose edit renews the module that read it: a refused one too, as its fix must.
+ * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
+ * @param isKept - whether a listed file may be read; every one by default.
+ */
+export declare const readStoryFiles: (root: string, patterns: readonly string[], watch: (file: string) => void, cache?: DiskCache<KeptIndex>, isKept?: IsFileKept) => StoryFilesRead;
+/**
+ * What fails a module that cannot go on without its files: every file refused, a line each.
+ *
+ * @param refused - the files, at least one.
+ */
+export declare const refusalError: (refused: readonly RefusedStoryFile[]) => Error;
+/**
+ * Every story file a group's patterns list, indexed, for those who cannot go on without one: a build, a test.
  *
  * @param root - the declaring module's folder.
  * @param patterns - the patterns (`storyFileKeys`).
  * @param watch - adds a file whose edit renews the module that read it.
  * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
  * @param isKept - whether a listed file may be read; every one by default.
- * @throws when a story file cannot be indexed.
+ * @throws when a story file cannot be indexed, naming every one that cannot.
  */
 export declare const indexedStoryFiles: (root: string, patterns: readonly string[], watch: (file: string) => void, cache?: DiskCache<KeptIndex>, isKept?: IsFileKept) => IndexedStoryFile[];
 /** The loaders a group offers besides its story files'. */
@@ -136,6 +171,14 @@ export type GroupLoaders = {
  * @returns the module's code, or a message saying which file cannot be indexed.
  */
 export declare const storyFilesModule: (root: string, patterns: readonly string[], watch: (file: string) => void, loaders?: GroupLoaders, cache?: DiskCache<KeptIndex>) => string;
+/**
+ * The stories a group needs before its stories are written as rows (`indexCode`). Rows write each key once and the
+ * objects once per story, but rows need the function that turns them back, which a small group's first load pays for
+ * more than it saves: gzip already shares a key repeated in every story. On the generated library, rows cost the shell's
+ * first load 11 bytes more at 100 stories and saved 92 at 500, so the two meet near 150; past 300 they save without
+ * doubt, and the build's own weight falls by a quarter of the index.
+ */
+export declare const ROWS_FROM_STORIES = 300;
 /**
  * The code of the module for one group, from its story files indexed.
  *
@@ -146,5 +189,7 @@ export declare const storyFilesModule: (root: string, patterns: readonly string[
  * @param loaders - the group's loaders besides its story files'.
  * @param hasTexts - a build's: whether each file's docs, code and page come from the group's texts module, in the
  * rows' order (`TEXTS_PREFIX`), and not each from its query.
+ * @param refused - the story files it lists that cannot be indexed, which the catalogue names among its problems.
+ * @param scriptProblems - the project's other scripts that do not parse, named among them too.
  */
-export declare const storyFilesCode: (root: string, patterns: readonly string[], files: readonly IndexedStoryFile[], loaders: GroupLoaders, hasTexts?: boolean) => string;
+export declare const storyFilesCode: (root: string, patterns: readonly string[], files: readonly IndexedStoryFile[], loaders: GroupLoaders, hasTexts?: boolean, refused?: readonly RefusedStoryFile[], scriptProblems?: readonly string[]) => string;