forgebook 0.3.3 → 0.4.0

package/dist/src/vite/agentStoryCode.js

@@ -0,0 +1,38 @@
+import { codeNameOf } from "../componentDocs.js";
+import { panelArgsOf } from "../frame/panelValues.js";
+import { readStory } from "../frame/storyModule.js";
+import { storyCodeText } from "../storyCodeText.js";
+/** Whether a module's answer is a story file's code, by export name. */
+const isStoryFileCode = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !("error" in value);
+/**
+ * A story's code; none when its module, its file's code or the framework's writer cannot be read.
+ *
+ * @param parts - the file's code, the framework's writer and the named values.
+ * @param story - the story, its module, what an agent set and its component's docs.
+ */
+export const agentStoryCode = (parts, { location, module, preview, accepted = {}, docs }) => {
+    const loaded = readStory(module, location.story.exportName, preview);
+    const value = "value" in parts.code ? parts.code.value : undefined;
+    if (typeof loaded === "string" || !isStoryFileCode(value) || parts.writer === undefined)
+        return undefined;
+    return storyCodeText({
+        code: value,
+        exportName: location.story.exportName,
+        componentName: docs === undefined ? location.component.name : codeNameOf(docs),
+        args: { ...panelArgsOf(loaded.args, parts.namedValues), ...accepted },
+        edited: Object.keys(accepted)
+    }, parts.writer);
+};
+/**
+ * A story's answer with its code, when it can be written.
+ *
+ * @param document - the story's answer.
+ * @param parts - the file's code, the framework's writer and the named values; none leaves the answer as it is.
+ * @param story - the story, its module and the preview.
+ */
+export const withStoryCode = (document, parts, story) => {
+    const code = parts === undefined
+        ? undefined
+        : agentStoryCode(parts, { ...story, accepted: document.setArgs?.accepted, docs: document.docs });
+    return code === undefined ? document : { ...document, code };
+};

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

