forgebook 0.3.3 → 0.4.1

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

@@ -1,19 +1,6 @@
-/**
- * The packages Vite pre-bundles, and the story files it scans, before the catalogue's first page opens, so the pages
- * never reload while they load.
- *
- * @remarks
- * Vite finds what to pre-bundle by scanning the app's HTML and entries on disk; a catalogue's pages and their entries
- * are generated (`pages.ts`), so without this list Vite discovers each package as a page imports it, pre-bundles it
- * then, and reloads the page, more than once on a first start. The list is the shell's and the frame's packages (the
- * shell is React), the framework's, Testing Library's when the project installs it, what the plugins name, and
- * Forgebook's own modules and the plugins' when they come from an installed package (a linked one is source, which Vite
- * does not pre-bundle). axe is not among them: the frame loads it as a script (`axeScript.ts`). A package the project
- * cannot resolve is left out, since Vite fails on one it cannot find. Pure: a resolver in, names out.
- *
- * @module
- */
+import type { UserConfig } from "vite";
 import { type ResolvedConfig } from "./configFile.ts";
+import { type ScriptProblems } from "./scriptProblems.ts";
 /**
  * Resolves a package as Node would from the catalogue's folder: its file's real path, or none when it is not there.
  *
@@ -41,3 +28,58 @@ export declare const prebundled: (config: ResolvedConfig, resolve: Resolve) => s
  * @param readText - reads a file's text; none when it cannot.
  */
 export declare const scannedEntries: (config: ResolvedConfig, resolve: Resolve, readText: (file: string) => string | undefined) => string[];
+/** Vite's options of its dependency scan. */
+type ScanOptions = NonNullable<NonNullable<UserConfig["optimizeDeps"]>["rolldownOptions"]>;
+/** A module the scan reads in place of a file's own text. */
+type ScanModule = {
+    code: string;
+    moduleType: "js" | "jsx";
+};
+/**
+ * What the scan reads for one of the project's scripts: nothing in its place when it parses (the scan reads it), the
+ * same text read as JSX when only JSX makes a `.js` file parse, and its imports alone when it does not parse at all,
+ * which the parser still finds, so their packages are pre-bundled with the rest.
+ *
+ * @param file - the script's path; its extension decides TypeScript and JSX.
+ * @param text - its source.
+ * @returns the module to scan, or none to let the scan read the file, and why the file does not parse.
+ */
+export declare const scannedScript: (file: string, text: string) => {
+    module: ScanModule | undefined;
+    problem: string | undefined;
+};
+/** Where the scan's findings go. */
+export type ScanFindings = {
+    /** The catalogue's folder: a warning names a file relative to it; absolute without it. */
+    readonly root?: string;
+    /** Writes one warning line; none are written without it. */
+    readonly warn?: (line: string) => void;
+    /** Keeps what the scan found of each of the project's scripts, other than story files (`scriptProblems.ts`). */
+    readonly scanned?: ScriptProblems["scanned"];
+    /**
+     * Whether every `.js` file is read as JSX, for a framework whose adapter compiles their JSX (`compilesJsxInScripts`):
+     * JSX is a superset of what such a file may hold, so the others give the same imports. Without it, only a file that
+     * parses as nothing else is.
+     */
+    readonly isJsxInScripts?: boolean;
+    /**
+     * Whether the scan reads only the story files here and leaves every other script to the scanner, which parses it
+     * itself: a first start's pre-bundling tries that first, since reading and parsing every component a second time in
+     * JavaScript costs a large library a quarter of a second, and scans again without it only when a script stops the
+     * scan (`prebundleRun.ts`). A server's own scan reads them all.
+     */
+    readonly isQuick?: boolean;
+};
+/**
+ * Keeps Vite's dependency scan going past one of the project's scripts that does not parse, a story file or a
+ * component, and reads a `.js` file holding JSX as JSX. One such file otherwise stops the scan, and with it the
+ * pre-bundling of every other story's packages, and fills the log with the scanner's stack; the pages then reload as
+ * each package is found. A script that does not parse is read as its imports alone: a story file is named by the
+ * catalogue itself (`storyFilesModule.ts`), any other is kept among the index's problems (`scriptProblems.ts`) and
+ * named by one warning with its place. The texts are read here on the scan only: a start that keeps its pre-bundled
+ * packages does not scan.
+ *
+ * @param findings - the catalogue's folder, where warnings and problems go, and whether `.js` is read as JSX.
+ */
+export declare const scanOptions: (findings?: ScanFindings) => ScanOptions;
+export {};

