@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/op.d.ts

@@ -0,0 +1,260 @@
+import type { z } from "zod";
+import type { Fake } from "./fake.ts";
+import type { Secrets } from "./secret.ts";
+import type { Steps } from "./steps.ts";
+/**
+ * What an operation does to the outside world. It sets the badge a reviewer
+ * sees and, later, the Cedar action the call is checked against.
+ */
+export type Effect = "read" | "write" | "publish" | "send" | "money" | "access";
+export interface OpSpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
+    effect: Effect;
+    input: I;
+    output: O;
+    /** Safe to retry: the vendor dedupes repeated calls. Otherwise a failed call stops the run. */
+    idempotent?: boolean;
+    description?: string;
+    /**
+     * The resource instance a call acts on, from its parsed input, such as a post's id. The
+     * policy sees it as `target`, so it can decide per instance. Must be deterministic.
+     *
+     * Its input is typed `any` inside `defineConnector`: TypeScript gives an inline function the
+     * type `Specs` declares, not the one its own spec's schema implies. Annotate it to have it
+     * checked: `target: ({ id }: { id: string }) => \`post/${id}\``.
+     */
+    target?: (input: any) => string;
+    /**
+     * How a scenario says this operation was set up or called, in Gherkin steps: `given` seeds
+     * the fake through it, `expect` expects a call to it. Cucumber expressions whose parameters are
+     * fields of the input, such as `{ given: "a post titled {title} exists" }`.
+     */
+    phrases?: {
+        given?: string;
+        expect?: string;
+    };
+    /**
+     * Top-level fields of its input and output that are the driver's own data, not the vendor's
+     * (a resource type's `handle`): the ledger records each as `"<name>"`, never its value.
+     */
+    opaque?: readonly string[];
+}
+/** One vendor operation, such as `ghost.post.publish`. Declares the contract only; drivers implement it. */
+export interface Op<V extends string = string, R extends string = string, N extends string = string, I = any, O = any> {
+    readonly kind: "op";
+    readonly id: `${V}.${R}.${N}`;
+    readonly vendor: V;
+    readonly resource: R;
+    readonly name: N;
+    readonly effect: Effect;
+    readonly idempotent: boolean;
+    readonly description?: string;
+    /** From the spec: the resource instance a call acts on. */
+    readonly target?: (input: any) => string;
+    /** From the spec: how a scenario's steps name it. */
+    readonly phrases?: {
+        readonly given?: string;
+        readonly expect?: string;
+    };
+    /** From the spec: fields the ledger records by name only. */
+    readonly opaque?: readonly string[];
+    readonly input: z.ZodType<any, I>;
+    readonly output: z.ZodType<O>;
+}
+/**
+ * Where a resource type keeps its brand. A symbol, so `defineConnector` tells a resource type
+ * (`defineResource`) from a group of operations; a registered one (`Symbol.for`), so a copy of
+ * this package reads what another copy made, as `VENDOR`.
+ */
+export declare const RESOURCE: unique symbol;
+/** What `defineConnector` reads of a resource type; `defineResource` makes them. */
+export interface ResourceGroup {
+    readonly [RESOURCE]: true;
+    readonly vendor: string;
+    readonly type: string;
+    readonly ops: Readonly<Record<string, OpSpec>>;
+}
+/** A connector's groups: operations by name, or a resource type, whose operations are `read` and `import`. */
+export type Specs = Record<string, Record<string, OpSpec> | ResourceGroup>;
+/** The operations of one group of `Specs`. */
+export type GroupOps<G> = G extends ResourceGroup ? G["ops"] : G;
+type InputOf<T> = T extends OpSpec<infer I, any> ? I : never;
+type OutputOf<T> = T extends OpSpec<any, infer O> ? O : never;
+/**
+ * Where a connector keeps its vendor. A symbol, so it names no resource: `Object.values` and
+ * `keyof` over a connector see its resources only. A registered one (`Symbol.for`): a process
+ * may load two copies of this package (a connector's peer linked into a sanoma checkout, the
+ * app's from its tarball), and each must read the connectors the other made.
+ */
+export declare const VENDOR: unique symbol;
+export type Connector<V extends string, S extends Specs> = {
+    readonly [R in keyof S & string]: {
+        readonly [N in keyof GroupOps<S[R]> & string]: Op<V, R, N, z.input<InputOf<GroupOps<S[R]>[N]>>, z.output<OutputOf<GroupOps<S[R]>[N]>>>;
+    };
+} & {
+    readonly [VENDOR]: ConnectorVendor<V>;
+};
+/**
+ * The shape of a connector's `[VENDOR]` record. A process may load two builds of this package,
+ * and `resolveConfig` reads only a record of its own shape (`checkConnector`): change it with
+ * the record, so a build refuses a connector another build made in another shape.
+ */
+export declare const CONNECTOR_FORMAT = 1;
+/**
+ * A connector's vendor: its id, who it is (`defineConnector`'s third argument, for a UI), its
+ * resource types, and the driver and fake its package attaches (`withSetup`).
+ */
+export interface ConnectorVendor<V extends string = string> {
+    /** The record's shape (`CONNECTOR_FORMAT`). */
+    readonly format: typeof CONNECTOR_FORMAT;
+    readonly id: V;
+    readonly info?: VendorInfo;
+    /** The resource types among its groups, in the order given. */
+    readonly resources: readonly ResourceGroup[];
+    /** What `withSetup` attached: how the config's resolver makes its driver and its fake. */
+    readonly setup?: ConnectorSetup;
+}
+/**
+ * Who a connector's vendor is, and where the connector lives, for a UI to show beside its
+ * operations. `logo` is the vendor's mark as inline SVG markup (one `<svg>…</svg>` element), and
+ * `dark` its variant for dark backgrounds. The app shows a logo only as an image (a `data:` URL
+ * in an `<img>`), where an SVG's scripts and external references never run or load.
+ */
+export interface VendorInfo {
+    /** The vendor's name as it writes it, such as "Resend". */
+    title?: string;
+    logo?: {
+        svg: string;
+        dark?: string;
+    };
+    /** The connector's npm package name, such as "@sanoma-ai/connector-resend". */
+    package?: string;
+    /** The connector package's `homepage` from its package.json: where its code and README are, as an https URL. */
+    homepage?: string;
+}
+/**
+ * Declares a vendor's operations, grouped by resource: `defineConnector("ghost", { post: { create: {...} } })`.
+ * A group may be a resource type from `defineResource`, under its own `type`, for its `read` and
+ * `import`: `defineConnector("github", { repository }, { package: "@sanoma-ai/connector-github" })`;
+ * it must be of the same vendor, and the connector needs `info.package`, whose `/resources`
+ * entry exports the types for data files.
+ * `info` says who the vendor is and where the connector lives, for a UI:
+ * `{ title: "Resend", logo: { svg }, package: "@sanoma-ai/connector-resend", homepage: "https://…" }`.
+ */
+export declare function defineConnector<const V extends string, const S extends Specs>(vendor: V, specs: S, info?: VendorInfo): Connector<V, S>;
+/**
+ * What the runtime tells a driver about the call it is making. `idempotencyKey` is the same
+ * on every replay and retry of one call (`<runId>:<seq>`), so a driver can hand it to the
+ * vendor, or dedupe on it, and a crash between the vendor's reply and the checkpoint does
+ * not repeat the side effect.
+ */
+export interface CallContext {
+    idempotencyKey: string;
+    runId: string;
+    opId: string;
+    /** 1 on the first try; retries count up (idempotent operations only). */
+    attempt: number;
+    /** The secrets store, for the values `secret()` markers name: `resolveSecrets(input, call.secrets)`. In memory for a fake. */
+    secrets: Secrets;
+}
+export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;
+/**
+ * A vendor's answer that the driver understood. `retryable` tells the runtime whether to try
+ * again (an idempotent operation on a timeout or a 5xx) or to stop (a 4xx). `status` and
+ * `vendorCode` keep what the vendor said, so the ledger and the UI can show it.
+ */
+export declare class DriverError extends Error {
+    readonly code: "driver_failed";
+    readonly retryable: boolean;
+    readonly status?: number;
+    readonly vendorCode?: string;
+    constructor(message: string, options: {
+        retryable: boolean;
+        status?: number;
+        vendorCode?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Whether a vendor's HTTP status is worth retrying: a request timeout (408), a rate limit (429)
+ * or a server error (5xx). It is the runtime's default rule; a driver adds its vendor's
+ * exceptions around it, such as a quota that does not lift in the seconds a retry waits.
+ */
+export declare function retryableStatus(status: number): boolean;
+/**
+ * The environment variables a driver reads, as a Zod object of string schemas keyed by variable
+ * name, such as `z.object({ ACME_API_KEY: z.string().describe("an API key, from Settings, API keys") })`:
+ * each `.describe()` is the variable's one-line manual (what to put there, where to get it),
+ * `.optional()` marks one that may be unset. `resolveConfig` checks it against `process.env` and
+ * never keeps a value. The driver still reads the raw environment when it is called, so a
+ * `.default()` or `.transform()` is not applied to what it reads (use `.optional()` and name the
+ * default in `.describe()`), and a `.refine()` or `.superRefine()` on the object is not evaluated,
+ * only its fields.
+ */
+export type DriverEnv = z.ZodObject<Record<string, z.ZodType<string | undefined, string | undefined>>>;
+/**
+ * Implements a vendor's operations, keyed `"resource.name"`. A driver reads its credentials
+ * from the environment when it is called, never from the config file; `env` declares them.
+ */
+export interface Driver {
+    readonly vendor: string;
+    readonly ops: Readonly<Record<string, DriverFn>>;
+    readonly env?: DriverEnv;
+}
+/**
+ * What a connector package attaches to its connector (`withSetup`), for the config's resolver
+ * to call: the config then names the connector alone, and never a driver, a fake or steps. Any may
+ * be missing: a workflow using an operation of a connector with no driver is refused, and a
+ * connector with no fake has none for sandbox runs.
+ */
+export interface ConnectorSetup {
+    /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
+    driver?: () => Driver;
+    /** Makes a fake of the vendor (`defineFake`): once per sandbox run, its own. */
+    fake?: () => Fake<any, any>;
+    /** The connector's steps for Gherkin tests (`defineSteps`): a config's scenarios and the connector's own features can use them. */
+    steps?: Steps;
+}
+/**
+ * The connector with `setup` laid over what it already carries, as a connector package exports
+ * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A
+ * config that needs a driver made otherwise (another bridge, other options) swaps that one and
+ * keeps the fake: `withSetup(github, { driver: () => githubDriver({ bridge }) })`. The operations
+ * are the same objects, and the type is the connector's. The setup is kept on the connector's
+ * vendor record (`[VENDOR]`), so a spread copy of the connector keeps it.
+ */
+export declare function withSetup<C extends Connector<any, any>>(connector: C, setup: Partial<ConnectorSetup>): C;
+/**
+ * Throws unless `value` is a connector this package can read: one `defineConnector` made, in this
+ * copy of the package or another of the same `CONNECTOR_FORMAT`. One an older build made (its
+ * `VENDOR` an unregistered symbol, or its record without a format) is refused as such.
+ */
+export declare function checkConnector(value: unknown): asserts value is Connector<any, any>;
+/** What `withSetup` attached to a connector: nothing when it attached nothing. */
+export declare const setupOf: (connector: Connector<any, any>) => ConnectorSetup;
+export declare function isOp(x: unknown): x is Op;
+/**
+ * What a driver for a connector must implement: every operation, by resource and name. Each
+ * function gets the input as the operation's schema parses it and returns what its output
+ * schema accepts.
+ */
+export type DriverImpl<S extends Specs> = {
+    [R in keyof S & string]: {
+        [N in keyof GroupOps<S[R]> & string]: DriverFn<z.output<InputOf<GroupOps<S[R]>[N]>>, z.input<OutputOf<GroupOps<S[R]>[N]>>>;
+    };
+};
+/** The ids of a connector's operations, such as `"ghost.post.create" | "ghost.post.publish"`. */
+export type OpIdOf<V extends string, S extends Specs> = {
+    [R in keyof S & string]: {
+        [N in keyof GroupOps<S[R]> & string]: `${V}.${R}.${N}`;
+    }[keyof GroupOps<S[R]> & string];
+}[keyof S & string];
+/**
+ * Implements a connector's operations, typed by its schemas. A driver must be complete: an
+ * operation the connector declares that `impl` leaves out, or one `impl` adds that the
+ * connector doesn't declare, is refused here rather than when a run calls it. `options.env`
+ * declares the environment variables it reads (see `DriverEnv`).
+ */
+export declare function defineDriver<V extends string, S extends Specs>(connector: Connector<V, S>, impl: DriverImpl<S>, options?: {
+    env?: DriverEnv;
+}): Driver;
+export {};

package/dist/op.js

@@ -0,0 +1,188 @@
+/**
+ * Where a resource type keeps its brand. A symbol, so `defineConnector` tells a resource type
+ * (`defineResource`) from a group of operations; a registered one (`Symbol.for`), so a copy of
+ * this package reads what another copy made, as `VENDOR`.
+ */
+export const RESOURCE = Symbol.for("sanoma.resource");
+/**
+ * Where a connector keeps its vendor. A symbol, so it names no resource: `Object.values` and
+ * `keyof` over a connector see its resources only. A registered one (`Symbol.for`): a process
+ * may load two copies of this package (a connector's peer linked into a sanoma checkout, the
+ * app's from its tarball), and each must read the connectors the other made.
+ */
+export const VENDOR = Symbol.for("sanoma.vendor");
+/**
+ * The shape of a connector's `[VENDOR]` record. A process may load two builds of this package,
+ * and `resolveConfig` reads only a record of its own shape (`checkConnector`): change it with
+ * the record, so a build refuses a connector another build made in another shape.
+ */
+export const CONNECTOR_FORMAT = 1;
+/** One `<svg>` element, with nothing but whitespace around it. */
+const SVG_ELEMENT = /^\s*<svg[\s>][\s\S]*<\/svg>\s*$/;
+const isResourceGroup = (group) => (typeof group === "function" || typeof group === "object") &&
+    group !== null &&
+    group[RESOURCE] === true;
+/**
+ * Declares a vendor's operations, grouped by resource: `defineConnector("ghost", { post: { create: {...} } })`.
+ * A group may be a resource type from `defineResource`, under its own `type`, for its `read` and
+ * `import`: `defineConnector("github", { repository }, { package: "@sanoma-ai/connector-github" })`;
+ * it must be of the same vendor, and the connector needs `info.package`, whose `/resources`
+ * entry exports the types for data files.
+ * `info` says who the vendor is and where the connector lives, for a UI:
+ * `{ title: "Resend", logo: { svg }, package: "@sanoma-ai/connector-resend", homepage: "https://…" }`.
+ */
+export function defineConnector(vendor, specs, info) {
+    // A copy, frozen once checked: changing the caller's object later cannot slip a logo past the check.
+    const logo = info?.logo && Object.freeze(Object.fromEntries(Object.entries(info.logo).filter(([, v]) => v !== undefined)));
+    for (const [variant, svg] of Object.entries(logo ?? {})) {
+        if (typeof svg !== "string" || !SVG_ELEMENT.test(svg)) {
+            throw new Error(`defineConnector("${vendor}"): logo.${variant} must be inline SVG markup, one <svg>…</svg> element`);
+        }
+    }
+    const vendorInfo = info && Object.freeze({ ...info, ...(logo && { logo: logo }) });
+    // It becomes a link's href: a whole https URL, so never a `javascript:` one. Checked on the copy kept.
+    const homepage = vendorInfo?.homepage;
+    if (homepage !== undefined && (typeof homepage !== "string" || URL.parse(homepage)?.protocol !== "https:"))
+        throw new Error(`defineConnector("${vendor}"): homepage must be an https URL`);
+    const out = {};
+    const resources = [];
+    for (const [resource, group] of Object.entries(specs)) {
+        let ops = group;
+        if (isResourceGroup(group)) {
+            if (group.vendor !== vendor) {
+                throw new Error(`defineConnector("${vendor}"): ${resource} is a resource type of ${group.vendor}`);
+            }
+            if (group.type !== resource) {
+                throw new Error(`defineConnector("${vendor}"): the resource type ${group.type} is given as ${resource}`);
+            }
+            resources.push(group);
+            ops = group.ops;
+        }
+        out[resource] = {};
+        for (const [name, spec] of Object.entries(ops)) {
+            out[resource][name] = Object.freeze({
+                kind: "op",
+                id: `${vendor}.${resource}.${name}`,
+                vendor,
+                resource,
+                name,
+                effect: spec.effect,
+                idempotent: spec.idempotent ?? false,
+                description: spec.description,
+                target: spec.target,
+                phrases: spec.phrases,
+                ...(spec.opaque?.length ? { opaque: spec.opaque } : {}),
+                input: spec.input,
+                output: spec.output,
+            });
+        }
+    }
+    // A data file imports the resource types from `<package>/resources`, which the reader matches exactly.
+    if (resources.length && !vendorInfo?.package) {
+        throw new Error(`defineConnector("${vendor}"): a connector with resource types needs info.package, the npm package data files import them from (\`<package>/resources\`)`);
+    }
+    const owner = Object.freeze({
+        format: CONNECTOR_FORMAT,
+        id: vendor,
+        info: vendorInfo,
+        resources: Object.freeze(resources),
+    });
+    return { ...out, [VENDOR]: owner };
+}
+/**
+ * A vendor's answer that the driver understood. `retryable` tells the runtime whether to try
+ * again (an idempotent operation on a timeout or a 5xx) or to stop (a 4xx). `status` and
+ * `vendorCode` keep what the vendor said, so the ledger and the UI can show it.
+ */
+export class DriverError extends Error {
+    code = "driver_failed";
+    retryable;
+    status;
+    vendorCode;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "DriverError";
+        this.retryable = options.retryable;
+        if (options.status !== undefined)
+            this.status = options.status;
+        if (options.vendorCode !== undefined)
+            this.vendorCode = options.vendorCode;
+    }
+}
+/**
+ * Whether a vendor's HTTP status is worth retrying: a request timeout (408), a rate limit (429)
+ * or a server error (5xx). It is the runtime's default rule; a driver adds its vendor's
+ * exceptions around it, such as a quota that does not lift in the seconds a retry waits.
+ */
+export function retryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/**
+ * The connector with `setup` laid over what it already carries, as a connector package exports
+ * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A
+ * config that needs a driver made otherwise (another bridge, other options) swaps that one and
+ * keeps the fake: `withSetup(github, { driver: () => githubDriver({ bridge }) })`. The operations
+ * are the same objects, and the type is the connector's. The setup is kept on the connector's
+ * vendor record (`[VENDOR]`), so a spread copy of the connector keeps it.
+ */
+export function withSetup(connector, setup) {
+    const owner = connector[VENDOR];
+    return {
+        ...connector,
+        [VENDOR]: Object.freeze({ ...owner, setup: Object.freeze({ ...owner.setup, ...setup }) }),
+    };
+}
+/**
+ * Throws unless `value` is a connector this package can read: one `defineConnector` made, in this
+ * copy of the package or another of the same `CONNECTOR_FORMAT`. One an older build made (its
+ * `VENDOR` an unregistered symbol, or its record without a format) is refused as such.
+ */
+export function checkConnector(value) {
+    const record = typeof value === "object" && value !== null ? value[VENDOR] : undefined;
+    if (record?.format === CONNECTOR_FORMAT)
+        return;
+    const build = "install the sanoma packages and connectors from one build";
+    throw new Error(record === undefined
+        ? `\`connectors\` holds something that is not a connector: list what the connector packages export (or one from an older build: ${build})`
+        : `The "${String(record.id)}" connector was made by another build of @sanoma-ai/workflows: ${build}`);
+}
+/** What `withSetup` attached to a connector: nothing when it attached nothing. */
+export const setupOf = (connector) => connector[VENDOR].setup ?? {};
+export function isOp(x) {
+    return typeof x === "object" && x !== null && x.kind === "op";
+}
+/**
+ * Implements a connector's operations, typed by its schemas. A driver must be complete: an
+ * operation the connector declares that `impl` leaves out, or one `impl` adds that the
+ * connector doesn't declare, is refused here rather than when a run calls it. `options.env`
+ * declares the environment variables it reads (see `DriverEnv`).
+ */
+export function defineDriver(connector, impl, options = {}) {
+    const declared = new Map();
+    for (const resource of Object.values(connector)) {
+        for (const op of Object.values(resource))
+            if (isOp(op))
+                declared.set(`${op.resource}.${op.name}`, op);
+    }
+    const vendor = connector[VENDOR].id;
+    const ops = {};
+    const extra = [];
+    for (const [resource, fns] of Object.entries(impl)) {
+        for (const [name, fn] of Object.entries(fns ?? {})) {
+            const key = `${resource}.${name}`;
+            if (!declared.has(key))
+                extra.push(`${vendor}.${key}`);
+            else if (typeof fn === "function")
+                ops[key] = fn;
+        }
+    }
+    const missing = [...declared.keys()].filter((key) => !Object.hasOwn(ops, key)).map((key) => `${vendor}.${key}`);
+    const problems = [
+        ...(missing.length ? [`it does not implement ${missing.join(", ")}`] : []),
+        ...(extra.length ? [`it implements ${extra.join(", ")}, which the connector does not declare`] : []),
+    ];
+    if (problems.length)
+        throw new Error(`defineDriver("${vendor}"): ${problems.join("; ")}`);
+    return Object.freeze({ vendor, ops: Object.freeze(ops), ...(options.env && { env: options.env }) });
+}
+//# sourceMappingURL=op.js.map

package/dist/op.js.map

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

package/dist/outline.d.ts

@@ -0,0 +1,179 @@
+import { type Node, type SourceFile } from "./ast.ts";
+import { type WorkflowDefinition } from "./define.ts";
+/**
+ * What a workflow's `run` calls through `ctx`, in the order it makes the calls, with the loops,
+ * branches, `try` blocks and `ctx.all` groups around them. Read from the file that defined the
+ * workflow, and a contract: `run` may write only what the outline can draw (`outlineBody`'s
+ * problems; the worker refuses a workflow with any, the lint reports them), and the worker
+ * places every `ctx` call a run makes at its node (`callAt`), refusing one made from code the
+ * outline has no node for (`call_not_in_outline`). Every record a call writes names its node
+ * (`node`), so a run's steps are the outline's calls and nothing else.
+ */
+export type Outline = 
+/** Read from the file that defined the workflow (`wf.file`): the spans index into its text. */
+{
+    nodes: OutlineNode[];
+    file: string;
+} | {
+    error: string;
+};
+/** Where a node is in the text the outline was read from: UTF-16 offsets, as a string index or CodeMirror counts them. */
+export type Span = readonly [start: number, end: number];
+/**
+ * Each node's `path` is its place in the outline: its index among its siblings, under its
+ * parent's path and the index of the branch, case or body it is in (`"2"`, `"2.1.0"`), so the
+ * same tree has the same paths however the code is laid out; a ledger record's `node` is one.
+ * Each node's `span` is the code it stands for: the call for `op`, `approval` and `sleep`, the
+ * `ctx.all(...)` call for `all` and `each`, the loop or the iterating call (`items.map(cb)`) for
+ * `repeat`, the whole `if` / `else if` chain, `switch`, `?:` or `&&` for `branch`, and the `try`
+ * statement for `try`.
+ *
+ * A call's `name` is its step's name, what a test and the graph call it: the one the call gives
+ * (`{ name: "…" }`, on `op` and `sleep`), else its operation's id, or `Sleep`
+ * (`DEFAULT_SLEEP_NAME`); an approval's is its `title`. A computed call without a name of its
+ * own has none here: the operation it calls, known only in a run, names it. A name given, and an
+ * approval's title, is one step's only; an unnamed call's may be several's. A loop's `label`
+ * (`repeat`, and `each`) is read from its code, "for each of subscribers" for
+ * `for (const s of subscribers)` or `subscribers.map(…)`, "repeat while queue.length" for a
+ * `while`: no step's name.
+ */
+export type OutlineNode = {
+    path: string;
+    span: Span;
+} & 
+/**
+ * `ctx.<vendor>.<resource>.<name>(...)`, a computed segment shown as `*`. An id with one has
+ * `ops`: the ids in the workflow's `uses` it fits (`fitsOp`), sorted, which is what the call
+ * can reach; an id with every segment literal has none.
+ */
+/** `name`: the one the call gives (`ctx.x.y.z(input, { name: "…" })`), else the id when no segment is computed. */
+({
+    kind: "op";
+    id: string;
+    ops?: string[];
+    name?: string;
+}
+/**
+ * `ctx.approval(...)`, with its title, and the title as its `name`, when the first argument is
+ * a string literal or a top-level `const` holding one.
+ */
+ | {
+    kind: "approval";
+    title?: string;
+    name?: string;
+}
+/** `name`: the one the call gives (`ctx.sleep(request, { name: "…" })`), else `DEFAULT_SLEEP_NAME`. */
+ | {
+    kind: "sleep";
+    name: string;
+}
+/** `ctx.all([...])` over an array literal: one branch per element. */
+ | {
+    kind: "all";
+    branches: OutlineNode[][];
+}
+/** `ctx.all(items.map(cb))`: what the callback's member does, labelled from the code (`for each of items`). */
+ | {
+    kind: "each";
+    label: string;
+    body: OutlineNode[];
+}
+/**
+ * A loop, or a `.map` / `.forEach` / `.reduce` callback, whose body makes ctx calls, labelled
+ * from the code: `for each of items`, `for each key of record`, `repeat while cond`, `repeat`.
+ */
+ | {
+    kind: "repeat";
+    label: string;
+    body: OutlineNode[];
+}
+/**
+ * `if`, `switch`, `?:`, `&&`, `||` or `??`: one case per arm that makes ctx calls, and one empty
+ * case for the way past them when there is one (an arm without calls, an `if` without `else`,
+ * a `switch` without `default`, the right side of `&&` not run).
+ */
+ | {
+    kind: "branch";
+    cases: OutlineNode[][];
+}
+/** `try { body } catch { handler }`: the handler runs when the body fails. A `finally` makes no calls. */
+ | {
+    kind: "try";
+    body: OutlineNode[];
+    handler: OutlineNode[];
+});
+/** The node kinds a `ctx` call is: what a call site resolves to (`callAt`). */
+export type CallNode = Extract<OutlineNode, {
+    kind: "op" | "approval" | "sleep" | "all" | "each";
+}>;
+/** Something in `run` the outline cannot draw, at an offset into the file, and what to write instead. */
+export interface OutlineProblem {
+    start: number;
+    message: string;
+}
+/**
+ * Outlines a workflow from the file that defined it (`wf.file`): TypeScript or, once built,
+ * JavaScript. Counts only calls on `run`'s first parameter, whatever it is named. Returns
+ * `{ error }` when the file cannot be read or parsed, holds no workflow of that name, `run`
+ * takes no `ctx` by name, or `run` holds what the outline cannot draw (each problem at
+ * `file:line:column`).
+ */
+export declare const outlineWorkflow: (wf: WorkflowDefinition<any, any>) => Outline;
+/**
+ * `outlineWorkflow` over `file`, the workflow's file as `readSource` read it, with the text its
+ * spans index into (none with an `{ error }`). `found` is whether the file was parsed and holds
+ * the workflow's `run`: an `{ error }` with it found is what `run` holds that the outline cannot
+ * draw, which the lint reports too; one without is the file's (unread, unparsed, or no workflow
+ * of that name).
+ */
+export declare function outlineWithSource(wf: WorkflowDefinition<any, any>, file: SourceFile | string): {
+    outline: Outline;
+    source?: string;
+    found: boolean;
+};
+/** The file's top-level string constants, `export const NAME = "drift"`, by name: what a name may be besides a literal. */
+export declare function constsOf(program: Node): ReadonlyMap<string, string>;
+/**
+ * The nodes of `fn`'s body (`run`'s, or a callback's the outline reads), each with an empty `path`
+ * for `withPaths` to fill, and the problems: what the body does that the graph could not show.
+ * A call's `{ name }`, and an approval's title, is a string literal or one of `consts`
+ * (`constsOf` the file); a name given is not an operation's id or `Sleep`, and no two steps are
+ * given one name (`twiceNamed`). A loop's label quotes its code from `source`, the file's text.
+ * `ctx` is `fn`'s first parameter, taken by one name (destructured is a problem; none, and the
+ * body makes no calls). `ctx` is only called, directly, as an operation or a built-in, or read
+ * for `ctx.runId`; a function defined inside that uses `ctx` is read only where the outline
+ * reads callbacks (`ctx.all`'s members, `.map`, `.forEach` and `.reduce`), elsewhere it is a
+ * problem; a `finally` may not use `ctx`; and in a body the outline reads, `return` comes last,
+ * `throw` only in a `catch`, `break` leaves only a `switch`, and there is no `continue`. A
+ * callback without `ctx` computes, and is not read.
+ */
+export declare function outlineBody(fn: Node, { consts, source }: {
+    consts: ReadonlyMap<string, string>;
+    source: string;
+}): {
+    nodes: OutlineNode[];
+    problems: OutlineProblem[];
+};
+/** The outline's call nodes, wherever they are in it, in order: what `callAt` searches. */
+export declare const callsOf: (nodes: readonly OutlineNode[]) => CallNode[];
+/** What a call node is called as on `ctx`: the operation's id (`*` for a computed segment), or `all`, `approval`, `sleep`. */
+export declare const callName: (node: CallNode) => string;
+/**
+ * The call a position in the source belongs to: the innermost of `calls` (`callsOf`) whose span
+ * holds the offset, as a stack frame places a call at its callee (`ctx.ghost.post.create(…)` at
+ * `create`). A call inside another's arguments is the inner one. None when no call's code holds
+ * it: a call made from a helper, or from a function defined inside `run`, which the outline does
+ * not read.
+ */
+export declare function callAt(calls: readonly CallNode[], offset: number): CallNode | undefined;
+/** The node under the wrappers that leave its value as it is, and a default's pattern. */
+export declare function unwrap(node: Node): Node;
+/**
+ * Every workflow literal in a parsed file: the object literal `defineWorkflow({ name, …, run })`
+ * (or `sanoma.defineWorkflow(…)`) is called with, when it has a `name` and a `run` function. For
+ * the outline, which picks the one by its name, and the lint, which checks each `run`.
+ */
+export declare function workflowLiterals(program: Node): {
+    name: Node;
+    run: Node;
+}[];