forgebook 0.3.2 → 0.4.0

package/dist/bin/forgebook/agentSetup/drawCandidates.js

@@ -0,0 +1,116 @@
+/**
+ * Which of a project's components to try first when `forgebook init --draw` looks for one that draws.
+ *
+ * @remarks
+ * A leaf of a design system needs the least of what the app sets up, so names and folders that say so come first, smaller
+ * files before larger, and what says page, layout, provider or route comes last or not at all. Only the names are read
+ * here, with each file's size: `forgebook new` reads the file itself, and says when it exports no component.
+ *
+ * @module
+ */
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { VITE_PATHS } from "../../../src/vite/vitePaths.js";
+/** What a component file of each framework ends in. */
+const COMPONENT_FILES = {
+    vue: /\.vue$/,
+    nuxt: /\.vue$/,
+    svelte: /\.svelte$/,
+    sveltekit: /\.svelte$/,
+    angular: /\.component\.ts$/,
+    "web-components": /\.[jt]s$/,
+    html: /\.[jt]s$/
+};
+/** A component file where the framework's are TSX or JSX. */
+const JSX_FILE = /\.[jt]sx$/;
+/** What is never a component to draw, by its path. */
+const NOT_COMPONENT = /(?:\.(?:test|spec|stories|e2e|cy|d)\.|(?:^|\/)(?:__\w+__|tests?|e2e|cypress|mocks?|fixtures|stories|node_modules|dist|build|out|coverage|public|\.[^/]+)\/|(?:^|\/)\+|\[[^/]*\]|(?:^|\/)(?:_app|_document|_error|main|index|entry[-.\w]*|root|error|global-error|loading|not-found|template|default|middleware|instrumentation)\.[^/]+$)/i;
+/** Names a small, self-contained component usually has. */
+const LEAF_NAME = /(?:^|[/-])(?:button|badge|label|separator|spinner|skeleton|icon|logo|avatar|kbd|tag|chip|card|alert|input|text|title|heading|divider|link|progress|checkbox|switch)[^/]*$/i;
+/** A folder a design system keeps its parts in. */
+const UI_FOLDER = /(?:^|\/)(?:ui|atoms|primitives|base|common|shared|elements|design-system)\//i;
+/** A folder of components. */
+const COMPONENT_FOLDER = /(?:^|\/)components?\//i;
+/** What needs most of what the app sets up. */
+const APP_SHAPED = /(?:page|layout|provider|route|router|app|screen|view|context|store|modal|dialog|form|table|chart|editor|sidebar|nav|header|footer|shell)[^/]*$|(?:^|\/)(?:app|pages|routes|views|screens|features|layouts|providers)\//i;
+/** How many folders a search goes through, so a huge repository's first run stays quick. */
+const SEARCH_LIMIT = 5000;
+/** How many files are ranked. */
+const FILE_LIMIT = 5000;
+/** How many candidates come back: past these, the reason is rarely the component. */
+export const CANDIDATE_LIMIT = 8;
+/**
+ * How promising a component's path is: lower comes first.
+ *
+ * @param path - the file, from the project's folder, with forward slashes.
+ * @param size - its size in bytes.
+ */
+export const candidateRank = (path, size) => {
+    let rank = Math.min(size / 200, 40);
+    if (LEAF_NAME.test(path))
+        rank -= 60;
+    if (UI_FOLDER.test(path))
+        rank -= 40;
+    else if (COMPONENT_FOLDER.test(path))
+        rank -= 15;
+    if (APP_SHAPED.test(path))
+        rank += 60;
+    return rank;
+};
+/**
+ * The top folders story patterns cover: a component outside them gets stories the catalogue does not list.
+ *
+ * @param patterns - the patterns (`{app,components}/**\/*.stories.tsx`).
+ * @returns the folders; none when any pattern covers more than folders can say, so nothing is left out.
+ */
+export const storyFolders = (patterns) => {
+    const folders = [];
+    for (const pattern of patterns) {
+        if (pattern.startsWith("!"))
+            continue;
+        const first = pattern.split("/")[0] ?? "";
+        if (first === "" || !pattern.includes("/") || first === "**" || first.startsWith("."))
+            return [];
+        folders.push(...first.replace(/^\{|\}$/g, "").split(","));
+    }
+    return folders;
+};
+/** A folder's entries; none for one the command may not read, which only leaves its files out. */
+const entriesOf = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * The project's component files to try, the most promising first.
+ *
+ * @param projectDir - the project's folder.
+ * @param framework - the adapter's name.
+ * @param folders - the top folders to look in; every one when none.
+ * @returns the files, from the project's folder.
+ */
+export const drawCandidates = (projectDir, framework, folders = []) => {
+    const isComponent = COMPONENT_FILES[framework] ?? JSX_FILE;
+    const queue = folders.length === 0 ? [projectDir] : folders.map((folder) => join(projectDir, folder));
+    const found = [];
+    const noteEntry = (entry, full) => {
+        const path = VITE_PATHS.normalize(relative(projectDir, full));
+        if (entry.isDirectory() && !NOT_COMPONENT.test(`${path}/`))
+            queue.push(full);
+        if (entry.isFile() && isComponent.test(entry.name) && !NOT_COMPONENT.test(path))
+            found.push({ path, rank: candidateRank(path, statSync(full).size) });
+    };
+    for (const dir of queue) {
+        if (queue.length > SEARCH_LIMIT || found.length > FILE_LIMIT)
+            break;
+        for (const entry of entriesOf(dir))
+            noteEntry(entry, join(dir, entry.name));
+    }
+    return found
+        .sort((a, b) => a.rank - b.rank || a.path.localeCompare(b.path))
+        .slice(0, CANDIDATE_LIMIT)
+        .map(({ path }) => path);
+};

