@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/rest/storage.js

@@ -0,0 +1,262 @@
+/**
+ * How REST APIs are stored in a project folder (spec §3.2): `apis/<slug>/api.yaml` with
+ * `kind: rest`, and a tree of folders and `*.request.yaml` files under `requests/`, a raw body in
+ * the sibling `<slug>.body.<ext>`.
+ *
+ * `restRequestReader` and `signingOf` are exported for core's loader, which reads the project's
+ * webhook collection (REST requests in a tree of their own) until phase 3 of #184 moves it here.
+ */
+import { toCallbackAssertion } from '../assert/schema.js';
+import { ProjectError } from '../errors.js';
+import { readFileIfExists } from '../project/fs.js';
+import { abs, authConfig, definitionAuth, exact, keyValueEntries, loadFolderContents, loadScripts, optional, readYaml, } from '../project/load-helpers.js';
+import { apiManagedFiles } from '../project/managed-files.js';
+import { API_FILE, APIS_DIR, assertPathSegment, REQUEST_SUFFIX, REQUESTS_DIR, restBodyFileName, WEBHOOKS_DIR, } from '../project/paths.js';
+import { assertSupportedKind, parseFile } from '../project/schema-parts.js';
+import { addFolderFiles, authDocument, definitionDocument, keyValueDocuments, scriptsDocument, writeScriptFiles, } from '../project/serialize-helpers.js';
+import { compact, stringifyYaml } from '../project/yaml.js';
+import { toSignatureScheme } from '../http/webhook-signature.js';
+import { apiFileSchema, restRequestFileSchema } from './files.js';
+import { RAW_LANGUAGE_EXTENSIONS } from './model.js';
+/** A parsed `signing` key as the model holds it. */
+export function signingOf(parsed) {
+    if (parsed.mode === 'none')
+        return { mode: 'none' };
+    return {
+        mode: 'sign',
+        scheme: toSignatureScheme(parsed.scheme),
+        ...optional('secretRef', parsed.secretRef),
+        ...optional('secretEnv', parsed.secretEnv),
+    };
+}
+/**
+ * One request body as loaded. A raw body's text lives in a sibling file, so it is read here and
+ * the file name is dropped: the model holds the text, the layout holds the name
+ * (`project/paths.ts` rebuilds it on save from the language).
+ */
+async function loadBody(fs, root, dir, document, requestName, problems) {
+    switch (document.kind) {
+        case 'raw': {
+            // The name comes from the request file, which a pull or an import may have written: it must
+            // name a file beside the request, never one elsewhere on the machine (`../…`).
+            assertPathSegment(document.file);
+            const relative = `${dir}/${document.file}`;
+            const text = await readFileIfExists(fs, abs(root, relative));
+            if (text === undefined) {
+                problems.push({
+                    code: 'missing-body',
+                    message: `Request "${requestName}" has no body file; loaded with an empty body`,
+                    file: relative,
+                });
+            }
+            return {
+                kind: 'raw',
+                language: document.language,
+                ...optional('contentType', document.contentType),
+                text: text === undefined ? '' : text.toString('utf8'),
+            };
+        }
+        case 'form':
+            return { kind: 'form', fields: keyValueEntries(document.fields) };
+        case 'multipart':
+            return {
+                kind: 'multipart',
+                parts: document.parts.map((part) => part.kind === 'text'
+                    ? exact({ ...part, kind: 'text' })
+                    : exact({ ...part, kind: 'file' })),
+            };
+        case 'binary':
+            return { kind: 'binary', source: document.source, contentType: document.contentType };
+        default:
+            return { kind: 'none' };
+    }
+}
+/** Reads a REST request and its raw body file. */
+export function restRequestReader(fs, root, problems) {
+    return async (dir, fileName, unclaimed) => {
+        const relative = `${dir}/${fileName}`;
+        const document = await readYaml(fs, root, relative);
+        assertSupportedKind(document, relative);
+        const parsed = parseFile(restRequestFileSchema, document, relative);
+        unclaimed.delete(fileName);
+        if (parsed.body.kind === 'raw') {
+            unclaimed.delete(parsed.body.file);
+        }
+        const slug = fileName.slice(0, -REQUEST_SUFFIX.length);
+        const scripts = await loadScripts(fs, root, dir, slug, parsed.scripts, parsed.name, problems, (name) => unclaimed.delete(name));
+        return {
+            kind: 'rest',
+            id: parsed.id,
+            name: parsed.name,
+            slug,
+            order: parsed.order,
+            ...optional('description', parsed.description),
+            method: parsed.method,
+            url: parsed.url,
+            pathParams: keyValueEntries(parsed.pathParams),
+            query: keyValueEntries(parsed.query),
+            headers: keyValueEntries(parsed.headers),
+            body: await loadBody(fs, root, dir, parsed.body, parsed.name, problems),
+            auth: authConfig(parsed.auth),
+            settings: exact(parsed.settings),
+            assertions: parsed.assertions.map((a) => (a.type === 'callback' ? toCallbackAssertion(a) : exact(a))),
+            ...(parsed.orphaned === true ? { orphaned: true } : {}),
+            ...(parsed.contract !== undefined
+                ? { contract: { method: parsed.contract.method, path: parsed.contract.path } }
+                : {}),
+            ...(parsed.hook !== undefined ? { hook: exact(parsed.hook) } : {}),
+            ...(parsed.signing !== undefined ? { signing: signingOf(parsed.signing) } : {}),
+            ...(scripts !== undefined ? { scripts } : {}),
+        };
+    };
+}
+/** A REST request under `apis/`: the same as {@link restRequestReader}, but a `hook` or `signing` has no place there. */
+function apiRequestReader(fs, root, problems) {
+    const read = restRequestReader(fs, root, problems);
+    return async (dir, fileName, unclaimed) => {
+        const request = await read(dir, fileName, unclaimed);
+        const misplaced = request.hook !== undefined ? 'hook' : request.signing !== undefined ? 'signing' : undefined;
+        if (misplaced !== undefined) {
+            const file = `${dir}/${fileName}`;
+            throw new ProjectError('project-file-invalid', `Invalid project file ${file}: ${misplaced} is only allowed under ${WEBHOOKS_DIR}/`, {
+                details: { file, issues: [{ path: misplaced, message: `only allowed under ${WEBHOOKS_DIR}/` }] },
+            });
+        }
+        return request;
+    };
+}
+/** A `signing` key as written: the scheme's own fields, and references only. */
+export function signingDocument(signing) {
+    if (signing === undefined)
+        return undefined;
+    if (signing.mode === 'none')
+        return { mode: 'none' };
+    return compact({
+        mode: 'sign',
+        scheme: compact({ ...signing.scheme }),
+        secretRef: signing.secretRef,
+        secretEnv: signing.secretEnv,
+    });
+}
+/**
+ * A body as written, plus the sibling file a raw body needs.
+ *
+ * The text of a raw body is deliberately *not* in the request document: it goes to
+ * `<slug>.body.<ext>` beside it, so a JSON payload is a JSON file in git — reviewable, searchable
+ * and mergeable — rather than a quoted blob inside YAML.
+ */
+function bodyDocument(body, requestSlug) {
+    switch (body.kind) {
+        case 'raw': {
+            const name = restBodyFileName(requestSlug, RAW_LANGUAGE_EXTENSIONS[body.language]);
+            assertPathSegment(name);
+            return {
+                document: compact({ kind: 'raw', language: body.language, contentType: body.contentType, file: name }),
+                file: [name, body.text],
+            };
+        }
+        case 'form':
+            return { document: { kind: 'form', fields: keyValueDocuments(body.fields) } };
+        case 'multipart':
+            return {
+                document: {
+                    kind: 'multipart',
+                    parts: body.parts.map((part) => compact({ ...part, enabled: part.enabled ? undefined : false })),
+                },
+            };
+        case 'binary':
+            return { document: { kind: 'binary', source: { ...body.source }, contentType: body.contentType } };
+        default:
+            return { document: { kind: 'none' } };
+    }
+}
+function restRequestDocument(request) {
+    const body = bodyDocument(request.body, request.slug);
+    return compact({
+        kind: request.kind,
+        id: request.id,
+        name: request.name,
+        order: request.order,
+        description: request.description,
+        method: request.method,
+        url: request.url,
+        pathParams: request.pathParams.length > 0 ? keyValueDocuments(request.pathParams) : undefined,
+        query: request.query.length > 0 ? keyValueDocuments(request.query) : undefined,
+        headers: request.headers.length > 0 ? keyValueDocuments(request.headers) : undefined,
+        body: body.document,
+        auth: authDocument(request.auth),
+        settings: Object.keys(request.settings).length > 0 ? compact({ ...request.settings }) : undefined,
+        assertions: request.assertions.length > 0 ? request.assertions.map((a) => compact({ ...a })) : undefined,
+        orphaned: request.orphaned === true ? true : undefined,
+        contract: request.contract === undefined ? undefined : { method: request.contract.method, path: request.contract.path },
+        hook: request.hook === undefined ? undefined : { ...request.hook },
+        signing: signingDocument(request.signing),
+        scripts: scriptsDocument(request.scripts, request.slug).document,
+    });
+}
+/** A REST request as written: its document, its raw body file and its script files. Core writes the webhook collection's items with it. */
+export const writeRestRequest = (files, dir, request) => {
+    const body = bodyDocument(request.body, request.slug);
+    files.set(`${dir}/${request.slug}${REQUEST_SUFFIX}`, stringifyYaml(restRequestDocument(request)));
+    if (body.file !== undefined) {
+        files.set(`${dir}/${body.file[0]}`, body.file[1]);
+    }
+    writeScriptFiles(files, dir, request.scripts, request.slug);
+};
+/** Every file one REST API occupies, keyed by path relative to the project root. */
+function addApiFiles(files, api) {
+    assertPathSegment(api.slug);
+    const base = `${APIS_DIR}/${api.slug}`;
+    files.set(`${base}/${API_FILE}`, stringifyYaml(compact({
+        kind: api.kind,
+        id: api.id,
+        name: api.name,
+        order: api.order,
+        description: api.description,
+        baseUrl: api.baseUrl,
+        servers: api.servers.length > 0 ? api.servers.map((server) => compact({ ...server })) : undefined,
+        auth: api.auth === undefined ? undefined : authDocument(api.auth),
+        definition: api.definition === undefined ? undefined : definitionDocument(api.definition),
+    })));
+    addFolderFiles(files, `${base}/${REQUESTS_DIR}`, api, 0, writeRestRequest);
+}
+/** REST's storage facet. */
+export const restStorage = {
+    dir: APIS_DIR,
+    async load(ctx, slug, document) {
+        const { fs, root, problems } = ctx;
+        const parsed = parseFile(apiFileSchema, document, `${APIS_DIR}/${slug}/${API_FILE}`);
+        const contents = await loadFolderContents(fs, root, `${APIS_DIR}/${slug}/${REQUESTS_DIR}`, 0, problems, apiRequestReader(fs, root, problems));
+        return {
+            kind: 'rest',
+            id: parsed.id,
+            name: parsed.name,
+            slug,
+            order: parsed.order,
+            ...optional('description', parsed.description),
+            baseUrl: parsed.baseUrl,
+            servers: parsed.servers.map((server) => exact(server)),
+            ...(parsed.auth !== undefined ? { auth: authConfig(parsed.auth) } : {}),
+            ...(parsed.definition !== undefined
+                ? {
+                    definition: {
+                        source: parsed.definition.source,
+                        cache: parsed.definition.cache,
+                        version: parsed.definition.version,
+                        ...optional('auth', definitionAuth(parsed.definition.auth)),
+                    },
+                }
+                : {}),
+            folders: contents.folders,
+            requests: contents.requests,
+        };
+    },
+    files(api) {
+        const files = new Map();
+        addApiFiles(files, api);
+        return files;
+    },
+    managed: (fs, root, slug) => apiManagedFiles(fs, root, slug),
+    containers: (project) => project.apis,
+    withContainers: (project, apis) => ({ ...project, apis }),
+};

