forgebook 0.1.8 → 0.3.0

package/dist/src/vite/catalogueConfig.js

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { packageResolver } from "./configFile.js";
+import { pageModulePath } from "./pages.js";
+import { prebundled, scannedEntries } from "./prebundled.js";
+/**
+ * A file's text, or none when it cannot be read.
+ *
+ * @param file - the file.
+ */
+const readTextFile = (file) => {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Whether an app's configuration names its build's output itself, which the plugin then leaves as it is.
+ *
+ * @param userConfig - the configuration so far.
+ */
+const hasOwnOutput = (userConfig) => userConfig.build?.rolldownOptions?.output !== undefined ||
+    userConfig.build?.rollupOptions?.output !== undefined;
+/**
+ * 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.
+ */
+export const catalogueConfig = (config, userConfig) => ({
+    root: config.dir,
+    // 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)
+    },
+    build: {
+        rolldownOptions: {
+            input: {
+                index: pageModulePath(config.dir, "index.html"),
+                frame: pageModulePath(config.dir, "frame.html")
+            },
+            // a catalogue names each story file's scripts once per loader: a name of its hash alone is a tenth of
+            // what the index weighs, and a catalogue whose builds are read by name keeps Vite's (`readableNames`)
+            ...(config.build.readableNames || hasOwnOutput(userConfig)
+                ? {}
+                : { output: { chunkFileNames: "assets/[hash].js", hashCharacters: "base36" } })
+        }
+    },
+    // 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
+        ? { server: { cors: false } }
+        : {})
+});

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

@@ -0,0 +1,67 @@
+/**
+ * What a change adds, checked against the design system: the mistakes agents make, in the lines they wrote.
+ *
+ * @remarks
+ * Pure, and it reads the change and not the project: code that was already there is not this change's to fix, and a
+ * check that lists a project's history is ignored. A check people turn off is worth nothing, so it reads only the files
+ * where a raw value is a mistake (styles and components), never where it belongs (stories, tests, tokens, generated
+ * 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.
+ *
+ * @module
+ */
+import type { DesignToken } from "./designTokens.ts";
+/** A line a change adds. */
+export type AddedLine = {
+    /** Its file, as the diff names it. */
+    readonly file: string;
+    /** Its line in the new file. */
+    readonly line: number;
+    /** Its text. */
+    readonly text: string;
+};
+/** The rules. */
+export type CodeRule = "raw-color" | "raw-size" | "suppression" | "deleted-test";
+/** What a check found. */
+export type CodeProblem = {
+    /** The rule. */
+    readonly rule: CodeRule;
+    /** The file, relative to the repository. */
+    readonly file: string;
+    /** The line in it; none for a file that is gone. */
+    readonly line?: number;
+    /** What was written. */
+    readonly value: string;
+    /** The name of the token to use instead, when one clearly fits; a name, not code to paste. */
+    readonly fix?: string;
+    /** What to do, in a sentence. */
+    readonly message: string;
+};
+/**
+ * The lines a unified diff adds. A header is read only outside a hunk, since an added line of `++ x` looks like one.
+ *
+ * @param diff - the diff, with no context lines.
+ */
+export declare const addedLines: (diff: string) => AddedLine[];
+/**
+ * Every line of a new file, as added lines: a new file is what an agent writes most, and a diff does not show it.
+ *
+ * @param file - the file, relative to the repository.
+ * @param text - its text.
+ */
+export declare const fileLines: (file: string, text: string) => AddedLine[];
+/**
+ * The test files a change deletes: the plainest way to make a failing check pass.
+ *
+ * @param deleted - the files it deletes.
+ */
+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.
+ *
+ * @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 checkedCode: (lines: readonly AddedLine[], tokens: readonly DesignToken[]) => CodeProblem[];

package/dist/src/vite/checkCode.js

