@sanoma-ai/workflows 0.5.0 → 0.7.0

package/dist/sandbox.js

@@ -53,16 +53,54 @@ export function seedResource(scenario, copy, given) {
         throw new SanomaError("invalid_input", `Scenario "${scenario}" cannot seed ${resource} "${name}" ("${given.step}"): ${errorMessage(err)}`, { scenario, step: given.step, resource, name }, { cause: err });
     }
 }
+/**
+ * Applies the scenario's `Given` steps to the target: calls each operation through its drivers,
+ * puts or removes each resource in its vendor's fake, then, for a `run`, injects the faults.
+ * Checks first that every operation it seeds has a driver there, that every resource's vendor has
+ * a fake holding resources, and, for an `instance`, that it injects no fault. Returns what it
+ * seeded, in order.
+ */
+export async function applyGivens(scenario, target) {
+    const { name, given } = scenario;
+    const fault = given.find((g) => "fault" in g);
+    if (fault && target.kind === "instance") {
+        throw new SanomaError("invalid_input", `Scenario "${name}" injects a fault ("${fault.step}"), but its Givens go to the instance, whose fakes every run shares`, { scenario: name, step: fault.step });
+    }
+    const missing = [...new Set(given.flatMap((g) => ("op" in g && !target.drivers.has(g.op) ? [g.op] : [])))];
+    if (missing.length) {
+        throw new SanomaError("invalid_input", `Scenario "${name}" seeds ${missing.join(", ")}, but no fake its connectors attach implements ${missing.length > 1 ? "them" : "it"}`, { scenario: name, missing });
+    }
+    const plain = missingResourceFake(scenario, target.fakes);
+    if (plain)
+        throw plain;
+    const seeded = [];
+    for (const [i, g] of given.entries()) {
+        if ("fault" in g)
+            continue;
+        if ("op" in g) {
+            const output = await target.drivers.get(g.op)(g.input, target.call(i, g.op));
+            seeded.push({ op: g.op, input: g.input, output });
+            continue;
+        }
+        // Checked above: the vendor's fake holds resources.
+        seeded.push(seedResource(name, target.fakes.get(g.vendor), g));
+    }
+    for (const g of given) {
+        if ("fault" in g)
+            target.fakes.get(target.ops.get(g.op).vendor)[g.fault](g.op);
+    }
+    return seeded;
+}
 /**
  * Seeds a sandbox run of the scenario `name`, from the worker, in one step: reads the scenario,
- * checks that it runs this workflow, makes the run's own fakes (each vendor's maker, called once
- * for the run), checks that every operation the workflow uses or the scenario seeds has one and
- * that every resource it seeds has a fake holding resources, calls each `Given` operation
- * through them, puts or removes each `Given` resource in them, injects the faults into them,
- * then puts their functions on the run. The run then calls those only, so sandbox runs share no
- * state when the makers make a new fake each. The step's checkpoint never stands in for them: a
- * run whose seeding is replayed from it has none, and fails, since a sandbox run does not
- * survive a worker restart.
+ * checks that it runs this workflow, picks the run's fakes, checks that every operation the
+ * workflow uses has one, then applies the scenario's `Given` steps to them
+ * (`applyGivens`) and puts their functions on the run. The run then calls those only. Its fakes
+ * are its own (each vendor's maker, called once for the run), so sandbox runs share no state when
+ * the makers make a new fake each; on an instance that runs on fakes (`instanceFakes`) they are
+ * the instance's, which its sandbox runs share, as its live drivers are. The step's checkpoint
+ * never stands in for a run's own: a run whose seeding is replayed from it has none, and fails,
+ * since a sandbox run does not survive a worker restart; on an instance's fakes it goes on with them.
  */
 export async function seedSandbox(run, name) {
     const { state } = run;
@@ -78,42 +116,35 @@ export async function seedSandbox(run, name) {
             throw new SanomaError("invalid_input", `No scenario named "${name}"${why}`, { scenario: name });
         }
         if (scenario.workflow !== run.workflow) {
-            throw new SanomaError("invalid_input", `Scenario "${name}" runs ${scenario.workflow}, not ${run.workflow}`, {
+            const runs = scenario.workflow === undefined ? "is a world, which runs nothing" : `runs ${scenario.workflow}`;
+            throw new SanomaError("invalid_input", `Scenario "${name}" ${runs}, not ${run.workflow}`, {
                 scenario: name,
-                workflow: scenario.workflow,
+                ...(scenario.workflow !== undefined && { workflow: scenario.workflow }),
             });
         }
-        const fakes = new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
-        const drivers = indexDrivers([...fakes.values()].map((f) => f.driver), state.ops);
-        const uses = opIdsOf(state.workflows.get(run.workflow));
-        const seeding = scenario.given.flatMap((g) => ("op" in g ? [g.op] : []));
-        const missing = [...new Set([...uses, ...seeding])].filter((id) => !drivers.has(id));
+        const instance = state.instanceFakes;
+        const fakes = instance ?? new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
+        const drivers = instance
+            ? state.drivers
+            : indexDrivers([...fakes.values()].map((f) => f.driver), state.ops);
+        // What the scenario seeds is checked by `applyGivens`.
+        const missing = opIdsOf(state.workflows.get(run.workflow)).filter((id) => !drivers.has(id));
         if (missing.length) {
             throw new SanomaError("invalid_input", `A sandbox run of ${run.workflow} has no fake for ${missing.join(", ")}: no fake its connectors attach implements ${missing.length > 1 ? "them" : "it"}`, { scenario: name, missing });
         }
-        const plain = missingResourceFake(scenario, fakes);
-        if (plain)
-            throw plain;
-        const seeded = [];
-        for (const [i, given] of scenario.given.entries()) {
-            if ("fault" in given)
-                continue;
-            if ("op" in given) {
-                const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1, secrets };
-                const output = await drivers.get(given.op)(given.input, call);
-                seeded.push({ op: given.op, input: given.input, output });
-                continue;
-            }
-            // Checked above: the vendor's fake holds resources.
-            seeded.push(seedResource(name, fakes.get(given.vendor), given));
-        }
-        for (const given of scenario.given) {
-            if ("fault" in given)
-                fakes.get(state.ops.get(given.op).vendor)[given.fault](given.op);
-        }
+        const seeded = await applyGivens(scenario, {
+            kind: instance ? "instance" : "run",
+            drivers,
+            fakes,
+            ops: state.ops,
+            call: (i, opId) => ({ idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId, attempt: 1, secrets }),
+        });
         copies = drivers;
         return { seeds: seeded };
     }, { name: "sandbox:seed" });
