forgebook 0.3.3 → 0.4.1

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

@@ -0,0 +1,45 @@
+/**
+ * What a change adds against the components a project already has: imports of what is deprecated or replaced, and new
+ * components that look like one that exists. Props are left to the type checker, which catches them where this cannot.
+ *
+ * @remarks
+ * Pure. It reads only what the change adds, as the rest of `check-code` does. A component's own words decide what is
+ * deprecated (`@deprecated`, `@replacedBy`). What fails has to be sure: a new exported component fails as a copy under any
+ * name, with the same name and two signs of being the same thing, or rebuilding a plain element a component of its name
+ * exists for. One sign is said as `advice`, as is what `@useWhen` and `@avoidWhen` say of a component just imported, since
+ * only a reader can weigh them. It compares only what the file could use: its package and those its package depends on.
+ *
+ * @module
+ */
+import type { AddedLine, CodeAdvice, CodeProblem, ExcusedValue } from "./checkCode.ts";
+import { type ScannedComponent } from "./componentScan.ts";
+import type { ProjectFile, WorkspacePackage } from "./projectFiles.ts";
+/** What the reuse check found. */
+export type ReuseFindings = {
+    /** What fails. */
+    readonly problems: readonly CodeProblem[];
+    /** What to weigh. */
+    readonly advice: readonly CodeAdvice[];
+    /** New components a comment says are meant. */
+    readonly excused: readonly ExcusedValue[];
+};
+/** What the reuse check reads. */
+export type ReuseInput = {
+    /** The lines the change adds, with paths from the repository. */
+    readonly added: readonly AddedLine[];
+    /** The changed files that can hold components, as they are now. */
+    readonly changed: readonly ProjectFile[];
+    /** The same as they were, and those the change deleted. */
+    readonly previous: readonly ProjectFile[];
+    /** Every component of the project as it is now. */
+    readonly components: readonly ScannedComponent[];
+    /** The repository's packages. */
+    readonly packages: readonly WorkspacePackage[];
+};
+/**
+ * What a change adds against the components the project has. New means new against the commit it starts from: an edit of a
+ * line that declares a component is no new component, nor is a file moved, nor a name a file already imported.
+ *
+ * @param input - the change and the project.
+ */
+export declare const reuseFindings: (input: ReuseInput) => ReuseFindings;

package/dist/src/vite/reuseCheck.js

