forgebook 0.3.2 → 0.4.0

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

@@ -0,0 +1,30 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+import { type IdentifiedStory } from "./changeCoverage.ts";
+import type { ResolveSource } from "./storylessRoutes.ts";
+/** A story the reach found in the tree, with its source and the file as that source lists it. */
+export type FoundStory = IdentifiedStory & {
+    /** Its source's id. */
+    readonly source: string;
+    /** Its file, as its source lists it (`./src/Badge.stories.tsx`). */
+    readonly file: string;
+};
+/**
+ * The catalogue's stories with what each reaches, and each group's answer, whose failure a route has to say.
+ *
+ * @param loaded - the sources.
+ * @param tree - their story tree.
+ */
+export declare const identifiedStories: (loaded: RouteContext["loaded"], tree: RouteContext["tree"]) => Promise<{
+    readonly groups: readonly {
+        readonly source: string;
+        readonly reach: unknown;
+    }[];
+    readonly identified: readonly FoundStory[];
+}>;
+/**
+ * The stories a change touches and the changed UI files with their stories.
+ *
+ * @param context - what the routes read.
+ * @param resolveSource - finds the file of a source's module.
+ */
+export declare const changedAnswer: ({ config, loaded, tree, params, pages, view }: RouteContext, resolveSource: ResolveSource) => Promise<AgentAnswer>;

package/dist/src/vite/changedRoute.js

