@reticlehq/server 3.9.0 → 3.10.0

package/dist/features/compare/compare-report.js

@@ -0,0 +1,73 @@
+/**
+ * What `reticle verify <candidate> --against <reference>` prints, writes and exits with.
+ *
+ * Exit 0 only when steps were compared and no difference was found. A run that compared nothing
+ * proved nothing, so it exits 1, the same as a difference.
+ */
+import { DifferenceKind } from './compare-diff.js';
+const EXIT_SAME = 0;
+const EXIT_DIFFERENT = 1;
+/** The version of the `--results-json` file this writes. */
+export const COMPARE_SCHEMA_VERSION = 1;
+const INDENT = '  ';
+const REMOVED_MARK = '- ';
+const ADDED_MARK = '+ ';
+const MSG_SAME = 'No difference: the candidate shows what the reference shows after every step.';
+const MSG_NOTHING_COMPARED = 'Nothing was compared, so nothing was proved. The reference did no step two times the same way. ' +
+    'Make sure the reference url opens, and that its page does not change on each load.';
+const MSG_UNREACHED = 'The candidate could not do the last action. The reference could.';
+export function compareExit(result) {
+    if (result.differences.length > 0 || 0 === result.compared) {
+        return EXIT_DIFFERENT;
+    }
+    return EXIT_SAME;
+}
+function differenceLines(difference) {
+    const where = 1 === difference.seen ? '1 step' : `${String(difference.seen)} steps`;
+    const lines = [
+        `difference ${difference.id} (seen at ${where})`,
+        `${INDENT}after:`,
+        ...difference.actions.map((action, i) => `${INDENT}${INDENT}${String(i + 1)}. ${action}`),
+    ];
+    if (DifferenceKind.UNREACHED === difference.kind) {
+        lines.push(`${INDENT}${MSG_UNREACHED}`);
+    }
+    lines.push(...difference.removed.map((line) => `${INDENT}${REMOVED_MARK}${line}`));
+    lines.push(...difference.added.map((line) => `${INDENT}${ADDED_MARK}${line}`));
+    return lines;
+}
+export function compareLines(urls, result) {
+    const lines = [
+        `Compared ${urls.candidate} against ${urls.reference}.`,
+        `${String(result.journeys)} journeys, ${String(result.compared)} steps compared. ` +
+            `${String(result.ignored)} lines ignored, because they also changed between two runs of the reference.`,
+    ];
+    if (result.unstable > 0) {
+        lines.push(`${String(result.unstable)} steps were not compared: the reference did them on one of its two runs only.`);
+    }
+    if (result.explored.budgetExhausted) {
+        lines.push(`The explorer used its action budget. ${String(result.explored.frontier)} states it found were not explored.`);
+    }
+    if (0 === result.compared && 0 === result.differences.length) {
+        lines.push(MSG_NOTHING_COMPARED);
+        return lines;
+    }
+    if (0 === result.differences.length) {
+        lines.push(MSG_SAME);
+        return lines;
+    }
+    lines.push(`${String(result.differences.length)} differences:`, '');
+    for (const difference of result.differences) {
+        lines.push(...differenceLines(difference), '');
+    }
+    return lines;
+}
+/** The `--results-json` file. Every count the text gives is here too, so nothing is dropped silently. */
+export function compareJson(urls, result) {
+    return {
+        schemaVersion: COMPARE_SCHEMA_VERSION,
+        ...urls,
+        identical: EXIT_SAME === compareExit(result),
+        ...result,
+    };
+}

