@itmetsam/samurai-framework 0.2.2 → 0.3.0

package/dist/flows/core/check.js

@@ -0,0 +1,202 @@
+import { problemOf, scopeAt } from "./expression/index.js";
+import { KEY_PATTERN } from "./keys.js";
+import { branchNames, dynamicOf, getPath, nodeDef, withDefaults, } from "./nodes/index.js";
+/** What the node is called in a message: its title, else its key, else its kind's label */
+const titleOf = (node, def) => node.title || node.key || def?.label || node.kind;
+const defOf = (kind) => {
+    try {
+        return nodeDef(kind);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Node ids in the order a run reaches them: from Start, following edges */
+function reachableFrom(flow, startId) {
+    const out = new Map();
+    for (const e of flow.edges)
+        out.set(e.source, [...(out.get(e.source) ?? []), e.target]);
+    const known = new Set(flow.nodes.map((n) => n.id));
+    const seen = new Set();
+    const visit = (id) => {
+        if (seen.has(id) || !known.has(id))
+            return;
+        seen.add(id);
+        for (const next of out.get(id) ?? [])
+            visit(next);
+    };
+    if (startId)
+        visit(startId);
+    return seen;
+}
+/**
+ * Checks a flow before a run: the shape of the graph, keys, references that still
+ * exist, expressions, and what a run can't execute. Pure; returns every problem.
+ * Messages are the SAMURAI app's, except that a node is named by its `title`, else
+ * its key, else its kind's label (the app names it by what the editor shows).
+ */
+export function checkFlow(flow, options = {}) {
+    const problems = [];
+    const tests = options.tests ? new Set(options.tests) : undefined;
+    const groups = options.groups ? new Set(options.groups) : undefined;
+    const shapeOf = (n) => defOf(n.kind)?.shape;
+    for (const n of flow.nodes)
+        if (!defOf(n.kind))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `Unknown node kind: ${n.kind}`,
+            });
+    const starts = flow.nodes.filter((n) => shapeOf(n) === "start");
+    const ends = flow.nodes.filter((n) => shapeOf(n) === "end");
+    if (starts.length !== 1)
+        problems.push({ level: "error", message: "A flow has exactly one Start." });
+    if (ends.length !== 1)
+        problems.push({ level: "error", message: "A flow has exactly one End." });
+    const reachable = reachableFrom(flow, starts[0]?.id);
+    // Can reach End: walk edges backwards from End
+    const back = new Map();
+    for (const e of flow.edges)
+        back.set(e.target, [...(back.get(e.target) ?? []), e.source]);
+    const toEnd = new Set();
+    const walk = (id) => {
+        if (toEnd.has(id))
+            return;
+        toEnd.add(id);
+        (back.get(id) ?? []).forEach(walk);
+    };
+    ends.forEach((e) => walk(e.id));
+    for (const n of flow.nodes) {
+        const def = defOf(n.kind);
+        const title = options.titles?.(n) ?? titleOf(n, def);
+        if (!reachable.has(n.id))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `${title} isn't reachable from Start.`,
+            });
+        else if (!toEnd.has(n.id))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `${title} doesn't lead to End.`,
+            });
+        if (!def)
+            continue;
+        const names = branchNames(n);
+        const outCount = flow.edges.filter((e) => e.source === n.id).length;
+        if (dynamicOf(n) && outCount < names.length)
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `${title} needs at least ${names.length} branches.`,
+            });
+        else if (!dynamicOf(n) &&
+            names.length &&
+            !names.every((h) => flow.edges.some((e) => e.source === n.id && e.sourceHandle === h)))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: names.length === 2
+                    ? `${title} needs both a ${names[0]} and a ${names[1]} branch.`
+                    : `${title} needs a branch for each of ${names.join(", ")}.`,
+            });
+        const ctx = { label: def.label, tests, groups };
+        problems.push(...(def.validate?.(withDefaults(def, n), ctx) ?? []));
+        if (options.handled &&
+            (def.shape === "step" || def.shape === "branches") &&
+            !options.handled.has(n.kind)) {
+            problems.push(options.unsupported === "fail"
+                ? {
+                    level: "error",
+                    nodeId: n.id,
+                    message: `${def.label} can't run yet.`,
+                }
+                : {
+                    level: "warning",
+                    nodeId: n.id,
+                    message: `${def.label} nodes can't run yet. They are skipped.`,
+                });
+        }
+    }
+    const seen = new Map();
+    for (const n of flow.nodes) {
+        if (!n.key)
+            continue;
+        if (!KEY_PATTERN.test(n.key))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `"${n.key}" isn't a valid key. Use lowercase letters, digits and _, starting with a letter.`,
+            });
+        else if (seen.has(n.key))
+            problems.push({
+                level: "error",
+                nodeId: n.id,
+                message: `The key "${n.key}" is used by another node.`,
+            });
+        else
+            seen.set(n.key, n.id);
+    }
+    problems.push(...emptyExpressions(flow));
+    if (options.environment)
+        problems.push(...expressionProblems(flow, options.environment));
+    const nodeCount = flow.nodes.filter((n) => {
+        const s = shapeOf(n);
+        return s !== "start" && s !== "end";
+    }).length;
+    if (nodeCount > 0 &&
+        flow.edges.some((e) => shapeOf(flow.nodes.find((n) => n.id === e.source) ?? {}) ===
+            "start" &&
+            shapeOf(flow.nodes.find((n) => n.id === e.target) ?? {}) ===
+                "end"))
+        problems.push({
+            level: "error",
+            message: "Start connects straight to End, skipping the nodes in between.",
+        });
+    return problems;
+}
+/** Every expression field left empty: it would stop the run at its node */
+function emptyExpressions(flow) {
+    return flow.nodes.flatMap((n) => {
+        const def = defOf(n.kind);
+        if (!def)
+            return [];
+        return def.fields
+            .filter((f) => f.type === "expression")
+            .filter((f) => {
+            const text = getPath(n, f.path);
+            return (text === undefined || (typeof text === "string" && text.trim() === ""));
+        })
+            .map(() => ({
+            level: "error",
+            nodeId: n.id,
+            message: `${def.label}: Write an expression`,
+        }));
+    });
+}
+/** Every expression field that doesn't check out, as "Label: message" */
+export function expressionProblems(flow, environment) {
+    return flow.nodes.flatMap((n) => {
+        const def = defOf(n.kind);
+        if (!def)
+            return [];
+        return def.fields
+            .filter((f) => f.type === "expression")
+            .flatMap((f) => {
+            const text = getPath(n, f.path);
+            if (typeof text !== "string" || text.trim() === "")
+                return [];
+            const problem = problemOf(text, scopeAt(flow, n.id, environment));
+            return problem
+                ? [
+                    {
+                        level: "error",
+                        nodeId: n.id,
+                        message: `${def.label}: ${problem.message}`,
+                    },
+                ]
+                : [];
+        });
+    });
+}

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

