forgebook 0.3.3 → 0.4.1

package/dist/src/vite/catalogueConfig.js

@@ -1,13 +1,15 @@
 /**
  * What Forgebook's 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, the build's script names, and the dev server's reads kept to each origin.
+ * pages as the build's inputs, the build's script names, no single-page fallback, and the dev server's reads kept to
+ * each origin.
  *
  * @module
  */
 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 +36,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: {
@@ -56,6 +69,10 @@ export const catalogueConfig = (config, userConfig) => ({
                 : { output: { chunkFileNames: "assets/[hash].js", hashCharacters: "base36" } })
         }
     },
+    // the plugin serves the catalogue's pages itself, so the only page a single-page fallback could answer with is the
+    // app's own `index.html`: a story's missing image would get it, and the server would load the whole app its scripts
+    // reach, pre-bundle again what the stories never import, and reload every frame open (unless the app chose its own)
+    ...(userConfig.appType === undefined ? { appType: "mpa" } : {}),
     // Vite lets any localhost page read the server: neither origin needs another's reads, and the guards
     // would be the only wall left between the frames and the catalogue (unless the app chose its own)
     ...(config.frames.kind === "isolated" && userConfig.server?.cors === undefined

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;
+};

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.