@@ -0,0 +1,197 @@
+/**
+ * The answer to `changed`: the stories a change touches, read from the files git names and the import graph "Used in"
+ * reads, and for each changed UI file the stories that show it.
+ *
+ * @remarks
+ * The preview and the style sheets it or a source's module name are shown by every story, though no story imports them.
+ * Only those count: a preview also imports its decorators, often from a library's barrel, and following that would
+ * make a component look covered for being exported.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { offersUsedIn, readsComponentDocs } from "../catalogue.js";
+import { isComponentDocs } from "../componentDocs.js";
+import { propsSignature, writtenSignature } from "../propsSignature.js";
+import { shellWord } from "../shellWord.js";
+import { sourceFiles } from "../sourceFiles.js";
+import { findComponentByTitle } from "../storyTree.js";
+import { storyLinks } from "./agentApi.js";
+import { settled } from "./agentRoutes.js";
+import { belongsToOtherCatalogue, changedUiFiles, deletedForms } from "./changeCoverage.js";
+import { findConfigFile } from "./configFile.js";
+import { catalogueChangedFiles, changeBase, changedFiles, noBaseReason } from "./gitChange.js";
+import { affectedStories } from "./storyReach.js";
+import { assetImports, sheetImports } from "./textImports.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** Whether a value is a list of stories with what they reach. */
+const isReach = (value) => Array.isArray(value);
+/** A file's text; a file that cannot be read has none. */
+const textOf = (file) => {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+};
+/** The files every story shows: the previews, and the sheets they and the sources' modules name, followed. */
+const everyStoryFiles = async (config, resolveSource) => {
+    const sourceModules = await Promise.all(config.sources.map(async (specifier) => {
+        const id = await resolveSource(specifier).catch(() => undefined);
+        return id?.split("?")[0];
+    }));
+    const modules = [...config.previews, ...sourceModules.flatMap((file) => file ?? [])]
+        .filter((file) => VITE_PATHS.isAbsolute(file))
+        .map((file) => VITE_PATHS.normalize(file));
+    const found = new Set(config.previews.map((file) => VITE_PATHS.normalize(file)));
+    const queue = modules.flatMap((file) => assetImports(file, textOf(file)));
+    while (queue.length > 0) {
+        const sheet = queue.pop() ?? "";
+        if (found.has(sheet))
+            continue;
+        found.add(sheet);
+        queue.push(...sheetImports(sheet, textOf(sheet)));
+    }
+    return found;
+};
+/** Why a group's reach could not be read, when that is what it answered. */
+const failureOf = (reach) => typeof reach === "string" ? `The stories' imports could not be read: ${reach}` : undefined;
+/** Without the import graph no story is found, which must not read as a change that touches none. */
+const graphProblems = (config) => {
+    if (offersUsedIn(config.lists))
+        return [];
+    return [
+        readsComponentDocs(config.lists)
+            ? "No story is found through the imports: the catalogue turns Used in off (usedIn: false), whose import graph this reads"
+            : "No story is found through the imports: the catalogue reads no component docs (componentDocs: false), whose programs read the import graph"
+    ];
+};
+/**
+ * The touched story files `forgebook new` wrote for other props than their component has now.
+ *
+ * @param touched - the touched story files, once each.
+ * @param dir - the catalogue's folder.
+ * @param root - the repository's folder, as the catalogue's folder is reached.
+ */
+const outdatedFiles = async (touched, dir, root) => {
+    const found = await Promise.all(touched.map(async (file) => {
+        const written = writtenSignature(textOf(file.absolute));
+        if (written === undefined)
+            return [];
+        // only a file that says what it was written for is compared: docs that cannot be read leave it alone
+        const docs = await settled(file.docs);
+        if (!("value" in docs) || !isComponentDocs(docs.value))
+            return [];
+        const current = propsSignature(docs.value.props);
+        if (current === written)
+            return [];
+        const path = VITE_PATHS.relative(dir, file.absolute);
+        return [
+            {
+                file: VITE_PATHS.relative(root, file.absolute),
+                path,
+                story: file.story,
+                component: docs.value.name,
+                written,
+                current,
+                // the names reach a command an agent runs, so they are quoted; the signature is eight hexadecimal digits
+                fix: `check the args in ${shellWord(path)} against the props npx forgebook story ${shellWord(file.story)} --json lists, then set its forgebook-props line to ${current}; or write it again with npx forgebook new on the component file it imports, with --force, which replaces any edit`
+            }
+        ];
+    }));
+    return found.flat();
+};
+/**
+ * The catalogue's stories with what each reaches, and each group's answer, whose failure a route has to say.
+ *
+ * @param loaded - the sources.
+ * @param tree - their story tree.
+ */
+export const identifiedStories = async (loaded, tree) => {
+    const groups = await Promise.all(loaded.sources.flatMap((source) => source.files.map(async (group) => ({ source: source.id, reach: await group.reach?.() }))));
+    const identified = groups.flatMap(({ source, reach }) => (isReach(reach) ? reach : []).flatMap((story) => {
+        const component = findComponentByTitle(tree, source, story.title)?.component;
+        const found = [...(component?.stories ?? []), ...(component?.unlisted ?? [])].find((each) => each.exportName === story.exportName);
+        return found === undefined ? [] : [{ id: found.id, reach: story, source, file: found.file }];
+    }));
+    return { groups, identified };
+};
+/**
+ * The stories a change touches and the changed UI files with their stories.
+ *
+ * @param context - what the routes read.
+ * @param resolveSource - finds the file of a source's module.
+ */
+export const changedAnswer = async ({ config, loaded, tree, params, pages, view }, resolveSource) => {
+    const since = params.get("since") || "HEAD";
+    const base = await changeBase(config.dir, since);
+    if (base === undefined)
+        return { status: 400, body: { error: await noBaseReason(config.dir, since) } };
+    const { root, files, deleted } = await changedFiles(config.dir, base);
+    const { groups, identified } = await identifiedStories(loaded, tree);
+    const realDir = await realpath(config.dir);
+    const absolute = catalogueChangedFiles(config.dir, realDir, root, files);
+    const gone = new Set(deleted);
+    const changed = absolute.flatMap((file, index) => gone.has(files[index] ?? "") ? deletedForms(file) : [file]);
+    const shownByAll = await everyStoryFiles(config, resolveSource);
+    const touched = absolute.some((file) => shownByAll.has(file))
+        ? identified.map(({ reach }) => reach)
+        : affectedStories(identified.map(({ reach }) => reach), changed);
+    const touchedSet = new Set(touched);
+    const touchedFiles = new Map();
+    for (const story of identified.filter(({ reach }) => touchedSet.has(reach))) {
+        const source = loaded.sources.find((each) => each.id === story.source);
+        if (source !== undefined && !touchedFiles.has(story.reach.storyFile))
+            touchedFiles.set(story.reach.storyFile, {
+                absolute: story.reach.storyFile,
+                story: story.id,
+                docs: sourceFiles(source).docs[story.file]
+            });
+    }
+    const outdated = await outdatedFiles([...touchedFiles.values()], config.dir, VITE_PATHS.join(config.dir, VITE_PATHS.relative(realDir, root)));
+    const stories = identified
+        .filter(({ reach }) => touchedSet.has(reach))
+        .map(({ id, reach }) => ({
+        id,
+        title: reach.title,
+        links: storyLinks(pages, id, view)
+    }));
+    const { uiFiles, outside } = changedUiFiles({
+        files: files.map((file, index) => {
+            const inCatalogue = absolute[index] ?? "";
+            return {
+                file,
+                path: VITE_PATHS.relative(config.dir, inCatalogue),
+                absolute: inCatalogue,
+                isDeleted: gone.has(file)
+            };
+        }),
+        stories: identified,
+        everyStoryFiles: shownByAll,
+        isOtherCatalogues: (file) => belongsToOtherCatalogue(file, VITE_PATHS.normalize(config.dir), VITE_PATHS.join(config.dir, VITE_PATHS.relative(realDir, root)), (folder) => findConfigFile(folder) !== undefined),
+        readText: (file) => textOf(VITE_PATHS.join(root, file))
+    });
+    const unread = loaded.sources.flatMap((source) => sourceFiles(source).problems ?? []);
+    const problems = [
+        ...new Set([
+            ...unread,
+            ...graphProblems(config),
+            ...groups.flatMap(({ reach }) => failureOf(reach) ?? []),
+            ...tree.problems
+        ])
+    ];
+    const body = {
+        schema: 1,
+        since,
+        files,
+        stories,
+        uiFiles,
+        outside,
+        problems,
+        ...(unread.length === 0 ? {} : { unread }),
+        ...(outdated.length === 0 ? {} : { outdated })
+    };
+    return { status: 200, body };
+};

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