package/dist/rest/url.d.ts

@@ -80,13 +80,19 @@ export declare function joinQuery(path: string, query: readonly KeyValueEntry[])
  * Builds the URL one send actually uses.
  *
  * Order of work: the request's URL wins over the base when it is absolute; `{name}` parameters are
- * filled from the enabled rows of `pathParams`; the URL's own query string and the `query` table
- * are concatenated, in that order, so a parameter typed into the field and one added in the table
- * both survive; every value is encoded unless `encode` is off.
+ * filled from the enabled rows of `pathParams`; the query is the enabled `query` rows, preceded by
+ * any parameter of the URL's own query string that no enabled row carries; every value is encoded
+ * unless `encode` is off.
+ *
+ * The table owns the query. The editor mirrors it into the URL field, so a saved request usually
+ * holds each parameter twice — once in `url`, once as a row — and sending both would send it twice.
+ * A URL parameter with the same name and value as an enabled row is that row, matched one for one
+ * so deliberate duplicates survive. One no row carries (a hand-written file, a URL with no table)
+ * is still sent, ahead of the rows, as it is written.
  *
  * @param base the API's effective base URL, already expanded
  * @param url the request's URL, already expanded
  * @param pathParams values for the URL's `{name}` placeholders
- * @param query query rows to append
+ * @param query query rows, the request's stored query
  */
 export declare function composeUrl(base: string, url: string, pathParams?: readonly KeyValueEntry[], query?: readonly KeyValueEntry[], options?: ComposeUrlOptions): ComposedUrl;

