@bpmnkit/core 0.0.14 → 0.0.16

package/dist/bpmn/optimize/variable-flow.js

@@ -0,0 +1,431 @@
+import { parseExpression } from "@bpmnkit/feel";
+import { buildFlowIndex, readZeebeIoMapping, readZeebeTaskType } from "./utils.js";
+// ---------------------------------------------------------------------------
+// FEEL built-in names (excluded from variable references)
+// ---------------------------------------------------------------------------
+const FEEL_BUILTINS = new Set([
+    "string",
+    "string length",
+    "substring",
+    "substring before",
+    "substring after",
+    "upper case",
+    "lower case",
+    "contains",
+    "starts with",
+    "ends with",
+    "matches",
+    "replace",
+    "split",
+    "string join",
+    "number",
+    "decimal",
+    "floor",
+    "ceiling",
+    "round half up",
+    "round half down",
+    "round up",
+    "round down",
+    "abs",
+    "modulo",
+    "sqrt",
+    "log",
+    "exp",
+    "odd",
+    "even",
+    "random number",
+    "count",
+    "list contains",
+    "append",
+    "concatenate",
+    "insert before",
+    "remove",
+    "reverse",
+    "index of",
+    "union",
+    "distinct values",
+    "duplicate values",
+    "flatten",
+    "product",
+    "sum",
+    "mean",
+    "all",
+    "any",
+    "sublist",
+    "min",
+    "max",
+    "median",
+    "mode",
+    "sort",
+    "string join",
+    "date",
+    "time",
+    "date and time",
+    "duration",
+    "years and months duration",
+    "now",
+    "today",
+    "day of week",
+    "day of year",
+    "week of year",
+    "month of year",
+    "last day of month",
+    "is",
+    "is defined",
+    "not",
+    "true",
+    "false",
+    "null",
+    "and",
+    "or",
+    "instance of",
+    "get value",
+    "get entries",
+    "put",
+    "put all",
+    "context",
+    "context merge",
+    "context put",
+    "context get entries",
+    "context get value",
+]);
+// ---------------------------------------------------------------------------
+// FEEL AST identifier extractor
+// ---------------------------------------------------------------------------
+function collectNames(node, out) {
+    switch (node.kind) {
+        case "name":
+            if (!FEEL_BUILTINS.has(node.name))
+                out.add(node.name);
+            break;
+        case "path":
+            // a.b.c — only the root (base) is a variable reference
+            collectNames(node.base, out);
+            break;
+        case "binary":
+            collectNames(node.left, out);
+            collectNames(node.right, out);
+            break;
+        case "unary-minus":
+            collectNames(node.operand, out);
+            break;
+        case "list":
+            for (const item of node.items)
+                collectNames(item, out);
+            break;
+        case "context":
+            for (const entry of node.entries)
+                collectNames(entry.value, out);
+            break;
+        case "range":
+            collectNames(node.low, out);
+            collectNames(node.high, out);
+            break;
+        case "filter":
+            collectNames(node.base, out);
+            collectNames(node.condition, out);
+            break;
+        case "call":
+            for (const arg of node.args)
+                collectNames(arg, out);
+            break;
+        case "call-named":
+            for (const arg of node.args)
+                collectNames(arg.value, out);
+            break;
+        case "if":
+            collectNames(node.condition, out);
+            collectNames(node.then, out);
+            collectNames(node.else, out);
+            break;
+        case "for":
+            for (const b of node.bindings)
+                collectNames(b.domain, out);
+            collectNames(node.body, out);
+            break;
+        case "some":
+        case "every":
+            for (const b of node.bindings)
+                collectNames(b.domain, out);
+            collectNames(node.satisfies, out);
+            break;
+        case "between":
+            collectNames(node.value, out);
+            collectNames(node.low, out);
+            collectNames(node.high, out);
+            break;
+        case "in-test":
+            collectNames(node.value, out);
+            collectNames(node.test, out);
+            break;
+        case "function-def":
+            collectNames(node.body, out);
+            break;
+        case "unary-test-list":
+            for (const t of node.tests)
+                collectNames(t, out);
+            break;
+        case "unary-not":
+            for (const t of node.tests)
+                collectNames(t, out);
+            break;
+        // Leaf nodes: number, string, boolean, null, temporal, any-input, instance-of
+        default:
+            break;
+    }
+}
+/** Extract variable names referenced in a FEEL expression string. */
+export function extractFeelIdentifiers(expression) {
+    const trimmed = expression.trim();
+    if (trimmed === "")
+        return [];
+    // Strip leading "=" unary-test prefix if present
+    const expr = trimmed.startsWith("=") ? trimmed.slice(1).trim() : trimmed;
+    const result = parseExpression(expr);
+    if (result.ast === null)
+        return [];
+    const names = new Set();
+    collectNames(result.ast, names);
+    return [...names];
+}
+// ---------------------------------------------------------------------------
+// Levenshtein distance (for typo suggestions)
+// ---------------------------------------------------------------------------
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    // Flat row buffers — avoids noUncheckedIndexedAccess issues with 2D arrays
+    let prev = new Int32Array(n + 1);
+    let curr = new Int32Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            curr[j] =
+                a[i - 1] === b[j - 1]
+                    ? prev[j - 1]
+                    : 1 + Math.min(prev[j], curr[j - 1], prev[j - 1]);
+        }
+        ;
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+function findClosest(name, candidates) {
+    let best = null;
+    let bestDist = 3; // only suggest if distance ≤ 2
+    for (const c of candidates) {
+        if (c === name)
+            continue;
+        const d = levenshtein(name, c);
+        if (d < bestDist) {
+            bestDist = d;
+            best = c;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Extension readers for result variables
+// ---------------------------------------------------------------------------
+function readResultVariable(ext) {
+    for (const el of ext) {
+        if (el.name === "zeebe:calledDecision" && el.attributes.resultVariable) {
+            return el.attributes.resultVariable;
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main analysis
+// ---------------------------------------------------------------------------
+export function analyzeVariableFlow(p) {
+    const findings = [];
+    const processId = p.id;
+    // Maps: variable name → list of element IDs that produce / consume it
+    const producedBy = new Map();
+    const consumedBy = new Map();
+    // Per-element role tracking
+    const elementProduces = new Map();
+    const elementConsumes = new Map();
+    function addProducer(varName, elementId) {
+        if (varName.trim() === "")
+            return;
+        const existing = producedBy.get(varName) ?? [];
+        if (!existing.includes(elementId))
+            existing.push(elementId);
+        producedBy.set(varName, existing);
+        const elList = elementProduces.get(elementId) ?? [];
+        if (!elList.includes(varName))
+            elList.push(varName);
+        elementProduces.set(elementId, elList);
+    }
+    function addConsumer(varName, elementId) {
+        if (varName.trim() === "")
+            return;
+        const existing = consumedBy.get(varName) ?? [];
+        if (!existing.includes(elementId))
+            existing.push(elementId);
+        consumedBy.set(varName, existing);
+        const elList = elementConsumes.get(elementId) ?? [];
+        if (!elList.includes(varName))
+            elList.push(varName);
+        elementConsumes.set(elementId, elList);
+    }
+    // ── Scan flow elements ───────────────────────────────────────────────────
+    for (const el of p.flowElements) {
+        const io = readZeebeIoMapping(el.extensionElements);
+        if (io !== null) {
+            // IO mapping inputs: the *target* variable is what gets written into this task's local scope
+            // IO mapping outputs: the *target* variable is what gets written back into the process scope
+            for (const inp of io.inputs) {
+                if (inp.target.trim() !== "")
+                    addProducer(inp.target.trim(), el.id);
+                // The source expression may consume variables from the process scope
+                for (const name of extractFeelIdentifiers(inp.source)) {
+                    addConsumer(name, el.id);
+                }
+            }
+            for (const out of io.outputs) {
+                if (out.target.trim() !== "")
+                    addProducer(out.target.trim(), el.id);
+                // The source expression may consume local variables
+                for (const name of extractFeelIdentifiers(out.source)) {
+                    addConsumer(name, el.id);
+                }
+            }
+        }
+        // Result variable (business rule tasks via zeebe:calledDecision)
+        const resultVar = readResultVariable(el.extensionElements);
+        if (resultVar !== null) {
+            addProducer(resultVar, el.id);
+        }
+    }
+    // ── Scan sequence flow conditions ────────────────────────────────────────
+    for (const flow of p.sequenceFlows) {
+        const cond = flow.conditionExpression?.text?.trim();
+        if (cond === undefined || cond === "")
+            continue;
+        for (const name of extractFeelIdentifiers(cond)) {
+            // Conditions on flows consume variables from the process scope
+            // Associate with the source element (gateway)
+            addConsumer(name, flow.sourceRef);
+        }
+    }
+    // ── Compute findings ─────────────────────────────────────────────────────
+    const allProducedNames = [...producedBy.keys()];
+    // Finding: variable consumed but never produced anywhere
+    const checkedConsumed = new Set();
+    for (const [varName, elementIds] of consumedBy) {
+        if (checkedConsumed.has(varName))
+            continue;
+        checkedConsumed.add(varName);
+        if (producedBy.has(varName))
+            continue;
+        const closest = findClosest(varName, allProducedNames);
+        const suggestion = closest !== null
+            ? `"${varName}" is never set. Did you mean "${closest}"?`
+            : `"${varName}" is never set on any path through this process.`;
+        findings.push({
+            id: `data-flow/undefined-variable:${varName}`,
+            category: "data-flow",
+            severity: "warning",
+            message: `Variable "${varName}" is referenced but never set in this process.`,
+            suggestion,
+            processId,
+            elementIds,
+            consumes: [varName],
+        });
+    }
+    // Finding: variable produced but never consumed anywhere
+    const checkedProduced = new Set();
+    for (const [varName, elementIds] of producedBy) {
+        if (checkedProduced.has(varName))
+            continue;
+        checkedProduced.add(varName);
+        if (consumedBy.has(varName))
+            continue;
+        findings.push({
+            id: `data-flow/dead-output:${varName}`,
+            category: "data-flow",
+            severity: "info",
+            message: `Variable "${varName}" is set but never read by any downstream element.`,
+            suggestion: `Remove the output mapping for "${varName}" or add a task that consumes it.`,
+            processId,
+            elementIds,
+            produces: [varName],
+        });
+    }
+    // ── Attach per-element role findings (for the overlay plugin) ────────────
+    const roleElements = new Set([...elementProduces.keys(), ...elementConsumes.keys()]);
+    for (const elementId of roleElements) {
+        const produces = elementProduces.get(elementId) ?? [];
+        const consumes = elementConsumes.get(elementId) ?? [];
+        if (produces.length === 0 && consumes.length === 0)
+            continue;
+        findings.push({
+            id: `data-flow/role:${elementId}`,
+            category: "data-flow",
+            severity: "info",
+            message: `Element "${elementId}" ${produces.length > 0 ? `produces: ${produces.join(", ")}` : ""}${produces.length > 0 && consumes.length > 0 ? "; " : ""}${consumes.length > 0 ? `consumes: ${consumes.join(", ")}` : ""}.`,
+            suggestion: "",
+            processId,
+            elementIds: [elementId],
+            produces: produces.length > 0 ? produces : undefined,
+            consumes: consumes.length > 0 ? consumes : undefined,
+        });
+    }
+    // ── Per-edge scope findings (variables available at each sequence flow) ──
+    // Build reverse adjacency: targetId → set of source IDs
+    const reverseAdj = new Map();
+    for (const flow of p.sequenceFlows) {
+        const set = reverseAdj.get(flow.targetRef) ?? new Set();
+        set.add(flow.sourceRef);
+        reverseAdj.set(flow.targetRef, set);
+    }
+    // Collect all transitive predecessors of an element (inclusive of start)
+    function allPredecessors(elementId) {
+        const visited = new Set();
+        const queue = [elementId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === undefined)
+                break;
+            const preds = reverseAdj.get(current);
+            if (preds === undefined)
+                continue;
+            for (const pred of preds) {
+                if (!visited.has(pred)) {
+                    visited.add(pred);
+                    queue.push(pred);
+                }
+            }
+        }
+        return visited;
+    }
+    for (const flow of p.sequenceFlows) {
+        const predIds = allPredecessors(flow.sourceRef);
+        predIds.add(flow.sourceRef);
+        const inScope = new Set();
+        for (const predId of predIds) {
+            for (const v of elementProduces.get(predId) ?? [])
+                inScope.add(v);
+        }
+        if (inScope.size === 0)
+            continue;
+        const scopeVars = [...inScope].sort();
+        findings.push({
+            id: `data-flow/edge-scope:${flow.id}`,
+            category: "data-flow",
+            severity: "info",
+            message: `Variables in scope at flow "${flow.id}": ${scopeVars.join(", ")}.`,
+            suggestion: "",
+            processId,
+            elementIds: [flow.id],
+            produces: scopeVars,
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=variable-flow.js.map

package/dist/bpmn/story.d.ts

@@ -0,0 +1,10 @@
+import type { BpmnDefinitions } from "./bpmn-model.js";
+export interface StoryRenderOptions {
+    /** If true, wrap in a complete HTML document with embedded CSS. Default false (returns fragment). */
+    standalone?: boolean;
+    /** Color theme. Default "light". */
+    theme?: "dark" | "light";
+}
+/** Render a BPMN process as a story-mode HTML string (no DOM required). */
+export declare function renderStoryHtml(defs: BpmnDefinitions, options?: StoryRenderOptions): string;
+//# sourceMappingURL=story.d.ts.map