@@ -0,0 +1,145 @@
+import { nearestTokens } from "./nearestToken.js";
+/** A hex colour standing as a value: not an id, an anchor or a word that happens to start like one. */
+const HEX_COLOR = /(?:^|[\s:'"`(,[=])(#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{3,4}))(?![0-9a-z_-])/gi;
+/** A colour function, not a function of that name being declared or a template being written. */
+const COLOR_FUNCTION = /(?<![\w.])(?:rgba?|hsla?|oklch|oklab)\((?![^)]*\$\{)[\d\s.,%/-]+\)/gi;
+/** A size, signed or in Tailwind's brackets. */
+const SIZE = /(?:^|[\s:'"`(,[-])(\d*\.?\d+(?:px|rem))\b/g;
+/** A comment that turns a check off. */
+const SUPPRESSION = /(?:\/\/|\/\*|<!--|\{\/\*)\s*(?:@ts-ignore|@ts-expect-error|@ts-nocheck|eslint-disable|biome-ignore|stylelint-disable)/;
+/** What says why after a suppression: the repository's rule allows one with a reason. */
+const HAS_REASON = /(?:biome-ignore [^:]+:\s*\S|eslint-disable[^*]*--\s*\S|@ts-expect-error\s+\S)/;
+/** The files where a raw value is a mistake: styles and components. */
+const CHECKED_FILE = /\.(?:css|scss|sass|less|tsx|jsx|vue|svelte|astro)$/;
+/** Where raw values belong: stories, tests, tokens and what a tool wrote. */
+const LEFT_ALONE = /(?:\.stories\.|\.test\.|\.spec\.|\.e2e\.|\.min\.|(?:^|\/)_?(?:design-)?tokens?(?:\.|\/)|\.tokens?\.|(?:^|\/)theme\.|(?:^|\/)(?:__tests__|tests?|e2e|dist|build|generated|vendor)\/)/;
+/** A test file. */
+const TEST_FILE = /(?:\.test\.|\.spec\.|\.e2e\.|_test\.|(?:^|\/)(?:__tests__|tests?|e2e)\/)/;
+/** A hunk's header: where its lines start in the new file. */
+const HUNK = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+/** A line that defines a value: a custom property or a Sass variable, where raw values belong. */
+const DEFINES_VALUE = /^\s*(?:--[\w-]+|\$[\w-]+)\s*:/;
+/** A media condition, where `var()` does not work, so a token cannot stand in. */
+const MEDIA_CONDITION = /@(?:media|container)\b/;
+/** A selector, whose `#` is an id. */
+const SELECTOR_LINE = /[{,]\s*$/;
+/** A line's code, without what follows a `//` or a comment's start. */
+const withoutComment = (text) => text.replace(/(?:^|\s)\/\/.*$/, "").replace(/\/\*.*$/, "");
+/**
+ * The lines a unified diff adds. A header is read only outside a hunk, since an added line of `++ x` looks like one.
+ *
+ * @param diff - the diff, with no context lines.
+ */
+export const addedLines = (diff) => {
+    const lines = [];
+    let file = "";
+    let next = 0;
+    let remaining = 0;
+    for (const line of diff.split("\n")) {
+        const hunk = HUNK.exec(line);
+        if (hunk !== null) {
+            next = Number(hunk[1]);
+            remaining = Number(/\+\d+,(\d+)/.exec(line)?.[1] ?? 1);
+        }
+        else if (remaining > 0 && line.startsWith("+")) {
+            lines.push({ file, line: next, text: line.slice(1) });
+            next += 1;
+            remaining -= 1;
+        }
+        else if (remaining === 0 && line.startsWith("+++ ")) {
+            file = line.slice(4).replace(/^b\//, "").replace(/\t$/, "");
+        }
+    }
+    return lines;
+};
+/**
+ * Every line of a new file, as added lines: a new file is what an agent writes most, and a diff does not show it.
+ *
+ * @param file - the file, relative to the repository.
+ * @param text - its text.
+ */
+export const fileLines = (file, text) => text.split("\n").map((line, index) => ({ file, line: index + 1, text: line }));
+/**
+ * The test files a change deletes: the plainest way to make a failing check pass.
+ *
+ * @param deleted - the files it deletes.
+ */
+export const deletedTests = (deleted) => deleted
+    .filter((file) => TEST_FILE.test(file))
+    .map((file) => ({
+    rule: "deleted-test",
+    file,
+    value: file,
+    message: "A test was deleted: fix what it found, or say why it no longer applies."
+}));
+/** The problem of a raw colour: a fix only from a token that holds in every theme. */
+const colorProblem = ({ file, line }, value, tokens) => {
+    const match = nearestTokens(tokens, value, "color").matches.find((each) => each.isClose && each.mode === undefined);
+    return {
+        rule: "raw-color",
+        file,
+        line,
+        value,
+        ...(match === undefined ? {} : { fix: match.name }),
+        message: match === undefined
+            ? "A colour written by hand, and no token is close: ask whether the design system has it."
+            : `A colour written by hand: use the token ${match.name} (${match.value}).`
+    };
+};
+/** The raw colours in a line of code. */
+const colorProblems = (added, code, tokens) => {
+    if (SELECTOR_LINE.test(code) || /(?:href|url)\s*[=(]/.test(code))
+        return [];
+    // digits alone are a number more often than a colour (`Order #1042`), unless they stand as a value
+    const hexes = [...code.matchAll(HEX_COLOR)]
+        .flatMap((match) => match[1] ?? [])
+        .filter((value) => !/^#\d+$/.test(value) || new RegExp(`[:=]\\s*['"\`]?${value}`).test(code));
+    const functions = [...code.matchAll(COLOR_FUNCTION)].map((match) => match[0]);
+    return [...hexes, ...functions].map((value) => colorProblem(added, value, tokens));
+};
+/** The sizes in a line that equal one token: two that do say what the size is for, which this cannot tell. */
+const sizeProblems = ({ file, line }, code, tokens) => {
+    if (MEDIA_CONDITION.test(code))
+        return [];
+    return [...code.matchAll(SIZE)].flatMap((found) => {
+        const value = found[1] ?? "";
+        const exact = nearestTokens(tokens, value, "dimension").matches.filter((each) => each.isExact && each.mode === undefined);
+        const [only] = exact;
+        if (only === undefined)
+            return [];
+        const fix = exact.length === 1 ? { fix: only.name } : {};
+        const names = exact.map((each) => each.name).join(" or ");
+        return [
+            { rule: "raw-size", file, line, value, ...fix, message: `A size written by hand: use ${names}.` }
+        ];
+    });
+};
+/** The suppression a line adds, unless it says why. */
+const suppressionProblem = ({ file, line, text }) => SUPPRESSION.test(text) && !HAS_REASON.test(text)
+    ? [
+        {
+            rule: "suppression",
+            file,
+            line,
+            value: text.trim(),
+            message: "A check was turned off with no reason: fix what it found, or say why it is wrong here."
+        }
+    ]
+    : [];
+/**
+ * What lines a change adds break. 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 const checkedCode = (lines, tokens) => lines.flatMap((added) => {
+    if (!CHECKED_FILE.test(added.file) && !/\.[cm]?[jt]s$/.test(added.file))
+        return [];
+    if (LEFT_ALONE.test(added.file))
+        return [];
+    const suppression = suppressionProblem(added);
+    if (tokens.length === 0 || !CHECKED_FILE.test(added.file) || DEFINES_VALUE.test(added.text))
+        return suppression;
+    const code = withoutComment(added.text);
+    return [...suppression, ...colorProblems(added, code, tokens), ...sizeProblems(added, code, tokens)];
+});

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

@@ -0,0 +1,96 @@
+import type { ViteDevServer, WatchOptions } from "vite";
+/** How many files are followed at most: each holds a file descriptor while it is followed. */
+export declare const CLOSE_WATCH_LIMIT = 64;
+/** A file's watch, as `watchFile` opens it. */
+export type FileWatch = {
+    /** Stops watching. */
+    readonly close: () => void;
+};
+/**
+ * Opens a file's watch: Node's `fs.watch`, unless a test hands its own.
+ *
+ * @param file - the file.
+ * @param onEvent - called with `"change"` when the file's content changed, `"rename"` when the file was replaced or
+ * removed (an editor that saves through a new file), `"error"` when the watch failed.
+ * @throws when the file cannot be watched (gone, or no file descriptor left).
+ */
+export type WatchFile = (file: string, onEvent: (kind: "change" | "rename" | "error") => void) => FileWatch;
+/** The files followed, and what the dev server took of each. */
+export type CloseWatch = {
+    /**
+     * Follows a file, or keeps following it as the most recent; a file that cannot be watched is left to Vite's watcher.
+     *
+     * @param file - the file, in Node's or Vite's form.
+     */
+    readonly follow: (file: string) => void;
+    /**
+     * Whether an update of a followed file is the late report of an edit the environment took already: one the close
+     * watch did not hand on since the environment's last update of the file, whose text is the one it took then. Each
+     * update the close watch handed on is taken, the same text or not; the text is kept for the next. Always false for
+     * a file not followed.
+     *
+     * @param environment - the environment's name.
+     * @param file - the file, in Node's or Vite's form.
+     */
+    readonly isLateReport: (environment: string, file: string) => boolean;
+    /** Stops following every file. */
+    readonly close: () => void;
+};
+/** What `closeWatch` is made with. */
+export type CloseWatchOptions = {
+    /**
+     * Hands a followed file's change to the dev server's watcher.
+     *
+     * @param file - the file, in Vite's form.
+     */
+    readonly onChange: (file: string) => void;
+    /** How many files are followed at most; `CLOSE_WATCH_LIMIT` by default. */
+    readonly limit?: number;
+    /** Opens a file's watch; Node's `fs.watch` by default. */
+    readonly watchFile?: WatchFile;
+    /**
+     * A file's text now, or none when it cannot be read; read from the disk by default.
+     *
+     * @param file - the file.
+     */
+    readonly readText?: (file: string) => string | undefined;
+};
+/**
+ * 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.
+ *
+ * @param options - the dev server's `server.watch`.
+ * @param platform - the system, `process.platform` by default.
+ */
+export declare const isWatchingByFileEvents: (options: WatchOptions | null | undefined, platform?: NodeJS.Platform) => boolean;
+/**
+ * Follows the files a person is working on, each on its own.
+ *
+ * @param options - where a change goes, how many files at most, and how a file is watched and read.
+ */
+export declare const closeWatch: (options: CloseWatchOptions) => CloseWatch;
+/**
+ * A dev server's close watch, where its watcher reads FSEvents and it sends updates: changes go to its watcher, and a
+ * file a page loaded that the person edits is followed from then on, since it is likely edited again. Closed with the
+ * server's HTTP server; the plugin closes it with the server too, which may have none.
+ *
+ * @param server - the dev server.
+ * @param platform - the system, `process.platform` by default.
+ * @returns the close watch; none where the watcher hears of changes at once, or polls.
+ */
+export declare const serverCloseWatch: (server: ViteDevServer, platform?: NodeJS.Platform) => CloseWatch | undefined;
+/** The close watch of the dev server that runs now, as the plugin holds it across restarts. */
+export type CurrentCloseWatch = Pick<CloseWatch, "follow" | "isLateReport" | "close"> & {
+    /**
+     * Ends the watch of the server before, if any, and starts this server's: a restart configures the new server before
+     * it closes the old one.
+     *
+     * @param server - the dev server; none in a run where no person waits for a page (a test run).
+     * @param platform - the system, `process.platform` by default.
+     */
+    readonly serve: (server: ViteDevServer | undefined, platform?: NodeJS.Platform) => void;
+};
+/**
+ * The close watch of the dev server that runs now; none follows a file until a server is served.
+ */
+export declare const currentCloseWatch: () => CurrentCloseWatch;

package/dist/src/vite/closeWatch.js

@@ -0,0 +1,219 @@
+/**
+ * The files a person is working on, each watched on its own, so the dev server hears of an edit at once: the story
+ * files the open frames loaded, and each file a page loaded that was edited since the server started.
+ *
+ * @remarks
+ * On macOS, Vite's watcher hears of a change through FSEvents, by streams that deliver it a tenth of a second late by
+ * design, and later still while the system's file-event service is busy: on a large library that wait is most of the
+ * time an edit takes to reach the page, and most of its spread. A file watched on its own (`fs.watch` on the file,
+ * a kernel event) is told at once, so each followed file's change is handed to Vite's watcher as its own. Its
+ * FSEvents event still comes, a little later: the dev server drops an update the close watch did not hand on when it
+ * finds the text the environment took last (`isLateReport`), so an edit is drawn once, while a save that changes
+ * nothing still draws anew when the close watch reports it (a story retried after an error). Vite still marks the
+ * file's modules stale for a dropped report, and no later plugin's `hotUpdate` sees it. A watch holds a file
+ * descriptor, so only a bounded few files are followed, the least recently followed dropped first; never a
+ * dependency's file, which Vite's watcher ignores, nor a page (`.html`), for which Vite answers an update it drops
+ * with a reload of the pages.
+ *
+ * Only where Vite's watcher reads FSEvents and the dev server sends updates: elsewhere its events already come at
+ * once, polling (`--poll`) is the choice where no event can be trusted, and a watcher told to wait for writes to
+ * finish (`awaitWriteFinish`) is left to wait.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, watch } from "node:fs";
+import { VITE_PATHS } from "./vitePaths.js";
+/** Where a project's dependencies are installed, whose files Vite's watcher ignores and none is followed in. */
+const DEPENDENCIES = "/node_modules/";
+/** A page, whose update Vite answers with a reload when it is dropped: never followed. */
+const PAGE_FILE = /\.html?$/;
+/** How many files are followed at most: each holds a file descriptor while it is followed. */
+export const CLOSE_WATCH_LIMIT = 64;
+/**
+ * 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.
+ */
+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() };
+};
+/**
+ * A file's text, or none when it cannot be read.
+ *
+ * @param file - the file.
+ */
+const diskText = (file) => {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * A text's digest: what is kept of a file's last update, so a long file is not held twice.
+ *
+ * @param text - the text.
+ */
+const digestOf = (text) => createHash("sha256").update(text).digest("hex");
+/**
+ * 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.
+ *
+ * @param options - the dev server's `server.watch`.
+ * @param platform - the system, `process.platform` by default.
+ */
+export const isWatchingByFileEvents = (options, platform = process.platform) => platform === "darwin" &&
+    options !== null &&
+    options?.usePolling !== true &&
+    options?.useFsEvents !== false &&
+    (options?.awaitWriteFinish === undefined || options.awaitWriteFinish === false);
+/**
+ * Follows the files a person is working on, each on its own.
+ *
+ * @param options - where a change goes, how many files at most, and how a file is watched and read.
+ */
+export const closeWatch = (options) => {
+    const limit = options.limit ?? CLOSE_WATCH_LIMIT;
+    const watchFile = options.watchFile ?? nodeWatchFile;
+    const readText = options.readText ?? diskText;
+    // by file in Vite's form, the least recently followed first
+    const followed = new Map();
+    // how many changes of each followed file the close watch handed on
+    const handed = new Map();
+    // what each environment last took of a followed file, by environment and file: the handed count it had reached and
+    // the text's digest
+    const taken = new Map();
+    // the files whose change is handed on at the end of this turn: a save is often two events (emptied, then written)
+    const handing = new Set();
+    const handOn = (file) => {
+        if (handing.has(file))
+            return;
+        handing.add(file);
+        setImmediate(() => {
+            handing.delete(file);
+            if (!followed.has(file))
+                return;
+            handed.set(file, (handed.get(file) ?? 0) + 1);
+            options.onChange(file);
+        });
+    };
+    const stop = (file) => {
+        followed.get(file)?.close();
+        followed.delete(file);
+    };
+    const forget = (file) => {
+        stop(file);
+        handed.delete(file);
+        for (const key of [...taken.keys()]) {
+            if (key.endsWith(`\0${file}`))
+                taken.delete(key);
+        }
+    };
+    const open = (file) => {
+        try {
+            followed.set(file, watchFile(file, (kind) => {
+                if (kind === "change") {
+                    handOn(file);
+                    return;
+                }
+                // a file saved through a new one is another file now: the old watch hears nothing more of it, and what
+                // was taken of it still tells the late event of this save from a new edit
+                if (kind === "rename" && existsSync(file)) {
+                    stop(file);
+                    open(file);
+                    handOn(file);
+                    return;
+                }
+                // removed, or the watch failed: Vite's own watcher reports what follows
+                forget(file);
+            }));
+        }
+        catch {
+            // gone already, or no file descriptor left: Vite's own watcher still reports it
+        }
+        while (followed.size > limit) {
+            const oldest = followed.keys().next().value;
+            if (oldest === undefined)
+                break;
+            forget(oldest);
+        }
+    };
+    return {
+        follow: (file) => {
+            const key = VITE_PATHS.normalize(file);
+            if (key.includes(DEPENDENCIES) || PAGE_FILE.test(key))
+                return;
+            const kept = followed.get(key);
+            if (kept === undefined) {
+                open(key);
+                return;
+            }
+            followed.delete(key);
+            followed.set(key, kept);
+        },
+        isLateReport: (environment, file) => {
+            const key = VITE_PATHS.normalize(file);
+            if (!followed.has(key))
+                return false;
+            const text = readText(key);
+            if (text === undefined)
+                return false;
+            const digest = digestOf(text);
+            const takenKey = `${environment}\0${key}`;
+            const last = taken.get(takenKey);
+            const count = handed.get(key) ?? 0;
+            const isHandedOn = last === undefined || count > last.handed;
+            if (!isHandedOn && last.digest === digest)
+                return true;
+            taken.set(takenKey, { handed: count, digest });
+            return false;
+        },
+        close: () => {
+            for (const file of [...followed.keys()])
+                forget(file);
+        }
+    };
+};
+/**
+ * A dev server's close watch, where its watcher reads FSEvents and it sends updates: changes go to its watcher, and a
+ * file a page loaded that the person edits is followed from then on, since it is likely edited again. Closed with the
+ * server's HTTP server; the plugin closes it with the server too, which may have none.
+ *
+ * @param server - the dev server.
+ * @param platform - the system, `process.platform` by default.
+ * @returns the close watch; none where the watcher hears of changes at once, or polls.
+ */
+export const serverCloseWatch = (server, platform = process.platform) => {
+    const { watch, hmr } = server.config.server;
+    if (!isWatchingByFileEvents(watch, platform) || hmr === false)
+        return undefined;
+    const watching = closeWatch({ onChange: (file) => void server.watcher.emit("change", file) });
+    server.watcher.on("change", (file) => {
+        const loaded = server.environments.client.moduleGraph.getModulesByFile(VITE_PATHS.normalize(file));
+        if (loaded !== undefined && loaded.size > 0)
+            watching.follow(file);
+    });
+    server.httpServer?.on("close", () => watching.close());
+    return watching;
+};
+/**
+ * The close watch of the dev server that runs now; none follows a file until a server is served.
+ */
+export const currentCloseWatch = () => {
+    let current;
+    return {
+        serve: (server, platform = process.platform) => {
+            current?.close();
+            current = server === undefined ? undefined : serverCloseWatch(server, platform);
+        },
+        follow: (file) => current?.follow(file),
+        isLateReport: (environment, file) => current?.isLateReport(environment, file) === true,
+        close: () => current?.close()
+    };
+};

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

@@ -0,0 +1,78 @@
+/**
+ * A code fence's whole line read, and its code drawn by it: a title, marked lines, inserted and deleted lines, a diff
+ * coloured in its own language, and long lines wrapped.
+ *
+ * @remarks
+ * The line after the backticks is written as Expressive Code and VitePress write it, so an author knows it: the
+ * language, then `title="Button.tsx"`, the marked lines in braces (`1,4-6`), `ins=` and `del=` with lines in braces,
+ * and `wrap`; a `diff` fence takes `lang="tsx"`, so its `+` and `-` lines keep the colours of their language. Everything is done here, at build time: the page gets HTML
+ * whose lines are elements (`<mark>`, `<ins>`, `<del>`), so a screen reader hears what changed and the shell needs no
+ * script for it. The copied text is the code as it reads after the change: its diff signs taken off and its deleted
+ * lines left out, so what is pasted runs. Pure.
+ *
+ * @module
+ */
+import type { PageNote, SourcePosition } from "./docDirectives.ts";
+/** What a code fence's line says. */
+export type FenceInfo = {
+    /** The language the code is coloured in; none leaves it plain. */
+    readonly language: string | undefined;
+    /** Its title, a file's name most often; none when it has none. */
+    readonly title: string | undefined;
+    /** The lines marked, from 1. */
+    readonly marked: ReadonlySet<number>;
+    /** The lines inserted, from 1. */
+    readonly inserted: ReadonlySet<number>;
+    /** The lines deleted, from 1. */
+    readonly deleted: ReadonlySet<number>;
+    /** Whether it is a diff, whose lines start with `+`, `-` or a space. */
+    readonly isDiff: boolean;
+    /** Whether long lines wrap instead of scrolling. */
+    readonly isWrapped: boolean;
+};
+/** A code block as the page draws it. */
+export type FencedCode = {
+    /** The code as the copy button copies it. */
+    readonly text: string;
+    /** The code as HTML, coloured, its lines elements when some are marked. */
+    readonly html: string;
+    /** Its language, when it has one. */
+    readonly language: string | undefined;
+    /** Its title, when it has one. */
+    readonly title: string | undefined;
+    /** Whether long lines wrap. */
+    readonly isWrapped: boolean;
+};
+/**
+ * What a code fence's line says, every word it does not read reported where it is.
+ *
+ * @param info - the line after the backticks.
+ * @param start - where the line starts in the file, for the notes.
+ * @param notes - receives what cannot be read.
+ */
+export declare const fenceInfo: (info: string, start: SourcePosition, notes: PageNote[]) => FenceInfo;
+/**
+ * Coloured HTML split at its lines, every span closed at a line's end and opened again on the next, so each line can
+ * be an element of its own.
+ *
+ * @param html - the coloured code.
+ */
+export declare const htmlLines: (html: string) => string[];
+/**
+ * The first line a fence names that its code does not have; none when every line it names is there.
+ *
+ * @param code - the code as the fence holds it.
+ * @param info - what its fence's line says.
+ * @returns the line, and how many the code has.
+ */
+export declare const missingLine: (code: string, info: FenceInfo) => {
+    readonly line: number;
+    readonly count: number;
+} | undefined;
+/**
+ * A fenced block's code as the page draws it.
+ *
+ * @param code - the code as the fence holds it.
+ * @param info - what its fence's line says.
+ */
+export declare const fencedCode: (code: string, info: FenceInfo) => FencedCode;