@junoflow/testkit 0.3.0 → 0.9.0

package/src/index.d.ts

@@ -94,6 +94,7 @@ export interface WebhookRequestInit {
   /** A string is sent as-is; anything else is JSON.stringify'd. */
   body?: unknown;
   url?: string;
+  subpath?: string;
 }
 
 export interface WebhookResult {
@@ -219,3 +220,401 @@ export function conformance(
 ): string[];
 
 export { AssertionError } from 'node:assert';
+
+// ─── flowHarness ─────────────────────────────────────────────────────────────
+
+/**
+ * The parsed contents of a flow's manifest.json, as loosely as `Manifest` and
+ * for the same reason: a JSON import widens every literal, and the server is
+ * where the vocabulary is enforced.
+ */
+export interface FlowManifest {
+  id?: string;
+  name?: string;
+  /** Keyed by the trigger's name, which is also its handler's key. */
+  triggers?: Record<string, { type: string; [k: string]: unknown }>;
+  /**
+   * Keyed by binding name. Exactly one of access, slot and signal grants the
+   * verbs: get (read), get/set (read_write), claim/release, signal/retract.
+   */
+  states?: Record<
+    string,
+    {
+      state?: string;
+      control?: string;
+      access?: string;
+      slot?: string;
+      signal?: string;
+    }
+  >;
+  /** Keyed by binding name; `integration` and `flow` decide the methods. */
+  targets?: Record<
+    string,
+    {
+      integration: string;
+      flow?: { flow_id?: string; label?: string };
+      actions?: string[];
+      [k: string]: unknown;
+    }
+  >;
+  controls?: Record<string, { id: string }>;
+  findings?: Array<{
+    slug: string;
+    title?: string;
+    severity?: string;
+    [k: string]: unknown;
+  }>;
+  credentials?: string[];
+  [k: string]: unknown;
+}
+
+/**
+ * The flow's default export, as the shim loads it. Generic so a module typed
+ * `Flow` fits: its triggers are the generated FlowHandlers interface, and an
+ * interface is not assignable to an index signature.
+ */
+export interface FlowModule<
+  Handlers extends Record<keyof Handlers, (ctx: never) => unknown> = Record<
+    string,
+    (ctx: never) => unknown
+  >,
+> {
+  triggers: Handlers;
+}
+
+/** What ctx.solar() answers; see SolarResult in the flow's types. */
+export interface SolarAnswer {
+  above_horizon?: boolean;
+  elevation?: number;
+  azimuth?: number;
+  rising?: boolean;
+  next_rising?: string | null;
+  next_setting?: string | null;
+}
+
+export interface FlowHarnessOptions<
+  Handlers extends Record<keyof Handlers, (ctx: never) => unknown> = Record<
+    string,
+    (ctx: never) => unknown
+  >,
+> {
+  manifest: FlowManifest;
+  flow: FlowModule<Handlers>;
+  /** As h.now(). */
+  now?: string;
+  /** As h.timezone(); UTC when omitted. */
+  timezone?: string;
+  /** As h.solar(). */
+  solar?: SolarAnswer;
+}
+
+export interface TriggerOptions {
+  /**
+   * The trigger's payload. An object is spread onto ctx.event beside
+   * `trigger`; an array (a batch) stays under `event.payload`; null (a timer
+   * edge) adds nothing. Omitted, the scenario's `event` is used, and with no
+   * scenario event nothing is added. Fields not given are not invented.
+   */
+  event?: unknown;
+}
+
+/** One journaled step, as step.run or step.llm recorded it. */
+export interface RecordedStep {
+  /** The journal id: the id the source says, then `id#1`, `id#2` on repeats. */
+  id: string;
+  /** What the journal holds: the JSON of the return value, null for void. */
+  output: unknown;
+}
+
+export interface FlowLogEntry {
+  level: 'debug' | 'warn' | 'error';
+  message: string;
+  data?: unknown;
+}
+
+/** One ctx.state write, claim or signal, in the order the handler made it. */
+export interface RecordedStateCall {
+  binding: string;
+  verb: 'set' | 'claim' | 'release' | 'signal' | 'retract';
+  /** set and claim. */
+  value?: unknown;
+  /** claim and signal: `{ ttl }`. */
+  opts?: { ttl: string };
+}
+
+/** One target call. `action` is the method the source called. */
+export interface RecordedTargetCall {
+  target: string;
+  action: string;
+  /** What the SDK sends: `{}` when an action is called bare, `null` for an invoke without input. */
+  params: unknown;
+  /** invoke/invokeAll only, when given. */
+  opts?: { timeout?: string };
+}
+
+export interface RecordedControlCall {
+  binding: string;
+  verb: 'press' | 'activate' | 'extend' | 'release';
+  value?: string;
+  for?: string;
+  until?: string;
+}
+
+/** What a control command answers. Fields left out take the SDK's defaults. */
+export interface ControlAnswer {
+  outcome?: string;
+  active?: boolean;
+  value?: unknown;
+  expires_at?: string | null;
+}
+
+export interface FlowTargets {
+  /**
+   * Answers `binding.method` (`kitchenSpeaker.ttsCloudSay`, `child.invoke`):
+   * a value, or a function of the params (an invoke's input) returning one.
+   * An action with no result is answered with `undefined`, explicitly.
+   */
+  answer(
+    key: string,
+    answer: (params: any) => unknown | Promise<unknown>
+  ): FlowTargets;
+  answer(key: string, answer: unknown): FlowTargets;
+  calls(): RecordedTargetCall[];
+}
+
+export interface FlowControls {
+  /** Answers `binding.verb` (`doorbell.press`). */
+  answer(
+    key: string,
+    answer:
+      | ControlAnswer
+      | ((args: {
+          value?: string;
+          for?: string;
+          until?: string;
+        }) => ControlAnswer | Promise<ControlAnswer>)
+  ): FlowControls;
+  calls(): RecordedControlCall[];
+}
+
+/**
+ * A scenario's reserved answer forms. `{ $replay: [a, b, …] }` answers calls
+ * in order and fails on one past the end; `{ $error: message }` makes the call
+ * throw `new Error(message)`, as a failed capability call does. A $replay item
+ * may be an $error. Only an object whose sole key is one of these is one.
+ */
+export type ReplayAnswer<T> = { $replay: Array<T | ErrorAnswer> };
+export type ErrorAnswer = { $error: string };
+export type ScenarioAnswer<T> = T | ReplayAnswer<T> | ErrorAnswer;
+
+/**
+ * The world a handler runs in, as JSON: what `h.scenario(s)` applies through
+ * the individual setters. Keys are what the source says — binding names, and
+ * `binding.method` / `binding.verb` / a step id for answers. A key left out
+ * sets nothing; an unknown key fails.
+ */
+export interface Scenario {
+  /** The trigger the test runs. Not applied: pass it to h.trigger. */
+  trigger?: string;
+  /** As h.now(). */
+  now?: string;
+  /** As h.timezone(). */
+  timezone?: string;
+  /** As h.solar(). */
+  solar?: SolarAnswer;
+  /** As h.states(). */
+  states?: Record<string, unknown>;
+  /** As h.controls.answer, keyed `binding.verb`. */
+  controls?: Record<string, ScenarioAnswer<ControlAnswer>>;
+  /** As h.targets.answer, keyed `binding.method`. */
+  targets?: Record<string, ScenarioAnswer<unknown>>;
+  /** As h.credentials(). */
+  credentials?: Record<string, string>;
+  /** Flows: the payload an h.trigger(name) without one runs with. */
+  event?: unknown;
+  /** Flows only: as h.llm, keyed by step id. */
+  llm?: Record<string, ScenarioAnswer<string>>;
+  /** What the test asserts. Not applied. */
+  expect?: unknown;
+  /** Flows: the version a recorded run ran. Not applied. */
+  flow_version?: number;
+}
+
+export interface FlowHarness {
+  /**
+   * Runs the declared trigger's handler and resolves to what it returned — a
+   * Status for most triggers, any value for a `call` trigger. A refusal the
+   * handler caught still fails here.
+   */
+  trigger(name: string, options?: TriggerOptions): Promise<unknown>;
+  /**
+   * Applies a scenario through the setters below, and keeps its `event` for
+   * an h.trigger(name) that passes none. Ignores `trigger`, `expect` and
+   * `flow_version`.
+   */
+  scenario(s: Scenario): FlowHarness;
+  /**
+   * Freezes ctx.now(). An offset (`Z`, `+02:00`) makes it an instant; without
+   * one it is wall time in h.timezone(), read when the handler asks.
+   */
+  now(iso: string): FlowHarness;
+  /** The site timezone, an IANA name. UTC unless set. */
+  timezone(tz: string): FlowHarness;
+  /** What ctx.solar() answers. Fields left out take the SDK's defaults. */
+  solar(values: SolarAnswer): FlowHarness;
+  /**
+   * Answers step.llm(id, …): text, or a function of the options returning it.
+   * The bare id answers every occurrence; `id#N` only that one, and wins.
+   */
+  llm(
+    id: string,
+    answer: string | ((options: unknown) => string | Promise<string>)
+  ): FlowHarness;
+  /** Every step.run and step.llm, in order. */
+  steps(): RecordedStep[];
+  logs(): FlowLogEntry[];
+  /** Triggers declared vs implemented, both ways; empty when they agree. */
+  conformance(): string[];
+  /** Seeds read and read_write bindings by name. */
+  states(values: Record<string, unknown>): FlowHarness;
+  /** A value binding's current value: its seed, or what set() last wrote. */
+  state(name: string): unknown;
+  stateCalls(): RecordedStateCall[];
+  readonly targets: FlowTargets;
+  readonly controls: FlowControls;
+  /** Findings by (slug, key), as the host collapses them. */
+  findings(): RecordedFinding[];
+  /** Sets ctx.credentials by declared id. Kept across reset(). */
+  credentials(values: Record<string, string>): FlowHarness;
+  /**
+   * Clears recordings, answers, seeded states, the scenario's event and
+   * scoped memory; keeps the clock, timezone, solar and credentials.
+   */
+  reset(): FlowHarness;
+}
+
+export function flowHarness<
+  Handlers extends Record<keyof Handlers, (ctx: never) => unknown>,
+>(options: FlowHarnessOptions<Handlers>): FlowHarness;
+
+// ─── appHarness ──────────────────────────────────────────────────────────────
+
+/**
+ * The parsed contents of an app's manifest.json, as loosely as FlowManifest.
+ * A handler's entry is policy only: its input and output are its TypeScript.
+ */
+export interface AppManifest {
+  id?: string;
+  name?: string;
+  /** Keyed by the handler's name, which is also its key in `handlers`. */
+  handlers?: Record<
+    string,
+    { description?: string; read_only?: boolean; timeout?: string }
+  >;
+  /** Keyed by binding name: `access: "read"` (get) or a `slot` (claim/release). */
+  states?: FlowManifest['states'];
+  targets?: FlowManifest['targets'];
+  controls?: FlowManifest['controls'];
+  credentials?: string[];
+  /** Keyed by event name; `payload` is the JSON Schema an emit is held to. */
+  events?: Record<string, { payload?: object; [k: string]: unknown }>;
+  [k: string]: unknown;
+}
+
+/**
+ * The app's default export, as the shim loads it. Generic so a module typed
+ * `App` fits: its handlers are the generated interface, and an interface is
+ * not assignable to an index signature.
+ */
+export interface AppModule<
+  Handlers extends Record<
+    keyof Handlers,
+    (ctx: never, input: never) => unknown
+  > = Record<string, (ctx: never, input: never) => unknown>,
+> {
+  handlers: Handlers;
+}
+
+export interface AppHarnessOptions<
+  Handlers extends Record<
+    keyof Handlers,
+    (ctx: never, input: never) => unknown
+  > = Record<string, (ctx: never, input: never) => unknown>,
+> {
+  manifest: AppManifest;
+  app: AppModule<Handlers>;
+  /** As h.now(). */
+  now?: string;
+  /** As h.timezone(); UTC when omitted. */
+  timezone?: string;
+  /** As h.solar(). */
+  solar?: SolarAnswer;
+}
+
+/** One ctx.events.<event>.emit that passed the host's checks. */
+export interface RecordedEvent {
+  event: string;
+  /** What the bus carries: the payload after a JSON round trip; null when omitted. */
+  payload: unknown;
+}
+
+/** One ctx.states claim or release, in the order the handler made it. */
+export interface RecordedAppStateCall {
+  binding: string;
+  verb: 'claim' | 'release';
+  /** claim. */
+  value?: unknown;
+  /** claim: `{ ttl }`. */
+  opts?: { ttl: string };
+}
+
+export interface AppHarness {
+  /**
+   * Calls a declared handler as juno.handlers.<name>(input) does, and
+   * resolves to what the page receives: the result after a JSON round trip
+   * (a Date becomes its ISO string, an undefined field disappears, undefined
+   * becomes null). An omitted input arrives as `{}`. A refusal the handler
+   * caught still fails here; in a `read_only` handler, claim, release, a
+   * control command, an emit and a call on a homeassistant or mqtt target
+   * fail with the host's message.
+   */
+  call(name: string, input?: unknown): Promise<unknown>;
+  /** Every emit that passed, in order. */
+  events(): RecordedEvent[];
+  logs(): FlowLogEntry[];
+  /** Handlers declared vs implemented, both ways; empty when they agree. */
+  conformance(): string[];
+  /**
+   * Applies a scenario through the setters below. Ignores `trigger`, `event`
+   * and `expect`; `llm` and `flow_version` are flow keys and fail here.
+   */
+  scenario(s: Omit<Scenario, 'llm' | 'flow_version'>): AppHarness;
+  /**
+   * Freezes ctx.now(). An offset (`Z`, `+02:00`) makes it an instant; without
+   * one it is wall time in h.timezone(), read when the handler asks.
+   */
+  now(iso: string): AppHarness;
+  /** The site timezone, an IANA name. UTC unless set. */
+  timezone(tz: string): AppHarness;
+  /** What ctx.solar() answers. Fields left out take the SDK's defaults. */
+  solar(values: SolarAnswer): AppHarness;
+  /** Seeds read bindings by name. */
+  states(values: Record<string, unknown>): AppHarness;
+  stateCalls(): RecordedAppStateCall[];
+  readonly targets: FlowTargets;
+  readonly controls: FlowControls;
+  /** Sets ctx.credentials by declared id. Kept across reset(). */
+  credentials(values: Record<string, string>): AppHarness;
+  /**
+   * Clears recordings, answers and seeded states; keeps the clock, timezone,
+   * solar and credentials.
+   */
+  reset(): AppHarness;
+}
+
+export function appHarness<
+  Handlers extends Record<
+    keyof Handlers,
+    (ctx: never, input: never) => unknown
+  >,
+>(options: AppHarnessOptions<Handlers>): AppHarness;

package/src/index.js

@@ -1,4 +1,6 @@
 import { fail } from './assert.js';
+import { setFinding } from './findings.js';
+import { names } from './names.js';
 import { conformance } from './conformance.js';
 import { createHttpMock, withFetch } from './http.js';
 import { assertValid } from './schema.js';
@@ -121,7 +123,7 @@ export function harness({ manifest, integration } = {}) {
       );
       if (result !== undefined && result !== null) {
         fail(
-          `schedule "${name}" returned a value; a schedule reports through ctx.emit and returns nothing`
+          `schedule "${name}" returned a value; a schedule reports through ctx.events and returns nothing`
         );
       }
     },