+    // Replayed on an instance that runs on fakes: they are the instance's, still there in this process.
+    if (!copies && state.instanceFakes)
+        copies = state.drivers;
     if (!copies) {
         // Replayed from its checkpoint (after a worker restart, or in a fork), so the run has no fakes.
         // The records written before the restart hold the seqs from here on: the failure goes after them.

package/dist/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}

package/dist/scenario.d.ts

@@ -129,7 +129,19 @@ export interface Scenario {
     file: string;
     /** Its line in the file: its keyword's, or for an outline's row, the row's. */
     line: number;
-    workflow: string;
+    /**
+     * The workflow its `When` runs. Absent for a scenario with no `When`, a *world*: its `Given`
+     * steps alone, which a demo applies to the instance (`applyGivens`) and nothing runs or checks.
+     */
+    workflow?: string;
+    /** Its tags, as written (`@slow`), the feature's and its own. */
+    tags: string[];
+    /**
+     * When it is tagged `@moment(<person>,<path>)` (no space: a Gherkin tag has none): a moment,
+     * which a demo starts as a sandbox run by `person`, a declared person, and leaves waiting, for
+     * a visitor signed in as them to land on at `path`.
+     */
+    moment?: Moment;
     /**
      * The scenario's own lines of its feature file, for display: from its keyword line to the end
      * of its last step (a step's doc string or table included, and an outline's examples), less
@@ -151,6 +163,11 @@ export interface Scenario {
     approvals: string[];
     expect: Expectation[];
 }
+/** A moment's visitor and where they land: `@moment(<person>,<path>)`. */
+export interface Moment {
+    person: string;
+    path: string;
+}
 /** The result of one expectation against a run's ledger. */
 export interface Check {
     step: string;

package/dist/scenario.js

@@ -150,6 +150,23 @@ function builtFor(scope) {
 /** The built-in workflows, whose input is never made up: each field is optional, and left out unless given. */
 /** 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) });
+/**
+ * `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. The
+ * people are the root's data files' (`readPeople`, read again only once a file changed): while
+ * they declare no one, any id goes.
+ */
+function actorNamed(scope, who) {
+    const declared = readPeople(scope.root);
+    try {
+        return admit({ id: who }, declared).id;
+    }
+    catch (err) {
+        if (errorCode(err) !== "not_admitted" || declared.problems.length)
+            throw err;
+        const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
+        throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
+    }
+}
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope) {
     const { types, collections } = scope;
@@ -172,22 +189,10 @@ function rulesOf(scope) {
     ];
     const opOf = (id) => scope.ops.get(id);
     const workflowOf = (name) => scope.workflows.get(name);
-    // The people as the root's data files declare them when a step names one (`readPeople`, read
-    // again only once a file changed): while they declare no one, any id and any group go.
-    /** `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. */
-    const actorNamed = (who) => {
-        const declared = readPeople(scope.root);
-        try {
-            return admit({ id: who }, declared).id;
-        }
-        catch (err) {
-            if (errorCode(err) !== "not_admitted" || declared.problems.length)
-                throw err;
-            const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
-            throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
-        }
-    };
-    /** `group`, a declared group or `agents`, while the people's files have no problems. */
+    /**
+     * `group`, a declared group or `agents`, while the people's files have no problems (`readPeople`,
+     * read again only once a file changed): while they declare no one, any group goes.
+     */
     const groupNamed = (group) => {
         const { people, problems } = readPeople(scope.root);
         if (problems.length) {
@@ -204,7 +209,7 @@ function rulesOf(scope) {
         return { resource: id, vendor, type, name: name };
     };
     const rules = [
-        { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who) },
+        { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(scope, who) },
         // A visitor of a public site, as a login would vouch for one; `anonymous` is a `{who}`.
         { kind: "actor", source: "a visitor is acting", read: () => visitorPrincipal("scenario", "visitor").id },
         {
@@ -903,6 +908,29 @@ function stepError(built, result, step, where) {
             return `${where}: ${result.message ?? `the step ended ${result.status}`}`;
     }
 }
+/**
+ * The moment its tags make a scenario (`@moment(<person>,<path>)`), the person admitted as a run's
+ * starter is, or undefined for none; throws, at `where`, for a malformed one or a second.
+ */
+function momentOf(scope, tags, where) {
+    const tagged = tags.filter((t) => t === "@moment" || t.startsWith("@moment("));
+    if (tagged.length === 0)
+        return undefined;
+    if (tagged.length > 1)
+        throw new Error(`${where}: ${tagged.join(" and ")}: a moment has one person and one page`);
+    const [, person, path] = /^@moment\(([^,()]+),(\/[^()]*)\)$/.exec(tagged[0]) ?? [];
+    if (person === undefined || path === undefined) {
+        throw new Error(`${where}: ${tagged[0]} needs a person and a path, as in @moment(alex,/sites/portal/requests), with no space: a tag has none`);
+    }
+    try {
+        return { person: actorNamed(scope, person), path };
+    }
+    catch (err) {
+        if (isBug(err))
+            throw err;
+        throw new Error(`${where}: ${tagged[0]}: ${errorMessage(err)}`, { cause: err });
+    }
+}
 /** The `.feature` files under `dir`, relative to it, with `/` between directories, in order. */
 function featureFiles(dir) {
     return readdirSync(dir, { recursive: true, encoding: "utf8" })
@@ -914,8 +942,9 @@ function featureFiles(dir) {
 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`,
+ * and its steps record what they say. A file none of whose scenarios has a `When` is of worlds.
+ * 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` beside one with,
  * a name used twice, a file Gherkin cannot parse, no scenarios at all) is its error.
  */
 async function compile(scope, dir, files) {
@@ -956,6 +985,8 @@ async function compile(scope, dir, files) {
                 const list = pickles.get(file) ?? [];
                 if (list.length === 0)
                     throw new Error(`${file}: no scenarios; add one with "Scenario: <name>"`);
+                // A feature none of whose scenarios has a When is of worlds; elsewhere a missing When is a mistake.
+                const ofWorlds = list.every((p) => specs.get(p.id).workflow === undefined);
                 for (const pickle of list) {
                     const line = lineOf(report, pickle);
                     const scenario = query.findLineageBy(pickle).scenario;
@@ -965,13 +996,32 @@ async function compile(scope, dir, files) {
                         if (error)
                             throw new Error(error);
                     }
-                    const { workflow, ...spec } = specs.get(pickle.id);
+                    const spec = specs.get(pickle.id);
+                    const { workflow } = spec;
                     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`);
                     }
+                    const tags = pickle.tags.map((t) => t.name);
+                    const moment = momentOf(scope, tags, where);
+                    const common = { name, file, line, tags, text: textOf(scenario, report.texts.get(file) ?? "") };
+                    if (workflow === undefined && !ofWorlds) {
+                        throw new Error(`${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with" (a feature with no When in any scenario is of worlds)`);
+                    }
                     if (workflow === undefined) {
-                        throw new Error(`${where}: scenario "${name}" has no When: say which workflow runs, such as "When <workflow> runs with"`);
+                        // A world: its Givens alone, which nothing runs or checks.
+                        const runs = moment
+                            ? "is a moment, which starts a run"
+                            : spec.expect[0]
+                                ? `checks a run ("${spec.expect[0].step}")`
+                                : spec.decisions[0]
+                                    ? `decides an approval ("${spec.decisions[0].step}")`
+                                    : undefined;
+                        if (runs) {
+                            throw new Error(`${where}: scenario "${name}" has no When, so it is a world, Givens only, but it ${runs}: say which workflow runs, such as "When <workflow> runs with"`);
+                        }
+                        inFile.push({ ...spec, ...common, approvals: [] });
+                        continue;
                     }
                     // A step about a declared resource reads the report of the built-in it is about.
                     for (const e of spec.expect) {
@@ -982,11 +1032,9 @@ async function compile(scope, dir, files) {
                     }
                     inFile.push({
                         ...spec,
-                        name,
-                        file,
-                        line,
+                        ...common,
                         workflow,
-                        text: textOf(scenario, report.texts.get(file) ?? ""),
+                        ...(moment && { moment }),
                         approvals: approvalsOf(scope.workflows.get(workflow)),
                     });
                 }
@@ -1078,10 +1126,12 @@ export async function loadScenarios(scope) {
 export async function check(scope, scenario, records) {
     if (!scope.scenarios)
         throw new Error(`No scenarios directory to check scenario "${scenario.name}" from`);
+    const { file, line, name, workflow } = scenario;
+    if (workflow === undefined)
+        throw new Error(`Scenario "${name}" is a world: it runs nothing to check`);
     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), {
+    const report = await runFeatures(built.library, checkWorld(built, workflow, viewOf(records), verdicts), {
         cwd: fileURLToPath(scope.scenarios),
         files: [file],
         line,