forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/agentSetup/uniformPicture.js

@@ -0,0 +1,98 @@
+/**
+ * Whether a story's picture shows one colour and nothing else: what no check of the page can tell, since an input with no
+ * look of its own has a size and draws nothing.
+ *
+ * @remarks
+ * Reads PNG as Chromium writes it, 8 bits per channel, with Node's own zlib, so the core adds no decoder. A file it cannot read
+ * counts as showing something: this only ever takes a story from "drew" to "try another".
+ *
+ * @module
+ */
+import { inflateSync } from "node:zlib";
+/** A PNG's signature, and where its header's fields sit. */
+const HEADER_START = 8;
+/** The bytes per pixel of the colour types Chromium writes: true colour, and with alpha. */
+const BYTES_PER_PIXEL = { 2: 3, 6: 4 };
+/** The chunks of a PNG: its header's fields, and its image data joined. */
+const readChunks = (file) => {
+    const parts = [];
+    let position = HEADER_START;
+    let width = 0;
+    let height = 0;
+    let type = -1;
+    while (position + 8 <= file.length) {
+        const length = file.readUInt32BE(position);
+        const name = file.toString("latin1", position + 4, position + 8);
+        const start = position + 8;
+        if (name === "IHDR") {
+            width = file.readUInt32BE(start);
+            height = file.readUInt32BE(start + 4);
+            type = file.readUInt8(start + 9);
+        }
+        if (name === "IDAT")
+            parts.push(file.subarray(start, start + length));
+        position = start + length + 4;
+    }
+    return { width, height, type, data: inflateSync(Buffer.concat(parts)) };
+};
+/** PNG's Paeth predictor. */
+const paeth = (left, up, corner) => {
+    const estimate = left + up - corner;
+    const toLeft = Math.abs(estimate - left);
+    const toUp = Math.abs(estimate - up);
+    const toCorner = Math.abs(estimate - corner);
+    if (toLeft <= toUp && toLeft <= toCorner)
+        return left;
+    return toUp <= toCorner ? up : corner;
+};
+/** A row's byte before its filter: the filter's prediction added back. */
+const predicted = (filter, left, up, corner) => {
+    if (filter === 1)
+        return left;
+    if (filter === 2)
+        return up;
+    if (filter === 3)
+        return Math.floor((left + up) / 2);
+    return filter === 4 ? paeth(left, up, corner) : 0;
+};
+/** A row with its filter undone, from the row above and where the row starts in the image data. */
+const unfilteredRow = (data, start, stride, pixel, previous) => {
+    const filter = data.readUInt8(start);
+    const row = Buffer.alloc(stride);
+    for (let index = 0; index < stride; index += 1) {
+        const left = index >= pixel ? (row[index - pixel] ?? 0) : 0;
+        const corner = index >= pixel ? (previous[index - pixel] ?? 0) : 0;
+        const raw = data[start + 1 + index] ?? 0;
+        row[index] = (raw + predicted(filter, left, previous[index] ?? 0, corner)) & 255;
+    }
+    return row;
+};
+/** Whether every pixel of a row is the colour. */
+const isRowOf = (row, colour) => row.every((value, index) => value === colour[index % colour.length]);
+/**
+ * Whether a PNG is one colour.
+ *
+ * @param file - the file's bytes.
+ * @returns the answer; `false` for one it cannot read.
+ */
+export const isUniformPicture = (file) => {
+    try {
+        const { width, height, type, data } = readChunks(file);
+        const pixel = BYTES_PER_PIXEL[type];
+        if (pixel === undefined || width === 0 || height === 0)
+            return false;
+        const stride = width * pixel;
+        let previous = Buffer.alloc(stride);
+        let colour;
+        for (let row = 0; row < height; row += 1) {
+            previous = unfilteredRow(data, row * (stride + 1), stride, pixel, previous);
+            colour ??= previous.subarray(0, pixel);
+            if (!isRowOf(previous, colour))
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+};

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

@@ -0,0 +1,14 @@
+/**
+ * The commands a project's coding agents are set up with: `hook`, which an assistant runs when it is about to finish, and
+ * `browser`, which installs what the stories' checks run on.
+ *
+ * @module
+ */
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const agentSetupCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/agentSetupCommands.mjs

@@ -0,0 +1,98 @@
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { emptyStoryGlobsProblems } from "../../src/vite/emptyStoryGlobs.js";
+import { catalogueClient } from "./agentClient.js";
+import { ASSISTANT_NAMES } from "./agentSetup/assistantHooks.js";
+import { allowed, answerToVerdict, isContinuing, isTurnAborted, sayAnswer, touchesUi } from "./agentSetup/stopHook.js";
+import { verifyText } from "./agentText.js";
+import { COMMAND, configOf } from "./catalogueCommands.js";
+import { runStoriesCheck } from "./storyCheckRun.js";
+import { runVerify } from "./verifyRun.js";
+/** What an assistant sent on stdin: empty when nothing is piped in, as when a person runs the command. */
+const hookInput = async () => {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin)
+        if (typeof chunk === "string")
+            chunks.push(chunk);
+    return chunks.join("");
+};
+/** Runs `verify` for a hook; anything but a verdict lets the assistant finish, since it cannot repair a hook. */
+const hookAnswer = async (assistant, input, configFile, url, style) => {
+    if (isTurnAborted(input))
+        return allowed();
+    try {
+        // a pattern that matches nothing leaves the verdict not verified, with the rest of it: never no verdict at all
+        const config = await configOf(configFile);
+        if (!(await touchesUi(config.dir)))
+            return allowed();
+        const client = await catalogueClient(config, url);
+        try {
+            const document = await runVerify({ dir: config.dir, ask: client.ask, check: (each) => runStoriesCheck(config, url, each) }, { since: undefined, isQuick: false, configProblems: emptyStoryGlobsProblems(config) });
+            if (typeof document === "string")
+                return allowed(`forgebook verify could not run: ${document}\n`);
+            const text = verifyText(document, style);
+            return answerToVerdict(assistant, document, text, config.dir, isContinuing(input));
+        }
+        finally {
+            await client.close();
+        }
+    }
+    catch (error) {
+        return allowed(`forgebook verify could not run: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+};
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const agentSetupCommands = (forgebook) => ({
+    hook: forgebook.command({
+        header: false,
+        summary: "What an assistant's hook runs when it is about to finish: verify on the change, sending the agent back on red. Written by init --agents.",
+        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: "assistant", description: `The assistant: ${ASSISTANT_NAMES.join(", ")}.`, required: true }
+        ],
+        examples: [{ command: `${COMMAND} hook claude`, description: "As Claude Code's Stop hook runs it." }],
+        run: async ({ args, options, io, style }) => {
+            const assistant = ASSISTANT_NAMES.find((name) => name === args.assistant);
+            if (assistant === undefined)
+                throw new ScriptError(`No hook format for ${args.assistant}`, {
+                    hint: `It takes ${ASSISTANT_NAMES.join(", ")}`
+                });
+            const input = await hookInput();
+            // what the server logs (a story's errors, in the project's words) would reach the agent as if the hook said it
+            const { write } = process.stderr;
+            Object.assign(process.stderr, { write: () => true });
+            const answer = await hookAnswer(assistant, input, options.config, options.url, style).finally(() => {
+                Object.assign(process.stderr, { write });
+            });
+            sayAnswer(answer, io);
+        }
+    }),
+    browser: forgebook.command({
+        summary: "Install the browser the stories' checks run on, with the Playwright that will open it.",
+        options: {
+            "with-deps": {
+                type: "boolean",
+                description: "Also install what the browser needs of the system, as CI does."
+            }
+        },
+        examples: [{ command: `${COMMAND} browser`, description: "Once, after installing @forgebook/testing." }],
+        run: async ({ options, io, log }) => {
+            const { installBrowser } = await import("./browserRun.js");
+            await installBrowser(process.cwd(), options["with-deps"] === true, io);
+            log.success("Browser installed");
+        }
+    })
+});

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

@@ -1,18 +1,19 @@
 import type { OutputStyle } from "@ensiria/cli-kit/log.types";
 import type { StoryCheckReport, StoryDiffReport, StoryShotReport } from "../../src/storyCheck.ts";
-import type { CheckedCodeDocument, ErrorsDocument, FoundComponentsDocument, NearestTokensDocument, PageDocument, PagesDocument, PluginsDocument, SearchDocument, StoriesDocument, StoryDocument, TokensDocument } from "../../src/vite/agent.types.ts";
+import type { CheckedCodeDocument, ErrorsDocument, FoundComponentsDocument, NearestTokensDocument, PageDocument, PagesDocument, PluginsDocument, SearchDocument, StoriesDocument, StoryDocument, SwitchesDocument, TokensDocument, VerifyDocument, VisibilityDocument } from "../../src/vite/agent.types.ts";
 import type { DesignToken } from "../../src/vite/designTokens.ts";
 import type { TokenClash } from "../../src/vite/tokenClashes.ts";
 /**
  * The stories as a table: one row per story, its id first (what `forgebook story` takes, never cut), then its
- * component's title and its name.
+ * component's title and its name, with its statuses in brackets.
  *
  * @param document - the stories document.
  * @param style - colours, glyphs and width.
  */
 export declare const storiesText: (document: StoriesDocument, style: OutputStyle) => string;
 /**
- * One story's facts: where it is, where it opens, its args, its component's props and those every use must set.
+ * One story's facts: where it is, where it opens, its args, its component's props and those every use must set, then
+ * its code.
  *
  * @param document - the story document.
  * @param style - colours, glyphs and width.
@@ -97,6 +98,19 @@ export declare const foundComponentsText: (document: FoundComponentsDocument) =>
  * @param document - the answer.
  */
 export declare const checkedCodeText: (document: CheckedCodeDocument) => string;
+/**
+ * The published components an agent cannot see, what was not looked at, and how many were.
+ *
+ * @param document - the answer.
+ */
+export declare const visibilityText: (document: VisibilityDocument) => string;
+/**
+ * What `verify` found, each with its fix, and the verdict in one line, last: what a person reads first at a prompt.
+ *
+ * @param document - the answer.
+ * @param style - colours, glyphs and width.
+ */
+export declare const verifyText: (document: VerifyDocument, style: OutputStyle) => string;
 /**
  * The catalogue's plugins, one per line.
  *
@@ -123,3 +137,9 @@ export declare const pageText: (document: PageDocument) => string;
  * @param document - the search's document.
  */
 export declare const searchText: (document: SearchDocument) => string;
+/**
+ * The catalogue's switches, one per line, each with its values and what they bring with them.
+ *
+ * @param document - the answer.
+ */
+export declare const switchesText: (document: SwitchesDocument) => string;

package/dist/bin/forgebook/agentText.js

@@ -11,19 +11,52 @@ import { formatJson } from "@ensiria/cli-kit/files";
 import { keyValue, table } from "@ensiria/cli-kit/layout";
 /** The style with no width to fit, so no cell is cut. */
 const uncut = (style) => ({ ...style, width: Number.POSITIVE_INFINITY });
+/** Statuses in brackets after a name (` [review]`); nothing for none. */
+const statusMark = (status) => status === undefined ? "" : ` [${status.join(", ")}]`;
+/** The words read as others, as the first line of an answer; none when the query was read as typed. */
+const correctionLines = (corrections) => corrections.length === 0
+    ? []
+    : [`Read as: ${corrections.map(({ typed, read }) => `"${read}" for "${typed}"`).join(", ")}`];
 /**
  * The stories as a table: one row per story, its id first (what `forgebook story` takes, never cut), then its
- * component's title and its name.
+ * component's title and its name, with its statuses in brackets.
  *
  * @param document - the stories document.
  * @param style - colours, glyphs and width.
  */
 export const storiesText = (document, style) => table(document.components.flatMap((component) => component.stories.map((story) => [
     story.id,
-    `${component.title} › ${story.name}${story.isUnlisted ? " (unlisted)" : ""}`
+    `${component.title} › ${story.name}${story.isUnlisted ? " (unlisted)" : ""}${statusMark(story.statuses)}`
 ])), { columns: [{ header: "Id" }, { header: "Story", tone: "muted" }] }, uncut(style));
+/** Why a component lists no props, as the `Props` line says it. */
+const PROPS_NOTES = {
+    untyped: () => "none: its props are typed any",
+    "no-signature": () => "none: its type cannot be called with props",
+    "outside-package": (count) => `none: all ${count} come from outside the package`
+};
+/** When a variant's prop applies, as the `Props` line says it (`mode is single, or left out`). */
+const conditionText = ({ prop, values, orOmitted }) => {
+    if (values.length === 0)
+        return `${prop} is left out`;
+    return `${prop} is ${values.map(String).join(" or ")}${orOmitted === true ? ", or left out" : ""}`;
+};
+/**
+ * A component's props in one line: each name, a variant's with when it can be passed, or why there are none.
+ *
+ * @param docs - the component's docs.
+ */
+const propsLine = (docs) => {
+    const { propsNote } = docs;
+    if (docs.props.length === 0 && propsNote !== undefined) {
+        return PROPS_NOTES[propsNote.reason](propsNote.reason === "outside-package" ? propsNote.count : 0);
+    }
+    return docs.props
+        .map((prop) => prop.onlyWhen === undefined ? prop.name : `${prop.name} (when ${conditionText(prop.onlyWhen)})`)
+        .join(", ");
+};
 /**
- * One story's facts: where it is, where it opens, its args, its component's props and those every use must set.
+ * One story's facts: where it is, where it opens, its args, its component's props and those every use must set, then
+ * its code.
  *
  * @param document - the story document.
  * @param style - colours, glyphs and width.
@@ -37,14 +70,21 @@ export const storyText = (document, style) => {
         ["Frame", document.story.links.frame],
         ["Embed", document.story.links.embed],
         ["Args", JSON.stringify(document.args)],
-        ["Props", document.docs === undefined ? "none" : document.docs.props.map((prop) => prop.name).join(", ")],
+        ["Props", document.docs === undefined ? "none" : propsLine(document.docs)],
         ["Required", document.requiredProps.length === 0 ? "none" : document.requiredProps.join(", ")]
     ];
     if (document.story.description !== undefined)
         entries.push(["About", document.story.description]);
+    // the story's own, which may take its meta's away, and the deprecation its component's TSDoc adds
+    const fromDocs = document.component.statuses?.includes("deprecated") ? ["deprecated"] : [];
+    const statuses = [...new Set([...(document.story.statuses ?? []), ...fromDocs])];
+    if (statuses.length > 0)
+        entries.push(["Status", statuses.join(", ")]);
     if (document.design !== undefined)
         entries.push(["Design", document.design.figma]);
-    return keyValue(entries, uncut(style));
+    const fields = keyValue(entries, uncut(style));
+    // the code spans lines: under the fields, as it is copied
+    return document.code === undefined ? fields : `${fields}\n\n${document.code}`;
 };
 /** What a model judged, each line saying it is an opinion. */
 const judgementLines = (result) => {
@@ -71,8 +111,17 @@ const judgementLines = (result) => {
  */
 export const checkText = (report, style) => (report.a11y === "off" ? "Accessibility is not checked: the catalogue sets a11y: false.\n" : "") +
     table(report.results.flatMap((result) => [
-        ...(result.problems.length === 0
-            ? [[result.storyId, result.view || "default", "passes"]]
+        ...(result.notVerified === undefined
+            ? []
+            : [[result.storyId, result.view || "default", `not verified: ${result.notVerified}`]]),
+        ...(result.problems.length === 0 && result.notVerified === undefined
+            ? [
+                [
+                    result.storyId,
+                    result.view || "default",
+                    result.isNotAwaited === true ? "passes, as drawn: parameters.suspense.expected" : "passes"
+                ]
+            ]
             : result.problems.map((problem) => [
                 result.storyId,
                 result.view || "default",
@@ -88,7 +137,11 @@ export const checkText = (report, style) => (report.a11y === "off" ? "Accessibil
  */
 export const errorsText = (document, style) => document.errors.length === 0
     ? ""
-    : table(document.errors.map((error) => [String(error.n), error.storyId, `${error.kind}: ${error.message}`]), { columns: [{ header: "#", tone: "muted" }, { header: "Story" }, { header: "Error" }] }, uncut(style));
+    : table(document.errors.map((error) => [
+        String(error.n),
+        error.storyId,
+        `${error.kind}: ${error.place === undefined ? "" : `${error.place}: `}${error.message}`
+    ]), { columns: [{ header: "#", tone: "muted" }, { header: "Story" }, { header: "Error" }] }, uncut(style));
 /**
  * What `forgebook errors` prints of an answer: its JSON (one line per error while following, so each can be read as it
  * comes), or its table.
@@ -111,7 +164,19 @@ export const errorsOutput = (document, mode, style) => {
  * @param shownFile - how a file is written for the reader (relative to where the command runs).
  * @param style - colours, glyphs and width.
  */
-export const shotText = (report, shownFile, style) => table(report.shots.map((shot) => [shot.storyId, shot.view || "default", shownFile(shot.file)]), { columns: [{ header: "Story" }, { header: "View", tone: "muted" }, { header: "Picture" }] }, uncut(style));
+export const shotText = (report, shownFile, style) => table(report.shots.map((shot) => [
+    shot.storyId,
+    shot.view || "default",
+    shownFile(shot.file),
+    shot.status === undefined ? "" : `not of the story: ${shot.status}`
+]), {
+    columns: [
+        { header: "Story" },
+        { header: "View", tone: "muted" },
+        { header: "Picture" },
+        { header: "Status" }
+    ]
+}, uncut(style));
 /**
  * A comparison with the baselines as a person reads it.
  *
@@ -141,16 +206,29 @@ export const diffText = (report, shownFile, style) => table(report.results.map((
  */
 export const tokensText = (document) => {
     if (!document.isConfigured)
-        return 'No tokens file: name one in forgebook.config.ts (`tokens: ["tokens.json"]`) or on a source.';
+        return 'No tokens file, and none found in the application: name one in forgebook.config.ts (`tokens: ["tokens.json"]`) or on a source.';
     if (document.total === 0)
         return "No tokens here.";
     const lines = document.tokens.map((token) => tokenLine(token));
     const more = document.total - document.tokens.length;
     return [
         ...lines,
-        ...(more > 0 ? [`… and ${more} more: narrow it with --category, or raise --limit.`] : [])
+        ...(more > 0 ? [`… and ${more} more: narrow it with --category, or raise --limit.`] : []),
+        ...tokenSourceLines(document.sources ?? [], document.notes ?? [])
     ].join("\n");
 };
+/** What tokens were read from, on one line, and what could not be, as a person reads them. */
+const tokenSourceLines = (sources, notes) => {
+    const read = sources.filter((source) => source.kind !== "tokens-file");
+    return [
+        ...(read.length === 0
+            ? []
+            : [
+                `Read from: ${read.map(({ kind, file, tokens }) => `${file} (${kind}, ${tokens ?? 0})`).join(", ")}`
+            ]),
+        ...notes.map((note) => `Not read: ${note}`)
+    ];
+};
 /** A token on one line, its themes and any deprecation beside it. */
 const tokenLine = (token) => {
     const modes = Object.entries(token.modes).map(([mode, value]) => ` ${mode}: ${value}`);
@@ -198,12 +276,13 @@ export const nearestTokensText = (document) => {
  */
 export const foundComponentsText = (document) => document.components.length === 0
     ? `Nothing in this catalogue holds "${document.query}".`
-    : document.components
-        .map((each) => {
-        const missed = each.missed.length === 0 ? "" : `  (no "${each.missed.join('", "')}")`;
-        return `${each.title}${missed}${each.guidance?.deprecated === undefined ? "" : "  deprecated"}`;
-    })
-        .join("\n");
+    : [
+        ...correctionLines(document.corrections),
+        ...document.components.map((each) => {
+            const missed = each.missed.length === 0 ? "" : `  (no "${each.missed.join('", "')}")`;
+            return `${each.title}${missed}${each.guidance?.deprecated === undefined ? "" : "  deprecated"}`;
+        })
+    ].join("\n");
 /**
  * What a change broke as a person reads it, a line a problem.
  *
@@ -212,8 +291,61 @@ export const foundComponentsText = (document) => document.components.length ===
 export const checkedCodeText = (document) => {
     const lines = document.problems.map((each) => `${each.file}${each.line === undefined ? "" : `:${each.line}`}  ${each.message}`);
     return [
-        ...(lines.length === 0 ? ["Nothing to report."] : lines),
-        ...document.skipped.map((each) => `Not checked: ${each}`)
+        ...(lines.length > 0
+            ? lines
+            : [document.skipped.length > 0 ? "Nothing to report in what was checked." : "Nothing to report."]),
+        ...document.skipped,
+        ...(document.advice ?? []).map(({ file, line, message }) => `${file}:${line}  ${message}`),
+        ...(document.excused ?? []).map(({ file, line, rule, reason }) => `${file}:${line}  ${rule} excused by a comment: ${reason}`),
+        ...tokenSourceLines(document.tokenSources ?? [], document.tokenNotes ?? [])
+    ].join("\n");
+};
+/** A published component an agent cannot see, a line for each thing that hides it. */
+const unseenLines = ({ file, reasons }) => reasons.map(({ reason, fix }) => `${file}  agents cannot see it: ${reason}. Fix: ${fix}`);
+/**
+ * The published components an agent cannot see, what was not looked at, and how many were.
+ *
+ * @param document - the answer.
+ */
+export const visibilityText = (document) => {
+    const scope = document.since === undefined ? "" : ` changed since ${document.since}`;
+    const count = `${document.checked} published component file${document.checked === 1 ? "" : "s"}${scope}`;
+    const ending = document.packages.length === 0 && document.skipped.length === 0
+        ? "No package here publishes a component: nothing to hold to this."
+        : `${count}, ${document.unseen.length} agents cannot see.`;
+    return [...document.unseen.flatMap(unseenLines), ...document.skipped, ending].join("\n");
+};
+/**
+ * What `verify` found, each with its fix, and the verdict in one line, last: what a person reads first at a prompt.
+ *
+ * @param document - the answer.
+ * @param style - colours, glyphs and width.
+ */
+export const verifyText = (document, style) => {
+    const uncovered = document.uiFiles.flatMap((each) => each.coverage === "none"
+        ? [
+            `${each.file}  not verified: ${each.reason ?? ""}${each.fix === undefined ? "" : ` Fix: ${each.fix}`}`
+        ]
+        : []);
+    const unseen = document.unseen.flatMap(unseenLines);
+    const code = document.code.problems.map((each) => `${each.file}${each.line === undefined ? "" : `:${each.line}`}  ${each.message}`);
+    const outdated = (document.outdated ?? []).map((each) => `${each.file}  out of date: written for props ${each.written}, now ${each.current}. Fix: ${each.fix}`);
+    const notes = document.code.notes.map((each) => `${each.file}${each.line === undefined ? "" : `:${each.line}`}  note: ${each.message}`);
+    const advice = (document.code.advice ?? []).map((each) => `${each.file}:${each.line}  ${each.message}`);
+    const results = [
+        ...document.failures,
+        ...document.notVerified.map((each) => ({ ...each, problems: [] }))
+    ].map((each) => ({ ...each, frame: each.links?.frame ?? "" }));
+    const stories = results.length === 0 ? [] : [checkText({ schema: 1, results }, style)];
+    return [
+        ...uncovered,
+        ...unseen,
+        ...code,
+        ...outdated,
+        ...notes,
+        ...advice,
+        ...stories,
+        document.summary
     ].join("\n");
 };
 /**
@@ -265,13 +397,28 @@ export const pageText = (document) => [document.page.links.address, "", document
  */
 export const searchText = (document) => document.results.length === 0
     ? `Nothing in the catalogue holds "${document.query}".`
-    : document.results
-        .flatMap((result) => [
-        `${result.name} (${result.place})${result.missed.length === 0 ? "" : `, missing: ${result.missed.join(", ")}`}`,
-        `  ${result.address}`,
-        ...result.hits.flatMap((hit) => [
-            `  ${hit.kind}${hit.name === undefined ? "" : ` ${hit.name}`}: ${hit.text}`,
-            `    ${hit.address}`
+    : [
+        ...correctionLines(document.corrections),
+        ...document.results.flatMap((result) => [
+            `${result.name} (${result.place})${result.missed.length === 0 ? "" : `, missing: ${result.missed.join(", ")}`}`,
+            `  ${result.address}`,
+            ...result.hits.flatMap((hit) => [
+                `  ${hit.kind}${hit.name === undefined ? "" : ` ${hit.name}`}: ${hit.text}`,
+                `    ${hit.address}`
+            ])
         ])
-    ])
-        .join("\n");
+    ].join("\n");
+/**
+ * The catalogue's switches, one per line, each with its values and what they bring with them.
+ *
+ * @param document - the answer.
+ */
+export const switchesText = (document) => document.switches
+    .map((each) => {
+    const values = each.values.map(({ value, implies }) => {
+        const implied = Object.entries(implies ?? {}).map(([id, other]) => `${id}=${other}`);
+        return implied.length === 0 ? value : `${value} (implies ${implied.join(", ")})`;
+    });
+    return `${each.id} (${each.control}): ${values.join(", ")}`;
+})
+    .join("\n");