forgebook 0.3.3 → 0.4.0

package/dist/src/vite/publishedExports.js

@@ -0,0 +1,298 @@
+/**
+ * The components a package's entries export, by the file that declares each: what "published" means to `verify`.
+ *
+ * @remarks
+ * Read from each file's syntax, with no program: a whole package must take moments on a change that touches one file, and
+ * an export's shape says enough. Only relative paths are followed, since a package's own files are what it publishes and
+ * another package of the repository has its own entries. A file counts as one finding however many parts it declares
+ * (`Dialog`, `DialogTrigger`): one story page shows them together, and a finding per part would bury the one that matters.
+ * Only what reads as a component counts. A context, a value, a constant in capitals and a hook are published too, and no
+ * story is owed for them.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/** A file that is a component by its extension alone: its default export is what it draws. */
+const COMPONENT_FILE = /\.(?:vue|svelte|astro)$/;
+/** A file whose capitalised functions draw something. */
+const DRAWN_FILE = /\.[cm]?[jt]sx$/;
+/** A script's text that defines a component with no JSX in it. */
+const DEFINES_COMPONENT = /\bcustomElements\.define\(|@customElement\(|\bextends\s+(?:LitElement|HTMLElement)\b|@Component\(|\bdefineComponent\(|\bforwardRef\(|\bcreateElement\(|\bstyled[.(]|<\/[A-Za-z][\w.-]{0,80}>|<[A-Z][\w.]{0,80}[^<>\n]{0,500}\/>/;
+/** A name a component can have: capitalised and not a constant. */
+const COMPONENT_NAME = /^[A-Z](?:[a-z0-9]|[A-Z]+[a-z0-9])\w*$|^[A-Z]$/;
+/** A call whose result is no component. */
+const NOT_A_COMPONENT_CALL = /^(?:React\.)?(?:createContext|cva|tv|defineConfig|Symbol|Object\.freeze)$/;
+/** An import through a project's alias rather than a package's name. */
+const ALIASED = /^(?:[@~#]\/|#)/;
+/** Whether a call's name says its result is no component. */
+const isPlainCall = (call) => NOT_A_COMPONENT_CALL.test(call.expression.getText());
+/** How the expression a name is given reads. */
+const shapeOfExpression = (node) => {
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+        return { takesProps: node.parameters.length > 0 };
+    if (ts.isClassExpression(node))
+        return { takesProps: true };
+    if (ts.isCallExpression(node)) {
+        if (isPlainCall(node))
+            return undefined;
+        const inner = node.arguments.find((each) => ts.isArrowFunction(each) || ts.isFunctionExpression(each));
+        const typed = (node.typeArguments?.length ?? 0) > 0;
+        return { takesProps: typed || (inner !== undefined && (shapeOfExpression(inner)?.takesProps ?? false)) };
+    }
+    if (ts.isTaggedTemplateExpression(node))
+        return { takesProps: false };
+    // `export const Tooltip = Primitive.Root`, a library's part under a name of its own
+    if (ts.isPropertyAccessExpression(node) && /^[A-Z]/.test(node.name.text))
+        return { takesProps: false };
+    if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node))
+        return shapeOfExpression(node.expression);
+    return undefined;
+};
+/** How a variable's declaration reads: its value, or the type it is written with. */
+const shapeOfVariable = (declaration) => {
+    const shape = declaration.initializer === undefined ? undefined : shapeOfExpression(declaration.initializer);
+    if (shape !== undefined || declaration.type === undefined)
+        return shape;
+    return ts.isTypeReferenceNode(declaration.type) && /(?:FC|ComponentType)\b/.test(declaration.type.getText())
+        ? { takesProps: (declaration.type.typeArguments?.length ?? 0) > 0 }
+        : undefined;
+};
+/** Whether a statement carries a modifier. */
+const hasModifier = (node, kind) => ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false;
+/** The named variables a statement declares. */
+const variablesOf = (statement) => statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name));
+/** A variable's name, which `variablesOf` has seen to be an identifier. */
+const variableName = (declaration) => declaration.name.getText();
+/** Reads what a statement declares into a file's scope. */
+const addDeclared = (statement, scope) => {
+    const isCommented = ts.getJSDocCommentsAndTags(statement).length > 0;
+    const declare = (name, shape) => {
+        scope.declared.set(name, shape);
+        if (isCommented)
+            scope.commented.add(name);
+    };
+    if (ts.isFunctionDeclaration(statement) && statement.name !== undefined)
+        declare(statement.name.text, { takesProps: statement.parameters.length > 0 });
+    if (ts.isClassDeclaration(statement) && statement.name !== undefined)
+        declare(statement.name.text, { takesProps: true });
+    if (ts.isVariableStatement(statement))
+        for (const declaration of variablesOf(statement))
+            declare(variableName(declaration), shapeOfVariable(declaration));
+};
+/** Reads what a statement imports into a file's scope; a type's import brings no component. */
+const addImported = (statement, scope) => {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+        return;
+    const from = statement.moduleSpecifier.text;
+    const clause = statement.importClause;
+    if (clause === undefined || clause.isTypeOnly)
+        return;
+    if (clause.name !== undefined)
+        scope.imported.set(clause.name.text, { from, name: "default" });
+    if (clause.namedBindings === undefined || !ts.isNamedImports(clause.namedBindings))
+        return;
+    for (const each of clause.namedBindings.elements)
+        if (!each.isTypeOnly)
+            scope.imported.set(each.name.text, { from, name: (each.propertyName ?? each.name).text });
+};
+/** How a default export written in place reads. */
+const defaultThing = (expression, file, isDrawn) => {
+    const shape = shapeOfExpression(expression);
+    return shape === undefined
+        ? undefined
+        : { file, isComponent: isDrawn, takesProps: shape.takesProps, hasComment: false };
+};
+/** How TypeScript is told to read a file. */
+const scriptKindOf = (file) => {
+    if (/\.tsx$/.test(file))
+        return ts.ScriptKind.TSX;
+    if (/\.jsx$/.test(file))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(file))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.TS;
+};
+/** Records an export, when it is something this can tell of. */
+const record = (context, name, thing) => {
+    if (thing !== undefined)
+        context.found.set(name, thing);
+};
+/** Adds what `export { … }`, with or without a `from`, exports. */
+const addNamedExports = (clause, specifier, context) => {
+    for (const each of clause.elements) {
+        if (each.isTypeOnly)
+            continue;
+        const name = (each.propertyName ?? each.name).text;
+        const thing = specifier === undefined ? context.local(name) : context.followed(specifier, name);
+        record(context, each.name.text, thing);
+    }
+};
+/** Adds what an `export … from`, or `export { … }`, exports. */
+const addExportDeclaration = (statement, context) => {
+    if (statement.isTypeOnly)
+        return;
+    const { moduleSpecifier, exportClause } = statement;
+    const specifier = moduleSpecifier !== undefined && ts.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : undefined;
+    if (exportClause !== undefined && ts.isNamedExports(exportClause)) {
+        addNamedExports(exportClause, specifier, context);
+        return;
+    }
+    if (specifier === undefined)
+        return;
+    // `export * as Dialog from`, or `export *`: either way what that file exports is published under its own name
+    for (const [name, thing] of context.allOf(specifier)) {
+        if (name !== "default" && !context.found.has(name))
+            context.found.set(name, thing);
+    }
+};
+/** Adds what `export default <expression>` exports. */
+const addExportAssignment = (statement, context) => {
+    const { expression } = statement;
+    const thing = ts.isIdentifier(expression)
+        ? context.local(expression.text)
+        : defaultThing(expression, context.file, context.isDrawn);
+    record(context, "default", thing);
+};
+/** Adds what `export function` or `export class`, with a name or as the default, exports. */
+const addExportedDeclaration = (statement, context) => {
+    const name = statement.name?.text;
+    const thing = name === undefined
+        ? {
+            file: context.file,
+            isComponent: context.isDrawn,
+            takesProps: ts.isClassDeclaration(statement),
+            hasComment: ts.getJSDocCommentsAndTags(statement).length > 0
+        }
+        : context.local(name);
+    const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword);
+    record(context, isDefault ? "default" : (name ?? "default"), thing);
+};
+/** Adds what one statement exports. */
+const addExports = (statement, context) => {
+    if (ts.isExportDeclaration(statement)) {
+        addExportDeclaration(statement, context);
+        return;
+    }
+    if (ts.isExportAssignment(statement)) {
+        if (!statement.isExportEquals)
+            addExportAssignment(statement, context);
+        return;
+    }
+    if (!ts.canHaveModifiers(statement) || !hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+        return;
+    if (ts.isVariableStatement(statement)) {
+        for (const declaration of variablesOf(statement)) {
+            const name = variableName(declaration);
+            record(context, name, context.local(name));
+        }
+        return;
+    }
+    if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement))
+        addExportedDeclaration(statement, context);
+};
+/**
+ * Reads files' exports, each file once.
+ *
+ * @param disk - what is asked of the disk.
+ * @returns what reads one file; a file reached again while it is read (a cycle) has none yet, as a cycle adds nothing.
+ */
+const exportReader = (disk) => {
+    const seen = new Map();
+    const targetOf = (specifier, from) => {
+        if (ALIASED.test(specifier))
+            disk.onAlias?.(specifier, from);
+        return specifier.startsWith(".") ? disk.resolve(specifier, from) : undefined;
+    };
+    const exportsOf = (file) => {
+        const known = seen.get(file);
+        if (known !== undefined)
+            return known;
+        const found = new Map();
+        seen.set(file, found);
+        const text = disk.readText(file);
+        if (text === undefined)
+            return found;
+        if (COMPONENT_FILE.test(file)) {
+            found.set("default", { file, isComponent: true, takesProps: false, hasComment: false });
+            return found;
+        }
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindOf(file));
+        const isDrawn = DRAWN_FILE.test(file) || DEFINES_COMPONENT.test(text);
+        const scope = { declared: new Map(), commented: new Set(), imported: new Map() };
+        for (const statement of source.statements) {
+            addDeclared(statement, scope);
+            addImported(statement, scope);
+        }
+        const followed = (specifier, name) => {
+            const target = targetOf(specifier, file);
+            return target === undefined ? undefined : exportsOf(target).get(name);
+        };
+        // once per file: the text may be large, and every export of it asks
+        const hasModuleComment = text.includes("@module");
+        const context = {
+            file,
+            isDrawn,
+            found,
+            followed,
+            allOf: (specifier) => {
+                const target = targetOf(specifier, file);
+                return target === undefined ? new Map() : exportsOf(target);
+            },
+            local: (name) => {
+                const imported = scope.imported.get(name);
+                if (imported !== undefined)
+                    return followed(imported.from, imported.name);
+                if (!scope.declared.has(name))
+                    return undefined;
+                const shape = scope.declared.get(name);
+                return {
+                    file,
+                    isComponent: isDrawn && shape !== undefined,
+                    takesProps: shape?.takesProps ?? false,
+                    hasComment: scope.commented.has(name) || hasModuleComment
+                };
+            }
+        };
+        for (const statement of source.statements)
+            addExports(statement, context);
+        return found;
+    };
+    return exportsOf;
+};
+/** The name a file goes by: its own, or its folder's for an index. */
+const stemOf = (file) => {
+    const parts = file.split("/");
+    const name = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "");
+    return name === "index" ? (parts.at(-2) ?? name) : name;
+};
+/** The name a published thing goes by, when it reads as a component: a default export by its file's. */
+const componentNameOf = (name, thing) => {
+    if (!thing.isComponent)
+        return undefined;
+    const stem = stemOf(thing.file);
+    const named = name === "default" ? `${stem.charAt(0).toUpperCase()}${stem.slice(1)}` : name;
+    return COMPONENT_NAME.test(named) && !named.endsWith("Context") ? named : undefined;
+};
+/**
+ * The components some entries publish, one element per declaring file.
+ *
+ * @param entries - the entries' source files, absolute.
+ * @param disk - what is asked of the disk.
+ */
+export const publishedComponents = (entries, disk) => {
+    const exportsOf = exportReader(disk);
+    const files = new Map();
+    const things = entries.flatMap((entry) => [...exportsOf(entry)]);
+    for (const [name, thing] of things) {
+        const named = componentNameOf(name, thing);
+        if (named === undefined)
+            continue;
+        const file = files.get(thing.file) ?? { names: [], takesProps: false, hasComment: false };
+        if (!file.names.includes(named))
+            file.names.push(named);
+        file.takesProps ||= thing.takesProps;
+        file.hasComment ||= thing.hasComment;
+        files.set(thing.file, file);
+    }
+    return [...files].map(([file, each]) => ({ file, ...each }));
+};

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