package/dist/features/compare/compare-run.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Drive two builds of one app with the same actions, and read what each one shows after every step.
+ *
+ * The actions come from two places. The project's saved flows are replayed one step at a time, and
+ * the page is read after each step, not only where the flow has a check. The explorer the exhaustive
+ * crawl uses (`explore`) walks the reference's states breadth first, and every click it tried
+ * becomes a journey. Only the reference is explored: both builds then get the same list of journeys,
+ * so a control the candidate lost shows as a step it could not do.
+ *
+ * Four browsers, one after the other: one to explore, two runs of the reference (the second sets
+ * what is noise), and one run of the candidate. Each run starts in a new browser, so state one run
+ * leaves (a cookie, local storage) cannot reach the next one.
+ */
+import { type ExplorePort } from '../exhaust/explorer.js';
+import { type Comparison } from './compare-diff.js';
+/** A browser on one build: what the explorer needs, plus a full read and one step of a saved flow. */
+export interface CompareDriver extends ExplorePort {
+    /** The whole page as an accessibility tree. */
+    read(): Promise<string>;
+    /**
+     * Do step `index` of the saved flow `flow`. Step 0 opens the flow's start page first. Every later
+     * step continues on the page as the step before it left it. `label` says what the step did.
+     */
+    replayStep(flow: string, index: number): Promise<{
+        done: boolean;
+        label: string;
+    }>;
+    close(): Promise<void>;
+}
+export interface CompareInput {
+    reference: string;
+    candidate: string;
+    /** Open a new browser on a build. Throws when the build cannot be opened. */
+    open(url: string): Promise<CompareDriver>;
+    /** The saved flows to replay, and how many steps each has. */
+    flows: readonly {
+        name: string;
+        steps: number;
+    }[];
+    /** The explorer's action budget. */
+    maxActions: number;
+    /** Called after each action, before the page is read, so behaviour driven by a timer can show. */
+    wait: () => Promise<void>;
+}
+export interface CompareResult extends Comparison {
+    /** How many journeys each build was driven through. */
+    journeys: number;
+    /** What the explorer found on the reference. A non-zero frontier means it stopped at its budget. */
+    explored: {
+        states: number;
+        actions: number;
+        frontier: number;
+        budgetExhausted: boolean;
+    };
+}
+/** The action that reaches the start page, for the journey that only reads it. */
+export declare const START_ACTION = "open the start page";
+/** What the explorer types into a text field: this, then the field's position on its state. */
+export declare const FILL_TEXT = "text";
+export declare function compareBuilds(input: CompareInput): Promise<CompareResult>;

package/dist/features/compare/compare-run.js

@@ -0,0 +1,123 @@
+/**
+ * Drive two builds of one app with the same actions, and read what each one shows after every step.
+ *
+ * The actions come from two places. The project's saved flows are replayed one step at a time, and
+ * the page is read after each step, not only where the flow has a check. The explorer the exhaustive
+ * crawl uses (`explore`) walks the reference's states breadth first, and every click it tried
+ * becomes a journey. Only the reference is explored: both builds then get the same list of journeys,
+ * so a control the candidate lost shows as a step it could not do.
+ *
+ * Four browsers, one after the other: one to explore, two runs of the reference (the second sets
+ * what is noise), and one run of the candidate. Each run starts in a new browser, so state one run
+ * leaves (a cookie, local storage) cannot reach the next one.
+ */
+import { controlsOf, explore } from '../exhaust/explorer.js';
+import { compareReadings } from './compare-diff.js';
+import { visibleLines } from './visible-content.js';
+const JourneyKind = { FLOW: 'flow', PATH: 'path' };
+const StepAction = { CLICK: 'click', FILL: 'fill' };
+/** The action that reaches the start page, for the journey that only reads it. */
+export const START_ACTION = 'open the start page';
+/** What the explorer types into a text field: this, then the field's position on its state. */
+export const FILL_TEXT = 'text';
+const flowStepLabel = (flow, index, label) => `flow "${flow}" step ${String(index + 1)}: ${label}`;
+const pathStepLabel = (step) => StepAction.FILL === step.action
+    ? `${StepAction.FILL} ${step.key} with "${step.value ?? ''}"`
+    : `${StepAction.CLICK} ${step.key}`;
+/** The paths that are not the start of a longer path: reading a long path reads its starts too. */
+function longestPaths(paths) {
+    const text = paths.map((path) => path.map((step) => JSON.stringify(step)));
+    return paths.filter((path, i) => text.every((other, j) => i === j || other.length <= path.length || path.some((_, k) => other[k] !== text[i]?.[k])));
+}
+async function readLines(driver, wait) {
+    await wait();
+    return visibleLines(await driver.read());
+}
+async function readFlow(driver, journey, flow, wait) {
+    const out = [];
+    const actions = [];
+    for (let step = 0; step < flow.steps; step += 1) {
+        const done = await driver.replayStep(flow.name, step);
+        actions.push(flowStepLabel(flow.name, step, done.label));
+        if (!done.done) {
+            out.push({ journey, step, actions: [...actions] });
+            break;
+        }
+        out.push({ journey, step, actions: [...actions], lines: await readLines(driver, wait) });
+    }
+    return out;
+}
+async function readPath(driver, journey, steps, wait) {
+    if (!(await driver.reset())) {
+        return [{ journey, step: 0, actions: [START_ACTION] }];
+    }
+    if (0 === steps.length) {
+        return [{ journey, step: 0, actions: [START_ACTION], lines: await readLines(driver, wait) }];
+    }
+    const out = [];
+    const actions = [];
+    for (const [index, step] of steps.entries()) {
+        actions.push(pathStepLabel(step));
+        // The first control with this identity, on every build, so both builds act on the same one.
+        const control = controlsOf((await driver.look()).tree).find((c) => c.key === step.key);
+        const done = control !== undefined && (await driver.act(control.ref, step.action, step.value)).ok;
+        if (!done) {
+            out.push({ journey, step: index, actions: [...actions] });
+            break;
+        }
+        out.push({ journey, step: index, actions: [...actions], lines: await readLines(driver, wait) });
+    }
+    return out;
+}
+/** Drive one build through every journey, in a new browser, and read it after every step. */
+async function readBuild(input, url, journeys) {
+    const driver = await input.open(url);
+    try {
+        const out = [];
+        for (const [index, journey] of journeys.entries()) {
+            if (JourneyKind.FLOW === journey.kind) {
+                out.push(...(await readFlow(driver, index, journey, input.wait)));
+            }
+            else {
+                out.push(...(await readPath(driver, index, journey.steps, input.wait)));
+            }
+        }
+        return out;
+    }
+    finally {
+        await driver.close();
+    }
+}
+export async function compareBuilds(input) {
+    const explorer = await input.open(input.reference);
+    let report;
+    try {
+        report = await explore(explorer, {
+            maxActions: input.maxActions,
+            // Each field its own value, so a build that swaps two fields does not read the same.
+            fillValue: (_label, index) => `${FILL_TEXT} ${String(index + 1)}`,
+            wait: input.wait,
+        });
+    }
+    finally {
+        await explorer.close();
+    }
+    const journeys = [
+        ...input.flows.map((flow) => ({ kind: JourneyKind.FLOW, ...flow })),
+        { kind: JourneyKind.PATH, steps: [] },
+        ...longestPaths(report.paths).map((steps) => ({ kind: JourneyKind.PATH, steps })),
+    ];
+    const reference = await readBuild(input, input.reference, journeys);
+    const again = await readBuild(input, input.reference, journeys);
+    const candidate = await readBuild(input, input.candidate, journeys);
+    return {
+        ...compareReadings(reference, again, candidate),
+        journeys: journeys.length,
+        explored: {
+            states: report.states,
+            actions: report.actions,
+            frontier: report.frontier,
+            budgetExhausted: report.budgetExhausted,
+        },
+    };
+}

