forgebook 0.1.7 → 0.2.0

package/dist/src/vite/docsDependencies.js

@@ -0,0 +1,150 @@
+/**
+ * The paths a story file's docs can change with, so a kept answer (`diskCache.ts`) is reused only while they are
+ * unchanged: what the story file reaches through its imports, type imports and `import()` types included, and the
+ * folders those sit in (a file added there may be what an import now finds); the files its imports name that
+ * TypeScript does not read (a `.svelte` or `.vue` component), read for their own imports too; the manifest of each
+ * installed package it imports, and the lock file, which every installed type hangs on; and the configurations that
+ * decided how it is read.
+ *
+ * @remarks
+ * Run in the docs' worker, after the docs were read. The imports are found as TypeScript's own pre-pass finds them
+ * (`preProcessFile`), so an import only a type uses still counts, and resolved with the options the file is read with
+ * (`compilerOptionsFor`), without a program of their own. A package of the workspace, which an install links into
+ * `node_modules`, is followed into its sources: its real path is outside `node_modules`. A group's story files share one
+ * walk, so "Used in" reads each file once.
+ *
+ * @module
+ */
+import { dirname, isAbsolute, resolve } from "node:path";
+import ts from "typescript-6";
+import { compilerOptionsFor, configurationFiles } from "./docsProgram.js";
+/** The files a package manager rewrites when it installs. */
+const LOCK_FILES = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"];
+/** Whether a path is inside a `node_modules` folder. */
+const isInstalled = (path) => path.replaceAll("\\", "/").includes("/node_modules/");
+/** The text after `*` of a `paths` pattern that matches a specifier, or none. */
+const matchedStar = (pattern, specifier) => {
+    const star = pattern.indexOf("*");
+    if (star < 0)
+        return pattern === specifier ? "" : undefined;
+    const [before, after] = [pattern.slice(0, star), pattern.slice(star + 1)];
+    return specifier.startsWith(before) &&
+        specifier.endsWith(after) &&
+        specifier.length >= before.length + after.length
+        ? specifier.slice(before.length, specifier.length - after.length)
+        : undefined;
+};
+/**
+ * Where a specifier TypeScript could not resolve points through the configuration's `paths` (`@/Button.vue`), as the
+ * first candidate that exists: a framework's component file, which TypeScript does not read.
+ *
+ * @param specifier - the import's specifier.
+ * @param options - the compiler options.
+ */
+const mappedPath = (specifier, options) => {
+    const base = options["pathsBasePath"];
+    const folder = typeof base === "string" ? base : options.baseUrl;
+    if (folder === undefined)
+        return undefined;
+    for (const [pattern, targets] of Object.entries(options.paths ?? {})) {
+        const star = matchedStar(pattern, specifier);
+        if (star === undefined)
+            continue;
+        for (const target of targets) {
+            const candidate = resolve(folder, target.replaceAll("*", star));
+            if (ts.sys.fileExists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+};
+/** The manifest of the installed package a file belongs to. */
+const manifestOf = (file) => ts.findConfigFile(dirname(file), ts.sys.fileExists, "package.json");
+/**
+ * Where an import points: what TypeScript resolves it to, else the path a relative import names, else where the
+ * configuration's `paths` lead it; none for a package TypeScript cannot find.
+ *
+ * @param specifier - the import's specifier.
+ * @param file - the importing file.
+ * @param options - the compiler options it is read with.
+ * @param cache - the module resolution cache of the walk.
+ */
+const importTarget = (specifier, file, options, cache) => {
+    const resolved = ts.resolveModuleName(specifier, file, options, ts.sys, cache).resolvedModule;
+    if (resolved !== undefined)
+        return resolved.resolvedFileName;
+    return specifier.startsWith(".") ? resolve(dirname(file), specifier) : mappedPath(specifier, options);
+};
+/**
+ * What one file names: its imports resolved outside `node_modules` (followed), its installed packages' manifests, the
+ * files TypeScript does not read (followed for their own imports), the missing ones as paths, and the files its
+ * `/// <reference path>` names.
+ *
+ * @param file - the file.
+ * @param options - the compiler options it is read with.
+ * @param cache - the module resolution cache of the walk.
+ */
+const namedBy = (file, options, cache) => {
+    const text = ts.sys.readFile(file);
+    if (text === undefined)
+        return { followed: [], named: [] };
+    const { importedFiles, referencedFiles } = ts.preProcessFile(text, true, true);
+    const targets = importedFiles.flatMap(({ fileName }) => importTarget(fileName, file, options, cache) ?? []);
+    const installed = targets.filter(isInstalled);
+    const own = targets.filter((target) => !isInstalled(target));
+    const references = referencedFiles
+        .map(({ fileName }) => (isAbsolute(fileName) ? fileName : resolve(dirname(file), fileName)))
+        .filter((path) => !isInstalled(path));
+    return {
+        followed: [...own.filter((target) => ts.sys.fileExists(target)), ...references],
+        named: [
+            ...installed.flatMap((target) => manifestOf(target) ?? []),
+            ...own.filter((target) => !ts.sys.fileExists(target))
+        ]
+    };
+};
+/**
+ * Adds to `paths` what one story file reaches, with the folders the reached files sit in.
+ *
+ * @param storyFile - the story file.
+ * @param walk - the walk's options, cache, files already read and paths found.
+ */
+const walkFrom = (storyFile, walk) => {
+    const queue = [storyFile];
+    while (queue.length > 0) {
+        const file = queue.pop() ?? "";
+        if (walk.reached.has(file))
+            continue;
+        walk.reached.add(file);
+        // in the system's form, so one path read through two spellings is stamped once
+        walk.paths.add(resolve(file));
+        walk.paths.add(resolve(dirname(file)));
+        // a framework's component file is read for its imports too, as plain text
+        const { followed, named } = namedBy(file, walk.options, walk.cache);
+        queue.push(...followed);
+        for (const path of named)
+            walk.paths.add(resolve(path));
+    }
+};
+/**
+ * The paths a group of story files' docs can change with, read in one walk.
+ *
+ * @param storyFiles - the story files.
+ */
+export const docsDependencies = (storyFiles) => {
+    const paths = new Set();
+    const reached = new Set();
+    const caches = new Map();
+    for (const storyFile of storyFiles) {
+        const options = compilerOptionsFor(storyFile);
+        const cache = caches.get(options) ?? ts.createModuleResolutionCache(dirname(storyFile), (name) => name, options);
+        caches.set(options, cache);
+        walkFrom(storyFile, { options, cache, reached, paths });
+        for (const path of configurationFiles(storyFile))
+            paths.add(path);
+        const locks = LOCK_FILES.flatMap((name) => ts.findConfigFile(dirname(storyFile), ts.sys.fileExists, name) ?? []);
+        for (const lock of locks)
+            paths.add(lock);
+    }
+    return [...paths];
+};

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

@@ -1,4 +1,5 @@
 import type { StoryComponentResult } from "./adapter.ts";
+import { type PathStamp } from "./diskCache.ts";
 import type { UsageGraph, UsageRequestFile } from "./usageGraph.ts";
 /** What the extractor answers for a story file: its component's docs, none, or why it cannot be read. */
 export type DocsResult = StoryComponentResult;
@@ -34,6 +35,11 @@ export type DocsResponse = {
     readonly id: number;
     /** The extractor's result. */
     readonly result: DocsResult;
+    /**
+     * The paths it can change with, stamped (`docsDependencies.ts`); none when it is not to be kept: a story file
+     * that cannot be read, or one of them changed while it was read.
+     */
+    readonly stamps: readonly PathStamp[] | undefined;
 } | {
     /** A group of story files' usage. */
     readonly kind: "usage";
@@ -41,6 +47,8 @@ export type DocsResponse = {
     readonly id: number;
     /** The facts, or why they cannot be read. */
     readonly result: UsageResult;
+    /** The paths they can change with, stamped; none when they are not to be kept. */
+    readonly stamps: readonly PathStamp[] | undefined;
 };
 /** The docs, read off the dev server's thread. */
 export type DocsExtractor = {
@@ -48,10 +56,18 @@ export type DocsExtractor = {
     readonly extract: (storyFile: string) => Promise<DocsResult>;
     /** What a group of story files' stories render, and the import graph they reach. */
     readonly usage: (files: readonly UsageRequestFile[]) => Promise<UsageResult>;
-    /** Builds the program that holds a story file, ahead of its first read. */
+    /**
+     * Builds the program that holds a story file ahead of its first read, while the worker has nothing else to do, when
+     * the disk keeps no docs: a first start, or a build, starts the worker while Vite still loads the pages.
+     */
     readonly warm: (storyFile: string) => void;
     /** Tells the worker a source file changed, so the next read sees it. */
     readonly changed: () => void;
+    /**
+     * Tells it a source file was added or removed: a kept answer is not read again this session, since a new file can
+     * change what a file's imports find or what holds for every file (a declaration) without touching what it read.
+     */
+    readonly listed: () => void;
     /** Ends the worker; a later request starts a new one. */
     readonly close: () => Promise<void>;
 };
@@ -59,12 +75,37 @@ export type DocsExtractor = {
 export type DocsWorkerData = {
     /** The URL of the module exporting the framework's `extractStoryComponent`. */
     readonly docsModule: string;
+    /**
+     * Whether every story's docs will be read, as in a build: each program then holds its whole configuration at once,
+     * rather than what was asked for so far, which a dev server showing one component at a time needs.
+     */
+    readonly readsEverything: boolean;
+    /** Whether its answers are kept on disk, so it stamps what each was read from; a build's are not. */
+    readonly keepsAnswers: boolean;
 };
+/** How an extractor reads. */
+export type DocsExtractorOptions = {
+    /** Whether every story's docs will be read, as in a build; a dev server's reads by default. */
+    readonly readsEverything?: boolean;
+    /** Where answers are kept between starts (`diskCache.ts`); none reads every time. */
+    readonly cacheFolder?: string;
+    /**
+     * How long the worker stays with nothing to do before it ends, in milliseconds; `IDLE_MS` by default. A build's
+     * never ends before the build does.
+     */
+    readonly idleMs?: number;
+};
+/**
+ * How long a dev server's worker stays with nothing to do, in milliseconds, before it ends. Its programs are the
+ * largest thing the server holds: a session that stops reading docs gives their memory back, while one that edits and
+ * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
+ */
+export declare const IDLE_MS: number;
 /**
  * A docs extractor with its worker, started on its first request.
  *
  * @param docsModule - the URL of the framework's docs module (`FrameworkAdapter.docsModule`).
+ * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export declare const createDocsExtractor: (docsModule: string) => DocsExtractor;
-//# sourceMappingURL=docsExtractor.d.ts.map
+export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs }?: DocsExtractorOptions) => DocsExtractor;

package/dist/src/vite/docsExtractor.js

@@ -3,52 +3,139 @@
  * (`docsWorker.ts`) so the dev server keeps answering while a package's TypeScript program is built.
  *
  * @remarks
- * One worker per plugin, started on the first request and kept: its programs make every later read quick, until a
- * source file changes (`changed`, which the dev server's watcher sends). Requests
- * are answered in order; a warm-up (`warm`) builds a package's program before a page asks for it, one at a time and
- * only while the worker has nothing else to do, so a page's request waits behind one warm-up at most, never behind
- * them all. The worker never keeps the process alive (`unref`), and `close` ends it when the build or the server
- * ends.
+ * One worker per plugin, started on the first request the disk cannot answer: its programs make every later read
+ * quick, until a source file changes (`changed`, which the dev server's watcher sends). A TypeScript program is the
+ * largest thing the server holds, and an answer kept on disk from an earlier start (`diskCache.ts`, with the files it
+ * was read from, `docsDependencies.ts`) needs none: a pattern's first story starts the worker early (`warm`) only when
+ * the disk keeps no docs at all (a first start, a build), one warm-up at a time and only while nothing waits. For the
+ * same reason a dev server's worker left with nothing to do ends (`IDLE_MS`), so the memory a first start took does
+ * not stay with the server until it stops. Requests are answered in order. The worker never keeps the process alive
+ * (`unref`), and `close` ends it when the build or the server ends.
  *
  * @module
  */
-import { extname } from "node:path";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
+import { packageResolver } from "./configFile.js";
+import { codeStamp, diskCache } from "./diskCache.js";
 /**
  * The worker's module, beside this one and with its extension: `.ts` in the sources, whose types Node strips, `.js`
  * once built for npm, where Node strips none.
  */
 const WORKER_URL = new URL(`./docsWorker${extname(import.meta.url)}`, import.meta.url);
+/** Whether what a cache file holds is a story file's docs, never a message. */
+const isKeptDocs = (value) => typeof value === "object" && value !== null && "docs" in value;
+/** Whether what a cache file holds is a group's usage, never a message. */
+const isKeptUsage = (value) => typeof value === "object" && value !== null && "files" in value && "imports" in value;
+/**
+ * The worker's young generation on a dev server, in MB. V8 sizes it for throughput, but a program's heap survives
+ * its collections, so a large young generation is mostly empty memory the worker keeps; a dev server reads one
+ * component at a time, where collecting more often costs little.
+ */
+const YOUNG_GENERATION_MB = 8;
+/**
+ * How long a dev server's worker stays with nothing to do, in milliseconds, before it ends. Its programs are the
+ * largest thing the server holds: a session that stops reading docs gives their memory back, while one that edits and
+ * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
+ */
+export const IDLE_MS = 5 * 60_000;
+/**
+ * The worker's young generation in a build, in MB: a build reads every story's docs in one go, and with the dev
+ * server's small one it would spend much of that time collecting garbage.
+ */
+const BUILD_YOUNG_GENERATION_MB = 64;
+/**
+ * The stamp of the code that reads the docs: the worker's folder, the framework's docs module's and the compiler's
+ * version; none when the module is not a file whose folder can be read, which keeps nothing.
+ *
+ * @param docsModule - the URL of the framework's docs module.
+ */
+const codeStampOf = (docsModule) => {
+    try {
+        const workerFolder = dirname(fileURLToPath(WORKER_URL));
+        // the compiler's version too: it reads every answer
+        const compiler = packageResolver(workerFolder)("typescript-6");
+        return codeStamp([workerFolder, dirname(fileURLToPath(docsModule))], compiler === undefined ? [] : [compiler]);
+    }
+    catch {
+        return undefined;
+    }
+};
 /**
  * A docs extractor with its worker, started on its first request.
  *
  * @param docsModule - the URL of the framework's docs module (`FrameworkAdapter.docsModule`).
+ * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export const createDocsExtractor = (docsModule) => {
+export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS } = {}) => {
+    // the code that writes the answers: this package's and the framework's docs, whose edit or new version is a miss
+    const code = cacheFolder === undefined ? undefined : codeStampOf(docsModule);
+    const cacheOf = (kind, isValue) => cacheFolder === undefined || code === undefined
+        ? undefined
+        : diskCache(join(cacheFolder, kind), code, isValue);
+    const docsCache = cacheOf("docs", isKeptDocs);
+    const usageCache = cacheOf("usage", isKeptUsage);
     let worker;
     let nextId = 0;
-    // every request sent and not answered yet, a warm-up's answer included (none reads it)
+    // the changes the watcher reported: an answer read across one may have read a file before it changed, so it is not kept
+    let changes = 0;
+    // whether kept answers are read: until a source file is added or removed while the server runs
+    let isKeptRead = true;
+    // a group's usage asked again before the worker answered (its "Used in" and its reach), by request and changes
+    const usageAsked = new Map();
+    // every request sent and not answered yet, a warm-up's included (none reads its answer)
     const pending = new Map();
-    // the warm-ups not sent yet: one goes out only when nothing is pending
+    // the warm-ups not sent yet: one goes out only when nothing is pending, so a read never waits behind them all
     const warmUps = [];
+    let idle;
+    // ends the worker once nothing is asked of it for a while; a request in the meantime keeps it
+    const stopWhenIdle = () => {
+        clearTimeout(idle);
+        // a build reads every story, and a quiet stretch in it would build every program again
+        if (readsEverything || pending.size > 0 || warmUps.length > 0)
+            return;
+        idle = setTimeout(() => {
+            const running = worker;
+            worker = undefined;
+            void running?.terminate();
+        }, idleMs);
+        idle.unref();
+    };
+    const sendWarmUp = () => {
+        if (pending.size > 0)
+            return;
+        const storyFile = warmUps.shift();
+        if (storyFile !== undefined)
+            send({ kind: "extract", id: nextId++, storyFile }, () => sendWarmUp());
+    };
     const started = () => {
+        clearTimeout(idle);
         if (worker !== undefined)
             return worker;
-        const workerData = { docsModule };
-        const created = new Worker(WORKER_URL, { workerData });
+        const workerData = { docsModule, readsEverything, keepsAnswers: code !== undefined };
+        const created = new Worker(WORKER_URL, {
+            workerData,
+            resourceLimits: {
+                maxYoungGenerationSizeMb: readsEverything ? BUILD_YOUNG_GENERATION_MB : YOUNG_GENERATION_MB
+            }
+        });
         created.unref();
         created.on("message", (response) => {
             pending.get(response.id)?.(response);
             pending.delete(response.id);
             sendWarmUp();
+            stopWhenIdle();
         });
         // a worker that dies answers every request still waiting with why, and the next request starts a new one
         created.on("error", (error) => {
             for (const resolve of pending.values())
                 resolve(`The docs' worker stopped: ${error.message}`);
             pending.clear();
-            worker = undefined;
+            // a worker ended when idle and replaced since leaves the new one in place
+            if (worker === created)
+                worker = undefined;
         });
         worker = created;
         return created;
@@ -60,27 +147,75 @@ export const createDocsExtractor = (docsModule) => {
         pending.set(request.id, resolve);
         started().postMessage(request);
     };
-    const extract = (storyFile, resolve) => send({ kind: "extract", id: nextId++, storyFile }, (response) => resolve(typeof response === "string" || response.kind !== "extract" ? String(response) : response.result));
-    const sendWarmUp = () => {
-        if (pending.size > 0)
-            return;
-        const storyFile = warmUps.shift();
-        if (storyFile !== undefined)
-            extract(storyFile, () => undefined);
-    };
     return {
-        extract: (storyFile) => new Promise((resolve) => extract(storyFile, resolve)),
-        usage: (files) => new Promise((resolve) => send({ kind: "usage", id: nextId++, files }, (response) => resolve(typeof response === "string" || response.kind !== "usage" ? String(response) : response.result))),
+        extract: (storyFile) => new Promise((resolve) => {
+            const kept = isKeptRead ? docsCache?.read(storyFile) : undefined;
+            if (kept !== undefined) {
+                resolve(kept);
+                return;
+            }
+            const asked = changes;
+            send({ kind: "extract", id: nextId++, storyFile }, (response) => {
+                if (typeof response === "string" || response.kind !== "extract") {
+                    resolve(String(response));
+                    return;
+                }
+                const { result, stamps } = response;
+                if (typeof result !== "string" && stamps !== undefined && changes === asked)
+                    docsCache?.write(storyFile, result, stamps);
+                resolve(result);
+            });
+        }),
+        usage: (files) => {
+            // a group is its story files and what each renders: the same files with other stories are another group
+            const key = JSON.stringify(files);
+            const asked = changes;
+            const pending = usageAsked.get(`${asked}:${key}`);
+            if (pending !== undefined)
+                return pending;
+            const read = new Promise((resolve) => {
+                const kept = isKeptRead ? usageCache?.read(key) : undefined;
+                if (kept !== undefined) {
+                    resolve(kept);
+                    return;
+                }
+                send({ kind: "usage", id: nextId++, files }, (response) => {
+                    if (typeof response === "string" || response.kind !== "usage") {
+                        resolve(String(response));
+                        return;
+                    }
+                    const { result, stamps } = response;
+                    if (typeof result !== "string" && stamps !== undefined && changes === asked)
+                        usageCache?.write(key, result, stamps);
+                    resolve(result);
+                });
+            });
+            usageAsked.set(`${asked}:${key}`, read);
+            void read.finally(() => usageAsked.delete(`${asked}:${key}`));
+            return read;
+        },
+        changed: () => {
+            changes += 1;
+            // a worker not started yet has no program to renew
+            const request = { kind: "changed" };
+            worker?.postMessage(request);
+        },
         warm: (storyFile) => {
+            // only a first start, which the disk can answer nothing for: a later one reads each page's docs from the disk
+            // and builds a program only for one it misses, so it stays without one until then
+            if (isKeptRead && docsCache !== undefined && !docsCache.isEmpty())
+                return;
             warmUps.push(storyFile);
             sendWarmUp();
         },
-        changed: () => {
-            // a worker not started yet has no program to renew
+        listed: () => {
+            isKeptRead = false;
+            changes += 1;
             const request = { kind: "changed" };
             worker?.postMessage(request);
         },
         close: async () => {
+            clearTimeout(idle);
             const running = worker;
             worker = undefined;
             warmUps.length = 0;
@@ -88,4 +223,3 @@ export const createDocsExtractor = (docsModule) => {
         }
     };
 };
-//# sourceMappingURL=docsExtractor.js.map

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

@@ -6,16 +6,86 @@ export type DocsProgram = {
     /** Its type checker. */
     readonly checker: ts.TypeChecker;
 };
+/**
+ * What TypeScript reads in place of files it cannot read itself: a framework's components, each written as the
+ * TypeScript it amounts to, under a name beside the component (`Badge.svelte.ts` for `Badge.svelte`), so an import of the
+ * component resolves to it as TypeScript resolves any import.
+ */
+export type ProgramSources = {
+    /** The sources' name, which keeps their programs apart from the plain ones (`svelte`). */
+    readonly name: string;
+    /**
+     * The text of a file that is not on disk.
+     *
+     * @param fileName - the file TypeScript asks for.
+     * @returns its text, or none for a file read from disk.
+     */
+    readonly textOf: (fileName: string) => string | undefined;
+    /** The declarations every program holds besides its sources, which the written text refers to. */
+    readonly roots: readonly string[];
+    /** Compiler options over the configuration's (JavaScript allowed, for components written without TypeScript). */
+    readonly options: ts.CompilerOptions;
+};
+/**
+ * How many programs are kept. A program holds all its package reaches, hundreds of megabytes in a monorepo whose
+ * `tsconfig` paths lead to every package's sources, and one is made per `tsconfig.json`: kept without a limit they fill
+ * the worker's heap, it stops, and every story still waiting gets that error instead of its docs. Making one again
+ * takes a second or so, which is the cheaper of the two.
+ */
+export declare const KEPT_PROGRAMS = 4;
+/**
+ * From now on a program holds what was asked for and what that imports, not its whole configuration: a dev server shows
+ * one component at a time. A reader of everything asks for it (`programFor`'s `reach`).
+ */
+export declare const readAskedFilesOnly: () => void;
+/** What a program is read for: what the asked file reaches, or every file of its configuration. */
+export type ProgramReach = "asked" | "whole";
+/** How a file's program is read. */
+export type ProgramOptions = {
+    /** The files read in place of a framework's components; none for a plain program. */
+    readonly sources?: ProgramSources;
+    /**
+     * What the reader needs: what the file reaches (a component's docs, the default), or every file of its
+     * configuration (a group's "Used in"); either way a build's programs hold every file.
+     */
+    readonly reach?: ProgramReach;
+};
 /** Marks every program as maybe holding an edited file: each is renewed on its next read. */
 export declare const markSourcesChanged: () => void;
 /**
- * The program that holds a file: the one of the nearest `tsconfig.json` up its folders, or, when none holds it, a
- * program of the file alone (`FALLBACK_OPTIONS`, or the configuration's with JavaScript allowed).
+ * The files besides a source's own imports that what is read of it can change with: every configuration looked at to
+ * find the one that holds it (up its folders, with the projects they reference) and those they extend, and the files
+ * that hold for every file of that configuration (its declarations, its augmentations). Kept answers are checked
+ * against them (`diskCache.ts`).
+ *
+ * @param file - an absolute path to a source file.
+ */
+export declare const configurationFiles: (file: string) => string[];
+/**
+ * The compiler options a file is read with, as `programFor` finds its configuration, without making a program: its
+ * imports resolve with them.
  *
  * @param file - an absolute path to a source file.
+ */
+export declare const compilerOptionsFor: (file: string) => ts.CompilerOptions;
+/**
+ * The program that holds a file: the one of the first configuration up its folders (or a project it references) that
+ * lists it; else the nearest one's, when the file reaches it through an import; else the one the files no
+ * configuration holds share (`FALLBACK_OPTIONS`, or the nearest configuration's with JavaScript allowed).
+ *
+ * @param file - an absolute path to a source file, or to a file the sources write.
+ * @param options - the sources a framework writes, and what the reader needs.
  * @returns the program, or a message when the configuration above it cannot be read.
  */
-export declare const programFor: (file: string) => DocsProgram | string;
+export declare const programFor: (file: string, { sources, reach }?: ProgramOptions) => DocsProgram | string;
+/**
+ * The configuration that holds a file, as `programFor` finds it; empty for a file none holds: what "Used in" groups a
+ * library's story files by, to read one configuration at a time.
+ *
+ * @internal
+ * @param file - an absolute path to a source file.
+ */
+export declare const configurationOf: (file: string) => string;
 /**
  * The first paragraph of a symbol's TSDoc.
  *
@@ -24,13 +94,13 @@ export declare const programFor: (file: string) => DocsProgram | string;
  */
 export declare const summaryOf: (symbol: ts.Symbol, checker: ts.TypeChecker) => string;
 /**
- * The first paragraph of a file's leading comment, its `@module` TSDoc: what the file holds, in a sentence. A
- * component's own TSDoc is often a bare name ("A button."); its file's comment says what it is and does.
+ * Each of a TSDoc tag's texts, for a tag that can be written more than once.
  *
- * @param sourceFile - the file.
- * @returns the paragraph on one line, or an empty text when the file does not open with a `@module` comment.
+ * @param symbol - a declared symbol.
+ * @param checker - the program's type checker.
+ * @param name - the tag (`useWhen`).
  */
-export declare const moduleSummaryOf: (sourceFile: ts.SourceFile) => string;
+export declare const tagsOf: (symbol: ts.Symbol, checker: ts.TypeChecker, name: string) => string[];
 /**
  * A TSDoc tag's text, without the backticks it is often written in.
  *
@@ -39,4 +109,14 @@ export declare const moduleSummaryOf: (sourceFile: ts.SourceFile) => string;
  * @param name - the tag (`defaultValue`).
  */
 export declare const tagOf: (symbol: ts.Symbol, checker: ts.TypeChecker, name: string) => string | undefined;
-//# sourceMappingURL=docsProgram.d.ts.map
+/**
+ * The component asked for among a file's: the one named, or the only one.
+ *
+ * @param components - the names of the components the file exports.
+ * @param exportName - the export asked for; the file's only component when none.
+ * @param file - the file, for the message.
+ * @returns the name, or a message naming the components when there is none or several.
+ */
+export declare const chosenExport: (components: readonly string[], exportName: string | undefined, file: string) => string | {
+    readonly problem: string;
+};