forgebook 0.1.7 → 0.2.0

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

@@ -9,23 +9,60 @@
  *
  * @module
  */
-import type { ComponentDocs } from "../componentDocs.ts";
+import type { StoryDeviceSetting } from "@forgebook/story-format/csf";
+import type { ComponentDocs, UsageGuidance } from "../componentDocs.ts";
+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 { FoundComponent } from "./findComponent.ts";
+import type { NearestTokens } from "./nearestToken.ts";
+import type { TokenClash } from "./tokenClashes.ts";
 /** The version of the documents' shape. */
 export type AgentSchema = 1;
 /** Where a story opens, in the view the answer describes. */
 export type StoryLinks = {
     /** Its page in the catalogue (the shell, the story selected). */
     readonly address: string;
+    /** Its component's page, where an audience in the view (`audience=designer`) reorders and filters what is drawn. */
+    readonly component: string;
     /** Its frame alone: the story's own document, as the tests open it. */
     readonly frame: string;
+    /** The story with no chrome, in the catalogue's theme: what a person pastes in a wiki or an iframe. */
+    readonly embed: string;
+};
+/** A design's place in Figma: what to give a person, or a tool that reads Figma. */
+export type AgentDesignLink = {
+    /** The link that opens it in Figma. */
+    readonly figma: string;
+    /** The file's key. */
+    readonly fileKey: string;
+    /** The branch's key, for a link to a branch of the file. */
+    readonly branchKey?: string;
+    /** The node, as Figma's API writes it (`12:34`); none for a link to the whole file. */
+    readonly nodeId?: string;
+};
+/** A story's design: its place in Figma, and where a person sees it beside the story. */
+export type AgentDesign = AgentDesignLink & {
+    /**
+     * The story's page in the catalogue, on the Design tab `@forgebook/plugin-figma` adds; on its first tab where the
+     * catalogue lists no such plugin or turned the tab off.
+     */
+    readonly address: string;
 };
 /** A story, as the list of stories gives it. */
 export type AgentStory = {
-    /** `<source>:<title>--<export>` in kebab case: what `forgebook story` takes. */
+    /**
+     * `<source>:<component>--<story>`, the rest as Storybook's id: what `forgebook story` takes, which also takes the id
+     * an earlier rule gave it.
+     */
     readonly id: string;
     /** The name the catalogue shows. */
     readonly name: string;
+    /** The story file it is written in, relative to the module that declares the source. */
+    readonly file: string;
     /** The named export in the story file. */
     readonly exportName: string;
     /** What it shows and what to notice, from its TSDoc; none when it has none. */
@@ -36,6 +73,16 @@ export type AgentStory = {
     readonly isUnlisted: boolean;
     /** The height its scene declares (`parameters.height`), in CSS px, when it declares one. */
     readonly height?: number;
+    /** Whether it is about logic, not looks (`parameters.logic`): a hook's or a function's scene. */
+    readonly isLogic: boolean;
+    /** Whether a `play` function acts on it. */
+    readonly hasPlay: boolean;
+    /**
+     * The device it is shown in by default (`parameters.device`, its own fields over the meta's), when either sets one;
+     * the catalogue's `device` sits under it. Add the model's id to a view (`forgebook shot <id> --view iphone-16`) for
+     * a framed picture.
+     */
+    readonly device?: StoryDeviceSetting;
     /** Where it opens. */
     readonly links: StoryLinks;
 };
@@ -50,18 +97,24 @@ export type AgentUsingComponent = {
     /** The ids of its stories that use the component. */
     readonly stories: readonly string[];
 };
-/** A component (a story file) and its stories. */
+/** A component (the story files with its title) and its stories. */
 export type AgentComponent = {
-    /** `<source>:<title>` in kebab case. */
+    /** `<source>:<component>`, the part of its stories' ids before `--`. */
     readonly id: string;
     /** Its whole title (`Inputs/Selection/Select`). */
     readonly title: string;
     /** The id of the source it belongs to. */
     readonly source: string;
-    /** The story file, relative to the module that declares the source. */
+    /**
+     * Its first story file, relative to the module that declares the source: the one its docs and its page come from.
+     */
     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 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. */
+    readonly design?: AgentDesignLink;
     /**
      * The other components of its source whose stories use it, direct users first; only when asked for (it reads the
      * package's import graph) and the catalogue offers it.
@@ -95,17 +148,210 @@ 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" | "usedIn">;
+    readonly component: Pick<AgentComponent, "id" | "title" | "source" | "file" | "files" | "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`).
      */
     readonly docs: ComponentDocs | undefined;
+    /** Its design: its own `parameters.design.figma`, else its component's; none when it has none. */
+    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>>;
     /** What went wrong while reading it: its module failing to load, its docs failing to be read. */
     readonly problems: readonly string[];
 };
+/** Where a docs page opens, in the view the answer describes. */
+export type PageLinks = {
+    /** Its page in the catalogue; a heading's anchor goes after it as the fragment. */
+    readonly address: string;
+};
+/** A docs page, as the list of pages gives it. */
+export type AgentPage = {
+    /** `<source>:<title>` in kebab case, or `home` for the catalogue's written home: what `forgebook page` takes. */
+    readonly id: string;
+    /** Its whole title (`Guides/Theming`). */
+    readonly title: string;
+    /** The id of the source it belongs to; empty for the written home, which belongs to the catalogue. */
+    readonly source: string;
+    /** Its file, relative to the module that declares the source. */
+    readonly file: string;
+    /** What it is about, in a sentence; none when it does not say. */
+    readonly description: string | undefined;
+    /** The ids of the stories it shows, which `forgebook story` takes. */
+    readonly stories: readonly string[];
+    /** The ids of the components whose API tables it shows. */
+    readonly components: readonly string[];
+    /** Where it opens. */
+    readonly links: PageLinks;
+};
+/** The docs pages a catalogue has, in reading order, and what is wrong in the index. */
+export type PagesDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The catalogue's name. */
+    readonly title: string;
+    /** Every page. */
+    readonly pages: readonly AgentPage[];
+    /** The catalogue's written home (`forgebook.home.md`), which `forgebook page home` reads; none for the generated one. */
+    readonly home?: AgentPage;
+    /** One message per problem the index found: a page naming a story that is not there, a title taken twice. */
+    readonly problems: readonly string[];
+};
+/** One docs page, to read. */
+export type PageDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The page. */
+    readonly page: AgentPage;
+    /** Its headings, each anchor the fragment of its address. */
+    readonly headings: readonly DocHeading[];
+    /** Its Markdown, without its front matter; empty when it could not be read (the reason is then in `problems`). */
+    readonly text: string;
+    /** What went wrong while reading it. */
+    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">;
+/** 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. */
+    readonly isConfigured: boolean;
+    /** How many tokens match, whatever the limit. */
+    readonly total: number;
+    /** How many of each type. */
+    readonly types: Readonly<Record<string, number>>;
+    /** The tokens, up to the limit asked for, in the files' order. */
+    readonly tokens: readonly AgentTokenSummary[];
+    /** What in the tokens files could not be read. */
+    readonly problems: readonly string[];
+    /** The tokens listed here that two authors give different values, with whose stands. */
+    readonly clashes: readonly TokenClash[];
+};
+/** One token, with all that is known of it. */
+export type TokenDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The token. */
+    readonly token: DesignToken;
+    /** What in the tokens files could not be read. */
+    readonly problems: readonly string[];
+    /** Whose value stands, when two authors give this token different ones. */
+    readonly clashes: readonly TokenClash[];
+};
+/** The tokens nearest a value written by hand. */
+export type NearestTokensDocument = NearestTokens & {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The value asked about. */
+    readonly value: string;
+    /** What in the tokens files could not be read. */
+    readonly problems: readonly string[];
+};
+/** A component an intent search found, with what a next step needs. */
+export type AgentFoundComponent = FoundComponent & {
+    /** Its first story's id, to pass to `story`. */
+    readonly story: string | undefined;
+    /** The links that open that story. */
+    readonly links: StoryLinks | undefined;
+    /** When to use it and when not, when its TSDoc says. */
+    readonly guidance?: UsageGuidance;
+};
+/** The components a query describes. */
+export type FoundComponentsDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The query. */
+    readonly query: string;
+    /** Up to five, best first; none means nothing in the catalogue holds those words. */
+    readonly components: readonly AgentFoundComponent[];
+};
+/** A line of a search's result: something inside a page that matched. */
+export type AgentSearchHit = {
+    /** What it is: a prop, an event, a story, a heading, text, a description. */
+    readonly kind: SearchHitKind;
+    /** Its name: the prop, the story, the heading; none for plain text. */
+    readonly name?: string;
+    /** The words around the match. */
+    readonly text: string;
+    /** The address that opens the page at it. */
+    readonly address: string;
+};
+/** A search's result: a component or a docs page. */
+export type AgentSearchResult = {
+    /** What it is. */
+    readonly kind: SearchResult["kind"];
+    /** Its id: a docs page's goes to `page`. */
+    readonly id: string;
+    /** Its name. */
+    readonly name: string;
+    /** Where it sits. */
+    readonly place: string;
+    /** How well it matches: higher is better, only comparable within an answer. */
+    readonly score: number;
+    /** The words of the query it holds. */
+    readonly matched: readonly string[];
+    /** The words of the query it does not. */
+    readonly missed: readonly string[];
+    /** Why its name is there; empty when only what is inside it matched. */
+    readonly reasons: readonly SearchReason[];
+    /** The best of what matched inside it. */
+    readonly hits: readonly AgentSearchHit[];
+    /** How many things inside it matched, those not listed included. */
+    readonly hitCount: number;
+    /** The address that opens it. */
+    readonly address: string;
+};
+/** What a search finds across a catalogue. */
+export type SearchDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** The query. */
+    readonly query: string;
+    /** How many results there are, those past `limit` included. */
+    readonly total: number;
+    /** The results, best first; none means nothing in the catalogue holds those words. */
+    readonly results: readonly AgentSearchResult[];
+    /** What could not be read for the search: the rest still answers. */
+    readonly problems: readonly string[];
+};
+/** A story a change touches. */
+export type AgentChangedStory = {
+    /** Its id. */
+    readonly id: string;
+    /** Its component's title. */
+    readonly title: string;
+    /** The links that open it. */
+    readonly links: StoryLinks;
+};
+/** The stories a change touches. */
+export type ChangedStoriesDocument = {
+    /** The shape's version. */
+    readonly schema: AgentSchema;
+    /** What the change is measured from. */
+    readonly since: string;
+    /** The files changed, relative to the repository. */
+    readonly files: readonly string[];
+    /** The stories that reach them. */
+    readonly stories: readonly AgentChangedStory[];
+    /** What could not be read: a group whose usage failed. */
+    readonly problems: readonly string[];
+};
+/** What a change adds that breaks the design system. */
+export type CheckedCodeDocument = {
+    /** The shape's version. */
+    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. */
+    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 the open frames reported while someone edited, and the story index's problems. */
 export type ErrorsDocument = {
     /** The shape's version. */
@@ -117,4 +363,32 @@ export type ErrorsDocument = {
     /** The story index's problems now (a broken story file, a title taken twice). */
     readonly problems: readonly string[];
 };
-//# sourceMappingURL=agent.types.d.ts.map
+/** A plugin as the documents give it. */
+export type AgentPlugin = {
+    /** Its id. */
+    readonly id: string;
+    /** The panel tabs it adds. */
+    readonly tabs: readonly {
+        /** The tab's id: `tab=<id>` in a view opens it. */
+        readonly id: string;
+        /** Its name. */
+        readonly label: string;
+        /** The story it is offered for; none for every story. */
+        readonly when?: PluginCondition;
+    }[];
+    /** The ids of the switches it adds: `<id>=<value>` in a view sets one. */
+    readonly switches: readonly string[];
+    /** The fences of the docs blocks it adds. */
+    readonly docBlocks: readonly string[];
+    /** Whether it runs code around every story. */
+    readonly runsInFrames: boolean;
+};
+/** What `forgebook plugins` and `list_plugins` answer. */
+export type PluginsDocument = {
+    /** The version of this document. */
+    readonly schema: 1;
+    /** The versions of the plugin API this Forgebook speaks. */
+    readonly apiVersions: readonly number[];
+    /** The plugins the configuration lists, in order. */
+    readonly plugins: readonly AgentPlugin[];
+};

package/dist/src/vite/agent.types.js

@@ -1 +1,11 @@
-//# sourceMappingURL=agent.types.js.map
+/**
+ * The documents the catalogue answers tools and agents with: the stories a catalogue has, and one story in detail.
+ * The dev server makes them (`/__forgebook/api/`), `forgebook stories` and `forgebook story` print them, and
+ * `forgebook mcp` hands them to an agent.
+ *
+ * @remarks
+ * Each document carries `schema`, so a tool can refuse a shape it does not know; a change that breaks a reader bumps
+ * it. Every story carries its links, so a person can open what a tool talks about in the same view.
+ *
+ * @module
+ */

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

@@ -8,7 +8,7 @@
 import { type LoadedPreview } from "../frame/storyModule.ts";
 import { type StoryLocation, type StoryTree } from "../storyTree.ts";
 import type { UsageIndex } from "../usedIn.ts";
-import type { ErrorsDocument, StoriesDocument, StoryDocument, StoryLinks } from "./agent.types.ts";
+import type { ChangedStoriesDocument, CheckedCodeDocument, ErrorsDocument, FoundComponentsDocument, NearestTokensDocument, PageDocument, PagesDocument, SearchDocument, StoriesDocument, StoryDocument, StoryLinks, TokenDocument, TokensDocument } from "./agent.types.ts";
 /** Where the catalogue is served, for the links: its page and its frame page. */
 export type CataloguePages = {
     /** The catalogue's page (`http://localhost:5173/`). */
@@ -103,4 +103,57 @@ export declare const isStoriesDocument: (value: unknown) => value is StoriesDocu
  * @param value - the answer's body.
  */
 export declare const isStoryDocument: (value: unknown) => value is StoryDocument;
-//# sourceMappingURL=agentApi.d.ts.map
+/**
+ * Whether a value is the tokens document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isTokensDocument: (value: unknown) => value is TokensDocument;
+/**
+ * Whether a value is one token's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isTokenDocument: (value: unknown) => value is TokenDocument;
+/**
+ * Whether a value is the nearest tokens' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isNearestTokensDocument: (value: unknown) => value is NearestTokensDocument;
+/**
+ * Whether a value is an intent search's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isFoundComponentsDocument: (value: unknown) => value is FoundComponentsDocument;
+/**
+ * Whether a value is a search's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isSearchDocument: (value: unknown) => value is SearchDocument;
+/**
+ * Whether a value is the changed stories' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isChangedStoriesDocument: (value: unknown) => value is ChangedStoriesDocument;
+/**
+ * Whether a value is the code check's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isCheckedCodeDocument: (value: unknown) => value is CheckedCodeDocument;
+/**
+ * Whether a value is the docs pages' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isPagesDocument: (value: unknown) => value is PagesDocument;
+/**
+ * Whether a value is one docs page's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export declare const isPageDocument: (value: unknown) => value is PageDocument;

package/dist/src/vite/agentApi.js

@@ -6,10 +6,11 @@
  * @module
  */
 import { isComponentDocs } from "../componentDocs.js";
+import { embedAddressOf } from "../embedCode.js";
 import { NO_PREVIEW, readStory } from "../frame/storyModule.js";
 import { isLiveErrorReport } from "../liveErrors.js";
-import { componentId, findComponent } from "../storyTree.js";
-import { frameAddressOf, storyAddressOf } from "../viewState.js";
+import { findComponentByTitle } from "../storyTree.js";
+import { componentAddressOf, frameAddressOf, storyAddressOf } from "../viewState.js";
 /**
  * A story's links in a view.
  *
@@ -19,19 +20,52 @@ import { frameAddressOf, storyAddressOf } from "../viewState.js";
  */
 export const storyLinks = (pages, id, view) => ({
     address: storyAddressOf(pages.page, id, view),
-    frame: frameAddressOf(pages.frame, id, view)
+    // the last `--` ends the component's id: a source's own id may hold one
+    component: componentAddressOf(pages.page, id.slice(0, id.lastIndexOf("--")), view),
+    frame: frameAddressOf(pages.frame, id, view),
+    embed: embedAddressOf(pages.page, id, view)
 });
 /** A story of the tree as the documents give it. */
 const agentStory = (story, isUnlisted, pages, view) => ({
     id: story.id,
     name: story.name,
+    file: story.file,
     exportName: story.exportName,
     description: story.description,
     tags: story.tags,
     isUnlisted,
     ...(story.height === undefined ? {} : { height: story.height }),
+    isLogic: story.isLogic,
+    hasPlay: story.hasPlay,
+    ...(story.device === undefined ? {} : { device: story.device }),
     links: storyLinks(pages, story.id, view)
 });
+/** A design's link as the documents give it. */
+const agentDesignLink = (link) => ({
+    figma: link.url,
+    fileKey: link.fileKey,
+    ...(link.branchKey === undefined ? {} : { branchKey: link.branchKey }),
+    ...(link.nodeId === undefined ? {} : { nodeId: link.nodeId })
+});
+/**
+ * A story's design as its document gives it.
+ *
+ * @param story - the story.
+ * @param pages - where the catalogue is served, for the link to its Design tab.
+ * @param view - the view the link opens in; empty for the default view.
+ */
+const agentDesign = (story, pages, view) => {
+    if (story.design === undefined)
+        return {};
+    const onTab = new URLSearchParams(view);
+    onTab.set("tab", "figma");
+    return {
+        design: {
+            ...agentDesignLink(story.design),
+            address: storyLinks(pages, story.id, onTab.toString()).address
+        }
+    };
+};
 /**
  * A component's "Used in" as the documents give it: the users the tree still has, by their ids and their stories' ids.
  *
@@ -41,27 +75,28 @@ const agentStory = (story, isUnlisted, pages, view) => ({
  * @param title - the component's title.
  */
 const agentUsers = (tree, sourceId, usage, title) => (usage[title] ?? []).flatMap((user) => {
-    const id = componentId(sourceId, user.title);
-    const found = findComponent(tree, id)?.component;
+    const found = findComponentByTitle(tree, sourceId, user.title)?.component;
     if (found === undefined)
         return [];
     const stories = [...found.stories, ...found.unlisted]
         .filter((story) => user.stories.includes(story.exportName))
         .map((story) => story.id);
-    return [{ id, title: user.title, isDirect: user.isDirect, stories }];
+    return [{ id: found.id, title: user.title, isDirect: user.isDirect, stories }];
 });
 /** A component of the tree as the documents give it, its listed stories first, its "Used in" when given. */
 const agentComponent = (location, pages, view, usage) => {
     const { source, component } = location;
     return {
-        id: componentId(source.id, component.title),
+        id: component.id,
         title: component.title,
         source: source.id,
         file: component.file,
+        files: component.files,
         stories: [
             ...component.stories.map((story) => agentStory(story, false, pages, view)),
             ...component.unlisted.map((story) => agentStory(story, true, pages, view))
         ],
+        ...(component.design === undefined ? {} : { design: agentDesignLink(component.design) }),
         ...(usage === undefined
             ? {}
             : { usedIn: agentUsers(usage.tree, source.id, usage.index, component.title) })
@@ -157,8 +192,11 @@ export const storyDocument = (location, parts, pages, view, usage) => {
             title: component.title,
             source: component.source,
             file: component.file,
+            files: component.files,
+            ...(component.design === undefined ? {} : { design: component.design }),
             ...(component.usedIn === undefined ? {} : { usedIn: component.usedIn })
         },
+        ...agentDesign(location.story, pages, view),
         docs,
         args,
         problems
@@ -213,4 +251,89 @@ export const isStoriesDocument = (value) => isRecord(value) &&
  * @param value - the answer's body.
  */
 export const isStoryDocument = (value) => isRecord(value) && value["schema"] === 1 && isRecord(value["story"]) && Array.isArray(value["problems"]);
-//# sourceMappingURL=agentApi.js.map
+/**
+ * Whether a value is the tokens document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isTokensDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["tokens"]) &&
+    Array.isArray(value["problems"]) &&
+    Array.isArray(value["clashes"]);
+/**
+ * Whether a value is one token's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isTokenDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    isRecord(value["token"]) &&
+    Array.isArray(value["problems"]) &&
+    Array.isArray(value["clashes"]);
+/**
+ * Whether a value is the nearest tokens' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isNearestTokensDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["matches"]) &&
+    Array.isArray(value["problems"]);
+/**
+ * Whether a value is an intent search's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isFoundComponentsDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    typeof value["query"] === "string" &&
+    Array.isArray(value["components"]);
+/**
+ * Whether a value is a search's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isSearchDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    typeof value["query"] === "string" &&
+    typeof value["total"] === "number" &&
+    Array.isArray(value["results"]) &&
+    Array.isArray(value["problems"]);
+/**
+ * Whether a value is the changed stories' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isChangedStoriesDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["stories"]) &&
+    Array.isArray(value["files"]);
+/**
+ * Whether a value is the code check's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isCheckedCodeDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    typeof value["since"] === "string" &&
+    Array.isArray(value["problems"]);
+/**
+ * Whether a value is the docs pages' document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isPagesDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    Array.isArray(value["pages"]) &&
+    Array.isArray(value["problems"]);
+/**
+ * Whether a value is one docs page's document, as a client receives it over HTTP.
+ *
+ * @param value - the answer's body.
+ */
+export const isPageDocument = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    isRecord(value["page"]) &&
+    typeof value["text"] === "string" &&
+    Array.isArray(value["problems"]);

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

@@ -0,0 +1,25 @@
+import type { AgentComponent, AgentStory, StoriesDocument } from "./agent.types.ts";
+/**
+ * The component an id names: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export declare const namedComponent: (document: StoriesDocument, id: string) => AgentComponent | undefined;
+/**
+ * The story an id names, with its component: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export declare const namedStory: (document: StoriesDocument, id: string) => {
+    readonly component: AgentComponent;
+    readonly story: AgentStory;
+} | undefined;
+/**
+ * The id the former rule gave a story of the document, when it differs from its id: its pictures may still carry it.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export declare const formerIdOf: (component: AgentComponent, story: AgentStory) => string | undefined;