forgebook 0.3.3 → 0.4.0

package/dist/src/vite/appAudit.js

@@ -0,0 +1,333 @@
+/**
+ * What a project actually uses: colours and sizes by how often, what is written by hand, and what the code asks of a token.
+ *
+ * @remarks
+ * Pure: files and tokens in, a report out. Discovery and not a system imposed: on a project with no tokens it says which
+ * values are the system in practice ("37 greys, 5 used 90% of the time"), and someone decides. It reads the same lines
+ * `check-code` does and leaves out what that leaves out, so the two never disagree on what a raw value is. Equal colours in
+ * different notations are one colour, since a palette is what the eye sees and not how a file spells it.
+ *
+ * @module
+ */
+import { DEFINES_VALUE, LEFT_ALONE, LONGEST_LINE, rawColorsOf, roleInLine, SIZE, sizeTokens, withoutBlockComments, withoutComment } from "./checkCode.js";
+import { nearestTokens, parsedColor } from "./nearestToken.js";
+/** How many values a list gives unless asked otherwise. */
+const TOP = 10;
+/** Below this distance in Oklab two colours are the same to the eye. */
+const NEAR = 0.02;
+/** Under this chroma a colour reads as grey: a neutral with a cool cast (`#64748b`) is one, as a palette calls it. */
+const GREY_CHROMA = 0.045;
+/** Near white a little chroma is already a tint (`#fef2f2`), so the limit falls with this share of what lightness is left. */
+const GREY_NEAR_WHITE = 0.3;
+/** What the conversion leaves of chroma in a pure white. */
+const ROUNDING = 0.001;
+/** The share of a kind's uses the "most used" count covers. */
+const MOST = 0.9;
+/** How long a site's text is kept. */
+const SITE_TEXT = 120;
+/** A colour's class: what it paints, and the rest of the name. */
+export const COLOR_CLASS = /(?<![\w-])(?:bg|text|border(?:-[trblxyse])?|ring|fill|stroke|from|via|to|divide|outline|decoration|accent|caret|placeholder|shadow)-([a-z][\w-]*)(?:\/[\w.%[\]]+)?(?![\w-])/g;
+/** A reference to a custom property. */
+const VAR_USE = /var\(\s*(--[\w-]+)/g;
+/** A spacing class on a scale. */
+export const SPACE_CLASS = /(?<![\w-])-?(?:[pm][xytrblse]?|gap(?:-[xy])?|space-[xy])-(\d+(?:\.\d+)?)(?![\w.-])/g;
+/** A radius class. */
+export const RADIUS_CLASS = /(?<![\w-])rounded(?:-[trblse]{1,2})?-(xs|sm|md|lg|xl|2xl|3xl|4xl)(?![\w-])/g;
+/** A font's size class. */
+export const FONT_CLASS = /(?<![\w-])text-(xs|sm|base|lg|xl|[2-9]xl)(?![\w-])/g;
+/** A size as a number in a style object, which has no unit to find it by. */
+const STYLE_NUMBER = /\b(margin|padding|gap|rowGap|columnGap|fontSize|borderRadius)(?:Top|Right|Bottom|Left|Inline|Block|Start|End|X|Y)*\s*:\s*(\d+(?:\.\d+)?)\s*[,}]/g;
+/** What a style object's property is for. */
+const STYLE_ROLES = {
+    margin: "space",
+    padding: "space",
+    gap: "space",
+    rowGap: "space",
+    columnGap: "space",
+    fontSize: "font",
+    borderRadius: "radius"
+};
+/** The files read for values: what `check-code` reads. */
+const IS_READ = /\.(?:css|scss|sass|less|tsx|jsx|vue|svelte|astro)$/;
+/** Adds a use to a tally by a key. */
+const tallied = (tallies, key, value, file, how) => {
+    const known = tallies.get(key) ?? { value, count: 0, hardCoded: 0, files: new Set(), hardFiles: new Set() };
+    tallies.set(key, known);
+    known.count += 1;
+    known.files.add(file);
+    if (how.isHard) {
+        known.hardCoded += 1;
+        known.hardFiles.add(file);
+    }
+    if (how.token !== undefined)
+        known.through ??= how.token;
+    if (how.suggested !== undefined)
+        known.suggested ??= how.suggested;
+};
+/** A colour's key: the same colour in any notation has one. */
+const colorKey = (color) => [color.l, color.a, color.b, color.alpha].map((part) => part.toFixed(3)).join(" ");
+/** The tallies as values, the most used first. */
+const valuesOf = (tallies) => tallies.toSorted((a, b) => b.count - a.count);
+/** A tally as a report gives it, with the token that fits when asked about colours. */
+const reported = ({ value, count, hardCoded, files, hardFiles }, token) => ({
+    value,
+    count,
+    files: files.size,
+    hardCoded,
+    hardCodedFiles: hardFiles.size,
+    ...(token === undefined ? {} : { token })
+});
+/** The token a raw colour equals or is close to, that holds in every theme. */
+const tokenFor = (tokens, value) => {
+    const name = nearestTokens(tokens, value, "color").matches.find((match) => match.isClose && match.mode === undefined)?.name;
+    return tokens.find((token) => token.name === name);
+};
+/** A value written by hand, with the token that fits it. */
+const reportedColor = (each, tokens) => {
+    const token = tokenFor(tokens, each.value);
+    const follows = token !== undefined && Object.values(token.modes).some((value) => value !== token.value);
+    return { ...reported(each, token?.name), ...(follows ? { tokenFollowsTheme: true } : {}) };
+};
+/**
+ * Colours the eye would hardly tell apart, each group once, the most used first. Two tokens close together are a choice
+ * (a page and a card a step apart), so a group counts only with a colour written by hand in it.
+ */
+const nearGroups = (tallies) => {
+    const groups = [];
+    for (const { value, hardCoded } of valuesOf(tallies)) {
+        const color = parsedColor(value);
+        if (color === undefined)
+            continue;
+        const near = groups.find(({ color: other }) => Math.hypot(color.l - other.l, color.a - other.a, color.b - other.b) < NEAR &&
+            color.alpha === other.alpha);
+        if (near === undefined)
+            groups.push({ color, values: [value], hasHandWritten: hardCoded > 0 });
+        else {
+            near.values.push(value);
+            near.hasHandWritten ||= hardCoded > 0;
+        }
+    }
+    return groups
+        .filter(({ values, hasHandWritten }) => values.length > 1 && hasHandWritten)
+        .map(({ values }) => values);
+};
+/** How many of the most used values it takes to cover most uses. */
+const coveringMost = (sorted) => {
+    const total = sorted.reduce((sum, each) => sum + each.count, 0);
+    let covered = 0;
+    for (const [index, each] of sorted.entries()) {
+        covered += each.count;
+        if (covered >= total * MOST)
+            return index + 1;
+    }
+    return sorted.length;
+};
+/** A colour used through a token. */
+const talliedToken = (found, token, file) => {
+    const color = parsedColor(token.value);
+    const key = color === undefined ? token.name : colorKey(color);
+    tallied(found.colors, key, token.value, file, { isHard: false, token: token.name });
+    if (token.origin?.kind === "tailwind-default")
+        found.defaultPalette += 1;
+    else
+        found.throughTokens += 1;
+};
+/** The colours in a line. */
+const readColors = (found, index, code, file) => {
+    for (const value of rawColorsOf(code)) {
+        const color = parsedColor(value);
+        tallied(found.colors, color === undefined ? value : colorKey(color), value, file, { isHard: true });
+    }
+    for (const match of code.matchAll(COLOR_CLASS)) {
+        const token = index.colorUtilities.get(match[1] ?? "");
+        if (token !== undefined)
+            talliedToken(found, token, file);
+    }
+    for (const match of code.matchAll(VAR_USE)) {
+        const token = index.byName.get(match[1] ?? "");
+        if (token?.type === "color")
+            talliedToken(found, token, file);
+    }
+};
+/** A size in pixels as a key, a rem being 16: one size in any unit is one size. */
+const sizeKey = (value) => {
+    const match = /^(-?\d*\.?\d+)(px|rem)?$/.exec(value);
+    return match === null ? value : `${Math.abs(Number(match[1]) * (match[2] === "rem" ? 16 : 1))}px`;
+};
+/** A class's box and not a space between things: a width of 240px is not a spacing to name. */
+const BOX_CLASS = /(?:^|[\s"'`:])-?(?:[wh]|size|(?:min|max)-[wh]|inset(?:-[xy])?|top|right|bottom|left)-\[[^\]]*$/;
+/** A size this small is a hairline or nothing, and no scale's business. */
+const SMALLEST_TOLD = 2;
+/** The sizes written by hand in a line: what a report counts and what `--value` lists are this one reading. */
+const handSizesOf = (code) => [
+    ...[...code.matchAll(SIZE)].flatMap((match) => {
+        const value = match[1] ?? "";
+        const before = code.slice(0, match.index + match[0].indexOf(value));
+        const where = roleInLine(before);
+        const key = sizeKey(value);
+        return where === undefined || BOX_CLASS.test(before) || Number.parseFloat(key) < SMALLEST_TOLD
+            ? []
+            : [{ key, role: where.role, before, value }];
+    }),
+    ...[...code.matchAll(STYLE_NUMBER)].flatMap((match) => {
+        const role = STYLE_ROLES[match[1] ?? ""];
+        const key = sizeKey(match[2] ?? "");
+        return role === undefined || Number.parseFloat(key) < SMALLEST_TOLD
+            ? []
+            : [{ key, role, value: `${match[2] ?? ""}px` }];
+    })
+];
+/** The sizes written by hand in a line, each with the token of its role that equals it. */
+const readHandSizes = (found, tokens, code, file) => {
+    for (const { key, role, before, value } of handSizesOf(code)) {
+        const candidates = before === undefined ? [] : sizeTokens(tokens, before);
+        const suggested = nearestTokens(candidates, value, "dimension").matches.find((each) => each.isExact && each.mode === undefined)?.name;
+        tallied(found.sizes[role], key, key, file, { isHard: true, suggested });
+    }
+};
+/** The sizes in a line through a class of a scale. */
+const readClassSizes = (found, index, code, file) => {
+    const classes = [
+        [SPACE_CLASS, "space", "--spacing-"],
+        [RADIUS_CLASS, "radius", "--radius-"],
+        [FONT_CLASS, "font", "--text-"]
+    ];
+    for (const [pattern, role, prefix] of classes) {
+        for (const match of code.matchAll(pattern)) {
+            const token = index.byName.get(`${prefix}${match[1]}`);
+            if (token !== undefined) {
+                const key = sizeKey(token.value);
+                tallied(found.sizes[role], key, key, file, { isHard: false, token: token.name });
+            }
+        }
+    }
+};
+/** A role's sizes as a report gives them. */
+const sizesOf = (tallies, top) => {
+    const sorted = valuesOf([...tallies.values()]);
+    return {
+        uses: sorted.reduce((sum, each) => sum + each.count, 0),
+        hardCoded: sorted.reduce((sum, each) => sum + each.hardCoded, 0),
+        distinct: sorted.length,
+        top: sorted.slice(0, top).map((each) => reported(each, each.through ?? each.suggested)),
+        handWritten: sorted
+            .filter((each) => each.hardCoded > 0)
+            .toSorted((first, second) => second.hardCoded - first.hardCoded)
+            .slice(0, top)
+            .map((each) => reported(each, each.suggested))
+    };
+};
+/** The colours as a report gives them. */
+const colorsOf = (found, tokens, top) => {
+    const sorted = valuesOf([...found.colors.values()]);
+    const greys = sorted.filter(({ value }) => {
+        const color = parsedColor(value);
+        if (color === undefined || color.alpha !== 1)
+            return false;
+        return Math.hypot(color.a, color.b) <= Math.min(GREY_CHROMA, (1 - color.l) * GREY_NEAR_WHITE) + ROUNDING;
+    });
+    const withToken = (each) => each.through === undefined ? reportedColor(each, tokens) : reported(each, each.through);
+    return {
+        uses: sorted.reduce((sum, each) => sum + each.count, 0),
+        throughTokens: found.throughTokens,
+        defaultPalette: found.defaultPalette,
+        hardCoded: sorted.reduce((sum, each) => sum + each.hardCoded, 0),
+        distinct: sorted.length,
+        top: sorted.slice(0, top).map(withToken),
+        handWritten: sorted
+            .filter((each) => each.hardCoded > 0)
+            .toSorted((first, second) => second.hardCoded - first.hardCoded)
+            .slice(0, top)
+            .map((each) => reportedColor(each, tokens)),
+        greys: {
+            distinct: greys.length,
+            coveringMost: coveringMost(greys),
+            top: greys.slice(0, top).map(withToken)
+        },
+        nearDuplicates: nearGroups(sorted).slice(0, top)
+    };
+};
+/** The lines of a file worth reading for values. */
+const codeLines = ({ file, text }) => {
+    if (!IS_READ.test(file) || LEFT_ALONE.test(file))
+        return [];
+    return withoutBlockComments(text)
+        .split("\n")
+        .flatMap((plain, index) => plain.length > LONGEST_LINE || DEFINES_VALUE.test(plain)
+        ? []
+        : [
+            {
+                line: index + 1,
+                code: withoutComment(plain).replace(/(?<![\w-])--[\w-]+\s*:[^;}]*;?/g, ""),
+                text: withoutComment(plain)
+            }
+        ]);
+};
+/**
+ * What a project's files use.
+ *
+ * @param files - its files.
+ * @param tokens - the tokens known; none is a report on values alone.
+ * @param top - how many values a list gives; 10 by default.
+ */
+export const valueAudit = (files, tokens, top = TOP) => {
+    const index = {
+        colorUtilities: new Map(tokens.flatMap((token) => token.type === "color" && token.utility !== undefined ? [[token.utility, token]] : [])),
+        byName: new Map(tokens.map((token) => [token.name, token]))
+    };
+    const found = {
+        colors: new Map(),
+        sizes: { space: new Map(), radius: new Map(), font: new Map() },
+        throughTokens: 0,
+        defaultPalette: 0
+    };
+    let lines = 0;
+    let read = 0;
+    for (const each of files) {
+        const code = codeLines(each);
+        if (code.length > 0)
+            read += 1;
+        lines += code.length;
+        for (const { code: written } of code) {
+            readColors(found, index, written, each.file);
+            readHandSizes(found, tokens, written, each.file);
+            readClassSizes(found, index, written, each.file);
+        }
+    }
+    return {
+        files: read,
+        lines,
+        colors: colorsOf(found, tokens, top),
+        sizes: {
+            space: sizesOf(found.sizes.space, top),
+            radius: sizesOf(found.sizes.radius, top),
+            font: sizesOf(found.sizes.font, top)
+        }
+    };
+};
+/**
+ * Where a value written by hand stands: what an agent replacing it edits.
+ *
+ * @param files - the project's files.
+ * @param value - the value, as code writes it; a colour matches in any notation.
+ */
+export const valueSites = (files, value) => {
+    const wanted = parsedColor(value);
+    const site = (file, line, text, role) => ({
+        file,
+        line,
+        text: text.trim().slice(0, SITE_TEXT),
+        ...(role === undefined ? {} : { role })
+    });
+    return files.flatMap((each) => codeLines(each).flatMap(({ line, code, text }) => {
+        if (wanted === undefined) {
+            const roles = handSizesOf(code).filter(({ key }) => key === sizeKey(value));
+            return roles.map(({ role }) => site(each.file, line, text, role));
+        }
+        const isIt = rawColorsOf(code).some((written) => {
+            const color = parsedColor(written);
+            return color !== undefined && colorKey(color) === colorKey(wanted);
+        });
+        return isIt ? [site(each.file, line, text)] : [];
+    }));
+};

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

@@ -0,0 +1,53 @@
+/**
+ * The `appBuild` option of a catalogue's configuration: how much of the app's own build its stories are drawn with,
+ * checked and resolved.
+ *
+ * @remarks
+ * A catalogue is its own Vite project, so what the app's build does for its components (aliases, Tailwind, PostCSS, its
+ * Vite plugins) has to be read from the app, or every story is told apart from the app by what it lacks. All of it is on
+ * by default, and each part can be turned off here. The command that reads the parts is `bin/forgebook/appBuild`.
+ *
+ * @module
+ */
+/** How much of the app's build a catalogue reads, as `forgebook.config.ts` writes it. */
+export type AppBuildOption = false | {
+    /**
+     * The app's Vite configuration, by path from the catalogue's folder; the `vite.config` beside the catalogue's by
+     * default. It is loaded as `vite dev` loads it, which runs its code and that of the plugins it makes. `false` reads
+     * none.
+     */
+    readonly viteConfig?: string | false;
+    /** Whether to read `paths` from `tsconfig.json`, which runs nothing; `true` by default. */
+    readonly tsconfigPaths?: boolean;
+    /** Whether to run the project's `postcss.config`, which runs its code and its plugins'; `true` by default. */
+    readonly postcss?: boolean;
+    /** The names of the app's Vite plugins to leave out, for one that only an app's build needs. */
+    readonly skipPlugins?: readonly string[];
+    /** The names of the app's Vite plugins to keep although Forgebook leaves them out by default. */
+    readonly keepPlugins?: readonly string[];
+};
+/** The `appBuild` option, resolved. */
+export type ResolvedAppBuild = {
+    /** The app's Vite configuration by its path from the catalogue's folder, the one found when none, or `false`. */
+    readonly viteConfig: string | false | undefined;
+    /** Whether `tsconfig.json`'s `paths` are read. */
+    readonly tsconfigPaths: boolean;
+    /** Whether the project's PostCSS runs. */
+    readonly postcss: boolean;
+    /** The names of the app's plugins to leave out. */
+    readonly skipPlugins: readonly string[];
+    /** The names of the app's plugins to keep whatever the default says. */
+    readonly keepPlugins: readonly string[];
+};
+/**
+ * Why an `appBuild` option cannot be used, or none.
+ *
+ * @param value - the option, as the configuration gives it.
+ */
+export declare const appBuildProblem: (value: unknown) => string | undefined;
+/**
+ * The `appBuild` option, resolved.
+ *
+ * @param option - the option, checked by `appBuildProblem`.
+ */
+export declare const resolvedAppBuild: (option: AppBuildOption | undefined) => ResolvedAppBuild;

package/dist/src/vite/appBuildOption.js

@@ -0,0 +1,55 @@
+/**
+ * The `appBuild` option of a catalogue's configuration: how much of the app's own build its stories are drawn with,
+ * checked and resolved.
+ *
+ * @remarks
+ * A catalogue is its own Vite project, so what the app's build does for its components (aliases, Tailwind, PostCSS, its
+ * Vite plugins) has to be read from the app, or every story is told apart from the app by what it lacks. All of it is on
+ * by default, and each part can be turned off here. The command that reads the parts is `bin/forgebook/appBuild`.
+ *
+ * @module
+ */
+/** Whether a value is a list of texts. */
+const isTextList = (value) => Array.isArray(value) && value.every((each) => typeof each === "string");
+/**
+ * Why an `appBuild` option cannot be used, or none.
+ *
+ * @param value - the option, as the configuration gives it.
+ */
+export const appBuildProblem = (value) => {
+    if (value === undefined || value === false)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return "`appBuild` is false or `{ viteConfig, tsconfigPaths, postcss, skipPlugins, keepPlugins }`";
+    const fields = new Map(Object.entries(value));
+    const viteConfig = fields.get("viteConfig");
+    if (viteConfig !== undefined &&
+        viteConfig !== false &&
+        (typeof viteConfig !== "string" || viteConfig === ""))
+        return "`appBuild.viteConfig` is a path or false";
+    for (const key of ["tsconfigPaths", "postcss"]) {
+        const field = fields.get(key);
+        if (field !== undefined && typeof field !== "boolean")
+            return `\`appBuild.${key}\` is true or false`;
+    }
+    for (const key of ["skipPlugins", "keepPlugins"]) {
+        const field = fields.get(key);
+        if (field !== undefined && !isTextList(field))
+            return `\`appBuild.${key}\` is a list of plugin names`;
+    }
+    return undefined;
+};
+/**
+ * The `appBuild` option, resolved.
+ *
+ * @param option - the option, checked by `appBuildProblem`.
+ */
+export const resolvedAppBuild = (option) => option === false
+    ? { viteConfig: false, tsconfigPaths: false, postcss: false, skipPlugins: [], keepPlugins: [] }
+    : {
+        viteConfig: option?.viteConfig,
+        tsconfigPaths: option?.tsconfigPaths ?? true,
+        postcss: option?.postcss ?? true,
+        skipPlugins: option?.skipPlugins ?? [],
+        keepPlugins: option?.keepPlugins ?? []
+    };

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

@@ -0,0 +1,92 @@
+import { type CssReading } from "./cssDeclarations.ts";
+import { type TailwindConfigReading } from "./tailwindConfigTokens.ts";
+/** What `components.json` says of a project's system. */
+export type ShadcnConfig = {
+    /** Its path. */
+    readonly file: string;
+    /** The sheet with its variables. */
+    readonly css: string | undefined;
+    /** Its Tailwind configuration file. */
+    readonly config: string | undefined;
+};
+/** One sheet, read. */
+export type ReadSheet = {
+    /** Its absolute path. */
+    readonly file: string;
+    /** Its text. */
+    readonly text: string;
+    /** What it declares. */
+    readonly reading: CssReading;
+};
+/** One configuration file, read. */
+export type ReadConfig = {
+    /** Its absolute path. */
+    readonly file: string;
+    /** Its text. */
+    readonly text: string;
+    /** What it declares. */
+    readonly reading: TailwindConfigReading;
+};
+/**
+ * A regular file's text, or none when it is something else, cannot be read or is too large to be written by hand.
+ *
+ * @param file - its path.
+ */
+export declare const smallFileText: (file: string) => string | undefined;
+/**
+ * The source files of a folder, relative to it: what git tracks and would track, or a walk when this is not a repository.
+ *
+ * @param dir - the folder.
+ * @param patterns - what git is asked for (`*.tsx`).
+ * @param kind - the same as a pattern for a file's name, for the walk.
+ * @param left - what the walk leaves out, as git would by what it ignores.
+ */
+export declare const listedFiles: (dir: string, patterns: readonly string[], kind: RegExp, left: RegExp) => string[];
+/**
+ * The file of a package, looked for from a folder up, as Node finds packages.
+ *
+ * @param dir - where to start.
+ * @param path - the package's name and the path in it.
+ */
+export declare const packageFile: (dir: string, path: string) => string | undefined;
+/**
+ * The repository a folder is in: the nearest above holding `.git`, or the folder itself in none.
+ *
+ * @param dir - the folder.
+ */
+export declare const repositoryOf: (dir: string) => string;
+/**
+ * Reads `components.json`, from a folder up; a file that says nothing plain gives nothing.
+ *
+ * @param dir - where to start.
+ */
+export declare const shadcnConfig: (dir: string) => ShadcnConfig | undefined;
+/**
+ * The sheets of installed packages that the application's sheets import, for the custom properties they declare: a
+ * reference to one of those has a value, though it is no token of this application's.
+ *
+ * @param dir - the catalogue's folder.
+ * @param sheets - the sheets read.
+ * @returns the texts found, and what each import that could not be read was called, a missing one included.
+ */
+export declare const importedPackageSheets: (dir: string, sheets: readonly ReadSheet[]) => {
+    readonly texts: readonly string[];
+    readonly unreadable: readonly string[];
+};
+/**
+ * Reads a catalogue's sheets, the one `components.json` names first, and what they import from the workspace, each once.
+ *
+ * @param dir - the catalogue's folder.
+ * @param shadcn - what `components.json` says.
+ * @param unread - told of what is left out.
+ */
+export declare const readSheets: (dir: string, shadcn: ShadcnConfig | undefined, unread: string[]) => ReadSheet[];
+/**
+ * Reads a catalogue's Tailwind configurations: what `components.json` and the sheets name, and the one in its folder.
+ *
+ * @param dir - the catalogue's folder.
+ * @param shadcn - what `components.json` says.
+ * @param sheets - the sheets read, for their `@config`s.
+ * @param unread - told of what is left out.
+ */
+export declare const readConfigs: (dir: string, shadcn: ShadcnConfig | undefined, sheets: readonly ReadSheet[], unread: string[]) => ReadConfig[];