@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/scenario.ts

@@ -13,6 +13,7 @@ import {
 } from "@cucumber/messages";
 import type { z } from "zod";
 import type { RunSummary, SanomaClient } from "./client.ts";
+import type { Approver } from "./define.ts";
 import type { ResolvedConfig } from "./config.ts";
 import {
   buildLibrary,
@@ -25,14 +26,30 @@ import {
   stepResults,
   StepStatus,
 } from "./cucumber.ts";
-import { errorInfo, SanomaError } from "./errors.ts";
+import { errorCode, errorInfo, SanomaError } from "./errors.ts";
 import { type CallRecord, contains, type CoreExpectation, detailOf, isCall } from "./expectations.ts";
 import type { Fake } from "./fake.ts";
 import { fill, isBug, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
-import { DRIFT_WORKFLOW, errorMessage, fitsOp, flatten, isEnded } from "./shared.ts";
+import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
+import { memorySecrets } from "./secret.ts";
+import {
+  APPLY_WORKFLOW,
+  BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  declaresPeople,
+  DRIFT_WORKFLOW,
+  errorMessage,
+  fitsOp,
+  flatten,
+  groupNamesOf,
+  isEnded,
+  principalIdsOf,
+  problemLine,
+  RUNTIME_AGENTS,
+} from "./shared.ts";
 import type { Call, RunView, Seed } from "./steps.ts";
 
 /*
@@ -89,8 +106,11 @@ export interface Decision {
 /**
  * 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.
+ * operation (`denied`, for a `reason` when the step names one) or hold one for an approver
+ * (`held`: a person's id or a group's name, or `{ group }` a group's alone), end a certain way,
+ * for a drift run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or
+ * drifted in a field, or for an apply run, create it, or leave it bound to an object (`bound`,
+ * its vendor's id).
  * 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.
  */
@@ -98,11 +118,13 @@ 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; op: string; decision: "denied"; reason?: string }
+  | { step: string; op: string; decision: "held"; approver: Approver }
   | { step: string; outcome: "finished" | "failed"; code?: string }
-  | { step: string; declared: string; status: "clean" | "gone" }
+  | { step: string; declared: string; status: "clean" | "gone" | "absent" }
   | { step: string; declared: string; status: "drifted"; field: string }
+  | { step: string; declared: string; created: true }
+  | { step: string; declared: string; bound: string }
   | { step: string; custom: true; op?: string; called?: boolean };
 
 export interface Scenario {
@@ -120,6 +142,8 @@ export interface Scenario {
   text: string;
   /** Every step in order, for a list and for marking graph nodes. */
   steps: ScenarioStep[];
+  /** Who starts the run, by id, when a `Given <who> is acting` says: a declared person or agent. */
+  startedBy?: string;
   given: Given[];
   input: unknown;
   decisions: Decision[];
@@ -140,10 +164,14 @@ export interface Check {
 }
 
 /**
- * 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.
+ * What steps can name: the config's operations, workflows, resource types and collections by id,
+ * the steps its connectors (and the company) ship, where the feature files are, and the root
+ * whose data files declare its people.
  */
-export type Scope = Pick<ResolvedConfig, "ops" | "workflows" | "scenarios" | "types" | "steps">;
+export type Scope = Pick<
+  ResolvedConfig,
+  "ops" | "workflows" | "scenarios" | "types" | "collections" | "steps" | "root"
+>;
 
 type Kind = ScenarioStep["kind"];
 type Fault = Extract<Seed, { fault: unknown }>["fault"];
@@ -158,9 +186,13 @@ interface Then {
   verify(run: RunView): string | undefined;
 }
 
-/** What a step of each kind reads into; `any` is a decision, which a step of any keyword may make. */
+/**
+ * What a step of each kind reads into; `any` is a decision, which a step of any keyword may make,
+ * and `actor` a `Given` saying who starts the run (`{who} is acting`), by id.
+ */
 interface Items {
   given: Unstepped<Given>[];
+  actor: string;
   when: When;
   then: Then;
   any: Unstepped<Decision>;
@@ -302,7 +334,9 @@ function builtFor(scope: Scope): Built {
     cached &&
     cached.scope.workflows === scope.workflows &&
     cached.scope.types === scope.types &&
-    cached.scope.steps === scope.steps
+    cached.scope.collections === scope.collections &&
+    cached.scope.steps === scope.steps &&
+    cached.scope.root === scope.root
   ) {
     return cached;
   }
@@ -314,29 +348,66 @@ function builtFor(scope: Scope): Built {
   return built;
 }
 
+/** 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: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
-  const { types } = scope;
+  const { types, collections } = scope;
+  // A collection's records are seeded as a resource's objects are, by `data.<name>`, through its operations.
+  const collectionOf = (id: unknown) =>
+    (id as string).startsWith(`${DATA_VENDOR}.`)
+      ? collections.get((id as string).slice(DATA_VENDOR.length + 1))
+      : undefined;
+  const seedable = new Map<string, unknown>([
+    ...types,
+    ...[...collections.keys()].map((n) => [`${DATA_VENDOR}.${n}`, n] as const),
+  ]);
   const parameterTypes: ParameterTypeSpec[] = [
     { 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) },
+    { name: "resource", regexp: /\S+/, transformer: known("resource type", seedable) },
     // 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: unknown) => scope.ops.get(id as string)!;
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
+  // 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. */
+  const actorNamed = (who: string) => {
+    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. */
+  const groupNamed = (group: string) => {
+    const { people, problems } = readPeople(scope.root);
+    if (problems.length) {
+      throw new Error(
+        `no group can be told while the people's files have problems: ${problems.map(problemLine).join("; ")}`,
+      );
+    }
+    const groups = groupNamesOf(people);
+    if (!declaresPeople(people) || groups.includes(group)) return group;
+    throw new Error(`no group "${group}"; resources/ declares ${groups.join(", ")}`);
+  };
   /** A resource step's object: its type's id, vendor and type, and its import id. */
   const object = (id: unknown, name: unknown) => {
     const { vendor, type } = types.get(id as string)!;
     return { resource: id as string, vendor, type, name: name as string };
   };
   const rules: Rule[] = [
+    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
     {
       kind: "given",
       source: "{op} was called with",
@@ -354,21 +425,32 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       kind: "given",
       source: "{resource} {string} has",
       takes: TAKES_OBJECT,
-      read: ([resource, name], pickle) => [
-        {
-          ...object(resource, name),
-          fields: fieldsFrom(
-            pickle,
-            types.get(resource as string)!.schema,
-            `${resource as string} "${name as string}"`,
-          ),
-        },
-      ],
+      read: ([resource, name], pickle) => {
+        const owner = `${resource as string} "${name as string}"`;
+        const c = collectionOf(resource);
+        if (c) {
+          // The record with its key, the fields the step gives, and the rest made up.
+          const record = shapeOf(opOf(c.save.id).input).record!;
+          const fields = fieldsFrom(pickle, record, owner);
+          if (Object.hasOwn(fields, c.key) && fields[c.key] !== name) {
+            throw new Error(
+              `${c.key} in ${owner} is ${JSON.stringify(fields[c.key])}: it is the key, "${name as string}"`,
+            );
+          }
+          return [{ op: c.save.id, input: { record: fill(record, { ...fields, [c.key]: name }) } }];
+        }
+        return [
+          { ...object(resource, name), fields: fieldsFrom(pickle, types.get(resource as string)!.schema, owner) },
+        ];
+      },
     },
     {
       kind: "given",
       source: "{resource} {string} is gone",
-      read: ([resource, name]) => [{ ...object(resource, name), gone: true }],
+      read: ([resource, name]) => {
+        const c = collectionOf(resource);
+        return [c ? { op: c.delete.id, input: { key: name } } : { ...object(resource, name), gone: true }];
+      },
     },
     {
       kind: "when",
@@ -376,13 +458,21 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       takes: TAKES_OBJECT,
       read: ([name], pickle) => {
         const { input } = workflowOf(name);
-        return { workflow: name as string, input: fill(input, fieldsFrom(pickle, input, inputOf(name))) };
+        const given = fieldsFrom(pickle, input, inputOf(name));
+        return {
+          workflow: name as string,
+          input: BUILT_IN_WORKFLOWS.has(name as string) ? input.parse(given) : fill(input, given),
+        };
       },
     },
     {
       kind: "when",
       source: "{workflow} runs",
-      read: ([name]) => ({ workflow: name as string, input: fill(workflowOf(name).input, {}) }),
+      // A built-in's input is optional throughout: what is not given is left out, not made up.
+      read: ([name]) => ({
+        workflow: name as string,
+        input: BUILT_IN_WORKFLOWS.has(name as string) ? {} : fill(workflowOf(name).input, {}),
+      }),
     },
     // An operation's own test: a call made to its driver, or its fake, directly.
     {
@@ -426,11 +516,22 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       source: "{op} was denied",
       read: ([op]) => expecting({ op: op as string, decision: "denied" }),
     },
+    {
+      kind: "then",
+      source: "{op} was denied with {string}",
+      read: ([op, reason]) => expecting({ op: op as string, decision: "denied", reason: reason as string }),
+    },
     {
       kind: "then",
       source: "{op} was held for {who}",
       read: ([op, who]) => expecting({ op: op as string, decision: "held", approver: who as string }),
     },
+    {
+      kind: "then",
+      source: "{op} was held for group {string}",
+      read: ([op, group]) =>
+        expecting({ op: op as string, decision: "held", approver: { group: groupNamed(group as string) } }),
+    },
     {
       kind: "then",
       source: "step {string} was called with",
@@ -469,11 +570,21 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       read: ([declared, field]) =>
         expecting({ declared: declared as string, status: "drifted", field: field as string }),
     },
-    ...(["clean", "gone"] as const).map((status): Rule => ({
+    ...(["clean", "gone", "absent"] as const).map((status): Rule => ({
       kind: "then",
       source: `{declared} is ${status}`,
       read: ([declared]) => expecting({ declared: declared as string, status }),
     })),
+    {
+      kind: "then",
+      source: "apply creates {declared}",
+      read: ([declared]) => expecting({ declared: declared as string, created: true }),
+    },
+    {
+      kind: "then",
+      source: "{declared} is bound to {string}",
+      read: ([declared, id]) => expecting({ declared: declared as string, bound: id as string }),
+    },
     { kind: "then", source: "the run succeeds", read: () => expecting({ outcome: "finished" }) },
     { kind: "then", source: "the run fails", read: () => expecting({ outcome: "failed" }) },
     {
@@ -618,7 +729,8 @@ function lastCall(records: readonly LedgerRecord[]): CallRecord | string {
 
 /** 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: Rule[]): string {
-  const keyword = (kind: Rule["kind"]) => (kind === "any" ? "Given/When/Then" : kind[0]!.toUpperCase() + kind.slice(1));
+  const keyword = (kind: Rule["kind"]) =>
+    kind === "any" ? "Given/When/Then" : kind === "actor" ? "Given" : kind[0]!.toUpperCase() + kind.slice(1);
   const line = (r: Rule) => `${keyword(r.kind)} ${r.source}${r.takes ? ` (and ${r.takes})` : ""}`;
   const { generic = [], ...groups } = Object.groupBy(rules, (r) => r.group ?? "generic");
   return [
@@ -772,7 +884,9 @@ const ambiguous = (text: string, sources: string[]) =>
 function ruleFor(built: Built, expression: string, pickle: PickleStep): Rule {
   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");
+  const rules = built.byExpression
+    .get(expression)!
+    .filter((r) => r.kind === kind || r.kind === "any" || (r.kind === "actor" && kind === "given"));
   if (rules.length === 0) throw new Error(noMatch(built, pickle.text));
   if (rules.length > 1)
     throw new Error(
@@ -805,6 +919,11 @@ function compileWorld(built: Built, specs: Map<string, Spec>) {
         const { text } = pickle;
         const step: ScenarioStep = { text, kind: KINDS[pickle.type!]! };
         switch (rule.kind) {
+          case "actor":
+            if (spec.startedBy !== undefined)
+              throw new Error(`${spec.startedBy} is acting already: a run has one actor`);
+            spec.startedBy = rule.read(args, pickle);
+            break;
           case "given": {
             const items = rule.read(args, pickle);
             spec.given.push(...items.map((item) => ({ step: text, ...item }) as Given));
@@ -879,6 +998,8 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
     const values = new Map<string, unknown>();
     const records: LedgerRecord[] = [];
     let runId = "";
+    // The test's own secrets, in memory: a driver resolves `secret()` markers against them.
+    const secrets = memorySecrets();
     /** A record of the test, as a run's ledger would hold it. */
     const record = (body: Record<string, unknown>) => {
       const seq = records.length;
@@ -892,7 +1013,7 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
       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 };
+      const context = { idempotencyKey: `${runId}:${records.length}`, runId, opId: id, attempt: 1, secrets };
       return { op, input, output: () => fn(input, context) };
     };
     return {
@@ -954,6 +1075,8 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
             throw new Error(
               `"${text}" decides an approval: a step for a scenario in scenarios/, not an operation's own test`,
             );
+          case "actor":
+            throw new Error(`"${text}" says who starts a run: a step for a scenario in scenarios/`);
           case "then": {
             const detail = rule.read(args, pickle).verify(viewOf(records));
             if (detail !== undefined) throw new Error(detail);
@@ -1092,11 +1215,14 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
               `${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}`,
-            );
+          // A step about a declared resource reads the report of the built-in it is about.
+          for (const e of spec.expect) {
+            const reads: string = "declared" in e ? ("status" in e ? DRIFT_WORKFLOW : APPLY_WORKFLOW) : workflow;
+            if (reads !== workflow) {
+              throw new Error(
+                `${where}: "${e.step}" reads ${reads === DRIFT_WORKFLOW ? "a drift" : "an apply"} report, so the scenario must run ${reads}, not ${workflow}`,
+              );
+            }
           }
           inFile.push({
             ...spec,
@@ -1142,18 +1268,22 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
 }
 
 /**
- * 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.
+ * Each scope's scenarios as last read, with the stamp of the files they were read from and the
+ * people they were checked against (`readPeople`'s answer, the same object until a data file
+ * changes). By scope, since what a file means depends on its operations and workflows.
  */
-const loadedByScope = new WeakMap<Scope, { stamp: string; loaded: Promise<LoadedScenarios> }>();
+const loadedByScope = new WeakMap<
+  Scope,
+  { stamp: string; people: DeclaredPeople | undefined; loaded: Promise<LoadedScenarios> }
+>();
 
 /**
  * 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.
+ * (its name, `mtimeMs` or size changes), or the people's data files change: until then each
+ * call returns the same object, which callers must not change.
  */
 export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
   if (!scope.scenarios) return { scenarios: [], errors: [] };
@@ -1169,10 +1299,12 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
       return [file, mtimeMs, size];
     }),
   ]);
+  // None without a root, which declares no one.
+  const people = scope.root === undefined ? undefined : readPeople(scope.root);
   const cached = loadedByScope.get(scope);
-  if (cached?.stamp === stamp) return cached.loaded;
+  if (cached?.stamp === stamp && cached.people === people) return cached.loaded;
   const loaded = files.length ? compile(scope, dir, files) : Promise.resolve({ scenarios: [], errors: [] });
-  loadedByScope.set(scope, { stamp, loaded });
+  loadedByScope.set(scope, { stamp, people, 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);

package/src/scenarios.ts

@@ -18,21 +18,28 @@ export interface RunScenarioOptions {
   client: SanomaClient;
   /** What the scenario was loaded from (`loadScenarios`), whose feature files its run is checked against: the resolved config. */
   scope: Scope;
-  /** Who starts the run. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /**
+   * Who starts the run, by id (`"ada"` or `{ id: "ada" }`), unless the scenario says who is acting.
+   * Defaults to `scenarios`, one of the runtime's own agents.
+   */
+  startedBy?: Principal | string;
   /** How long the run may take, passed to `drive`. */
   timeoutMs?: number;
 }
 
 /**
- * Runs a scenario as a sandbox run: starts its workflow with its input, decides its approvals
- * as it says, and checks the run's ledger against it (`check`: Cucumber runs its `Then` steps).
+ * Runs a scenario as a sandbox run: starts its workflow with its input, as whoever it says is
+ * acting, decides its approvals as it says, and checks the run's ledger against it (`check`:
+ * Cucumber runs its `Then` steps).
  */
 export async function runScenario(
   scenario: Scenario,
-  { client, scope, startedBy = { id: "scenarios" }, timeoutMs }: RunScenarioOptions,
+  { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
-  const runId = await client.start(scenario.workflow, scenario.input, { startedBy, sandbox: scenario.name });
+  const runId = await client.start(scenario.workflow, scenario.input, {
+    startedBy: scenario.startedBy ?? startedBy,
+    sandbox: scenario.name,
+  });
   const run = await drive(client, runId, scenario, { timeoutMs });
   const ledger = await client.ledger(runId);
   return { runId, run, ledger, checks: await check(scope, scenario, ledger) };
@@ -49,8 +56,8 @@ export interface ScenarioFailure {
 export interface RunScenariosOptions {
   /** The Postgres the worker and the client run on, instead of the config's: a database of its own. */
   databaseUrl: string;
-  /** Who starts the runs. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /** Who starts the runs whose scenario does not say who is acting (`runScenario`'s). */
+  startedBy?: Principal | string;
   /** How long each run may take (`drive`'s; 15 seconds by default). */
   timeoutMs?: number;
   /** Receives a line per scenario as it ends. */