forgebook 0.3.3 → 0.4.1

package/dist/src/vite/agent.types.d.ts

@@ -15,8 +15,12 @@ import type { DocHeading } from "../docPages.ts";
 import type { LiveError } from "../liveErrors.ts";
 import type { PluginCondition } from "../plugin.ts";
 import type { SearchHitKind, SearchReason, SearchResult } from "../search.ts";
-import type { CodeProblem, CodeRule } from "./checkCode.ts";
-import type { DesignToken } from "./designTokens.ts";
+import type { SearchCorrection } from "../searchTypos.ts";
+import type { StoryCheckResult, StoryDiffStatus, StoryWarning } from "../storyCheck.ts";
+import type { SetArgs, StoryControl } from "../storyControls.ts";
+import type { SwitchControlKind, SwitchPreview, SwitchRole } from "../switches.ts";
+import type { CodeAdvice, CodeProblem, CodeRule, ExcusedValue } from "./checkCode.ts";
+import type { DesignToken, TokenSource } from "./designTokens.ts";
 import type { FoundComponent } from "./findComponent.ts";
 import type { NearestTokens } from "./nearestToken.ts";
 import type { TokenClash } from "./tokenClashes.ts";
@@ -69,6 +73,11 @@ export type AgentStory = {
     readonly description: string | undefined;
     /** Its tags, the meta's and its own. */
     readonly tags: readonly string[];
+    /**
+     * The tags among them the catalogue declares as statuses (`review`, `experimental`, `deprecated`), in its order;
+     * only when it holds one. Filter by one as by any tag.
+     */
+    readonly statuses?: readonly string[];
     /** Whether it is listed nowhere (`!dev`), opened only by its address. */
     readonly isUnlisted: boolean;
     /** The height its scene declares (`parameters.height`), in CSS px, when it declares one. */
@@ -111,6 +120,11 @@ export type AgentComponent = {
     readonly file: string;
     /** Every story file with its title, `file` first: one, unless the title is written in several files. */
     readonly files: readonly string[];
+    /**
+     * Its statuses: those its meta's tags hold, in the catalogue's order; in a story's answer also `deprecated`
+     * when its TSDoc says `@deprecated`. Only when it has one. A story may add or take one away (`AgentStory.statuses`).
+     */
+    readonly statuses?: readonly string[];
     /** Its stories: the listed ones in the catalogue's order, then the unlisted ones. */
     readonly stories: readonly AgentStory[];
     /** Its design (the meta's `parameters.design.figma`), when it has one. */
@@ -155,7 +169,7 @@ export type StoryDocument = {
     /** The story, with its links in the view asked for. */
     readonly story: AgentStory;
     /** Its component's id and title, and its "Used in" when the catalogue offers it. */
-    readonly component: Pick<AgentComponent, "id" | "title" | "source" | "file" | "files" | "design" | "usedIn">;
+    readonly component: Pick<AgentComponent, "id" | "title" | "source" | "file" | "files" | "statuses" | "design" | "usedIn">;
     /**
      * The component's docs as the props panel reads them (its props, their types, defaults and TSDoc); none when the
      * story file names no component, or its docs could not be read (the reason is then in `problems`).
@@ -165,6 +179,21 @@ export type StoryDocument = {
     readonly design?: AgentDesign;
     /** The story's args once its module ran, the meta's under its own; only what can be written as JSON. */
     readonly args: Readonly<Record<string, unknown>>;
+    /**
+     * The story's code, as its Code tab shows and copies it: its `render` as written, or the component in the
+     * framework's code with the args its file writes as code (functions, elements) as written and the rest from their
+     * values, those set through `args` from theirs. None when it cannot be written: the story file did not load, or
+     * the framework's code writer does not load on the server.
+     */
+    readonly code?: string;
+    /**
+     * The props its values can set, as the panel sets them: each one's control and what its value looks like, its
+     * `argTypes` taken into account. Give values through `args` of `forgebook story` or of the tools, or in the address's
+     * `args=` as JSON.
+     */
+    readonly controls: readonly StoryControl[];
+    /** What became of the values asked for (`args`), checked as a link's are; the links carry those it takes. */
+    readonly setArgs?: Pick<SetArgs, "accepted" | "dropped">;
     /** What went wrong while reading it: its module failing to load, its docs failing to be read. */
     readonly problems: readonly string[];
     /**
@@ -224,12 +253,12 @@ export type PageDocument = {
     readonly problems: readonly string[];
 };
 /** A token in a list: what to write, without what a list does not need. */
-export type AgentTokenSummary = Pick<DesignToken, "name" | "type" | "value" | "modes" | "deprecated" | "isThemeOnly">;
+export type AgentTokenSummary = Pick<DesignToken, "name" | "type" | "value" | "modes" | "deprecated" | "isThemeOnly" | "utility">;
 /** The catalogue's tokens: how many, and the first of them, since agents degrade on long answers. */
 export type TokensDocument = {
     /** The shape's version. */
     readonly schema: AgentSchema;
-    /** Whether the catalogue or one of its sources names a tokens file at all. */
+    /** Whether there is a system to ask about: a tokens file named by the catalogue or a source, or tokens read from the application. */
     readonly isConfigured: boolean;
     /** How many tokens match, whatever the limit. */
     readonly total: number;
@@ -241,6 +270,10 @@ export type TokensDocument = {
     readonly problems: readonly string[];
     /** The tokens listed here that two authors give different values, with whose stands. */
     readonly clashes: readonly TokenClash[];
+    /** What the tokens were read from, each file with how many it gives; none from an older catalogue. */
+    readonly sources?: readonly TokenSource[];
+    /** What the application's files hold that could not be read without running them, so some tokens may be unknown. */
+    readonly notes?: readonly string[];
 };
 /** One token, with all that is known of it. */
 export type TokenDocument = {
@@ -279,6 +312,8 @@ export type FoundComponentsDocument = {
     readonly query: string;
     /** Up to five, best first; none means nothing in the catalogue holds those words. */
     readonly components: readonly AgentFoundComponent[];
+    /** The words nothing held as typed, and the name each was read as; empty when the query was read as typed. */
+    readonly corrections: readonly SearchCorrection[];
 };
 /** A line of a search's result: something inside a page that matched. */
 export type AgentSearchHit = {
@@ -326,6 +361,8 @@ export type SearchDocument = {
     readonly total: number;
     /** The results, best first; none means nothing in the catalogue holds those words. */
     readonly results: readonly AgentSearchResult[];
+    /** The words nothing held as typed, and the name each was read as; empty when the query was read as typed. */
+    readonly corrections: readonly SearchCorrection[];
     /** What could not be read for the search: the rest still answers. */
     readonly problems: readonly string[];
 };
@@ -338,6 +375,39 @@ export type AgentChangedStory = {
     /** The links that open it. */
     readonly links: StoryLinks;
 };
+/** How a changed UI file is covered: by stories of its own, only through another component's, or by none. */
+export type UiFileCoverage = "own" | "through" | "none";
+/**
+ * A story file `forgebook new` wrote for props its component no longer has: its args may pass a prop that is gone or miss
+ * one that is now required, which neither the frame nor a check would say.
+ */
+export type OutdatedStoryFile = {
+    /** The story file, relative to the repository. */
+    readonly file: string;
+    /** The same file, relative to the catalogue's folder: what a command run there names. */
+    readonly path: string;
+    /** One of its stories' ids, whose `story` answer lists the component's props. */
+    readonly story: string;
+    /** Its component's name. */
+    readonly component: string;
+    /** The props' signature the file says it was written for. */
+    readonly written: string;
+    /** The props' signature now. */
+    readonly current: string;
+    /** What to do. */
+    readonly fix: string;
+};
+/** A changed file a person sees (`changeCoverage.ts`), and the stories that show it. */
+export type ChangedUiFile = {
+    /** The file, relative to the repository. */
+    readonly file: string;
+    /** The same file, relative to the catalogue's folder: what a command run there names. */
+    readonly path: string;
+    /** How it is covered. */
+    readonly coverage: UiFileCoverage;
+    /** The ids of the stories that reach it. */
+    readonly stories: readonly string[];
+};
 /** The stories a change touches. */
 export type ChangedStoriesDocument = {
     /** The shape's version. */
@@ -348,8 +418,217 @@ export type ChangedStoriesDocument = {
     readonly files: readonly string[];
     /** The stories that reach them. */
     readonly stories: readonly AgentChangedStory[];
-    /** What could not be read: a group whose usage failed. */
+    /** The changed files a person sees and that this catalogue can show, each with its stories. */
+    readonly uiFiles: readonly ChangedUiFile[];
+    /** The changed files a person sees that no story reaches and another catalogue of the repository answers for. */
+    readonly outside: readonly string[];
+    /** What could not be read: a group whose usage failed, a story file (`unread`). */
     readonly problems: readonly string[];
+    /** The story files that cannot be read, whose stories no change can reach: a check of a change fails on them. */
+    readonly unread?: readonly string[];
+    /** The story files the change reaches that were written for other props; absent when there are none. */
+    readonly outdated?: readonly OutdatedStoryFile[];
+};
+/** How `verify` ended. */
+export type VerifyVerdict = 
+/** Every changed UI file ran in stories, every check ran, and nothing was found. */
+"verified"
+/** Nothing was found, but `skipped` names what was not checked. */
+ | "partly-verified"
+/**
+ * A changed UI file has no story that ran, a story that reaches the change was never seen in its final state (its frame
+ * gave up on what it loads: `notVerified`), a changed published component cannot be seen by an agent (`unseen`), the catalogue has a problem that stops it telling, or nothing changed since
+ * a start nobody named: the work may be committed where this cannot see it.
+ */
+ | "not-verified"
+/** A check found a problem. */
+ | "failed"
+/** No UI file changed; `skipped` names what was not checked. */
+ | "nothing-to-verify";
+/** A changed UI file, as `verify` ends up with it. */
+export type VerifiedUiFile = {
+    /** The file, relative to the repository. */
+    readonly file: string;
+    /** How it is covered by stories that ran; `none` when none of those that reach it ran. */
+    readonly coverage: UiFileCoverage;
+    /** How many stories that ran reach it. */
+    readonly stories: number;
+    /** Why it is not verified. */
+    readonly reason?: string;
+    /** What to do about it: the command to run, when there is one. */
+    readonly fix?: string;
+};
+/** A story and view that found something. */
+export type VerifyFailure = {
+    /** The story's id. */
+    readonly storyId: string;
+    /** The view, in the address's form; empty for the default. */
+    readonly view: string;
+    /** What it found. */
+    readonly problems: StoryCheckResult["problems"];
+    /** The links that open the story; those of a server started for the run would be dead by now. */
+    readonly links?: StoryLinks;
+};
+/** A static file the change's stories asked for that is not there: said, never counted against the change. */
+export type VerifyWarning = StoryWarning & {
+    /** The stories that asked for it, each once. */
+    readonly stories: readonly string[];
+};
+/** The one answer to whether a change is verified. */
+export type VerifyDocument = {
+    /** The shape's version: this shape is not the first `verify` answered. */
+    readonly schema: 2;
+    /** How it ended; `not-verified` and `failed` exit non-zero. */
+    readonly verdict: VerifyVerdict;
+    /** The verdict in one line, what was not checked included. */
+    readonly summary: string;
+    /** What was not checked: never read an empty list of problems as all clear when these are named. */
+    readonly skipped: readonly string[];
+    /** What the change is measured from, as named. */
+    readonly since: string;
+    /** The commit that is: where the branch left `since`. */
+    readonly base: string;
+    /** The views the stories ran in: every variant the browser tests check, or `quick`'s default view. */
+    readonly variants: "all" | "default";
+    /** The files changed, relative to the repository. */
+    readonly files: readonly string[];
+    /** The changed UI files. */
+    readonly uiFiles: readonly VerifiedUiFile[];
+    /** How many stories reach the change. */
+    readonly storyCount: number;
+    /** The first of them, with the links that open them: a shared sheet reaches every story, and an answer stays short. */
+    readonly stories: readonly AgentChangedStory[];
+    /** How many story and view pairs ran. */
+    readonly ran: number;
+    /** The pairs that found something, with the links that open the story; those that pass are only counted. */
+    readonly failures: readonly VerifyFailure[];
+    /** The pairs no check saw in their final state: their frame gave up on what the story loads. None of them passed. */
+    readonly notVerified: readonly VerifyNotVerified[];
+    /** What the stories found that does not fail the change, one per file: static files that answer 404. */
+    readonly warnings: readonly VerifyWarning[];
+    /** What the change adds, by `check-code`. */
+    readonly code: {
+        /** What was checked. */
+        readonly checked: readonly CodeRule[];
+        /** What breaks the design system in a changed UI file: these fail. */
+        readonly problems: readonly CodeProblem[];
+        /** What it found in a file no one sees: a turned-off check, a deleted test. Said, and not a failure. */
+        readonly notes: readonly CodeProblem[];
+        /** What the values were compared with, each file with how many tokens it gives. */
+        readonly tokenSources?: readonly TokenSource[];
+        /** What the application's files hold that could not be read without running them. */
+        readonly tokenNotes?: readonly string[];
+        /** The values a comment in the change says are meant. */
+        readonly excused?: readonly ExcusedValue[];
+        /** What it found to weigh and not to fail on. */
+        readonly advice?: readonly CodeAdvice[];
+    };
+    /** The story files the change reaches that were written for other props, each with its fix; absent when none. */
+    readonly outdated?: readonly OutdatedStoryFile[];
+    /** How many problems there are, in `failures`, `code.problems` and `outdated` together: those the change brought. */
+    readonly problems: number;
+    /**
+     * The problems the stories had on the base as well, which the verdict does not count: present when the stories that
+     * found something ran again on the base. `--all-problems` counts them.
+     */
+    readonly existing?: {
+        /** How many. */
+        readonly problems: number;
+        /** The pairs that had them, with the links that open the story. */
+        readonly failures: readonly VerifyFailure[];
+    };
+    /** The changed published components an agent cannot see: these leave the change not verified. */
+    readonly unseen: readonly UnseenComponent[];
+};
+/** What hides a published component from an agent. */
+export type UnseenMissing = "story" | "listed-story" | "props" | "tsdoc";
+/** One thing that hides a published component from an agent, with what to do about it. */
+export type UnseenReason = {
+    /** What is missing. */
+    readonly missing: UnseenMissing;
+    /** Why it hides the component. */
+    readonly reason: string;
+    /** What to do about it. */
+    readonly fix: string;
+};
+/** A published component an agent cannot see. */
+export type UnseenComponent = {
+    /** The file that declares it, relative to the repository. */
+    readonly file: string;
+    /** Its name. */
+    readonly component: string;
+    /** What hides it. */
+    readonly reasons: readonly UnseenReason[];
+};
+/** What `forgebook visibility` answers, and the route `verify` asks with a commit. */
+export type VisibilityDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The commit the change is measured from; none when every published component was read. */
+    readonly since?: string;
+    /** The packages that publish components, as their manifests name them; none, with nothing `skipped`, means nothing is published here. */
+    readonly packages: readonly string[];
+    /** How many published component files were looked at. */
+    readonly checked: number;
+    /** Those an agent cannot see. */
+    readonly unseen: readonly UnseenComponent[];
+    /** What could not be looked at: an entry not led back to a source, docs turned off. */
+    readonly skipped: readonly string[];
+};
+/** One state a change touches, as `proof` compares it with where the change started. */
+export type ProofState = {
+    /** The story's id. */
+    readonly storyId: string;
+    /** The view's name; empty for the default. */
+    readonly view: string;
+    /**
+     * How it compares: as a comparison says, or `unstable` when two pictures of the same code differ here too, so the
+     * difference proves nothing.
+     */
+    readonly status: Exclude<StoryDiffStatus, "same"> | "unstable";
+    /** The share of the picture that changed, 0 to 100. */
+    readonly percent: number;
+    /** The pictures, relative to the proof's folder; those a state has. */
+    readonly pictures: {
+        /** Where the change started. */
+        readonly before?: string;
+        /** With the change. */
+        readonly after?: string;
+        /** With the change, what moved marked. */
+        readonly marked?: string;
+    };
+};
+/** What `forgebook proof` answers and what a pull request's comment is written from. */
+export type ProofDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The commit compared with: where the checked-out commit left the ref named. */
+    readonly base: string;
+    /** The commit shown: on a pull request's run, the commit that merges it. */
+    readonly head: string;
+    /** `verify`'s verdict on the change. */
+    readonly verdict: VerifyVerdict;
+    /** `verify`'s line. */
+    readonly summary: string;
+    /** The states that differ, are new, were removed or did not draw. */
+    readonly states: readonly ProofState[];
+    /** How many states were compared and are the same. */
+    readonly same: number;
+    /** What was checked, in words. */
+    readonly checked: readonly string[];
+    /** What was not, in words: never read an empty list of states as all clear when these are named. */
+    readonly notChecked: readonly string[];
+};
+/** A story and view whose checks did not run, since its frame gave up on what the story loads. */
+export type VerifyNotVerified = {
+    /** The story's id. */
+    readonly storyId: string;
+    /** The view, or the variant's name. */
+    readonly view: string;
+    /** Why, as the frame says it. */
+    readonly notVerified: string;
+    /** The links that open the story. */
+    readonly links?: AgentChangedStory["links"];
 };
 /** What a change adds that breaks the design system. */
 export type CheckedCodeDocument = {
@@ -357,12 +636,24 @@ export type CheckedCodeDocument = {
     readonly schema: AgentSchema;
     /** What the change is measured from. */
     readonly since: string;
-    /** What was checked. Props, imports and deprecated components never are: a clean answer says no more than this. */
+    /** What was checked. Props never are, since the type checker does: a clean answer says no more than this. */
     readonly checked: readonly CodeRule[];
     /** What was not, and why: an agent must not read an empty list as all clear when these were skipped. */
     readonly skipped: readonly string[];
     /** What it found, by file and line. */
     readonly problems: readonly CodeProblem[];
+    /** What it found to weigh and not to fail on: a component that may be one that exists, what `@useWhen` says of an import, a bare number in an object that may be a style. */
+    readonly advice?: readonly CodeAdvice[];
+    /** What the values were compared with, each file with how many tokens it gives; none from an older catalogue. */
+    readonly tokenSources?: readonly TokenSource[];
+    /** How many tokens two files give different values: `forgebook tokens` names them. */
+    readonly tokenClashes?: number;
+    /** What the application's files hold that could not be read without running them, so some tokens may be unknown. */
+    readonly tokenNotes?: readonly string[];
+    /** The changed files whose values were not compared, being outside the folder whose system was read. */
+    readonly notCompared?: readonly string[];
+    /** The values a comment in the change says are meant, each with the comment's reason. */
+    readonly excused?: readonly ExcusedValue[];
 };
 /** What the open frames reported while someone edited, and the story index's problems. */
 export type ErrorsDocument = {
@@ -395,6 +686,41 @@ export type AgentPlugin = {
     /** Whether it runs code around every story. */
     readonly runsInFrames: boolean;
 };
+/** A switch's value as the documents give it. */
+export type AgentSwitchValue = {
+    /** The value, as the address writes it. */
+    readonly value: string;
+    /** Its name. */
+    readonly label: string;
+    /** What to write in a view to draw it (`look=night`). */
+    readonly view: string;
+    /** The values it sets on other switches while drawn, by switch id. */
+    readonly implies?: Readonly<Record<string, string>>;
+    /** Its own style sheet, by its path from the configuration's folder. */
+    readonly sheet?: string;
+    /** What a gallery shows of it: a picture by its path from the configuration's folder, or colours and a font's name. */
+    readonly preview?: SwitchPreview;
+};
+/** What `forgebook switches` and `list_switches` answer. */
+export type SwitchesDocument = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** The catalogue's switches, the ready-made ones among them, in their order. */
+    readonly switches: readonly {
+        /** Its id, the address's parameter. */
+        readonly id: string;
+        /** Its name. */
+        readonly label: string;
+        /** The value when a view names none. */
+        readonly default: string;
+        /** How the shell offers it. */
+        readonly control: SwitchControlKind;
+        /** What the catalogue reads of it; none for a switch only the library reads. */
+        readonly role?: SwitchRole;
+        /** Its values, in their order. */
+        readonly values: readonly AgentSwitchValue[];
+    }[];
+};
 /** What `forgebook plugins` and `list_plugins` answer. */
 export type PluginsDocument = {
     /** The version of this document. */
@@ -404,3 +730,24 @@ export type PluginsDocument = {
     /** The plugins the configuration lists, in order. */
     readonly plugins: readonly AgentPlugin[];
 };
+/** The list of the agents' guide, as `forgebook guide --json` and `get_guide` answer with no topic. */
+export type GuideListDocument = {
+    /** The document's version. */
+    readonly schema: AgentSchema;
+    /** Each topic: its name, as `forgebook guide <name>` takes it, and what it is about. */
+    readonly topics: ReadonlyArray<{
+        readonly topic: string;
+        readonly about: string;
+    }>;
+    /** The frameworks found in this project, whose topics are the ones to read. */
+    readonly frameworks: readonly string[];
+};
+/** One topic of the agents' guide, as `forgebook guide <topic> --json` and `get_guide` answer. */
+export type GuideDocument = {
+    /** The document's version. */
+    readonly schema: AgentSchema;
+    /** The topic's name. */
+    readonly topic: string;
+    /** Its Markdown. */
+    readonly text: string;
+};

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

@@ -5,7 +5,10 @@
  *
  * @module
  */
+import type { AddressTexts } from "../addressTexts.ts";
 import { type LoadedPreview } from "../frame/storyModule.ts";
+import type { NamedValues } from "../namedValues.ts";
+import { type CustomControlsRead } from "../storyControls.ts";
 import { type StoryLocation, type StoryTree } from "../storyTree.ts";
 import type { UsageIndex } from "../usedIn.ts";
 import type { ChangedStoriesDocument, CheckedCodeDocument, ErrorsDocument, FoundComponentsDocument, NearestTokensDocument, PageDocument, PagesDocument, SearchDocument, StoriesDocument, StoryDocument, StoryLinks, TokenDocument, TokensDocument } from "./agent.types.ts";
@@ -57,7 +60,22 @@ export type LoadedStoryParts = {
     };
     /** The catalogue's previews merged, whose args are under every story's. */
     readonly preview?: LoadedPreview;
+    /** The source's named values; none when it names none. */
+    readonly namedValues?: NamedValues | undefined;
+    /** The values an agent asks to set, as JSON; none reads the story as it is. */
+    readonly setArgs?: string | undefined;
+    /** The custom controls' schemas, those whose module could be read, and why the others could not. */
+    readonly customControls?: CustomControlsRead | undefined;
+    /** How the framework's stories take a link's texts: what the shell would refuse is said here too. */
+    readonly addressTexts?: AddressTexts | undefined;
 };
+/**
+ * The custom controls a story names, read from its module before its document is made: their modules load for it.
+ *
+ * @param module - the story file's module, as the dev server loaded it.
+ * @param location - the story's place in the tree.
+ */
+export declare const customControlNames: (module: LoadedStoryParts["module"], location: StoryLocation) => readonly string[];
 /**
  * One story in detail.
  *
@@ -77,6 +95,11 @@ export type StoriesFilter = {
     readonly source?: string | undefined;
     /** Text a component's title holds, any case (`button`); every component when none. */
     readonly component?: string | undefined;
+    /**
+     * Tags, each `name` or `!name`, as the catalogue's address writes them: only the stories holding any `name` and no
+     * `!name`, and the components left with one; every story when none.
+     */
+    readonly tags?: readonly string[] | undefined;
 };
 /**
  * The stories document cut to the components a filter keeps; its sources and problems kept whole.