@@ -0,0 +1,21 @@
+import { type ExpressionError, type Parsed } from "./parse.js";
+export interface ExpressionScope {
+    /** The flow environment's name and its variable names */
+    env: {
+        name: string;
+        variables: string[];
+    };
+    /** Variables set before this node, on every path */
+    vars: string[];
+    /** Keys of nodes before this node (on some path) */
+    before: string[];
+    /** Keys of nodes after this node */
+    after: string[];
+    /** Every key in the flow */
+    all: string[];
+}
+export declare const NODE_FIELDS: readonly ["status", "durationMs", "error"];
+export declare const RUN_FIELDS: readonly ["environment", "trigger", "startedAt"];
+export declare function checkExpression(parsed: Parsed, scope: ExpressionScope): ExpressionError | undefined;
+/** Parse + check in one: the first problem, if any */
+export declare const problemOf: (text: string, scope: ExpressionScope) => ExpressionError | undefined;

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

@@ -0,0 +1,95 @@
+import { HELPER_ARGS, HELPERS } from "./evaluate.js";
+import { parseExpression } from "./parse.js";
+export const NODE_FIELDS = ["status", "durationMs", "error"];
+export const RUN_FIELDS = ["environment", "trigger", "startedAt"];
+const list = (items) => items.length <= 1
+    ? items.join("")
+    : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+function distance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [
+        i,
+        ...Array(b.length).fill(0),
+    ]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++)
+        for (let j = 1; j <= b.length; j++)
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return d[a.length][b.length];
+}
+/** The closest name, when it's a likely typo */
+const closest = (name, options) => options.find((o) => o.toLowerCase() === name.toLowerCase()) ??
+    options
+        .filter((o) => distance(o, name) <= 2)
+        .sort((a, b) => distance(a, name) - distance(b, name))[0];
+export function checkExpression(parsed, scope) {
+    if (!parsed.ok)
+        return parsed.error;
+    for (const call of parsed.calls) {
+        if (!HELPERS.includes(call.name)) {
+            const near = closest(call.name, HELPERS);
+            return {
+                message: near
+                    ? `${call.name}() doesn't exist. Did you mean ${near}()?`
+                    : `${call.name}() doesn't exist. Use ${list(HELPERS)}.`,
+                at: call.start,
+            };
+        }
+        const want = HELPER_ARGS[call.name];
+        if (call.args !== want)
+            return {
+                message: `${call.name}() takes ${want} ${want === 1 ? "value" : "values"}`,
+                at: call.start,
+            };
+    }
+    for (const { path, start: at } of parsed.refs) {
+        const [root, name, field] = path;
+        if (!["env", "vars", "nodes", "run"].includes(root))
+            return {
+                message: `${root} isn't available. Use env., vars., nodes. or run.`,
+                at,
+            };
+        if (name === undefined)
+            return {
+                message: `Use ${root}.<${root === "nodes" ? "key" : root === "run" ? "field" : "name"}>`,
+                at,
+            };
+        if (root === "env" && !scope.env.variables.includes(name))
+            return { message: `${name} isn't a variable of ${scope.env.name}`, at };
+        if (root === "vars" && !scope.vars.includes(name))
+            return { message: `vars.${name} isn't set before this node`, at };
+        if (root === "run" && !RUN_FIELDS.includes(name))
+            return {
+                message: `run.${name} doesn't exist. Use ${list(RUN_FIELDS)}`,
+                at,
+            };
+        if (root === "nodes") {
+            if (!scope.all.includes(name)) {
+                const near = closest(name, scope.all);
+                return {
+                    message: `No node with key "${name}"${near ? `. Did you mean ${near}?` : ""}`,
+                    at,
+                };
+            }
+            if (scope.after.includes(name))
+                return {
+                    message: `${name} runs after this node, so it has no result yet`,
+                    at,
+                };
+            if (!scope.before.includes(name))
+                return {
+                    message: `${name} is on another branch, so it has no result here`,
+                    at,
+                };
+            if (field !== undefined &&
+                !NODE_FIELDS.includes(field))
+                return {
+                    message: `nodes.${name}.${field} doesn't exist. Use ${list(NODE_FIELDS)}`,
+                    at,
+                };
+        }
+    }
+    return undefined;
+}
+/** Parse + check in one: the first problem, if any */
+export const problemOf = (text, scope) => checkExpression(parseExpression(text), scope);

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

