@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,87 @@
+import type { ApprovalState, Principal, WorkflowDefinition } from "./define.ts";
+import type { Fake } from "./fake.ts";
+import type { LedgerStore } from "./ledger.ts";
+import type { DriverFn, Op } from "./op.ts";
+import type { CallNode } from "./outline.ts";
+import type { Policy } from "./policy.ts";
+import type { Resource } from "./resource.ts";
+import type { Steps } from "./steps.ts";
+/** What the DBOS workflow receives: the workflow's input, who started the run, and for a sandbox run its scenario. */
+export interface RunArgs {
+    input: unknown;
+    startedBy: Principal;
+    /** The scenario a sandbox run is seeded from; the run calls the fakes instead of the drivers. */
+    sandbox?: string;
+}
+/**
+ * What one `startWorker` call runs with. DBOS registrations are process-wide and outlive a
+ * shutdown, so each run takes the state current when it starts and keeps it: a run left over
+ * from a stopped worker never reads a newer worker's drivers or policy.
+ */
+export interface WorkerState {
+    /** The config's `appName`, recorded on every ledger record. */
+    app: string;
+    /** The operations as the config's connectors declare them, by id. */
+    ops: Map<string, Op>;
+    /** The drivers' functions, by operation id, each guarded by its driver's `env` (`indexDrivers` in config.ts). */
+    drivers: Map<string, DriverFn>;
+    /** The makers of the config's fake vendors, by vendor id: a sandbox run makes its own of each when it is seeded. */
+    fakes: Map<string, () => Fake<any, any>>;
+    /** Where sandbox runs' scenarios are, the resource types their steps may name, and the steps the connectors ship. */
+    scenarios?: URL;
+    types: ReadonlyMap<string, Resource>;
+    steps: readonly Steps[];
+    /** Its `version`, when it has one, is recorded with each of its decisions. */
+    policy: Policy;
+    ledger: LedgerStore;
+    /**
+     * The config's workflows by name, the built-in `drift` among them. A run takes its definition
+     * from here, by the name it was registered under: a process registers each name with DBOS once,
+     * and each worker's config says what it runs. Scenarios name them too.
+     */
+    workflows: Map<string, WorkflowDefinition<any, any>>;
+    /** Each workflow's outline, by name: read once when the worker starts, every run is held to it (`call_not_in_outline`). */
+    outlines: Map<string, WorkflowOutline>;
+    /**
+     * Set when the worker stops, before DBOS shuts down. DBOS abandons a stopped worker's run
+     * functions, which then fail as their next DBOS call finds the database closed. Such a failure,
+     * one with none of our codes, is not recorded: the run recovered on the next worker records
+     * how it really ends (see `isInfrastructureError`).
+     */
+    stopped: boolean;
+}
+/** What a run keeps in memory. Rebuilt the same way when DBOS replays the run. */
+export interface Run {
+    id: string;
+    workflow: string;
+    actor: Principal;
+    /** The scenario a sandbox run is seeded from; unset for a live run. */
+    sandbox?: string;
+    /** A sandbox run's own fakes' functions, by operation id, from `seedSandbox`; unset for a live run. */
+    fakeDrivers?: Map<string, DriverFn>;
+    approvals: ApprovalState[];
+    /** The next ledger `seq`. Advanced only outside steps, so a replay counts the same way. */
+    seq: number;
+    /**
+     * The last `ctx` call queued. Each call waits for the one before it, so a run's calls run one
+     * at a time, in program order, even under `Promise.all`. Never rejects.
+     */
+    tail: Promise<unknown>;
+    /**
+     * Set while a `ctx.all` runs, so a second one started before it settles is refused. The
+     * member a call belongs to travels with the call (`currentGroup` in ledger.ts), not here.
+     */
+    inAll: boolean;
+    /** Set when the workflow body has returned or thrown. A call still queued then is refused. */
+    ended: boolean;
+    /** The workflow's outline, which every `ctx` call is placed in (`placeCall`). */
+    outline: WorkflowOutline;
+    state: WorkerState;
+}
+/** What `placeCall` holds a run's `ctx` calls to: the file's lines, so a frame's line and column become an offset, and the outline's call nodes. */
+export interface WorkflowOutline {
+    file: string;
+    /** `lineStartsOf` the file's text, `\n` line endings. */
+    lineStarts: readonly number[];
+    calls: readonly CallNode[];
+}

