forgebook 0.1.7 → 0.2.0

package/dist/bin/forgebook/prebundleChild.js

@@ -0,0 +1,34 @@
+/**
+ * The child that pre-bundles a catalogue's dependencies on a first start (`prebundleStart.ts`), and ends: what
+ * rolldown took goes back with it. Its exit code tells the server whether the work is done.
+ *
+ * @module
+ */
+import { enableCompileCache } from "node:module";
+import { loadConfigFile } from "../../src/vite/configFile.js";
+import { FRAMES_MODES, withFramePort, withFramesMode } from "./catalogueVite.js";
+import { compileCacheFolder } from "./compileCache.js";
+import { prebundle } from "./prebundleRun.js";
+const folder = compileCacheFolder(import.meta.dirname);
+if (folder !== undefined)
+    enableCompileCache(folder);
+/**
+ * Whether the parent's JSON is what it sends.
+ *
+ * @param value - the JSON, parsed.
+ */
+const isChildData = (value) => typeof value === "object" &&
+    value !== null &&
+    "configFile" in value &&
+    typeof value.configFile === "string" &&
+    "isForced" in value &&
+    typeof value.isForced === "boolean" &&
+    (!("frames" in value) || FRAMES_MODES.some((mode) => mode === value.frames)) &&
+    (!("framePort" in value) || typeof value.framePort === "string");
+const data = JSON.parse(process.argv[2] ?? "null");
+if (!isChildData(data))
+    throw new Error("The pre-bundling child was started without what it needs");
+const config = withFramePort(withFramesMode(await loadConfigFile(data.configFile), data.frames), data.framePort);
+await prebundle(config, data.isForced);
+// done: a handle a plugin left open would keep the server waiting for this process
+process.exit(0);

package/dist/bin/forgebook/prebundleRun.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+/**
+ * The imports Vite's error names as unresolved, when it is that error; its colours, which Vite adds on Windows and in
+ * CI, taken out first.
+ *
+ * @param error - what `optimizeDeps` threw.
+ */
+export declare const unresolvedOf: (error: unknown) => string[];
+/**
+ * Pre-bundles a catalogue's dependencies in this process.
+ *
+ * @remarks
+ * Vite's `optimizeDeps` fails on an import it cannot resolve (stories that import a package not installed), where a
+ * dev server only warns and pre-bundles the rest. So a failure that names such imports is tried once more with them
+ * left out too, kept in a file every later server of the catalogue reads (`unresolvedFile`), which is what the server
+ * would have done; any other failure is thrown, and the server does the work, as it always could. What an earlier
+ * pre-bundling left out stays out unless it is forced: it is part of the pre-bundle's hash.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param isForced - whether to pre-bundle whatever is there, finding again what does not resolve.
+ */
+export declare const prebundle: (config: ResolvedConfig, isForced: boolean) => Promise<void>;

package/dist/bin/forgebook/prebundleRun.js