package/dist/src/vite/prebundled.js

@@ -13,9 +13,13 @@
  *
  * @module
  */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { STORY_FILE } from "./autoTitle.js";
 import { PLAY_TOOLS_PACKAGES } from "./configFile.js";
 import { hasPluginViews, PLUGIN_HOSTS_MODULE, WRITTEN_HOME_MODULE } from "./pages.js";
 import { pluginModules } from "./pluginConfig.js";
+import { REFS_MODULE } from "./refsConfig.js";
+import { INSTALLED, parsedScript, SCRIPT } from "./scriptProblems.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** What the shell and the frame import in the browser from the project's packages (React is a peer of the core). */
 const CORE_BROWSER_DEPENDENCIES = [
@@ -40,6 +44,7 @@ export const prebundled = (config, resolve) => {
         // imported on first use, so the scanner never sees it: named, or the first home would wait for the optimizer
         ...(config.home === undefined ? [] : [WRITTEN_HOME_MODULE]),
         ...(hasPluginViews(config) ? [PLUGIN_HOSTS_MODULE] : []),
+        ...(config.refs.length === 0 ? [] : [REFS_MODULE]),
         config.framework.pages.frame,
         config.framework.pages.code,
         ...pluginModules(config.plugins, config.framework.name)
@@ -90,3 +95,78 @@ export const scannedEntries = (config, resolve, readText) => {
     // `!` patterns stay as they are, which Vite's scanner reads as fast-glob does, from the same folder
     return [...config.stories, ...fromSources, ...config.previews];
 };
+/**
+ * What the scan reads for one of the project's scripts: nothing in its place when it parses (the scan reads it), the
+ * same text read as JSX when only JSX makes a `.js` file parse, and its imports alone when it does not parse at all,
+ * which the parser still finds, so their packages are pre-bundled with the rest.
+ *
+ * @param file - the script's path; its extension decides TypeScript and JSX.
+ * @param text - its source.
+ * @returns the module to scan, or none to let the scan read the file, and why the file does not parse.
+ */
+export const scannedScript = (file, text) => {
+    const { imports, isJsx, problem } = parsedScript(file, text);
+    if (isJsx)
+        return { module: { code: text, moduleType: "jsx" }, problem };
+    if (problem === undefined)
+        return { module: undefined, problem };
+    const code = imports.map((name) => `import ${JSON.stringify(name)};`).join("\n");
+    return { module: { code, moduleType: "js" }, problem };
+};
+/**
+ * Whether the scan reads a script here rather than leave it to the scanner: a quick scan reads the story files alone,
+ * whose problems the catalogue names as they are edited, and an id that names no file (a plugin's own module) is not
+ * the scan's to answer.
+ *
+ * @param id - the module's id.
+ * @param isQuick - whether the scan is a quick one (`ScanFindings.isQuick`).
+ */
+const isReadHere = (id, isQuick) => (!isQuick || STORY_FILE.test(id)) && existsSync(id);
+/**
+ * The warnings this process wrote: a first start's pre-bundling scans again after leaving out an import it could not
+ * resolve (`prebundleRun.ts`), and a file is named once.
+ */
+const WARNED = new Set();
+/**
+ * Keeps Vite's dependency scan going past one of the project's scripts that does not parse, a story file or a
+ * component, and reads a `.js` file holding JSX as JSX. One such file otherwise stops the scan, and with it the
+ * pre-bundling of every other story's packages, and fills the log with the scanner's stack; the pages then reload as
+ * each package is found. A script that does not parse is read as its imports alone: a story file is named by the
+ * catalogue itself (`storyFilesModule.ts`), any other is kept among the index's problems (`scriptProblems.ts`) and
+ * named by one warning with its place. The texts are read here on the scan only: a start that keeps its pre-bundled
+ * packages does not scan.
+ *
+ * @param findings - the catalogue's folder, where warnings and problems go, and whether `.js` is read as JSX.
+ */
+export const scanOptions = (findings = {}) => {
+    // the scan names files by their real path: a folder reached through a link (`/tmp` on macOS) would not prefix them
+    const root = findings.root === undefined || !existsSync(findings.root) ? undefined : realpathSync(findings.root);
+    return {
+        ...(findings.isJsxInScripts === true ? { moduleTypes: { ".js": "jsx", ".mjs": "jsx" } } : {}),
+        plugins: [
+            {
+                name: "forgebook:scan-scripts",
+                load: {
+                    filter: { id: { include: SCRIPT, exclude: INSTALLED } },
+                    handler: (id) => {
+                        if (!isReadHere(id, findings.isQuick === true))
+                            return null;
+                        const file = VITE_PATHS.normalize(id);
+                        const { module, problem } = scannedScript(file, readFileSync(id, "utf8"));
+                        if (STORY_FILE.test(id))
+                            return module ?? null;
+                        findings.scanned?.(file, problem);
+                        if (problem !== undefined) {
+                            const shown = root === undefined ? file : VITE_PATHS.relative(root, file);
+                            const line = `The dependency scan skipped ${problem.replace(file, shown)}`;
+                            if (!WARNED.has(line))
+                                findings.warn?.(line);
+                            WARNED.add(line);
+                        }
+                        return module ?? null;
+                    }
+                }
+            }
+        ]
+    };
+};

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

@@ -0,0 +1,25 @@
+import type { IndexedStoryFile } from "./storyFilesModule.ts";
+/**
+ * The tags a preview's text writes: none when it writes none, or none plainly.
+ *
+ * @param file - the preview's path, for the parser's language.
+ * @param text - its text.
+ */
+export declare const tagsOfPreviewText: (file: string, text: string) => readonly string[];
+/**
+ * The tags of a catalogue's previews, the first preview's under the next's.
+ *
+ * @param config - the catalogue, with its previews' paths, the presets' first; none has no previews.
+ * @param watch - adds a file whose edit renews the module that reads them.
+ */
+export declare const previewTagsOf: (config: {
+    readonly previews: readonly string[];
+} | undefined, watch: (file: string) => void) => readonly string[];
+/**
+ * Story files with a preview's tags under each story's own, and under the meta's: a preview that marks every story
+ * marks every component.
+ *
+ * @param files - the story files, indexed.
+ * @param tags - the previews' tags.
+ */
+export declare const withPreviewTags: (files: readonly IndexedStoryFile[], tags: readonly string[]) => readonly IndexedStoryFile[];

package/dist/src/vite/previewTags.js

@@ -0,0 +1,56 @@
+/**
+ * The tags a preview gives every story (`tags` in `forgebook.preview.ts`), read from its text as a story file's are, so
+ * the list of stories needs no preview run.
+ *
+ * @remarks
+ * CSF puts them under a meta's and a story's, whose `!name` takes one away. The story index is kept between starts per
+ * file, so they join each story when the group's module is written, not in the kept index. Only tags written plainly
+ * count, as in a story file. Pure, but for reading the files.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { objectFields, stringListOf } from "./indexFields.js";
+import { combinedTags, storyFileMeta } from "./indexStoryFile.js";
+import { parseStoryFile } from "./storyParse.js";
+/**
+ * The tags a preview's text writes: none when it writes none, or none plainly.
+ *
+ * @param file - the preview's path, for the parser's language.
+ * @param text - its text.
+ */
+export const tagsOfPreviewText = (file, text) => {
+    const meta = storyFileMeta(parseStoryFile(file, text).program);
+    const tags = meta === undefined ? undefined : stringListOf(objectFields(meta), "tags");
+    return tags === undefined || tags instanceof Error ? [] : tags;
+};
+/**
+ * The tags of a catalogue's previews, the first preview's under the next's.
+ *
+ * @param config - the catalogue, with its previews' paths, the presets' first; none has no previews.
+ * @param watch - adds a file whose edit renews the module that reads them.
+ */
+export const previewTagsOf = (config, watch) => combinedTags((config?.previews ?? []).map((file) => {
+    watch(file);
+    return tagsOfPreviewText(file, readFileSync(file, "utf8"));
+}));
+/**
+ * Story files with a preview's tags under each story's own, and under the meta's: a preview that marks every story
+ * marks every component.
+ *
+ * @param files - the story files, indexed.
+ * @param tags - the previews' tags.
+ */
+export const withPreviewTags = (files, tags) => tags.length === 0
+    ? files
+    : files.map((file) => ({
+        ...file,
+        index: {
+            ...file.index,
+            tags: combinedTags([tags, file.index.tags]),
+            stories: file.index.stories.map((story) => ({
+                ...story,
+                tags: combinedTags([tags, story.tags])
+            }))
+        }
+    }));

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

@@ -0,0 +1,54 @@
+/** A file of a project. */
+export type ProjectFile = {
+    /** Its path, relative to the folder asked about. */
+    readonly file: string;
+    /** Its text. */
+    readonly text: string;
+};
+/** A package of a repository. */
+export type WorkspacePackage = {
+    /** Its name; empty for none. */
+    readonly name: string;
+    /** Its folder, from the repository; empty for its root. */
+    readonly dir: string;
+    /** The packages it depends on, by name. */
+    readonly dependsOn: readonly string[];
+};
+/** What git is asked for. */
+export declare const UI_PATTERNS: readonly string[];
+/** Past this much text a report stops reading, rather than run out of memory on what no one wrote by hand. */
+export declare const MOST_BYTES = 200000000;
+/**
+ * The project's files inside its repository, relative to its folder, without reading them.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export declare const listedProjectFiles: (dir: string, notes: string[]) => string[];
+/**
+ * Reads a project's files.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export declare const projectFiles: (dir: string, notes: string[]) => ProjectFile[];
+/** A project's files and its scripts, read under one bound of files and bytes. */
+export type FilesAndScripts = {
+    /** Its styles and components, as {@link projectFiles} reads them. */
+    readonly files: readonly ProjectFile[];
+    /** Its scripts, read with what room the files left. */
+    readonly scripts: readonly ProjectFile[];
+};
+/**
+ * Reads a project's files and then its scripts, the two together held to the bounds {@link projectFiles} keeps alone.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export declare const projectFilesAndScripts: (dir: string, notes: string[]) => FilesAndScripts;
+/**
+ * The packages of a repository, from their manifests, read and not run.
+ *
+ * @param root - the repository.
+ */
+export declare const workspacePackages: (root: string) => WorkspacePackage[];

package/dist/src/vite/projectFiles.js

@@ -0,0 +1,116 @@
+/**
+ * The files of a project a static reading takes: its styles and components, what git knows of them, inside the repository.
+ *
+ * @remarks
+ * Shared by what reads a whole project without a catalogue (`forgebook audit`) and by `check-code`; the audit also reads
+ * the scripts, which import components and hold stories. A tracked link may lead
+ * anywhere, and a repository may hold more than memory, so both are bounded here and said in `notes`.
+ *
+ * @module
+ */
+import { join } from "node:path";
+import { listedFiles, repositoryOf, smallFileText } from "./appTokenFiles.js";
+import { isInside } from "./sourceTokens.js";
+/** What git is asked for. */
+export const UI_PATTERNS = [
+    "*.css",
+    "*.scss",
+    "*.sass",
+    "*.less",
+    "*.tsx",
+    "*.jsx",
+    "*.vue",
+    "*.svelte",
+    "*.astro"
+];
+/** The same, for a file's name. */
+const UI_FILE = /\.(?:css|scss|sass|less|tsx|jsx|vue|svelte|astro)$/;
+/** What is not the project's own code: copies, generated output and what a package brought. */
+const NOT_ITS_CODE = /(?:^|\/)(?:node_modules|dist|build|out|coverage|vendor|vendors|public|static|\.next|\.nuxt|\.svelte-kit|\.astro|\.turbo|storybook-static)\//;
+/** Past this a project's files are not all read, and the report says so. */
+const MOST_FILES = 5000;
+/** Past this much text a report stops reading, rather than run out of memory on what no one wrote by hand. */
+export const MOST_BYTES = 200_000_000;
+/**
+ * The project's files inside its repository, relative to its folder, without reading them.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export const listedProjectFiles = (dir, notes) => {
+    const root = repositoryOf(dir);
+    const listed = listedFiles(dir, UI_PATTERNS, UI_FILE, NOT_ITS_CODE).filter((file) => !NOT_ITS_CODE.test(file));
+    if (listed.length > MOST_FILES)
+        notes.push(`${listed.length - MOST_FILES} files past the first ${MOST_FILES} not read`);
+    // a tracked link may lead anywhere
+    return listed.slice(0, MOST_FILES).filter((file) => isInside(root, join(dir, file)));
+};
+/** Reads listed files, up to the bytes a report reads, and says when it stops. */
+const readFiles = (dir, listed, notes) => {
+    let bytes = 0;
+    const read = listed.flatMap((file) => {
+        const text = bytes > MOST_BYTES ? undefined : smallFileText(join(dir, file));
+        bytes += text?.length ?? 0;
+        return text === undefined ? [] : [{ file, text }];
+    });
+    if (bytes > MOST_BYTES)
+        notes.push(`files past the first ${MOST_BYTES} bytes not read`);
+    return read;
+};
+/**
+ * Reads a project's files.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export const projectFiles = (dir, notes) => readFiles(dir, listedProjectFiles(dir, notes), notes);
+/** The scripts git is asked for: what may import a component or hold a story, with no markup of its own. */
+const SCRIPT_PATTERNS = ["*.ts", "*.mts", "*.cts", "*.js", "*.mjs", "*.cjs"];
+/** The same, for a file's name; a type declaration imports nothing that runs. */
+const SCRIPT_FILE = /(?<!\.d)\.[cm]?[jt]s$/;
+/**
+ * Reads a project's files and then its scripts, the two together held to the bounds {@link projectFiles} keeps alone.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export const projectFilesAndScripts = (dir, notes) => {
+    const root = repositoryOf(dir);
+    const ui = listedProjectFiles(dir, notes);
+    const listed = listedFiles(dir, SCRIPT_PATTERNS, SCRIPT_FILE, NOT_ITS_CODE).filter((file) => SCRIPT_FILE.test(file) && !NOT_ITS_CODE.test(file));
+    const room = Math.max(0, MOST_FILES - ui.length);
+    if (listed.length > room)
+        notes.push(`${listed.length - room} scripts past the first ${MOST_FILES} files not read`);
+    const scripts = new Set(listed.slice(0, room).filter((file) => isInside(root, join(dir, file))));
+    const read = readFiles(dir, [...ui, ...scripts], notes);
+    return {
+        files: read.filter(({ file }) => !scripts.has(file)),
+        scripts: read.filter(({ file }) => scripts.has(file))
+    };
+};
+/**
+ * The packages of a repository, from their manifests, read and not run.
+ *
+ * @param root - the repository.
+ */
+export const workspacePackages = (root) => listedFiles(root, ["package.json", "*/package.json"], /^package\.json$/, NOT_ITS_CODE)
+    .filter((file) => !NOT_ITS_CODE.test(file))
+    .slice(0, MOST_FILES)
+    .flatMap((file) => {
+    try {
+        const parsed = JSON.parse(smallFileText(join(root, file)) ?? "");
+        if (typeof parsed !== "object" || parsed === null)
+            return [];
+        const fields = new Map(Object.entries(parsed));
+        const name = fields.get("name");
+        const dependsOn = ["dependencies", "devDependencies", "peerDependencies"].flatMap((key) => {
+            const list = fields.get(key);
+            return typeof list === "object" && list !== null ? Object.keys(list) : [];
+        });
+        const dir = file === "package.json" ? "" : file.slice(0, -"/package.json".length);
+        return [{ name: typeof name === "string" ? name : "", dir, dependsOn }];
+    }
+    catch {
+        return [];
+    }
+});

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

@@ -0,0 +1,70 @@
+/** What PostCSS's `process` gives, as this module reads it. */
+export type Processed = {
+    /** The style sheet. */
+    readonly css: string;
+    /** What the plugins said: among them, the files they read. */
+    readonly messages: readonly unknown[];
+};
+/**
+ * The files PostCSS's plugins said they read: each `dependency`, and each file of a `dir-dependency`'s glob.
+ *
+ * @param messages - the messages of PostCSS's result.
+ */
+export declare const watchedFiles: (messages: readonly unknown[]) => string[];
+/** Where a project's configuration is. */
+export type PostcssConfigPlace = {
+    /** A file of its own. */
+    readonly kind: "file";
+    /** Its absolute path. */
+    readonly file: string;
+} | {
+    /** The `postcss` key of a `package.json`. */
+    readonly kind: "package";
+    /** That file's absolute path. */
+    readonly file: string;
+    /** What the key holds. */
+    readonly config: unknown;
+};
+/**
+ * Where a project's PostCSS configuration is, or none: in its folder, else in the ones above it, up to its repository's
+ * root.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const postcssConfigPlace: (dir: string) => PostcssConfigPlace | undefined;
+/**
+ * The project's PostCSS configuration file, or none.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const postcssConfigFile: (dir: string) => string | undefined;
+/**
+ * The plugins a configuration names, each loaded from the project and given its options; one set to `false` is off.
+ *
+ * @param plugins - the configuration's `plugins`: an object of names and options, or a list.
+ * @param load - loads a plugin's package by name.
+ */
+export declare const configuredPlugins: (plugins: unknown, load: (name: string) => Promise<unknown>) => Promise<unknown[]>;
+/**
+ * A project's PostCSS configuration that could not be loaded, which is a different thing from a sheet it refuses: every
+ * sheet would fail alike, so a catalogue goes on without it and says so once.
+ */
+export declare class PostcssConfigError extends Error {
+}
+/** Runs the project's PostCSS on a style sheet. */
+export type PostcssRunner = (css: string, file: string) => Promise<Processed>;
+/** What a project's PostCSS is made from, when it is not read from a configuration of its own. */
+export type PostcssOptions = {
+    /** A package of the project that brings its own PostCSS and plugins (Next.js does), looked in after the project. */
+    readonly bringsPostcss?: string;
+    /** The plugins, already made (Vite's `css.postcss`): no file is looked for. */
+    readonly plugins?: readonly unknown[];
+};
+/**
+ * The project's PostCSS, ready to run: its configuration and plugins loaded on the first style sheet.
+ *
+ * @param dir - the project's folder.
+ * @param options - where else to look, and plugins already made.
+ * @returns the runner, or none for a project without a PostCSS configuration.
+ */
+export declare const projectPostcss: (dir: string, options?: PostcssOptions) => PostcssRunner | undefined;