@@ -8,7 +8,15 @@
  * output), and it does not read a `#` as a colour unless it stands as a value. A raw colour is named whether or not a
  * token is close; a size only when it equals a token, since most sizes are not the design system's. A fix is the token's
  * name, not code to paste, and it is offered only when one token clearly fits: forcing the nearest is how a wrong colour
- * gets a token's name. Props, imports and deprecated components are not checked here.
+ * gets a token's name. Props are the type checker's; what a change reuses is `reuseCheck.ts`'s.
+ *
+ * React reads a bare number in a style object as pixels, so `padding: 16` there is a size like `16px`. The same keys are
+ * options of other code (`fitView({ padding: 16 })`), and an added line seldom shows where its object starts: such a
+ * number fails only on a line that says the object is a style, and is advice elsewhere.
+ *
+ * A token read from an application says less than one in a tokens file, which someone wrote for this use: a project's
+ * `--sidebar-width: 16px` does not make every `16px` a mistake. So a size is compared with those of the same role only:
+ * spacing with spacing, a radius with a radius, a font's size with a font's size. A size with no such role is left alone.
  *
  * @module
  */
@@ -23,7 +31,18 @@ export type AddedLine = {
     readonly text: string;
 };
 /** The rules. */
-export type CodeRule = "raw-color" | "raw-size" | "suppression" | "deleted-test";
+export type CodeRule = "raw-color" | "raw-size" | "suppression" | "deleted-test" | "deprecated-component" | "duplicate-component" | "composition";
+/** A value a comment says is meant. */
+export type ExcusedValue = {
+    /** The file, relative to the repository. */
+    readonly file: string;
+    /** The comment's line. */
+    readonly line: number;
+    /** The rule it excuses. */
+    readonly rule: "raw-color" | "raw-size" | "duplicate-component" | "composition";
+    /** Why, as the comment says. */
+    readonly reason: string;
+};
 /** What a check found. */
 export type CodeProblem = {
     /** The rule. */
@@ -39,6 +58,27 @@ export type CodeProblem = {
     /** What to do, in a sentence. */
     readonly message: string;
 };
+/** A size, signed or in Tailwind's brackets. */
+export declare const SIZE: RegExp;
+/** The files where a raw value is a mistake: styles and components. */
+export declare const CHECKED_FILE: RegExp;
+/**
+ * Where raw values belong: stories, tests, tokens and what a tool wrote; and what is drawn where a page's custom
+ * properties do not reach, as an email or a generated social image.
+ */
+export declare const LEFT_ALONE: RegExp;
+/** A line that defines a value: a custom property or a Sass variable, where raw values belong. */
+export declare const DEFINES_VALUE: RegExp;
+/** Past this a line is data or a minified bundle, written by no one, and these patterns would take long to read it. */
+export declare const LONGEST_LINE = 2000;
+/** What a size is for. */
+export type SizeRole = "space" | "radius" | "font";
+/**
+ * A line's code, without what follows a `//` or a comment's start.
+ *
+ * @param text - the line.
+ */
+export declare const withoutComment: (text: string) => string;
 /**
  * The lines a unified diff adds. A header is read only outside a hunk, since an added line of `++ x` looks like one.
  *
@@ -59,7 +99,69 @@ export declare const fileLines: (file: string, text: string) => AddedLine[];
  */
 export declare const deletedTests: (deleted: readonly string[]) => CodeProblem[];
 /**
- * What lines a change adds break. Only code is read: a rule named in a sentence is not that rule.
+ * The colours written by hand in a line of code, leaving out what is not the system's to give.
+ *
+ * @param written - the line, its comment taken off.
+ */
+export declare const rawColorsOf: (written: string) => readonly string[];
+/**
+ * What a size in a line is for, and whether a class holds it; none when it stands in a sum no token can replace.
+ *
+ * @param before - the line up to the size.
+ */
+export declare const roleInLine: (before: string) => {
+    readonly role: SizeRole;
+    readonly isClass: boolean;
+} | undefined;
+/**
+ * The tokens a size can be compared with where it stands: a tokens file's all, an application's of its role. Tailwind's
+ * own scale counts only in a class's brackets, where a class of that scale says the same (`p-[16px]`, `p-4`): in a sheet
+ * or a style, a size equal to a step of a scale nobody there chose means nothing.
+ *
+ * @param tokens - the tokens.
+ * @param before - the line up to the size.
+ */
+export declare const sizeTokens: (tokens: readonly DesignToken[], before: string) => readonly DesignToken[];
+/** Something to weigh, which fails nothing. */
+export type CodeAdvice = {
+    /** The file, relative to the repository. */
+    readonly file: string;
+    /** The line in it. */
+    readonly line: number;
+    /** What to weigh, in a sentence. */
+    readonly message: string;
+};
+/** What the checks found: what fails, and what to weigh. */
+export type CodeFindings = {
+    /** What fails. */
+    readonly problems: readonly CodeProblem[];
+    /** What to weigh. */
+    readonly advice: readonly CodeAdvice[];
+};
+/**
+ * A file with its block comments blanked and its lines kept, so what is commented out does not count as used. A `/*` right
+ * after a word or a star or a quote is a path's pattern (`src/**` then `/*.ts`), not a comment.
+ *
+ * @param text - the file.
+ */
+export declare const withoutBlockComments: (text: string) => string;
+/**
+ * The values a change excuses with a comment: said in the answer, so a reader sees every one, and an agent gains nothing
+ * by hiding a value this way.
+ *
+ * @param lines - the added lines.
+ */
+export declare const excusedValues: (lines: readonly AddedLine[]) => ExcusedValue[];
+/**
+ * What lines a change adds break, and what they hold to weigh. Only code is read: a rule named in a sentence is not that
+ * rule.
+ *
+ * @param lines - the added lines.
+ * @param tokens - the catalogue's tokens; none skips the checks on values, which have nothing to compare with.
+ */
+export declare const codeFindings: (lines: readonly AddedLine[], tokens: readonly DesignToken[]) => CodeFindings;
+/**
+ * What lines a change adds break.
  *
  * @param lines - the added lines.
  * @param tokens - the catalogue's tokens; none skips the checks on values, which have nothing to compare with.