package/dist/run.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":""}

package/dist/sandbox.d.ts

@@ -0,0 +1,33 @@
+import { SanomaError } from "./errors.ts";
+import type { Fake, ResourceFake } from "./fake.ts";
+import { type LedgerRecord } from "./ledger.ts";
+import type { Run } from "./run.ts";
+import { type Given, type Scenario } from "./scenario.ts";
+/**
+ * The error a sandbox run of the scenario fails with when it seeds a resource of a vendor whose
+ * fake (one of `fakes`, by vendor) holds none, or whose connector attaches no fake; undefined
+ * when every vendor it seeds a resource of has a `ResourceFake`. Pure.
+ */
+export declare function missingResourceFake(scenario: Pick<Scenario, "name" | "given">, fakes: ReadonlyMap<string, Fake<unknown>>): SanomaError | undefined;
+/**
+ * Seeds one resource into the run's own fake of its vendor: put with its fields, or removed.
+ * A seed the fake refuses (a field the provider's shape lacks, say) fails the scenario, naming
+ * the step, as the other seed-time refusals do.
+ */
+export declare function seedResource(scenario: string, copy: ResourceFake, given: Extract<Given, {
+    resource: string;
+}>): Extract<LedgerRecord, {
+    type: "scenario.seeded";
+}>["seeds"][number];
+/**
+ * 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.
+ */
+export declare function seedSandbox(run: Run, name: string): Promise<void>;

package/dist/sandbox.js