package/dist/rest/url.js

@@ -159,14 +159,20 @@ export function joinQuery(path, query) {
  * Builds the URL one send actually uses.
  *
  * Order of work: the request's URL wins over the base when it is absolute; `{name}` parameters are
- * filled from the enabled rows of `pathParams`; the URL's own query string and the `query` table
- * are concatenated, in that order, so a parameter typed into the field and one added in the table
- * both survive; every value is encoded unless `encode` is off.
+ * filled from the enabled rows of `pathParams`; the query is the enabled `query` rows, preceded by
+ * any parameter of the URL's own query string that no enabled row carries; every value is encoded
+ * unless `encode` is off.
+ *
+ * The table owns the query. The editor mirrors it into the URL field, so a saved request usually
+ * holds each parameter twice — once in `url`, once as a row — and sending both would send it twice.
+ * A URL parameter with the same name and value as an enabled row is that row, matched one for one
+ * so deliberate duplicates survive. One no row carries (a hand-written file, a URL with no table)
+ * is still sent, ahead of the rows, as it is written.
  *
  * @param base the API's effective base URL, already expanded
  * @param url the request's URL, already expanded
  * @param pathParams values for the URL's `{name}` placeholders
- * @param query query rows to append
+ * @param query query rows, the request's stored query
  */
 export function composeUrl(base, url, pathParams = [], query = [], options = {}) {
     const encode = options.encode ?? true;
@@ -189,7 +195,7 @@ export function composeUrl(base, url, pathParams = [], query = [], options = {})
         // segment the request did not ask for.
         return encode ? encodeValue(value, "!$&'()*+,;=:@") : value;
     });
