@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/scenario.d.ts

@@ -0,0 +1,221 @@
+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, 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.
+ */
+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" | "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 {
+    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 {};