@@ -0,0 +1,123 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { indexDrivers } from "./config.js";
+import { opIdsOf } from "./define.js";
+import { SanomaError } from "./errors.js";
+import { entry, write } from "./ledger.js";
+import { loadScenarios } from "./scenario.js";
+import { errorMessage } from "./shared.js";
+/*
+ * What a worker does for a sandbox run, imported only when it starts one: kept apart from
+ * `scenario.ts`, which the app reads too, because it needs DBOS and the ledger.
+ */
+/** True for a fake that holds resources (`ResourceFake`, as `@sanoma-ai/bridge`'s `tfFake` is). */
+const holdsResources = (fake) => "override" in fake && "put" in fake && "remove" in fake;
+/**
+ * The error a sandbox run of the scenario fails with when it seeds a resource of a vendor whose
+ * fake (one of `fakes`, by vendor) holds none, or whose connector attaches no fake; undefined
+ * when every vendor it seeds a resource of has a `ResourceFake`. Pure.
+ */
+export function missingResourceFake(scenario, fakes) {
+    const plain = scenario.given.filter((g) => {
+        if (!("resource" in g))
+            return false;
+        const fake = fakes.get(g.vendor);
+        return !fake || !holdsResources(fake);
+    });
+    if (plain.length === 0)
+        return undefined;
+    const resources = [...new Set(plain.map((g) => g.resource))];
+    const vendors = [...new Set(plain.map((g) => g.vendor))];
+    const why = vendors.map((v) => fakes.has(v) ? `${v}'s fake holds no resources (it is not a tfFake)` : `${v}'s connector attaches no fake`);
+    return new SanomaError("invalid_input", `Scenario "${scenario.name}" seeds ${resources.join(", ")}, but ${why.join("; ")}`, {
+        scenario: scenario.name,
+        resources,
+    });
+}
+/**
+ * Seeds one resource into the run's own fake of its vendor: put with its fields, or removed.
+ * A seed the fake refuses (a field the provider's shape lacks, say) fails the scenario, naming
+ * the step, as the other seed-time refusals do.
+ */
+export function seedResource(scenario, copy, given) {
+    const { resource, type, name } = given;
+    try {
+        if ("gone" in given) {
+            copy.remove(type, name);
+            return { resource, name, gone: true };
+        }
+        copy.put(type, name, given.fields);
+        return { resource, name, fields: given.fields };
+    }
+    catch (err) {
+        throw new SanomaError("invalid_input", `Scenario "${scenario}" cannot seed ${resource} "${name}" ("${given.step}"): ${errorMessage(err)}`, { scenario, step: given.step, resource, name }, { cause: err });
+    }
+}
+/**
+ * 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.
+ */
+export async function seedSandbox(run, name) {
+    const { state } = run;
+    let copies;
+    const { seeds } = await DBOS.runStep(async () => {
+        // Read in the step, so a recovered run never reads a feature file edited or renamed since.
+        const { scenarios, errors } = await loadScenarios(state);
+        const scenario = scenarios.find((s) => s.name === name);
+        if (!scenario) {
+            const why = errors.length ? `; these files did not load: ${errors.map((e) => e.message).join("; ")}` : "";
+            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}`, {
+                scenario: name,
+                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));
+        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 };
+                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);
+        }
+        copies = drivers;
+        return { seeds: seeded };
+    }, { name: "sandbox:seed" });
+    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.
+        run.seq = Math.max(run.seq, ...(await state.ledger.read(run.id)).map((r) => r.seq + 1));
+        throw new SanomaError("invalid_input", `Sandbox run ${run.id} was interrupted by a worker restart and the fakes' state is gone; start the scenario again`, { runId: run.id, scenario: name });
+    }
+    run.fakeDrivers = copies;
+    await write(run, entry(run, { type: "scenario.seeded", scenario: name, seeds }));
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

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

package/dist/scenario.d.ts

@@ -0,0 +1,212 @@
+import type { RunSummary, SanomaClient } from "./client.ts";
+import type { ResolvedConfig } from "./config.ts";
+import type { Fake } from "./fake.ts";
+import type { LedgerRecord } from "./ledger.ts";
+import type { Driver } from "./op.ts";
+import type { Seed } from "./steps.ts";
+/** One step of a scenario, as written, for a list and for marking the graph node it is about. */
+export interface ScenarioStep {
+    text: string;
+    kind: "given" | "when" | "then";
+    /** The operation the step is about, when it names one. */
+    op?: string;
+    /** For a `Then` step about a step by its name (`step "Draft the post" was called`): that name. */
+    name?: string;
+    /**
+     * For a `Then` step about an operation, or a step by its name: true when it expects a call (or
+     * a run), false for `was not called` (or `ran 0 times`).
+     */
+    called?: boolean;
+    /** For a `Then` step about the policy's decision on an operation: `was denied`, or `was held for`. */
+    decision?: "denied" | "held";
+    /** For a `Given` that injects a fault into the operation's next call (`fails once` and the like), rather than seeding it. */
+    fault?: true;
+}
+/**
+ * A fake's state to seed through one of its operations (`as` names what the call returns, for
+ * an operation's own test), a fault to inject into its next call, or an object a vendor's fake
+ * holds: `resource` is its type's id (`github.repository`, its `vendor` and `type`) and `name`
+ * its import id, with `fields` to set on it (put, when the vendor has none) or `gone` to remove it.
+ */
+export type Given = {
+    step: string;
+    op: string;
+    input: unknown;
+    as?: string;
+} | {
+    step: string;
+    op: string;
+    fault: Fault;
+} | {
+    step: string;
+    resource: string;
+    vendor: string;
+    type: string;
+    name: string;
+    fields: Record<string, unknown>;
+} | {
+    step: string;
+    resource: string;
+    vendor: string;
+    type: string;
+    name: string;
+    gone: true;
+};
+/** How one approval is decided; `approval` is its title or its id. */
+export interface Decision {
+    step: string;
+    approval: string;
+    decision: "approve" | "reject";
+    by: string;
+    note?: string;
+}
+/**
+ * What the run should do: call an operation (with at least this input) or not, run the step
+ * `name`d in the workflow's outline or not, or a number of `times`, have the policy deny an
+ * operation (`denied`) or hold one for an approver (`held`), end a certain way, or, for a drift
+ * run, report the resource `declared` (`<file>#<export>`) clean, gone, or drifted in a field.
+ * A step whose own code checks the run (a connector's or the company's, or an operation's own
+ * test's) is `custom`, with what it is about.
+ */
+export type Expectation = {
+    step: string;
+    op: string;
+    input?: unknown;
+    called: boolean;
+} | {
+    step: string;
+    name: string;
+    input?: unknown;
+    called: boolean;
+} | {
+    step: string;
+    name: string;
+    times: number;
+} | {
+    step: string;
+    op: string;
+    decision: "denied";
+} | {
+    step: string;
+    op: string;
+    decision: "held";
+    approver: string;
+} | {
+    step: string;
+    outcome: "finished" | "failed";
+    code?: string;
+} | {
+    step: string;
+    declared: string;
+    status: "clean" | "gone";
+} | {
+    step: string;
+    declared: string;
+    status: "drifted";
+    field: string;
+} | {
+    step: string;
+    custom: true;
+    op?: string;
+    called?: boolean;
+};
+export interface Scenario {
+    name: string;
+    /** The feature file, relative to the scenarios directory. */
+    file: string;
+    /** Its line in the file: its keyword's, or for an outline's row, the row's. */
+    line: number;
+    workflow: string;
+    /**
+     * 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
+     * the keyword line's indent. An outline's rows share their outline's.
+     */
+    text: string;
+    /** Every step in order, for a list and for marking graph nodes. */
+    steps: ScenarioStep[];
+    given: Given[];
+    input: unknown;
+    decisions: Decision[];
+    /**
+     * The titles of the approvals the workflow's code asks for, where a title is a string literal
+     * (read from its outline), so `drive` can tell a decision for an approval still to come from
+     * one meant for whichever comes next.
+     */
+    approvals: string[];
+    expect: Expectation[];
+}
+/** The result of one expectation against a run's ledger. */
+export interface Check {
+    step: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * What steps can name: the config's operations, workflows and resource types by id, the steps
+ * its connectors (and the company) ship, and where the feature files are.
+ */
+export type Scope = Pick<ResolvedConfig, "ops" | "workflows" | "scenarios" | "types" | "steps">;
+type Fault = Extract<Seed, {
+    fault: unknown;
+}>["fault"];
+/** Where an operation's own test makes its calls: an operation's driver, live, replayed or a fake's, and the fake. */
+export interface FeatureTarget {
+    driver: Driver;
+    /** The fake whose driver it is: a scenario's faults need one. */
+    fake?: Fake<any, any>;
+}
+/** What `loadScenarios` returns. */
+export interface LoadedScenarios {
+    scenarios: Scenario[];
+    errors: {
+        file: string;
+        message: string;
+    }[];
+}
+/**
+ * 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 declare function loadScenarios(scope: Scope): Promise<LoadedScenarios>;
+/**
+ * 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 declare function check(scope: Scope, scenario: Scenario, records: readonly LedgerRecord[]): Promise<Check[]>;
+/**
+ * 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 declare function featureScenarios(scope: Scope, dir: URL): Promise<{
+    file: string;
+    line: number;
+    name: string;
+    tags: string[];
+}[]>;
+/**
+ * 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 declare function testFeature(scope: Scope, file: string, line: number, target: FeatureTarget): Promise<void>;
+/**
+ * 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 declare function drive(client: SanomaClient, runId: string, scenario: Scenario, { timeoutMs }?: {
+    timeoutMs?: number;
+}): Promise<RunSummary>;
+export {};