forgebook 0.3.2 → 0.4.0

package/dist/src/vite/appTokens.js

@@ -0,0 +1,275 @@
+/**
+ * The design system an application already has, read from its files with nothing written for it: custom properties,
+ * Tailwind's `@theme` and configuration, and what shadcn's `components.json` points at.
+ *
+ * @remarks
+ * Nobody writes a tokens file for a catalogue they did not ask for, and an agent that finds no tokens writes colours by
+ * hand, so this is what a catalogue with no tokens file reads. No project code runs: the files are read as text
+ * (`appTokenFiles.ts`, `tailwindConfigTokens.ts`). Tailwind's default theme counts, since a project on Tailwind has it
+ * whether or not it writes any of its own, but it comes last in a list: it is not what makes this project's system.
+ *
+ * Later sources stand over earlier ones, and a difference between two files is a clash, reported as a tokens file's
+ * would be: other sheets, then the configuration, then the sheet `components.json` names.
+ *
+ * @module
+ */
+import { realpathSync } from "node:fs";
+import { dirname, relative } from "node:path";
+import { packageFile, readConfigs, readSheets, shadcnConfig, smallFileText } from "./appTokenFiles.js";
+import { readCssText } from "./cssDeclarations.js";
+import { colorWrappers, resolvedTokens } from "./cssTokenValues.js";
+import { readTailwindPalette } from "./tailwindConfigTokens.js";
+import { tokenClashes } from "./tokenClashes.js";
+import { unresolvedTokens } from "./unresolvedTokens.js";
+/** A custom property's name, and no more. */
+const TOKEN_NAME = /^--[\w.-]{1,100}$/;
+/** Past this a value is not a token's, in characters. */
+const LONGEST_TOKEN_VALUE = 500;
+/** A block with this many custom properties is a system's root and not one component's variables. */
+const SYSTEM_BLOCK = 12;
+/** The steps of Tailwind's spacing scale that classes write, in units of its base. */
+const SPACING_STEPS = [
+    0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56,
+    60, 64, 72, 80, 96
+];
+/** Tailwind 3's font sizes, which its configuration file does not list unless it changes them. */
+const OLD_FONT_SIZES = {
+    xs: "0.75rem",
+    sm: "0.875rem",
+    base: "1rem",
+    lg: "1.125rem",
+    xl: "1.25rem",
+    "2xl": "1.5rem",
+    "3xl": "1.875rem",
+    "4xl": "2.25rem",
+    "5xl": "3rem",
+    "6xl": "3.75rem",
+    "7xl": "4.5rem",
+    "8xl": "6rem",
+    "9xl": "8rem"
+};
+/** Tailwind 3's radii. */
+const OLD_RADII = {
+    sm: "0.125rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem"
+};
+/** Plugins whose additions to the theme are not tokens worth saying they are unknown. */
+const KNOWN_PLUGIN = /typography|forms|animate|container-queries|aspect-ratio/;
+/** A path with forward slashes on every system, for an answer that travels. */
+const toPosix = (path) => path.replaceAll("\\", "/");
+/** Selectors holding enough custom properties to be a system's root, in a sheet. */
+const systemSelectors = ({ declarations }) => {
+    const counts = new Map();
+    for (const { place } of declarations) {
+        if (place.kind === "selector")
+            counts.set(place.selector, (counts.get(place.selector) ?? 0) + 1);
+    }
+    return new Set([...counts].flatMap(([selector, count]) => count >= SYSTEM_BLOCK && /^[.#[][\w-]+\]?$/.test(selector) ? [selector] : []));
+};
+/** The kind and theme of a declaration read from a sheet, when it makes a token at all. */
+const sheetToken = (place, system) => {
+    if (place.kind === "theme")
+        return { kind: "tailwind-theme", mode: undefined };
+    if (place.kind === "root")
+        return { kind: "css-variables", mode: undefined };
+    if (place.kind === "mode")
+        return { kind: "css-variables", mode: place.mode };
+    return place.kind === "selector" && system.has(place.selector)
+        ? { kind: "css-variables", mode: place.mode }
+        : undefined;
+};
+/**
+ * Whether a declaration is a token: not a framework's internals, a private variable or a way of clearing a namespace. A
+ * name is plain and a value short, since both reach an agent's context as its next step, and a file may be written by
+ * someone who wants that.
+ */
+const isTokenName = (name) => TOKEN_NAME.test(name) && !name.startsWith("--tw-") && !name.startsWith("--_");
+/** Whether a value is short enough to be a value. */
+const isTokenValue = (value) => value !== "initial" && value.length <= LONGEST_TOKEN_VALUE;
+/** The namespaces sheets clear (`--color-*: initial`), where Tailwind's defaults no longer apply. */
+const clearedNamespaces = (sheets) => sheets.flatMap(({ reading }) => reading.declarations.flatMap(({ name, value }) => value === "initial" && name.endsWith("*") ? [name.slice(0, -1)] : []));
+/** A sheet's declarations, in the shape tokens are made from. */
+const sheetDeclarations = (dir, { file, reading }) => {
+    const system = systemSelectors(reading);
+    const label = toPosix(relative(dir, file));
+    return reading.declarations.flatMap(({ name, value, line, place }) => {
+        const token = sheetToken(place, system);
+        if (token === undefined || !isTokenName(name) || !isTokenValue(value))
+            return [];
+        return [
+            {
+                name,
+                value,
+                mode: token.mode,
+                origin: { kind: token.kind, file: label, line },
+                ...(place.kind === "selector" ? { isScoped: true } : {})
+            }
+        ];
+    });
+};
+/** Tailwind 4's default theme as declarations, when a sheet brings it in and it is installed. */
+const themeDefaults = (sheets, cleared, unread) => {
+    const importing = sheets.find(({ reading }) => reading.importsTailwindTheme);
+    if (importing === undefined)
+        return [];
+    const file = packageFile(dirname(importing.file), "tailwindcss/theme.css");
+    const text = file === undefined ? undefined : smallFileText(file);
+    if (text === undefined) {
+        unread.push("Tailwind's default theme: tailwindcss is not installed here");
+        return [];
+    }
+    return readCssText(text).declarations.flatMap(({ name, value, line, place }) => place.kind === "theme" &&
+        isTokenName(name) &&
+        isTokenValue(value) &&
+        !cleared.some((prefix) => name.startsWith(prefix))
+        ? [{ name, value, mode: undefined, origin: { kind: "tailwind-default", file: "tailwindcss", line } }]
+        : []);
+};
+/** The spacing scale's steps as tokens: Tailwind makes them from one base, and classes write them. */
+const spacingScale = (base, origin, declared) => SPACING_STEPS.flatMap((step) => {
+    const name = `--spacing-${step}`;
+    return declared.has(name)
+        ? []
+        : [{ name, value: `calc(${base} * ${step})`, mode: undefined, origin, type: "dimension" }];
+});
+/** Tailwind's published palette, read as text from the installed package; none when it is not there. */
+const installedPalette = (dir) => {
+    const installed = packageFile(dir, "tailwindcss/lib/public/colors.js");
+    return installed === undefined ? undefined : readTailwindPalette(installed, smallFileText(installed) ?? "");
+};
+/** The colours a configuration takes from the palette by name: `brand: colors.blue` is a whole scale under `brand`. */
+const paletteAliased = (aliases, palette, origin) => aliases.flatMap(({ name, palette: wanted }) => palette.flatMap(({ name: named, value, type }) => {
+    const full = `--color-${wanted}`;
+    if (named !== full && !named.startsWith(`${full}-`))
+        return [];
+    return [{ name: `${name}${named.slice(full.length)}`, value, mode: undefined, type, origin }];
+}));
+/** Tailwind's default palette and scale as declarations, for a project on a configuration file (before version 4). */
+const configDefaults = (dir, configs, unread) => {
+    const replaced = new Set(configs.flatMap(({ reading }) => reading.replaced));
+    const palette = installedPalette(dir);
+    if (palette === undefined) {
+        unread.push("Tailwind's default palette: tailwindcss is not installed here");
+        return [];
+    }
+    const origin = { kind: "tailwind-default", file: "tailwindcss" };
+    const colors = replaced.has("colors")
+        ? []
+        : palette.map(({ name, value, type }) => ({ name, value, mode: undefined, type, origin }));
+    const scale = replaced.has("spacing") ? [] : spacingScale("0.25rem", origin, new Set());
+    const named = (prefix, values, key) => replaced.has(key)
+        ? []
+        : Object.entries(values).map(([name, value]) => ({
+            name: `${prefix}${name}`,
+            value,
+            mode: undefined,
+            type: "dimension",
+            origin
+        }));
+    return [
+        ...colors,
+        ...scale,
+        ...named("--text-", OLD_FONT_SIZES, "fontSize"),
+        ...named("--radius-", OLD_RADII, "borderRadius")
+    ];
+};
+/** A configuration's tokens as declarations. */
+const configDeclarations = (dir, { file, reading }) => {
+    const origin = { kind: "tailwind-config", file: toPosix(relative(dir, file)) };
+    return [
+        ...paletteAliased(reading.paletteAliases, installedPalette(dirname(file)) ?? [], origin),
+        ...reading.tokens.map(({ name, value, type }) => ({ name, value, mode: undefined, type, origin }))
+    ].filter(({ name, value }) => isTokenName(name) && isTokenValue(value));
+};
+/** The clashes between files: each theme compared with itself. */
+const clashesOf = (authors) => tokenClashes(authors.flatMap(({ label, declarations }) => [...new Set(declarations.map((each) => each.mode))].map((mode) => ({
+    mode,
+    raw: declarations
+        .filter((each) => each.mode === mode)
+        .map(({ name, value }) => ({ name, value, label, source: label }))
+}))));
+/** What the tokens came from, each file once with how many it gave. */
+const sourcesOf = (tokens) => {
+    const counts = new Map();
+    for (const { origin } of tokens) {
+        if (origin === undefined)
+            continue;
+        const key = `${origin.kind}\0${origin.file}`;
+        const known = counts.get(key);
+        counts.set(key, { kind: origin.kind, file: origin.file, tokens: (known?.tokens ?? 0) + 1 });
+    }
+    return [...counts.values()];
+};
+/** Tailwind's defaults for a project, whichever version it is on, and the spacing scale over its own declarations. */
+const defaultDeclarations = (dir, sheets, configs, own, unread) => {
+    const cleared = clearedNamespaces(sheets);
+    const hasTheme = sheets.some(({ reading }) => reading.importsTailwindTheme);
+    const isOnConfig = sheets.some(({ reading }) => reading.usesTailwindDirectives) || configs.length > 0;
+    if (!hasTheme) {
+        return isOnConfig ? configDefaults(dir, configs, unread) : [];
+    }
+    const defaults = themeDefaults(sheets, cleared, unread);
+    const base = [...defaults, ...own].findLast((each) => each.name === "--spacing" && each.mode === undefined);
+    const scale = base === undefined || cleared.includes("--spacing-")
+        ? []
+        : spacingScale(base.value, { kind: "tailwind-default", file: base.origin.file }, new Set(own.map((each) => each.name)));
+    return [...defaults, ...scale];
+};
+/**
+ * Reads what an application declares of its design system.
+ *
+ * @param folder - the catalogue's folder.
+ */
+export const readAppTokens = (folder) => {
+    // a sheet's path comes back with its links followed, and the labels are relative to this
+    const dir = realpathSync(folder);
+    const unread = [];
+    const shadcn = shadcnConfig(dir);
+    const sheets = readSheets(dir, shadcn, unread);
+    const configs = readConfigs(dir, shadcn, sheets, unread);
+    for (const { file, reading } of configs) {
+        unread.push(...reading.unread.map((each) => `${toPosix(relative(dir, file))}: ${each}`));
+    }
+    for (const plugin of new Set(sheets.flatMap(({ reading }) => reading.plugins))) {
+        if (!KNOWN_PLUGIN.test(plugin))
+            unread.push(`Tailwind plugin ${plugin}: what it adds to the theme is known only by running it`);
+    }
+    const authorOf = (file, declarations) => ({
+        label: toPosix(relative(dir, file)),
+        declarations
+    });
+    const fromSheets = sheets.map((sheet) => authorOf(sheet.file, sheetDeclarations(dir, sheet)));
+    const named = shadcn?.css === undefined ? undefined : toPosix(relative(dir, shadcn.css));
+    const authors = [
+        ...fromSheets.filter(({ label }) => label !== named),
+        ...configs.map((config) => authorOf(config.file, configDeclarations(dir, config))),
+        ...fromSheets.filter(({ label }) => label === named)
+    ];
+    const declared = authors.flatMap(({ declarations }) => declarations);
+    const onDocument = new Set(declared.filter((each) => each.isScoped !== true).map((each) => each.name));
+    const own = declared.filter((each) => each.isScoped !== true || !onDocument.has(each.name));
+    const lowest = defaultDeclarations(dir, sheets, configs, own, unread);
+    const wrappers = colorWrappers([...sheets, ...configs].map(({ text }) => text));
+    const declarations = [...lowest, ...own];
+    const tokens = resolvedTokens(declarations, wrappers);
+    const unresolved = unresolvedTokens(dir, { sheets, configs, declarations });
+    const isDefault = (token) => token.origin?.kind === "tailwind-default";
+    const ordered = [...tokens.filter((token) => !isDefault(token)), ...tokens.filter(isDefault)];
+    return {
+        tokens: ordered,
+        clashes: clashesOf(authors),
+        sources: [
+            ...(shadcn === undefined
+                ? []
+                : [{ kind: "components-json", file: toPosix(relative(dir, shadcn.file)), tokens: 0 }]),
+            ...sourcesOf(ordered)
+        ],
+        problems: unresolved.problems,
+        unread: [...unread, ...unresolved.unread],
+        files: [...sheets, ...configs].map(({ file }) => file).concat(shadcn === undefined ? [] : [shadcn.file])
+    };
+};

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

@@ -10,6 +10,11 @@
  * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
  * the loader answers the text, as the query's module's default did.
  *
+ * The packed texts of a group go in shared files, in the rows' order, up to `PACK_LIMIT` of JSON each, rather than a
+ * file each: gzip reads each file alone, and the docs of neighbouring components repeat their keys, their types and
+ * their wording, which a file of one text cannot share. On a library of small components a file each weighs ten times
+ * what the same texts weigh together, and a page that asks for one text fetches a few kilobytes more.
+ *
  * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
  * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
  * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
@@ -23,6 +28,11 @@ import { type IndexedStoryFile } from "./storyFilesModule.ts";
 import type { ComponentPageText, KeptCode, TextModuleContext } from "./textModules.ts";
 /** A story file's texts as their queries' modules answer them: its component's docs, its stories' code, its page. */
 export type FileTexts = readonly [docs: unknown, code: KeptCode, page: ComponentPageText];
+/**
+ * The JSON a packed file holds at most, in characters, unless one text alone is longer: enough for the docs of a few
+ * components to share their words, little enough that a page asking for one text fetches a few kilobytes.
+ */
+export declare const PACK_LIMIT: number;
 /**
  * The code of a group's texts module: the functions its loaders call, then, as its default, each file's loaders of its
  * docs, code and page, in the order of the group's rows.

package/dist/src/vite/builtTexts.js

@@ -10,6 +10,11 @@
  * whose stories are all args has no code, most components have no page) is written in the module itself. Either way
  * the loader answers the text, as the query's module's default did.
  *
+ * The packed texts of a group go in shared files, in the rows' order, up to `PACK_LIMIT` of JSON each, rather than a
+ * file each: gzip reads each file alone, and the docs of neighbouring components repeat their keys, their types and
+ * their wording, which a file of one text cannot share. On a library of small components a file each weighs ten times
+ * what the same texts weigh together, and a page that asks for one text fetches a few kilobytes more.
+ *
  * The texts are a module of their own (`TEXTS_PREFIX`), imported by the group's module alone, so the bundler keeps
  * them in its chunk. Reading them waits for every component's docs, seconds on a large library: written in the group's
  * module, they would hold back the stories it imports, and everything those import, until the last docs were read. As
@@ -25,37 +30,64 @@ import { indexedStoryFiles, storyFilesGroupOf, storyFilesGroupText } from "./sto
 import { VITE_PATHS } from "./vitePaths.js";
 /** The function that makes a packed file's loader, in the generated code. */
 const PACKED = "packedText";
+/** The function that makes the loader of one text of a packed file, in the generated code. */
+const PART = "packedPart";
+/** The loaders of the packed files, in the generated code, numbered. */
+const PACKED_FILE = "packedTexts";
 /** The function that makes the loader of a text written in the module, in the generated code. */
 const WRITTEN = "writtenText";
 /**
- * Writes texts as loaders: each in a gzipped file, or in the module when that weighs no more than the file and its
- * address (an empty page's JSON is shorter than its gzip header and the fetch it would cost). A text written in the
- * module is written once, however many files share it (most story files have no code and no page), and its loader
- * shared with them.
- *
- * @param emit - writes a packed file.
+ * The JSON a packed file holds at most, in characters, unless one text alone is longer: enough for the docs of a few
+ * components to share their words, little enough that a page asking for one text fetches a few kilobytes.
  */
-const textWriter = (emit) => {
-    const names = new Map();
-    const written = (json) => {
-        const name = names.get(json) ?? `${WRITTEN}${names.size}`;
-        names.set(json, name);
-        return name;
+export const PACK_LIMIT = 64 * 1024;
+/**
+ * Writes texts as loaders: each in a packed file shared with its neighbours, or in the module when it weighs no more
+ * than its loader there (an empty page, a story file with no code). A text is written once, however many files share
+ * it, and its loader shared with them.
+ */
+const textWriter = () => {
+    const written = new Map();
+    const packed = new Map();
+    const packs = [];
+    const pack = (json) => {
+        const known = packed.get(json);
+        if (known !== undefined)
+            return known;
+        let last = packs.at(-1);
+        if (last === undefined || (last.texts.length > 0 && last.length + json.length > PACK_LIMIT)) {
+            last = { texts: [], length: 0 };
+            packs.push(last);
+        }
+        const loader = `${PART}(${PACKED_FILE}${packs.length - 1},${last.texts.length})`;
+        last.texts.push(json);
+        last.length += json.length;
+        packed.set(json, loader);
+        return loader;
     };
     return {
         loaderOf: (value) => {
             const json = JSON.stringify(value);
-            const fileName = packedFileName(json);
-            const address = codeLiteral(fileName);
-            const packed = gzippedJson(json);
-            if (json.length <= address.length + packed.length)
-                return written(json);
-            emit({ type: "asset", fileName, source: packed });
-            return `${PACKED}(${address})`;
+            if (written.has(json) || json.length <= `${PART}(${PACKED_FILE}${packs.length},0)`.length) {
+                const name = written.get(json) ?? `${WRITTEN}${written.size}`;
+                written.set(json, name);
+                return name;
+            }
+            return pack(json);
         },
-        written: () => [...names].map(([json, name]) => `const ${name} = () => Promise.resolve(${codeOfJson(json)});`)
+        code: (emit) => [
+            ...[...written].map(([json, name]) => `const ${name} = () => Promise.resolve(${codeOfJson(json)});`),
+            ...packs.map((each, at) => {
+                const json = `[${each.texts.join(",")}]`;
+                const fileName = packedFileName(json);
+                emit({ type: "asset", fileName, source: gzippedJson(json) });
+                return `const ${PACKED_FILE}${at} = ${PACKED}(${codeLiteral(fileName)});`;
+            })
+        ]
     };
 };
+/** The code of the function that makes the loader of one text of a packed file: it answers the same value each time. */
+const PART_MAKER = `const ${PART} = (load, at) => () => load().then((texts) => texts[at]);`;
 /**
  * Every file's texts, read: a build reads them all once, as it would for their modules.
  *
@@ -73,10 +105,15 @@ const readTexts = (files, read) => Promise.all(files.map(({ file }) => Promise.a
  */
 export const textsModuleCode = (texts, emit) => {
     // written in the files' order once all are read, so the names in the module do not depend on which read ended first
-    const writer = textWriter(emit);
+    const writer = textWriter();
     // a text not read (the docs of a catalogue that reads none) has no loader, and its place stays in the row
     const rows = texts.map((each) => `[${each.map((text) => (text === undefined ? "null" : writer.loaderOf(text))).join(", ")}]`);
-    return [packedLoaderMaker(PACKED), ...writer.written(), `export default [${rows.join(",\n")}];`].join("\n");
+    return [
+        packedLoaderMaker(PACKED),
+        PART_MAKER,
+        ...writer.code(emit),
+        `export default [${rows.join(",\n")}];`
+    ].join("\n");
 };
 /**
  * A build's readers of the texts: the code and the pages as their queries answer them, read with the modules that

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

@@ -1,10 +1,12 @@
 import type { UserConfig } from "vite";
 import { type ResolvedConfig } from "./configFile.ts";
+import { type ScanFindings } from "./prebundled.ts";
 /**
  * What the plugin sets in Vite's configuration for a catalogue: its folder as the root, what to pre-bundle, the pages
  * as the build's inputs, and the dev server's reads kept to each origin.
  *
  * @param config - the catalogue's configuration.
  * @param userConfig - the configuration so far, whose own `server.cors` and build output the plugin leaves alone.
+ * @param findings - where the dependency scan's warnings and problems go.
  */
-export declare const catalogueConfig: (config: ResolvedConfig, userConfig: UserConfig) => UserConfig;
+export declare const catalogueConfig: (config: ResolvedConfig, userConfig: UserConfig, findings?: Omit<ScanFindings, "root">) => UserConfig;

package/dist/src/vite/catalogueConfig.js

@@ -7,7 +7,8 @@
 import { readFileSync } from "node:fs";
 import { packageResolver } from "./configFile.js";
 import { pageModulePath } from "./pages.js";
-import { prebundled, scannedEntries } from "./prebundled.js";
+import { prebundled, scannedEntries, scanOptions } from "./prebundled.js";
+import { refsDefine } from "./refsConfig.js";
 /**
  * A file's text, or none when it cannot be read.
  *
@@ -34,14 +35,25 @@ const hasOwnOutput = (userConfig) => userConfig.build?.rolldownOptions?.output !
  *
  * @param config - the catalogue's configuration.
  * @param userConfig - the configuration so far, whose own `server.cors` and build output the plugin leaves alone.
+ * @param findings - where the dependency scan's warnings and problems go.
  */
-export const catalogueConfig = (config, userConfig) => ({
+export const catalogueConfig = (config, userConfig, findings = {}) => ({
     root: config.dir,
+    // a hoisted workspace can keep a package's React in its folder while the adapter, at the root, reads another copy, and
+    // every component then fails with "invalid hook call": the catalogue's folder decides
+    resolve: { dedupe: ["react", "react-dom"] },
+    // a catalogue that composes no other has every part of composition removed from its shell (`shell/composition.ts`)
+    define: refsDefine(config.refs),
     // the pages are generated, so Vite's scanner cannot find what they import: it is named here, and the
     // story files (the project's and the sources') are scanned for what their components import
     optimizeDeps: {
         include: prebundled(config, packageResolver(config.dir)),
-        entries: scannedEntries(config, packageResolver(config.dir), readTextFile)
+        entries: scannedEntries(config, packageResolver(config.dir), readTextFile),
+        rolldownOptions: scanOptions({
+            root: config.dir,
+            isJsxInScripts: config.framework.compilesJsxInScripts === true,
+            ...findings
+        })
     },
     build: {
         rolldownOptions: {

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

@@ -0,0 +1,74 @@
+/**
+ * Which changed files a person sees, and which stories show them: what `verify` holds a change to.
+ *
+ * @remarks
+ * Pure. A UI file is a component or a style sheet, by its extension, and a story file; a plain script is one only when
+ * its text defines or draws a component, since most scripts are logic a change may touch freely, and a script a story
+ * reaches is checked by that story anyway. Tests, type declarations and what a tool wrote are not. A file reached through
+ * another component's stories counts as covered, and says so: a private part rarely has stories of its own, and they run
+ * it. A file only another catalogue of the repository can answer for is named and neither passes nor fails; any other
+ * file nothing reaches is this catalogue's to fail, or a component in a package beside it would pass unseen.
+ *
+ * @module
+ */
+import type { ChangedUiFile } from "./agent.types.ts";
+import type { ReachedStory } from "./storyReach.ts";
+/**
+ * Whether a changed file is one a person sees.
+ *
+ * @param file - the file, relative to the repository.
+ * @param readText - its text; a plain script's is read to tell whether it defines a component.
+ */
+export declare const isUiFile: (file: string, readText: (file: string) => string) => boolean;
+/** A story with its id, as the catalogue lists it. */
+export type IdentifiedStory = {
+    /** Its id. */
+    readonly id: string;
+    /** What it reaches. */
+    readonly reach: ReachedStory;
+};
+/**
+ * The forms a deleted file can have left in the graph: what still imports it wrote it with no extension, or by its
+ * folder.
+ *
+ * @param file - the deleted file, absolute.
+ */
+export declare const deletedForms: (file: string) => readonly string[];
+/** What `changedUiFiles` reads. */
+export type UiFilesInput = {
+    /** The files that changed, with their forms in the graph, relative to the repository and to the catalogue. */
+    readonly files: readonly {
+        readonly file: string;
+        readonly path: string;
+        readonly absolute: string;
+        readonly isDeleted: boolean;
+    }[];
+    /** The catalogue's stories. */
+    readonly stories: readonly IdentifiedStory[];
+    /** The files every story shows. */
+    readonly everyStoryFiles: ReadonlySet<string>;
+    /** Whether a file, in the graph's form, belongs to another catalogue of the repository. */
+    readonly isOtherCatalogues: (absolute: string) => boolean;
+    /** Reads a file by its path relative to the repository. */
+    readonly readText: (file: string) => string;
+};
+/**
+ * The changed files a person sees: those this catalogue can show, with their stories, and those it cannot speak for. A
+ * deleted file with no story behind it is left out, as there is nothing left to look at, and so is what every story shows
+ * while the catalogue has no story.
+ *
+ * @param input - the change and the catalogue.
+ */
+export declare const changedUiFiles: ({ files, stories, everyStoryFiles, isOtherCatalogues, readText }: UiFilesInput) => {
+    readonly uiFiles: readonly ChangedUiFile[];
+    readonly outside: readonly string[];
+};
+/**
+ * Whether the nearest catalogue above a file is another one.
+ *
+ * @param file - the file, absolute, under the catalogue's root as named.
+ * @param own - this catalogue's folder.
+ * @param root - the repository's folder, in the same form: nothing above it is looked at.
+ * @param hasCatalogue - whether a folder holds a catalogue's configuration.
+ */
+export declare const belongsToOtherCatalogue: (file: string, own: string, root: string, hasCatalogue: (folder: string) => boolean) => boolean;

package/dist/src/vite/changeCoverage.js

@@ -0,0 +1,120 @@
+import { CHECKED_FILE } from "./checkCode.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A story file, in any framework's extension; a snapshot of one is not. */
+const STORY_FILE = /\.stories\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/;
+/** A test's file or helper, wherever it sits. */
+const TEST_FILE = /(?:\.test\.|\.spec\.|\.e2e\.|\.cy\.|_test\.|(?:^|\/)(?:__tests__|__mocks__|__snapshots__|e2e|cypress)\/|(?:^|\/)test-?utils\.)/;
+/** A folder of tests; under `src` a folder of that name is as likely a feature. */
+const TESTS_FOLDER = /(?:^|\/)tests?\//;
+/** What is under `src`. */
+const UNDER_SRC = /(?:^|\/)src\//;
+/** What is written by a tool, or only types: nobody sees it change. */
+const NOT_SEEN = /(?:\.d\.[cm]?ts$|\.min\.|(?:^|\/)(?:dist|generated|node_modules)\/)/;
+/** Components and sheets `check-code` does not read for values, and an Angular component's files. */
+const OTHER_UI_FILE = /(?:\.component\.(?:ts|html)|\.(?:css|styles?)\.[cm]?[jt]s|\.(?:pcss|postcss|styl))$/;
+/** A plain script. */
+const SCRIPT_FILE = /\.[cm]?[jt]s$/;
+/** A script's text that defines a component: a custom element, an Angular component, a Vue one, a tagged template. */
+const DEFINES_COMPONENT = /\bcustomElements\.define\(|@customElement\(|\bextends\s+(?:LitElement|HTMLElement)\b|@Component\(|\bdefineComponent\(|(?<![\w./-])html`/;
+/** A JavaScript file, which may hold JSX with no extension to say so; TypeScript cannot without `.tsx`. */
+const PLAIN_JAVASCRIPT = /\.[cm]?js$/;
+/** JSX in a file's text: a closing tag, or a component closed on itself. */
+const DRAWS_JSX = /<\/[A-Za-z][\w.-]{0,80}>|<[A-Z][\w.]{0,80}[^<>\n]{0,500}\/>/;
+/**
+ * Whether a changed file is one a person sees.
+ *
+ * @param file - the file, relative to the repository.
+ * @param readText - its text; a plain script's is read to tell whether it defines a component.
+ */
+export const isUiFile = (file, readText) => {
+    if (TEST_FILE.test(file) || NOT_SEEN.test(file))
+        return false;
+    if (TESTS_FOLDER.test(file) && !UNDER_SRC.test(file))
+        return false;
+    if (STORY_FILE.test(file) || CHECKED_FILE.test(file) || OTHER_UI_FILE.test(file))
+        return true;
+    if (!SCRIPT_FILE.test(file))
+        return false;
+    const text = readText(file);
+    return DEFINES_COMPONENT.test(text) || (PLAIN_JAVASCRIPT.test(file) && DRAWS_JSX.test(text));
+};
+/**
+ * The forms a deleted file can have left in the graph: what still imports it wrote it with no extension, or by its
+ * folder.
+ *
+ * @param file - the deleted file, absolute.
+ */
+export const deletedForms = (file) => {
+    const bare = file.replace(/\.[^./]+$/, "");
+    return [file, bare, ...(bare.endsWith("/index") ? [bare.slice(0, -"/index".length)] : [])];
+};
+/**
+ * How a changed file is covered.
+ *
+ * @param forms - the file's forms in the graph.
+ * @param stories - the catalogue's stories.
+ * @param everyStory - whether every story shows it: the catalogue's preview and its sheets.
+ */
+const coverageOf = (forms, stories, everyStory) => {
+    const reaching = everyStory
+        ? stories
+        : stories.filter(({ reach }) => forms.some((form) => reach.files.includes(form)));
+    // what every story shows is none's own, though a story may name it
+    const isOwn = !everyStory && reaching.some(({ reach }) => forms.some((form) => reach.own.includes(form)));
+    const covering = isOwn ? "own" : "through";
+    return { coverage: reaching.length === 0 ? "none" : covering, stories: reaching.map(({ id }) => id) };
+};
+/**
+ * The changed files a story can show: what every story shows is none of them while the catalogue has no story, as a
+ * catalogue just set up has its preview and nothing yet that shows it.
+ *
+ * @param files - the changed files.
+ * @param stories - the catalogue's stories.
+ * @param everyStoryFiles - the files every story shows.
+ */
+const shownFiles = (files, stories, everyStoryFiles) => stories.length > 0 ? files : files.filter(({ absolute }) => !everyStoryFiles.has(absolute));
+/**
+ * The changed files a person sees: those this catalogue can show, with their stories, and those it cannot speak for. A
+ * deleted file with no story behind it is left out, as there is nothing left to look at, and so is what every story shows
+ * while the catalogue has no story.
+ *
+ * @param input - the change and the catalogue.
+ */
+export const changedUiFiles = ({ files, stories, everyStoryFiles, isOtherCatalogues, readText }) => {
+    const uiFiles = [];
+    const outside = [];
+    for (const { file, path, absolute, isDeleted } of shownFiles(files, stories, everyStoryFiles)) {
+        if (!isUiFile(file, isDeleted ? () => "" : readText))
+            continue;
+        const forms = isDeleted ? deletedForms(absolute) : [absolute];
+        const found = coverageOf(forms, stories, everyStoryFiles.has(absolute));
+        if (found.coverage === "none" && isDeleted)
+            continue;
+        if (found.coverage === "none" && isOtherCatalogues(absolute))
+            outside.push(file);
+        else
+            uiFiles.push({ file, path, ...found });
+    }
+    return { uiFiles, outside };
+};
+/**
+ * Whether the nearest catalogue above a file is another one.
+ *
+ * @param file - the file, absolute, under the catalogue's root as named.
+ * @param own - this catalogue's folder.
+ * @param root - the repository's folder, in the same form: nothing above it is looked at.
+ * @param hasCatalogue - whether a folder holds a catalogue's configuration.
+ */
+export const belongsToOtherCatalogue = (file, own, root, hasCatalogue) => {
+    let folder = VITE_PATHS.dirname(file);
+    while (folder === root || folder.startsWith(`${root}/`)) {
+        if (folder === own)
+            return false;
+        if (hasCatalogue(folder))
+            return true;
+        if (folder === root)
+            return false;
+        folder = VITE_PATHS.dirname(folder);
+    }
+    return false;
+};