@procedures/compiler 0.0.0-stage → 0.3.0

package/dist/ir.d.ts

@@ -0,0 +1,240 @@
+/**
+ * The intermediate representation (IR) of a program.
+ *
+ * The normalize pass makes the IR from the JSON of a program. Each node is one step of the
+ * interpreter: `hydrateInput()` or a control-flow procedure of `@procedures/client`. The code
+ * generation follows the IR in the order of the interpreter. Each node keeps the JSON pointer
+ * (RFC 6901) of its source in the program.
+ */
+import type { ProcedurePath } from "@procedures/client/browser";
+/** A JSON pointer (RFC 6901) into the program. The empty string is the root. */
+export type Pointer = string;
+/** This function gives the pointer of a child: the key is escaped as RFC 6901 tells. */
+export declare function childPointer(pointer: Pointer, key: string | number): Pointer;
+/** The kinds of a binding: the source of a name in a scope. */
+export type BindingKind = "step" | "initial" | "item" | "index" | "acc" | "error" | "input";
+/**
+ * A binding is a value that a scope gives to a name. Examples are the result of a chain step,
+ * the item of `client.map` and the error of `client.tryCatch`. Each binding gets one variable.
+ */
+export interface Binding {
+    /** The number of the binding, unique in the program. */
+    readonly id: number;
+    readonly kind: BindingKind;
+    /** The name in the scope. A step without `$name` has no name: only `$last` reads it. */
+    readonly name: string | undefined;
+    /** The pointer of the source of the binding. */
+    readonly pointer: Pointer;
+}
+/** One frame of a static scope, as the interpreter has it at one point of the program. */
+export interface ScopeFrame {
+    /** The names of the frame and their bindings, in the order of `Map.set`. */
+    readonly names: ReadonlyArray<readonly [string, Binding]>;
+    /** The binding that `$last` reads in this frame, or undefined when the frame has none. */
+    readonly last: Binding | undefined;
+}
+/** A static scope: the frames from the outermost to the innermost. Undefined: no scope. */
+export type ScopeSnapshot = readonly ScopeFrame[] | undefined;
+/** Where a call is: the root call, an operand of control flow, or a call in an input. */
+export type CallPosition = "root" | "operand" | "nested";
+interface NodeBase {
+    readonly pointer: Pointer;
+}
+/** A value that the program gives as it is. */
+export interface LiteralNode extends NodeBase {
+    readonly kind: "literal";
+    /** The value. The closure code gives this object itself, as the interpreter does. */
+    readonly value: unknown;
+    /**
+     * The source of the value. It is plain data, a `$literal`, a `$never` call or a `$ref` outside
+     * each scope. It can also be a deferred call of a procedure that takes raw input, or a folded call.
+     */
+    readonly origin: "data" | "literal" | "never" | "deferred" | "unscoped-ref" | "fold";
+}
+/** A plain object with values that the interpreter computes. The entries keep the order of `Object.entries`. */
+export interface ObjectNode extends NodeBase {
+    readonly kind: "object";
+    readonly entries: ReadonlyArray<{
+        readonly key: string;
+        readonly value: IRNode;
+    }>;
+}
+/** An array with items that the interpreter computes, from the first item to the last item. */
+export interface ArrayNode extends NodeBase {
+    readonly kind: "array";
+    readonly items: readonly IRNode[];
+}
+/** A `$ref`: it reads a name of the scope and optional fields. */
+export interface ReferenceNode extends NodeBase {
+    readonly kind: "reference";
+    /** The text of the `$ref`: a name and fields, with dots. */
+    readonly text: string;
+    readonly name: string;
+    readonly fields: readonly string[];
+    /** True in the input of a deferred call: there, an unknown name stays data for the runner. */
+    readonly deferred: boolean;
+    /** The `$ref` object of the program. A deferred input gives it for an unknown name. */
+    readonly source: unknown;
+    /** True for a reference that the compiler made (the value that `passThrough` gives). */
+    readonly synthetic: boolean;
+    /** The binding of the name. The scopes pass sets it. Undefined: no scope has the name. */
+    binding: Binding | undefined;
+}
+/** A call through the client. Its input is hydrated before the call. */
+export interface CallNode extends NodeBase {
+    readonly kind: "call";
+    readonly path: ProcedurePath;
+    readonly key: string;
+    readonly position: CallPosition;
+    readonly input: IRNode;
+    /** The parent context (`cwd`, `node`) that control flow adds to the input of an operand call. */
+    readonly extra: Readonly<Record<string, unknown>>;
+    /** The `$name` of the call. Only a chain step binds it. */
+    readonly name: string | undefined;
+}
+/** A call that waits for its runner (`$parent` or a context name): it is data, with its input hydrated. */
+export interface DeferredNode extends NodeBase {
+    readonly kind: "deferred";
+    readonly path: ProcedurePath;
+    readonly key: string;
+    readonly when: string;
+    /** The call object of the program. */
+    readonly source: Readonly<Record<string, unknown>>;
+    readonly input: IRNode;
+}
+/** The reasons for a dynamic node. */
+export type DynamicReason = 
+/** The procedure runs the refs of its input (the `runs-refs` tag): `client.eval`, `dag.traverse`, `procedure.define`. */
+"runs-refs"
+/** The procedure takes its input as data (the `raw-input` tag): `client.export`. */
+ | "raw-input"
+/** The input of a control-flow procedure does not agree with its schema: the call gives the validation error. */
+ | "invalid-control-flow"
+/** The registry does not have the core control-flow procedure at the path. */
+ | "not-core"
+/** A control-flow call contains itself. */
+ | "cyclic";
+/**
+ * A call whose procedure gets its input raw, and whose operands the compiler does not model.
+ * The compiled code calls the procedure through the client with the raw input and the scope:
+ * the interpreter of the client runs it.
+ */
+export interface DynamicNode extends NodeBase {
+    readonly kind: "dynamic";
+    readonly path: ProcedurePath;
+    readonly key: string;
+    readonly position: CallPosition;
+    readonly reason: DynamicReason;
+    /** The raw input: a literal, or a value that the compiled code computes (`passThrough`). */
+    readonly input: IRNode;
+    readonly extra: Readonly<Record<string, unknown>>;
+    /** What the procedure runs, when the compiler can see it (`client.eval` of a literal path). Only the checks read it. */
+    readonly model: IRNode | undefined;
+    /** The scope that the call gets (`withScope`). The scopes pass sets it. */
+    scope: ScopeSnapshot;
+}
+/** A step of the interpreter that throws: a hydration limit, or a `fn` that is not a call. */
+export interface FailNode extends NodeBase {
+    readonly kind: "fail";
+    readonly message: string;
+}
+interface ControlBase extends NodeBase {
+    readonly path: ProcedurePath;
+    readonly key: string;
+    readonly position: CallPosition;
+}
+/** One step of a chain. */
+export interface ChainStep {
+    readonly pointer: Pointer;
+    readonly node: IRNode;
+    /** The result of the step: `$last` and `passThrough` read it, and `$name` names it. */
+    readonly result: Binding;
+}
+/** `client.chain`, or an array of calls that runs as one chain (an implicit chain). */
+export interface ChainNode extends ControlBase {
+    readonly kind: "chain";
+    readonly implicit: boolean;
+    readonly steps: readonly ChainStep[];
+    readonly passThrough: boolean;
+    /** The hydrated `initialInput` when `passThrough` is true. */
+    readonly initialInput: IRNode | undefined;
+    readonly initial: Binding | undefined;
+}
+/** `client.parallel`. */
+export interface ParallelNode extends ControlBase {
+    readonly kind: "parallel";
+    readonly tasks: readonly IRNode[];
+    readonly concurrency: number | undefined;
+    readonly failFast: boolean;
+}
+/** `client.conditional`. An absent branch is undefined: the result is undefined, and nothing runs. */
+export interface ConditionalNode extends ControlBase {
+    readonly kind: "conditional";
+    readonly condition: IRNode;
+    readonly then: IRNode | undefined;
+    readonly else: IRNode | undefined;
+}
+/** `client.tryCatch`. */
+export interface TryNode extends ControlBase {
+    readonly kind: "try";
+    readonly try: IRNode;
+    readonly catch: IRNode;
+    readonly error: Binding;
+}
+/** `client.and` and `client.or`. */
+export interface LogicNode extends ControlBase {
+    readonly kind: "and" | "or";
+    readonly values: readonly IRNode[];
+}
+/** The `items` of `client.map` and `client.reduce`: an array whose items are hydrated one by one, or one value. */
+export type ItemsSpec = {
+    readonly kind: "list";
+    readonly items: readonly IRNode[];
+} | {
+    readonly kind: "value";
+    readonly value: IRNode;
+};
+/** `client.map`. */
+export interface MapNode extends ControlBase {
+    readonly kind: "map";
+    readonly items: ItemsSpec;
+    readonly fn: IRNode | undefined;
+    readonly item: Binding;
+    readonly index: Binding;
+}
+/** `client.reduce`. Without `fn`, the result is the hydrated `initial` (or `accumulated`), and the items do not run. */
+export interface ReduceNode extends ControlBase {
+    readonly kind: "reduce";
+    readonly items: ItemsSpec | undefined;
+    readonly initial: IRNode;
+    readonly fn: IRNode | undefined;
+    readonly acc: Binding;
+    readonly item: Binding;
+    readonly index: Binding;
+}
+/** The nodes of the control flow. */
+export type ControlNode = ChainNode | ParallelNode | ConditionalNode | TryNode | LogicNode | MapNode | ReduceNode;
+/** A node of the IR. */
+export type IRNode = LiteralNode | ObjectNode | ArrayNode | ReferenceNode | CallNode | DeferredNode | DynamicNode | FailNode | ControlNode;
+/** The IR of a program. */
+export interface ProgramIR {
+    /** `exec`: the program runs as `client.exec()` runs it. `body`: as the body of a defined procedure. */
+    readonly mode: "exec" | "body";
+    readonly root: IRNode;
+    /** The binding of `input` in the body mode. */
+    readonly input: Binding | undefined;
+    /** The number of bindings: the ids go from 0 to this number minus one. */
+    readonly bindingCount: number;
+    /** The program, as the source of the IR. */
+    readonly program: unknown;
+}
+/** True for the nodes that call a procedure (a control-flow node is a call in the interpreter). */
+export declare function isCallLike(node: IRNode): node is CallNode | DynamicNode | ControlNode;
+/** True for a control-flow node. */
+export declare function isControl(node: IRNode): node is ControlNode;
+/** The child nodes of a node, in the order of the interpreter. A dynamic node gives its input, not its model. */
+export declare function childrenOf(node: IRNode): IRNode[];
+/** This function calls `visit` for each node of the tree, parents before children. */
+export declare function walk(node: IRNode, visit: (node: IRNode) => void): void;
+export {};
+//# sourceMappingURL=ir.d.ts.map