@@ -0,0 +1,47 @@
+import type { UnseenComponent, VisibilityDocument } from "./agent.types.ts";
+import type { PublishedFile } from "./publishedExports.ts";
+/** A catalogue's component as this reads it. */
+export type SeenComponent = {
+    /** Its whole title. */
+    readonly title: string;
+    /** Its first story file, relative to the catalogue: what a fix names. */
+    readonly storyFile: string;
+    /** How many of its stories are listed. */
+    readonly listed: number;
+    /** How many are tagged `!dev`. */
+    readonly unlisted: number;
+    /** The names of its stories and the words its meta declares: what a search reads. */
+    readonly words: readonly string[];
+    /** The file its meta's `component` is declared in; none when its meta names none. */
+    readonly metaFile: string | undefined;
+    /** The files its stories reach. */
+    readonly reached: readonly string[];
+    /** Its story files' text: what names a part when the graph cannot follow a JavaScript library's imports. */
+    readonly storyText: string;
+    /** The docs its meta's component has; none when none could be read. */
+    readonly docs: {
+        /** How many props they list. */
+        readonly props: number;
+        /** Whether they hold its TSDoc, or its file's. */
+        readonly hasText: boolean;
+        /** The names of the parts its meta lists. */
+        readonly subcomponents: readonly string[];
+    } | undefined;
+    /** The meta's `parameters.docs.description.component`, which an agent reads as it reads TSDoc. */
+    readonly description: string | undefined;
+};
+/**
+ * What hides a published file from an agent; none when it can be seen.
+ *
+ * @param published - the file, with the components it declares.
+ * @param path - the file as a command names it, relative to the catalogue.
+ * @param file - the file as a person names it, relative to the repository.
+ * @param components - the catalogue's components.
+ */
+export declare const unseenComponent: (published: PublishedFile, path: string, file: string, components: readonly SeenComponent[]) => UnseenComponent | undefined;
+/**
+ * Whether a value is the answer on what agents cannot see, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isVisibilityDocument: (value: unknown) => value is VisibilityDocument;

package/dist/src/vite/agentVisibility.js

@@ -0,0 +1,174 @@
+/**
+ * Whether an agent can see a published component: what `verify` holds a changed one to, and `forgebook visibility` every
+ * one.
+ *
+ * @remarks
+ * Pure. An agent looks a component up by its words and reads it through its stories (`find`, `story`), so a component
+ * nothing there names is rebuilt instead of reused, as has happened with a component only other components' stories drew.
+ * Four things hide one, each with its fix: no story of its own, stories all tagged `!dev`, stories whose meta names no
+ * component or a component whose docs have no props (the props table is what an agent writes against), and no TSDoc.
+ * `keywords` are not asked for: a good title finds most components, and a check nearly every project fails is turned off.
+ * A part (`DialogTrigger`, in a file of its own) that the stories of the component it is named after reach is seen on that
+ * page, as `subcomponents` shows it. A provider draws nothing of its own to look at, so no story is owed for it.
+ *
+ * @module
+ */
+import { shellWord } from "../shellWord.js";
+/** A component that only hands something to what it wraps. */
+const DRAWS_NOTHING = /(?:Provider|Context|Consumer)$/;
+/** A name with what does not change its reading taken off: `date-picker`, `DatePicker` and `Date Picker` are one. */
+const plainName = (name) => name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+/** The name a file goes by. */
+const fileStem = (file) => {
+    const parts = file.split("/");
+    const name = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "");
+    return name === "index" ? (parts.at(-2) ?? name) : name;
+};
+/**
+ * Whether a meta's component is a published file: the same file, or the declaration of it. A JavaScript library declares
+ * its types beside its code, and a package whose types point at its build leads the checker into that build, so a meta's
+ * component may be `Box/index.d.ts` or `dist/Button.d.ts` and not the source.
+ */
+const isMetaOf = (metaFile, file) => {
+    if (metaFile === file)
+        return true;
+    if (metaFile === undefined || !/\.d\.[cm]?ts$/.test(metaFile))
+        return false;
+    const folderOf = (path) => path.split("/").slice(0, -1).join("/");
+    const isBeside = folderOf(metaFile) === folderOf(file);
+    const isBuilt = /\/(?:dist|build|lib|es|esm|cjs)\//.test(metaFile);
+    return (isBeside || isBuilt) && fileStem(metaFile.replace(/\.d(\.[cm]?ts)$/, "$1")) === fileStem(file);
+};
+/** The plain names a search finds a component by: its title's parts, its stories' names, its meta's words. */
+const namesOf = (component) => [...component.title.split("/"), ...component.words].map(plainName);
+/**
+ * Whether a component's stories draw another file of a published file's name: another package's component of that name
+ * is then what they are about. The graph may not reach a JavaScript library's files at all, so what it does not reach
+ * says nothing. An index only leads to the file it names, and a form with no extension is an import it did not resolve.
+ */
+const drawsAnother = (component, published) => {
+    if (component.reached.includes(published.file))
+        return false;
+    const stem = plainName(fileStem(published.file));
+    return component.reached.some((file) => /\.[^/]+$/.test(file) && !/\/index\.[^/]+$/.test(file) && plainName(fileStem(file)) === stem);
+};
+/** Whether a component's stories are about a published file: its meta names it, or a search finds it there by name. */
+const isAbout = (component, published) => {
+    if (isMetaOf(component.metaFile, published.file))
+        return true;
+    if (drawsAnother(component, published))
+        return false;
+    const names = namesOf(component);
+    const wanted = [...published.names, fileStem(published.file)].map(plainName);
+    if (wanted.some((name) => names.includes(name)))
+        return true;
+    // a story named `DefaultIssueLabelToken` is what a search for the token finds
+    const storyNames = component.words.map(plainName);
+    return wanted.some((name) => name.length > 3 && storyNames.some((each) => each.includes(name)));
+};
+/**
+ * Whether a component's stories reach a published file, in any of the forms the graph writes an import it could not
+ * resolve further (`components/Text`, `components/Text/index`).
+ */
+const isReached = (component, file) => {
+    const bare = file.replace(/\.[^./]+$/, "");
+    const folder = file.split("/").slice(0, -1).join("/");
+    return [file, bare, folder, `${folder}/index`].some((form) => component.reached.includes(form));
+};
+/** Whether a story file's text uses a name as a word. */
+const mentions = (text, name) => new RegExp(`(?<![\\w$])${name.replace(/[^\w$]/g, "")}(?![\\w$])`).test(text);
+/**
+ * Whether a published file is a part of a component: its meta lists it, or its stories use it and its name extends the
+ * component's (`DialogTrigger` of `Dialog`) or is the one item of a plural (`Tab` of `Tabs`). The name alone would call
+ * `ButtonGroup` seen on `Button`'s page, with nothing there showing it.
+ */
+const isPartOf = (component, published) => {
+    if (published.names.some((name) => component.docs?.subcomponents.includes(name) === true))
+        return true;
+    // a title's first part is a section (`Controls`), and its last may be a variation (`Table/Simple`)
+    const titles = component.title
+        .split("/")
+        .slice(1)
+        .map(plainName)
+        .filter((title) => title !== "");
+    return published.names.some((name) => {
+        const plain = plainName(name);
+        const isNamedAfter = titles.some((title) => plain.startsWith(title) || title === `${plain}s`);
+        return isNamedAfter && (isReached(component, published.file) || mentions(component.storyText, name));
+    });
+};
+/** What hides a published file whose stories are about it. */
+const reasonsAbout = (published, path, own) => {
+    const name = published.names[0] ?? fileStem(published.file);
+    const first = own[0];
+    if (first === undefined)
+        return [];
+    const reasons = [];
+    if (own.every((each) => each.listed === 0))
+        reasons.push({
+            missing: "listed-story",
+            reason: `every story of ${first.title} is tagged !dev, so a search gives no story to open`,
+            fix: `take !dev off a story in ${first.storyFile}`
+        });
+    const named = own.filter((each) => isMetaOf(each.metaFile, published.file));
+    if (named.length === 0)
+        reasons.push({
+            missing: "props",
+            reason: `the meta in ${first.storyFile} names no component, so an agent reads no props`,
+            fix: `add component: ${name} to the meta in ${first.storyFile}`
+        });
+    else if (published.takesProps && named.every((each) => each.docs !== undefined && each.docs.props === 0))
+        reasons.push({
+            missing: "props",
+            reason: `${name} takes props, and none could be read from its types`,
+            fix: `give ${name} a props type declared in its package, in ${path}`
+        });
+    const hasText = published.hasComment ||
+        own.some((each) => each.docs?.hasText === true || (each.description ?? "") !== "");
+    // with no docs read there is no telling: naming the component in the meta comes first, then this says
+    if (!hasText && named.some((each) => each.docs !== undefined))
+        reasons.push({
+            missing: "tsdoc",
+            reason: `${name} has no TSDoc, so an agent cannot tell what it is for`,
+            fix: `write a TSDoc comment on ${name} in ${path}`
+        });
+    return reasons;
+};
+/**
+ * What hides a published file from an agent; none when it can be seen.
+ *
+ * @param published - the file, with the components it declares.
+ * @param path - the file as a command names it, relative to the catalogue.
+ * @param file - the file as a person names it, relative to the repository.
+ * @param components - the catalogue's components.
+ */
+export const unseenComponent = (published, path, file, components) => {
+    const name = published.names[0] ?? fileStem(published.file);
+    const own = components.filter((each) => isAbout(each, published));
+    if (own.length === 0 && components.some((each) => isPartOf(each, published)))
+        return undefined;
+    if (own.length === 0 && published.names.every((each) => DRAWS_NOTHING.test(each)))
+        return undefined;
+    const reasons = own.length === 0
+        ? [
+            {
+                missing: "story",
+                reason: `no story is about ${name}, so a search for it finds nothing`,
+                fix: `npx forgebook new ${shellWord(path)}`
+            }
+        ]
+        : reasonsAbout(published, path, own);
+    return reasons.length === 0 ? undefined : { file, component: name, reasons };
+};
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is the answer on what agents cannot see, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isVisibilityDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["packages"]) &&
+    Array.isArray(value["unseen"]) &&
+    Array.isArray(value["skipped"]);

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