@@ -0,0 +1,49 @@
+/**
+ * A catalogue's dependencies pre-bundled as `forgebook dev` would on a first start: what the pre-bundling child runs
+ * (`prebundleChild.ts`), and `forgebook prebundle`.
+ *
+ * @module
+ */
+import { rmSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+import { catalogueVite } from "./catalogueVite.js";
+import { keepUnresolved, unresolvedFile, unresolvedImports } from "./viteCache.js";
+/** A line of Vite's error about imports it cannot resolve: the name, then the file that imports it. */
+const UNRESOLVED_LINE = /^\s+(\S+) \(imported by /gm;
+/**
+ * The imports Vite's error names as unresolved, when it is that error; its colours, which Vite adds on Windows and in
+ * CI, taken out first.
+ *
+ * @param error - what `optimizeDeps` threw.
+ */
+export const unresolvedOf = (error) => error instanceof Error
+    ? [...stripVTControlCharacters(error.message).matchAll(UNRESOLVED_LINE)].flatMap((match) => match[1] ?? [])
+    : [];
+/**
+ * Pre-bundles a catalogue's dependencies in this process.
+ *
+ * @remarks
+ * Vite's `optimizeDeps` fails on an import it cannot resolve (stories that import a package not installed), where a
+ * dev server only warns and pre-bundles the rest. So a failure that names such imports is tried once more with them
+ * left out too, kept in a file every later server of the catalogue reads (`unresolvedFile`), which is what the server
+ * would have done; any other failure is thrown, and the server does the work, as it always could. What an earlier
+ * pre-bundling left out stays out unless it is forced: it is part of the pre-bundle's hash.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param isForced - whether to pre-bundle whatever is there, finding again what does not resolve.
+ */
+export const prebundle = async (config, isForced) => {
+    const { optimizeDeps, resolveConfig } = await import("vite");
+    if (isForced)
+        rmSync(unresolvedFile(config.dir), { force: true });
+    try {
+        await optimizeDeps(await resolveConfig(await catalogueVite(config, {}), "serve"), isForced);
+    }
+    catch (error) {
+        const unresolved = unresolvedOf(error);
+        if (unresolved.length === 0)
+            throw error;
+        keepUnresolved(config.dir, [...new Set([...unresolvedImports(config.dir), ...unresolved])]);
+        await optimizeDeps(await resolveConfig(await catalogueVite(config, {}), "serve"), isForced);
+    }
+};

package/dist/bin/forgebook/prebundleStart.d.ts

@@ -0,0 +1,44 @@
+import type { FramesMode } from "./catalogueVite.ts";
+/** What the child is started with, as JSON: what `forgebook dev` was given that the pre-bundle depends on. */
+export type PrebundleChildData = {
+    /** The catalogue's configuration file. */
+    readonly configFile: string;
+    /** Whether to pre-bundle whatever is there (`--force`). */
+    readonly isForced: boolean;
+    /** Where the stories' frames run for this run (`--frames`); the configuration's when none. */
+    readonly frames?: FramesMode;
+    /** The frames' port (`--frame-port`); the configuration's when none. */
+    readonly framePort?: string;
+};
+/**
+ * Pre-bundles a catalogue's dependencies in a child, unless they are there already; a second call for the same
+ * run waits for the first.
+ *
+ * @param data - what the child pre-bundles for.
+ * @returns a promise of whether the child pre-bundled them: `false` when it failed, or was not needed.
+ */
+export declare const prebundleInChild: (data: PrebundleChildData) => Promise<boolean>;
+/** The options of `forgebook dev` the pre-bundling reads. */
+export type DevPrebundleOptions = {
+    /** `--force`. */
+    readonly force?: boolean | undefined;
+    /** `--frames`. */
+    readonly frames?: FramesMode | undefined;
+    /** `--frame-port`. */
+    readonly "frame-port"?: string | undefined;
+};
+/**
+ * The pre-bundling of a `forgebook dev` run: the one its entry started, or one started now.
+ *
+ * @param configFile - the catalogue's configuration file; none when there is none, which pre-bundles nothing.
+ * @param options - the run's options.
+ * @returns a promise of whether the child pre-bundled the dependencies.
+ */
+export declare const prebundleForDev: (configFile: string | undefined, options: DevPrebundleOptions) => Promise<boolean>;
+/**
+ * Starts the pre-bundling before the commands load, for `forgebook dev` run in the catalogue's folder. Any other form
+ * (`--config`, `--force`, the frames' options) is left to the command, which starts it once it has read its options.
+ *
+ * @param args - the command line's arguments.
+ */
+export declare const prebundleEarly: (args: readonly string[]) => void;

package/dist/bin/forgebook/prebundleStart.js

@@ -0,0 +1,82 @@
+/**
+ * Starts a first start's pre-bundling in a child process (`prebundleChild.ts`), from the command's entry or from
+ * `forgebook dev`; light, so the entry can start it before the commands load.
+ *
+ * @remarks
+ * Vite pre-bundles a catalogue's dependencies once. Rolldown's allocator keeps what it took, a hundred megabytes and
+ * more that the server would hold for as long as it runs, on top of what a first start needs for the docs. In a child
+ * they go back when it ends. The child starts as the command does (`prebundleEarly`), so it works while this process
+ * loads the commands, the configuration and Vite, and the server waits for it before it reads the cache folder. Should
+ * the child fail, the server pre-bundles as it always could.
+ *
+ * Whether there is anything to do is told by the pre-bundle's metadata in Vite's default cache folder: a catalogue
+ * whose framework moves the cache folder starts the child on every start, which finds the work done and ends.
+ *
+ * @module
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findConfigFile } from "../../src/vite/configFile.js";
+import { viteCacheDir } from "./viteCache.js";
+/** The child's entry, beside this module and with its extension (`.ts` in the sources, `.js` once built). */
+const CHILD_URL = new URL(`./prebundleChild${extname(import.meta.url)}`, import.meta.url);
+/** The pre-bundling started, by what it was started for: the command finds the one its entry started. */
+let started;
+/**
+ * Pre-bundles a catalogue's dependencies in a child, unless they are there already; a second call for the same
+ * run waits for the first.
+ *
+ * @param data - what the child pre-bundles for.
+ * @returns a promise of whether the child pre-bundled them: `false` when it failed, or was not needed.
+ */
+export const prebundleInChild = (data) => {
+    const key = JSON.stringify(data);
+    if (started?.key === key)
+        return started.done;
+    const metadata = join(viteCacheDir({ root: dirname(data.configFile) }), "deps", "_metadata.json");
+    if (existsSync(metadata) && !data.isForced)
+        return Promise.resolve(false);
+    const done = new Promise((resolve) => {
+        const child = spawn(process.execPath, [fileURLToPath(CHILD_URL), JSON.stringify(data)], {
+            stdio: "ignore"
+        });
+        child.once("error", () => resolve(false));
+        child.once("exit", (code) => resolve(code === 0));
+    });
+    started = { key, done };
+    return done;
+};
+/**
+ * The pre-bundling of a `forgebook dev` run: the one its entry started, or one started now.
+ *
+ * @param configFile - the catalogue's configuration file; none when there is none, which pre-bundles nothing.
+ * @param options - the run's options.
+ * @returns a promise of whether the child pre-bundled the dependencies.
+ */
+export const prebundleForDev = (configFile, options) => configFile === undefined
+    ? Promise.resolve(false)
+    : prebundleInChild({
+        configFile,
+        isForced: options.force === true,
+        ...(options.frames === undefined ? {} : { frames: options.frames }),
+        ...(options["frame-port"] === undefined ? {} : { framePort: options["frame-port"] })
+    });
+/** The options of `forgebook dev` that change what it pre-bundles, or whose meaning only the command knows. */
+const LEFT_TO_THE_COMMAND = ["--config", "--frames", "--frame-port", "--force", "--help", "-h"];
+/**
+ * Starts the pre-bundling before the commands load, for `forgebook dev` run in the catalogue's folder. Any other form
+ * (`--config`, `--force`, the frames' options) is left to the command, which starts it once it has read its options.
+ *
+ * @param args - the command line's arguments.
+ */
+export const prebundleEarly = (args) => {
+    if (args[0] !== "dev")
+        return;
+    if (args.some((arg) => LEFT_TO_THE_COMMAND.some((option) => arg === option || arg.startsWith(`${option}=`))))
+        return;
+    const configFile = findConfigFile(process.cwd());
+    if (configFile !== undefined)
+        void prebundleInChild({ configFile, isForced: false });
+};

package/dist/bin/forgebook/semanticOptions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The options that name the model `--semantic` asks, shared by `forgebook check` and `forgebook mcp`: read from the
+ * environment, so a key stays out of the project's files and of the command line.
+ *
+ * @module
+ */
+import type { SemanticModel } from "../../src/storyCheck.ts";
+/** The options. */
+export declare const SEMANTIC_OPTIONS: {
+    readonly "semantic-url": {
+        readonly type: "string";
+        readonly env: "FORGEBOOK_SEMANTIC_URL";
+        readonly valueName: "address";
+        readonly description: "The OpenAI-compatible API --semantic asks.";
+    };
+    readonly "semantic-model": {
+        readonly type: "string";
+        readonly env: "FORGEBOOK_SEMANTIC_MODEL";
+        readonly valueName: "name";
+        readonly description: "The model --semantic asks.";
+    };
+    readonly "semantic-key": {
+        readonly type: "string";
+        readonly env: "FORGEBOOK_SEMANTIC_KEY";
+        readonly valueName: "key";
+        readonly description: "Its key, when it needs one: better in the environment than here.";
+    };
+};
+/** What those options give a command. */
+type SemanticOptions = {
+    /** The API's address. */
+    readonly "semantic-url"?: string | undefined;
+    /** The model's name. */
+    readonly "semantic-model"?: string | undefined;
+    /** Its key. */
+    readonly "semantic-key"?: string | undefined;
+};
+/**
+ * The model the options name.
+ *
+ * @param options - the command's options.
+ * @returns the model, or what to set.
+ */
+export declare const semanticModelOf: (options: SemanticOptions) => SemanticModel | string;
+export {};

package/dist/bin/forgebook/semanticOptions.js

@@ -0,0 +1,36 @@
+/** The options. */
+export const SEMANTIC_OPTIONS = {
+    "semantic-url": {
+        type: "string",
+        env: "FORGEBOOK_SEMANTIC_URL",
+        valueName: "address",
+        description: "The OpenAI-compatible API --semantic asks."
+    },
+    "semantic-model": {
+        type: "string",
+        env: "FORGEBOOK_SEMANTIC_MODEL",
+        valueName: "name",
+        description: "The model --semantic asks."
+    },
+    "semantic-key": {
+        type: "string",
+        env: "FORGEBOOK_SEMANTIC_KEY",
+        valueName: "key",
+        description: "Its key, when it needs one: better in the environment than here."
+    }
+};
+/**
+ * The model the options name.
+ *
+ * @param options - the command's options.
+ * @returns the model, or what to set.
+ */
+export const semanticModelOf = (options) => {
+    const url = options["semantic-url"];
+    const name = options["semantic-model"];
+    const key = options["semantic-key"];
+    if (url === undefined || name === undefined) {
+        return "Set FORGEBOOK_SEMANTIC_URL (an OpenAI-compatible API) and FORGEBOOK_SEMANTIC_MODEL, with FORGEBOOK_SEMANTIC_KEY when it needs one";
+    }
+    return { url, name, ...(key === undefined ? {} : { key }) };
+};

package/dist/bin/forgebook/storyCheckCommands.d.mts

@@ -0,0 +1,13 @@
+/**
+ * `forgebook check`: the catalogue's checks on a story in a browser, with the model's judgement when asked.
+ *
+ * @module
+ */
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const storyCheckCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/storyCheckCommands.mjs

@@ -0,0 +1,69 @@
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { checkText } from "./agentText.js";
+import { COMMAND, configOf } from "./catalogueCommands.js";
+import { SEMANTIC_OPTIONS, semanticModelOf } from "./semanticOptions.js";
+import { runStoryCheck } from "./storyCheckRun.js";
+/**
+ * The command.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const storyCheckCommands = (forgebook) => ({
+    check: forgebook.command({
+        summary: "Run the catalogue's checks on a story in a browser: accessibility, spills, overlays, errors.",
+        json: true,
+        options: {
+            view: {
+                type: "string",
+                multiple: true,
+                valueName: "query",
+                description: "A view to check it in, as the catalogue's address writes it (theme=dark&width=360); the default view when none."
+            },
+            "all-variants": {
+                type: "boolean",
+                description: "Check every variant the catalogue's browser tests check."
+            },
+            semantic: {
+                type: "boolean",
+                description: "Also ask the configured model, sending it each story's tree and picture."
+            },
+            ...SEMANTIC_OPTIONS,
+            url: {
+                type: "string",
+                env: "FORGEBOOK_URL",
+                valueName: "address",
+                description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+            }
+        },
+        positionals: [
+            { name: "id", description: "A story's id, or a component's for its listed stories.", required: true }
+        ],
+        examples: [
+            {
+                command: `${COMMAND} check kit:inputs-select--overview`,
+                description: "One story, in the default view."
+            },
+            {
+                command: `${COMMAND} check kit:inputs-select --view "theme=dark" --json`,
+                description: "Every story of a component, in the dark theme, as JSON."
+            }
+        ],
+        run: async ({ args, options, io, isJson, style }) => {
+            const config = await configOf(options.config);
+            const report = await runStoryCheck(config, options.url, {
+                id: args.id,
+                views: options.view ?? [],
+                isAllVariants: options["all-variants"] === true,
+                isSemantic: options.semantic === true
+            }, semanticModelOf(options));
+            if (typeof report === "string")
+                throw new ScriptError(report);
+            io.stdout.write(isJson ? formatJson(report) : `${checkText(report, style)}\n`);
+            const problems = report.results.reduce((count, result) => count + result.problems.length, 0);
+            if (problems > 0)
+                throw new ScriptError(`${problems} problems`, { exitCode: EXIT.failure, isReported: true });
+        }
+    })
+});

package/dist/bin/forgebook/storyCheckRun.d.ts

@@ -1,5 +1,6 @@
-import { type StoryCheckReport, type StoryShotReport } from "../../src/storyCheck.ts";
-import type { AgentStory, StoriesDocument } from "../../src/vite/agent.types.ts";
+import { type DeviceDefault } from "../../src/deviceView.ts";
+import { type SemanticModel, type StoryCheckReport, type StoryCheckStory, type StoryDiffReport, type StoryDiffRequest, type StoryShotReport } from "../../src/storyCheck.ts";
+import type { StoriesDocument } from "../../src/vite/agent.types.ts";
 import type { ResolvedConfig } from "../../src/vite/configFile.ts";
 /** What a run is asked: the id, the views and whether to run every variant. */
 export type StoryCheckInput = {
@@ -9,14 +10,18 @@ export type StoryCheckInput = {
     readonly views: readonly string[];
     /** Run every variant the catalogue's browser tests check. */
     readonly isAllVariants: boolean;
+    /** Ask the configured model too: it sends each story's tree and picture to that address. */
+    readonly isSemantic?: boolean;
 };
 /**
- * The stories an id names: the story itself, or a component's listed stories.
+ * The stories an id names, as a check reads them: the story itself, or a component's listed stories; by their ids, or
+ * by the ids an earlier rule gave them.
  *
  * @param document - the catalogue's stories.
  * @param id - the id.
+ * @param catalogueDevice - the catalogue's default device; none by default.
  */
-export declare const storiesNamed: (document: StoriesDocument, id: string) => AgentStory[];
+export declare const storiesNamed: (document: StoriesDocument, id: string, catalogueDevice?: DeviceDefault) => StoryCheckStory[];
 /**
  * A function the testing package exports, resolved from the catalogue's folder as the project's own code would: the
  * check, the pictures, the touch window.
@@ -33,9 +38,10 @@ export declare const testingFunction: (dir: string, specifier: string, name: str
  * @param config - the catalogue's configuration.
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
  * @param input - the id, the views and whether to check every variant.
+ * @param model - the model `isSemantic` asks, or what to set to have one.
  * @returns the report, or why the check could not run.
  */
-export declare const runStoryCheck: (config: ResolvedConfig, url: string | undefined, input: StoryCheckInput) => Promise<StoryCheckReport | string>;
+export declare const runStoryCheck: (config: ResolvedConfig, url: string | undefined, input: StoryCheckInput, model?: SemanticModel | string) => Promise<StoryCheckReport | string>;
 /**
  * Takes the stories' pictures.
  *
@@ -46,4 +52,32 @@ export declare const runStoryCheck: (config: ResolvedConfig, url: string | undef
  * @returns the pictures, or why they could not be taken.
  */
 export declare const runStoryShot: (config: ResolvedConfig, url: string | undefined, input: StoryCheckInput, outDir: string) => Promise<StoryShotReport | string>;
-//# sourceMappingURL=storyCheckRun.d.ts.map
+/**
+ * The component a comparison names, by its current id and the one the former rule gave it, so its baselines under
+ * either are its own; none when the id names a story.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id asked for, current or former.
+ */
+export declare const diffedComponent: (document: StoriesDocument, id: string) => Pick<StoryDiffRequest, "component" | "formerComponent">;
+/**
+ * Compares the stories' pictures with their baselines.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the id, the views and whether to compare every variant.
+ * @param folders - the baselines' folder and the one the new pictures go in, absolute.
+ * @returns the results, or why they could not be had.
+ */
+export declare const runStoryDiff: (config: ResolvedConfig, url: string | undefined, input: StoryCheckInput, folders: {
+    readonly baselines: string;
+    readonly outDir: string;
+}) => Promise<StoryDiffReport | string>;
+/**
+ * Checks pages of an application.
+ *
+ * @param config - the catalogue's configuration: its accessibility rules, and the folder the testing package is in.
+ * @param addresses - the pages' addresses.
+ * @returns the report, or why the check could not run.
+ */
+export declare const runPageCheck: (config: ResolvedConfig, addresses: readonly string[]) => Promise<StoryCheckReport | string>;

package/dist/bin/forgebook/storyCheckRun.js

@@ -22,25 +22,50 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createRequire } from "node:module";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { isStoryCheckReport, isStoryShotReport } from "../../src/storyCheck.js";
+import { deviceDefaultOf, NO_DEVICE } from "../../src/deviceView.js";
+import { isStoryCheckReport, isStoryDiffReport, isStoryShotReport } from "../../src/storyCheck.js";
+import { formerComponentId } from "../../src/storyTree.js";
 import { catalogueSwitches } from "../../src/switches.js";
 import { viewQuery } from "../../src/viewWords.js";
 import { isStoriesDocument } from "../../src/vite/agentApi.js";
+import { formerIdOf, namedComponent, namedStory } from "../../src/vite/agentIds.js";
 import { AGENT_API } from "../../src/vite/agentRoutes.js";
 import { servedCatalogue } from "./agentClient.js";
 /** What the project installs to run the stories in a browser, and how. */
 const INSTALL = "Stories run in a browser with @forgebook/testing: npm install -D @forgebook/testing @playwright/test, then npx playwright install chromium";
 /**
- * The stories an id names: the story itself, or a component's listed stories.
+ * A story of the document as a check reads it.
+ *
+ * @param component - its component.
+ * @param story - the story.
+ * @param catalogueDevice - the catalogue's default device, under the story's.
+ */
+const checkedStory = (component, story, catalogueDevice) => {
+    const formerId = formerIdOf(component, story);
+    return {
+        id: story.id,
+        ...(formerId === undefined ? {} : { formerId }),
+        ...(story.height === undefined ? {} : { height: story.height }),
+        ...(story.isLogic ? { isLogic: true } : {}),
+        ...(deviceDefaultOf(catalogueDevice, story.device).isEdgeToEdge ? { isEdgeToEdge: true } : {})
+    };
+};
+/**
+ * The stories an id names, as a check reads them: the story itself, or a component's listed stories; by their ids, or
+ * by the ids an earlier rule gave them.
  *
  * @param document - the catalogue's stories.
  * @param id - the id.
+ * @param catalogueDevice - the catalogue's default device; none by default.
  */
-export const storiesNamed = (document, id) => {
-    const component = document.components.find((each) => each.id === id);
+export const storiesNamed = (document, id, catalogueDevice = NO_DEVICE) => {
+    const component = namedComponent(document, id);
     if (component !== undefined)
-        return component.stories.filter((story) => !story.isUnlisted);
-    return document.components.flatMap((each) => each.stories.filter((story) => story.id === id));
+        return component.stories
+            .filter((story) => !story.isUnlisted)
+            .map((story) => checkedStory(component, story, catalogueDevice));
+    const named = namedStory(document, id);
+    return named === undefined ? [] : [checkedStory(named.component, named.story, catalogueDevice)];
 };
 /**
  * The views in the address's form, or why one cannot be read.
@@ -118,21 +143,18 @@ const runOnStories = async (config, url, input, run) => {
         const document = await storiesAt(served.origin);
         if (typeof document === "string")
             return document;
-        const stories = storiesNamed(document, input.id);
+        const stories = storiesNamed(document, input.id, deviceDefaultOf(NO_DEVICE, config.lists.device));
         if (stories.length === 0)
             return `No story or component "${input.id}"`;
         const request = {
             frameUrl: `${served.origin}/frame.html`,
-            stories: stories.map((story) => ({
-                id: story.id,
-                ...(story.height === undefined ? {} : { height: story.height })
-            })),
+            stories,
             switches,
             lists: config.lists,
             views,
             isAllVariants: input.isAllVariants
         };
-        return await call({ ...request, ...run.extra });
+        return await call({ ...request, ...run.extra(document) });
     }
     finally {
         await served.close();
@@ -144,13 +166,17 @@ const runOnStories = async (config, url, input, run) => {
  * @param config - the catalogue's configuration.
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
  * @param input - the id, the views and whether to check every variant.
+ * @param model - the model `isSemantic` asks, or what to set to have one.
  * @returns the report, or why the check could not run.
  */
-export const runStoryCheck = async (config, url, input) => {
+export const runStoryCheck = async (config, url, input, model) => {
+    const semantic = input.isSemantic === true ? model : undefined;
+    if (typeof semantic === "string")
+        return semantic;
     const answer = await runOnStories(config, url, input, {
         specifier: "@forgebook/testing/check",
         name: "checkStories",
-        extra: {}
+        extra: () => (semantic === undefined ? {} : { semantic })
     });
     if (typeof answer === "string" || isStoryCheckReport(answer))
         return answer;
@@ -169,10 +195,58 @@ export const runStoryShot = async (config, url, input, outDir) => {
     const answer = await runOnStories(config, url, input, {
         specifier: "@forgebook/testing/shot",
         name: "shotStories",
-        extra: { outDir }
+        extra: () => ({ outDir })
     });
     if (typeof answer === "string" || isStoryShotReport(answer))
         return answer;
     return "@forgebook/testing/shot answered something that is not a picture run's report";
 };
-//# sourceMappingURL=storyCheckRun.js.map
+/**
+ * The component a comparison names, by its current id and the one the former rule gave it, so its baselines under
+ * either are its own; none when the id names a story.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id asked for, current or former.
+ */
+export const diffedComponent = (document, id) => {
+    const component = namedComponent(document, id);
+    if (component === undefined)
+        return {};
+    const former = formerComponentId(component.source, component.title);
+    return { component: component.id, ...(former === component.id ? {} : { formerComponent: former }) };
+};
+/**
+ * Compares the stories' pictures with their baselines.
+ *
+ * @param config - the catalogue's configuration.
+ * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param input - the id, the views and whether to compare every variant.
+ * @param folders - the baselines' folder and the one the new pictures go in, absolute.
+ * @returns the results, or why they could not be had.
+ */
+export const runStoryDiff = async (config, url, input, folders) => {
+    const answer = await runOnStories(config, url, input, {
+        specifier: "@forgebook/testing/diff",
+        name: "diffStories",
+        extra: (document) => ({ ...folders, ...diffedComponent(document, input.id) })
+    });
+    if (typeof answer === "string" || isStoryDiffReport(answer))
+        return answer;
+    return "@forgebook/testing/diff answered something that is not a comparison's report";
+};
+/**
+ * Checks pages of an application.
+ *
+ * @param config - the catalogue's configuration: its accessibility rules, and the folder the testing package is in.
+ * @param addresses - the pages' addresses.
+ * @returns the report, or why the check could not run.
+ */
+export const runPageCheck = async (config, addresses) => {
+    const check = await testingFunction(config.dir, "@forgebook/testing/check-page", "checkPages");
+    if (typeof check === "string")
+        return check;
+    const answer = await check({ addresses, lists: config.lists });
+    return isStoryCheckReport(answer)
+        ? answer
+        : "@forgebook/testing/check-page answered something that is not a report";
+};