forgebook 0.3.2 → 0.4.0

package/dist/src/vite/usageGraph.js

@@ -9,13 +9,15 @@
  * into its own JSX; a story without JSX renders its meta's component. A component is known by the file that declares
  * it and its name there, so two imports of one component are one. The import graph holds the modules the rendered
  * components reach through the package's own imports, never a dependency's (`node_modules`): "used through" follows
- * those edges. A lowercase tag is an element (`<div>`), not a component. A component reached only through code the
+ * those edges, by what each import names: a name taken through a barrel counts for the file that declares it, or every
+ * file a barrel lists would look used (`usageImports.ts`). A lowercase tag is an element (`<div>`), not a component. A component reached only through code the
  * checker cannot follow (a computed lazy import, a component handed in as a prop) is not found.
  *
  * @module
  */
 import ts from "typescript-6";
 import { configurationOf, programFor } from "./docsProgram.js";
+import { importsOf, textImportsOf } from "./usageImports.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /**
  * The symbol a name stands for, through its imports and re-exports.
@@ -169,53 +171,6 @@ const fileUsage = (request, program) => {
     });
     return { storyFile: request.storyFile, ...(component === undefined ? {} : { component }), stories };
 };
-/**
- * The package's own modules a module imports or re-exports from, resolved as its program resolves them.
- *
- * @param source - the module.
- * @param program - its program.
- * @param cache - the program's resolution cache.
- */
-/**
- * Whether an import or an export takes types only (`import type`, `export type`, `import { type A }`).
- *
- * @param statement - the statement.
- */
-const isTypeOnly = (statement) => {
-    if (ts.isExportDeclaration(statement))
-        return statement.isTypeOnly;
-    if (!ts.isImportDeclaration(statement))
-        return false;
-    const clause = statement.importClause;
-    if (clause === undefined)
-        return false;
-    if (clause.isTypeOnly)
-        return true;
-    // `import { type A, type B }`: every name a type, and no default
-    const bindings = clause.namedBindings;
-    return (clause.name === undefined &&
-        bindings !== undefined &&
-        ts.isNamedImports(bindings) &&
-        bindings.elements.length > 0 &&
-        bindings.elements.every((element) => element.isTypeOnly));
-};
-const importsOf = (source, program, cache) => {
-    const targets = [];
-    for (const statement of source.statements) {
-        const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) &&
-            statement.moduleSpecifier !== undefined &&
-            ts.isStringLiteral(statement.moduleSpecifier)
-            ? statement.moduleSpecifier.text
-            : undefined;
-        // a type renders nothing: a file that only takes types from another does not use its components
-        if (specifier === undefined || isTypeOnly(statement))
-            continue;
-        const resolved = ts.resolveModuleName(specifier, source.fileName, program.getCompilerOptions(), ts.sys, cache).resolvedModule;
-        if (resolved !== undefined && !resolved.isExternalLibraryImport)
-            targets.push(resolved.resolvedFileName);
-    }
-    return targets;
-};
 /**
  * The import graph of the modules the given files reach, through the package's own imports.
  *
@@ -236,8 +191,9 @@ const reachedImports = (starts, programs) => {
         const program = programs.find((candidate) => candidate.getSourceFile(file) !== undefined);
         const source = program?.getSourceFile(file);
         const cache = program === undefined ? undefined : caches.get(program);
+        // a style sheet or a single-file component is in no program, and it still imports what it draws with
         const targets = program === undefined || source === undefined || cache === undefined
-            ? []
+            ? textImportsOf(file, programs[0], programs[0] === undefined ? undefined : caches.get(programs[0]))
             : importsOf(source, program, cache);
         imports[file] = targets;
         queue.push(...targets);
@@ -245,7 +201,7 @@ const reachedImports = (starts, programs) => {
     return imports;
 };
 /**
- * The facts of the story files one configuration holds, read with that configuration's whole program.
+ * The facts of the story files one configuration holds, read with the program of what they all reach.
  *
  * @param group - the story files, in Vite's form, each held by the same configuration.
  * @returns the facts, or why a story file's program could not be read.
@@ -254,8 +210,8 @@ const groupGraph = (group) => {
     const files = [];
     const programs = new Set();
     for (const request of group) {
-        // what every story of the configuration reaches: its whole program, built once
-        const docsProgram = programFor(request.storyFile, { reach: "whole" });
+        // what every story of the configuration reaches, in one program built once
+        const docsProgram = programFor(request.storyFile, { reach: "stories" });
         if (typeof docsProgram === "string")
             return docsProgram;
         programs.add(docsProgram.program);
@@ -264,6 +220,8 @@ const groupGraph = (group) => {
             files.push(usage);
     }
     const starts = files.flatMap((file) => [
+        // what a story file imports itself runs with its stories: a single-file component, a sheet, a fixture
+        file.storyFile,
         ...(file.component === undefined ? [] : [file.component.file]),
         ...file.stories.flatMap((story) => story.renders.map((ref) => ref.file))
     ]);

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

@@ -1,10 +1,11 @@
 /**
  * When to use a component and when not, read from its TSDoc tags. Shared by the frameworks' docs modules: a framework
- * whose components have no symbol to carry a comment (a Vue single-file component) hands the tags it read itself.
+ * whose components have no symbol to carry a comment (a Vue single-file component) hands the tags it read itself. It holds
+ * only the compiler's types, so that what reads a whole project in a moment, from comments' text, does not load it.
  *
  * @module
  */