@@ -0,0 +1,260 @@
+import { scannedComponents } from "./componentScan.js";
+import { importsOfFile } from "./fileImports.js";
+import { isBuiltOn, isRebuilt, isShareable, SAME_CODE, signsBetween, stemOf } from "./lookAlikes.js";
+import { plainWords } from "./sourceText.js";
+/** What says a new component is meant: its rule and why, in a comment. */
+const IGNORE_DUPLICATE = /(?:\/\/|\/\*|<!--)\s*forgebook-ignore\s+duplicate-component\s*:\s*([^*\n]{3,120})/;
+/** How far above a component its comment may stand, past its own documentation. */
+const IGNORE_REACH = 20;
+/** A name a fix may give: an agent may act on it, and a tag holds any text. */
+const COMPONENT_NAME = /^[A-Za-z_$][\w$.]{0,80}$/;
+/** How many things to weigh an answer gives. */
+const MOST_ADVICE = 20;
+/** How much of a tag's text an answer repeats. */
+const LONGEST_WORDS = 200;
+/** What a package name's module part is. */
+const PACKAGE_NAME = /^(@[^/]+\/[^/]+|[^@./][^/]*)(?:\/(.*))?$/;
+/** A file's extension and a folder's index, which an import may leave out or write. */
+const modulePath = (file) => file.replace(/\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/, "").replace(/\/index$/, "");
+/** A relative module's path from the repository. */
+const relativeTarget = (from, module) => {
+    const parts = from.split("/").slice(0, -1);
+    for (const part of module.split("/")) {
+        if (part === "..")
+            parts.pop();
+        else if (part !== ".")
+            parts.push(part);
+    }
+    return parts.join("/");
+};
+/** The folders of a file, nearest first, the repository last. */
+const foldersOf = (file) => {
+    const parts = file.split("/").slice(0, -1);
+    return [...parts.keys(), parts.length].map((count) => parts.slice(0, count).join("/")).toReversed();
+};
+/**
+ * What an import may mean in the project's paths. An alias's folder is not known, but it is one this file sits under, so
+ * another application's file of that path is not it; a package's name is the one its manifest says, so a third party's of
+ * a similar path is not it either.
+ */
+const targetsOf = (from, module, packages) => {
+    const written = modulePath(module);
+    if (written.startsWith("."))
+        return [relativeTarget(from, written)];
+    if (/^[@~#]\//.test(written)) {
+        const rest = written.slice(2);
+        return foldersOf(from).map((folder) => (folder === "" ? rest : `${folder}/${rest}`));
+    }
+    const [, name = "", rest = ""] = PACKAGE_NAME.exec(written) ?? [];
+    const found = packages.find((each) => each.name === name && each.name !== "");
+    if (found === undefined)
+        return [];
+    const inside = (folder) => [found.dir, folder, rest].filter((part) => part !== "").join("/");
+    return [inside(""), inside("src")];
+};
+/** Whether a component is what an import of a name means. */
+const isImported = (component, name, targets) => {
+    const path = modulePath(component.file);
+    if (targets.includes(path))
+        return name === "default" ? component.isDefault === true : component.name === name;
+    // through a folder's index the file is another; the name has to be that folder's own
+    return name === component.name && targets.some((target) => target !== "" && path.startsWith(`${target}/`));
+};
+/** A tag's text as an answer repeats it. */
+const capped = (text) => plainWords(text, LONGEST_WORDS);
+/** What an imported component's own words make of importing it. */
+const wordsOnImport = (file, line, { name, guidance, rules }) => {
+    const { deprecated, replacedBy, useWhen, avoidWhen } = guidance ?? {};
+    if (deprecated !== undefined || replacedBy !== undefined) {
+        const why = deprecated === undefined ? "" : `: ${deprecated}`;
+        const use = replacedBy === undefined ? "" : ` Use ${replacedBy}.`;
+        return {
+            problems: [
+                {
+                    rule: "deprecated-component",
+                    file,
+                    line,
+                    value: name,
+                    ...(replacedBy !== undefined && COMPONENT_NAME.test(replacedBy) ? { fix: replacedBy } : {}),
+                    message: `${name} is deprecated${capped(why)}${capped(use)}`
+                }
+            ],
+            advice: [],
+            excused: []
+        };
+    }
+    const intents = (rules?.intents ?? []).map(({ id, when }) => `for ${id}${when === undefined ? "" : ` (${when})`}`);
+    const parts = [
+        ...intents,
+        ...(useWhen === undefined ? [] : [`use when ${useWhen.join("; ")}`]),
+        ...(avoidWhen === undefined ? [] : [`avoid when ${avoidWhen.join("; ")}`])
+    ];
+    return {
+        problems: [],
+        advice: parts.length === 0 ? [] : [{ file, line, message: `${name}: ${capped(parts.join("; "))}.` }],
+        excused: []
+    };
+};
+/** What fails and what to weigh in one import the change adds, of the names it did not import before. */
+const importFindings = (file, { names, module, lines }, isOld, { components, packages }) => {
+    const targets = targetsOf(file, module, packages);
+    const found = names
+        .filter((name) => !isOld(name))
+        .flatMap((name) => {
+        const matches = components.filter((each) => each.file !== file &&
+            (each.guidance !== undefined || each.rules?.intents !== undefined) &&
+            isImported(each, name, targets));
+        // two of a name through one folder could be either
+        return matches.length === 1 ? matches : [];
+    })
+        .map((each) => wordsOnImport(file, lines[0], each));
+    return {
+        problems: found.flatMap((each) => each.problems),
+        advice: found.flatMap((each) => each.advice),
+        excused: []
+    };
+};
+/** Where an existing component is, and when to use it. */
+const existingWords = ({ name, file, line, guidance }) => {
+    const when = guidance?.useWhen === undefined ? "" : ` (use when ${capped(guidance.useWhen.join("; "))})`;
+    return `${name} in ${file}:${line}${when}`;
+};
+/** The existing component a new one is surely the same as, with why: a copy under any name, or the same name and signs. */
+const sureMatch = (added, existing, alike) => {
+    const copied = added.code === undefined
+        ? undefined
+        : existing.find((other) => other.file !== added.file && other.code === added.code);
+    if (copied !== undefined)
+        return { other: copied, why: SAME_CODE };
+    const sure = alike.find(({ signs }) => signs.length >= 2);
+    if (sure !== undefined)
+        return { other: sure.other, why: sure.signs.join(", ") };
+    const [first] = alike;
+    return first !== undefined && isRebuilt(added, stemOf(added.name))
+        ? { other: first.other, why: `it renders a plain ${added.root ?? ""} of its own` }
+        : undefined;
+};
+/** What a new component is against those that exist. */
+const newComponentFindings = (added, existing) => {
+    const stem = stemOf(added.name);
+    const isRebuilding = isRebuilt(added, stem);
+    const alike = existing.flatMap((other) => {
+        if (other.file === added.file || isBuiltOn(added, other) || stemOf(other.name) !== stem)
+            return [];
+        const signs = signsBetween(added, other);
+        return signs.length === 0 && !isRebuilding ? [] : [{ other, signs }];
+    });
+    const sure = sureMatch(added, existing, alike);
+    const { name, file, line } = added;
+    if (sure !== undefined) {
+        return {
+            problems: [
+                {
+                    rule: "duplicate-component",
+                    file,
+                    line,
+                    value: name,
+                    fix: sure.other.name,
+                    message: `${name} looks like ${existingWords(sure.other)}: ${sure.why}. Use it, or say why not.`
+                }
+            ],
+            advice: [],
+            excused: []
+        };
+    }
+    return {
+        problems: [],
+        excused: [],
+        advice: alike.slice(0, 1).map(({ other, signs }) => ({
+            file,
+            line,
+            message: `${name} may be ${existingWords(other)}: ${signs.join(", ")}.`
+        }))
+    };
+};
+/** The package a file belongs to: the nearest with a manifest. */
+const packageOf = (file, packages) => packages
+    .filter(({ dir }) => dir === "" || file.startsWith(`${dir}/`))
+    .toSorted((first, second) => second.dir.length - first.dir.length)[0];
+/** Whether a file could use a component of another: in one package, or one its package depends on. */
+const canUse = (file, other, packages) => {
+    const [own, theirs] = [packageOf(file, packages), packageOf(other, packages)];
+    return own === theirs || theirs === undefined || (own?.dependsOn.includes(theirs.name) ?? true);
+};
+/** A comment excusing a new component, when one stands within reach above it (anywhere in a single-file component). */
+const excuseOf = ({ name, file, line }, added) => {
+    for (const each of added) {
+        const reason = each.file === file ? IGNORE_DUPLICATE.exec(each.text)?.[1] : undefined;
+        const isNear = line === 1 || (each.line <= line && each.line >= line - IGNORE_REACH);
+        if (reason !== undefined && isNear) {
+            return { file, line: each.line, rule: "duplicate-component", reason: `${name}: ${reason.trim()}` };
+        }
+    }
+    return undefined;
+};
+/** What the components were before the change: by file, and those of files it deleted, which may only have moved. */
+const before = (previous, changed) => {
+    const current = new Set(changed.map(({ file }) => file));
+    const scanned = previous.map(({ file, text }) => ({
+        file,
+        components: scannedComponents(file, text),
+        imported: importsOfFile(file, text).flatMap(({ names }) => names)
+    }));
+    const gone = scanned.filter(({ file }) => !current.has(file));
+    return {
+        names: new Map(scanned.map(({ file, components }) => [file, new Set(components.map(({ name }) => name))])),
+        imports: new Map(scanned.map(({ file, imported }) => [file, new Set(imported)])),
+        moved: {
+            names: new Set(gone.flatMap(({ components }) => components.map(({ name }) => name))),
+            codes: new Set(gone.flatMap(({ components }) => components.flatMap(({ code }) => code ?? []))),
+            imports: new Set(gone.flatMap(({ imported }) => imported))
+        }
+    };
+};
+/**
+ * What a change adds against the components the project has. New means new against the commit it starts from: an edit of a
+ * line that declares a component is no new component, nor is a file moved, nor a name a file already imported.
+ *
+ * @param input - the change and the project.
+ */
+export const reuseFindings = (input) => {
+    const { added, changed, previous, components, packages } = input;
+    const lines = new Map();
+    for (const { file, line } of added)
+        lines.set(file, (lines.get(file) ?? new Set()).add(line));
+    const isAdded = (file, from, to) => {
+        const own = lines.get(file);
+        for (let at = from; own !== undefined && at <= to; at += 1)
+            if (own.has(at))
+                return true;
+        return false;
+    };
+    const was = before(previous, changed);
+    const imports = changed.flatMap(({ file, text }) => {
+        const isOld = (name) => was.imports.get(file)?.has(name) === true || was.moved.imports.has(name);
+        return importsOfFile(file, text)
+            .filter(({ lines: [from, to] }) => isAdded(file, from, to))
+            .map((each) => importFindings(file, each, isOld, input));
+    });
+    const changedFiles = new Set(changed.map(({ file }) => file));
+    const isNew = ({ file, name, code }) => changedFiles.has(file) &&
+        was.names.get(file)?.has(name) !== true &&
+        !was.moved.names.has(name) &&
+        !(code !== undefined && was.moved.codes.has(code));
+    const usable = components.filter((each) => each.isExported && isShareable(each));
+    const fresh = usable.filter(isNew).map((each) => {
+        const excuse = excuseOf(each, added);
+        if (excuse !== undefined)
+            return { problems: [], advice: [], excused: [excuse] };
+        const reachable = usable.filter((other) => !isNew(other) && canUse(each.file, other.file, packages));
+        return newComponentFindings(each, reachable);
+    });
+    const all = [...imports, ...fresh];
+    return {
+        problems: all.flatMap((each) => each.problems),
+        advice: [
+            ...new Map(all.flatMap((each) => each.advice).map((each) => [JSON.stringify(each), each])).values()
+        ].slice(0, MOST_ADVICE),
+        excused: all.flatMap((each) => each.excused)
+    };
+};

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

@@ -0,0 +1,33 @@
+/**
+ * What a catalogue says when Vite's configuration is read: what is wrong with its theme, and of the Vite it finds itself running on: the command brings its own, and an app that puts the plugin
+ * in its own `vite.config` runs it on the app's.
+ *
+ * @module
+ */
+import type { Logger } from "vite";
+/**
+ * Stops on a Vite older than the one this runs on, for an app that puts this plugin in its own `vite.config`: the command
+ * brings its own Vite, and a project's older one would otherwise fail later, at its first watched file, far from here.
+ *
+ * @param build - the resolved configuration's `build`, which names Rolldown's options from Vite 8 on.
+ * @throws when it is an older Vite's.
+ */
+export declare const assertViteEight: (build: object | undefined) => void;
+/** What is read of Vite's resolved configuration. */
+export type ResolvedVite = {
+    /** Vite's logger. */
+    readonly logger: Logger;
+    /** Its cache folder. */
+    readonly cacheDir: string;
+    /** Its `build`; none in a test's stand-in. */
+    readonly build?: object;
+};
+/**
+ * Stops on a Vite too old, and warns of what will not work in the shell's theme: a warning, since a theme a reader can still
+ * use must not stop a catalogue from building.
+ *
+ * @param resolved - Vite's resolved configuration.
+ * @param themeProblems - what will not work in the theme.
+ * @throws when Vite is too old.
+ */
+export declare const checkAtStart: (resolved: ResolvedVite, themeProblems: readonly string[]) => void;

package/dist/src/vite/runningVersions.js

@@ -0,0 +1,25 @@
+/**
+ * Stops on a Vite older than the one this runs on, for an app that puts this plugin in its own `vite.config`: the command
+ * brings its own Vite, and a project's older one would otherwise fail later, at its first watched file, far from here.
+ *
+ * @param build - the resolved configuration's `build`, which names Rolldown's options from Vite 8 on.
+ * @throws when it is an older Vite's.
+ */
+export const assertViteEight = (build) => {
+    if (build === undefined || "rolldownOptions" in build)
+        return;
+    throw new Error("forgebookPlugin runs on Vite 8.3.4 or later, and this vite.config runs on an older one: run the catalogue with the forgebook command, which brings its own, or upgrade Vite");
+};
+/**
+ * Stops on a Vite too old, and warns of what will not work in the shell's theme: a warning, since a theme a reader can still
+ * use must not stop a catalogue from building.
+ *
+ * @param resolved - Vite's resolved configuration.
+ * @param themeProblems - what will not work in the theme.
+ * @throws when Vite is too old.
+ */
+export const checkAtStart = (resolved, themeProblems) => {
+    assertViteEight(resolved.build);
+    for (const problem of themeProblems)
+        resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
+};

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

@@ -0,0 +1,60 @@
+import { type Logger } from "vite";
+import type { StoryFileRead } from "../hotModules.ts";
+/** A project's script: JavaScript or TypeScript, with or without JSX. */
+export declare const SCRIPT: RegExp;
+/** A file of an installed package, which is not the project's to fix. */
+export declare const INSTALLED: RegExp;
+/** A script parsed: its imports, and why it does not parse. */
+export type ParsedScript = {
+    /** The modules it imports statically, as written. */
+    readonly imports: readonly string[];
+    /** Whether it parses only as JSX (a `.js` file holding JSX). */
+    readonly isJsx: boolean;
+    /** Why it does not parse, naming the file with its line and column; none when it parses. */
+    readonly problem: string | undefined;
+};
+/**
+ * A script parsed as its extension says, and as JSX when only that makes a plain `.js` file parse.
+ *
+ * @param file - the script's path, as the problem names it; its extension decides TypeScript and JSX.
+ * @param text - its source.
+ */
+export declare const parsedScript: (file: string, text: string) => ParsedScript;
+/**
+ * Whether a file is one of the project's scripts this module names: not a story file, not an installed package's.
+ *
+ * @param file - the file.
+ */
+export declare const isNamedScript: (file: string) => boolean;
+/** The project's scripts that do not parse, as a dev server or a dependency scan knows them. */
+export type ScriptProblems = {
+    /**
+     * Starts once Vite's configuration is resolved: keeps the logger the scan's warnings go to, and the folder the
+     * problems are kept in between processes, reading what an earlier scan found there, each file read again.
+     *
+     * @param logger - Vite's logger.
+     * @param folder - Forgebook's cache folder; none keeps nothing (a build).
+     */
+    readonly start: (logger: Pick<Logger, "warn">, folder: string | undefined) => void;
+    /** Writes a warning of the scan, once the logger is known (the scan runs after the configuration is resolved). */
+    readonly warn: (line: string) => void;
+    /**
+     * Notes what a scan found of a script.
+     *
+     * @param file - the script, absolute.
+     * @param problem - why it does not parse; none when it does.
+     * @returns whether that is new: a problem not known before.
+     */
+    readonly scanned: (file: string, problem: string | undefined) => boolean;
+    /**
+     * Reads an edited script again.
+     *
+     * @param file - the script, absolute.
+     * @returns whether it parses now, when that changed; none when nothing changed.
+     */
+    readonly edited: (file: string) => StoryFileRead | undefined;
+    /** The problems, one per script. */
+    readonly list: () => readonly string[];
+};
+/** The project's scripts that do not parse, empty until a scan or an edit finds one. */
+export declare const scriptProblems: () => ScriptProblems;

package/dist/src/vite/scriptProblems.js

@@ -0,0 +1,155 @@
+/**
+ * The project's scripts that do not parse, other than story files: each one a problem naming its place, among the
+ * index's problems, so a component that does not parse is named once, before any frame loads it, to people and agents.
+ *
+ * @remarks
+ * Vite's dependency scan finds them (`prebundled.ts`), and an edit of a script finds them on a dev server, which also
+ * recovers on the fix. The scan may run in a process of its own (a first start's pre-bundling), and a later start that
+ * keeps the pre-bundled packages does not scan: what it found is kept in Forgebook's cache folder, read when a dev
+ * server starts, and each file read again then, so a file fixed in between is not named. A file broken while no server
+ * ran is named once it is edited, or by the frames of the stories that import it. Story files are the catalogue's own
+ * to name (`storyFilesModule.ts`).
+ *
+ * @module
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseSync } from "vite";
+import { STORY_FILE } from "./autoTitle.js";
+import { lineAndColumn } from "./lineAndColumn.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A project's script: JavaScript or TypeScript, with or without JSX. */
+export const SCRIPT = /\.[cm]?[jt]sx?$/;
+/** A file of an installed package, which is not the project's to fix. */
+export const INSTALLED = /[\\/]node_modules[\\/]/;
+/** A script whose extension says nothing about JSX: it may hold JSX, as libraries written in JavaScript do. */
+const PLAIN_SCRIPT = /\.[cm]?js$/;
+/** The file the found problems are kept in, in Forgebook's cache folder. */
+const KEPT_FILE = "script-problems.json";
+/**
+ * A script parsed as its extension says, and as JSX when only that makes a plain `.js` file parse.
+ *
+ * @param file - the script's path, as the problem names it; its extension decides TypeScript and JSX.
+ * @param text - its source.
+ */
+export const parsedScript = (file, text) => {
+    const parsed = parseSync(file, text);
+    const imports = parsed.module.staticImports.map((each) => each.moduleRequest.value);
+    const [error] = parsed.errors;
+    if (error === undefined)
+        return { imports, isJsx: false, problem: undefined };
+    if (PLAIN_SCRIPT.test(file)) {
+        const asJsx = parseSync(file, text, { lang: "jsx" });
+        if (asJsx.errors.length === 0) {
+            return {
+                imports: asJsx.module.staticImports.map((each) => each.moduleRequest.value),
+                isJsx: true,
+                problem: undefined
+            };
+        }
+    }
+    const [label] = error.labels;
+    const place = label === undefined ? file : `${file}:${lineAndColumn(text, label.start)}`;
+    return { imports, isJsx: false, problem: `${place} does not parse: ${error.message}` };
+};
+/**
+ * Whether a file is one of the project's scripts this module names: not a story file, not an installed package's.
+ *
+ * @param file - the file.
+ */
+export const isNamedScript = (file) => SCRIPT.test(file) && !INSTALLED.test(file) && !STORY_FILE.test(file);
+/**
+ * Why a script on disk does not parse; none when it does, or cannot be read (an editor writes it anew in place).
+ *
+ * @param file - the script, absolute in Vite's form.
+ */
+const problemOnDisk = (file) => {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return parsedScript(file, readFileSync(file, "utf8")).problem;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The problems kept in a folder, each file read again; none when nothing is kept there.
+ *
+ * @param path - the kept file.
+ */
+const keptProblems = (path) => {
+    const problems = new Map();
+    if (!existsSync(path))
+        return problems;
+    try {
+        const kept = JSON.parse(readFileSync(path, "utf8"));
+        if (!Array.isArray(kept))
+            return problems;
+        for (const file of kept) {
+            if (typeof file !== "string")
+                continue;
+            const problem = problemOnDisk(file);
+            if (problem !== undefined)
+                problems.set(file, problem);
+        }
+    }
+    catch {
+        // a file another version wrote, or half written: the next scan or edit writes it anew
+    }
+    return problems;
+};
+/** The project's scripts that do not parse, empty until a scan or an edit finds one. */
+export const scriptProblems = () => {
+    const problems = new Map();
+    let keptPath;
+    let logger;
+    const keep = () => {
+        if (keptPath === undefined)
+            return;
+        try {
+            mkdirSync(VITE_PATHS.dirname(keptPath), { recursive: true });
+            writeFileSync(keptPath, JSON.stringify([...problems.keys()]));
+        }
+        catch {
+            // a read-only cache folder: the problems stay this process's
+        }
+    };
+    return {
+        start: (started, folder) => {
+            logger = started;
+            if (folder === undefined)
+                return;
+            keptPath = join(folder, KEPT_FILE);
+            for (const [file, problem] of keptProblems(keptPath))
+                problems.set(file, problem);
+        },
+        warn: (line) => logger?.warn(line),
+        scanned: (file, problem) => {
+            const key = VITE_PATHS.normalize(file);
+            const before = problems.get(key);
+            if (problem === undefined)
+                problems.delete(key);
+            else
+                problems.set(key, problem);
+            if (before !== problem)
+                keep();
+            return problem !== undefined && before !== problem;
+        },
+        edited: (file) => {
+            const key = VITE_PATHS.normalize(file);
+            if (!isNamedScript(key))
+                return undefined;
+            const problem = problemOnDisk(key);
+            if (problem === problems.get(key))
+                return undefined;
+            if (problem === undefined)
+                problems.delete(key);
+            else
+                problems.set(key, problem);
+            keep();
+            return { file: key, ...(problem === undefined ? {} : { problem }) };
+        },
+        list: () => [...problems.values()]
+    };
+};

package/dist/src/vite/searchModule.js

@@ -14,7 +14,7 @@ import { readFileSync } from "node:fs";
 import { componentPage } from "./componentPage.js";
 import { compiledDocPage } from "./docPageMarkdown.js";
 import { indexedDocPages } from "./docPagesModule.js";
-import { EVERY_FILE, indexedStoryFiles } from "./storyFilesModule.js";
+import { EVERY_FILE, readStoryFiles } from "./storyFilesModule.js";
 /** A heading of the pages' HTML: its anchor, and what is inside it. */
 const HEADING = /<h[1-6] id="doc-([^"]*)"[^>]*>([\s\S]*?)<\/h[1-6]>/g;
 /** A tag: `>` inside a quoted attribute does not end it. */
