forgebook 0.3.3 → 0.4.0

package/dist/src/vite/checkoutWatch.js

@@ -0,0 +1,287 @@
+/**
+ * The files a checkout rewrote, told to the dev server's watcher: `git switch`, `git reset --hard`, a pull or a rebase
+ * moves the repository to another commit and rewrites its files at once, and the system's file events for such a burst
+ * may come many seconds late, or never.
+ *
+ * @remarks
+ * Vite's watcher on macOS reads FSEvents, which a busy machine delivers late and coalesces; a branch switch writes,
+ * removes and adds files within milliseconds, and its events can be lost outright. Missed, a story removed by the switch
+ * stays in the sidebar, one it added never shows, a story file's old module keeps being served, and nothing ever renews
+ * them: every later answer comes from the stale module. A watch of git's own `HEAD` and `index` files, each on its own
+ * (a kernel event, kqueue on macOS), hears every checkout at once; the commit `HEAD` names before and after says which
+ * files changed, and each that the checkout wrote is handed to Vite's watcher as its own event, so every path a real
+ * event takes (the lists, the modules, the pages' reload) runs as it would have.
+ *
+ * The moves come from git's reflog of `HEAD`, read from where the last check stopped: a switch and a switch back that
+ * land between two checks leave `HEAD` where it was, yet rewrote files, and a page that loaded in between holds the
+ * other branch's stories. Each move's files are handed on, the later move standing for a file both wrote. With no
+ * reflog, the commit seen last is compared with the one now.
+ *
+ * Only files the checkout wrote are handed on: one git lists that is untouched on disk since the last checkout seen (a
+ * commit, which changes `HEAD` and rewrites nothing) is not, nor a file it says was removed that is still there. A
+ * checkout that keeps `HEAD` where it was (`git checkout -- <file>`, `git stash`) changes no commit and is left to the
+ * system's events. Where the watcher hears of changes at once or polls, there is nothing to make up for.
+ *
+ * @module
+ */
+import { execFile } from "node:child_process";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { isWatchingByFileEvents, nodeWatchFile } from "./closeWatch.js";
+import { VITE_PATHS } from "./vitePaths.js";
+const run = promisify(execFile);
+/**
+ * How long before the last checkout seen a file's change still counts as this checkout's, in milliseconds: a file
+ * system writes times with its own clock and grain, so a file written by the checkout may carry a time a little early.
+ */
+const CHECKOUT_MARGIN_MS = 2_000;
+/** How long the watch waits for git to finish writing before it reads `HEAD`, in milliseconds. */
+const SETTLE_MS = 100;
+/** How long after a file's watch is opened it is checked to still hold the file, in milliseconds. */
+const REWATCH_MS = 50;
+/** Which file a path names now: its device and inode; none when nothing is there. */
+const identityOf = (file) => {
+    const stats = statSync(file, { throwIfNoEntry: false });
+    return stats === undefined ? undefined : `${stats.dev}:${stats.ino}`;
+};
+/** A dependency's file, which Vite's watcher ignores. */
+const DEPENDENCY = /(?:^|\/)node_modules\//;
+/** A file's status from the disk. */
+const diskStatus = (file) => {
+    const stats = statSync(file, { throwIfNoEntry: false });
+    return stats === undefined ? undefined : { changedAt: stats.ctimeMs };
+};
+/**
+ * The events a checkout's files make: what `git diff --name-status -z --no-renames` lists between two commits, kept to
+ * the files the checkout wrote.
+ *
+ * @param listed - git's output.
+ * @param top - the repository's folder, which git's paths are relative to.
+ * @param since - when the commit before was seen, in milliseconds: a file unchanged since is not the checkout's.
+ * @param status - a file's status now; the disk's by default.
+ */
+export const checkoutEvents = (listed, top, since, status = diskStatus) => {
+    const parts = listed.split("\0");
+    const events = [];
+    for (let at = 0; at + 1 < parts.length; at += 2) {
+        const [letter = "", path = ""] = [parts[at], parts[at + 1]];
+        if (path === "" || DEPENDENCY.test(path))
+            continue;
+        const file = VITE_PATHS.normalize(join(top, path));
+        const now = status(file);
+        if (letter.startsWith("D")) {
+            if (now === undefined)
+                events.push({ kind: "unlink", file });
+            continue;
+        }
+        if (now === undefined || now.changedAt < since - CHECKOUT_MARGIN_MS)
+            continue;
+        events.push({ kind: letter.startsWith("A") ? "add" : "change", file });
+    }
+    return events;
+};
+/** A reflog line's two commits, before the name and the message: 40 or 64 hexadecimal digits each. */
+const REFLOG_LINE = /^([0-9a-f]{40}(?:[0-9a-f]{24})?) ([0-9a-f]{40}(?:[0-9a-f]{24})?) /;
+/**
+ * The moves of `HEAD` in what git appended to its reflog, in order, each that changed the commit: a branch switched and
+ * switched back before a check reads `HEAD` is two moves, though `HEAD` ends where it was.
+ *
+ * @param appended - the reflog's lines written since the last check.
+ */
+export const headMoves = (appended) => appended.split("\n").flatMap((line) => {
+    const [, from = "", to = ""] = REFLOG_LINE.exec(line) ?? [];
+    return from === "" || from === to || /^0+$/.test(from) ? [] : [{ from, to }];
+});
+/** What a reflog holds past a point, and where it ends; none when it cannot be read or was rewritten shorter. */
+const reflogFrom = (file, offset) => {
+    const size = statSync(file, { throwIfNoEntry: false })?.size;
+    if (size === undefined || size < offset)
+        return undefined;
+    const buffer = Buffer.alloc(size - offset);
+    const handle = openSync(file, "r");
+    try {
+        readSync(handle, buffer, 0, buffer.length, offset);
+    }
+    finally {
+        closeSync(handle);
+    }
+    // a line git is still writing is read at the next check
+    const text = buffer.toString("utf8");
+    const complete = text.lastIndexOf("\n") + 1;
+    return { text: text.slice(0, complete), end: offset + Buffer.byteLength(text.slice(0, complete)) };
+};
+/** Git, as installed, with no option of the user's that changes how it lists. */
+const runGit = async (dir, args) => {
+    try {
+        const { stdout } = await run("git", ["-c", "core.quotePath=false", ...args], {
+            cwd: dir,
+            maxBuffer: 64 * 1024 * 1024
+        });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Watches a repository's checkouts and hands the files each one wrote to `onEvent`.
+ *
+ * @param options - the repository, where events go, and how files are watched and git is run.
+ */
+export const checkoutWatch = (options) => {
+    const watchFile = options.watchFile ?? nodeWatchFile;
+    const git = options.git ?? runGit;
+    const settleMs = options.settleMs ?? SETTLE_MS;
+    const watches = new Map();
+    let isClosed = false;
+    let head;
+    let since = Date.now();
+    let top = "";
+    // the reflog of `HEAD`, and how far it was read
+    let reflog = "";
+    let reflogEnd = 0;
+    let timer;
+    // one check at a time, in order: two checkouts in a row are compared each with the one before
+    let checking = Promise.resolve();
+    /**
+     * The moves since the last check: from the reflog of `HEAD`, which records a switch and a switch back that leave
+     * `HEAD` where it was; else the one move from the commit seen last to the one now.
+     */
+    const movesTo = (now) => {
+        const appended = reflog === "" ? undefined : reflogFrom(reflog, reflogEnd);
+        if (appended !== undefined) {
+            reflogEnd = appended.end;
+            const moves = headMoves(appended.text);
+            if (moves.length > 0 && moves.at(-1)?.to === now)
+                return moves;
+        }
+        return head === undefined || head === now ? [] : [{ from: head, to: now }];
+    };
+    /** Each move's files, the later standing: a file written by two moves is told once, as the disk has it now. */
+    const movesEvents = async (moves) => {
+        const events = new Map();
+        for (const { from, to } of moves) {
+            const listed = await git(options.dir, [
+                "diff",
+                "--name-status",
+                "-z",
+                "--no-renames",
+                "--no-ext-diff",
+                from,
+                to
+            ]);
+            for (const event of checkoutEvents(listed ?? "", top, since, options.status))
+                events.set(event.file, event);
+        }
+        return [...events.values()];
+    };
+    const check = async () => {
+        const seenAt = Date.now();
+        const now = await git(options.dir, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+        if (isClosed || now === undefined)
+            return;
+        const moves = head === undefined ? [] : movesTo(now);
+        head = now;
+        const events = await movesEvents(moves);
+        if (!isClosed)
+            for (const event of events)
+                options.onEvent(event);
+        since = seenAt;
+    };
+    const schedule = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            checking = checking.then(check);
+        }, settleMs);
+    };
+    const follow = (file) => {
+        if (isClosed)
+            return;
+        watches.get(file)?.close();
+        watches.delete(file);
+        const watched = identityOf(file);
+        try {
+            watches.set(file, watchFile(file, (kind) => {
+                // git replaces the file through a new one, which the old watch never hears of
+                if (kind !== "change")
+                    setTimeout(() => follow(file), 0);
+                schedule();
+            }));
+        }
+        catch {
+            // not there yet (a repository with no commit has no index): the next event of the other file looks again
+            return;
+        }
+        // a watch is taken by the system on the loop's next turn, and hears nothing of a file replaced before that: then
+        // the file it holds is gone for good, so it is opened again and the checkout that replaced it is looked for
+        setTimeout(() => {
+            if (isClosed || identityOf(file) === watched)
+                return;
+            follow(file);
+            schedule();
+        }, REWATCH_MS);
+    };
+    const ready = (async () => {
+        const gitDir = await git(options.dir, ["rev-parse", "--absolute-git-dir"]);
+        const shown = await git(options.dir, ["rev-parse", "--show-toplevel"]);
+        if (gitDir === undefined || shown === undefined || isClosed)
+            return;
+        top = shown;
+        head = await git(options.dir, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+        reflog = join(gitDir, "logs", "HEAD");
+        reflogEnd = statSync(reflog, { throwIfNoEntry: false })?.size ?? 0;
+        since = Date.now();
+        // `HEAD` moves with a switch; the index is rewritten by every checkout, a reset of the branch included
+        for (const name of ["HEAD", "index"])
+            follow(join(gitDir, name));
+    })();
+    return {
+        ready,
+        settled: async () => {
+            await ready;
+            await new Promise((resolve) => setTimeout(resolve, settleMs * 2));
+            await checking;
+        },
+        close: () => {
+            isClosed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            for (const watch of watches.values())
+                watch.close();
+            watches.clear();
+        }
+    };
+};
+/**
+ * A dev server's checkout watch, where its watcher reads FSEvents and it sends updates: what a checkout wrote goes to
+ * its watcher. Closed with the server's HTTP server.
+ *
+ * @param server - the dev server.
+ * @param platform - the system, `process.platform` by default.
+ * @returns the watch; none where the watcher hears of changes at once, or polls.
+ */
+export const serverCheckoutWatch = (server, platform = process.platform) => {
+    const { watch, hmr } = server.config.server;
+    if (!isWatchingByFileEvents(watch, platform) || hmr === false)
+        return undefined;
+    const watching = checkoutWatch({
+        dir: server.config.root,
+        onEvent: ({ kind, file }) => void server.watcher.emit(kind, file)
+    });
+    server.httpServer?.on("close", () => watching.close());
+    return watching;
+};
+/** The checkout watch of the dev server that runs now; none watches until a server is served. */
+export const currentCheckoutWatch = () => {
+    let current;
+    return {
+        serve: (server, platform = process.platform) => {
+            current?.close();
+            current = server === undefined ? undefined : serverCheckoutWatch(server, platform);
+        },
+        close: () => current?.close()
+    };
+};

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

@@ -55,6 +55,14 @@ export type CloseWatchOptions = {
      */
     readonly readText?: (file: string) => string | undefined;
 };
+/**
+ * Node's watch of one file: a kernel event per change (kqueue on macOS). Not persistent, so it never keeps a process
+ * that is ending alive.
+ *
+ * @param file - the file.
+ * @param onEvent - the watch's events.
+ */
+export declare const nodeWatchFile: WatchFile;
 /**
  * Whether a dev server's watcher hears of changes through FSEvents, which deliver them late: Vite's on macOS, unless
  * it polls, was told not to use them, or waits for writes to finish; none when the dev server watches nothing.

package/dist/src/vite/closeWatch.js

@@ -37,7 +37,7 @@ export const CLOSE_WATCH_LIMIT = 64;
  * @param file - the file.
  * @param onEvent - the watch's events.
  */
-const nodeWatchFile = (file, onEvent) => {
+export const nodeWatchFile = (file, onEvent) => {
     const watcher = watch(file, { persistent: false }, (kind) => onEvent(kind === "rename" ? "rename" : "change"));
     watcher.on("error", () => onEvent("error"));
     return { close: () => watcher.close() };

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

@@ -0,0 +1,8 @@
+import { type ScannedComponent } from "./componentScan.ts";
+/**
+ * Every component of a project as its files are now.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export declare const currentComponents: (dir: string, notes: string[]) => ScannedComponent[];

package/dist/src/vite/componentCache.js

@@ -0,0 +1,66 @@
+/**
+ * A project's components, read from disk and kept by each file's size and time, so a running dev server that is asked again
+ * reads only what changed.
+ *
+ * @remarks
+ * Every `check-code` reads the whole repository, and a long-lived server is asked often. Only components are kept, not
+ * files' text, since a repository's text is more than a server should hold.
+ *
+ * @module
+ */
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { repositoryOf, smallFileText } from "./appTokenFiles.js";
+import { LEFT_ALONE } from "./checkCode.js";
+import { rulesOfFile } from "./componentRules.js";
+import { COMPONENT_FILE, projectComponents } from "./componentScan.js";
+import { listedProjectFiles, MOST_BYTES } from "./projectFiles.js";
+import { isInside } from "./sourceTokens.js";
+/** What has been read, by absolute path. */
+const KEPT = new Map();
+/**
+ * A file's components with what a rules file beside it says of them, by the file's name or the component's (`radio-group.tsx`
+ * may have `RadioGroup.rules.json`). Read each time: it is short and rare.
+ */
+const withRulesBeside = (components, path, root) => components.map((each) => {
+    const names = [path.replace(/\.[^./\\]+$/, ""), join(dirname(path), each.name)];
+    const own = names
+        .map((name) => `${name}.rules.json`)
+        // a link beside a component may lead anywhere
+        .flatMap((name) => (isInside(root, name) ? (smallFileText(name) ?? []) : []))
+        .map((text) => rulesOfFile(text).get(each.name))
+        .find((rules) => rules !== undefined);
+    return own === undefined ? each : { ...each, rules: { ...each.rules, ...own } };
+});
+/**
+ * Every component of a project as its files are now.
+ *
+ * @param dir - its folder.
+ * @param notes - told of what is left out.
+ */
+export const currentComponents = (dir, notes) => {
+    let bytes = 0;
+    const root = repositoryOf(dir);
+    return listedProjectFiles(dir, notes)
+        .filter((file) => COMPONENT_FILE.test(file) && !LEFT_ALONE.test(file))
+        .flatMap((file) => {
+        const path = join(dir, file);
+        try {
+            const { size, mtimeMs } = statSync(path);
+            const stamp = `${size}:${mtimeMs}`;
+            const known = KEPT.get(path);
+            if (known?.stamp === stamp)
+                return withRulesBeside(known.components, path, root);
+            if (bytes > MOST_BYTES)
+                return [];
+            bytes += size;
+            const text = smallFileText(path);
+            const components = text === undefined ? [] : projectComponents([{ file, text }]);
+            KEPT.set(path, { stamp, components });
+            return withRulesBeside(components, path, root);
+        }
+        catch {
+            return [];
+        }
+    });
+};

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

@@ -0,0 +1,71 @@
+/**
+ * A map of a project's components and tokens, for an agent to read instead of everything: what exists, what each is for,
+ * what renders what and which tokens each file uses.
+ *
+ * @remarks
+ * Generated from the source, so it cannot drift from it, and small on purpose: a list of names first, and a component's
+ * neighbourhood or an intent's choices on request. A store of decisions written apart would be a second source of truth.
+ *
+ * @module
+ */
+import type { UsageGuidance } from "../componentDocs.ts";
+import type { ComponentIntent, ComponentRules } from "./componentRules.ts";
+/** A component in the map. */
+export type GraphComponent = {
+    /** Its name. */
+    readonly name: string;
+    /** Where it is, `file:line`. */
+    readonly at: string;
+    /** When to use it and when not. */
+    readonly guidance?: UsageGuidance;
+    /** How it is chosen and how it fits. */
+    readonly rules?: ComponentRules;
+    /** The project's components it renders. */
+    readonly renders: readonly string[];
+    /** How many of the project's components render it. */
+    readonly usedBy: number;
+};
+/** A component in detail, with those around it. */
+export type GraphDetail = GraphComponent & {
+    /** The components that render it. */
+    readonly renderedBy: readonly string[];
+    /** The tokens its file uses. */
+    readonly tokens: readonly string[];
+    /** Where else a component of this name is: `usedBy` counts them together. */
+    readonly alsoAt: readonly string[];
+};
+/** The map. */
+export type GraphDocument = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** How many components there are, whatever the answer lists. */
+    readonly total: number;
+    /** The components, those with something to say first. */
+    readonly components: readonly GraphComponent[];
+    /** The choices for each situation, by what it is called. */
+    readonly intents: Readonly<Record<string, readonly (ComponentIntent & {
+        readonly component: string;
+    })[]>>;
+    /** The tokens known, by type, and how many of each. */
+    readonly tokens: Readonly<Record<string, number>>;
+    /** The one asked about, in detail. */
+    readonly detail?: GraphDetail;
+    /** What could not be read. */
+    readonly notes: readonly string[];
+};
+/** What is asked of the map. */
+export type GraphQuestion = {
+    /** A component to give in detail. */
+    readonly component?: string | undefined;
+    /** An intent to list only the choices of. */
+    readonly intent?: string | undefined;
+    /** How many components to list. */
+    readonly limit?: number | undefined;
+};
+/**
+ * The map of a project.
+ *
+ * @param dir - its folder.
+ * @param question - what is asked.
+ */
+export declare const graphDocument: (dir: string, question: GraphQuestion) => GraphDocument;

package/dist/src/vite/componentGraph.js

@@ -0,0 +1,133 @@
+/**
+ * A map of a project's components and tokens, for an agent to read instead of everything: what exists, what each is for,
+ * what renders what and which tokens each file uses.
+ *
+ * @remarks
+ * Generated from the source, so it cannot drift from it, and small on purpose: a list of names first, and a component's
+ * neighbourhood or an intent's choices on request. A store of decisions written apart would be a second source of truth.
+ *
+ * @module
+ */
+import { join } from "node:path";
+import { COLOR_CLASS, FONT_CLASS, RADIUS_CLASS, SPACE_CLASS } from "./appAudit.js";
+import { smallFileText } from "./appTokenFiles.js";
+import { readAppTokens } from "./appTokens.js";
+import { currentComponents } from "./componentCache.js";
+import { plainWords } from "./sourceText.js";
+/** How many components a map lists unless asked otherwise: an agent degrades on long answers. */
+const LIMIT = 100;
+/** How much of what an author wrote the map repeats, for each thing. */
+const LONGEST_WORDS = 200;
+/** How many things of a kind (situations, choices) the map gives. */
+const MOST_WORDS = 20;
+/** A custom property a file uses. */
+const VAR_USE = /var\(\s*(--[\w-]+)/g;
+/** What an author wrote, as data and short. */
+const plainGuidance = (guidance) => {
+    const plain = (text) => plainWords(text, LONGEST_WORDS);
+    const list = (texts) => texts?.slice(0, MOST_WORDS).map(plain);
+    const { useWhen, avoidWhen, alternatives, deprecated, replacedBy } = guidance;
+    const [when, avoid, others] = [list(useWhen), list(avoidWhen), list(alternatives)];
+    return {
+        ...(when === undefined ? {} : { useWhen: when }),
+        ...(avoid === undefined ? {} : { avoidWhen: avoid }),
+        ...(others === undefined ? {} : { alternatives: others }),
+        ...(deprecated === undefined ? {} : { deprecated: plain(deprecated) }),
+        ...(replacedBy === undefined ? {} : { replacedBy: plain(replacedBy) })
+    };
+};
+/** A component in the map's short form. */
+const shortForm = (each, usedBy, known) => ({
+    name: each.name,
+    at: plainWords(`${each.file}:${each.line}`, LONGEST_WORDS),
+    ...(each.guidance === undefined ? {} : { guidance: plainGuidance(each.guidance) }),
+    ...(each.rules === undefined ? {} : { rules: each.rules }),
+    renders: each.renders.filter((name) => known.has(name) && name !== each.name),
+    usedBy: usedBy.get(each.name)?.length ?? 0
+});
+/** The tokens a component's file uses: by reference, and by the classes that write them. */
+const tokensOfFile = (text, tokens) => {
+    const names = new Set(tokens.map(({ name }) => name));
+    const colors = new Map(tokens.flatMap(({ utility, name, type }) => utility !== undefined && type === "color" ? [[utility, name]] : []));
+    const used = [...text.matchAll(VAR_USE)].flatMap((match) => match[1] ?? []);
+    const classed = [
+        ...[...text.matchAll(COLOR_CLASS)].flatMap((match) => colors.get(match[1] ?? "") ?? []),
+        ...[...text.matchAll(SPACE_CLASS)].map((match) => `--spacing-${match[1] ?? ""}`),
+        ...[...text.matchAll(RADIUS_CLASS)].map((match) => `--radius-${match[1] ?? ""}`),
+        ...[...text.matchAll(FONT_CLASS)].map((match) => `--text-${match[1] ?? ""}`)
+    ];
+    return [...new Set([...used, ...classed])].filter((name) => names.has(name)).toSorted();
+};
+/** Which components render each, by name. */
+const usersOf = (components, known) => {
+    const users = new Map();
+    for (const each of components) {
+        for (const name of each.renders) {
+            if (known.has(name) && name !== each.name)
+                users.set(name, [...(users.get(name) ?? []), each.name]);
+        }
+    }
+    return users;
+};
+/** The choices for each situation, by what it is called; a Map, since an author may call one `constructor`. */
+const intentsOf = (components) => {
+    const intents = new Map();
+    for (const each of components) {
+        for (const intent of each.rules?.intents ?? []) {
+            intents.set(intent.id, [...(intents.get(intent.id) ?? []), { ...intent, component: each.name }]);
+        }
+    }
+    return intents;
+};
+/** How many tokens of each type. */
+const countsOf = (tokens) => {
+    const types = {};
+    for (const { type } of tokens)
+        types[type] = (types[type] ?? 0) + 1;
+    return types;
+};
+/**
+ * The map of a project.
+ *
+ * @param dir - its folder.
+ * @param question - what is asked.
+ */
+export const graphDocument = (dir, question) => {
+    const notes = [];
+    const everything = currentComponents(dir, notes);
+    const components = everything.filter((each) => each.isExported);
+    const { tokens, unread } = readAppTokens(dir);
+    const known = new Set(components.map(({ name }) => name));
+    const usedBy = usersOf(everything, known);
+    const intents = intentsOf(components);
+    const uses = (name) => usedBy.get(name)?.length ?? 0;
+    const isSilent = (each) => Number(each.rules === undefined && each.guidance === undefined);
+    const choices = new Set((intents.get(question.intent ?? "") ?? []).map(({ component }) => component));
+    const listed = (question.intent === undefined ? components : components.filter((each) => choices.has(each.name)))
+        .toSorted((first, second) => isSilent(first) - isSilent(second) || uses(second.name) - uses(first.name))
+        .slice(0, question.limit ?? LIMIT)
+        .map((each) => shortForm(each, usedBy, known));
+    const asked = components.find((each) => each.name === question.component);
+    return {
+        schema: 1,
+        total: components.length,
+        components: listed,
+        intents: Object.fromEntries((question.intent === undefined
+            ? [...intents].slice(0, question.limit ?? LIMIT)
+            : [[question.intent, intents.get(question.intent) ?? []]]).map(([id, list]) => [id, list.slice(0, question.limit ?? LIMIT)])),
+        tokens: countsOf(tokens),
+        ...(asked === undefined
+            ? {}
+            : {
+                detail: {
+                    ...shortForm(asked, usedBy, known),
+                    renderedBy: usedBy.get(asked.name) ?? [],
+                    tokens: tokensOfFile(smallFileText(join(dir, asked.file)) ?? "", tokens),
+                    alsoAt: components
+                        .filter((each) => each.name === asked.name && each !== asked)
+                        .map(({ file, line }) => `${file}:${line}`)
+                }
+            }),
+        notes: [...notes, ...unread]
+    };
+};

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

@@ -0,0 +1,33 @@
+import type { DocTag } from "./usageGuidance.ts";
+/** A situation a component answers. */
+export type ComponentIntent = {
+    /** What it is for, in the words of whoever wrote it: components sharing it are the choices for it. */
+    readonly id: string;
+    /** When this one is the right one. */
+    readonly when?: string;
+};
+/** How a component is chosen and how it fits with others. */
+export type ComponentRules = {
+    /** The situations it answers. */
+    readonly intents?: readonly ComponentIntent[];
+    /** What it may stand inside, at any depth; none for anywhere. */
+    readonly parents?: readonly string[];
+    /** What may stand directly inside it; none for anything. */
+    readonly children?: readonly string[];
+    /** What may stand beside it; none for anything. */
+    readonly siblings?: readonly string[];
+    /** The plain elements it stands in for: writing one by hand is a mistake. */
+    readonly insteadOf?: readonly string[];
+};
+/**
+ * A component's rules, from its tags.
+ *
+ * @param tags - its TSDoc tags.
+ */
+export declare const rulesOfTags: (tags: readonly DocTag[]) => ComponentRules | undefined;
+/**
+ * What a rules file says, by component, read as data: one that cannot be read says nothing.
+ *
+ * @param text - the file's text.
+ */
+export declare const rulesOfFile: (text: string) => ReadonlyMap<string, ComponentRules>;