package/dist/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../src/ir.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,gFAAgF;AAChF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAE5E;AAED,+DAA+D;AAC/D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5F;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED,2FAA2F;AAC3F,MAAM,MAAM,aAAa,GAAG,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;AAE9D,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD,UAAU,QAAQ;IAChB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,MAAM,CAAC;CACtF;AAED,gHAAgH;AAChH,MAAM,WAAW,UAAW,SAAQ,QAAQ;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnF;AAED,+FAA+F;AAC/F,MAAM,WAAW,SAAU,SAAQ,QAAQ;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAc,SAAQ,QAAQ;IAC7C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0FAA0F;IAC1F,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,2GAA2G;AAC3G,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,MAAM,aAAa;AACvB,yHAAyH;AACvH,WAAW;AACb,oFAAoF;GAClF,WAAW;AACb,iHAAiH;GAC/G,sBAAsB;AACxB,8EAA8E;GAC5E,UAAU;AACZ,2CAA2C;GACzC,QAAQ,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,wHAAwH;IACxH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,2EAA2E;IAC3E,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,8FAA8F;AAC9F,MAAM,WAAW,QAAS,SAAQ,QAAQ;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,UAAU,WAAY,SAAQ,QAAQ;IACpC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED,yBAAyB;AACzB,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,sGAAsG;AACtG,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,yBAAyB;AACzB,MAAM,WAAW,OAAQ,SAAQ,WAAW;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,oCAAoC;AACpC,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,mHAAmH;AACnH,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,oBAAoB;AACpB,MAAM,WAAW,OAAQ,SAAQ,WAAW;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wHAAwH;AACxH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAElH,wBAAwB;AACxB,MAAM,MAAM,MAAM,GACd,WAAW,GACX,UAAU,GACV,SAAS,GACT,aAAa,GACb,QAAQ,GACR,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAEhB,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,QAAQ,GAAG,WAAW,GAAG,WAAW,CAErF;AAED,oCAAoC;AACpC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,WAAW,CAc3D;AAED,iHAAiH;AACjH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BjD;AAMD,sFAAsF;AACtF,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAGtE"}