@@ -186,7 +186,8 @@ const entryOf = (file, read, watch) => {
  * few visits read.
  */
 export const storySearchModule = async (root, patterns, watch, extract, isServing, pack, isKept = EVERY_FILE) => {
-    const files = indexedStoryFiles(root, patterns, watch, undefined, isKept);
+    // a file that cannot be indexed has nothing to find: the group's own module names it
+    const { files } = readStoryFiles(root, patterns, watch, undefined, isKept);
     const entries = await Promise.all(files.map(async (file) => ({ file, ...entryOf(file, await extract(file.file), watch) })));
     const problems = entries.flatMap(({ problem }) => problem ?? []);
     const index = {

package/dist/src/vite/searchRoute.js

@@ -1,5 +1,6 @@
-import { searchables, searchCatalogue } from "../search.js";
+import { searchables } from "../search.js";
 import { isSearchIndex, mergedSearchIndex } from "../searchIndex.js";
+import { correctedSearch } from "../searchTypos.js";
 import { sourceSearchLoaders } from "../sourceFiles.js";
 import { componentAddressOf, docPageAddressOf, storyAddressOf } from "../viewState.js";
 import { settled } from "./agentRoutes.js";
@@ -64,7 +65,7 @@ export const searchAnswer = async ({ tree, params, pages, view, loaded }) => {
         return { status: 400, body: { error: "No words to look for" } };
     const read = await Promise.all(loaded.sources.map(async (source) => ({ id: source.id, ...(await indexOf(source)) })));
     const indexes = new Map(read.map(({ id, index }) => [id, index]));
-    const answer = searchCatalogue(searchables(tree, indexes), query, {
+    const answer = correctedSearch(searchables(tree, indexes), query, {
         results: limitOf(params.get("limit")),
         hits: HITS
     });
@@ -73,6 +74,7 @@ export const searchAnswer = async ({ tree, params, pages, view, loaded }) => {
         query,
         total: answer.total,
         results: answer.results.map((result) => agentResult(result, pages, view)),
+        corrections: answer.corrections,
         problems: read.flatMap(({ index, problems }) => [...problems, ...(index.problems ?? [])])
     };
     return { status: 200, body };

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

@@ -0,0 +1,36 @@
+/**
+ * What a prop's value looks like, read from its type: the fields of an object, a list's items, the members of a mixed
+ * union, so the panel can draw them and a link's value can be checked against them.
+ *
+ * @remarks
+ * What JSON cannot hold (a function, a class's instance, a node) is a `named` part, which only the source's named values
+ * can fill: whether it offers some is known in the page. Types can be recursive and very wide (`CSSProperties`,
+ * `HTMLElement`), and every docs answer carries the shape, so a recursive part, a part too deep and a type too wide are
+ * `json`, typed by hand: the answer stays small, and the prop can still be set.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { ValueShape } from "../valueShape.ts";
+/** What reading a shape needs from the docs that ask. */
+export type ShapeReading = {
+    /** The program's checker. */
+    readonly checker: ts.TypeChecker;
+    /** Where the code names the component. */
+    readonly node: ts.Node;
+    /** A choice's values in the source's order; applied to the prop's own literals. */
+    readonly order: (values: readonly (string | number)[]) => readonly (string | number)[];
+    /** A member's type as the source writes it. */
+    readonly typeText: (member: ts.Symbol) => string | undefined;
+    /** A member's TSDoc. */
+    readonly description: (member: ts.Symbol) => string;
+};
+/**
+ * A prop's shape, when it says more than the prop's kind does.
+ *
+ * @param type - the prop's type, without `undefined` and `null`.
+ * @param canTakeText - whether it takes a plain text: its text field stays, rather than JSON for a type that says nothing.
+ * @param reading - what reading a shape needs.
+ * @returns the shape; none for a prop no JSON value can fill, whose named values the page looks up by its type.
+ */
+export declare const shapeOfProp: (type: ts.Type, canTakeText: boolean, reading: ShapeReading) => ValueShape | undefined;