@@ -0,0 +1,22 @@
+import { type Expr } from "./parse.js";
+export interface ExpressionContext {
+    env: Record<string, unknown>;
+    vars: Record<string, unknown>;
+    nodes: Record<string, {
+        status: string;
+        durationMs?: number;
+        error?: string;
+    }>;
+    run: {
+        environment: string;
+        trigger: string;
+        startedAt: string;
+    };
+}
+export declare const HELPERS: readonly ["contains", "startsWith", "matches", "len", "exists"];
+export declare const HELPER_ARGS: Record<(typeof HELPERS)[number], number>;
+export declare class EvaluationError extends Error {
+}
+export declare function evaluate(expr: Expr, context: ExpressionContext): unknown;
+/** Parses and evaluates; a syntax error throws an EvaluationError with the parser's message */
+export declare function evaluateText(text: string, context: ExpressionContext): unknown;

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

@@ -0,0 +1,141 @@
+import { parseExpression } from "./parse.js";
+export const HELPERS = [
+    "contains",
+    "startsWith",
+    "matches",
+    "len",
+    "exists",
+];
+export const HELPER_ARGS = {
+    contains: 2,
+    startsWith: 2,
+    matches: 2,
+    len: 1,
+    exists: 1,
+};
+export class EvaluationError extends Error {
+}
+const ROOTS = ["env", "vars", "nodes", "run"];
+/** Own, plain values only: nothing from prototypes, nothing named like an internal */
+function read(object, key) {
+    if (object === null || typeof object !== "object")
+        return undefined;
+    const name = String(key);
+    if (name.startsWith("__") || name === "constructor" || name === "prototype")
+        return undefined;
+    if (Array.isArray(object))
+        return /^\d+$/.test(name) ? object[Number(name)] : undefined;
+    return Object.prototype.hasOwnProperty.call(object, name)
+        ? object[name]
+        : undefined;
+}
+const typeName = (v) => v === null ? "null" : Array.isArray(v) ? "a list" : typeof v;
+function arithmetic(op, l, r) {
+    if (op === "+" && (typeof l === "string" || typeof r === "string")) {
+        const ok = (v) => typeof v === "string" || typeof v === "number";
+        if (ok(l) && ok(r))
+            return String(l) + String(r);
+    }
+    if (typeof l !== "number" || typeof r !== "number")
+        throw new EvaluationError(`Can't use ${op} on ${typeName(typeof l !== "number" ? l : r)}`);
+    switch (op) {
+        case "+":
+            return l + r;
+        case "-":
+            return l - r;
+        case "*":
+            return l * r;
+        case "/":
+            return l / r;
+        default:
+            return l % r;
+    }
+}
+function compare(op, l, r) {
+    const same = (typeof l === "number" && typeof r === "number") ||
+        (typeof l === "string" && typeof r === "string");
+    if (!same)
+        return false;
+    const a = l;
+    const b = r;
+    return op === "<"
+        ? a < b
+        : op === "<="
+            ? a <= b
+            : op === ">"
+                ? a > b
+                : a >= b;
+}
+function makeRegExp(pattern, flags) {
+    try {
+        return new RegExp(pattern, flags);
+    }
+    catch (e) {
+        throw new EvaluationError(`Invalid pattern: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const helpers = {
+    contains: (x, y) => typeof x === "string"
+        ? typeof y === "string" && x.includes(y)
+        : Array.isArray(x) && x.includes(y),
+    startsWith: (s, p) => typeof s === "string" && typeof p === "string" && s.startsWith(p),
+    matches: (s, re) => typeof s === "string" &&
+        (re instanceof RegExp
+            ? re.test(s)
+            : typeof re === "string" && makeRegExp(re).test(s)),
+    len: (x) => typeof x === "string" || Array.isArray(x)
+        ? x.length
+        : x && typeof x === "object"
+            ? Object.keys(x).length
+            : 0,
+    exists: (x) => x !== undefined && x !== null,
+};
+export function evaluate(expr, context) {
+    const go = (e) => {
+        switch (e.type) {
+            case "literal":
+                return e.value;
+            case "regex":
+                return makeRegExp(e.pattern, e.flags);
+            case "name":
+                if (!ROOTS.includes(e.name))
+                    throw new EvaluationError(`${e.name} isn't available. Use env., vars., nodes. or run.`);
+                return context[e.name];
+            case "member":
+                return read(go(e.object), typeof e.property === "string" ? e.property : go(e.property));
+            case "unary":
+                return e.op === "!" ? !go(e.arg) : arithmetic("-", 0, go(e.arg));
+            case "binary": {
+                if (e.op === "&&")
+                    return go(e.left) ? Boolean(go(e.right)) : false;
+                if (e.op === "||")
+                    return go(e.left) ? true : Boolean(go(e.right));
+                const l = go(e.left);
+                const r = go(e.right);
+                if (e.op === "==")
+                    return l === r;
+                if (e.op === "!=")
+                    return l !== r;
+                if (["<", "<=", ">", ">="].includes(e.op))
+                    return compare(e.op, l, r);
+                return arithmetic(e.op, l, r);
+            }
+            case "call": {
+                const fn = Object.prototype.hasOwnProperty.call(helpers, e.callee)
+                    ? helpers[e.callee]
+                    : undefined;
+                if (!fn)
+                    throw new EvaluationError(`${e.callee}() doesn't exist`);
+                return fn(...e.args.map(go));
+            }
+        }
+    };
+    return go(expr);
+}
+/** Parses and evaluates; a syntax error throws an EvaluationError with the parser's message */
+export function evaluateText(text, context) {
+    const parsed = parseExpression(text);
+    if (!parsed.ok)
+        throw new EvaluationError(parsed.error.message);
+    return evaluate(parsed.expr, context);
+}

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