package/dist/ir.js

@@ -0,0 +1,74 @@
+/**
+ * The intermediate representation (IR) of a program.
+ *
+ * The normalize pass makes the IR from the JSON of a program. Each node is one step of the
+ * interpreter: `hydrateInput()` or a control-flow procedure of `@procedures/client`. The code
+ * generation follows the IR in the order of the interpreter. Each node keeps the JSON pointer
+ * (RFC 6901) of its source in the program.
+ */
+/** This function gives the pointer of a child: the key is escaped as RFC 6901 tells. */
+export function childPointer(pointer, key) {
+    return `${pointer}/${String(key).replace(/~/g, "~0").replace(/\//g, "~1")}`;
+}
+/** True for the nodes that call a procedure (a control-flow node is a call in the interpreter). */
+export function isCallLike(node) {
+    return node.kind === "call" || node.kind === "dynamic" || isControl(node);
+}
+/** True for a control-flow node. */
+export function isControl(node) {
+    switch (node.kind) {
+        case "chain":
+        case "parallel":
+        case "conditional":
+        case "try":
+        case "and":
+        case "or":
+        case "map":
+        case "reduce":
+            return true;
+        default:
+            return false;
+    }
+}
+/** The child nodes of a node, in the order of the interpreter. A dynamic node gives its input, not its model. */
+export function childrenOf(node) {
+    switch (node.kind) {
+        case "literal":
+        case "reference":
+        case "fail":
+            return [];
+        case "object":
+            return node.entries.map((entry) => entry.value);
+        case "array":
+            return [...node.items];
+        case "call":
+        case "deferred":
+        case "dynamic":
+            return [node.input];
+        case "chain":
+            return [...(node.initialInput ? [node.initialInput] : []), ...node.steps.map((step) => step.node)];
+        case "parallel":
+            return [...node.tasks];
+        case "conditional":
+            return [node.condition, ...(node.then ? [node.then] : []), ...(node.else ? [node.else] : [])];
+        case "try":
+            return [node.try, node.catch];
+        case "and":
+        case "or":
+            return [...node.values];
+        case "map":
+            return [...itemsChildren(node.items), ...(node.fn ? [node.fn] : [])];
+        case "reduce":
+            return [...(node.items ? itemsChildren(node.items) : []), node.initial, ...(node.fn ? [node.fn] : [])];
+    }
+}
+function itemsChildren(items) {
+    return items.kind === "list" ? [...items.items] : [items.value];
+}
+/** This function calls `visit` for each node of the tree, parents before children. */
+export function walk(node, visit) {
+    visit(node);
+    for (const child of childrenOf(node))
+        walk(child, visit);
+}
+//# sourceMappingURL=ir.js.map