-    const rows = [...inlineQuery, ...query].filter((row) => row.enabled);
+    const rows = [...unclaimed(inlineQuery, query), ...query.filter((row) => row.enabled)];
     const search = rows
         .map((row) => {
         const name = encode ? encodeValue(row.name, '') : row.name;
@@ -206,6 +212,33 @@ export function composeUrl(base, url, pathParams = [], query = [], options = {})
     }
     return { url: composed, problems };
 }
+/**
+ * The rows of `inline` that no enabled row of `table` accounts for, in order. Each table row claims
+ * at most one inline row with its name and value, so `?t=a&t=a` against two `t=a` rows is fully
+ * claimed and against one leaves one.
+ */
+function unclaimed(inline, table) {
+    const available = new Map();
+    for (const row of table) {
+        if (row.enabled) {
+            const key = queryKey(row);
+            available.set(key, (available.get(key) ?? 0) + 1);
+        }
+    }
+    return inline.filter((row) => {
+        const key = queryKey(row);
+        const left = available.get(key) ?? 0;
+        if (left === 0) {
+            return true;
+        }
+        available.set(key, left - 1);
+        return false;
+    });
+}
+/** One key per name and value; `=` cannot end a name, so the join is unambiguous. */
+function queryKey(row) {
+    return `${row.name}=${row.value}`;
+}
 /** Appends a query string to a URL that may already carry a fragment. */
 function appendSearch(url, search) {
     const hash = url.indexOf('#');

package/dist/run/baseline-update.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The runner's `--update-baseline` decision (#217): whether one response replaces, creates or
+ * leaves its golden, compared as `--baseline` compares. Pure; the run reads and writes the file.
+ */
+import type { AssertionSubject } from '../assert/model.js';
+import type { GoldenFile, GoldenRead, GoldenWrite } from '../snapshot/golden-file.js';
+import type { BaselineCheck, BaselineReport } from './baseline.js';
+export interface BaselineUpdateInput {
+    readonly read: GoldenRead;
+    readonly subject: AssertionSubject;
+    /** The request's own assertions failed: nothing is written. */
+    readonly failed: boolean;
+    readonly containsKnownSecret?: (value: string) => boolean;
+    readonly now: () => Date;
+}
+export type BaselineUpdatePlan = {
+    readonly kind: 'done';
+    readonly check: BaselineCheck;
+} | {
+    readonly kind: 'write';
+    readonly golden: GoldenFile;
+    readonly report: BaselineReport;
+};
+/** What the sink answered; `failed` when it threw. */
+export type SinkOutcome = GoldenWrite | {
+    readonly status: 'failed';
+    readonly message: string;
+};
+/**
+ * Own assertions first, then the golden read, then the comparison. Only a golden about to be
+ * written is checked for a secret and for text, so a matching golden is never refused.
+ */
+export declare function planBaselineUpdate(input: BaselineUpdateInput): BaselineUpdatePlan;
+/** The check for a planned write, once the sink has answered. */
+export declare function finishBaselineUpdate(report: BaselineReport, outcome: SinkOutcome): BaselineCheck;

package/dist/run/baseline-update.js

@@ -0,0 +1,97 @@
+/**
+ * The runner's `--update-baseline` decision (#217): whether one response replaces, creates or
+ * leaves its golden, compared as `--baseline` compares. Pure; the run reads and writes the file.
+ */
+import { diffSnapshot } from '../snapshot/diff.js';
+import { detectSnapshotFormat } from '../snapshot/format.js';
+import { parseIgnoreRules } from '../snapshot/ignore.js';
+import { BASELINE_REPORT_CHANGES, contentTypeOf, tooLarge } from './baseline.js';
+const REFUSED = {
+    secret: 'The response holds a secret value, so its baseline was not written.',
+    malformed: 'The saved baseline cannot be read (malformed), so it was not replaced.',
+    'not-a-file': 'The baseline file is not a regular file, so it was not replaced.',
+    unsaved: 'The request file is not on disk, so no baseline was written.',
+    'write-failed': 'The baseline could not be written',
+};
+function refused(reason, detail) {
+    const assertion = {
+        type: 'baseline',
+        label: 'baseline not written',
+        outcome: 'errored',
+        message: detail === undefined ? REFUSED[reason] : `${REFUSED[reason]}: ${detail}`,
+    };
+    return { report: { status: 'refused', reason }, assertion };
+}
+const done = (check) => ({ kind: 'done', check });
+/** A NUL, or U+FFFD where the decoder met bytes that are not UTF-8: the Snapshot tab keeps no such body either. */
+const isText = (body) => !body.includes('\u0000') && !body.includes('�');
+/**
+ * Own assertions first, then the golden read, then the comparison. Only a golden about to be
+ * written is checked for a secret and for text, so a matching golden is never refused.
+ */
+export function planBaselineUpdate(input) {
+    const { read, subject } = input;
+    if (input.failed)
+        return done({ report: { status: 'skipped', reason: 'failed' } });
+    if (read.status === 'unreadable')
+        return done(refused(read.reason));
+    const body = subject.bodyText;
+    let report;
+    if (read.status === 'present') {
+        const old = read.golden;
+        if (tooLarge(old.body) || tooLarge(body)) {
+            // No semantic diff past the limit (#36); exact text decides.
+            if (old.body === body)
+                return done({ report: { status: 'matched' } });
+            report = { status: 'updated' };
+        }
+        else {
+            // The same calls `--baseline` and the Snapshot tab make.
+            const format = detectSnapshotFormat(old.body, old.contentType ?? contentTypeOf(subject));
+            const diff = diffSnapshot(old.body, body, { format, ignore: parseIgnoreRules(old.ignore.join('\n')) });
+            const shared = {
+                format: diff.format,
+                ignored: diff.ignored,
+                ...(diff.error !== undefined ? { error: diff.error } : {}),
+            };
+            if (diff.changes.length === 0)
+                return done({ report: { status: 'matched', ...shared } });
+            report = {
+                status: 'updated',
+                ...shared,
+                changes: diff.changes.slice(0, BASELINE_REPORT_CHANGES),
+                ...(diff.changes.length > BASELINE_REPORT_CHANGES ? { truncated: true } : {}),
+            };
+        }
+    }
+    else {
+        report = { status: 'created' };
+    }
+    if (input.containsKnownSecret?.(body) === true)
+        return done(refused('secret'));
+    if (!isText(body))
+        return done({ report: { status: 'skipped', reason: 'not-text' } });
+    const contentType = contentTypeOf(subject);
+    return {
+        kind: 'write',
+        report,
+        golden: {
+            ...(contentType !== undefined ? { contentType } : {}),
+            savedAt: input.now().toISOString(),
+            ignore: read.status === 'present' ? [...read.golden.ignore] : [],
+            body,
+        },
+    };
+}
+/** The check for a planned write, once the sink has answered. */
+export function finishBaselineUpdate(report, outcome) {
+    if (outcome.status === 'written') {
+        return {
+            report: { ...report, file: outcome.file },
+            assertion: { type: 'baseline', label: `baseline ${report.status}`, outcome: 'passed' },
+        };
+    }
+    if (outcome.status === 'refused')
+        return refused(outcome.reason);
+    return refused('write-failed', outcome.message);
+}

package/dist/run/baseline.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The runner's `--baseline` check (#36): one response against the golden saved beside its request,
+ * compared as the desktop's Snapshot tab compares them. Pure; the run reads the golden.
+ */
+import type { AssertionResult, AssertionSubject } from '../assert/model.js';
+import type { SnapshotChange, SnapshotFormat } from '../snapshot/diff.js';
+import type { GoldenRead } from '../snapshot/golden-file.js';
+/** Past this many UTF-8 bytes on either side, no semantic diff is attempted (as the Snapshot tab). */
+export declare const BASELINE_MAX_BYTES: number;
+/** Changes kept in a result's `baseline.changes`. */
+export declare const BASELINE_REPORT_CHANGES = 100;
+/** Changes listed in the failed assertion's message. */
+export declare const BASELINE_MESSAGE_CHANGES = 20;
+/** The protocols a golden can be saved for. */
+export declare const BASELINE_PROTOCOLS: ReadonlySet<string>;
+export type BaselineStatus = 'matched' | 'differs' | 'missing' | 'unreadable' | 'too-large' | 'unsupported' | 'updated' | 'created' | 'skipped' | 'refused';
+/** Why an update did not write: `skipped` for `failed` and `not-text`, `refused` for the rest. */
+export type BaselineReason = 'failed' | 'not-text' | 'secret' | 'malformed' | 'not-a-file' | 'unsaved' | 'write-failed';
+export interface BaselineReport {
+    readonly status: BaselineStatus;
+    readonly format?: SnapshotFormat;
+    readonly changes?: readonly SnapshotChange[];
+    readonly ignored?: number;
+    readonly truncated?: boolean;
+    readonly error?: string;
+    readonly reason?: BaselineReason;
+    /** The sidecar `--update-baseline` wrote, project-relative. */
+    readonly file?: string;
+}
+export interface BaselineCheck {
+    readonly report: BaselineReport;
+    readonly assertion?: AssertionResult;
+    /** Set only for a missing golden under `require`: the request errors with it. */
+    readonly error?: {
+        readonly code: 'baseline-missing';
+        readonly message: string;
+    };
+}
+export declare function tooLarge(text: string): boolean;
+export declare function contentTypeOf(subject: AssertionSubject): string | undefined;
+/** One response against the golden read for its request; `require` makes a missing golden an error. */
+export declare function checkBaseline(golden: GoldenRead, subject: AssertionSubject, require: boolean): BaselineCheck;

package/dist/run/baseline.js

@@ -0,0 +1,93 @@
+/**
+ * The runner's `--baseline` check (#36): one response against the golden saved beside its request,
+ * compared as the desktop's Snapshot tab compares them. Pure; the run reads the golden.
+ */
+import { diffSnapshot } from '../snapshot/diff.js';
+import { detectSnapshotFormat } from '../snapshot/format.js';
+import { parseIgnoreRules } from '../snapshot/ignore.js';
+/** Past this many UTF-8 bytes on either side, no semantic diff is attempted (as the Snapshot tab). */
+export const BASELINE_MAX_BYTES = 2 * 1024 * 1024;
+/** Changes kept in a result's `baseline.changes`. */
+export const BASELINE_REPORT_CHANGES = 100;
+/** Changes listed in the failed assertion's message. */
+export const BASELINE_MESSAGE_CHANGES = 20;
+/** The protocols a golden can be saved for. */
+export const BASELINE_PROTOCOLS = new Set(['soap', 'rest']);
+const encoder = new TextEncoder();
+export function tooLarge(text) {
+    // A UTF-16 code unit is at most 3 UTF-8 bytes, so only a borderline string needs encoding.
+    if (text.length > BASELINE_MAX_BYTES)
+        return true;
+    return text.length * 3 > BASELINE_MAX_BYTES && encoder.encode(text).length > BASELINE_MAX_BYTES;
+}
+export function contentTypeOf(subject) {
+    return subject.headers?.find(([name]) => name.toLowerCase() === 'content-type')?.[1];
+}
+function changeLine(change) {
+    if (change.kind === 'added')
+        return `added ${change.path}: ${change.actual ?? ''}`;
+    if (change.kind === 'removed')
+        return `removed ${change.path}: ${change.expected ?? ''}`;
+    return `changed ${change.path}: ${change.expected ?? ''} → ${change.actual ?? ''}`;
+}
+const errored = (status, message) => ({
+    report: { status },
+    assertion: { type: 'baseline', label: 'baseline', outcome: 'errored', message },
+});
+/** One response against the golden read for its request; `require` makes a missing golden an error. */
+export function checkBaseline(golden, subject, require) {
+    if (golden.status === 'none') {
+        return require
+            ? {
+                report: { status: 'missing' },
+                error: { code: 'baseline-missing', message: 'No baseline is saved for this request.' },
+            }
+            : { report: { status: 'missing' } };
+    }
+    if (golden.status === 'unreadable') {
+        return errored('unreadable', `The saved baseline cannot be read (${golden.reason}).`);
+    }
+    const { body, contentType, ignore } = golden.golden;
+    if (tooLarge(body) || tooLarge(subject.bodyText)) {
+        return errored('too-large', 'Too large to compare semantically.');
+    }
+    // The same calls the Snapshot tab makes, so CI and the app agree.
+    const format = detectSnapshotFormat(body, contentType ?? contentTypeOf(subject));
+    const diff = diffSnapshot(body, subject.bodyText, { format, ignore: parseIgnoreRules(ignore.join('\n')) });
+    const shared = {
+        format: diff.format,
+        ignored: diff.ignored,
+        ...(diff.error !== undefined ? { error: diff.error } : {}),
+    };
+    if (diff.changes.length === 0) {
+        return {
+            report: { status: 'matched', ...shared },
+            assertion: {
+                type: 'baseline',
+                label: diff.ignored > 0 ? `matches the baseline (${diff.ignored} ignored)` : 'matches the baseline',
+                outcome: 'passed',
+            },
+        };
+    }
+    const count = diff.changes.length;
+    const lines = diff.changes.slice(0, BASELINE_MESSAGE_CHANGES).map(changeLine);
+    if (count > BASELINE_MESSAGE_CHANGES)
+        lines.push(`… and ${count - BASELINE_MESSAGE_CHANGES} more`);
+    // Every reporter prints the message, so the fallback note reaches them all (and the masker).
+    if (diff.error !== undefined)
+        lines.unshift(`compared as text: ${diff.error}`);
+    return {
+        report: {
+            status: 'differs',
+            ...shared,
+            changes: diff.changes.slice(0, BASELINE_REPORT_CHANGES),
+            ...(count > BASELINE_REPORT_CHANGES ? { truncated: true } : {}),
+        },
+        assertion: {
+            type: 'baseline',
+            label: `${count} ${count === 1 ? 'difference' : 'differences'} from the baseline`,
+            outcome: 'failed',
+            message: lines.join('\n'),
+        },
+    };
+}