forgebook 0.3.3 → 0.4.1

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>;

package/dist/src/vite/visibilityRoute.js

@@ -0,0 +1,320 @@
+/**
+ * The answer to `visibility`: the published components of the repository's packages an agent cannot see, every one, or
+ * with `since` those a change touches or newly publishes.
+ *
+ * @remarks
+ * The change is held to it, and not the whole repository: a project adopting the gate would otherwise fail on all it has,
+ * and turn it off. A name a barrel starts exporting counts as a change of that component, though its own file did not
+ * move, since that is the moment it reaches everyone. What cannot be told is said, and never reads as nothing unseen: with
+ * no import graph every component would look storyless, so none is judged.
+ *
+ * @module
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { offersUsedIn, readsComponentDocs } from "../catalogue.js";
+import { isComponentDocs } from "../componentDocs.js";
+import { printable } from "../printable.js";
+import { sourceFiles } from "../sourceFiles.js";
+import { settled } from "./agentRoutes.js";
+import { unseenComponent } from "./agentVisibility.js";
+import { belongsToOtherCatalogue } from "./changeCoverage.js";
+import { identifiedStories } from "./changedRoute.js";
+import { findConfigFile } from "./configFile.js";
+import { catalogueChangedFiles, changeBase, changedFiles, gitOutput, noBaseReason } from "./gitChange.js";
+import { isPublished, packageEntries } from "./packageEntries.js";
+import { publishedComponents } from "./publishedExports.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The extensions an import may leave out, in the order a bundler tries them. */
+const RESOLVED_EXTENSIONS = [".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs", ".vue", ".svelte"];
+/** A package that is a project's sample, published or not: nobody looks for its components. */
+const NOT_A_LIBRARY = /(?:^|\/)(?:examples?|fixtures?|__fixtures__|e2e|tests?|__tests__|templates?|docs?)\//;
+/** The largest file read: a generated bundle says nothing here, and a hostile one must not hold the server. */
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+/** The most files a pattern's folder is walked for. */
+const MAX_WALKED = 20_000;
+/** A folder's entries; none when it cannot be read. */
+const entriesOf = (folder) => {
+    try {
+        return readdirSync(folder, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Every file under a folder, walked by hand: a recursive listing follows links in circles and goes through `node_modules`.
+ *
+ * @param folder - the folder.
+ */
+const filesUnder = (folder) => {
+    const files = [];
+    const pending = [folder];
+    while (pending.length > 0 && files.length < MAX_WALKED) {
+        const current = pending.pop() ?? "";
+        for (const entry of entriesOf(current)) {
+            const path = VITE_PATHS.join(current, entry.name);
+            const isWalked = entry.isDirectory() && entry.name !== "node_modules" && !entry.name.startsWith(".");
+            if (entry.isFile())
+                files.push(path);
+            else if (isWalked)
+                pending.push(path);
+        }
+    }
+    return files;
+};
+/**
+ * A file's text, and nothing outside the repository: a manifest or an import names what the branch likes, and a link may
+ * lead anywhere, so only a regular file under the repository's real folder is read.
+ *
+ * @param root - the repository's real folder.
+ * @param file - the file.
+ */
+const textIn = (root, file) => {
+    try {
+        const real = VITE_PATHS.normalize(realpathSync(file));
+        if (!real.startsWith(`${root}/`))
+            return undefined;
+        const stats = statSync(real);
+        return stats.isFile() && stats.size <= MAX_FILE_BYTES ? readFileSync(real, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * What the readers ask of a tree of files: the working tree's, or a commit's.
+ *
+ * @param exists - whether a file is there.
+ * @param readText - its text.
+ */
+const exportsDisk = (exists, readText, onAlias) => ({
+    readText,
+    onAlias,
+    resolve: (specifier, from) => {
+        const bare = VITE_PATHS.join(VITE_PATHS.dirname(from), specifier);
+        const written = bare.replace(/\.[cm]?jsx?$/, "");
+        if (/\.(?:[cm]?tsx?|jsx|vue|svelte)$/.test(bare) && exists(bare))
+            return bare;
+        for (const form of [written, `${written}/index`]) {
+            for (const extension of RESOLVED_EXTENSIONS) {
+                if (exists(`${form}${extension}`))
+                    return `${form}${extension}`;
+            }
+        }
+        return exists(bare) ? bare : undefined;
+    }
+});
+/** A manifest's value, or why it cannot be read. */
+const manifestOf = (text) => {
+    try {
+        return { value: JSON.parse(text ?? "null") };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+};
+/**
+ * What the packages publish.
+ *
+ * @param manifests - the packages' manifests, in the catalogue's form of their paths.
+ * @param exists - whether a file is there.
+ * @param readText - its text.
+ * @param listFiles - every file under a folder.
+ */
+const publishedIn = (manifests, exists, readText, listFiles) => {
+    const packages = [];
+    const files = [];
+    const seen = new Set();
+    const unread = [];
+    for (const file of manifests) {
+        const dir = VITE_PATHS.dirname(file);
+        const read = manifestOf(readText(file));
+        if ("error" in read) {
+            unread.push({ dir, text: `a manifest that cannot be read: ${read.error}` });
+            continue;
+        }
+        const manifest = read.value;
+        if (!isPublished(manifest))
+            continue;
+        const found = packageEntries(manifest, dir, { exists, filesUnder: listFiles });
+        const name = typeof manifest === "object" && manifest !== null && "name" in manifest ? String(manifest.name) : dir;
+        const aliases = new Set();
+        const own = publishedComponents(found.entries, exportsDisk(exists, readText, (specifier) => aliases.add(specifier)));
+        if (own.length > 0)
+            packages.push(name);
+        files.push(...own.filter((each) => !seen.has(each.file)));
+        for (const each of own)
+            seen.add(each.file);
+        unread.push(...found.unread.map((path) => ({
+            dir,
+            text: `a published entry not led back to its source: ${name}: ${path}`
+        })), ...[...aliases].map((alias) => ({
+            dir,
+            text: `a published export through an alias not followed: ${name}: ${alias}`
+        })));
+    }
+    return { packages, files, unread };
+};
+/** The manifests git lists, a new package's among them: the change may be what adds it. */
+const manifestsOf = async (dir, realDir, root) => {
+    const names = (await gitOutput(root, "ls-files", "-z", "--cached", "--others", "--exclude-standard", "--", "package.json", "*/package.json"))
+        .split("\0")
+        .filter((name) => name !== "" && !NOT_A_LIBRARY.test(name));
+    return catalogueChangedFiles(dir, realDir, root, names);
+};
+/** Each component of a tree. */
+const treeComponents = (tree) => tree.sources.flatMap((source) => source.families.flatMap((family) => family.groups.flatMap((group) => group.components.map((component) => ({ source: source.id, component })))));
+/** A source's component as the check reads it, with its docs. */
+const seenComponent = async ({ loaded }, readStory, source, component, reach) => {
+    const own = reach.filter((each) => each.title === component.title);
+    const loadedSource = loaded.sources.find((each) => each.id === source);
+    const files = loadedSource === undefined ? undefined : sourceFiles(loadedSource);
+    const docs = await settled(files?.docs[component.file]);
+    const value = "value" in docs && isComponentDocs(docs.value) ? docs.value : undefined;
+    return {
+        title: component.title,
+        storyFile: component.file,
+        words: [...component.stories.map((each) => each.name), ...component.keywords],
+        listed: component.stories.length,
+        unlisted: component.unlisted.length,
+        metaFile: own.find((each) => each.metaFile !== undefined)?.metaFile,
+        reached: [...new Set(own.flatMap((each) => each.files))],
+        storyText: [...new Set(own.map((each) => each.storyFile))]
+            .map((file) => readStory(file) ?? "")
+            .join("\n"),
+        docs: value === undefined
+            ? undefined
+            : {
+                props: value.props.length,
+                hasText: value.description !== "" || value.summary !== "",
+                subcomponents: value.subcomponents.map((each) => each.name)
+            },
+        description: files?.index[component.file]?.description
+    };
+};
+/** What a commit published, read with git and nothing of the working tree. */
+const publishedAt = async (dir, root, base, manifests) => {
+    const paths = new Set((await gitOutput(root, "ls-tree", "-r", "-z", "--name-only", base))
+        .split("\0")
+        .map((name) => VITE_PATHS.join(root, name)));
+    const inRoot = (file) => VITE_PATHS.join(root, VITE_PATHS.relative(dir, file));
+    const fromRoot = (file) => VITE_PATHS.join(dir, VITE_PATHS.relative(root, file));
+    const tree = publishedIn(manifests.map(inRoot).filter((file) => paths.has(file)), (file) => paths.has(file), (file) => {
+        if (!paths.has(file))
+            return undefined;
+        return execFileSync("git", ["show", `${base}:${VITE_PATHS.relative(root, file)}`], {
+            cwd: root,
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024
+        });
+    }, (folder) => [...paths].filter((file) => file.startsWith(`${folder}/`)));
+    return { ...tree, files: tree.files.map((each) => ({ ...each, file: fromRoot(each.file) })) };
+};
+/** A story file. */
+const STORY_FILE = /\.stories\.[^/]+$/;
+/** A name with what does not change its reading taken off. */
+const plainWord = (name) => name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+/** What a file is named after: itself, or its folder for an index. */
+const namedAfter = (file) => {
+    const parts = file.split("/");
+    const name = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "");
+    return name === "index" ? (parts.at(-2) ?? name) : name;
+};
+/**
+ * What a story file may be about, in plain words: its own name, and its folder's, past a folder only for stories
+ * (`Box/stories/Simple.stories.js` is about `Box`).
+ */
+const storyFileNames = (file) => {
+    const parts = file.split("/").slice(0, -1);
+    const folders = parts.filter((part) => !/^_*stories_*$/.test(part)).slice(-1);
+    const name = (file.split("/").at(-1) ?? "").replace(/\.stories\.[^/]+$/, "");
+    return [name, ...folders].map(plainWord);
+};
+/**
+ * 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 const filesOfChange = async (now, changed, readBefore) => {
+    const moved = new Set(changed);
+    // losing a story, its listing or its meta's component hides a component whose own file did not move
+    const stories = changed.filter((file) => STORY_FILE.test(file)).flatMap(storyFileNames);
+    const edited = now.filter(({ file, names }) => moved.has(file) || [...names, namedAfter(file)].some((name) => stories.includes(plainWord(name))));
+    // a change touching only components cannot have published anything new, and a commit's tree costs a git call per file
+    if (changed.every((file) => STORY_FILE.test(file) || now.some((each) => each.file === file)))
+        return edited;
+    const before = new Map((await readBefore()).map((each) => [each.file, new Set(each.names)]));
+    const named = now.filter((each) => {
+        const known = before.get(each.file);
+        return !edited.includes(each) && each.names.some((name) => known?.has(name) !== true);
+    });
+    return [...edited, ...named];
+};
+/**
+ * What agents cannot see.
+ *
+ * @param context - what the routes read.
+ */
+export const visibilityAnswer = async (context) => {
+    const { config, loaded, tree, params } = context;
+    const since = params.get("since") || undefined;
+    const base = since === undefined ? undefined : await changeBase(config.dir, since);
+    if (since !== undefined && base === undefined)
+        return { status: 400, body: { error: await noBaseReason(config.dir, since) } };
+    const answerOf = (packages, unseen, checked, skipped) => {
+        const body = {
+            schema: 1,
+            ...(since === undefined ? {} : { since }),
+            packages,
+            checked,
+            unseen,
+            // a branch writes these: what reaches an agent or a terminal holds no control character
+            skipped: skipped.map(printable)
+        };
+        return { status: 200, body };
+    };
+    const realDir = await realpath(config.dir);
+    const root = await gitOutput(config.dir, "rev-parse", "--show-toplevel").then((text) => text.trim(), () => undefined);
+    if (root === undefined)
+        return answerOf([], [], 0, ["what agents see not checked: this is not a git repository"]);
+    const rootInDir = VITE_PATHS.join(config.dir, VITE_PATHS.relative(realDir, root));
+    const manifests = await manifestsOf(config.dir, realDir, root);
+    const own = VITE_PATHS.normalize(config.dir);
+    const realRoot = VITE_PATHS.normalize(realpathSync(root));
+    const published = publishedIn(manifests.filter((file) => !belongsToOtherCatalogue(file, own, rootInDir, (folder) => findConfigFile(folder) !== undefined)), (file) => existsSync(file), (file) => textIn(realRoot, file), filesUnder);
+    const change = base === undefined ? undefined : await changedFiles(config.dir, base);
+    const changed = change === undefined ? [] : catalogueChangedFiles(config.dir, realDir, root, change.files);
+    // a package the change does not touch is no reason to call the change only partly verified
+    const unread = published.unread
+        .filter(({ dir }) => change === undefined || changed.some((file) => file.startsWith(`${dir}/`)))
+        .map(({ text }) => text);
+    if (!offersUsedIn(config.lists) || !readsComponentDocs(config.lists))
+        return answerOf(published.packages, [], 0, [
+            ...unread,
+            "what agents see not checked: the catalogue turns off the component docs or Used in, which it reads"
+        ]);
+    const relevant = change === undefined || base === undefined
+        ? published.files
+        : await filesOfChange(published.files, changed, async () => (await publishedAt(rootInDir, root, base, manifests)).files);
+    if (relevant.length === 0)
+        return answerOf(published.packages, [], 0, unread);
+    const { groups, identified } = await identifiedStories(loaded, tree);
+    // with no graph every component would look storyless
+    if (groups.some(({ reach }) => typeof reach === "string"))
+        return answerOf(published.packages, [], 0, [
+            ...unread,
+            "what agents see not checked: the stories' imports could not be read"
+        ]);
+    const reach = identified.map((each) => each.reach);
+    const components = await Promise.all(treeComponents(tree).map(({ source, component }) => seenComponent(context, (file) => textIn(realRoot, file), source, component, reach)));
+    const unseen = relevant.flatMap((file) => {
+        const path = VITE_PATHS.relative(config.dir, file.file);
+        const found = unseenComponent(file, path, VITE_PATHS.relative(rootInDir, file.file), components);
+        return found === undefined ? [] : [found];
+    });
+    return answerOf(published.packages, unseen, relevant.length, unread);
+};

package/dist/src/worstCase.d.ts

@@ -13,3 +13,5 @@ export declare const WORST_WORD = "Supercalifragilisticexpialidocious_with_no_pl
 export declare const WORST_SCRIPTS = "\u00DCn\u00EFc\u00F6d\u00E9 \u540D\u524D \u0645\u0631\u062D\u0628\u0627 \uD83D\uDC69\uD83C\uDFFD\u200D\uD83D\uDCBB";
 /** A number with more digits than a box usually holds. */
 export declare const WORST_NUMBER = 123456789012;
+/** The worst text: a long one, with a word that cannot break. */
+export declare const WORST_ARG_TEXT = "A label long enough to wrap onto several lines in any box it is given, with words of every length in it Supercalifragilisticexpialidocious_with_no_place_to_break_it_at_all_1234567890";

package/dist/src/worstCase.js

@@ -13,3 +13,5 @@ export const WORST_WORD = "Supercalifragilisticexpialidocious_with_no_place_to_b
 export const WORST_SCRIPTS = "Ünïcödé 名前 مرحبا 👩🏽‍💻";
 /** A number with more digits than a box usually holds. */
 export const WORST_NUMBER = 123_456_789_012;
+/** The worst text: a long one, with a word that cannot break. */
+export const WORST_ARG_TEXT = `${WORST_TEXT} ${WORST_WORD}`;