@@ -0,0 +1,6 @@
+/**
+ * A folder's real path; for one not made yet, its nearest folder that is, with the rest of the path after it.
+ *
+ * @param folder - the folder, absolute.
+ */
+export declare const realFolder: (folder: string) => string;

package/dist/src/vite/realFolder.js

@@ -0,0 +1,25 @@
+/**
+ * A folder written as Vite writes its root: links followed and, on Windows, short names (`RUNNER~1`) written out in
+ * full. The configuration's folder and the build's output are named this way, so they compare with Vite's root.
+ *
+ * @remarks
+ * Vite reads its root with one of Node's two real paths on Windows, the plain one until a check it runs in the
+ * background ends and the native one after: they agree only on a path already written out. A root that differs from
+ * the folder the pages are named under makes the build's names climb out of it, and an output it does not see inside
+ * it is never emptied.
+ *
+ * @module
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * A folder's real path; for one not made yet, its nearest folder that is, with the rest of the path after it.
+ *
+ * @param folder - the folder, absolute.
+ */
+export const realFolder = (folder) => {
+    if (existsSync(folder))
+        return realpathSync.native(folder);
+    const parent = dirname(folder);
+    return parent === folder ? folder : join(realFolder(parent), basename(folder));
+};

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

@@ -0,0 +1,39 @@
+/**
+ * The configuration's `refs`, checked and made ready for the shell, and what the shell's generated entry says of them:
+ * the catalogues shown in the sidebar after this one's stories.
+ *
+ * @module
+ */
+import { type CatalogueRef } from "../catalogueRefs.ts";
+import type { RefOption } from "./config.ts";
+import type { ResolvedConfig } from "./configFile.ts";
+/** The composed catalogues, ready for the shell, in the configuration's order. */
+export type ResolvedRefs = readonly CatalogueRef[];
+/**
+ * Why the configuration's `refs` cannot be used, or none.
+ *
+ * @param config - the configuration, as loaded.
+ */
+export declare const refsProblem: (config: object) => string | undefined;
+/**
+ * The composed catalogues, each address its folder, in the configuration's order.
+ *
+ * @param refs - the configuration's `refs`, checked by `refsProblem`.
+ */
+export declare const resolvedRefs: (refs: Readonly<Record<string, RefOption>> | undefined) => readonly CatalogueRef[];
+/** The module that draws the composed catalogues, imported only by a catalogue that composes one. */
+export declare const REFS_MODULE = "forgebook/shell/refs";
+/**
+ * The composed catalogues and the code that draws them, for the shell; nothing for a catalogue that composes none, so
+ * its first load carries not even the way to that code.
+ *
+ * @param config - the configuration.
+ */
+export declare const refsLines: (config: Pick<ResolvedConfig, "refs">) => string[];
+/**
+ * What the plugin defines in the build for composition: whether the catalogue composes others, so a shell that composes
+ * none has every part of composition removed.
+ *
+ * @param refs - the composed catalogues.
+ */
+export declare const refsDefine: (refs: ResolvedRefs) => Readonly<Record<string, string>>;