package/dist/bin/forgebook/agentSetup/drawDiagnosis.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Why a story did not draw, named: what an agent or a person reads instead of a bundler's words, with the step to take.
+ *
+ * @remarks
+ * Pure: a message in, a diagnosis out. The patterns are what Vite, Node, the browser and the libraries really say, and an
+ * unknown message stays itself, under its own kind, never a guess. A project's text is only ever shown, cut short.
+ *
+ * @module
+ */
+/** What stopped a story from drawing. */
+export type DrawFailureKind = "no-component" | "missing-import" | "provider" | "server-only" | "style-sheet" | "native-build" | "browser" | "app-config" | "older-forgebook" | "nuxt-runtime" | "network" | "unbuilt-package" | "generated-files" | "needs-props" | "old-sass" | "blank" | "timeout" | "unknown";
+/** Why a story did not draw. */
+export type DrawDiagnosis = {
+    /** What kind of thing stopped it. */
+    readonly kind: DrawFailureKind;
+    /** What was said, cut short. */
+    readonly message: string;
+    /** What to do. */
+    readonly nextStep: string;
+};
+/**
+ * Why a story did not draw.
+ *
+ * @param said - what the command or the frame said.
+ */
+export declare const diagnosed: (said: string) => DrawDiagnosis;
+/** The diagnosis of a story that drew nothing visible. */
+export declare const BLANK: DrawDiagnosis;

package/dist/bin/forgebook/agentSetup/drawDiagnosis.js

