@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/scenario.js

@@ -0,0 +1,1079 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { ParameterTypeRegistry } from "@cucumber/cucumber-expressions";
+import { PickleStepType, } from "@cucumber/messages";
+import { buildLibrary, lineOf, runFeatures, stepResults, StepStatus, } from "./cucumber.js";
+import { errorInfo, SanomaError } from "./errors.js";
+import { contains, detailOf, isCall } from "./expectations.js";
+import { fill, isBug, seedFrom, shapeOf } from "./fill.js";
+import { outlineWorkflow } from "./outline.js";
+import { DRIFT_WORKFLOW, errorMessage, fitsOp, flatten, isEnded } from "./shared.js";
+const KINDS = {
+    [PickleStepType.CONTEXT]: "given",
+    [PickleStepType.ACTION]: "when",
+    [PickleStepType.OUTCOME]: "then",
+};
+const FAULTS = {
+    "fails once": "failNext",
+    "is rate limited once": "rateLimit",
+    "loses its reply once": "loseReply",
+};
+/** The schema of the field `name` of an object schema (`owner`, for the error); throws naming the fields it has. */
+function fieldOf(schema, name, owner) {
+    const shape = shapeOf(schema);
+    if (!Object.hasOwn(shape, name)) {
+        throw new Error(`no field "${name}" in ${owner}; it has ${Object.keys(shape).join(", ") || "none"}`);
+    }
+    return shape[name];
+}
+const issues = (error) => error.issues.map((i) => i.message).join("; ");
+/**
+ * The value text from a table cell or a phrase gives a field: the text itself when the field
+ * takes it, else the text read as JSON (a number, `true`, a list) when the field takes that.
+ */
+function valueFor(field, text, what) {
+    const asText = field.safeParse(text);
+    if (asText.success)
+        return text;
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${what} cannot be ${JSON.stringify(text)}: ${issues(asText.error)}`);
+    }
+    const asJson = field.safeParse(json);
+    if (!asJson.success)
+        throw new Error(`${what} cannot be ${text}: ${issues(asJson.error)}`);
+    return json;
+}
+/**
+ * The fields the step's doc string (a JSON object) or two-column table gives `owner` (an
+ * operation's input, or a resource), each checked against its field in `schema`: a field it
+ * lacks, or a value it refuses, is an error.
+ */
+function fieldsFrom(pickle, schema, owner) {
+    const { docString, dataTable } = pickle.argument ?? {};
+    const what = (name) => `${name} in ${owner}`;
+    if (dataTable) {
+        return Object.fromEntries(dataTable.rows.map(({ cells }) => {
+            if (cells.length !== 2)
+                throw new Error(`the table after "${pickle.text}" needs two columns: name | value`);
+            const [name, text] = cells.map((c) => c.value);
+            return [name, valueFor(fieldOf(schema, name, owner), text, what(name))];
+        }));
+    }
+    if (!docString)
+        throw new Error(`"${pickle.text}" needs a JSON doc string or a two-column table after it`);
+    let value;
+    try {
+        value = JSON.parse(docString.content);
+    }
+    catch (err) {
+        throw new Error(`the doc string after "${pickle.text}" is not JSON: ${errorMessage(err)}`, { cause: err });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`"${pickle.text}" needs a JSON object`);
+    }
+    for (const [name, v] of Object.entries(value)) {
+        const parsed = fieldOf(schema, name, owner).safeParse(v);
+        if (!parsed.success)
+            throw new Error(`${what(name)} cannot be ${JSON.stringify(v)}: ${issues(parsed.error)}`);
+    }
+    return value;
+}
+/** A parameter's transform: the name, when `ids` has it. */
+const known = (what, ids) => (name) => {
+    if (!ids.has(name))
+        throw new Error(`no ${what} "${name}"; the config has ${[...ids.keys()].toSorted().join(", ")}`);
+    return name;
+};
+const TAKES_OBJECT = "a JSON doc string or a two-column table";
+/** What a field belongs to, in errors: an operation's or a workflow's input. */
+const inputOf = (name) => `${name}'s input`;
+/** A step's verdict: passed when there is no `detail`. */
+const verdict = (step, detail) => detail === undefined ? { step, ok: true } : { step, ok: false, detail };
+const expressionOf = (rule) => rule.expression ?? rule.source;
+/** By the scope's operations, which every scope of one resolved config shares. */
+const builtByOps = new WeakMap();
+/**
+ * The steps a feature file may use in a scope, and the Cucumber library that runs them: the
+ * generic steps, the steps of an operation's own tests, each step library's steps, and each
+ * operation's `phrases`, compiled into steps. Throws for a phrase naming a field its operation's
+ * input does not have.
+ */
+function builtFor(scope) {
+    const cached = builtByOps.get(scope.ops);
+    if (cached &&
+        cached.scope.workflows === scope.workflows &&
+        cached.scope.types === scope.types &&
+        cached.scope.steps === scope.steps) {
+        return cached;
+    }
+    const { rules, parameterTypes } = rulesOf(scope);
+    const byExpression = Map.groupBy(rules, expressionOf);
+    const library = buildLibrary(parameterTypes, byExpression.keys());
+    const built = { scope, byExpression, library, known: knownSteps(rules) };
+    builtByOps.set(scope.ops, built);
+    return built;
+}
+/** A `Then` step of the generic steps: its expectation, checked against the run's records. */
+const expecting = (expect) => ({ expect, verify: (run) => detailOf(expect, run.records) });
+/** The rules a scope has, and the parameter types their expressions use. */
+function rulesOf(scope) {
+    const { types } = scope;
+    const parameterTypes = [
+        { name: "op", regexp: /\S+/, transformer: known("operation", scope.ops) },
+        { name: "workflow", regexp: /\S+/, transformer: known("workflow", scope.workflows) },
+        { name: "who", regexp: /\S+/, transformer: (s) => s },
+        { name: "resource", regexp: /\S+/, transformer: known("resource type", types) },
+        // A declared resource, as a drift report names it: `<file>#<export>`.
+        { name: "declared", regexp: /[^\s#]+#\S+/, transformer: (s) => s },
+        { name: "field", regexp: /\S+/, transformer: (s) => s },
+    ];
+    const opOf = (id) => scope.ops.get(id);
+    const workflowOf = (name) => scope.workflows.get(name);
+    /** A resource step's object: its type's id, vendor and type, and its import id. */
+    const object = (id, name) => {
+        const { vendor, type } = types.get(id);
+        return { resource: id, vendor, type, name: name };
+    };
+    const rules = [
+        {
+            kind: "given",
+            source: "{op} was called with",
+            takes: TAKES_OBJECT,
+            read: ([op], pickle) => [
+                { op: op, input: fill(opOf(op).input, fieldsFrom(pickle, opOf(op).input, inputOf(op))) },
+            ],
+        },
+        ...Object.entries(FAULTS).map(([words, fault]) => ({
+            kind: "given",
+            source: `{op} ${words}`,
+            read: ([op]) => [{ op: op, fault }],
+        })),
+        {
+            kind: "given",
+            source: "{resource} {string} has",
+            takes: TAKES_OBJECT,
+            read: ([resource, name], pickle) => [
+                {
+                    ...object(resource, name),
+                    fields: fieldsFrom(pickle, types.get(resource).schema, `${resource} "${name}"`),
+                },
+            ],
+        },
+        {
+            kind: "given",
+            source: "{resource} {string} is gone",
+            read: ([resource, name]) => [{ ...object(resource, name), gone: true }],
+        },
+        {
+            kind: "when",
+            source: "{workflow} runs with",
+            takes: TAKES_OBJECT,
+            read: ([name], pickle) => {
+                const { input } = workflowOf(name);
+                return { workflow: name, input: fill(input, fieldsFrom(pickle, input, inputOf(name))) };
+            },
+        },
+        {
+            kind: "when",
+            source: "{workflow} runs",
+            read: ([name]) => ({ workflow: name, input: fill(workflowOf(name).input, {}) }),
+        },
+        // An operation's own test: a call made to its driver, or its fake, directly.
+        {
+            kind: "when",
+            source: "{op} is called with",
+            takes: TAKES_OBJECT,
+            read: ([op], pickle) => ({
+                call: op,
+                input: fill(opOf(op).input, fieldsFrom(pickle, opOf(op).input, inputOf(op))),
+            }),
+        },
+        ...["approve", "reject"].flatMap((decision) => {
+            const verb = decision === "approve" ? "approved" : "rejected";
+            return [`{string} is ${verb} by {who}`, `{string} is ${verb} by {who} with note {string}`].map((source) => ({
+                kind: "any",
+                source,
+                read: ([approval, by, note]) => ({
+                    approval: approval,
+                    decision,
+                    by: by,
+                    ...(note === undefined ? {} : { note: note }),
+                }),
+            }));
+        }),
+        {
+            kind: "then",
+            source: "{op} was called with",
+            takes: TAKES_OBJECT,
+            read: ([op], pickle) => expecting({ op: op, input: fieldsFrom(pickle, opOf(op).input, inputOf(op)), called: true }),
+        },
+        ...[true, false].map((called) => ({
+            kind: "then",
+            source: `{op} was ${called ? "" : "not "}called`,
+            read: ([op]) => expecting({ op: op, called }),
+        })),
+        {
+            kind: "then",
+            source: "{op} was denied",
+            read: ([op]) => expecting({ op: op, decision: "denied" }),
+        },
+        {
+            kind: "then",
+            source: "{op} was held for {who}",
+            read: ([op, who]) => expecting({ op: op, decision: "held", approver: who }),
+        },
+        {
+            kind: "then",
+            source: "step {string} was called with",
+            takes: TAKES_OBJECT,
+            read: ([name], pickle, workflow) => {
+                const node = stepNamed(scope, workflow, name);
+                const step = `step "${name}"`;
+                if (node.kind !== "op") {
+                    throw new Error(`${step} is ${node.kind === "sleep" ? "a sleep" : "an approval"}, which takes no input`);
+                }
+                // An unnamed call with a computed segment is named by the operation it calls.
+                const op = scope.ops.get(node.id) ?? (node.name === undefined ? scope.ops.get(name) : undefined);
+                if (!op)
+                    throw new Error(`${step} calls ${node.id}, whose input cannot be read: name its operation in full`);
+                return expecting({ name: name, input: fieldsFrom(pickle, op.input, inputOf(op.id)), called: true });
+            },
+        },
+        ...[true, false].map((called) => ({
+            kind: "then",
+            source: `step {string} was ${called ? "" : "not "}called`,
+            read: ([name], _, workflow) => {
+                stepNamed(scope, workflow, name);
+                return expecting({ name: name, called });
+            },
+        })),
+        {
+            kind: "then",
+            source: "step {string} ran {int} time(s)",
+            read: ([name, times], _, workflow) => {
+                stepNamed(scope, workflow, name);
+                return expecting({ name: name, times: times });
+            },
+        },
+        {
+            kind: "then",
+            source: "{declared} is drifted in {field}",
+            read: ([declared, field]) => expecting({ declared: declared, status: "drifted", field: field }),
+        },
+        ...["clean", "gone"].map((status) => ({
+            kind: "then",
+            source: `{declared} is ${status}`,
+            read: ([declared]) => expecting({ declared: declared, status }),
+        })),
+        { kind: "then", source: "the run succeeds", read: () => expecting({ outcome: "finished" }) },
+        { kind: "then", source: "the run fails", read: () => expecting({ outcome: "failed" }) },
+        {
+            kind: "then",
+            source: "the run fails with {string}",
+            read: ([code]) => expecting({ outcome: "failed", code: code }),
+        },
+        // The result of the last call: what an operation's own test checks.
+        {
+            kind: "then",
+            source: "it returns",
+            takes: "a JSON doc string or a two-column table, of fields of its output",
+            read: (_, pickle) => ({
+                expect: { custom: true },
+                verify: ({ records }) => {
+                    const last = lastCall(records);
+                    if (typeof last === "string")
+                        return last;
+                    if (last.error)
+                        return `it failed: ${last.error.code ?? last.error.name}: ${last.error.message}`;
+                    const expected = fieldsFrom(pickle, opOf(last.op).output, `${last.op}'s output`);
+                    return contains(last.output, expected) ? undefined : `it returned ${JSON.stringify(last.output)}`;
+                },
+            }),
+        },
+        {
+            kind: "then",
+            source: "it fails with status {int}",
+            read: ([status]) => ({
+                expect: { custom: true },
+                verify: ({ records }) => {
+                    const last = lastCall(records);
+                    if (typeof last === "string")
+                        return last;
+                    if (!last.error)
+                        return `it returned ${JSON.stringify(last.output)}`;
+                    if (last.error.status === status)
+                        return undefined;
+                    return `it failed with ${last.error.status === undefined ? "no status" : `status ${last.error.status}`}: ${last.error.message}`;
+                },
+            }),
+        },
+    ];
+    // Each step library's steps, after the generic ones.
+    /** An operation a step library's step names: one of the config's. */
+    const opNamed = (op) => known("operation", scope.ops)(op.id);
+    for (const { owner, steps } of scope.steps) {
+        for (const def of steps) {
+            const base = { source: def.expression, group: owner };
+            if (def.kind === "given") {
+                rules.push({
+                    ...base,
+                    kind: "given",
+                    read: (values) => {
+                        const seed = def.fn(...values);
+                        const op = opNamed(seed.op);
+                        if ("fault" in seed)
+                            return [{ op, fault: seed.fault }];
+                        let input;
+                        try {
+                            input = fill(opOf(op).input, seed.input);
+                        }
+                        catch (err) {
+                            if (isBug(err))
+                                throw err;
+                            throw new Error(`${inputOf(op)} cannot be ${JSON.stringify(seed.input)}: ${errorMessage(err)}`, {
+                                cause: err,
+                            });
+                        }
+                        return [{ op, input, ...(seed.as === undefined ? {} : { as: seed.as }) }];
+                    },
+                });
+                continue;
+            }
+            rules.push({
+                ...base,
+                kind: "then",
+                read: (values) => {
+                    const expected = def.fn(...values);
+                    return {
+                        expect: {
+                            custom: true,
+                            ...(expected.op === undefined ? {} : { op: opNamed(expected.op) }),
+                            ...(expected.called === undefined ? {} : { called: expected.called }),
+                        },
+                        verify: (run) => {
+                            const detail = expected.check(run);
+                            return typeof detail === "string" ? detail : undefined;
+                        },
+                    };
+                },
+            });
+        }
+    }
+    // Each operation's phrases, last. A field `{title}` becomes the parameter type `{field_title}`,
+    // so a field named like another type (`op`, `string`, `int`) never takes that type's pattern.
+    // It matches what `{string}` does, or one word, and unquotes the same way.
+    const string = new ParameterTypeRegistry().lookupByTypeName("string");
+    const word = /([^\s"']\S*)/;
+    const field = (groups) => groups.at(-1) ?? string.transform(null, groups.slice(0, -1));
+    const fieldTypes = new Set();
+    for (const op of scope.ops.values()) {
+        // A phrase's key, and the keyword of the steps it adds.
+        for (const [key, kind] of [
+            ["given", "given"],
+            ["expect", "then"],
+        ]) {
+            const template = op.phrases?.[key];
+            if (template === undefined)
+                continue;
+            const fields = [...template.matchAll(/\{([^}]*)\}/g)].map(([, name]) => name);
+            const schemas = fields.map((name) => {
+                try {
+                    return fieldOf(op.input, name, inputOf(op.id));
+                }
+                catch {
+                    throw new Error(`${op.id}: its ${key} phrase "${template}" names {${name}}, which is not a field of its input`);
+                }
+            });
+            for (const name of fields) {
+                if (fieldTypes.has(name))
+                    continue;
+                fieldTypes.add(name);
+                parameterTypes.push({
+                    name: `field_${name}`,
+                    regexp: [...string.regexpStrings, word.source],
+                    transformer: (...g) => field(g),
+                });
+            }
+            const given = (values) => Object.fromEntries(fields.map((name, i) => [name, valueFor(schemas[i], values[i], `${name} in ${inputOf(op.id)}`)]));
+            const common = { source: template, group: op.id, expression: template.replaceAll(/\{([^}]*)\}/g, "{field_$1}") };
+            rules.push(kind === "given"
+                ? { ...common, kind, read: (values) => [{ op: op.id, input: fill(op.input, given(values)) }] }
+                : { ...common, kind, read: (values) => expecting({ op: op.id, input: given(values), called: true }) });
+        }
+    }
+    return { rules, parameterTypes };
+}
+/** The last call of a run, or why there is none to check. */
+function lastCall(records) {
+    return records.findLast(isCall) ?? "no call was made";
+}
+/** Every step the scope knows, for an error: the generic ones by keyword, then each operation's phrases and each step library's steps under its name. */
+function knownSteps(rules) {
+    const keyword = (kind) => (kind === "any" ? "Given/When/Then" : kind[0].toUpperCase() + kind.slice(1));
+    const line = (r) => `${keyword(r.kind)} ${r.source}${r.takes ? ` (and ${r.takes})` : ""}`;
+    const { generic = [], ...groups } = Object.groupBy(rules, (r) => r.group ?? "generic");
+    return [
+        "Known steps:",
+        ...generic.map((r) => `  ${line(r)}`),
+        ...Object.entries(groups).flatMap(([group, list]) => [`  ${group}:`, ...(list ?? []).map((r) => `    ${line(r)}`)]),
+    ].join("\n");
+}
+/**
+ * A scenario's own lines of its file's `text`: from its keyword line to the end of its last
+ * step (the closing delimiter of a doc string, the last row of a table) or of its examples'
+ * last row, each line less the keyword line's indent.
+ */
+function textOf(scenario, text) {
+    const lines = text.split(/\r?\n/);
+    const endOf = (step) => {
+        if (step.dataTable)
+            return step.dataTable.rows.at(-1)?.location.line ?? step.location.line;
+        if (!step.docString)
+            return step.location.line;
+        // Line numbers count from 1, so index `line` is the line after the opening delimiter.
+        const { location, delimiter } = step.docString;
+        const close = lines.findIndex((l, i) => i >= location.line && l.trim() === delimiter);
+        return close === -1 ? location.line : close + 1;
+    };
+    const { line, column = 1 } = scenario.location;
+    const end = Math.max(line, ...scenario.steps.map(endOf), ...scenario.examples.map((ex) => (ex.tableBody.at(-1) ?? ex.tableHeader ?? ex).location.line));
+    return lines
+        .slice(line - 1, end)
+        .map((l) => l.slice(Math.min(column - 1, l.length - l.trimStart().length)))
+        .join("\n");
+}
+const nodesByWorkflow = new WeakMap();
+/** A workflow's outline, read once: its nodes, or undefined when its code cannot be outlined. */
+function nodesOf(wf) {
+    if (!nodesByWorkflow.has(wf)) {
+        const outline = outlineWorkflow(wf);
+        nodesByWorkflow.set(wf, "nodes" in outline ? outline.nodes : undefined);
+    }
+    return nodesByWorkflow.get(wf);
+}
+const isStep = (n) => n.kind === "op" || n.kind === "approval" || n.kind === "sleep";
+/**
+ * The one step of the workflow's outline named `name` (an operation's call or a sleep by the
+ * name it gives or its default, an approval by its title). Throws outside a scenario's workflow
+ * (before its `When`, or in an operation's own test), when no step has the name, and when several
+ * may: a name a call defaults to (its operation's id) can be several calls', and an unnamed call
+ * with a computed segment is named in a run by the operation it calls, which may be this one.
+ */
+function stepNamed(scope, workflow, name) {
+    if (workflow === undefined) {
+        throw new Error(`step "${name}" names a step of a workflow: it goes after the When that runs one, in scenarios/`);
+    }
+    const nodes = nodesOf(scope.workflows.get(workflow));
+    if (!nodes)
+        throw new Error(`${workflow}'s code cannot be outlined, so its steps have no names`);
+    const steps = flatten(nodes).filter(isStep);
+    const named = steps.filter((n) => n.name === name || (n.kind === "op" && n.name === undefined && (n.ops?.includes(name) ?? fitsOp(n.id, name))));
+    if (named.length === 1)
+        return named[0];
+    if (named.length > 1) {
+        throw new Error(`${named.length} steps of ${workflow} are named "${name}": give the one to check a name of its own, such as \`{ name: "Publish the post" }\``);
+    }
+    const names = [...new Set(steps.flatMap((n) => (n.name === undefined ? [] : [`"${n.name}"`])))];
+    throw new Error(`no step of ${workflow} is named "${name}"; its steps are ${names.join(", ") || "none"}`);
+}
+/** The titles of the approvals in an outline, at any depth, where they are string literals. */
+const titles = (nodes) => nodes.flatMap((n) => {
+    if (n.kind === "approval")
+        return n.title === undefined ? [] : [n.title];
+    if (n.kind === "all")
+        return n.branches.flatMap(titles);
+    if (n.kind === "branch")
+        return n.cases.flatMap(titles);
+    return n.kind === "each" || n.kind === "repeat" ? titles(n.body) : [];
+});
+/** The literal titles of the approvals a workflow's code asks for, from its outline. */
+const approvalsOf = (wf) => [...new Set(titles(nodesOf(wf) ?? []))];
+const namesByReport = new WeakMap();
+/**
+ * The name of each pickle of a run, by its id: its own, or for an outline's rows whose names
+ * would be the same, its own with its row's line (`Launch (line 12)`).
+ */
+function namesOf(report) {
+    const cached = namesByReport.get(report);
+    if (cached)
+        return cached;
+    const names = new Map();
+    namesByReport.set(report, names);
+    for (const inFile of Map.groupBy(report.query.findAllPickles(), (p) => p.uri).values()) {
+        const counts = Map.groupBy(inFile, (p) => p.name);
+        for (const pickle of inFile) {
+            const shared = pickle.astNodeIds.length > 1 && counts.get(pickle.name).length > 1;
+            names.set(pickle.id, shared ? `${pickle.name} (line ${lineOf(report, pickle)})` : pickle.name);
+        }
+    }
+    return names;
+}
+/** The run's records, as a `Then` step reads them. */
+function viewOf(records) {
+    // What the ledger holds a call took and returned is of its operation's types.
+    const calls = (op) => records
+        .filter((r) => isCall(r) && r.op === op.id && !r.error)
+        .map(({ input, output }) => ({ input, output }));
+    const seeded = (op) => records.flatMap((r) => r.type === "scenario.seeded"
+        ? r.seeds.flatMap((s) => "op" in s && s.op === op.id ? [{ input: s.input, output: s.output }] : [])
+        : []);
+    return { records, calls, seeded, made: (op) => [...seeded(op), ...calls(op)] };
+}
+/** Why no step, or two, match a step's text. */
+const noMatch = (built, text) => `no step matches "${text}"\n${built.known}`;
+const ambiguous = (text, sources) => `"${text}" is ambiguous: it matches ${[...new Set(sources)].map((s) => `"${s}"`).join(" and ")}`;
+/**
+ * The rule a step's keyword picks among those registered with the expression it matched:
+ * Cucumber matches the text alone, so one expression can be both a `Given` and a `Then`.
+ */
+function ruleFor(built, expression, pickle) {
+    const kind = pickle.type && KINDS[pickle.type];
+    if (!kind)
+        throw new Error(`"${pickle.text}" needs a Given, When or Then before it`);
+    const rules = built.byExpression.get(expression).filter((r) => r.kind === kind || r.kind === "any");
+    if (rules.length === 0)
+        throw new Error(noMatch(built, pickle.text));
+    if (rules.length > 1)
+        throw new Error(ambiguous(pickle.text, rules.map((r) => r.source)));
+    return rules[0];
+}
+/** Each scenario of a run, before its first step: one name always makes up the same values. */
+function seedNames(report, pickle) {
+    const name = namesOf(report).get(pickle.id) ?? pickle.name;
+    seedFrom(name);
+    return name;
+}
+/** A World for compiling: each step records what it says into its scenario's spec, in `specs`. */
+function compileWorld(built, specs) {
+    return (report) => {
+        let spec;
+        return {
+            begin(pickle) {
+                spec = { name: seedNames(report, pickle), steps: [], given: [], input: undefined, decisions: [], expect: [] };
+                specs.set(pickle.id, spec);
+            },
+            step(expression, args, pickle) {
+                const rule = ruleFor(built, expression, pickle);
+                const { text } = pickle;
+                const step = { text, kind: KINDS[pickle.type] };
+                switch (rule.kind) {
+                    case "given": {
+                        const items = rule.read(args, pickle);
+                        spec.given.push(...items.map((item) => ({ step: text, ...item })));
+                        const [first] = items;
+                        if (first && "op" in first)
+                            step.op = first.op;
+                        if (items.some((i) => "fault" in i))
+                            step.fault = true;
+                        break;
+                    }
+                    case "then": {
+                        const { expect } = rule.read(args, pickle, spec.workflow);
+                        spec.expect.push({ step: text, ...expect });
+                        if ("op" in expect && expect.op !== undefined)
+                            step.op = expect.op;
+                        if ("name" in expect)
+                            step.name = expect.name;
+                        if ("called" in expect && expect.called !== undefined)
+                            step.called = expect.called;
+                        if ("times" in expect)
+                            step.called = expect.times > 0;
+                        if ("decision" in expect)
+                            step.decision = expect.decision;
+                        break;
+                    }
+                    case "any":
+                        spec.decisions.push({ step: text, ...rule.read(args, pickle) });
+                        break;
+                    case "when": {
+                        if (spec.workflow !== undefined)
+                            throw new Error("a second When: a scenario runs its workflow once");
+                        const item = rule.read(args, pickle);
+                        if ("call" in item) {
+                            throw new Error(`"${text}" calls ${item.call} directly: a step for an operation's own test, in its connector's features`);
+                        }
+                        Object.assign(spec, item);
+                    }
+                }
+                spec.steps.push(step);
+            },
+        };
+    };
+}
+/**
+ * A World for checking a run: each `Then` step judges the run on its own, and records its
+ * verdict (why it does not hold, or undefined) in `verdicts`, by its pickle step's id, rather
+ * than failing, so every `Then` runs. The other steps do nothing.
+ */
+function checkWorld(built, workflow, view, verdicts) {
+    return (report) => ({
+        begin(pickle) {
+            seedNames(report, pickle);
+        },
+        step(expression, args, pickle) {
+            const rule = ruleFor(built, expression, pickle);
+            if (rule.kind !== "then")
+                return;
+            const { verify } = rule.read(args, pickle, workflow);
+            let detail;
+            try {
+                detail = verify(view);
+            }
+            catch (err) {
+                if (isBug(err))
+                    throw err;
+                detail = errorMessage(err);
+            }
+            verdicts.set(pickle.id, detail);
+        },
+    });
+}
+/**
+ * A World for an operation's own test: `Given` steps seed through the target, `When` steps call
+ * its operations directly (no worker, no policy), and `Then` steps fail when they do not hold.
+ */
+function testWorld(built, { driver, fake }) {
+    return (report) => {
+        // What the steps named (`as`), and the calls made, as a run's ledger would hold them.
+        const values = new Map();
+        const records = [];
+        let runId = "";
+        /** A record of the test, as a run's ledger would hold it. */
+        const record = (body) => {
+            const seq = records.length;
+            const at = Date.now();
+            const common = { v: 1, app: "test", runId, seq, at, actor: { id: "test" }, workflow: "" };
+            records.push({ ...common, id: `${runId}:${body.type}:${seq}`, ...body });
+        };
+        /** Calls an operation on the target, as the runtime would: the input parsed by its schema. */
+        const call = (id, given) => {
+            const op = built.scope.ops.get(id);
+            const input = op.input.parse(resolve(given, values));
+            const fn = driver.ops[`${op.resource}.${op.name}`];
+            if (!fn)
+                throw new Error(`the driver under test does not implement ${id}`);
+            const context = { idempotencyKey: `${runId}:${records.length}`, runId, opId: id, attempt: 1 };
+            return { op, input, output: () => fn(input, context) };
+        };
+        return {
+            begin(pickle) {
+                runId = pickle.id;
+                seedNames(report, pickle);
+            },
+            async step(expression, args, pickle) {
+                const rule = ruleFor(built, expression, pickle);
+                const { text } = pickle;
+                switch (rule.kind) {
+                    case "given": {
+                        const seeds = [];
+                        for (const item of rule.read(args, pickle)) {
+                            if ("resource" in item)
+                                throw new Error(`"${text}" seeds a resource: a step for a sandbox run`);
+                            if ("fault" in item) {
+                                if (!fake)
+                                    throw new Error(`"${text}" injects a fault, which only a fake can`);
+                                fake[item.fault](item.op);
+                                continue;
+                            }
+                            const made = call(item.op, item.input);
+                            const output = await made.output();
+                            if (item.as !== undefined)
+                                values.set(item.as, output);
+                            seeds.push({ op: item.op, input: made.input, output });
+                        }
+                        if (seeds.length)
+                            record({ type: "scenario.seeded", scenario: "", seeds });
+                        return;
+                    }
+                    case "when": {
+                        const item = rule.read(args, pickle);
+                        if ("workflow" in item) {
+                            throw new Error(`"${text}" runs a workflow: a step for a scenario in scenarios/, not an operation's own test`);
+                        }
+                        const made = call(item.call, item.input);
+                        const started = Date.now();
+                        const result = await made.output().then((output) => ({ output }), (err) => {
+                            if (isBug(err))
+                                throw err;
+                            return { error: errorInfo(err) };
+                        });
+                        const { op, input } = made;
+                        const durationMs = Date.now() - started;
+                        record({
+                            type: "op.called",
+                            op: op.id,
+                            effect: op.effect,
+                            input,
+                            decision: { kind: "allow" },
+                            durationMs,
+                            ...result,
+                        });
+                        return;
+                    }
+                    case "any":
+                        throw new Error(`"${text}" decides an approval: a step for a scenario in scenarios/, not an operation's own test`);
+                    case "then": {
+                        const detail = rule.read(args, pickle).verify(viewOf(records));
+                        if (detail !== undefined)
+                            throw new Error(detail);
+                    }
+                }
+            },
+        };
+    };
+}
+/**
+ * The value with each string `$name` or `$name.field.field` replaced by what `values` holds
+ * under that name (an output a `Given` named with `as`), at any depth.
+ */
+function resolve(value, values) {
+    if (typeof value === "string") {
+        const ref = /^\$([A-Za-z_][\w-]*)((?:\.[\w-]+)*)$/.exec(value);
+        if (!ref)
+            return value;
+        const [, name, path] = ref;
+        if (!values.has(name)) {
+            const named = values.size ? `; the steps named ${[...values.keys()].join(", ")}` : "";
+            throw new Error(`no value named "${name}" for ${value}${named}`);
+        }
+        return path
+            .split(".")
+            .slice(1)
+            .reduce((v, key) => v?.[key], values.get(name));
+    }
+    if (Array.isArray(value))
+        return value.map((v) => resolve(v, values));
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolve(v, values)]));
+    }
+    return value;
+}
+/** A step's `file:line`. */
+const whereOf = (report, file, step) => `${file}:${report.query.findStepBy(step)?.location.line ?? 1}`;
+/**
+ * Why a step that did not pass did not, at `where`: the error it failed with, no step matching
+ * it (with the steps there are), or more than one; undefined for a step that passed or did not run.
+ */
+function stepError(built, result, step, where) {
+    if (!result)
+        return undefined;
+    switch (result.status) {
+        case StepStatus.PASSED:
+        case StepStatus.SKIPPED:
+            return undefined;
+        case StepStatus.UNDEFINED:
+            return step.type && KINDS[step.type]
+                ? `${where}: ${noMatch(built, step.text)}`
+                : `${where}: "${step.text}" needs a Given, When or Then before it`;
+        case StepStatus.AMBIGUOUS:
+            return `${where}: ${ambiguous(step.text, result.matches.flatMap((e) => built.byExpression.get(e).map((r) => r.source)))}`;
+        default:
+            return `${where}: ${result.message ?? `the step ended ${result.status}`}`;
+    }
+}
+/** The `.feature` files under `dir`, relative to it, with `/` between directories, in order. */
+function featureFiles(dir) {
+    return readdirSync(dir, { recursive: true, encoding: "utf8" })
+        .filter((f) => f.endsWith(".feature"))
+        .map((f) => f.replaceAll("\\", "/"))
+        .toSorted();
+}
+/** A parse error, as a file's error: `file:line: message`. */
+const parseErrorOf = ({ uri, line, message }) => `${uri}${line === undefined ? "" : `:${line}`}: ${message}`;
+/**
+ * Compiles the feature files `files` (relative to `dir`) into scenarios: Cucumber runs each,
+ * and its steps record what they say. A file with an error has none of its scenarios: the
+ * first error in it (a step that fails or matches no step or two, a scenario with no `When`,
+ * a name used twice, a file Gherkin cannot parse, no scenarios at all) is its error.
+ */
+async function compile(scope, dir, files) {
+    const built = builtFor(scope);
+    const errors = new Map();
+    const specs = new Map();
+    let report;
+    let left = files;
+    // A file Gherkin cannot parse stops the whole run: it is left out, and the rest run again.
+    while (left.length) {
+        report = await runFeatures(built.library, compileWorld(built, specs), { cwd: dir, files: left, isBug });
+        if (report.parseErrors.length === 0)
+            break;
+        for (const error of report.parseErrors) {
+            if (!errors.has(error.uri))
+                errors.set(error.uri, parseErrorOf(error));
+        }
+        const rest = left.filter((f) => !errors.has(f));
+        // An error of no file left: give it to every file, rather than run them again forever.
+        if (rest.length === left.length) {
+            for (const f of left)
+                errors.set(f, report.parseErrors.map(parseErrorOf).join("; "));
+        }
+        left = rest.length === left.length ? [] : rest;
+        report = undefined;
+    }
+    const scenarios = [];
+    if (report) {
+        const { query } = report;
+        const names = namesOf(report);
+        const results = stepResults(report);
+        const pickles = Map.groupBy(query.findAllPickles(), (p) => p.uri);
+        for (const file of files) {
+            if (errors.has(file))
+                continue;
+            const inFile = [];
+            try {
+                const list = pickles.get(file) ?? [];
+                if (list.length === 0)
+                    throw new Error(`${file}: no scenarios; add one with "Scenario: <name>"`);
+                for (const pickle of list) {
+                    const line = lineOf(report, pickle);
+                    const scenario = query.findLineageBy(pickle).scenario;
+                    const where = `${file}:${scenario.location.line}`;
+                    for (const step of pickle.steps) {
+                        const error = stepError(built, results.get(step.id), step, whereOf(report, file, step));
+                        if (error)
+                            throw new Error(error);
+                    }
+                    const { workflow, ...spec } = specs.get(pickle.id);
+                    const name = names.get(pickle.id);
+                    if (inFile.some((s) => s.name === name)) {
+                        throw new Error(`${where}: a second scenario named "${name}"; give each its own name`);
+                    }
+                    if (workflow === undefined) {
+                        throw new Error(`${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`);
+                    }
+                    const drift = spec.expect.find((e) => "declared" in e);
+                    if (drift && workflow !== DRIFT_WORKFLOW) {
+                        throw new Error(`${where}: "${drift.step}" reads a drift report, so the scenario must run ${DRIFT_WORKFLOW}, not ${workflow}`);
+                    }
+                    inFile.push({
+                        ...spec,
+                        name,
+                        file,
+                        line,
+                        workflow,
+                        text: textOf(scenario, report.texts.get(file) ?? ""),
+                        approvals: approvalsOf(scope.workflows.get(workflow)),
+                    });
+                }
+            }
+            catch (err) {
+                if (isBug(err))
+                    throw err;
+                errors.set(file, errorMessage(err));
+                continue;
+            }
+            scenarios.push(...inFile);
+        }
+    }
+    // Each file's error, in the files' order, and the scenarios of the rest, one name each across files.
+    const loaded = { scenarios: [], errors: [] };
+    const seen = new Map();
+    for (const file of files) {
+        const error = errors.get(file);
+        if (error !== undefined) {
+            loaded.errors.push({ file, message: error });
+            continue;
+        }
+        for (const s of scenarios.filter((x) => x.file === file)) {
+            const other = seen.get(s.name);
+            if (other !== undefined) {
+                loaded.errors.push({
+                    file,
+                    message: `${file}: scenario "${s.name}" is also in ${other}; give each its own name`,
+                });
+                continue;
+            }
+            seen.set(s.name, file);
+            loaded.scenarios.push(s);
+        }
+    }
+    return loaded;
+}
+/**
+ * Each scope's scenarios as last read, with the stamp of the files they were read from. By
+ * scope, since what a file means depends on its operations and workflows.
+ */
+const loadedByScope = new WeakMap();
+/**
+ * Every scenario in the `.feature` files under `scenarios` (a `file:` URL to a directory),
+ * compiled by Cucumber, with an error for each file that does not compile and each name used
+ * twice. No directory, or none given, is no scenarios. Rejects when an operation's phrase names
+ * a field it lacks. The files are compiled again only once one is added, removed or written
+ * (its name, `mtimeMs` or size changes): until then each call returns the same object, which
+ * callers must not change.
+ */
+export async function loadScenarios(scope) {
+    if (!scope.scenarios)
+        return { scenarios: [], errors: [] };
+    const dir = fileURLToPath(scope.scenarios);
+    if (!existsSync(dir))
+        return { scenarios: [], errors: [] };
+    // Built first, so a phrase naming a field its input lacks rejects even with no feature files.
+    builtFor(scope);
+    const files = featureFiles(dir);
+    const stamp = JSON.stringify([
+        dir,
+        files.map((file) => {
+            const { mtimeMs, size } = statSync(join(dir, file));
+            return [file, mtimeMs, size];
+        }),
+    ]);
+    const cached = loadedByScope.get(scope);
+    if (cached?.stamp === stamp)
+        return cached.loaded;
+    const loaded = files.length ? compile(scope, dir, files) : Promise.resolve({ scenarios: [], errors: [] });
+    loadedByScope.set(scope, { stamp, loaded });
+    // A compile that throws (a bug) is not kept: the next call tries again.
+    loaded.catch(() => {
+        if (loadedByScope.get(scope)?.loaded === loaded)
+            loadedByScope.delete(scope);
+    });
+    return loaded;
+}
+/**
+ * Checks a run's ledger records against the scenario, as its feature file reads now: Cucumber
+ * runs the scenario's `Then` steps, each judging the run on its own, and the rest of its steps
+ * do nothing. One check per expectation (`scenario.expect`), in order, a step that does not hold
+ * with why as its `detail`. Rejects when the scenario no longer compiles as it did (a step the
+ * file no longer matches, say): load the scenarios again first, as the app does.
+ */
+export async function check(scope, scenario, records) {
+    if (!scope.scenarios)
+        throw new Error(`No scenarios directory to check scenario "${scenario.name}" from`);
+    const built = builtFor(scope);
+    const { file, line, name } = scenario;
+    const verdicts = new Map();
+    const report = await runFeatures(built.library, checkWorld(built, scenario.workflow, viewOf(records), verdicts), {
+        cwd: fileURLToPath(scope.scenarios),
+        files: [file],
+        line,
+        isBug,
+    });
+    const where = `${file}:${line}`;
+    if (report.parseErrors.length)
+        throw new Error(`${where}: ${report.parseErrors.map((e) => e.message).join("; ")}`);
+    const names = namesOf(report);
+    const pickle = report.query
+        .findAllPickles()
+        .find((p) => p.uri === file && lineOf(report, p) === line && names.get(p.id) === name);
+    if (!pickle)
+        throw new Error(`${where}: no scenario "${name}" there now`);
+    const results = stepResults(report);
+    const checks = [];
+    for (const step of pickle.steps) {
+        const expectation = scenario.expect[checks.length];
+        // Only a `Then` step expects: a `Given` can read the same as one (`{op} was called with`).
+        if (expectation?.step === step.text && KINDS[step.type] === "then" && verdicts.has(step.id)) {
+            checks.push(verdict(step.text, verdicts.get(step.id)));
+            continue;
+        }
+        const error = stepError(built, results.get(step.id), step, whereOf(report, file, step));
+        if (error)
+            throw new Error(error);
+    }
+    if (checks.length !== scenario.expect.length) {
+        throw new Error(`${where}: scenario "${name}" no longer has the expectations it was read with`);
+    }
+    return checks;
+}
+/**
+ * The scenarios of the `.feature` files under `dir` (a `file:` URL to a directory), in order,
+ * named as `loadScenarios` names them, from a dry run: what a test runner lists before it runs
+ * each (`testFeature`). Rejects, naming the file, for one Gherkin cannot parse.
+ */
+export async function featureScenarios(scope, dir) {
+    const cwd = fileURLToPath(dir);
+    const report = await runFeatures(builtFor(scope).library, () => ({ begin() { }, step() { } }), {
+        cwd,
+        files: featureFiles(cwd),
+        dryRun: true,
+        isBug,
+    });
+    if (report.parseErrors.length)
+        throw new Error(report.parseErrors.map(parseErrorOf).join("\n"));
+    const names = namesOf(report);
+    return report.query.findAllPickles().map((pickle) => ({
+        file: pickle.uri,
+        line: lineOf(report, pickle),
+        name: names.get(pickle.id),
+        tags: pickle.tags.map((t) => t.name),
+    }));
+}
+/**
+ * Runs the scenario at `line` of the feature file `file` (absolute) as an operation's own test,
+ * on the target: its `Given` steps seed through it, its `When` steps call its operations directly
+ * (no worker, no policy), and its `Then` steps check those calls. Rejects with its first step
+ * that did not pass, at `file:line`.
+ */
+export async function testFeature(scope, file, line, target) {
+    const built = builtFor(scope);
+    const name = basename(file);
+    const report = await runFeatures(built.library, testWorld(built, target), {
+        cwd: dirname(file),
+        files: [name],
+        line,
+        isBug,
+    });
+    if (report.parseErrors.length)
+        throw new Error(report.parseErrors.map(parseErrorOf).join("\n"));
+    const results = stepResults(report);
+    for (const pickle of report.query.findAllPickles()) {
+        for (const step of pickle.steps) {
+            const error = stepError(built, results.get(step.id), step, whereOf(report, name, step));
+            if (error)
+                throw new Error(error);
+        }
+    }
+}
+/**
+ * Decides the run's approvals as the scenario says until the run ends, and returns how it
+ * ended. Each pending approval takes the decision naming its title (or id), else the next one
+ * left that names no approval of the run (one it has asked for, or one its code names). Throws
+ * for an approval with no such decision, and `run_running` when the run has not ended within
+ * `timeoutMs` or the worker has not read a decision by then.
+ */
+export async function drive(client, runId, scenario, { timeoutMs = 15_000 } = {}) {
+    const left = [...scenario.decisions];
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const run = await client.run(runId);
+        if (!run)
+            throw new SanomaError("run_not_found", `No run ${runId}`, { runId });
+        if (isEnded(run.status))
+            return run;
+        const names = new Set([...scenario.approvals, ...run.approvals.flatMap((a) => [a.title, a.id])]);
+        for (const approval of run.approvals.filter((a) => a.status === "pending")) {
+            const named = left.findIndex((d) => d.approval === approval.title || d.approval === approval.id);
+            const next = named === -1 ? left.findIndex((d) => !names.has(d.approval)) : named;
+            if (next === -1) {
+                const which = left.length
+                    ? `; the decisions left are for ${left.map((d) => `"${d.approval}"`).join(", ")}`
+                    : "";
+                throw new Error(`Scenario "${scenario.name}" has no decision for "${approval.title}" (${approval.id})${which}`);
+            }
+            const [d] = left.splice(next, 1);
+            const note = d.note === undefined ? {} : { note: d.note };
+            const timeoutSeconds = Math.max(1, Math.ceil((deadline - Date.now()) / 1000));
+            const decided = await client.decide(runId, { decision: d.decision, by: { id: d.by }, ...note }, approval.id, {
+                timeoutSeconds,
+            });
+            if (decided.status === "pending") {
+                throw new SanomaError("run_running", `The worker did not read the decision for "${approval.title}" (${approval.id}) of run ${runId} within ${timeoutMs} ms`, { runId, approvalId: approval.id, timeoutMs });
+            }
+        }
+        if (Date.now() > deadline) {
+            throw new SanomaError("run_running", `Run ${runId} is still running after ${timeoutMs} ms`, {
+                runId,
+                timeoutMs,
+            });
+        }
+        await delay(100);
+    }
+}
+//# sourceMappingURL=scenario.js.map