package/dist/ir.js.map

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

package/dist/mermaid.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A Mermaid flowchart of a program (roadmap R23).
+ *
+ * The diagram comes from the IR, so it shows what the interpreter does:
+ *
+ * - A solid arrow is the order of the interpreter. A call in an input starts before its call.
+ * - A chain is a subgraph with its steps in order. A parallel call has a fork and a join.
+ * - A conditional call is a decision with a `then` arrow and an `else` arrow.
+ * - A `client.tryCatch` call has a `try` subgraph and an `error` arrow to its catch part.
+ * - A map or a reduce has a loop node: an arrow to `fn` for each item, and an arrow back.
+ * - The operands of `client.and` and `client.or` are in order, with a stop arrow from each operand.
+ * - A dotted arrow goes from the part that binds a name to each `$ref` that reads the name.
+ * - A dynamic call and a deferred call have their own class and a second line of text.
+ *
+ * Each label goes through `mermaidText()`, so no text of a program can break the syntax.
+ */
+import type { ProgramIR } from "./ir.js";
+import type { Diagnostic } from "./diagnostics.js";
+import { type CheckOptions } from "./program.js";
+/** The options of `toMermaid()`. */
+export interface MermaidOptions {
+    /** The direction of the flowchart: `TD` (from the top down, the default) or `LR` (from left to right). */
+    readonly direction?: "TD" | "LR" | undefined;
+    /** The diagnostics of the check. A node with an error at its pointer gets the class `error`. */
+    readonly diagnostics?: readonly Diagnostic[] | undefined;
+}
+/**
+ * This function makes a text safe for a quoted Mermaid label. It keeps letters, digits, spaces
+ * and some punctuation. It writes each other character as an entity code (`#34;` for a quote).
+ * Thus quotes, brackets, `<`, `#`, line breaks and the Unicode line separators cannot break the
+ * syntax. A text longer than `limit` characters ends with three dots.
+ */
+export declare function mermaidText(text: string, limit?: number): string;
+/**
+ * This function gives a Mermaid flowchart of the IR of a program. The flowchart shows the order
+ * of the calls, the control flow and the names. The text has the same lines for the same IR.
+ */
+export declare function toMermaid(ir: ProgramIR, options?: MermaidOptions): string;
+/** The result of `diagramProgram()`. */
+export interface DiagramResult {
+    /** True when no diagnostic is an error. */
+    readonly ok: boolean;
+    /** The text of the Mermaid flowchart. */
+    readonly mermaid: string;
+    /** The diagnostics of the check, in the order of the program. */
+    readonly diagnostics: Diagnostic[];
+}
+/**
+ * This function checks a program and gives the Mermaid flowchart of its IR. A node with an error
+ * gets the class `error`. No call of the program starts.
+ */
+export declare function diagramProgram(program: unknown, options: CheckOptions & Pick<MermaidOptions, "direction">): DiagramResult;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/mermaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../src/mermaid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAkG,SAAS,EAAsC,MAAM,SAAS,CAAC;AAC7K,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAE/D,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;CAC1D;AAQD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,MAAM,CAI5E;AAgYD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,MAAM,CAE7E;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,aAAa,CAOzH"}