@jterrazz/test 16.1.1 → 18.0.0

package/dist/shared-index.stubs.d.ts

@@ -0,0 +1,287 @@
+//#region src/stubs/exchange.d.ts
+/** An observed outgoing request, reduced to what stub matchers inspect. */
+type MatchableRequest = {
+  /** Parsed JSON body when the payload is JSON, the raw text otherwise, or `null` when absent. */
+  body: unknown;
+  /** Request headers, keyed by lowercased header name. */
+  headers: Record<string, string>;
+  /** Uppercased HTTP method of the observed request. */
+  method: string;
+  /** The request URL: fully-qualified, or origin-relative for the stub backend. */
+  url: string;
+};
+/** The request half of a stub: an absolute URL, or a path form (`/articles/{{uuid}}`) matching any origin. */
+type StubRequest = {
+  /** Adapter name: `http` | `openai` | `anthropic`. */
+  adapter: string;
+  /** HTTP method to match. `*` matches any method. */
+  method: string;
+  /** Absolute URL (string | RegExp) or an any-origin path form (`/articles/{{uuid}}`). */
+  url: RegExp | string;
+  /** Optional request matcher; the stub only fires if this returns true. */
+  match?: ((request: MatchableRequest) => boolean) | undefined;
+  /** Header names, case-insensitive, whose presence keeps the stub from firing; `http.*` writes them from `without.headers`. */
+  absentHeaders?: readonly string[] | undefined;
+  /** Transform raw data into a provider-specific response envelope. */
+  wrap: (data: unknown) => StubResponse;
+};
+/** The response half of a stub. */
+type StubResponse = {
+  /** HTTP status code (default: 200). */
+  status?: number;
+  /** Response body: an object is JSON, a string text, `null` empty, a `StreamBody` arrives in pieces. */
+  body: unknown;
+  headers?: Record<string, string> | undefined;
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number | undefined;
+  /** A transport failure instead of a reply: `fetch` rejects, as no status code can express. */
+  transport?: 'network-error' | undefined;
+};
+/** Each adapter serialises an object as JSON, so a stream declared as a plain value would arrive as `{}`: the tag tells them apart. */
+declare const STREAM_BODY = "@jterrazz/test:stream";
+/** A body that arrives in pieces, as `http.stream()` and `http.sse()` build it. */
+type StreamBody = {
+  /** The pieces, written in order. */
+  chunks: readonly string[];
+  /** The `content-type` the stream is served under. */
+  contentType: string;
+  /** Milliseconds between two chunks. Default 0: everything at once. */
+  delayBetweenChunks: number;
+  kind: typeof STREAM_BODY;
+};
+/** A response computed from the observed request at serve time. */
+type StubResponder = (request: MatchableRequest) => StubResponse;
+/** A fixed `StubResponse`, or a `StubResponder` evaluated per served request. */
+type StubResponseValue = StubResponder | StubResponse;
+//#endregion
+//#region src/stubs/stub.d.ts
+/** A declared external interaction: what to match and what to reply. */
+type Stub = {
+  /** Which outgoing call this stub speaks for. */
+  request: StubRequest;
+  /** A fixed reply, or a function of the observed request. */
+  response: StubResponseValue;
+  /** How many times it may serve; omitted is unlimited. `0` with `required` is a never stub: docs/reference/stubs.md#never-a-call-that-must-not-happen. */
+  times?: number;
+  /** Fail the chain unless it was requested: exactly `times` times when set, so `times: 0` fails it once requested. */
+  required?: boolean;
+};
+/** A composite of stubs; `.with()` derives a variant without touching the original. */
+type Stubs = {
+  /** The flattened stubs, in selection order. */
+  readonly stubs: readonly Stub[];
+  /** Overrides replace base stubs of the same route and are prepended, so a more specific override wins first match. */
+  with: (...overrides: (Stub | Stub[] | Stubs)[]) => Stubs;
+};
+/** Any accepted stub input: one, a list, or a composite. */
+type StubInput = Stub | Stub[] | Stubs;
+declare function defineStub(stub: Stub): Stub;
+/** Compose stubs, lists and composites, order preserved; `.with()` derives a scenario. */
+declare function defineStubs(...items: StubInput[]): Stubs;
+//#endregion
+//#region lint/kit/project/tokens.d.ts
+declare const TOKEN_KINDS: readonly ["any", "base64", "date", "duration", "email", "float", "hex", "int", "ip", "iso8601", "number", "path", "port", "semver", "sha", "string", "time", "ulid", "url", "uuid", "workdir"];
+type TokenKind = (typeof TOKEN_KINDS)[number];
+//#endregion
+//#region src/expectations/tokens/match.d.ts
+/** The frozen token vocabulary (rule `no-unknown-token`) plus the code-only kinds. */
+type MatcherKind = 'any' | 'base64' | 'date' | 'duration' | 'email' | 'float' | 'hex' | 'includes' | 'int' | 'ip' | 'iso8601' | 'number' | 'path' | 'port' | 'ref' | 'regex' | 'semver' | 'sha' | 'string' | 'time' | 'ulid' | 'url' | 'uuid' | 'workdir';
+/** A dynamic-value matcher, created through the `match` factories. */
+declare class Matcher {
+  /** For kind 'includes': the substring the actual value must contain. */
+  readonly includes?: string | undefined;
+  readonly kind: MatcherKind;
+  /** For kind 'ref': the capture to assert inequality against. */
+  readonly notRef?: string | undefined;
+  /** For kind 'ref': the capture name. */
+  readonly refName?: string | undefined;
+  /** For kind 'regex': the pattern the actual value must match. */
+  readonly regex?: RegExp | undefined;
+  constructor(kind: MatcherKind, options?: {
+    includes?: string | undefined;
+    notRef?: string | undefined;
+    refName?: string | undefined;
+    regex?: RegExp | undefined;
+  });
+  /** Placeholder-style rendering used in failure diffs and serialization. */
+  toString(): string;
+  toJSON(): string;
+}
+type TypedMatcher = () => Matcher;
+/** Dynamic-value matchers, the code-side mirror of the `{{token}}` grammar (`no-unknown-token`). */
+type MatchFactories = Record<TokenKind, TypedMatcher> & {
+  includes: (substring: string) => Matcher;
+  ref: (name: string, options?: {
+    not?: string;
+  }) => Matcher;
+  regex: (regex: RegExp) => Matcher;
+};
+declare const match: MatchFactories;
+//#endregion
+//#region src/stubs/kinds/text-filter.d.ts
+/** A text filter on a provider request builder: a string is exact, a `RegExp` or `match.*` loosens it. */
+type TextFilter = Matcher | RegExp | string;
+//#endregion
+//#region src/stubs/kinds/anthropic.d.ts
+type AnthropicMessagesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+/** Init options for a streamed Anthropic reply. */
+type AnthropicStreamInit = {
+  /** Milliseconds between two events. Default 0: every event at once. */
+  delay?: number;
+};
+/** Anthropic API stub helpers. */
+declare const anthropic: {
+  /** Match Messages API calls, optionally through a gateway URL; a string filter is exact equality. */
+  messages(filter?: AnthropicMessagesFilter, url?: string): StubRequest;
+  /** A stub the chain fails on if the subject reaches this endpoint: `http.never()`. */
+  never(request: StubRequest): Stub;
+  /** Response: data wrapped in the Messages format. */
+  reply(data: unknown): StubResponse;
+  /** Response: the text streamed as server-sent events, one `text_delta` per piece. */
+  stream(pieces: readonly string[], init?: AnthropicStreamInit): StubResponse;
+  /** Response: return an Anthropic error. */
+  error(status: number, message?: string): StubResponse;
+  /** Response: simulate a timeout. */
+  timeout(): StubResponse;
+};
+//#endregion
+//#region src/stubs/kinds/http-filter.d.ts
+/** Request filters; a request matches when every provided field matches. */
+type HttpStubFilter = {
+  /** An object is a deep subset match (leaves may be `match.*`); a string is containment, a RegExp `test()`s the raw body. */
+  body?: object | RegExp | string;
+  /** Header subset. Names are case-insensitive; string = exact value, RegExp = `test()`. */
+  headers?: Record<string, RegExp | string>;
+  /** Query-param subset. string = exact value, RegExp = `test()`. */
+  query?: Record<string, RegExp | string>;
+  /** Headers the request must not carry; a name present with any value keeps the stub from firing. */
+  without?: {
+    headers?: readonly string[];
+  };
+};
+//#endregion
+//#region src/stubs/kinds/http.d.ts
+/** Init options for a streamed reply. */
+type HttpStreamInit = {
+  /** The `content-type` the stream is served under. Default `application/octet-stream`. */
+  contentType?: string;
+  /** Milliseconds between two chunks. Default 0: every chunk at once. */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. Default 200. */
+  status?: number;
+};
+/** One server-sent event, as `http.sse()` frames it. */
+type SseEvent = {
+  /** The `data:` payload. An object is serialised as JSON; a string is sent as-is. */
+  data: unknown;
+  /** The `event:` name. Omitted for an unnamed (default `message`) event. */
+  event?: string;
+  /** The `id:` the client echoes as `Last-Event-ID` when it reconnects. */
+  id?: string;
+  /** The `retry:` hint, in milliseconds. */
+  retry?: number;
+};
+/** Init options shared by the response builders. */
+type HttpResponseInit = {
+  /** Delay in ms before responding (for timeout testing). */
+  delay?: number;
+  /** Response headers, merged over the builder's own. */
+  headers?: Record<string, string>;
+  /** HTTP status code. */
+  status?: number;
+};
+/** Generic HTTP stub helpers: an absolute URL, or a path form (`/articles/{{uuid}}`) matching any origin. */
+declare const http: {
+  any(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  delete(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  get(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  patch(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  post(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  put(url: RegExp | string, filter?: HttpStubFilter): StubRequest;
+  /** A stub the chain fails on if the subject reaches its route: `required` with `times: 0`. */
+  never(request: StubRequest): Stub;
+  /** Response: a body-less reply (204 by default). */
+  empty(status?: number): StubResponse;
+  /** Response: an error status. Without a body, `{ error: 'HTTP <status>' }`. */
+  error(status: number, body?: unknown): StubResponse;
+  /** Response: a JSON body (200 by default). */
+  json(body: unknown, init?: HttpResponseInit): StubResponse;
+  /** Response: no response at all; `fetch` rejects, as when no server is running. */
+  unreachable(): StubResponse;
+  /** Response: a body that arrives in pieces, written in order. */
+  stream(chunks: readonly string[], init?: HttpStreamInit): StubResponse;
+  /** Response: a server-sent event stream, served as `text/event-stream`. */
+  sse(events: readonly SseEvent[], init?: Omit<HttpStreamInit, "contentType">): StubResponse;
+  /** Response: a text body, served as `text/plain` (200 by default). */
+  text(body: string, init?: HttpResponseInit): StubResponse;
+};
+//#endregion
+//#region src/stubs/kinds/openai.d.ts
+type OpenAIChatFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+  temperature?: number;
+};
+type OpenAIResponsesFilter = {
+  model?: TextFilter;
+  system?: TextFilter;
+  user?: TextFilter;
+  tools?: string[];
+};
+type OpenAIStreamInit = {
+  /** The API whose stream is served: Chat Completions (default) or Responses. */
+  api?: 'chat' | 'responses';
+  /** Milliseconds between two events. Default 0: every event at once. */
+  delay?: number;
+  /** The tokens the stream reports it spent: a Chat Completions stream ends on a usage chunk, as `stream_options.include_usage` asks, and a Responses stream carries them in its completed response. Default 10 and 10. */
+  usage?: {
+    completionTokens: number;
+    promptTokens: number;
+  };
+};
+/** OpenAI API stub helpers. */
+declare const openai: {
+  /** Match Chat Completions calls, at `url` where the client reaches another host; a string filter is exact equality, a RegExp or `match.includes` loosens it. */
+  chat(filter?: OpenAIChatFilter, url?: string): StubRequest;
+  /** Match Responses API calls; a JSON file is wrapped in the Responses envelope. */
+  responses(filter?: OpenAIResponsesFilter, url?: string): StubRequest;
+  /** A stub the chain fails on if the subject reaches this endpoint: `http.never()`. */
+  never(request: StubRequest): Stub;
+  /** Response: data wrapped in the Chat Completions format. */
+  reply(data: unknown): StubResponse;
+  /** Response: the text streamed as server-sent events; `api` picks Chat Completions (default) or Responses. */
+  stream(pieces: readonly string[], init?: OpenAIStreamInit): StubResponse;
+  /** Response: return an OpenAI error. */
+  error(status: number, message?: string): StubResponse;
+  /** Response: return malformed content. */
+  malformed(content: string): StubResponse;
+  /** Response: simulate a timeout. */
+  timeout(): StubResponse;
+};
+//#endregion
+//#region src/stubs/intercept/intercept.d.ts
+/** Disposed at the end of the declaring scope: handlers dropped, an unmatched request thrown. */
+type InterceptScope = AsyncDisposable;
+/** What a scope may state about the network it declares. */
+type InterceptOptions = {
+  /** The base a relative request resolves against for the life of the scope; under node `fetch('/api/posts')` cannot parse. */
+  origin?: string;
+};
+/** The module-scope network double; awaited, so the network double listens before the subject runs. */
+type Intercept = ((stubs: StubInput, options?: InterceptOptions) => Promise<InterceptScope>) & ((request: StubRequest, response: StubResponder | StubResponse, options?: InterceptOptions) => Promise<InterceptScope>);
+//#endregion
+//#region src/stubs/delivery/same-process/intercept.d.ts
+/** The module-scope network double, on msw's node server. */
+declare const intercept: Intercept;
+//#endregion
+export { StubRequest as C, StubResponseValue as E, StreamBody as S, StubResponse as T, StubInput as _, openai as a, defineStubs as b, SseEvent as c, anthropic as d, TextFilter as f, Stub as g, match as h, InterceptScope as i, http as l, MatcherKind as m, Intercept as n, HttpResponseInit as o, Matcher as p, InterceptOptions as r, HttpStreamInit as s, intercept as t, HttpStubFilter as u, Stubs as v, StubResponder as w, MatchableRequest as x, defineStub as y };
+//# sourceMappingURL=shared-index.stubs.d.ts.map

package/dist/shared-json-shape.js

@@ -0,0 +1,17 @@
+//#region lint/kit/project/json-shape.ts
+/** `JSON.parse` answers `any`: these read a parsed value field by field, and a field of another shape reads as absent. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** What a text that is no JSON stands for is the caller's to say. */
+function parsedJson(text, otherwise) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return otherwise;
+	}
+}
+//#endregion
+export { parsedJson as n, isRecord as t };
+
+//# sourceMappingURL=shared-json-shape.js.map

package/dist/shared-landmarks.js

@@ -0,0 +1,71 @@
+//#region src/visitor/targets/roles.ts
+const stated = (options) => options?.exact === void 0 ? {} : { exact: options.exact };
+const named = (kind) => (name, options) => ({
+	kind,
+	name,
+	...stated(options)
+});
+const optionallyNamed = (kind) => (name, options) => ({
+	kind,
+	...name === void 0 ? {} : { name },
+	...stated(options)
+});
+/** A button (or element with the button role), by accessible name. */
+const button = named("button");
+/** A form field, by label. */
+const field = named("field");
+/** A heading, by accessible name. */
+const heading = named("heading");
+/** A link, by accessible name. */
+const link = named("link");
+/** An element containing the given text. */
+const content = named("text");
+/** An option of a select or listbox, by label; asserted by presence, since a collapsed select's options have no box. */
+const option = named("option");
+/** A modal or non-modal `<dialog>`, by accessible name. A closed one is absent. */
+const dialog = optionallyNamed("dialog");
+/** A live region announcing a result: `role="status"`, an `<output>`. */
+const status = optionallyNamed("status");
+/** A table, by its caption or accessible name. */
+const table = optionallyNamed("table");
+/** A row of a table or grid, by the text of its cells. */
+const row = optionallyNamed("row");
+/** An item of a list, by its text. */
+const listitem = optionallyNamed("listitem");
+/** The escape hatch: an element by `data-testid`. Prefer user-facing targets. */
+const testId = (id) => ({
+	kind: "testId",
+	name: id
+});
+//#endregion
+//#region src/visitor/targets/landmarks.ts
+/** The `banner` landmark: the page header. */
+const banner = optionallyNamed("banner");
+/** The `complementary` landmark: an `<aside>`, a sidebar. */
+const complementary = optionallyNamed("complementary");
+/** The `contentinfo` landmark: the page footer. */
+const contentinfo = optionallyNamed("contentinfo");
+/** The `form` landmark: a form carrying an accessible name. */
+const form = optionallyNamed("form");
+/** The `main` landmark: the primary content of the document. */
+const main = optionallyNamed("main");
+/** The `navigation` landmark: a `<nav>`. Name it when a page has several. */
+const navigation = optionallyNamed("navigation");
+/** The `region` landmark: a `<section>` carrying an accessible name. */
+const region = optionallyNamed("region");
+/** The `search` landmark. */
+const search = optionallyNamed("search");
+/** Restrict a target to the inside of another: `click(within(navigation(), link('Articles')))`. */
+const within = (scope, target) => ({
+	...target,
+	scope: target.scope ? within(scope, target.scope) : scope
+});
+function scopeChain(target) {
+	const chain = [];
+	for (let current = target; current; current = current.scope) chain.unshift(current);
+	return chain;
+}
+//#endregion
+export { testId as S, listitem as _, main as a, status as b, scopeChain as c, button as d, content as f, link as g, heading as h, form as i, search as l, field as m, complementary as n, navigation as o, dialog as p, contentinfo as r, region as s, banner as t, within as u, option as v, table as x, row as y };
+
+//# sourceMappingURL=shared-landmarks.js.map

package/dist/shared-ledger.js

@@ -0,0 +1,68 @@
+import { t as isRecord } from "./shared-json-shape.js";
+import { u as VITEST_ARTIFACTS_DIR } from "./shared-artifacts.js";
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/expectations/in-place/update.ts
+/** `TEST_UPDATE=1` or vitest's `-u` / `--update`. */
+function shouldUpdateSnapshots() {
+	if (process.env.TEST_UPDATE === "1") return true;
+	return process.argv.includes("-u") || process.argv.includes("--update");
+}
+const UPDATE_HINT = "Run with TEST_UPDATE=1 (or vitest -u) to create it.";
+const FROZEN_HINT = "This golden is `{ frozen }`: update mode never writes it. Write the file by hand, or drop `{ frozen }` for one TEST_UPDATE=1 run and put it back.";
+function missingHint(frozen) {
+	return frozen ? FROZEN_HINT : UPDATE_HINT;
+}
+//#endregion
+//#region src/specifications/api/routes/ledger.ts
+const isLedger = (value) => isRecord(value) && Array.isArray(value.reached) && (value.declared === void 0 || Array.isArray(value.declared));
+function entriesOf(directory) {
+	try {
+		return readdirSync(directory, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+const ROUTES_DIR = `${VITEST_ARTIFACTS_DIR}/routes`;
+function shardLedgersDir(shard) {
+	return `${ROUTES_DIR}/shard-${shard.index}-${shard.count}`;
+}
+function clearLedgers(directory) {
+	rmSync(directory, {
+		force: true,
+		recursive: true
+	});
+}
+function writeLedger(directory, ledger) {
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(join(directory, `${randomUUID()}.json`), `${JSON.stringify(ledger)}\n`);
+}
+const parsed = (path) => JSON.parse(readFileSync(path, "utf8"));
+function readLedgers(directory) {
+	return entriesOf(directory).filter((entry) => entry.name.endsWith(".json")).map((entry) => parsed(join(directory, entry.name))).filter((ledger) => isLedger(ledger));
+}
+const PARTIAL_MARK = "partial";
+function markPartial(directory) {
+	mkdirSync(directory, { recursive: true });
+	writeFileSync(join(directory, PARTIAL_MARK), "");
+}
+function measure(ledgers) {
+	const tables = ledgers.map((ledger) => ledger.declared);
+	return {
+		declared: tables.every((table) => table !== void 0) ? tables.flat() : void 0,
+		reached: ledgers.flatMap((ledger) => ledger.reached)
+	};
+}
+async function routesLedger() {
+	try {
+		const { inject } = await import("vitest");
+		return inject("routesLedger");
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { readLedgers as a, writeLedger as c, measure as i, missingHint as l, clearLedgers as n, routesLedger as o, markPartial as r, shardLedgersDir as s, ROUTES_DIR as t, shouldUpdateSnapshots as u };
+
+//# sourceMappingURL=shared-ledger.js.map

package/dist/shared-listened-port.js

@@ -0,0 +1,19 @@
+import { t as invariant } from "./shared-refusal.js";
+//#region src/chain/listened-port.ts
+/** Listens, on `host` when one is named, and answers the port it got; a port another server holds rejects with its error. */
+async function listenedPort(server, { host, port = 0 } = {}) {
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, host, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw invariant("a server listening on a TCP port answered no port");
+	return address.port;
+}
+//#endregion
+export { listenedPort as t };
+
+//# sourceMappingURL=shared-listened-port.js.map

package/dist/shared-literate-plugin.js

@@ -0,0 +1,184 @@
+import { n as refusal } from "./shared-refusal.js";
+import { c as isRelativePath, s as SpecSyntaxError } from "./shared-spec-grammar.js";
+import { i as readSpecFile, o as dedent } from "./shared-spec-document.js";
+import { readFileSync } from "node:fs";
+import { basename, isAbsolute, resolve } from "node:path";
+//#region src/disk/spec-path.ts
+const DISK_KEY = "@jterrazz/test:disk";
+const DISK = Symbol.for(DISK_KEY);
+/** Name one file, by its path from the spec file. */
+function file(path) {
+	requireRelativePath("file", path);
+	if (path.endsWith("/")) {
+		const bare = path.replace(/\/+$/u, "");
+		throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+			fix: `name the directory with directory(${JSON.stringify(path)}), or the file without its /: file(${JSON.stringify(bare)})`,
+			found: `file(${JSON.stringify(path)}), a path ending in /, which is a directory's`
+		}));
+	}
+	return diskValue("file", path);
+}
+function diskValue(brand, path) {
+	const value = {
+		[DISK]: brand,
+		path
+	};
+	Object.defineProperty(value, Symbol.match, { value: () => {
+		throw new TypeError(refusal("one-verb-per-meaning", {
+			fix: `wrap the string to golden it, \`expect(text(value)).toMatch(${brand}(...))\`, or compare it to a value, \`toMatch('...')\``,
+			found: `toMatch(${brand}(${JSON.stringify(path)})) on a string, a value with no golden`
+		}));
+	} });
+	return Object.freeze(value);
+}
+/** Name one directory, by its path from the spec file, ending in `/`. */
+function directory(path) {
+	requireRelativePath("directory", path);
+	if (!path.endsWith("/")) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `end it in /: directory(${JSON.stringify(`${path}/`)}), or name a file with file(${JSON.stringify(path)})`,
+		found: `directory(${JSON.stringify(path)}), a path that does not end in /`
+	}));
+	return diskValue("directory", path);
+}
+function isDiskFile(value) {
+	return brandOf(value) === "file";
+}
+function isDiskDirectory(value) {
+	return brandOf(value) === "directory";
+}
+function isDiskTarget(value) {
+	return brandOf(value) !== void 0;
+}
+function brandOf(value) {
+	if (value === null || typeof value !== "object") return;
+	const brand = Reflect.get(value, DISK);
+	return brand === "file" || brand === "directory" ? brand : void 0;
+}
+function spelled(value) {
+	if (isDiskTarget(value)) return `${brandOf(value)}(${JSON.stringify(value.path)})`;
+	return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+function requireDiskFile(verb, value, extension = "") {
+	if (!isDiskFile(value)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name one file: ${verb}(file('./${exampleOf(verb, extension)}'))`,
+		found: isDiskDirectory(value) ? `${verb}(${spelled(value)}), a directory where one file is read` : `${verb}(${spelled(value)}), a value where a file is read`
+	}));
+	if (!value.path.endsWith(extension)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name the ${extension} file ${verb}() reads: ${verb}(file('./${exampleOf(verb, extension)}'))`,
+		found: `${verb}(${spelled(value)}), a file not ending in ${extension}`
+	}));
+	return value;
+}
+function requireDiskTarget(verb, value) {
+	if (!isDiskTarget(value)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `name the disk: ${verb}(file('./<path>')) for a file, ${verb}(directory('./<path>/')) for a directory`,
+		found: `${verb}(${spelled(value)}), a value where the disk is read`
+	}));
+	return value;
+}
+function exampleOf(verb, extension) {
+	return {
+		fixture: "__fixtures__/config.json",
+		request: "__requests__/create.http",
+		run: "case.spec.yaml",
+		seed: "__seeds__/rows.sql"
+	}[verb] ?? `__expected__/output${extension || ".txt"}`;
+}
+function asRelative(path) {
+	const bare = typeof path === "string" ? path.replace(/^\/+/u, "") : "";
+	return `./${bare === "" ? "__expected__/output.txt" : bare}`;
+}
+function requireRelativePath(call, path) {
+	if (typeof path !== "string" || !isRelativePath(path)) throw new TypeError(refusal("disk-named-by-relative-path-at-runtime", {
+		fix: `start it with ./ or ../, from the spec file: ${call}('${asRelative(path)}')`,
+		found: `${call}(${JSON.stringify(path)}), a path that is not relative to the spec file`
+	}));
+}
+//#endregion
+//#region src/disk/resolved-spec-path.ts
+function resolveSpecPath(verb, path, specDir) {
+	requireRelativePath(verb, path);
+	return resolve(specDir, path);
+}
+//#endregion
+//#region src/expectations/in-place/render.ts
+function escapeTemplate(text) {
+	return text.replaceAll("\\", String.raw`\\`).replaceAll("`", "\\`").replaceAll("${", "\\${");
+}
+function renderText(text, indent) {
+	if (!text.includes("\n")) return `\`${escapeTemplate(text)}\``;
+	const inner = `${indent}    `;
+	const lines = text.split("\n");
+	const last = String(lines.pop());
+	const block = `\n${lines.map((line) => line === "" ? "" : `${inner}${line}`).join("\n")}\n${last === "" ? indent : `${inner}${last}`}`;
+	return dedent(block) === text ? `\`${escapeTemplate(block)}\`` : JSON.stringify(text);
+}
+const NUMBER_MARK = "@@in-place-number:";
+const GROUPED_FROM = 1e4;
+function grouped(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && Math.abs(value) >= GROUPED_FROM ? `${NUMBER_MARK}${String(value).replaceAll(/\B(?=(?:\d{3})+$)/gu, "_")}` : value;
+}
+const MARKED = new RegExp(`"${NUMBER_MARK}(?<digits>-?[\\d_]+)"`, "gu");
+const literal = (value, space) => JSON.stringify(value, (_key, item) => grouped(item), space)?.replaceAll(MARKED, "$<digits>");
+function renderValue(value, indent) {
+	return (literal(value, 4) ?? "undefined").split("\n").join(`\n${indent}`);
+}
+function renderRows(rows, indent) {
+	if (rows.length === 0) return "[]";
+	return `[\n${rows.map((row) => `${indent}    [${row.map((cell) => literal(cell) ?? "null").join(", ")}],`).join("\n")}\n${indent}]`;
+}
+//#endregion
+//#region src/specifications/cli/documents/literate-plugin.ts
+const SPEC_FILE = /\.spec\.yaml(?:\?.*)?$/u;
+function grammarRefusal(error, displayPath) {
+	return new Error(refusal({
+		fix: "write the key the grammar names; the reason prints the accepted set",
+		found: `${displayPath}:${error.line}: ${error.reason}`,
+		read: "docs/reference/linting.md#document-follows-its-grammar",
+		why: "A spec document follows one grammar, read by the parser the runner and the linter share: closed keys, `description:` and `runs:` required, `command:` and `exit:` in every run."
+	}), { cause: error });
+}
+function readDocument(content, displayPath) {
+	try {
+		return readSpecFile(content, displayPath);
+	} catch (error) {
+		throw error instanceof SpecSyntaxError ? grammarRefusal(error, displayPath) : error;
+	}
+}
+function literateModule(content, filePath, runnerPath) {
+	const { description } = readDocument(content, filePath).document;
+	return [
+		"import { test } from 'vitest';",
+		`import { cli } from ${JSON.stringify(runnerPath)};`,
+		"",
+		`test(${JSON.stringify(description)}, async () => {`,
+		`    await cli.run({ [Symbol.for(${JSON.stringify(DISK_KEY)})]: 'file', path: ${JSON.stringify(`./${basename(filePath)}`)} });`,
+		"});",
+		""
+	].join("\n");
+}
+function cleanId(id) {
+	return id.split("?")[0] ?? id;
+}
+function literate(options) {
+	const include = options.include ?? ["**/*.spec.yaml"];
+	let root = process.cwd();
+	return {
+		config: () => ({ test: { include } }),
+		configResolved: (resolved) => {
+			({root} = resolved);
+		},
+		enforce: "pre",
+		load: (id) => {
+			if (!SPEC_FILE.test(id)) return null;
+			const filePath = cleanId(id);
+			const runnerPath = isAbsolute(options.runner) ? options.runner : resolve(root, options.runner);
+			return literateModule(readFileSync(filePath, "utf8"), filePath, runnerPath);
+		},
+		name: "jterrazz-test:literate"
+	};
+}
+//#endregion
+export { renderValue as a, file as c, isDiskTarget as d, requireDiskFile as f, renderText as i, isDiskDirectory as l, literate as n, resolveSpecPath as o, requireDiskTarget as p, renderRows as r, directory as s, grammarRefusal as t, isDiskFile as u };
+
+//# sourceMappingURL=shared-literate-plugin.js.map