-import ts from "typescript-6";
+import type ts from "typescript-6";
 import type { UsageGuidance } from "../componentDocs.ts";
 /** One TSDoc tag, read. */
 export type DocTag = {
@@ -22,6 +23,12 @@ export type DocTag = {
 export declare const guidanceOfTags: (tags: readonly DocTag[]) => {
     readonly guidance?: UsageGuidance;
 };
+/**
+ * The tags of a documentation comment's text, each with the lines that follow it.
+ *
+ * @param comment - the comment, with or without its stars.
+ */
+export declare const tagsOfComment: (comment: string) => DocTag[];
 /**
  * The field of a component's docs saying when to use it and when not, from its symbol's TSDoc.
  *

package/dist/src/vite/usageGuidance.js

@@ -1,10 +1,5 @@
-/**
- * When to use a component and when not, read from its TSDoc tags. Shared by the frameworks' docs modules: a framework
- * whose components have no symbol to carry a comment (a Vue single-file component) hands the tags it read itself.
- *
- * @module
- */
-import ts from "typescript-6";
+/** A tag at a word's start. */
+const TAG = /(?:^|\s)@(\w+)/g;
 /**
  * The field of a component's docs saying when to use it and when not; none when its TSDoc says nothing, so most
  * components carry nothing.
@@ -33,6 +28,36 @@ export const guidanceOfTags = (tags) => {
     };
     return Object.keys(guidance).length === 0 ? {} : { guidance };
 };
+/** A comment's text without its fenced examples: what an example shows is not said of this component. */
+const withoutFences = (text) => {
+    const parts = text.split("```");
+    return parts.filter((_, index) => index % 2 === 0).join(" ");
+};
+/**
+ * The tags of a documentation comment's text, each with the lines that follow it.
+ *
+ * @param comment - the comment, with or without its stars.
+ */
+export const tagsOfComment = (comment) => {
+    const plain = comment
+        .split("\n")
+        .map((line) => {
+        const text = line.trimEnd();
+        const open = text.replace(/^\s*\/?\*+\/?\s?/, "");
+        return open.endsWith("*/") ? open.slice(0, -2) : open;
+    })
+        .join(" ");
+    const shown = withoutFences(plain);
+    const found = [...shown.matchAll(TAG)];
+    return found.map((match, index) => ({
+        name: match[1] ?? "",
+        text: shown
+            .slice(match.index + match[0].length, found[index + 1]?.index ?? shown.length)
+            .split(/\s+/)
+            .join(" ")
+            .trim()
+    }));
+};
 /**
  * The field of a component's docs saying when to use it and when not, from its symbol's TSDoc.
  *
@@ -41,5 +66,8 @@ export const guidanceOfTags = (tags) => {
  */
 export const guidanceOf = (symbol, checker) => guidanceOfTags(symbol.getJsDocTags(checker).map((tag) => ({
     name: tag.name,
-    text: ts.displayPartsToString(tag.text).trim()
+    text: (tag.text ?? [])
+        .map((part) => part.text)
+        .join("")
+        .trim()
 })));

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

@@ -0,0 +1,35 @@
+/**
+ * The edges of the import graph: what a module takes from the package's own modules, what a style sheet or a single-file
+ * component names in its text.
+ *
+ * @remarks
+ * An import counts for the file that declares each name it takes, not for the module it is written against: a barrel
+ * lists every component, so following it would make a story of one component reach all of them, and a new component
+ * would look verified for being exported. A name only an ambient declaration knows (a `.vue` shim) counts for the file its
+ * last re-export names, and a name from a dependency for nothing. A barrel is followed only for a namespace import or a
+ * side effect, and what it imports for its side effects (a global sheet) still runs when a name is taken through it. A
+ * module's own `export … from` stays an edge, for those cases. A relative import that resolves to nothing is kept as an edge to where it points: the file may
+ * have just been deleted, and the stories behind the edge are the ones that break. TypeScript does not resolve a style
+ * sheet or a single-file component, so their names are read from the text; an Angular component's `templateUrl` and
+ * `styleUrls` are found the same way.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/**
+ * The edges of a file no program holds, read from its text; a file that cannot be read has none.
+ *
+ * @param file - the file, absolute.
+ * @param program - a program whose rules resolve its imports.
+ * @param cache - that program's resolution cache.
+ */
+export declare const textImportsOf: (file: string, program: ts.Program | undefined, cache: ts.ModuleResolutionCache | undefined) => string[];
+/**
+ * The package's own modules a module imports or re-exports from, resolved as its program resolves them, with the assets
+ * and lazy modules its text names.
+ *
+ * @param source - the module.
+ * @param program - its program.
+ * @param cache - the program's resolution cache.
+ */
+export declare const importsOf: (source: ts.SourceFile, program: ts.Program, cache: ts.ModuleResolutionCache) => string[];

package/dist/src/vite/usageImports.js

@@ -0,0 +1,280 @@
+/**
+ * The edges of the import graph: what a module takes from the package's own modules, what a style sheet or a single-file
+ * component names in its text.
+ *
+ * @remarks
+ * An import counts for the file that declares each name it takes, not for the module it is written against: a barrel
+ * lists every component, so following it would make a story of one component reach all of them, and a new component
+ * would look verified for being exported. A name only an ambient declaration knows (a `.vue` shim) counts for the file its
+ * last re-export names, and a name from a dependency for nothing. A barrel is followed only for a namespace import or a
+ * side effect, and what it imports for its side effects (a global sheet) still runs when a name is taken through it. A
+ * module's own `export … from` stays an edge, for those cases. A relative import that resolves to nothing is kept as an edge to where it points: the file may
+ * have just been deleted, and the stories behind the edge are the ones that break. TypeScript does not resolve a style
+ * sheet or a single-file component, so their names are read from the text; an Angular component's `templateUrl` and
+ * `styleUrls` are found the same way.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { assetImports, sheetImports } from "./textImports.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A dynamic import of a path written out: a lazy component is drawn as any other. */
+const DYNAMIC_IMPORT = /\bimport\(\s*["'`]([^"'`\n$]+)["'`]\s*\)/g;
+/** A static import in the script of a single-file component, whose text no program holds. */
+const STATIC_IMPORT = /^[ \t]*(?:import|export)\s+(?:[^"';]{0,2000}?\sfrom\s+)?["']([^"']+)["']/gm;
+/** A file whose imports are read from its text. */
+const SINGLE_FILE_COMPONENT = /\.(?:vue|svelte|astro)$/;
+/** A style sheet. */
+const STYLE_SHEET = /\.(?:css|scss|sass|less)$/;
+/** The file system as each resolution cache's resolutions read it, remembered for the cache's life. */
+const HOSTS = new WeakMap();
+/**
+ * The file system a resolution reads, with what it asked remembered as long as its cache lives: resolving every import
+ * of a library asks again and again whether the same candidate files and folders exist, each time a call to the disk.
+ *
+ * @param cache - the resolution cache, made for one graph.
+ */
+const hostOf = (cache) => {
+    const known = HOSTS.get(cache);
+    if (known !== undefined)
+        return known;
+    const remembered = (read) => {
+        const answers = new Map();
+        return (path) => {
+            const answer = answers.get(path) ?? { value: read(path) };
+            answers.set(path, answer);
+            return answer.value;
+        };
+    };
+    const host = {
+        fileExists: remembered((path) => ts.sys.fileExists(path)),
+        readFile: remembered((path) => ts.sys.readFile(path)),
+        directoryExists: remembered((path) => ts.sys.directoryExists(path)),
+        realpath: remembered((path) => (ts.sys.realpath === undefined ? path : ts.sys.realpath(path))),
+        getCurrentDirectory: () => ts.sys.getCurrentDirectory(),
+        getDirectories: (path) => ts.sys.getDirectories(path)
+    };
+    HOSTS.set(cache, host);
+    return host;
+};
+/** Resolves a specifier as a program does, leaving out a dependency's files. */
+const resolverOf = (program, cache) => {
+    return (specifier, containing) => {
+        const resolved = ts.resolveModuleName(specifier, containing, program.getCompilerOptions(), hostOf(cache), cache).resolvedModule;
+        return resolved === undefined || resolved.isExternalLibraryImport ? undefined : resolved.resolvedFileName;
+    };
+};
+/** Where a path alias of the program's configuration sends a name TypeScript cannot resolve: a sheet, a `.vue` file. */
+const aliased = (specifier, options) => {
+    const configFile = options["configFilePath"];
+    const base = options.baseUrl ?? (typeof configFile === "string" ? VITE_PATHS.dirname(configFile) : undefined);
+    if (base === undefined)
+        return undefined;
+    for (const [pattern, targets] of Object.entries(options.paths ?? {})) {
+        const [prefix = "", suffix] = pattern.split("*");
+        const [target] = targets;
+        if (target === undefined || suffix === undefined)
+            continue;
+        if (specifier.startsWith(prefix) && specifier.endsWith(suffix))
+            return VITE_PATHS.resolve(base, target.split("*").join(specifier.slice(prefix.length, specifier.length - suffix.length)));
+    }
+    return undefined;
+};
+/** A specifier that resolves to nothing, as a path: where an alias sends it, or where a relative one points. */
+const unresolvedTarget = (specifier, file, options) => {
+    const name = specifier.split("?")[0] ?? specifier;
+    if (name.startsWith("."))
+        return VITE_PATHS.join(VITE_PATHS.dirname(file), name);
+    return aliased(name, options);
+};
+/** The specifiers matched in a text, resolved; a relative one that resolves to nothing kept as where it points. */
+const specifierTargets = (file, text, pattern, program, cache) => [...text.matchAll(pattern)].flatMap((match) => {
+    const specifier = match[1] ?? "";
+    const resolved = program === undefined || cache === undefined ? undefined : resolverOf(program, cache)(specifier, file);
+    if (resolved !== undefined)
+        return [resolved];
+    return [unresolvedTarget(specifier, file, program?.getCompilerOptions() ?? {}) ?? []].flat();
+});
+/**
+ * The edges of a file no program holds, read from its text; a file that cannot be read has none.
+ *
+ * @param file - the file, absolute.
+ * @param program - a program whose rules resolve its imports.
+ * @param cache - that program's resolution cache.
+ */
+export const textImportsOf = (file, program, cache) => {
+    const text = ts.sys.readFile(file);
+    if (text === undefined)
+        return [];
+    if (STYLE_SHEET.test(file))
+        return sheetImports(file, text);
+    if (!SINGLE_FILE_COMPONENT.test(file))
+        return [];
+    return [
+        ...new Set([
+            ...assetImports(file, text),
+            ...specifierTargets(file, text, STATIC_IMPORT, program, cache),
+            ...specifierTargets(file, text, DYNAMIC_IMPORT, program, cache)
+        ])
+    ];
+};
+/**
+ * Whether an import or an export takes types only (`import type`, `export type`, `import { type A }`).
+ *
+ * @param statement - the statement.
+ */
+const isTypeOnly = (statement) => {
+    if (ts.isExportDeclaration(statement))
+        return statement.isTypeOnly;
+    if (!ts.isImportDeclaration(statement))
+        return false;
+    const clause = statement.importClause;
+    if (clause === undefined)
+        return false;
+    if (clause.isTypeOnly)
+        return true;
+    // `import { type A, type B }`: every name a type, and no default
+    const bindings = clause.namedBindings;
+    return (clause.name === undefined &&
+        bindings !== undefined &&
+        ts.isNamedImports(bindings) &&
+        bindings.elements.length > 0 &&
+        bindings.elements.every((element) => element.isTypeOnly));
+};
+/** The import or export statement a declaration of a name belongs to, with its module's name. */
+const moduleOfDeclaration = (declaration) => {
+    let node = declaration;
+    while (node !== undefined && !ts.isSourceFile(node)) {
+        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+            node.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(node.moduleSpecifier))
+            return node.moduleSpecifier;
+        node = node.parent;
+    }
+    return undefined;
+};
+/**
+ * The file an ambiently declared name comes from: the module named by the last import or re-export on its way, which is
+ * the only place that says which `.vue` file it is.
+ *
+ * @param name - the imported name.
+ * @param checker - its program's checker.
+ * @param options - its program's options.
+ */
+const ambientOrigin = (name, checker, options) => {
+    let symbol = checker.getSymbolAtLocation(name);
+    let origin;
+    while (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+        const literal = moduleOfDeclaration(symbol.declarations?.[0]);
+        if (literal !== undefined)
+            origin = unresolvedTarget(literal.text, literal.getSourceFile().fileName, options) ?? origin;
+        symbol = checker.getImmediateAliasedSymbol(symbol);
+    }
+    return origin;
+};
+/**
+ * Where an imported name comes from: the file that declares it, nothing for a dependency's, or none when it cannot be told.
+ *
+ * @param name - the imported name.
+ * @param program - its program.
+ */
+const nameOrigin = (name, program) => {
+    const checker = program.getTypeChecker();
+    const symbol = checker.getSymbolAtLocation(name);
+    const target = symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias) !== 0
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    const declaring = target?.declarations?.[0]?.getSourceFile();
+    if (declaring !== undefined && program.isSourceFileFromExternalLibrary(declaring))
+        return null;
+    if (declaring !== undefined && !declaring.isDeclarationFile)
+        return declaring.fileName;
+    return ambientOrigin(name, checker, program.getCompilerOptions());
+};
+/**
+ * The files that declare the names an import takes, or none when that cannot be told: a side effect, a namespace, a name
+ * with no known origin.
+ *
+ * @param statement - the import.
+ * @param program - its program.
+ */
+const declaringFiles = (statement, program) => {
+    if (!ts.isImportDeclaration(statement))
+        return undefined;
+    const clause = statement.importClause;
+    const bindings = clause?.namedBindings;
+    if (clause === undefined || (bindings !== undefined && ts.isNamespaceImport(bindings)))
+        return undefined;
+    const names = [
+        ...(clause.name === undefined ? [] : [clause.name]),
+        ...(bindings === undefined || !ts.isNamedImports(bindings)
+            ? []
+            : bindings.elements.filter((element) => !element.isTypeOnly).map((element) => element.name))
+    ];
+    const found = names.map((name) => nameOrigin(name, program));
+    return found.includes(undefined) ? undefined : found.flatMap((file) => file ?? []);
+};
+/** The module a statement names, when it is an import or a re-export that takes more than types. */
+const moduleNamed = (statement) => {
+    if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement))
+        return undefined;
+    const literal = statement.moduleSpecifier;
+    // a type renders nothing: a file that only takes types from another does not use its components
+    if (literal === undefined || !ts.isStringLiteral(literal) || isTypeOnly(statement))
+        return undefined;
+    return literal.text;
+};
+/**
+ * What a module imports for its side effects alone: it runs whichever name is taken through it.
+ *
+ * @param file - the module, absolute.
+ * @param reading - its program.
+ */
+const sideEffectTargets = (file, { program, cache }) => {
+    const source = program.getSourceFile(file);
+    if (source === undefined)
+        return [];
+    return source.statements.flatMap((statement) => ts.isImportDeclaration(statement) && statement.importClause === undefined
+        ? statementTargets(statement, { source, program, cache })
+        : []);
+};
+/**
+ * The files a statement of a module takes.
+ *
+ * @param statement - the statement.
+ * @param reading - its module and program.
+ */
+const statementTargets = (statement, reading) => {
+    const { source, program, cache } = reading;
+    const specifier = moduleNamed(statement);
+    if (specifier === undefined)
+        return [];
+    const options = program.getCompilerOptions();
+    const resolved = ts.resolveModuleName(specifier, source.fileName, options, hostOf(cache), cache).resolvedModule;
+    if (resolved === undefined)
+        return [unresolvedTarget(specifier, source.fileName, options) ?? []].flat();
+    if (resolved.isExternalLibraryImport)
+        return [];
+    const declaring = declaringFiles(statement, program);
+    if (declaring === undefined)
+        return [resolved.resolvedFileName];
+    const through = declaring.includes(resolved.resolvedFileName)
+        ? []
+        : sideEffectTargets(resolved.resolvedFileName, reading);
+    return [...declaring, ...through];
+};
+/**
+ * The package's own modules a module imports or re-exports from, resolved as its program resolves them, with the assets
+ * and lazy modules its text names.
+ *
+ * @param source - the module.
+ * @param program - its program.
+ * @param cache - the program's resolution cache.
+ */
+export const importsOf = (source, program, cache) => [
+    ...new Set([
+        ...source.statements.flatMap((statement) => statementTargets(statement, { source, program, cache })),
+        ...assetImports(source.fileName, source.text),
+        ...specifierTargets(source.fileName, source.text, DYNAMIC_IMPORT, program, cache)
+    ])
+];

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

@@ -0,0 +1,16 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+import { type PublishedFile } from "./publishedExports.ts";
+/**
+ * The published files a change holds to the check: those it edits, and those it starts publishing or names anew.
+ *
+ * @param now - what is published now.
+ * @param changed - the files it changes, in the catalogue's form.
+ * @param readBefore - what the change's start published; read only when an entry or a barrel changed.
+ */
+export declare const filesOfChange: (now: readonly PublishedFile[], changed: readonly string[], readBefore: () => Promise<readonly PublishedFile[]>) => Promise<readonly PublishedFile[]>;
+/**
+ * What agents cannot see.
+ *
+ * @param context - what the routes read.
+ */
+export declare const visibilityAnswer: (context: RouteContext) => Promise<AgentAnswer>;