package/dist/features/compare/outside/effect-lines.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What the app DID, as lines that compare like page text. Pure.
+ *
+ * A wrong payload, a swallowed failure, a duplicate submit or a thrown error can leave the page the
+ * same; it shows here. Each network call is its method, its path (the host removed, the query values
+ * blanked, the keys kept), its status, and the start of its request body. Each console error or
+ * warning is its level and text.
+ *
+ * A repeated identical GET is kept once. A list that loads one more page on one run is not a change
+ * in behaviour, and a read changes nothing on the server. A repeated write is kept: a double submit
+ * is a defect.
+ *
+ * A read that failed is written as an `effects failed` line, never dropped: an empty list must mean
+ * that nothing happened.
+ */
+/** The lines of a `reticle_observe { action: "network" }` result. */
+export declare function networkLines(result: unknown): string[];
+/** The error and warning lines of a `reticle_observe { action: "console" }` result. */
+export declare function consoleLines(result: unknown): string[];
+/**
+ * A read that loaded. Compare does not count it as a difference: what it loaded shows on the page, and when a
+ * read runs (a font, a refetch) changes from run to run. A read that failed, and every write, still count.
+ */
+export declare const isLoadedRead: (line: string) => boolean;
+/** A network line for a call that was still in flight when it was read. */
+export declare const isPendingLine: (line: string) => boolean;

package/dist/features/compare/outside/effect-lines.js