@@ -0,0 +1,25 @@
+import { type ExpressionScope } from "./check.js";
+export interface HelpEntry {
+    label: string;
+    insert: string;
+    detail?: string;
+}
+export interface HelpSections {
+    nodes: HelpEntry[];
+    vars: HelpEntry[];
+    env: HelpEntry[];
+    run: HelpEntry[];
+}
+/** What an expression at a node can use, as entries to insert; the same names the checker accepts */
+export declare function helpEntries(scope: ExpressionScope): HelpSections;
+/** Inserts text at the cursor; returns the new value and cursor */
+export declare function insertAt(value: string, cursor: number, text: string): {
+    value: string;
+    cursor: number;
+};
+export declare const HELPER_DOCS: {
+    name: string;
+    signature: string;
+    example: string;
+    description: string;
+}[];

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

@@ -0,0 +1,75 @@
+import { NODE_FIELDS, RUN_FIELDS } from "./check.js";
+const access = (root, name) => /^[A-Za-z_$][\w$]*$/.test(name) ? `${root}.${name}` : `${root}["${name}"]`;
+const NODE_DETAIL = {
+    status: '"passed", "failed" or "skipped"',
+    durationMs: "how long it took, in ms",
+    error: "its error message, when it failed",
+};
+const RUN_DETAIL = {
+    environment: "the environment this run uses",
+    trigger: '"manual"',
+    startedAt: "when the run started (ISO time)",
+};
+/** What an expression at a node can use, as entries to insert; the same names the checker accepts */
+export function helpEntries(scope) {
+    return {
+        nodes: scope.before.flatMap((key) => NODE_FIELDS.map((f) => ({
+            label: `${key}.${f}`,
+            insert: `nodes.${key}.${f}`,
+            detail: NODE_DETAIL[f],
+        }))),
+        vars: scope.vars.map((name) => ({
+            label: name,
+            insert: access("vars", name),
+        })),
+        env: scope.env.variables.map((name) => ({
+            label: name,
+            insert: access("env", name),
+            detail: scope.env.name,
+        })),
+        run: RUN_FIELDS.map((f) => ({
+            label: f,
+            insert: `run.${f}`,
+            detail: RUN_DETAIL[f],
+        })),
+    };
+}
+/** Inserts text at the cursor; returns the new value and cursor */
+export function insertAt(value, cursor, text) {
+    return {
+        value: value.slice(0, cursor) + text + value.slice(cursor),
+        cursor: cursor + text.length,
+    };
+}
+export const HELPER_DOCS = [
+    {
+        name: "contains",
+        signature: "contains(list or text, value)",
+        example: 'contains(vars.tags, "vip")',
+        description: "Whether a list has the value, or text contains it",
+    },
+    {
+        name: "startsWith",
+        signature: "startsWith(text, start)",
+        example: 'startsWith(run.environment, "prod")',
+        description: "Whether text starts with the given text",
+    },
+    {
+        name: "matches",
+        signature: "matches(text, /pattern/)",
+        example: "matches(env.baseURL, /^https:/)",
+        description: "Whether text matches a regular expression",
+    },
+    {
+        name: "len",
+        signature: "len(list or text)",
+        example: "len(vars.items) > 0",
+        description: "How many items a list has, or characters a text",
+    },
+    {
+        name: "exists",
+        signature: "exists(value)",
+        example: "exists(vars.orderId)",
+        description: "Whether a value is set",
+    },
+];

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

