forgebook 0.3.3 → 0.4.1

package/dist/src/vite/unresolvedTokens.js

@@ -0,0 +1,193 @@
+/**
+ * The tokens of an application's sheets that a browser gives no value, as problems: a reference that leads back to
+ * itself, or one to a name nothing declares.
+ *
+ * @remarks
+ * A token that resolves to nothing draws the UI with no colour or no size, and nothing else says so: the browser drops the
+ * declaration in silence. A cycle in the base is always a problem. A name the sheets do not declare may still get a value:
+ * another rule declares it, `@property` registers it, an installed package's sheet does, or code sets it (`next/font`
+ * writes `--font-geist-sans` on the page's element). So the names every sheet read declares count, those of the packages
+ * the sheets import count, and so does a name the repository's files write as code sets one: in quotes, as a declaration
+ * (`--gap:` in a template, a `.vue` style block, a sheet not read), a Svelte `style:` directive, a Tailwind arbitrary
+ * property. When that cannot all be known (a package's sheet that cannot be read, a sheet that builds names with Sass or
+ * Less, the files that cannot be searched), or when a cycle exists only inside a theme, which depends on the element the
+ * theme is set on, the line is something not read, which fails nothing, and never a problem that might be false. The
+ * repository is searched only for names already found missing, so an answer with none reads nothing more.
+ *
+ * @module
+ */
+import { spawnSync } from "node:child_process";
+import { importedPackageSheets, repositoryOf } from "./appTokenFiles.js";
+import { readCssText } from "./cssDeclarations.js";
+import { brokenReferences } from "./cssReferences.js";
+/** The files a custom property is set in, by code or by a sheet this does not read as the application's system. */
+const SEARCHED_FILES = [
+    "*.js",
+    "*.jsx",
+    "*.mjs",
+    "*.cjs",
+    "*.ts",
+    "*.tsx",
+    "*.mts",
+    "*.cts",
+    "*.vue",
+    "*.svelte",
+    "*.astro",
+    "*.html",
+    "*.css",
+    "*.scss",
+    "*.sass",
+    "*.less",
+    "*.pcss",
+    "*.postcss"
+];
+/** How long git may take to search the repository, in milliseconds. */
+const SEARCH_TIMEOUT = 10_000;
+/** How many names a line gives, of a cycle or of tokens that could not be told: past a few, they say nothing more. */
+const MOST_NAMED = 5;
+/** A name built by Sass or Less interpolation (`--#{$key}`, `--@{key}`), which no reading of the text can know. */
+const BUILT_NAME = /--(?:#\{|@\{)/;
+/** A custom property `@property` registers: it has its initial value wherever nothing else sets it. */
+const REGISTERED = /@property\s+(--[\w-]+)/g;
+/**
+ * The names of custom properties sheets declare. A cleared one (`initial`) gives no value, and one that only reads its own
+ * name (Tailwind's `@theme inline { --font-sans: var(--font-sans); }`) takes its value from elsewhere.
+ */
+const declaredNames = (readings, texts) => {
+    const declared = new Set(readings.flatMap(({ declarations }) => declarations.flatMap(({ name, value }) => (isOwnReference(name, value) ? [] : [name]))));
+    for (const text of texts)
+        for (const [, name = ""] of text.matchAll(REGISTERED))
+            declared.add(name);
+    return declared;
+};
+/** Whether a value gives no value of its own: cleared, or reading only its own name. */
+const isOwnReference = (name, value) => value === "initial" || value.replace(/\s/g, "") === `var(${name})`;
+/**
+ * Whether a line of a file sets a name: in quotes (`variable: "--font-sans"`, `style={{ "--gap": … }}`,
+ * `setProperty("--gap", …)`), as a declaration (`--gap: 4px`) that is not only its own name, a Svelte `style:` directive
+ * or a Tailwind arbitrary property (`[--gap:4px]`). A reference is `var(--gap)`, which none of these match.
+ */
+const setsName = (line, name) => {
+    if ([`"${name}"`, `'${name}'`, `\`${name}\``, `style:${name}=`, `[${name}:`].some((form) => line.includes(form))) {
+        return true;
+    }
+    const at = line.indexOf(`${name}:`);
+    if (at === -1)
+        return false;
+    const value = line.slice(at + name.length + 1).split(/[;}]/)[0] ?? "";
+    return !isOwnReference(name, value.trim());
+};
+/**
+ * The names among some that the repository's files set, searched as fixed strings, which git matches all at once where
+ * a pattern per name takes seconds; the strings go on its input, since a command line has a limit on Windows. None when
+ * the files cannot be searched.
+ */
+const namesSetIn = (root, names) => {
+    // a repository's configuration may name a program for git to run: nothing here is to run
+    const found = spawnSync("git", [
+        "-c",
+        "core.fsmonitor=false",
+        "grep",
+        "--untracked",
+        "-I",
+        "-h",
+        "-F",
+        "-f",
+        "-",
+        "--",
+        ...SEARCHED_FILES
+    ], {
+        cwd: root,
+        input: names.join("\n"),
+        encoding: "utf8",
+        timeout: SEARCH_TIMEOUT,
+        maxBuffer: 64 * 1024 * 1024
+    });
+    if (found.status === 1)
+        return new Set();
+    if (found.status !== 0)
+        return undefined;
+    const lines = found.stdout.split("\n");
+    return new Set(names.filter((name) => lines.some((line) => line.includes(name) && setsName(line, name))));
+};
+/** Where a declaration stands, for a line that names it. */
+const placeOf = ({ origin }) => origin.line === undefined ? origin.file : `${origin.file}:${origin.line}`;
+/** What is wrong with a declaration, without where. */
+const whatOf = (broken) => {
+    const { name } = broken.declaration;
+    if (broken.kind === "undeclared")
+        return `${name} reads var(${broken.target})`;
+    const shown = broken.through.slice(0, MOST_NAMED);
+    const more = broken.through.length - shown.length;
+    const names = more > 0 ? `${shown.join(", ")} and ${more} more` : shown.join(", ");
+    const theme = broken.mode === undefined ? "" : ` in the ${broken.mode} theme`;
+    return `${name} leads back to ${shown.length === 0 ? "itself" : `itself through ${names}`}${theme}`;
+};
+/** A problem's line. */
+const problemOf = (broken) => {
+    const at = placeOf(broken.declaration);
+    if (broken.kind === "cycle")
+        return `${at}: ${whatOf(broken)}, so a browser gives it no value`;
+    return `${at}: ${whatOf(broken)}, which nothing declares, so a browser gives it no value: declare ${broken.target} or give it a fallback`;
+};
+/**
+ * What could not be told for one reason, one line a token, or one line in all past a few: an application whose
+ * dependencies are not installed has hundreds, and each says the same.
+ */
+const unsureLines = (unsure, why) => {
+    if (unsure.length <= MOST_NAMED)
+        return unsure.map((each) => `${placeOf(each.declaration)}: ${whatOf(each)}: ${why}`);
+    const shown = unsure.slice(0, MOST_NAMED).map(whatOf).join("; ");
+    return [
+        `${unsure.length} tokens may have no value (${shown}; and ${unsure.length - MOST_NAMED} more): ${why}`
+    ];
+};
+/** Why a name nothing read declares cannot be called missing; none when it can. */
+const doubtOf = (unreadable, hasBuiltNames, setInFiles) => {
+    if (setInFiles === undefined)
+        return "nothing read declares it, and the repository could not be searched for it";
+    if (hasBuiltNames)
+        return "nothing read declares it, and a sheet builds names with Sass or Less, which only running it knows";
+    if (unreadable.length > 0) {
+        const named = unreadable.map((each) => `"${each}"`).join(", ");
+        return `nothing read declares it; it may come from ${named}, which could not be read`;
+    }
+    return undefined;
+};
+/**
+ * Finds the tokens that resolve to nothing.
+ *
+ * @param dir - the catalogue's folder, its links followed.
+ * @param read - the sheets and configurations read, and the declarations tokens are made from, the lowest first.
+ */
+export const unresolvedTokens = (dir, read) => {
+    const packages = importedPackageSheets(dir, read.sheets);
+    const declared = declaredNames([...read.sheets.map(({ reading }) => reading), ...packages.texts.map((text) => readCssText(text))], [...read.sheets.map(({ text }) => text), ...packages.texts]);
+    for (const { reading } of read.configs)
+        for (const { name } of reading.tokens)
+            declared.add(name);
+    const broken = brokenReferences(read.declarations, (name) => declared.has(name)).filter(({ declaration }) => declaration.origin.kind !== "tailwind-default");
+    const missing = [...new Set(broken.flatMap((each) => (each.kind === "undeclared" ? [each.target] : [])))];
+    const setInFiles = missing.length === 0 ? new Set() : namesSetIn(repositoryOf(dir), missing);
+    const hasBuiltNames = read.sheets.some(({ text }) => BUILT_NAME.test(text));
+    const doubt = doubtOf(packages.unreadable, hasBuiltNames, setInFiles);
+    const problems = [];
+    const inTheme = [];
+    const doubted = [];
+    for (const each of broken) {
+        if (each.kind === "cycle" && each.mode !== undefined)
+            inTheme.push(each);
+        else if (each.kind === "cycle" || (doubt === undefined && setInFiles?.has(each.target) !== true)) {
+            problems.push(problemOf(each));
+        }
+        else if (setInFiles?.has(each.target) !== true)
+            doubted.push(each);
+    }
+    return {
+        problems,
+        unread: [
+            ...unsureLines(inTheme, "a browser gives it no value if the theme is set on the root, as its base is"),
+            ...(doubt === undefined ? [] : unsureLines(doubted, doubt))
+        ]
+    };
+};

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