@@ -0,0 +1,134 @@
+/**
+ * Why a story did not draw, named: what an agent or a person reads instead of a bundler's words, with the step to take.
+ *
+ * @remarks
+ * Pure: a message in, a diagnosis out. The patterns are what Vite, Node, the browser and the libraries really say, and an
+ * unknown message stays itself, under its own kind, never a guess. A project's text is only ever shown, cut short.
+ *
+ * @module
+ */
+import { printable } from "../../../src/printable.js";
+/** The longest message kept: a stack would flood an agent's context. */
+const MESSAGE_LENGTH = 400;
+/** What a package manager runs when it installs a package with native code, which `--ignore-scripts` leaves undone. */
+const NATIVE_STEP = "A package's install step did not run: run the project's install without --ignore-scripts, or rebuild that package";
+/** The rules, the most telling first. */
+const RULES = [
+    {
+        pattern: /fetch failed|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|ECONNRESET|Fetch web fonts timeout/,
+        kind: "network",
+        nextStep: () => "Something the app's build runs fetched from the network and could not (UnoCSS's web fonts, a fonts module): check the connection and run this again, or name the plugin in appBuild.skipPlugins"
+    },
+    {
+        pattern: /written by Nuxt's build, which a catalogue does not run|#nuxt-i18n\/|forgebook-nuxt:(?:kept|build):/i,
+        kind: "nuxt-runtime",
+        nextStep: () => "The component reads what a Nuxt module sets up when Nuxt's app runs (i18n's messages, a plugin's provide), which a catalogue does not run: give it in a decorator of forgebook.preview, or try a component that needs none"
+    },
+    {
+        pattern: /TSCONFIG_ERROR|Failed to load tsconfig|Cannot find base config/i,
+        kind: "generated-files",
+        nextStep: () => "The project's tsconfig.json extends a file a tool writes: run that tool (svelte-kit sync, nuxt prepare), or an install with its scripts"
+    },
+    {
+        pattern: /sass\.initAsyncCompiler is not a function/i,
+        kind: "old-sass",
+        nextStep: () => "The project's Sass is older than the catalogue's Vite can use: upgrade sass, to 1.70 or later"
+    },
+    {
+        pattern: /no valid target file was found|Package path \S+ is (?:not )?exported/i,
+        kind: "unbuilt-package",
+        nextStep: () => "A package the project imports has no built files: in a workspace, build its packages first, then run this again"
+    },
+    {
+        pattern: /Unexpected token Function\("theme"\)|Unknown at rule: @(?:tailwind|apply|theme|source)/i,
+        kind: "style-sheet",
+        nextStep: () => "Tailwind's own syntax reached the compiler unprocessed. On Nuxt a module's work is not done (@nuxt/ui, @nuxtjs/tailwindcss): keep to a sheet with no such import in nuxt.config's css, or give the catalogue its own; elsewhere, check the project's Tailwind plugin or PostCSS is declared"
+    },
+    {
+        pattern: /Unknown option '--json'|unknown command (?:new|check|shot|stories)/i,
+        kind: "older-forgebook",
+        nextStep: () => "The project installed an older forgebook than the one running this: a package manager's release-age or trust rule can do that; install the same version, then run this again"
+    },
+    {
+        pattern: /Executable doesn't exist|playwright install|Stories run in a browser with/i,
+        kind: "browser",
+        nextStep: () => "Install the browser: forgebook browser (or forgebook init --browser)"
+    },
+    {
+        pattern: /exports no component|cannot read a component|no component/i,
+        kind: "no-component",
+        nextStep: () => "This file exports no component to draw: name one with forgebook new <file> --export <name>"
+    },
+    {
+        pattern: /native binding|\.node['" ]|was compiled against|NODE_MODULE_VERSION|bindings file/i,
+        kind: "native-build",
+        nextStep: () => NATIVE_STEP
+    },
+    {
+        pattern: /could not be loaded, so its aliases|vite\.config[^ ]* could not|failed to load config/i,
+        kind: "app-config",
+        nextStep: () => "The app's Vite configuration did not load: fix what it says, or set appBuild: { viteConfig: false } in forgebook.config.ts"
+    },
+    {
+        pattern: /(?:Failed to resolve import|Cannot find (?:module|package)|Rollup failed to resolve|Could not resolve)\s+["']?([^"'\s]+)/i,
+        kind: "missing-import",
+        // never the name in the sentence: it is the project's text, and "install it" would make it an instruction
+        nextStep: (name) => name.startsWith(".") || name.startsWith("/")
+            ? "A file the component imports is not there: one a build step writes, perhaps; run that step first"
+            : "An import does not resolve: if the message names a package the project's manifest declares, install the project; if an alias of the app's build, check what forgebook dev says it read (appBuild)"
+    },
+    {
+        pattern: /does the file exist|Failed to fetch dynamically imported module/i,
+        kind: "missing-import",
+        nextStep: () => "A module of the story did not load: open the frame to see which, and install or generate it"
+    },
+    {
+        pattern: /\b(next\/headers|server-only|cookies\(\)|async Client Component|Server Component)\b/i,
+        kind: "server-only",
+        nextStep: () => "This component runs on the server: try a client component, or give it what it reads through the story's parameters"
+    },
+    {
+        pattern: /must be (?:used|rendered|wrapped) (?:with)?in|\bwithin (?:a|an|the) [A-Za-z<]*(?:Provider|Router|Context|Root)\b|outside (?:of )?(?:a |an |the )?[<A-Za-z]*(?:Provider|Router|Context)\b|No QueryClient set|could not find [a-z-]*\s?(?:store|context|react-redux)|use[A-Z]\w+(?:\(\))? (?:may be used|can only be used)|Cannot destructure property .* of .*(?:useContext|Context)|injection "[^"]+" not found|No [A-Za-z]+ (?:context|provider)|Context is (?:undefined|null)|lifecycle_outside_component|set_context_after_init|No router|without first setting the initial locale|Missing Provider/i,
+        kind: "provider",
+        nextStep: () => "The component needs what the app wraps it in: add a decorator to forgebook.preview with that provider (init's next steps name the ones the entry sets up)"
+    },
+    {
+        pattern: /Cannot apply unknown utility|@apply|Unexpected token|Unknown at rule|lightningcss|CssSyntaxError|Tailwind/i,
+        kind: "style-sheet",
+        nextStep: () => "A style sheet did not compile: check the preview's imports; forgebook dev prints what it read of the app's PostCSS and plugins"
+    },
+    {
+        pattern: /Cannot read propert(?:y|ies) of (?:undefined|null)|is not iterable|is not a function/i,
+        kind: "needs-props",
+        nextStep: () => "The component reads a prop or data the first story does not give: complete its args in the story file"
+    },
+    {
+        pattern: /did not say it was ready|timed? ?out/i,
+        kind: "timeout",
+        nextStep: () => "No answer in time: the component may wait for data the story does not give, or a plugin of the app's starts a process of its own (name it in appBuild.skipPlugins)"
+    }
+];
+/**
+ * Why a story did not draw.
+ *
+ * @param said - what the command or the frame said.
+ */
+export const diagnosed = (said) => {
+    const message = printable(said.trim().slice(0, MESSAGE_LENGTH));
+    for (const { pattern, kind, nextStep } of RULES) {
+        const found = said.match(pattern);
+        if (found !== null)
+            return { kind, message, nextStep: printable(nextStep(found[1] ?? "")) };
+    }
+    return {
+        kind: "unknown",
+        message,
+        nextStep: "Nothing known says this: open the frame with forgebook dev, and read the error it shows"
+    };
+};
+/** The diagnosis of a story that drew nothing visible. */
+export const BLANK = {
+    kind: "blank",
+    message: "The story drew and nothing can be seen: no text, and no element with a size",
+    nextStep: "The component may need props or data the first story does not give: complete its args in the story file"
+};

package/dist/bin/forgebook/agentSetup/drawRun.d.ts

@@ -0,0 +1,91 @@
+import { type StoryCheckResult } from "../../../src/storyCheck.ts";
+import { type DrawDiagnosis } from "./drawDiagnosis.ts";
+/** One component tried. */
+export type DrawAttempt = {
+    /** The component's file, or the story's when the project had it; from the project's folder. */
+    readonly file: string;
+    /** Why it did not draw. */
+    readonly diagnosis: DrawDiagnosis;
+};
+/** What came of trying to draw. */
+export type DrawResult = {
+    /** Whether a story drew, none was tried, or all that were tried failed. */
+    readonly status: "drawn" | "failed" | "not-run";
+    /** The story that drew, by its id. */
+    readonly story: string | undefined;
+    /** The story file it is in, from the project's folder. */
+    readonly storyFile: string | undefined;
+    /** Whether this run wrote that file. */
+    readonly isWritten: boolean;
+    /** The picture of it, absolute. */
+    readonly picture: string | undefined;
+    /** What was tried before it, each with why it did not draw. */
+    readonly attempts: readonly DrawAttempt[];
+    /** Why the run stopped short; none when it went through all it could. */
+    readonly stoppedBecause: string | undefined;
+    /** The wrappers of the app's entry written into the preview for it to draw; none when it needed none. */
+    readonly liftedProviders?: readonly string[];
+};
+/** What a step's process said. */
+type StepOutput = {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly isOk: boolean;
+};
+/** Where the steps run. */
+export type DrawContext = {
+    /** The project's folder. */
+    readonly dir: string;
+    /** The adapter's name. */
+    readonly framework: string;
+    /** The top folders to look for components in; every one when none. */
+    readonly folders?: readonly string[];
+    /**
+     * Gives the preview the providers of the app's entry: a way to undo it, when it could; run when components fail for want
+     * of one.
+     */
+    readonly liftProviders?: () => {
+        readonly names: readonly string[];
+        readonly undo: () => void;
+    } | undefined;
+    /** Writes what a framework's tools write on install and an install without scripts leaves undone; none has none. */
+    readonly prepare?: () => Promise<void>;
+    /** Runs the project's `forgebook` with these arguments. */
+    readonly run: (args: readonly string[]) => Promise<StepOutput>;
+};
+/**
+ * The file of the `forgebook` command a project installed; none when it has not.
+ *
+ * @remarks
+ * Run by Node and not through the package manager, which reads some of the arguments as its own: Yarn 1 takes `--json`.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const installedForgebook: (dir: string) => string | undefined;
+/**
+ * Runs the project's own `forgebook`.
+ *
+ * @param dir - the project's folder.
+ * @param env - the environment.
+ */
+export declare const projectForgebook: (dir: string, env: Readonly<Record<string, string | undefined>>) => (args: readonly string[]) => Promise<StepOutput>;
+/**
+ * Writes a framework's generated folder when it is missing: its `prepare` script does on an install, and every module fails
+ * to compile without it after one that ran no scripts. A failure is left for the stories to say.
+ *
+ * @param dir - the project's folder.
+ * @param framework - the adapter's name.
+ * @param env - the environment.
+ */
+export declare const prepareGenerated: (dir: string, framework: string, env: Readonly<Record<string, string | undefined>>) => Promise<void>;
+/** Why one story's result does not count as drawn; none when it does. */
+export declare const resultProblem: (result: StoryCheckResult) => DrawDiagnosis | undefined;
+/** The component to choose in a file of several: its name's, or the first. */
+export declare const chosenExport: (file: string, names: readonly string[]) => string | undefined;
+/**
+ * Draws a story of the project.
+ *
+ * @param context - where the steps run.
+ */
+export declare const runDraw: (context: DrawContext) => Promise<DrawResult>;
+export {};