@@ -0,0 +1,103 @@
+/**
+ * What the app DID, as lines that compare like page text. Pure.
+ *
+ * A wrong payload, a swallowed failure, a duplicate submit or a thrown error can leave the page the
+ * same; it shows here. Each network call is its method, its path (the host removed, the query values
+ * blanked, the keys kept), its status, and the start of its request body. Each console error or
+ * warning is its level and text.
+ *
+ * A repeated identical GET is kept once. A list that loads one more page on one run is not a change
+ * in behaviour, and a read changes nothing on the server. A repeated write is kept: a double submit
+ * is a defect.
+ *
+ * A read that failed is written as an `effects failed` line, never dropped: an empty list must mean
+ * that nothing happened.
+ */
+const NET = 'net:';
+const CONSOLE = 'console';
+const EFFECTS_FAILED = 'effects failed:';
+const NETWORK_SOURCE = 'network';
+const CONSOLE_SOURCE = 'console';
+const NO_ANSWER = 'no answer';
+/** The status a call still in flight carries. */
+const PENDING = 'pending';
+const KEPT_LEVELS = new Set(['error', 'warn', 'warning']);
+const BODY_CHARS = 120;
+const TEXT_CHARS = 200;
+const FAILURE_CHARS = 160;
+const HOST = /^[a-z][a-z0-9+.-]*:\/\/[^/]+/i;
+const QUERY_VALUE = /=[^&#]*/g;
+const asText = (value) => 'string' === typeof value ? value : undefined;
+const record = (value) => 'object' === typeof value && null !== value ? value : undefined;
+const oneLine = (text, max) => text.replace(/\s+/g, ' ').trim().slice(0, max);
+/** The list under `key`, or the reason it is not there. */
+function listOf(result, key) {
+    const r = record(result);
+    const items = r?.[key];
+    if (Array.isArray(items)) {
+        return { items };
+    }
+    const why = asText(r?.['error']) ?? (r === undefined ? NO_ANSWER : JSON.stringify(r));
+    return { failed: oneLine(why, FAILURE_CHARS) };
+}
+/** The path of a url, with the host removed and the query values blanked. */
+const pathOf = (url) => url.replace(HOST, '').replace(QUERY_VALUE, '=');
+const READ_METHOD = 'GET';
+/** The lines of a `reticle_observe { action: "network" }` result. */
+export function networkLines(result) {
+    const list = listOf(result, 'calls');
+    if ('failed' in list) {
+        return [`${EFFECTS_FAILED} ${NETWORK_SOURCE}: ${list.failed}`];
+    }
+    const reads = new Set();
+    return list.items.flatMap((item) => {
+        const line = callLine(item);
+        if (line.startsWith(`${NET} ${READ_METHOD} `)) {
+            if (reads.has(line)) {
+                return [];
+            }
+            reads.add(line);
+        }
+        return [line];
+    });
+}
+/** One call as a line. */
+function callLine(item) {
+    const call = record(item) ?? {};
+    const status = call['status'];
+    const parts = [
+        NET,
+        asText(call['method']) ?? READ_METHOD,
+        pathOf(asText(call['url']) ?? ''),
+        'number' === typeof status || 'string' === typeof status ? String(status) : '',
+    ];
+    const body = asText(call['requestBody']);
+    if (body !== undefined && body.length > 0) {
+        parts.push(oneLine(body, BODY_CHARS));
+    }
+    return parts.filter((p) => p.length > 0).join(' ');
+}
+/** The error and warning lines of a `reticle_observe { action: "console" }` result. */
+export function consoleLines(result) {
+    const list = listOf(result, 'logs');
+    if ('failed' in list) {
+        return [`${EFFECTS_FAILED} ${CONSOLE_SOURCE}: ${list.failed}`];
+    }
+    const out = [];
+    for (const item of list.items) {
+        const log = record(item) ?? {};
+        const level = asText(log['level']) ?? '';
+        if (KEPT_LEVELS.has(level)) {
+            out.push(`${CONSOLE} ${level}: ${oneLine(asText(log['text']) ?? '', TEXT_CHARS)}`);
+        }
+    }
+    return out;
+}
+const LOADED_READ = /^net: GET \S+ [1-3]\d\d$/;
+/**
+ * A read that loaded. Compare does not count it as a difference: what it loaded shows on the page, and when a
+ * read runs (a font, a refetch) changes from run to run. A read that failed, and every write, still count.
+ */
+export const isLoadedRead = (line) => LOADED_READ.test(line);
+/** A network line for a call that was still in flight when it was read. */
+export const isPendingLine = (line) => line.startsWith(NET) && line.split(' ').includes(PENDING);

package/dist/features/compare/outside/state-sources.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+export declare const StateSourceKind: {
+    readonly COMMAND: "command";
+    readonly HTTP: "http";
+    readonly FILE: "file";
+};
+/**
+ * Rows kept for each source. More are cut, and a line declares the cut and a digest of the cut rows.
+ *
+ * ponytail: the line diff is an O(n*m) table, so a source of thousands of rows makes each compared
+ * sequence slow. Raise this only with a faster diff.
+ */
+export declare const STATE_ROW_CAP = 1000;
+export declare const STATE_PREFIX = "state";
+export declare const MSG_READ_FAILED = "state read failed:";
+export declare const MSG_ROWS_CUT = "state rows cut:";
+export declare const StateSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"command">;
+    label: z.ZodString;
+    command: z.ZodString;
+    container: z.ZodOptional<z.ZodString>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"http">;
+    label: z.ZodString;
+    url: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    label: z.ZodString;
+    path: z.ZodString;
+    at: z.ZodOptional<z.ZodString>;
+    container: z.ZodOptional<z.ZodString>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>], "kind">;
+export type StateSource = z.infer<typeof StateSourceSchema>;
+/** The `--state` file. */
+export declare const StateDeclarationSchema: z.ZodObject<{
+    sources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"command">;
+        label: z.ZodString;
+        command: z.ZodString;
+        container: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"http">;
+        label: z.ZodString;
+        url: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        label: z.ZodString;
+        path: z.ZodString;
+        at: z.ZodOptional<z.ZodString>;
+        container: z.ZodOptional<z.ZodString>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+/** How the sources are read. Each method throws when the read fails. */
+export interface StateIo {
+    /** The standard output of `command`, run on the host, or in `container` when one is given. */
+    run(command: string, container?: string): Promise<string>;
+    fetchJson(url: string): Promise<unknown>;
+    readFile(path: string): Promise<string>;
+}
+/** The rows of one source, unsorted and without the `state <label>` prefix. Throws when the read fails. */
+export declare function sourceRows(source: StateSource, io: StateIo): Promise<string[]>;
+/**
+ * Every source, read and turned into sorted `state <label> <row>` lines, in declared order. A read
+ * that fails is one `state read failed: <label>: <reason>` line. A source with more than
+ * `cap` rows (`STATE_ROW_CAP` by default) keeps the first rows in sorted order, then a `state rows cut:` line. That line
+ * holds a digest of the rows it cuts, so a change to a cut row still makes the reading differ.
+ */
+export declare function readStateSources(sources: readonly StateSource[], io: StateIo, cap?: number): Promise<string[]>;

package/dist/features/compare/outside/state-sources.js

@@ -0,0 +1,164 @@
+/**
+ * Declared state sources: the data an app keeps, read as lines that `reticle compare` diffs like a
+ * page read. A page read sees only the pages a sequence opens. A change to another record (the
+ * price of another product) was not seen, and the candidate passed.
+ *
+ * The user declares each source as data. Nothing here knows one app:
+ * - `command`: the output rows of a shell command on the host, or in `container` through
+ *   `docker exec <container> sh -c`. A database dump goes through the database's own client.
+ * - `http`: the records of a JSON endpoint. `path` is a dotted path to the array.
+ * - `file`: a file of JSON records (`at` is a dotted path to the array), or of plain lines. With
+ *   `container`, it is read in that container.
+ *
+ * `ignore` holds field names to remove from JSON records, or regular expressions to remove from text
+ * rows (a time, an id that changes on each run). Each row becomes `state <label> <row>`, sorted. A
+ * row that identifies a record starts with the record id, so a changed row names its record.
+ *
+ * I/O is injected (`StateIo`), so this file is pure.
+ */
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const StateSourceKind = {
+    COMMAND: 'command',
+    HTTP: 'http',
+    FILE: 'file',
+};
+/**
+ * Rows kept for each source. More are cut, and a line declares the cut and a digest of the cut rows.
+ *
+ * ponytail: the line diff is an O(n*m) table, so a source of thousands of rows makes each compared
+ * sequence slow. Raise this only with a faster diff.
+ */
+export const STATE_ROW_CAP = 1000;
+export const STATE_PREFIX = 'state';
+export const MSG_READ_FAILED = 'state read failed:';
+export const MSG_ROWS_CUT = 'state rows cut:';
+const DIGEST_ALGORITHM = 'sha256';
+const DIGEST_LENGTH = 16;
+/** A short digest of the rows past the cap, so a change to one of them changes the cut line. */
+const digestOf = (rows) => createHash(DIGEST_ALGORITHM).update(rows.join('\n')).digest('hex').slice(0, DIGEST_LENGTH);
+const PATH_SEPARATOR = '.';
+const LINE_BREAK = /\r?\n/;
+const ANY_LINE_BREAK = /\s*\r?\n\s*/g;
+const label = z.string().min(1).describe('The name each row of this source starts with.');
+const ignore = z.array(z.string()).optional();
+const container = z.string().min(1).optional();
+export const StateSourceSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z.literal(StateSourceKind.COMMAND),
+        label,
+        command: z.string().min(1),
+        container,
+        ignore,
+    }),
+    z.strictObject({
+        kind: z.literal(StateSourceKind.HTTP),
+        label,
+        url: z.string().min(1),
+        path: z.string().optional(),
+        ignore,
+    }),
+    z.strictObject({
+        kind: z.literal(StateSourceKind.FILE),
+        label,
+        path: z.string().min(1),
+        at: z.string().optional(),
+        container,
+        ignore,
+    }),
+]);
+/** The `--state` file. */
+export const StateDeclarationSchema = z.strictObject({
+    sources: z.array(StateSourceSchema).min(1),
+});
+const isRecord = (value) => value !== null && 'object' === typeof value && !Array.isArray(value);
+const sortKeys = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((k) => [k, sortKeys(value[k])]));
+    }
+    return value;
+};
+const at = (value, path) => path === undefined
+    ? value
+    : path
+        .split(PATH_SEPARATOR)
+        .reduce((v, key) => (isRecord(v) ? v[key] : undefined), value);
+function recordRows(value, dropped = []) {
+    const records = Array.isArray(value) ? value : [value];
+    return records.map((record) => {
+        if (!isRecord(record)) {
+            return JSON.stringify(record);
+        }
+        const kept = Object.fromEntries(Object.entries(record).filter(([k]) => !dropped.includes(k)));
+        return JSON.stringify(sortKeys(kept));
+    });
+}
+function textRows(text, patterns = []) {
+    const res = patterns.map((p) => new RegExp(p, 'g'));
+    return (text
+        .split(LINE_BREAK)
+        .filter((line) => '' !== line.trim())
+        .map((line) => res.reduce((row, re) => row.replace(re, ''), line))
+        // A pattern that removes all of a row removes the row, so a row of no meaning can be ignored.
+        .filter((row) => '' !== row.trim()));
+}
+/** A shell word that holds `text` as it is. */
+const shellQuote = (text) => `'${text.replaceAll("'", "'\\''")}'`;
+/** JSON records when the text is JSON, else plain lines. */
+function fileRows(text, path, patterns) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return textRows(text, patterns);
+    }
+    return recordRows(at(parsed, path), patterns);
+}
+/** The rows of one source, unsorted and without the `state <label>` prefix. Throws when the read fails. */
+export async function sourceRows(source, io) {
+    switch (source.kind) {
+        case StateSourceKind.COMMAND:
+            return textRows(await io.run(source.command, source.container), source.ignore);
+        case StateSourceKind.HTTP:
+            return recordRows(at(await io.fetchJson(source.url), source.path), source.ignore);
+        case StateSourceKind.FILE: {
+            const text = source.container === undefined
+                ? await io.readFile(source.path)
+                : await io.run(`cat ${shellQuote(source.path)}`, source.container);
+            return fileRows(text, source.at, source.ignore);
+        }
+    }
+}
+const reasonOf = (error) => (error instanceof Error ? error.message : String(error)).trim().replace(ANY_LINE_BREAK, ' ');
+/**
+ * Every source, read and turned into sorted `state <label> <row>` lines, in declared order. A read
+ * that fails is one `state read failed: <label>: <reason>` line. A source with more than
+ * `cap` rows (`STATE_ROW_CAP` by default) keeps the first rows in sorted order, then a `state rows cut:` line. That line
+ * holds a digest of the rows it cuts, so a change to a cut row still makes the reading differ.
+ */
+export async function readStateSources(sources, io, cap = STATE_ROW_CAP) {
+    const out = [];
+    for (const source of sources) {
+        let rows;
+        try {
+            rows = (await sourceRows(source, io)).sort();
+        }
+        catch (error) {
+            out.push(`${MSG_READ_FAILED} ${source.label}: ${reasonOf(error)}`);
+            continue;
+        }
+        for (const row of rows.slice(0, cap)) {
+            out.push(`${STATE_PREFIX} ${source.label} ${row}`);
+        }
+        if (rows.length > cap) {
+            out.push(`${MSG_ROWS_CUT} ${source.label}: kept ${String(cap)} of ${String(rows.length)}, rest ${digestOf(rows.slice(cap))}`);
+        }
+    }
+    return out;
+}