@antelopejs/dms 0.15.0 → 0.16.0

package/bin/control/journey.mjs

@@ -1,16 +1,11 @@
 import { randomBytes } from "node:crypto";
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { withBaseBackend } from "./base.mjs";
 import { launchBrowser, newContext } from "./browser.mjs";
 import { capturedMail } from "./mail.mjs";
+import { isRecord, isString, readRecordList } from "./json.mjs";
 import { saveRun } from "./run-state.mjs";
 import {
   adminCredentials,
@@ -27,6 +22,14 @@ import {
 } from "./stack.mjs";
 import { Tab } from "./tab.mjs";
 
+/**
+ * @typedef {{ name: string, pass: boolean, detail: string }} Check
+ * @typedef {ReturnType<typeof capturedMail>[number]} CapturedMail
+ * @typedef {import("./verify/types.mjs").FeatureResult} FeatureResult
+ * @typedef {{ id: string, title: string, entryPoint: string, database?: string, onboard?: boolean, run: (context: JourneyContext) => Promise<void> }} Journey
+ * @typedef {{ name: string, folder: string, checks: Check[] }} Step
+ */
+
 const EXPECT_TIMEOUT_MS = 15_000;
 const POLL_MS = 250;
 const DETAIL_LENGTH = 300;
@@ -34,6 +37,10 @@ const UNIQUE_BYTES = 3;
 
 class JourneyAbort extends Error {}
 
+/**
+ * @param {string} text The text
+ * @returns {string} The text as a folder name
+ */
 function slug(text) {
   return text
     .toLowerCase()
@@ -42,11 +49,22 @@ function slug(text) {
     .slice(0, 60);
 }
 
+/**
+ * @param {string} file The file
+ * @param {unknown} value The value
+ */
 function writeJson(file, value) {
   writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-/** An equality check over JSON-serialisable values. */
+/**
+ * An equality check over JSON-serialisable values.
+ *
+ * @param {string} name What is compared
+ * @param {unknown} actual The value found
+ * @param {unknown} expected The value wanted
+ * @returns {Check} The check
+ */
 function equal(name, actual, expected) {
   const [left, right] = [JSON.stringify(actual), JSON.stringify(expected)];
   return {
@@ -56,7 +74,13 @@ function equal(name, actual, expected) {
   };
 }
 
-/** A check that an API answer has `expected` as its status. */
+/**
+ * A check that an API answer has `expected` as its status.
+ *
+ * @param {Pick<import("./session.mjs").ApiAnswer, "status" | "body">} answer The answer
+ * @param {number} expected The status wanted
+ * @returns {Check} The check
+ */
 function status(answer, expected) {
   const body = JSON.stringify(answer.body) ?? "";
   return {
@@ -66,7 +90,14 @@ function status(answer, expected) {
   };
 }
 
-/** A check that a condition holds, with what was observed. */
+/**
+ * A check that a condition holds, with what was observed.
+ *
+ * @param {string} name What is checked
+ * @param {unknown} pass Whether it holds
+ * @param {unknown} detail What was observed
+ * @returns {Check} The check
+ */
 function holds(name, pass, detail) {
   return { name, pass: Boolean(pass), detail: String(detail) };
 }
@@ -77,6 +108,13 @@ function holds(name, pass, detail) {
  * folders under `<run>/evidence/<feature>/<journey>/`.
  */
 export class JourneyContext {
+  /**
+   * @param {import("./run-state.mjs").RunState} state The run
+   * @param {string} feature The feature the journey belongs to
+   * @param {string} journey The journey id
+   * @param {import("playwright-core").Browser} browser The Playwright browser
+   * @param {import("./verify/skill.mjs").Skill} skill The skill the journey belongs to
+   */
   constructor(state, feature, journey, browser, skill) {
     this.state = state;
     this.skill = skill;
@@ -84,7 +122,9 @@ export class JourneyContext {
     this.journey = journey;
     this.browser = browser;
     this.folder = join(state.evidence, feature, journey);
+    /** @type {Step[]} */
     this.steps = [];
+    /** @type {Map<string, import("playwright-core").BrowserContext>} */
     this.contexts = new Map();
     this.index = 0;
     this.startedAt = new Date().toISOString();
@@ -95,7 +135,12 @@ export class JourneyContext {
     mkdirSync(this.folder, { recursive: true });
   }
 
-  /** A new numbered step folder. */
+  /**
+   * A new numbered step folder.
+   *
+   * @param {string} label What the step does
+   * @returns {string} The step folder
+   */
   step(label) {
     this.index += 1;
     const name = `${String(this.index).padStart(2, "0")}-${slug(label)}`;
@@ -104,7 +149,14 @@ export class JourneyContext {
     return folder;
   }
 
-  /** Records the checks of a step folder; a failed critical step ends the journey. */
+  /**
+   * Records the checks of a step folder; a failed critical step ends the journey.
+   *
+   * @param {string} folder The step folder
+   * @param {{ name: string, pass: boolean, detail: string }[]} checks The checks
+   * @param {{ critical?: boolean }} [options] Whether a failure ends the journey
+   * @returns {boolean} Whether every check passed
+   */
   record(folder, checks, options = {}) {
     this.steps.push({
       name: relative(this.folder, folder),
@@ -124,12 +176,27 @@ export class JourneyContext {
   /**
    * Records a step of checks, which may be promises (`tab.visible(...)`).
    * With `{ critical: true }` a failure ends the journey.
+   *
+   * @param {string} label What the step verifies
+   * @param {(Check | Promise<Check>)[]} checks The checks, or promises of them
+   * @param {{ critical?: boolean }} [options] Whether a failure ends the journey
+   * @returns {Promise<boolean>} Whether every check passed
    */
   async verify(label, checks, options = {}) {
-    return this.record(this.step(label), await Promise.all(checks), options);
+    return this.record(
+      this.step(label),
+      await Promise.all(checks.map((check) => Promise.resolve(check))),
+      options,
+    );
   }
 
-  /** A new tab as `account` (`anon` for nobody), in that account's own browser context. */
+  /**
+   * A new tab as `account` (`anon` for nobody), in that account's own browser context.
+   *
+   * @param {string} [account] The account, or `anon`
+   * @param {string} [label] The tab's name in evidence
+   * @returns {Promise<Tab>} The tab
+   */
   async tab(account = "admin", label = account) {
     if (!this.contexts.has(account)) {
       this.contexts.set(account, await newContext(this.browser));
@@ -140,6 +207,10 @@ export class JourneyContext {
   /**
    * Calls the backend as `as` (an account, or `anon`; `admin` by default),
    * or with an explicit `token` and no retry, and records the exchange.
+   *
+   * @param {string} label What the call does
+   * @param {{ method: string, path: string, body?: unknown, as?: string, token?: string }} request What to send and as whom
+   * @returns {Promise<import("./session.mjs").ApiAnswer & { folder?: string }>} The answer
    */
   api(label, request) {
     if (request.token) {
@@ -155,7 +226,13 @@ export class JourneyContext {
     });
   }
 
-  /** Sends anonymous requests at once, for races, each recorded in its own step folder. */
+  /**
+   * Sends anonymous requests at once, for races, each recorded in its own step folder.
+   *
+   * @param {string} label What the calls do
+   * @param {{ method: string, path: string, body?: unknown, token?: string }[]} requests What to send
+   * @returns {Promise<import("./session.mjs").ApiAnswer[]>} The answers
+   */
   concurrent(label, requests) {
     return Promise.all(
       requests.map((request, index) =>
@@ -167,18 +244,33 @@ export class JourneyContext {
     );
   }
 
-  /** Adds an account the journey created (an invited member) so tabs and the API can act as it. */
+  /**
+   * Adds an account the journey created (an invited member) so tabs and the API can act as it.
+   *
+   * @param {string} name The account name
+   * @param {import("./run-state.mjs").RunState["accounts"][string]} credentials Its credentials
+   */
   addAccount(name, credentials) {
     this.state.accounts = { ...this.state.accounts, [name]: credentials };
     saveRun(this.state);
   }
 
-  /** An address unique to this run and journey, which the mail sink receives. */
+  /**
+   * An address unique to this run and journey, which the mail sink receives.
+   *
+   * @param {string} name The local part
+   * @returns {string} The address
+   */
   email(name) {
     return `${name}+${this.state.id}-${slug(this.journey)}@verify.local`.toLowerCase();
   }
 
-  /** A string unique to this journey, for names a journey creates. */
+  /**
+   * A string unique to this journey, for names a journey creates.
+   *
+   * @param {string} prefix What the string starts with
+   * @returns {string} The unique string
+   */
   unique(prefix) {
     return `${prefix} ${randomBytes(UNIQUE_BYTES).toString("hex")}`;
   }
@@ -193,6 +285,11 @@ export class JourneyContext {
     return adminCredentials(this.state);
   }
 
+  /** The setup token the run's backend accepts for the first registration (`DMS_SETUP_TOKEN`). */
+  setupToken() {
+    return this.state.secrets.DMS_SETUP_TOKEN;
+  }
+
   /** Creates the administrator through `POST /api/onboarding/register`, then signs it in. */
   onboard(options = {}) {
     return onboard(this.state, options);
@@ -202,6 +299,9 @@ export class JourneyContext {
    * Runs `action` against the base version's backend on the same database,
    * then the run's own backend again: data written inside `action` is data
    * the previous release wrote. Records the base commit as a step.
+   *
+   * @param {(sha: string) => Promise<void>} action What to do against the base backend
+   * @returns {Promise<string>} The base commit
    */
   async withBaseBackend(action) {
     const sha = await withBaseBackend(this.state, this.skill, action);
@@ -220,6 +320,10 @@ export class JourneyContext {
   /**
    * The mail the sink captured since the journey started, waiting until
    * `accept` matches one or the timeout passes; `match` is the latest match.
+   *
+   * @param {(message: CapturedMail) => boolean} accept Whether a message is the awaited one
+   * @param {number} [timeoutMs] How long to wait
+   * @returns {Promise<{ folder: string, messages: CapturedMail[], match: CapturedMail | undefined }>} What arrived
    */
   async mail(accept, timeoutMs = EXPECT_TIMEOUT_MS) {
     const deadline = Date.now() + timeoutMs;
@@ -241,6 +345,12 @@ export class JourneyContext {
   }
 }
 
+/**
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {string} feature The feature the journey belongs to
+ * @param {Journey} journey The journey
+ * @param {JourneyContext} context The journey's context
+ */
 async function prepare(state, feature, journey, context) {
   await ensureMail(state);
   if (journey.database !== "shared") {
@@ -278,10 +388,11 @@ async function prepare(state, feature, journey, context) {
  * false` skips the administrator), with a fresh browser, and writes its
  * result.json.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {string} feature The feature it belongs to
- * @param {{ id: string, title: string, entryPoint: string, database?: string, onboard?: boolean, run: (context: JourneyContext) => Promise<void> }} journey The journey
- * @returns {Promise<Record<string, any>>} The result
+ * @param {Journey} journey The journey
+ * @param {import("./verify/skill.mjs").Skill} skill The skill the journey belongs to
+ * @returns {Promise<FeatureResult>} The result
  */
 export async function runJourney(state, feature, journey, skill) {
   const browser = await launchBrowser(resolutionFolders(state));
@@ -323,17 +434,40 @@ export async function runJourney(state, feature, journey, skill) {
   return result;
 }
 
+/**
+ * @param {unknown} value A value a journeys module exports
+ * @returns {value is Journey} True for an object with the fields a journey run reads
+ */
+function isJourney(value) {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.title) &&
+    isString(value.entryPoint) &&
+    (value.database === undefined || isString(value.database)) &&
+    (value.onboard === undefined || typeof value.onboard === "boolean") &&
+    typeof value.run === "function"
+  );
+}
+
 /**
  * Loads the journeys a feature's file exports (`export const journeys`).
  *
  * @param {string} file The journeys module
- * @returns {Promise<Record<string, any>[]>} The journeys
+ * @returns {Promise<Journey[]>} The journeys
  */
 export async function loadJourneys(file) {
   if (!existsSync(file)) throw new Error(`${file} does not exist`);
-  const { journeys } = await import(pathToFileURL(file).href);
-  if (!Array.isArray(journeys))
+  /** @type {unknown} */
+  const exported = await import(pathToFileURL(file).href);
+  const entries = isRecord(exported) ? exported.journeys : undefined;
+  if (!Array.isArray(entries))
     throw new Error(`${file} exports no journeys array`);
+  const journeys = entries.filter(isJourney);
+  if (journeys.length !== entries.length)
+    throw new Error(
+      `${file} exports a journey without an id, title, entry point or run function`,
+    );
   return journeys;
 }
 
@@ -341,9 +475,9 @@ export async function loadJourneys(file) {
  * Runs a feature's journeys, all or those named, and merges their results
  * into `<feature>/feature.json` so a partial run never drops earlier ones.
  *
- * @param {Record<string, any>} state The run
- * @param {{ file: string, feature: string, ids: string[], skill: Record<string, any> }} request Which journeys, and the skill they belong to
- * @returns {Promise<Record<string, any>[]>} The results of this run
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {{ file: string, feature: string, ids: string[], skill: import("./verify/skill.mjs").Skill }} request Which journeys, and the skill they belong to
+ * @returns {Promise<FeatureResult[]>} The results of this run
  */
 export async function runJourneyFile(state, request) {
   const journeys = await loadJourneys(request.file);
@@ -359,15 +493,14 @@ export async function runJourneyFile(state, request) {
     request.ids.length > 0
       ? journeys.filter((journey) => request.ids.includes(journey.id))
       : journeys;
+  /** @type {FeatureResult[]} */
   const results = [];
   for (const journey of selected)
     results.push(
       await runJourney(state, request.feature, journey, request.skill),
     );
   const file = join(state.evidence, request.feature, "feature.json");
-  const earlier = existsSync(file)
-    ? JSON.parse(readFileSync(file, "utf8"))
-    : [];
+  const earlier = existsSync(file) ? readRecordList(file) : [];
   const merged = journeys.flatMap((journey) => {
     const fresh = results.filter((result) => result.journey === journey.id);
     return fresh.length > 0

package/bin/control/journey.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { loadJourneys } from "./journey.mjs";
+
+const JOURNEY = '{ id: "smoke", title: "t", entryPoint: "e", async run() {} }';
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {string} source The module source
+ * @returns {string} The journeys module
+ */
+function journeysModule(t, source) {
+  const dir = mkdtempSync(join(tmpdir(), "dms-control-journey-test-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  const file = join(dir, "journeys.mjs");
+  writeFileSync(file, source);
+  return file;
+}
+
+await test("a module exporting well-formed journeys loads them", async (t) => {
+  const file = journeysModule(
+    t,
+    `export const journeys = [${JOURNEY}, { id: "b", title: "t", entryPoint: "e", database: "fresh", onboard: false, async run() {} }];`,
+  );
+  const journeys = await loadJourneys(file);
+  assert.deepEqual(
+    journeys.map((journey) => journey.id),
+    ["smoke", "b"],
+  );
+});
+
+await test("a module without a journeys array is refused", async (t) => {
+  await assert.rejects(
+    loadJourneys(journeysModule(t, "export const journeys = {};")),
+    /exports no journeys array/,
+  );
+  await assert.rejects(
+    loadJourneys(journeysModule(t, "export const other = [];")),
+    /exports no journeys array/,
+  );
+});
+
+await test("a journey missing a field a run reads is refused", async (t) => {
+  const broken = [
+    '{ title: "t", entryPoint: "e", async run() {} }',
+    '{ id: "x", title: "t", entryPoint: "e" }',
+    '{ id: "x", title: "t", entryPoint: "e", database: 3, async run() {} }',
+    '{ id: "x", title: "t", entryPoint: "e", onboard: "yes", async run() {} }',
+    "null",
+  ];
+  for (const journey of broken) {
+    await assert.rejects(
+      loadJourneys(journeysModule(t, `export const journeys = [${journey}];`)),
+      /exports a journey without an id/,
+      journey,
+    );
+  }
+});

package/bin/control/json.mjs

@@ -0,0 +1,229 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Reads of JSON a program received, narrowed through checks instead of typed
+ * by assertion. Everything here takes `unknown` because JSON arrives
+ * unchecked.
+ */
+
+/**
+ * @param {unknown} value A parsed JSON value
+ * @returns {value is Record<string, unknown>} True for an object that is not an array or null
+ */
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value A parsed JSON value
+ * @returns {value is string} True for a string
+ */
+export function isString(value) {
+  return typeof value === "string";
+}
+
+/**
+ * The string an object holds under its own key.
+ *
+ * @param {unknown} body A parsed JSON value
+ * @param {string} key The property
+ * @returns {string | undefined} The string, or undefined when `body` is no object or the property is absent or not a string
+ */
+export function stringField(body, key) {
+  if (!isRecord(body)) return undefined;
+  /** @type {unknown} */
+  const value = Object.getOwnPropertyDescriptor(body, key)?.value;
+  return isString(value) ? value : undefined;
+}
+
+/**
+ * The first element of a JSON array, when it is a string.
+ *
+ * @param {unknown} body A parsed JSON value
+ * @returns {string | undefined} The first string, or undefined when `body` is no array or starts with anything else
+ */
+export function firstString(body) {
+  if (!Array.isArray(body)) return undefined;
+  /** @type {unknown} */
+  const first = body.at(0);
+  return isString(first) ? first : undefined;
+}
+
+/**
+ * The objects a JSON file lists, kept as written.
+ *
+ * @param {string} file The JSON file
+ * @returns {Record<string, unknown>[]} The listed objects
+ * @throws When the file holds anything but a list of objects
+ */
+export function readRecordList(file) {
+  /** @type {unknown} */
+  const stored = JSON.parse(readFileSync(file, "utf8"));
+  if (!Array.isArray(stored))
+    throw new Error(`${file} is not a list of objects`);
+  const records = stored.filter(isRecord);
+  if (records.length !== stored.length)
+    throw new Error(`${file} is not a list of objects`);
+  return records;
+}
+
+/**
+ * @template T
+ * @typedef {(value: unknown) => value is T} Guard A check that narrows a parsed JSON value to `T`
+ */
+
+/**
+ * @param {unknown} value A parsed JSON value
+ * @returns {value is number} True for a number
+ */
+export function isNumber(value) {
+  return typeof value === "number";
+}
+
+/**
+ * @param {unknown} value A parsed JSON value
+ * @returns {value is boolean} True for a boolean
+ */
+export function isBoolean(value) {
+  return typeof value === "boolean";
+}
+
+/**
+ * @param {unknown} value A parsed JSON value
+ * @returns {value is null} True for null
+ */
+function isNull(value) {
+  return value === null;
+}
+
+/**
+ * @template T
+ * @param {Guard<T>} item What each element must be
+ * @returns {Guard<T[]>} A guard for lists
+ */
+export function arrayOf(item) {
+  /**
+   * @param {unknown} value A parsed JSON value
+   * @returns {value is T[]} True for a list whose every element passes `item`
+   */
+  return (value) => Array.isArray(value) && value.every(item);
+}
+
+/**
+ * @template T
+ * @param {Guard<T>} item What each value must be
+ * @returns {Guard<Record<string, T>>} A guard for objects keyed by any string
+ */
+export function recordOf(item) {
+  /**
+   * @param {unknown} value A parsed JSON value
+   * @returns {value is Record<string, T>} True for an object whose every value passes `item`
+   */
+  return (value) => isRecord(value) && Object.values(value).every(item);
+}
+
+/**
+ * @template T
+ * @param {Guard<T>} guard What the value must be unless it is null
+ * @returns {Guard<T | null>} A guard that also accepts null
+ */
+export function nullable(guard) {
+  return either(guard, isNull);
+}
+
+/**
+ * @template A
+ * @template B
+ * @param {Guard<A>} first One accepted form
+ * @param {Guard<B>} second The other accepted form
+ * @returns {Guard<A | B>} A guard for either form
+ */
+export function either(first, second) {
+  /**
+   * @param {unknown} value A parsed JSON value
+   * @returns {value is A | B} True when one of the forms matches
+   */
+  return (value) => first(value) || second(value);
+}
+
+/**
+ * @template {string} Name
+ * @param {Name[]} names The accepted strings
+ * @returns {Guard<Name>} A guard for one of the names
+ */
+export function oneOf(names) {
+  /**
+   * @param {unknown} value A parsed JSON value
+   * @returns {value is Name} True for one of the names
+   */
+  return (value) => isString(value) && names.some((name) => name === value);
+}
+
+/**
+ * @template T
+ * @param {new (...args: never[]) => T} constructor The class
+ * @returns {Guard<T>} A guard for its instances
+ */
+export function instanceOf(constructor) {
+  /**
+   * @param {unknown} value A value
+   * @returns {value is T} True for an instance
+   */
+  return (value) => value instanceof constructor;
+}
+
+/**
+ * @param {Record<string, unknown>} record An object
+ * @param {string} key The property
+ * @returns {unknown} Its own value, undefined when it holds none
+ */
+function ownValue(record, key) {
+  return Object.getOwnPropertyDescriptor(record, key)?.value;
+}
+
+/**
+ * @template {Record<string, Guard<unknown>>} Required
+ * @template {Record<string, Guard<unknown>>} Optional
+ * @typedef {{ [Key in keyof Required]: Required[Key] extends Guard<infer T> ? T : never } & { [Key in keyof Optional]?: Optional[Key] extends Guard<infer T> ? T : never }} Properties
+ */
+
+/**
+ * An object with the required properties, each passing its guard, and the
+ * optional ones, which pass theirs when present. Other properties are not
+ * looked at. Only own properties count.
+ *
+ * @template {Record<string, Guard<unknown>>} Required
+ * @template {Record<string, Guard<unknown>>} [Optional=Record<never, never>]
+ * @param {Required} required The guard of each required property
+ * @param {Optional} [optional] The guard of each optional property
+ * @returns {Guard<Properties<Required, Optional>>} A guard for the object
+ */
+export function objectOf(required, optional) {
+  /**
+   * @param {unknown} value A parsed JSON value
+   * @returns {value is Properties<Required, Optional>} True for an object with these properties
+   */
+  return (value) =>
+    isRecord(value) &&
+    Object.entries(required).every(([key, guard]) =>
+      guard(ownValue(value, key)),
+    ) &&
+    Object.entries(optional ?? {}).every(
+      ([key, guard]) =>
+        ownValue(value, key) === undefined || guard(ownValue(value, key)),
+    );
+}
+
+/**
+ * @template T
+ * @param {Guard<T>} guard What the value must be
+ * @param {unknown} value The value read
+ * @param {string} source Where it was read, named in the error
+ * @param {string} expected What the value should be, named in the error
+ * @returns {T} The value
+ * @throws When the value does not pass the guard
+ */
+export function decode(guard, value, source, expected) {
+  if (guard(value)) return value;
+  throw new Error(`${source} is malformed: expected ${expected}`);
+}