@bpmnkit/core 0.0.14 → 0.0.15

package/README.md

@@ -186,6 +186,8 @@ const outXml = Bpmn.export(restored)
 | [`@bpmnkit/cli-sdk`](https://www.npmjs.com/package/@bpmnkit/cli-sdk) | Plugin authoring SDK for the casen CLI |
 | [`@bpmnkit/create-casen-plugin`](https://www.npmjs.com/package/@bpmnkit/create-casen-plugin) | Scaffold a new casen CLI plugin in seconds |
 | [`@bpmnkit/casen-report`](https://www.npmjs.com/package/@bpmnkit/casen-report) | HTML reports from Camunda 8 incident and SLA data |
+| [`@bpmnkit/casen-worker-http`](https://www.npmjs.com/package/@bpmnkit/casen-worker-http) | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data |
+| [`@bpmnkit/casen-worker-ai`](https://www.npmjs.com/package/@bpmnkit/casen-worker-ai) | AI task worker — classify, summarize, extract, and decide using Claude |
 
 ## License
 

package/dist/bpmn/optimize/index.js

@@ -1,8 +1,18 @@
 import { analyzeFeel } from "./feel.js";
 import { analyzeFlow } from "./flow.js";
 import { analyzeNaming } from "./naming.js";
+import { analyzePatterns } from "./patterns.js";
 import { analyzeTasks } from "./tasks.js";
-const ALL_CATEGORIES = ["feel", "flow", "naming", "task-reuse", "extract"];
+import { analyzeVariableFlow } from "./variable-flow.js";
+const ALL_CATEGORIES = [
+    "feel",
+    "flow",
+    "naming",
+    "task-reuse",
+    "extract",
+    "pattern",
+    "data-flow",
+];
 function resolveOptions(opts) {
     return {
         feelLengthThreshold: opts?.feelLengthThreshold ?? 80,
@@ -30,11 +40,22 @@ export function optimize(defs, options) {
         if (resolved.categories.includes("task-reuse")) {
             findings.push(...analyzeTasks(process, resolved));
         }
+        if (resolved.categories.includes("pattern")) {
+            findings.push(...analyzePatterns(process));
+        }
+        if (resolved.categories.includes("data-flow")) {
+            findings.push(...analyzeVariableFlow(process));
+        }
     }
-    const byCategory = Object.fromEntries(["feel", "flow", "naming", "task-reuse", "extract"].map((c) => [
-        c,
-        findings.filter((f) => f.category === c).length,
-    ]));
+    const byCategory = Object.fromEntries([
+        "feel",
+        "flow",
+        "naming",
+        "task-reuse",
+        "extract",
+        "pattern",
+        "data-flow",
+    ].map((c) => [c, findings.filter((f) => f.category === c).length]));
     const bySeverity = Object.fromEntries(["info", "warning", "error"].map((s) => [
         s,
         findings.filter((f) => f.severity === s).length,

package/dist/bpmn/optimize/patterns.d.ts

@@ -0,0 +1,4 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding } from "./types.js";
+export declare function analyzePatterns(p: BpmnProcess): OptimizationFinding[];
+//# sourceMappingURL=patterns.d.ts.map

package/dist/bpmn/optimize/patterns.js

@@ -0,0 +1,365 @@
+import { buildFlowIndex, readZeebeIoMapping, readZeebeTaskType } from "./utils.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Returns true if the element has a boundary event of the given type attached. */
+function hasBoundaryOf(elementId, eventType, p) {
+    for (const el of p.flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        if (el.attachedToRef !== elementId)
+            continue;
+        for (const def of el.eventDefinitions) {
+            if (def.type === eventType)
+                return true;
+        }
+    }
+    return false;
+}
+/** Returns true if the condition expression text appears to contain only literals (no variable names). */
+function isLiteralOnlyCondition(text) {
+    // Strip leading "=" (FEEL unary test prefix)
+    const expr = text.replace(/^\s*=\s*/, "").trim();
+    // Patterns that are clearly literals: numbers, quoted strings, true/false/null
+    const literalPattern = /^(?:"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)$/i;
+    if (literalPattern.test(expr))
+        return true;
+    // List of literals: [1, 2, 3] or ["a", "b"]
+    const listPattern = /^\[(?:\s*(?:"[^"]*"|-?\d+(?:\.\d+)?|true|false|null)\s*,?\s*)*\]$/i;
+    if (listPattern.test(expr))
+        return true;
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Pattern rules
+// ---------------------------------------------------------------------------
+export function analyzePatterns(p) {
+    const findings = [];
+    const processId = p.id;
+    const { bySource, byTarget } = buildFlowIndex(p);
+    // ── Rule 1: HTTP/REST service task without error boundary ───────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "serviceTask")
+            continue;
+        const jobType = readZeebeTaskType(el.extensionElements) ?? "";
+        const isHttp = jobType.toLowerCase().includes("http") ||
+            jobType.toLowerCase().includes("rest") ||
+            jobType === "io.camunda.connector.HttpJson:1";
+        if (!isHttp)
+            continue;
+        if (!hasBoundaryOf(el.id, "error", p)) {
+            findings.push({
+                id: "pattern/http-no-error-boundary",
+                category: "pattern",
+                severity: "error",
+                message: `Service task "${el.name ?? el.id}" calls an HTTP connector but has no error boundary event.`,
+                suggestion: "Add an error boundary event to handle network failures (timeouts, non-2xx responses).",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 2: Exclusive gateway without default flow ──────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "exclusiveGateway")
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        if (outflows.length <= 1)
+            continue; // covered by single-outgoing rule
+        if (el.default === undefined) {
+            findings.push({
+                id: "pattern/gateway-no-default-flow",
+                category: "pattern",
+                severity: "error",
+                message: `Exclusive gateway "${el.name ?? el.id}" has no default sequence flow.`,
+                suggestion: "Add a default flow to ensure the process does not get stuck when no condition matches.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 3: Sub-process without error boundary ──────────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "subProcess" && el.type !== "adHocSubProcess" && el.type !== "transaction")
+            continue;
+        if (!hasBoundaryOf(el.id, "error", p)) {
+            findings.push({
+                id: "pattern/subprocess-no-error-boundary",
+                category: "pattern",
+                severity: "error",
+                message: `Sub-process "${el.name ?? el.id}" has no error boundary event.`,
+                suggestion: "Add an error boundary event to catch unhandled errors thrown inside the sub-process.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 4: Call activity with no error propagation ─────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "callActivity")
+            continue;
+        if (!hasBoundaryOf(el.id, "error", p)) {
+            findings.push({
+                id: "pattern/call-activity-no-error-boundary",
+                category: "pattern",
+                severity: "error",
+                message: `Call activity "${el.name ?? el.id}" has no error boundary event.`,
+                suggestion: "Add an error boundary event to handle errors propagated from the called process.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 5: Parallel branches writing the same variable ─────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "parallelGateway")
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        if (outflows.length < 2)
+            continue;
+        // Collect output variable targets per branch (BFS one level deep)
+        const branchTargets = [];
+        for (const flow of outflows) {
+            const targets = [];
+            const branchEl = p.flowElements.find((e) => e.id === flow.targetRef);
+            if (branchEl !== undefined) {
+                const io = readZeebeIoMapping(branchEl.extensionElements);
+                if (io !== null) {
+                    for (const out of io.outputs) {
+                        if (out.target.trim() !== "")
+                            targets.push(out.target.trim());
+                    }
+                }
+            }
+            branchTargets.push(targets);
+        }
+        // Find variables written by more than one branch
+        const seen = new Map(); // varName -> branch count
+        for (const targets of branchTargets) {
+            const unique = new Set(targets);
+            for (const t of unique) {
+                seen.set(t, (seen.get(t) ?? 0) + 1);
+            }
+        }
+        const conflicts = [...seen.entries()].filter(([, count]) => count > 1).map(([v]) => v);
+        if (conflicts.length > 0) {
+            findings.push({
+                id: "pattern/parallel-variable-conflict",
+                category: "pattern",
+                severity: "error",
+                message: `Parallel branches from gateway "${el.name ?? el.id}" both write to: ${conflicts.join(", ")}.`,
+                suggestion: "Last writer wins — result is non-deterministic. Use distinct variable names per branch.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 6: User task without timer boundary ────────────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "userTask")
+            continue;
+        if (!hasBoundaryOf(el.id, "timer", p)) {
+            findings.push({
+                id: "pattern/user-task-no-timer",
+                category: "pattern",
+                severity: "warning",
+                message: `User task "${el.name ?? el.id}" has no timer boundary event.`,
+                suggestion: "Add a timer boundary to enforce an SLA and prevent tasks from waiting indefinitely.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 7: Service task output mapping with no result variable ──────────
+    for (const el of p.flowElements) {
+        if (el.type !== "serviceTask")
+            continue;
+        const jobType = readZeebeTaskType(el.extensionElements);
+        if (jobType === null)
+            continue; // not a worker task
+        const io = readZeebeIoMapping(el.extensionElements);
+        const hasOutputs = io !== null && io.outputs.length > 0;
+        if (!hasOutputs) {
+            findings.push({
+                id: "pattern/service-task-no-output",
+                category: "pattern",
+                severity: "warning",
+                message: `Service task "${el.name ?? el.id}" has no output variable mapping.`,
+                suggestion: "Map the job result to process variables so downstream tasks can consume it.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 8: Error boundary leading directly to end event (catch-and-swallow) ─
+    for (const el of p.flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        const hasError = el.eventDefinitions.some((d) => d.type === "error");
+        if (!hasError)
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        for (const flow of outflows) {
+            const target = p.flowElements.find((e) => e.id === flow.targetRef);
+            if (target !== undefined && target.type === "endEvent") {
+                findings.push({
+                    id: "pattern/catch-and-swallow",
+                    category: "pattern",
+                    severity: "warning",
+                    message: `Error boundary on "${el.attachedToRef}" leads directly to an end event — error is silently consumed.`,
+                    suggestion: "Add error logging, compensation, or re-throw the error rather than swallowing it silently.",
+                    processId,
+                    elementIds: [el.id],
+                });
+                break;
+            }
+        }
+    }
+    // ── Rule 9: Exclusive gateway with only one outgoing flow ───────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "exclusiveGateway")
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        if (outflows.length === 1) {
+            findings.push({
+                id: "pattern/gateway-single-outgoing",
+                category: "pattern",
+                severity: "warning",
+                message: `Exclusive gateway "${el.name ?? el.id}" has only one outgoing flow and is a pass-through.`,
+                suggestion: "Remove this gateway and connect its source directly to its target.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 10: Undocumented process start variables ───────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "startEvent")
+            continue;
+        if (el.eventDefinitions.length > 0)
+            continue; // message/timer start — skip
+        const inflows = byTarget.get(el.id) ?? [];
+        if (inflows.length > 0)
+            continue; // not a true start
+        const hasDoc = el.documentation !== undefined && el.documentation.trim() !== "";
+        if (!hasDoc) {
+            findings.push({
+                id: "pattern/start-no-documentation",
+                category: "pattern",
+                severity: "warning",
+                message: `Start event "${el.name ?? el.id}" has no documentation describing expected input variables.`,
+                suggestion: "Add documentation listing the process input variables so callers know the expected contract.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 11: Timer boundary with duration 0 ──────────────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        for (const def of el.eventDefinitions) {
+            if (def.type !== "timer")
+                continue;
+            const dur = def.timeDuration?.trim() ?? "";
+            const isZero = dur === "PT0S" ||
+                dur === "P0D" ||
+                dur === "PT0M" ||
+                dur === "PT0H" ||
+                dur === "0" ||
+                dur === "P0";
+            if (isZero) {
+                findings.push({
+                    id: "pattern/timer-duration-zero",
+                    category: "pattern",
+                    severity: "error",
+                    message: `Timer boundary on "${el.attachedToRef}" has a duration of zero — it will fire immediately.`,
+                    suggestion: "Set a meaningful duration (e.g. PT1H for 1 hour) to avoid instant firing.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+    }
+    // ── Rule 12: Boundary event with no outgoing flow ────────────────────────
+    for (const el of p.flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        if (outflows.length === 0) {
+            findings.push({
+                id: "pattern/boundary-no-outgoing",
+                category: "pattern",
+                severity: "error",
+                message: `Boundary event on "${el.attachedToRef}" has no outgoing sequence flow.`,
+                suggestion: "Connect the boundary event to a handler task or end event.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+    }
+    // ── Rule 13: Empty text annotation ──────────────────────────────────────
+    for (const ann of p.textAnnotations) {
+        const text = ann.text?.trim() ?? "";
+        if (text === "") {
+            findings.push({
+                id: "pattern/empty-annotation",
+                category: "pattern",
+                severity: "info",
+                message: `Text annotation "${ann.id}" is empty.`,
+                suggestion: "Fill in the annotation or remove it to keep the diagram clean.",
+                processId,
+                elementIds: [ann.id],
+            });
+        }
+    }
+    // ── Rule 14: Duplicate job type across multiple service tasks ────────────
+    const jobTypeCounts = new Map(); // jobType -> [elementId]
+    for (const el of p.flowElements) {
+        if (el.type !== "serviceTask")
+            continue;
+        const jobType = readZeebeTaskType(el.extensionElements);
+        if (jobType === null || jobType.trim() === "")
+            continue;
+        const ids = jobTypeCounts.get(jobType) ?? [];
+        ids.push(el.id);
+        jobTypeCounts.set(jobType, ids);
+    }
+    for (const [jobType, ids] of jobTypeCounts) {
+        if (ids.length < 2)
+            continue;
+        findings.push({
+            id: "pattern/duplicate-job-type",
+            category: "pattern",
+            severity: "info",
+            message: `Job type "${jobType}" is used by ${ids.length} service tasks.`,
+            suggestion: "Verify this is intentional — the same worker will handle all these tasks. Consider distinct job types if behaviors differ.",
+            processId,
+            elementIds: ids,
+        });
+    }
+    // ── Rule 15: FEEL condition using only literal values ────────────────────
+    const checkedFlows = new Set();
+    for (const flow of p.sequenceFlows) {
+        if (checkedFlows.has(flow.id))
+            continue;
+        checkedFlows.add(flow.id);
+        const cond = flow.conditionExpression?.text?.trim();
+        if (cond === undefined || cond === "")
+            continue;
+        if (isLiteralOnlyCondition(cond)) {
+            const sourceEl = p.flowElements.find((e) => e.id === flow.sourceRef);
+            findings.push({
+                id: "pattern/literal-condition",
+                category: "pattern",
+                severity: "info",
+                message: `Sequence flow "${flow.name ?? flow.id}" has a condition that only references literal values: \`${cond}\``,
+                suggestion: "A literal condition never changes at runtime. Replace with a variable reference or remove the condition.",
+                processId,
+                elementIds: [flow.id, ...(sourceEl !== undefined ? [sourceEl.id] : [])],
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=patterns.js.map

package/dist/bpmn/optimize/types.d.ts

@@ -1,6 +1,6 @@
 import type { BpmnDefinitions } from "../bpmn-model.js";
 export type OptimizationSeverity = "info" | "warning" | "error";
-export type OptimizationCategory = "feel" | "flow" | "naming" | "task-reuse" | "extract";
+export type OptimizationCategory = "feel" | "flow" | "naming" | "task-reuse" | "extract" | "pattern" | "data-flow";
 export interface ApplyFixResult {
     description: string;
     /** New BpmnDefinitions generated by the fix (e.g. extracted reusable sub-process). */
@@ -16,6 +16,10 @@ export interface OptimizationFinding {
     elementIds: string[];
     /** Mutates `defs` in-place. Returns what changed + any generated file. */
     applyFix?: (defs: BpmnDefinitions) => ApplyFixResult;
+    /** Data-flow: variable names produced (written) by the associated element. */
+    produces?: string[];
+    /** Data-flow: variable names consumed (read) by the associated element. */
+    consumes?: string[];
 }
 export interface OptimizationReport {
     findings: OptimizationFinding[];

package/dist/bpmn/optimize/variable-flow.d.ts

@@ -0,0 +1,6 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding } from "./types.js";
+/** Extract variable names referenced in a FEEL expression string. */
+export declare function extractFeelIdentifiers(expression: string): string[];
+export declare function analyzeVariableFlow(p: BpmnProcess): OptimizationFinding[];
+//# sourceMappingURL=variable-flow.d.ts.map

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

package/dist/bpmn/story.js

@@ -0,0 +1,336 @@
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function getCardInfo(el, laneName) {
+    switch (el.type) {
+        case "startEvent":
+            return { role: "start", header: "Process starts" };
+        case "endEvent":
+            return { role: "end", header: "Process ends" };
+        case "serviceTask":
+            return { role: "service", header: "System" };
+        case "userTask":
+            return { role: "user", header: laneName ?? "User" };
+        case "businessRuleTask":
+            return { role: "service", header: "Decision table" };
+        case "scriptTask":
+            return { role: "service", header: "Script" };
+        case "exclusiveGateway":
+        case "inclusiveGateway":
+            return { role: "gateway", header: "Decision" };
+        case "parallelGateway":
+            return { role: "parallel", header: "Parallel" };
+        case "callActivity":
+            return { role: "subprocess", header: "Sub-process" };
+        case "subProcess":
+        case "eventSubProcess":
+        case "transaction":
+            return { role: "subprocess", header: "Sub-process" };
+        case "intermediateCatchEvent":
+        case "intermediateThrowEvent":
+        case "boundaryEvent":
+            return { role: "event", header: "Event" };
+        default: {
+            const t = el.type;
+            const header = t.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
+            return { role: "task", header };
+        }
+    }
+}
+// ── Topological sort (Kahn's algorithm) ─────────────────────────────────────
+function topoSort(elements, flows) {
+    const idToEl = new Map();
+    for (const el of elements)
+        idToEl.set(el.id, el);
+    // in-degree and adjacency
+    const inDegree = new Map();
+    const successors = new Map();
+    for (const el of elements) {
+        inDegree.set(el.id, 0);
+        successors.set(el.id, []);
+    }
+    for (const flow of flows) {
+        if (!idToEl.has(flow.sourceRef) || !idToEl.has(flow.targetRef))
+            continue;
+        successors.get(flow.sourceRef)?.push(flow.targetRef);
+        inDegree.set(flow.targetRef, (inDegree.get(flow.targetRef) ?? 0) + 1);
+    }
+    const queue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    const result = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (id === undefined)
+            break;
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const el = idToEl.get(id);
+        if (el)
+            result.push(el);
+        for (const next of successors.get(id) ?? []) {
+            const deg = (inDegree.get(next) ?? 1) - 1;
+            inDegree.set(next, deg);
+            if (deg === 0)
+                queue.push(next);
+        }
+    }
+    // Handle cycles: append any unvisited elements in original order
+    for (const el of elements) {
+        if (!visited.has(el.id))
+            result.push(el);
+    }
+    return result;
+}
+// ── Lane mapping ─────────────────────────────────────────────────────────────
+function buildLaneMap(process) {
+    const map = new Map();
+    if (!process.laneSet)
+        return map;
+    for (const lane of process.laneSet.lanes) {
+        const name = lane.name ?? lane.id;
+        for (const ref of lane.flowNodeRefs) {
+            map.set(ref, name);
+        }
+    }
+    return map;
+}
+// ── Outgoing conditions ───────────────────────────────────────────────────────
+function getOutgoingConditions(el, flows) {
+    const outgoing = new Set(el.outgoing);
+    const result = [];
+    for (const flow of flows) {
+        if (!outgoing.has(flow.id))
+            continue;
+        if (flow.conditionExpression) {
+            result.push({
+                label: flow.name ?? flow.targetRef,
+                condition: flow.conditionExpression.text,
+            });
+        }
+    }
+    return result;
+}
+// ── Card HTML ─────────────────────────────────────────────────────────────────
+function renderCard(el, flows, laneName) {
+    const { role, header } = getCardInfo(el, laneName);
+    const name = "name" in el ? (el.name ?? "") : "";
+    const conditions = role === "gateway" ? getOutgoingConditions(el, flows) : [];
+    let conditionsHtml = "";
+    if (conditions.length > 0) {
+        const items = conditions
+            .map((c) => `<div class="bks-condition"><span class="bks-condition-label">${escapeHtml(c.label)}</span><span class="bks-condition-expr">${escapeHtml(c.condition)}</span></div>`)
+            .join("");
+        conditionsHtml = `<div class="bks-conditions">${items}</div>`;
+    }
+    return `<div class="bks-card bks-card--${role}" data-bpmnkit-id="${escapeHtml(el.id)}"><div class="bks-card-header">${escapeHtml(header)}</div><div class="bks-card-body">${escapeHtml(name)}</div>${conditionsHtml}</div>`;
+}
+// ── Lane HTML ─────────────────────────────────────────────────────────────────
+function renderLane(laneName, elements, flows, laneMap) {
+    if (elements.length === 0)
+        return "";
+    const cards = elements
+        .map((el, i) => {
+        const card = renderCard(el, flows, laneName === "_default" ? undefined : laneName);
+        const arrow = i < elements.length - 1 ? '<div class="bks-arrow">→</div>' : "";
+        return card + arrow;
+    })
+        .join("");
+    const laneHeader = laneName !== "_default" ? `<div class="bks-lane-header">${escapeHtml(laneName)}</div>` : "";
+    return `<div class="bks-lane">${laneHeader}<div class="bks-lane-cards">${cards}</div></div>`;
+}
+// ── Standalone CSS ────────────────────────────────────────────────────────────
+function buildStandaloneCss(theme) {
+    const isDark = theme === "dark";
+    const vars = isDark
+        ? `
+  --bks-bg: #0d0d16;
+  --bks-surface: #161626;
+  --bks-border: #2a2a42;
+  --bks-fg: #cdd6f4;
+  --bks-fg-muted: #8888a8;
+  --bks-accent: #6b9df7;
+  --bks-success: #22c55e;
+  --bks-danger: #f87171;
+  --bks-warn: #f59e0b;
+  --bks-teal: #2dd4bf;
+  --bks-purple: #a78bfa;`
+        : `
+  --bks-bg: #f4f4f8;
+  --bks-surface: #ffffff;
+  --bks-border: #d0d0e8;
+  --bks-fg: #1a1a2e;
+  --bks-fg-muted: #6666a0;
+  --bks-accent: #1a56db;
+  --bks-success: #16a34a;
+  --bks-danger: #dc2626;
+  --bks-warn: #d97706;
+  --bks-teal: #0d9488;
+  --bks-purple: #7c3aed;`;
+    return `
+:root {${vars}
+}
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+  background: var(--bks-bg);
+  color: var(--bks-fg);
+  font-family: system-ui, -apple-system, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  padding: 24px;
+}
+.bks-process-title {
+  font-size: 20px;
+  font-weight: 700;
+  margin-bottom: 20px;
+  color: var(--bks-fg);
+}
+.bks-lane {
+  margin-bottom: 16px;
+}
+.bks-lane-header {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--bks-fg-muted);
+  padding: 4px 0 8px;
+  border-bottom: 1px solid var(--bks-border);
+  margin-bottom: 10px;
+}
+.bks-lane-cards {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+}
+.bks-card {
+  background: var(--bks-surface);
+  border: 1px solid var(--bks-border);
+  border-radius: 8px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+  padding: 10px 14px;
+  min-width: 120px;
+  max-width: 200px;
+}
+.bks-card-header {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--bks-fg-muted);
+  margin-bottom: 4px;
+}
+.bks-card-body {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--bks-fg);
+  word-break: break-word;
+}
+.bks-card--start { border-left: 3px solid var(--bks-success); }
+.bks-card--end { border-left: 3px solid var(--bks-fg-muted); }
+.bks-card--service { border-left: 3px solid var(--bks-accent); }
+.bks-card--user { border-left: 3px solid var(--bks-teal); }
+.bks-card--gateway { border-left: 3px solid var(--bks-warn); }
+.bks-card--parallel { border-left: 3px solid var(--bks-fg-muted); }
+.bks-card--subprocess { border-left: 3px solid var(--bks-purple); }
+.bks-card--event { border-left: 3px solid var(--bks-accent); }
+.bks-card--task { border-left: 3px solid var(--bks-border); }
+.bks-conditions {
+  margin-top: 6px;
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+.bks-condition {
+  font-size: 11px;
+  display: flex;
+  gap: 4px;
+  flex-wrap: wrap;
+}
+.bks-condition-label {
+  font-weight: 600;
+  color: var(--bks-fg);
+}
+.bks-condition-expr {
+  color: var(--bks-fg-muted);
+  font-family: ui-monospace, monospace;
+}
+.bks-arrow {
+  color: var(--bks-fg-muted);
+  font-size: 18px;
+  padding: 0 2px;
+  flex-shrink: 0;
+}
+`;
+}
+// ── Main renderer ─────────────────────────────────────────────────────────────
+/** Render a BPMN process as a story-mode HTML string (no DOM required). */
+export function renderStoryHtml(defs, options) {
+    const standalone = options?.standalone ?? false;
+    const theme = options?.theme ?? "light";
+    const process = defs.processes[0];
+    if (!process)
+        return standalone ? wrapDocument("", "", theme) : "";
+    const laneMap = buildLaneMap(process);
+    const sorted = topoSort(process.flowElements, process.sequenceFlows);
+    // Group by lane
+    const laneNames = new Set();
+    const laneElements = new Map();
+    if (process.laneSet && process.laneSet.lanes.length > 0) {
+        // Collect unique lane names in alpha order
+        const sortedLaneNames = process.laneSet.lanes
+            .map((l) => l.name ?? l.id)
+            .sort((a, b) => a.localeCompare(b));
+        for (const n of sortedLaneNames) {
+            laneNames.add(n);
+            laneElements.set(n, []);
+        }
+        // Place each element in its lane
+        for (const el of sorted) {
+            const lane = laneMap.get(el.id) ?? sortedLaneNames[0];
+            if (lane !== undefined) {
+                laneElements.get(lane)?.push(el);
+            }
+        }
+    }
+    else {
+        // No lane set — single default lane
+        laneNames.add("_default");
+        laneElements.set("_default", sorted);
+    }
+    let body = "";
+    for (const laneName of laneNames) {
+        const els = laneElements.get(laneName) ?? [];
+        body += renderLane(laneName, els, process.sequenceFlows, laneMap);
+    }
+    const processTitle = process.name ?? process.id;
+    const fragment = `<div class="bks-process-title">${escapeHtml(processTitle)}</div>${body}`;
+    if (standalone) {
+        return wrapDocument(fragment, buildStandaloneCss(theme), theme);
+    }
+    return fragment;
+}
+function wrapDocument(body, css, theme) {
+    return `<!DOCTYPE html>
+<html lang="en" data-theme="${theme}">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>BPMN Story View</title>
+<style>${css}</style>
+</head>
+<body>${body}</body>
+</html>`;
+}
+//# sourceMappingURL=story.js.map

package/dist/index.d.ts

@@ -24,6 +24,9 @@ export { parseXml, serializeXml } from "./xml/index.js";
 export { readDiColor, writeDiColor, BIOC_NS, COLOR_NS } from "./bpmn/di-color.js";
 export type { DiColor } from "./bpmn/di-color.js";
 export { optimize } from "./bpmn/optimize/index.js";
+export { renderStoryHtml } from "./bpmn/story.js";
+export type { StoryRenderOptions } from "./bpmn/story.js";
+export { analyzeVariableFlow, extractFeelIdentifiers } from "./bpmn/optimize/variable-flow.js";
 export type { OptimizationReport, OptimizationFinding, OptimizationSeverity, OptimizationCategory, ApplyFixResult, OptimizeOptions, } from "./bpmn/optimize/types.js";
 export { layoutProcess, layoutFlowNodes } from "./layout/index.js";
 export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./layout/index.js";

package/dist/index.js

@@ -11,6 +11,8 @@ export { generateId, resetIdCounter } from "./types/id-generator.js";
 export { parseXml, serializeXml } from "./xml/index.js";
 export { readDiColor, writeDiColor, BIOC_NS, COLOR_NS } from "./bpmn/di-color.js";
 export { optimize } from "./bpmn/optimize/index.js";
+export { renderStoryHtml } from "./bpmn/story.js";
+export { analyzeVariableFlow, extractFeelIdentifiers } from "./bpmn/optimize/variable-flow.js";
 export { layoutProcess, layoutFlowNodes } from "./layout/index.js";
 export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./layout/index.js";
 export { ELEMENT_SIZES, GRID_CELL_HEIGHT } from "./layout/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/core",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,7 +16,9 @@
     "dist/**/*.js",
     "dist/**/*.d.ts"
   ],
-  "dependencies": {},
+  "dependencies": {
+    "@bpmnkit/feel": "0.0.13"
+  },
   "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
   "keywords": [
     "bpmn",