@@ -306,53 +308,6 @@ function buildContext(manifest, state) {
   };
 }
 
-/**
- * The one call behind open/clear/set, mirroring the SDK and the host: the verbs
- * differ only in whether the boolean is already decided, and the answer is the
- * transition this call made. Both false means it refreshed an instance that was
- * already standing, or retracted one that was already absent.
- *
- * The name is checked against the manifest for the same reason emit's is: Juno
- * rejects an undeclared finding at runtime, and finding that out from an
- * installer is not a test.
- */
-function setFinding(manifest, state, slug, standing, opts) {
-  const declared = manifest.findings?.[slug];
-  if (!declared) {
-    fail(
-      `ctx.findings — "${slug}" is not declared in manifest.json (have: ${names(manifest.findings)}). ` +
-        'Juno rejects an undeclared finding at runtime.'
-    );
-  }
-  const key = opts.key ?? '';
-  const existing = state.findings.find((f) => f.slug === slug && f.key === key);
-
-  if (!standing) {
-    // A retraction says nothing about severity or text, and clearing what was
-    // never open is a no-op here exactly as it is in the store.
-    if (!existing || !existing.standing)
-      return { opened: false, cleared: false };
-    existing.standing = false;
-    return { opened: false, cleared: true };
-  }
-
-  const severity = opts.severity ?? declared.severity ?? 'error';
-  if (!['info', 'warn', 'error'].includes(severity)) {
-    fail(
-      `ctx.findings severity must be "info", "warn" or "error", got ${JSON.stringify(severity)}`
-    );
-  }
-  const text = opts.text ?? '';
-  if (existing) {
-    // Refresh in place — never a second instance for the same (slug, key).
-    const opened = !existing.standing;
-    Object.assign(existing, { severity, text, standing: true });
-    return { opened, cleared: false };
-  }
-  state.findings.push({ slug, key, severity, text, standing: true });
-  return { opened: true, cleared: false };
-}
-
 /**
  * The one call behind ctx.states.publish. Every name is checked against the
  * manifest before any is recorded — a batch is all-or-nothing, mirroring
@@ -422,22 +377,34 @@ function describeJSON(value) {
   return typeof value === 'object' ? 'an object' : typeof value;
 }
 
-/** Adds ctx.emit, which every surface but an action has. */
+/** Adds ctx.events, which every surface but an action has. */
 function emitting(baseCtx, manifest, state) {
-  return {
-    ...baseCtx,
-    async emit(event, payload) {
-      const declared = manifest.events?.[event];
-      if (!declared) {
-        fail(
-          `ctx.emit("${event}") — that event is not declared in manifest.json (have: ${names(manifest.events)}). ` +
-            'Juno rejects an undeclared event at runtime.'
-        );
-      }
-      assertValid(declared.payload, payload, `payload of event "${event}"`);
-      state.emitted.push({ event, payload });
-    },
-  };
+  const events = new Proxy(
+    {},
+    {
+      get(_own, event) {
+        if (typeof event !== 'string') return undefined;
+        return {
+          async emit(payload) {
+            const declared = manifest.events?.[event];
+            if (!declared) {
+              fail(
+                `ctx.events.${event}.emit() — that event is not declared in manifest.json (have: ${names(manifest.events)}). ` +
+                  'Juno rejects an undeclared event at runtime.'
+              );
+            }
+            assertValid(
+              declared.payload,
+              payload,
+              `payload of event "${event}"`
+            );
+            state.emitted.push({ event, payload });
+          },
+        };
+      },
+    }
+  );
+  return { ...baseCtx, events };
 }
 
 function defaultConfig(manifest) {
@@ -506,16 +473,35 @@ function buildWebhookRequest(request) {
     typeof request.body === 'string'
       ? request.body
       : JSON.stringify(request.body ?? '');
+  const headers = request.headers ?? {};
   return {
     method: (request.method ?? 'POST').toUpperCase(),
-    headers: request.headers ?? {},
+    headers,
     query: request.query ?? {},
     body,
     json: parseJSONOrNull(body),
     url: request.url ?? '/',
+    subpath: request.subpath ?? '',
+    form: parseFormOrNull(headers, body),
   };
 }
 
+// The host's rule: lower-cased content-type, media type
+// application/x-www-form-urlencoded (a charset parameter is ignored), first
+// value per key — else null.
+function parseFormOrNull(headers, body) {
+  const contentType = (headers['content-type'] ?? headers['Content-Type'] ?? '')
+    .toLowerCase()
+    .split(';')[0]
+    .trim();
+  if (contentType !== 'application/x-www-form-urlencoded') return null;
+  const form = {};
+  for (const [key, value] of new URLSearchParams(body)) {
+    if (!(key in form)) form[key] = value;
+  }
+  return form;
+}
+
 // The host's rule (cmd/control-plane readWebhookRequest): whatever parses is
 // parsed, whatever does not is null — content-type is not consulted.
 function parseJSONOrNull(body) {
@@ -552,11 +538,6 @@ function assertWebhookResponse(name, result) {
   }
 }
 
-function names(obj) {
-  const keys = Object.keys(obj ?? {});
-  return keys.length ? keys.join(', ') : '(none)';
-}
-
 /** Polls a condition, resolving true when it holds or false at the deadline. */
 async function waitFor(condition, timeout) {
   const deadline = Date.now() + timeout;
@@ -580,3 +561,5 @@ async function withTimeout(promise, ms) {
 
 export { conformance } from './conformance.js';
 export { AssertionError } from './assert.js';
+export { flowHarness } from './flow.js';
+export { appHarness } from './app.js';

package/src/names.js

@@ -0,0 +1,9 @@
+/**
+ * The keys of a manifest section, for the "(have: …)" half of a refusal. Both
+ * harnesses end every "not declared" message with it, so the fix is visible in
+ * the failure itself rather than one manifest lookup away.
+ */
+export function names(obj) {
+  const keys = Object.keys(obj ?? {});
+  return keys.length ? keys.join(', ') : '(none)';
+}

package/src/scenario.js

@@ -0,0 +1,72 @@
+import { fail } from './assert.js';
+
+/**
+ * What each scenario key does, per harness kind. A key is applied through the
+ * harness's own setter, so it passes the same checks and fails with the same
+ * message as the call a hand-written test would make; `null` is a key the
+ * harness accepts and leaves to the test.
+ *
+ * - `trigger` names the handler the test runs (`h.trigger(s.trigger)`), and
+ *   `expect` is what the test asserts; neither is world.
+ * - `event` is kept by flowHarness for an event-less `h.trigger(name)`.
+ * - `flow_version` is the version a recorded run ran, which a fixture made
+ *   from that run carries.
+ * - An app has no trigger, event or step.llm. It ignores `trigger` and
+ *   `event`, so one scenario can describe both, and `llm` is unknown to it:
+ *   an answer it would never read is a mistake, not a no-op.
+ */
+const SHARED = {
+  trigger: null,
+  now: (h, v) => h.now(v),
+  timezone: (h, v) => h.timezone(v),
+  solar: (h, v) => h.solar(v),
+  states: (h, v) => h.states(v),
+  controls: (h, v) =>
+    answerAll(v, 'controls', (k, a) => h.controls.answer(k, a)),
+  targets: (h, v) => answerAll(v, 'targets', (k, a) => h.targets.answer(k, a)),
+  credentials: (h, v) => h.credentials(v),
+  event: null,
+  expect: null,
+};
+
+const KEYS = {
+  flow: {
+    ...SHARED,
+    llm: (h, v) => answerAll(v, 'llm', (k, a) => h.llm(k, a)),
+    flow_version: null,
+  },
+  app: SHARED,
+};
+
+/**
+ * Applies scenario s to harness h, key by key through h's own setters. A key
+ * the scenario leaves out sets nothing, so the harness's "not answered"
+ * refusals still apply to it; an unknown key fails before anything is set.
+ */
+export function applyScenario(h, s, { kind }) {
+  const keys = KEYS[kind];
+  if (s === null || typeof s !== 'object' || Array.isArray(s)) {
+    fail(`h.scenario — expected a scenario object, got ${JSON.stringify(s)}`);
+  }
+  for (const key of Object.keys(s)) {
+    if (!Object.hasOwn(keys, key)) {
+      fail(
+        `h.scenario — "${key}" is not a scenario key for ${kind === 'app' ? 'an app' : 'a flow'} (have: ${Object.keys(keys).join(', ')})`
+      );
+    }
+  }
+  for (const [key, apply] of Object.entries(keys)) {
+    if (apply && s[key] !== undefined) apply(h, s[key]);
+  }
+  return h;
+}
+
+/** Answers every `key: answer` of one scenario map with set. */
+function answerAll(map, name, set) {
+  if (map === null || typeof map !== 'object' || Array.isArray(map)) {
+    fail(
+      `h.scenario — "${name}" maps keys to answers; got ${JSON.stringify(map)}`
+    );
+  }
+  for (const [key, answer] of Object.entries(map)) set(key, answer);
+}

package/src/schema.js

@@ -31,11 +31,8 @@ export function assertValid(schema, value, what) {
   if (!schema) return value; // nothing declared, nothing to check
   const validate = compile(schema);
   if (validate(value)) return value;
-  const detail = (validate.errors ?? [])
-    .map((e) => `  ${e.instancePath || '(root)'} ${e.message}`)
-    .join('\n');
   fail(
-    `${what} does not match the schema declared in manifest.json:\n${detail}`,
+    `${what} does not match the schema declared in manifest.json:\n${describeErrors(validate.errors)}`,
     {
       actual: value,
       expected: schema,
@@ -43,6 +40,13 @@ export function assertValid(schema, value, what) {
   );
 }
 
+/** ajv's errors as the testkit prints them: one indented line per error. */
+export function describeErrors(errors) {
+  return (errors ?? [])
+    .map((e) => `  ${e.instancePath || '(root)'} ${e.message}`)
+    .join('\n');
+}
+
 /** Reports whether a schema compiles, for conformance(). */
 export function schemaError(schema) {
   try {