@@ -0,0 +1,5 @@
+export * from "./parse.js";
+export * from "./evaluate.js";
+export * from "./check.js";
+export * from "./scope.js";
+export * from "./help.js";

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

@@ -0,0 +1,5 @@
+export * from "./parse.js";
+export * from "./evaluate.js";
+export * from "./check.js";
+export * from "./scope.js";
+export * from "./help.js";

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

@@ -0,0 +1,61 @@
+export type BinaryOp = "==" | "!=" | "<" | "<=" | ">" | ">=" | "&&" | "||" | "+" | "-" | "*" | "/" | "%";
+export type Expr = {
+    type: "literal";
+    value: string | number | boolean | null;
+    start: number;
+} | {
+    type: "regex";
+    pattern: string;
+    flags: string;
+    start: number;
+} | {
+    type: "name";
+    name: string;
+    start: number;
+} | {
+    type: "member";
+    object: Expr;
+    property: string | Expr;
+    start: number;
+} | {
+    type: "unary";
+    op: "!" | "-";
+    arg: Expr;
+    start: number;
+} | {
+    type: "binary";
+    op: BinaryOp;
+    left: Expr;
+    right: Expr;
+    start: number;
+} | {
+    type: "call";
+    callee: string;
+    args: Expr[];
+    start: number;
+};
+/** A name chain with static parts: nodes.login.status → ["nodes", "login", "status"] */
+export interface Reference {
+    path: string[];
+    start: number;
+}
+export interface CallRef {
+    name: string;
+    args: number;
+    start: number;
+}
+export interface ExpressionError {
+    message: string;
+    at: number;
+}
+export type Parsed = {
+    ok: true;
+    expr: Expr;
+    refs: Reference[];
+    calls: CallRef[];
+} | {
+    ok: false;
+    error: ExpressionError;
+};
+/** Parses an expression into its syntax tree, the references it reads and the helpers it calls */
+export declare function parseExpression(text: string): Parsed;