@itmetsam/samurai-framework 0.2.3 → 0.4.0

package/dist/flows/core/expression/parse.js

@@ -0,0 +1,317 @@
+class Fail extends Error {
+    constructor(message, at) {
+        super(message);
+        this.at = at;
+    }
+}
+const PUNCT = [
+    "==",
+    "!=",
+    "<=",
+    ">=",
+    "&&",
+    "||",
+    "<",
+    ">",
+    "!",
+    "+",
+    "-",
+    "*",
+    "/",
+    "%",
+    "(",
+    ")",
+    "[",
+    "]",
+    ".",
+    ",",
+];
+function tokenize(text) {
+    const tokens = [];
+    let i = 0;
+    // A "/" starts a regex only where a value is expected: after "(" or ","
+    const valueExpected = () => {
+        const last = tokens[tokens.length - 1];
+        return last?.kind === "punct" && (last.value === "(" || last.value === ",");
+    };
+    while (i < text.length) {
+        const c = text[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        const start = i;
+        if (/[0-9]/.test(c)) {
+            while (/[0-9]/.test(text[i] ?? ""))
+                i++;
+            if (text[i] === "." && /[0-9]/.test(text[i + 1] ?? "")) {
+                i++;
+                while (/[0-9]/.test(text[i] ?? ""))
+                    i++;
+            }
+            if (text[i] === ".")
+                throw new Fail("Invalid number", start);
+            tokens.push({
+                kind: "num",
+                value: Number(text.slice(start, i)),
+                start,
+                end: i,
+            });
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(c)) {
+            while (/[\w$]/.test(text[i] ?? ""))
+                i++;
+            tokens.push({
+                kind: "ident",
+                value: text.slice(start, i),
+                start,
+                end: i,
+            });
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            let value = "";
+            i++;
+            while (i < text.length && text[i] !== c) {
+                if (text[i] === "\\" && i + 1 < text.length)
+                    i++;
+                value += text[i++];
+            }
+            if (i >= text.length)
+                throw new Fail("Missing closing quote", start);
+            i++;
+            tokens.push({ kind: "str", value, start, end: i });
+            continue;
+        }
+        if (c === "/" && valueExpected()) {
+            i++;
+            let pattern = "";
+            while (i < text.length && text[i] !== "/") {
+                if (text[i] === "\\" && i + 1 < text.length)
+                    pattern += text[i++];
+                pattern += text[i++];
+            }
+            if (i >= text.length)
+                throw new Fail("Missing closing /", start);
+            i++;
+            let flags = "";
+            while (/[gimsuy]/.test(text[i] ?? ""))
+                flags += text[i++];
+            tokens.push({ kind: "regex", pattern, flags, start, end: i });
+            continue;
+        }
+        if (c === "=" && text[i + 1] !== "=")
+            throw new Fail("Use == to compare", start);
+        const p = PUNCT.find((x) => text.startsWith(x, i));
+        if (!p)
+            throw new Fail(`Unexpected "${c}"`, start);
+        i += p.length;
+        tokens.push({ kind: "punct", value: p, start, end: i });
+    }
+    tokens.push({ kind: "end", start: text.length, end: text.length });
+    return tokens;
+}
+const BINARY = {
+    "||": 1,
+    "&&": 2,
+    "==": 3,
+    "!=": 3,
+    "<": 4,
+    "<=": 4,
+    ">": 4,
+    ">=": 4,
+    "+": 5,
+    "-": 5,
+    "*": 6,
+    "/": 6,
+    "%": 6,
+};
+function parser(text, tokens) {
+    let pos = 0;
+    const peek = () => tokens[pos];
+    const next = () => tokens[pos++];
+    const isPunct = (v) => peek().kind === "punct" && peek().value === v;
+    const show = (t) => t.kind === "end" ? "the end" : `"${text.slice(t.start, t.end)}"`;
+    function expect(v, after) {
+        if (!isPunct(v)) {
+            const shown = text.slice(after.start, peek().start).trim();
+            throw new Fail(`Expected "${v}" after "${shown}"`, peek().start);
+        }
+        next();
+    }
+    function primary() {
+        const t = next();
+        switch (t.kind) {
+            case "num":
+                return { type: "literal", value: t.value, start: t.start };
+            case "str":
+                return { type: "literal", value: t.value, start: t.start };
+            case "regex":
+                return {
+                    type: "regex",
+                    pattern: t.pattern,
+                    flags: t.flags,
+                    start: t.start,
+                };
+            case "ident": {
+                if (t.value === "true" || t.value === "false")
+                    return { type: "literal", value: t.value === "true", start: t.start };
+                if (t.value === "null")
+                    return { type: "literal", value: null, start: t.start };
+                if (isPunct("(")) {
+                    next();
+                    const args = [];
+                    if (!isPunct(")")) {
+                        do
+                            args.push(expression(0));
+                        while (isPunct(",") && next());
+                    }
+                    const call = {
+                        type: "call",
+                        callee: t.value,
+                        args,
+                        start: t.start,
+                    };
+                    expect(")", call);
+                    return call;
+                }
+                return { type: "name", name: t.value, start: t.start };
+            }
+            case "punct":
+                if (t.value === "(") {
+                    const inner = expression(0);
+                    expect(")", { ...inner, start: t.start + 1 });
+                    return inner;
+                }
+                if (t.value === "!" || t.value === "-")
+                    return {
+                        type: "unary",
+                        op: t.value,
+                        arg: postfix(primary()),
+                        start: t.start,
+                    };
+                throw new Fail(`Unexpected ${show(t)}`, t.start);
+            case "end":
+                throw new Fail(pos === 1 ? "Write an expression" : "The expression ends too early", t.start);
+        }
+    }
+    function postfix(expr) {
+        for (;;) {
+            if (isPunct(".")) {
+                next();
+                const name = next();
+                if (name.kind !== "ident")
+                    throw new Fail(`Expected a name after "."`, name.start);
+                expr = {
+                    type: "member",
+                    object: expr,
+                    property: name.value,
+                    start: expr.start,
+                };
+            }
+            else if (isPunct("[")) {
+                next();
+                const property = expression(0);
+                expect("]", property);
+                expr = { type: "member", object: expr, property, start: expr.start };
+            }
+            else if (isPunct("(")) {
+                throw new Fail("Only helpers can be called, like contains(x, y)", expr.start);
+            }
+            else
+                return expr;
+        }
+    }
+    function expression(min) {
+        let left = postfix(primary());
+        for (;;) {
+            const t = peek();
+            const prec = t.kind === "punct" ? BINARY[t.value] : undefined;
+            if (prec === undefined || prec <= min) {
+                if (min === 0 &&
+                    t.kind !== "end" &&
+                    !(t.kind === "punct" && [")", "]", ","].includes(t.value)))
+                    throw new Fail(`Unexpected ${show(t)}`, t.start);
+                return left;
+            }
+            next();
+            const right = expression(prec);
+            left = {
+                type: "binary",
+                op: t.value,
+                left,
+                right,
+                start: left.start,
+            };
+        }
+    }
+    return { expression, peek };
+}
+/** A member chain with only static parts, as a path; undefined otherwise */
+function chainOf(e) {
+    if (e.type === "name")
+        return { path: [e.name], start: e.start };
+    if (e.type !== "member")
+        return undefined;
+    const inner = chainOf(e.object);
+    if (!inner)
+        return undefined;
+    const prop = typeof e.property === "string"
+        ? e.property
+        : e.property.type === "literal" &&
+            (typeof e.property.value === "string" ||
+                typeof e.property.value === "number")
+            ? String(e.property.value)
+            : undefined;
+    return prop === undefined
+        ? undefined
+        : { path: [...inner.path, prop], start: inner.start };
+}
+function collect(e, refs, calls) {
+    switch (e.type) {
+        case "name":
+            refs.push({ path: [e.name], start: e.start });
+            return;
+        case "member": {
+            const chain = chainOf(e);
+            if (chain)
+                refs.push(chain);
+            else {
+                collect(e.object, refs, calls);
+                if (typeof e.property !== "string")
+                    collect(e.property, refs, calls);
+            }
+            return;
+        }
+        case "unary":
+            return collect(e.arg, refs, calls);
+        case "binary":
+            collect(e.left, refs, calls);
+            return collect(e.right, refs, calls);
+        case "call":
+            calls.push({ name: e.callee, args: e.args.length, start: e.start });
+            for (const a of e.args)
+                collect(a, refs, calls);
+            return;
+    }
+}
+/** Parses an expression into its syntax tree, the references it reads and the helpers it calls */
+export function parseExpression(text) {
+    try {
+        const tokens = tokenize(text);
+        const { expression, peek } = parser(text, tokens);
+        const expr = expression(0);
+        if (peek().kind !== "end")
+            throw new Fail(`Unexpected "${text.slice(peek().start, peek().end)}"`, peek().start);
+        const refs = [];
+        const calls = [];
+        collect(expr, refs, calls);
+        return { ok: true, expr, refs, calls };
+    }
+    catch (e) {
+        if (e instanceof Fail)
+            return { ok: false, error: { message: e.message, at: e.at } };
+        throw e;
+    }
+}

package/dist/flows/core/expression/scope.d.ts

@@ -0,0 +1,8 @@
+import type { AnyNodeDefinition } from "../nodes/define.js";
+import type { FlowFile } from "../schema.js";
+import type { ExpressionScope } from "./check.js";
+/** What an expression at `nodeId` may use; `nodes` adds definitions core doesn't have (steps) */
+export declare function scopeAt(flow: FlowFile, nodeId: string, environment: {
+    name: string;
+    variables: Record<string, unknown>;
+}, nodes?: readonly AnyNodeDefinition[]): ExpressionScope;

package/dist/flows/core/expression/scope.js

@@ -0,0 +1,34 @@
+import { ancestors, dominates, reachOrder } from "../graph.js";
+import { NODES } from "../nodes/index.js";
+import { getPath } from "../nodes/path.js";
+/** What an expression at `nodeId` may use; `nodes` adds definitions core doesn't have (steps) */
+export function scopeAt(flow, nodeId, environment, nodes = []) {
+    const defOf = (kind) => nodes.find((d) => d.kind === kind) ?? NODES.find((d) => d.kind === kind);
+    const keyOf = (id) => flow.nodes.find((n) => n.id === id)?.key;
+    const keys = (ids) => [...ids].map(keyOf).filter((k) => !!k);
+    const before = ancestors(flow, nodeId);
+    const after = new Set(reachOrder(flow, nodeId));
+    after.delete(nodeId);
+    const vars = flow.nodes
+        .filter((n) => n.id !== nodeId && dominates(flow, n.id, nodeId))
+        .map((n) => {
+        const path = defOf(n.kind)?.writesVar;
+        return path ? getPath(n, path) : undefined;
+    })
+        .filter((name) => typeof name === "string" && name !== "");
+    const outputs = Object.fromEntries(flow.nodes.flatMap((n) => {
+        const results = defOf(n.kind)?.results;
+        return n.key && results?.length ? [[n.key, results]] : [];
+    }));
+    return {
+        env: {
+            name: environment.name,
+            variables: Object.keys(environment.variables),
+        },
+        vars: [...new Set(vars)],
+        before: keys(before),
+        after: keys(after),
+        all: keys(flow.nodes.map((n) => n.id)),
+        outputs,
+    };
+}

package/dist/flows/core/graph.d.ts

@@ -0,0 +1,11 @@
+import type { FlowEdgeModel, FlowFile } from "./schema.js";
+/** The nodes reached from `from`, in the order a walk first meets them (`from` included) */
+export declare function reachOrder(flow: FlowFile, from: string): string[];
+/** Where the branches of a node meet: the first node the first branch reaches that every other branch reaches too */
+export declare function meetOf(flow: FlowFile, node: string): string | undefined;
+/** The edges out of a dynamic `branches` node in the order their branches were filled (by their branch-<n> name) */
+export declare const inFillOrder: (edges: FlowEdgeModel[]) => FlowEdgeModel[];
+/** Every node with a path to `nodeId` (not the node itself) */
+export declare function ancestors(flow: FlowFile, nodeId: string): Set<string>;
+/** Whether every path from Start to `n` passes `d` */
+export declare function dominates(flow: FlowFile, d: string, n: string): boolean;

package/dist/flows/core/graph.js

@@ -0,0 +1,65 @@
+/** The nodes reached from `from`, in the order a walk first meets them (`from` included) */
+export function reachOrder(flow, from) {
+    const order = [];
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        order.push(id);
+        for (const e of flow.edges)
+            if (e.source === id)
+                visit(e.target);
+    };
+    visit(from);
+    return order;
+}
+/** Where the branches of a node meet: the first node the first branch reaches that every other branch reaches too */
+export function meetOf(flow, node) {
+    const out = flow.edges.filter((e) => e.source === node);
+    if (out.length === 0)
+        return undefined;
+    const others = out.slice(1).map((e) => new Set(reachOrder(flow, e.target)));
+    return reachOrder(flow, out[0].target).find((id) => others.every((reach) => reach.has(id)));
+}
+/** The edges out of a dynamic `branches` node in the order their branches were filled (by their branch-<n> name) */
+export const inFillOrder = (edges) => {
+    const index = (e) => Number(e.sourceHandle?.match(/^branch-(\d+)$/)?.[1] ?? 1e9);
+    return [...edges].sort((a, b) => index(a) - index(b));
+};
+/** Every node with a path to `nodeId` (not the node itself) */
+export function ancestors(flow, nodeId) {
+    const seen = new Set();
+    const visit = (id) => {
+        for (const e of flow.edges)
+            if (e.target === id && !seen.has(e.source)) {
+                seen.add(e.source);
+                visit(e.source);
+            }
+    };
+    visit(nodeId);
+    seen.delete(nodeId);
+    return seen;
+}
+/** Whether every path from Start to `n` passes `d` */
+export function dominates(flow, d, n) {
+    const start = flow.nodes.find((x) => x.kind === "start");
+    if (!start || d === n)
+        return d === n;
+    if (d === start.id)
+        return true;
+    const seen = new Set([d]);
+    const stack = [start.id];
+    while (stack.length) {
+        const id = stack.pop();
+        if (id === n)
+            return false;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        for (const e of flow.edges)
+            if (e.source === id)
+                stack.push(e.target);
+    }
+    return true;
+}