package/dist/src/vite/refsConfig.js

@@ -0,0 +1,54 @@
+/**
+ * The configuration's `refs`, checked and made ready for the shell, and what the shell's generated entry says of them:
+ * the catalogues shown in the sidebar after this one's stories.
+ *
+ * @module
+ */
+import { refFolder, refProblem } from "../catalogueRefs.js";
+import { codeLiteral } from "../codeLiteral.js";
+/**
+ * Why the configuration's `refs` cannot be used, or none.
+ *
+ * @param config - the configuration, as loaded.
+ */
+export const refsProblem = (config) => {
+    const refs = Reflect.get(config, "refs");
+    if (refs === undefined)
+        return undefined;
+    if (typeof refs !== "object" || refs === null || Array.isArray(refs))
+        return 'refs must be an object of catalogues by id (`refs: { "design-system": { title, url } }`)';
+    return Object.entries(refs).flatMap(([id, ref]) => refProblem(id, ref) ?? [])[0];
+};
+/**
+ * The composed catalogues, each address its folder, in the configuration's order.
+ *
+ * @param refs - the configuration's `refs`, checked by `refsProblem`.
+ */
+export const resolvedRefs = (refs) => Object.entries(refs ?? {}).map(([id, ref]) => ({ id, title: ref.title.trim(), url: refFolder(ref.url) }));
+/** The module that draws the composed catalogues, imported only by a catalogue that composes one. */
+export const REFS_MODULE = "forgebook/shell/refs";
+/**
+ * The composed catalogues and the code that draws them, for the shell; nothing for a catalogue that composes none, so
+ * its first load carries not even the way to that code.
+ *
+ * @param config - the configuration.
+ */
+export const refsLines = (config) => config.refs.length === 0
+    ? []
+    : [
+        "    refs: {",
+        `      catalogues: ${codeLiteral(config.refs)},`,
+        `      load: () => import(${codeLiteral(REFS_MODULE)}).then((module) => module.RefPart)`,
+        "    },"
+    ];
+/** The name the build gives whether the catalogue composes others (`shell/composition.ts`). */
+const REFS_CONSTANT = "__FORGEBOOK_REFS__";
+/**
+ * What the plugin defines in the build for composition: whether the catalogue composes others, so a shell that composes
+ * none has every part of composition removed.
+ *
+ * @param refs - the composed catalogues.
+ */
+export const refsDefine = (refs) => ({
+    [REFS_CONSTANT]: JSON.stringify(refs.length > 0)
+});

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

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