@@ -0,0 +1,134 @@
+/**
+ * What a project actually uses: colours and sizes by how often, what is written by hand, and what the code asks of a token.
+ *
+ * @remarks
+ * Pure: files and tokens in, a report out. Discovery and not a system imposed: on a project with no tokens it says which
+ * values are the system in practice ("37 greys, 5 used 90% of the time"), and someone decides. It reads the same lines
+ * `check-code` does and leaves out what that leaves out, so the two never disagree on what a raw value is. Equal colours in
+ * different notations are one colour, since a palette is what the eye sees and not how a file spells it.
+ *
+ * @module
+ */
+import { type SizeRole } from "./checkCode.ts";
+import type { DesignToken, TokenSource } from "./designTokens.ts";
+/** A value, and how much it is used. */
+export type AuditValue = {
+    /** The value, as first written. */
+    readonly value: string;
+    /** How many times. */
+    readonly count: number;
+    /** In how many files. */
+    readonly files: number;
+    /** Of them, how many are written by hand. */
+    readonly hardCoded: number;
+    /** In how many files it is written by hand. */
+    readonly hardCodedFiles: number;
+    /** The token it is used through, or that it equals or is close to when written by hand. */
+    readonly token?: string;
+    /** That token's value changes with the theme, so replacing a fixed value with it changes what a theme shows. */
+    readonly tokenFollowsTheme?: true;
+};
+/** What the colours in use come to. */
+export type AuditColors = {
+    /** How many uses, of any kind. */
+    readonly uses: number;
+    /** Through the project's own tokens. */
+    readonly throughTokens: number;
+    /** Through Tailwind's default palette. */
+    readonly defaultPalette: number;
+    /** Written by hand. */
+    readonly hardCoded: number;
+    /** How many different colours. */
+    readonly distinct: number;
+    /** The most used, of all colours. */
+    readonly top: readonly AuditValue[];
+    /** The most written by hand: what there is to act on, which a well-kept project's `top` does not show. */
+    readonly handWritten: readonly AuditValue[];
+    /** The greys. */
+    readonly greys: {
+        /** How many different. */
+        readonly distinct: number;
+        /** How many cover 90 % of their uses. */
+        readonly coveringMost: number;
+        /** The most used. */
+        readonly top: readonly AuditValue[];
+    };
+    /** Colours a person would not tell apart, most used first. */
+    readonly nearDuplicates: readonly (readonly string[])[];
+};
+/** What the sizes in use of one role come to. */
+export type AuditSizes = {
+    /** How many uses. */
+    readonly uses: number;
+    /** Written by hand: not through a token or a class of a scale. */
+    readonly hardCoded: number;
+    /** How many different. */
+    readonly distinct: number;
+    /** The most used. */
+    readonly top: readonly AuditValue[];
+    /** The most written by hand. */
+    readonly handWritten: readonly AuditValue[];
+};
+/** Where a value is used. */
+export type AuditSite = {
+    /** The file, relative to the project. */
+    readonly file: string;
+    /** The line, from 1. */
+    readonly line: number;
+    /** The line's text, shortened. */
+    readonly text: string;
+    /** What the size is for; none for a colour. */
+    readonly role?: SizeRole;
+};
+/** What the values in a project's files come to. */
+export type ValueAudit = {
+    /** How many files were read. */
+    readonly files: number;
+    /** How many lines. */
+    readonly lines: number;
+    /** The colours. */
+    readonly colors: AuditColors;
+    /** The sizes, by what they are for. */
+    readonly sizes: Readonly<Record<SizeRole, AuditSizes>>;
+};
+/** A file to read. */
+export type AuditFile = {
+    /** Its path, relative to the project. */
+    readonly file: string;
+    /** Its text. */
+    readonly text: string;
+};
+/** What the tokens say to the reader of a report. */
+export type AuditSystem = {
+    /** How many tokens are known. */
+    readonly tokens: number;
+    /** How many are the project's own and not Tailwind's defaults. */
+    readonly own: number;
+    /** What they were read from. */
+    readonly sources: readonly TokenSource[];
+    /** What could not be read. */
+    readonly notes: readonly string[];
+};
+/** A colour's class: what it paints, and the rest of the name. */
+export declare const COLOR_CLASS: RegExp;
+/** A spacing class on a scale. */
+export declare const SPACE_CLASS: RegExp;
+/** A radius class. */
+export declare const RADIUS_CLASS: RegExp;
+/** A font's size class. */
+export declare const FONT_CLASS: RegExp;
+/**
+ * What a project's files use.
+ *
+ * @param files - its files.
+ * @param tokens - the tokens known; none is a report on values alone.
+ * @param top - how many values a list gives; 10 by default.
+ */
+export declare const valueAudit: (files: readonly AuditFile[], tokens: readonly DesignToken[], top?: number) => ValueAudit;
+/**
+ * Where a value written by hand stands: what an agent replacing it edits.
+ *
+ * @param files - the project's files.
+ * @param value - the value, as code writes it; a colour matches in any notation.
+ */
+export declare const valueSites: (files: readonly AuditFile[], value: string) => AuditSite[];