package/dist/flows/core/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The pure half of flows: the file format, keys, graph helpers and the expression language.
+ * No Node APIs, so a browser bundle (the SAMURAI app's renderer) can import it.
+ */
+export * from "./schema.js";
+export * from "./keys.js";
+export * from "./graph.js";
+export * from "./expression/index.js";
+export * from "./nodes/index.js";
+export * from "./check.js";
+export * from "./steps.js";
+/**
+ * Version of the contract between the SAMURAI app and this framework.
+ * Increments whenever the app and the framework must agree on something new
+ * (a node kind, a field, an event), so the app can tell when the framework is too old.
+ */
+export declare const FLOWS_API = 2;

package/dist/flows/core/index.js

@@ -0,0 +1,17 @@
+/**
+ * The pure half of flows: the file format, keys, graph helpers and the expression language.
+ * No Node APIs, so a browser bundle (the SAMURAI app's renderer) can import it.
+ */
+export * from "./schema.js";
+export * from "./keys.js";
+export * from "./graph.js";
+export * from "./expression/index.js";
+export * from "./nodes/index.js";
+export * from "./check.js";
+export * from "./steps.js";
+/**
+ * Version of the contract between the SAMURAI app and this framework.
+ * Increments whenever the app and the framework must agree on something new
+ * (a node kind, a field, an event), so the app can tell when the framework is too old.
+ */
+export const FLOWS_API = 2;

package/dist/flows/core/keys.d.ts

@@ -0,0 +1,8 @@
+import type { FlowFile, FlowNodeModel } from "./schema.js";
+export declare const KEY_PATTERN: RegExp;
+/** What a node's key is made from: its title, else its test's name (last part), else its group, else its kind */
+export declare function keyBase(node: FlowNodeModel): string;
+/** `base`, or `base_2`, `base_3` … when taken */
+export declare function uniqueKey(base: string, taken: Set<string>): string;
+/** Gives every node a valid, unique key; nodes that have one keep it (the first of a duplicate keeps it) */
+export declare function withKeys(flow: FlowFile): FlowFile;

package/dist/flows/core/keys.js

@@ -0,0 +1,46 @@
+export const KEY_PATTERN = /^[a-z][a-z0-9_]*$/;
+const slug = (text) => {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return !s ? "" : /^[a-z]/.test(s) ? s : `n${s}`;
+};
+/** What a node's key is made from: its title, else its test's name (last part), else its group, else its kind */
+export function keyBase(node) {
+    const testName = node.ref?.testId?.split("::").pop()?.split(" > ").pop();
+    return (slug(node.title ?? "") ||
+        slug(testName ?? "") ||
+        slug(node.ref?.group ?? "") ||
+        slug(node.kind) ||
+        "node");
+}
+/** `base`, or `base_2`, `base_3` … when taken */
+export function uniqueKey(base, taken) {
+    if (!taken.has(base))
+        return base;
+    let i = 2;
+    while (taken.has(`${base}_${i}`))
+        i++;
+    return `${base}_${i}`;
+}
+/** Gives every node a valid, unique key; nodes that have one keep it (the first of a duplicate keeps it) */
+export function withKeys(flow) {
+    const taken = new Set();
+    const keeps = new Set();
+    for (const node of flow.nodes)
+        if (node.key && KEY_PATTERN.test(node.key) && !taken.has(node.key)) {
+            taken.add(node.key);
+            keeps.add(node);
+        }
+    if (keeps.size === flow.nodes.length)
+        return flow;
+    const nodes = flow.nodes.map((node) => {
+        if (keeps.has(node))
+            return node;
+        const key = uniqueKey(keyBase(node), taken);
+        taken.add(key);
+        return { ...node, key };
+    });
+    return { ...flow, nodes };
+}

package/dist/flows/core/nodes/condition.d.ts

@@ -0,0 +1,7 @@
+export declare const condition: import("./define.js").NodeCoreDefinition<"condition", import("./define.js").ConfigOf<readonly [{
+    readonly path: "config.expr";
+    readonly type: "expression";
+    readonly label: "Expression";
+    readonly placeholder: "nodes.login.status == \"passed\"";
+    readonly default: "";
+}]>>;

package/dist/flows/core/nodes/condition.js

@@ -0,0 +1,21 @@
+import { defineNode } from "./define.js";
+export const condition = defineNode({
+    kind: "condition",
+    label: "Condition",
+    shape: "branches",
+    branches: [
+        { name: "true", label: "true", color: "success" },
+        { name: "false", label: "false", color: "error" },
+    ],
+    fields: [
+        {
+            path: "config.expr",
+            type: "expression",
+            label: "Expression",
+            placeholder: 'nodes.login.status == "passed"',
+            default: "",
+        },
+    ],
+    outputs: true,
+    onFailure: true,
+});