@bpmnkit/core 0.0.8

package/dist/bpmn/optimize/feel.js

@@ -0,0 +1,186 @@
+import { buildFlowIndex, findProcess, readZeebeIoMapping, readZeebeTaskType } from "./utils.js";
+// ---------------------------------------------------------------------------
+// FEEL complexity scoring
+// ---------------------------------------------------------------------------
+const FEEL_KEYWORD_OPERATORS = new Set([
+    "and",
+    "or",
+    "not",
+    "if",
+    "then",
+    "else",
+    "instance",
+    "of",
+    "some",
+    "every",
+    "satisfies",
+    "function",
+]);
+function scoreFeelExpression(expr, opts) {
+    const length = expr.length;
+    // Nesting depth: track max depth of parentheses/brackets
+    let depth = 0;
+    let nestingDepth = 0;
+    for (const ch of expr) {
+        if (ch === "(" || ch === "[") {
+            depth++;
+            if (depth > nestingDepth)
+                nestingDepth = depth;
+        }
+        else if (ch === ")" || ch === "]") {
+            depth--;
+        }
+    }
+    // Tokenize on non-word boundaries; collect keywords and identifiers
+    const wordTokens = expr.split(/\W+/).filter(Boolean);
+    let operatorCount = 0;
+    const variables = new Set();
+    for (const token of wordTokens) {
+        if (FEEL_KEYWORD_OPERATORS.has(token)) {
+            operatorCount++;
+        }
+        else if (!/^\d/.test(token)) {
+            variables.add(token);
+        }
+    }
+    // Count symbol operators (order matters: longer patterns first)
+    const symbolMatches = expr.match(/!=|<=|>=|[+\-*/=<>]/g) ?? [];
+    operatorCount += symbolMatches.length;
+    const variableCount = variables.size;
+    const isComplex = length > opts.feelLengthThreshold ||
+        nestingDepth > opts.feelNestingThreshold ||
+        operatorCount > opts.feelOperatorThreshold ||
+        variableCount > opts.feelVariableThreshold;
+    return { length, nestingDepth, operatorCount, variableCount, isComplex };
+}
+// ---------------------------------------------------------------------------
+// FEEL analyzer
+// ---------------------------------------------------------------------------
+export function analyzeFeel(p, opts) {
+    const findings = [];
+    const { bySource } = buildFlowIndex(p);
+    const processId = p.id;
+    // Track FEEL expressions across all sequence flows for duplicate detection
+    const exprToFlowIds = new Map();
+    for (const flow of p.sequenceFlows) {
+        // Determine if source is an exclusive/inclusive gateway
+        const srcEl = p.flowElements.find((e) => e.id === flow.sourceRef);
+        const srcIsDecisionGateway = srcEl !== undefined &&
+            (srcEl.type === "exclusiveGateway" || srcEl.type === "inclusiveGateway");
+        if (srcIsDecisionGateway && srcEl !== undefined) {
+            const defaultFlowId = srcEl.type === "exclusiveGateway" || srcEl.type === "inclusiveGateway"
+                ? srcEl.default
+                : undefined;
+            if (!flow.conditionExpression && flow.id !== defaultFlowId) {
+                findings.push({
+                    id: "feel/empty-condition",
+                    category: "feel",
+                    severity: "error",
+                    message: `Sequence flow "${flow.id}" exits a decision gateway without a condition expression.`,
+                    suggestion: "Add a FEEL condition expression or mark this flow as the default.",
+                    processId,
+                    elementIds: [flow.id],
+                });
+            }
+        }
+        // Track FEEL expression for duplicate detection
+        if (flow.conditionExpression) {
+            const expr = flow.conditionExpression.text.trim();
+            if (expr.length > 0) {
+                const list = exprToFlowIds.get(expr) ?? [];
+                list.push(flow.id);
+                exprToFlowIds.set(expr, list);
+            }
+            // Check complexity
+            const score = scoreFeelExpression(flow.conditionExpression.text, opts);
+            if (score.isComplex) {
+                findings.push({
+                    id: "feel/complex-condition",
+                    category: "feel",
+                    severity: "warning",
+                    message: `Condition on flow "${flow.id}" is complex (length=${score.length}, nesting=${score.nestingDepth}, operators=${score.operatorCount}, variables=${score.variableCount}).`,
+                    suggestion: "Consider extracting complex FEEL expressions into named variables or decision tables.",
+                    processId,
+                    elementIds: [flow.id],
+                });
+            }
+        }
+    }
+    // Check gateways: missing default flow
+    for (const el of p.flowElements) {
+        if (el.type !== "exclusiveGateway" && el.type !== "inclusiveGateway")
+            continue;
+        const outflows = bySource.get(el.id) ?? [];
+        if (outflows.length < 2)
+            continue;
+        if (!el.default) {
+            const lastFlowId = outflows[outflows.length - 1]?.id ?? "";
+            const gwId = el.id;
+            findings.push({
+                id: "feel/missing-default-flow",
+                category: "feel",
+                severity: "warning",
+                message: `Gateway "${el.id}" has ${outflows.length} outgoing flows but no default flow set.`,
+                suggestion: "Set a default flow to handle unmatched conditions.",
+                processId,
+                elementIds: [el.id],
+                applyFix: (defs) => {
+                    const proc = findProcess(defs, processId);
+                    if (!proc)
+                        return { description: "Process not found" };
+                    const gw = proc.flowElements.find((e) => e.id === gwId);
+                    if (!gw)
+                        return { description: "Gateway not found" };
+                    if (gw.type === "exclusiveGateway" || gw.type === "inclusiveGateway") {
+                        gw.default = lastFlowId;
+                    }
+                    return { description: `Set default flow to "${lastFlowId}" on gateway "${gwId}"` };
+                },
+            });
+        }
+    }
+    // Check service tasks: complex IO mapping
+    // Skip connector tasks — their ioMapping inputs are structured connector parameters
+    // (url, method, headers, body), not user-authored FEEL expressions.
+    const REST_CONNECTOR_TYPE = "io.camunda:http-json:1";
+    for (const el of p.flowElements) {
+        if (el.type !== "serviceTask")
+            continue;
+        if (readZeebeTaskType(el.extensionElements) === REST_CONNECTOR_TYPE)
+            continue;
+        const ioMapping = readZeebeIoMapping(el.extensionElements);
+        if (!ioMapping)
+            continue;
+        for (const input of ioMapping.inputs) {
+            const score = scoreFeelExpression(input.source, opts);
+            if (score.isComplex) {
+                findings.push({
+                    id: "feel/complex-io-mapping",
+                    category: "feel",
+                    severity: "info",
+                    message: `IO mapping input source on task "${el.id}" is complex.`,
+                    suggestion: "Consider extracting complex FEEL expressions into intermediate variables.",
+                    processId,
+                    elementIds: [el.id],
+                });
+                break; // One finding per task
+            }
+        }
+    }
+    // Duplicate FEEL expressions
+    for (const [expr, flowIds] of exprToFlowIds) {
+        if (flowIds.length >= 2) {
+            findings.push({
+                id: "feel/duplicate-expression",
+                category: "feel",
+                severity: "info",
+                message: `FEEL expression "${expr.slice(0, 40)}" appears on ${flowIds.length} sequence flows.`,
+                suggestion: "Consider extracting repeated FEEL expressions into a shared variable or decision table.",
+                processId,
+                elementIds: flowIds,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=feel.js.map

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

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

package/dist/bpmn/optimize/flow.js

@@ -0,0 +1,323 @@
+import { generateId } from "../../types/id-generator.js";
+import { buildFlowIndex, findDiPlane, findProcess, insertElement, insertFlow, isEndEvent, isGateway, isStartEvent, reachableFrom, removeElement, removeFlow, } from "./utils.js";
+export function analyzeFlow(p, _opts) {
+    const findings = [];
+    const processId = p.id;
+    const { bySource, byTarget } = buildFlowIndex(p);
+    // Start IDs for BFS reachability
+    const startIds = p.flowElements.filter((e) => isStartEvent(e.type)).map((e) => e.id);
+    // flow/no-start-event
+    const startEvents = p.flowElements.filter((e) => isStartEvent(e.type));
+    if (startEvents.length === 0) {
+        findings.push({
+            id: "flow/no-start-event",
+            category: "flow",
+            severity: "error",
+            message: `Process "${processId}" has no start event.`,
+            suggestion: "Add a start event to define where the process begins.",
+            processId,
+            elementIds: [],
+        });
+    }
+    // flow/no-end-event
+    const endEvents = p.flowElements.filter((e) => isEndEvent(e.type));
+    if (endEvents.length === 0) {
+        findings.push({
+            id: "flow/no-end-event",
+            category: "flow",
+            severity: "warning",
+            message: `Process "${processId}" has no end event.`,
+            suggestion: "Add an end event to properly terminate the process.",
+            processId,
+            elementIds: [],
+        });
+    }
+    // BFS reachability from start events
+    const reachable = reachableFrom(startIds, bySource);
+    for (const el of p.flowElements) {
+        // flow/unreachable
+        if (!reachable.has(el.id)) {
+            findings.push({
+                id: "flow/unreachable",
+                category: "flow",
+                severity: "error",
+                message: `Element "${el.id}" (${el.type}) is not reachable from any start event.`,
+                suggestion: "Connect this element to the process flow or remove it.",
+                processId,
+                elementIds: [el.id],
+            });
+        }
+        // flow/dead-end: non-end-event with 0 outgoing flows
+        const outflows = bySource.get(el.id) ?? [];
+        if (!isEndEvent(el.type) && outflows.length === 0) {
+            const deadEndId = el.id;
+            findings.push({
+                id: "flow/dead-end",
+                category: "flow",
+                severity: "warning",
+                message: `Element "${el.id}" (${el.type}) has no outgoing sequence flows.`,
+                suggestion: "Connect this element to a downstream element or an end event.",
+                processId,
+                elementIds: [el.id],
+                applyFix: (defs) => {
+                    const proc = findProcess(defs, processId);
+                    if (!proc)
+                        return { description: "Process not found" };
+                    const endEventId = generateId("EndEvent");
+                    const flowId = generateId("Flow");
+                    const endEvent = {
+                        type: "endEvent",
+                        id: endEventId,
+                        incoming: [flowId],
+                        outgoing: [],
+                        extensionElements: [],
+                        unknownAttributes: {},
+                        eventDefinitions: [],
+                    };
+                    const newFlow = {
+                        id: flowId,
+                        sourceRef: deadEndId,
+                        targetRef: endEventId,
+                        extensionElements: [],
+                        unknownAttributes: {},
+                    };
+                    // Update outgoing on dead-end element
+                    const deadEl = proc.flowElements.find((e) => e.id === deadEndId);
+                    if (deadEl) {
+                        deadEl.outgoing.push(flowId);
+                    }
+                    insertElement(proc, endEvent);
+                    insertFlow(proc, newFlow);
+                    // Update diagram if plane exists
+                    const plane = findDiPlane(defs, processId);
+                    if (plane) {
+                        const srcShape = plane.shapes.find((s) => s.bpmnElement === deadEndId);
+                        const srcRight = srcShape ? srcShape.bounds.x + srcShape.bounds.width : 300;
+                        const srcMidY = srcShape ? srcShape.bounds.y + srcShape.bounds.height / 2 : 220;
+                        const endX = srcShape ? srcShape.bounds.x + srcShape.bounds.width + 150 : 450;
+                        const endY = srcMidY - 18;
+                        plane.shapes.push({
+                            id: `${endEventId}_di`,
+                            bpmnElement: endEventId,
+                            bounds: { x: endX, y: endY, width: 36, height: 36 },
+                            unknownAttributes: {},
+                        });
+                        plane.edges.push({
+                            id: `${flowId}_di`,
+                            bpmnElement: flowId,
+                            waypoints: [
+                                { x: srcRight, y: srcMidY },
+                                { x: endX, y: srcMidY },
+                            ],
+                            unknownAttributes: {},
+                        });
+                    }
+                    return { description: `Added end event "${endEventId}" connected from "${deadEndId}"` };
+                },
+            });
+        }
+        // flow/multi-incoming-task: non-gateway element with more than 1 incoming flow
+        const inflows = byTarget.get(el.id) ?? [];
+        if (!isGateway(el.type) && !isStartEvent(el.type) && inflows.length > 1) {
+            const elId = el.id;
+            const inflowCount = inflows.length;
+            findings.push({
+                id: "flow/multi-incoming-task",
+                category: "flow",
+                severity: "error",
+                message: `Element "${el.id}" (${el.type}) has ${inflows.length} incoming flows. Non-gateway elements must have at most one incoming flow.`,
+                suggestion: "Add an exclusive gateway before this element to join the incoming flows.",
+                processId,
+                elementIds: [el.id],
+                applyFix: (defs) => {
+                    const proc = findProcess(defs, processId);
+                    if (!proc)
+                        return { description: "Process not found" };
+                    const targetEl = proc.flowElements.find((e) => e.id === elId);
+                    if (!targetEl)
+                        return { description: "Element not found" };
+                    const oldIncomingIds = [...targetEl.incoming];
+                    const gatewayId = generateId("Gateway");
+                    const joinFlowId = generateId("Flow");
+                    // Redirect all existing incoming flows to the new gateway
+                    for (const flowId of oldIncomingIds) {
+                        const f = proc.sequenceFlows.find((sf) => sf.id === flowId);
+                        if (f)
+                            f.targetRef = gatewayId;
+                    }
+                    const gateway = {
+                        type: "exclusiveGateway",
+                        id: gatewayId,
+                        incoming: oldIncomingIds,
+                        outgoing: [joinFlowId],
+                        extensionElements: [],
+                        unknownAttributes: {},
+                    };
+                    const joinFlow = {
+                        id: joinFlowId,
+                        sourceRef: gatewayId,
+                        targetRef: elId,
+                        extensionElements: [],
+                        unknownAttributes: {},
+                    };
+                    insertElement(proc, gateway);
+                    insertFlow(proc, joinFlow);
+                    targetEl.incoming = [joinFlowId];
+                    // Add DI shape for the new gateway, positioned just before the target
+                    const plane = findDiPlane(defs, processId);
+                    if (plane) {
+                        const tgtShape = plane.shapes.find((s) => s.bpmnElement === elId);
+                        if (tgtShape) {
+                            const gwWidth = 50;
+                            const gwHeight = 50;
+                            const gwX = tgtShape.bounds.x - 100;
+                            const gwY = tgtShape.bounds.y + (tgtShape.bounds.height - gwHeight) / 2;
+                            plane.shapes.push({
+                                id: `${gatewayId}_di`,
+                                bpmnElement: gatewayId,
+                                bounds: { x: gwX, y: gwY, width: gwWidth, height: gwHeight },
+                                unknownAttributes: {},
+                            });
+                            for (const inFlowId of oldIncomingIds) {
+                                const edge = plane.edges.find((e) => e.bpmnElement === inFlowId);
+                                if (edge && edge.waypoints.length > 0) {
+                                    const last = edge.waypoints[edge.waypoints.length - 1];
+                                    if (last) {
+                                        last.x = gwX + gwWidth / 2;
+                                        last.y = gwY + gwHeight / 2;
+                                    }
+                                }
+                            }
+                            plane.edges.push({
+                                id: `${joinFlowId}_di`,
+                                bpmnElement: joinFlowId,
+                                waypoints: [
+                                    { x: gwX + gwWidth, y: gwY + gwHeight / 2 },
+                                    { x: tgtShape.bounds.x, y: tgtShape.bounds.y + tgtShape.bounds.height / 2 },
+                                ],
+                                unknownAttributes: {},
+                            });
+                        }
+                    }
+                    return {
+                        description: `Inserted exclusive gateway "${gatewayId}" before "${elId}" to join ${inflowCount} incoming flows`,
+                    };
+                },
+            });
+        }
+        // flow/redundant-gateway: gateway with exactly 1 incoming AND 1 outgoing
+        if (isGateway(el.type)) {
+            const inflows = byTarget.get(el.id) ?? [];
+            if (inflows.length === 1 && outflows.length === 1) {
+                const gwId = el.id;
+                const inFlowId = inflows[0]?.id ?? "";
+                const outFlowId = outflows[0]?.id ?? "";
+                findings.push({
+                    id: "flow/redundant-gateway",
+                    category: "flow",
+                    severity: "info",
+                    message: `Gateway "${el.id}" (${el.type}) has only 1 incoming and 1 outgoing flow — it is redundant.`,
+                    suggestion: "Remove this gateway and connect its source directly to its target.",
+                    processId,
+                    elementIds: [el.id],
+                    applyFix: (defs) => {
+                        const proc = findProcess(defs, processId);
+                        if (!proc)
+                            return { description: "Process not found" };
+                        // Find the two flows
+                        const inFlow = proc.sequenceFlows.find((f) => f.id === inFlowId);
+                        const outFlow = proc.sequenceFlows.find((f) => f.id === outFlowId);
+                        if (!inFlow || !outFlow)
+                            return { description: "Flows not found" };
+                        const srcId = inFlow.sourceRef;
+                        const tgtId = outFlow.targetRef;
+                        const newFlowId = generateId("Flow");
+                        // Remove gateway and its two flows
+                        removeElement(proc, gwId);
+                        removeFlow(proc, inFlowId);
+                        removeFlow(proc, outFlowId);
+                        // Update outgoing/incoming on connected elements
+                        const srcEl = proc.flowElements.find((e) => e.id === srcId);
+                        if (srcEl) {
+                            srcEl.outgoing = srcEl.outgoing.filter((id) => id !== inFlowId);
+                            srcEl.outgoing.push(newFlowId);
+                        }
+                        const tgtEl = proc.flowElements.find((e) => e.id === tgtId);
+                        if (tgtEl) {
+                            tgtEl.incoming = tgtEl.incoming.filter((id) => id !== outFlowId);
+                            tgtEl.incoming.push(newFlowId);
+                        }
+                        const newFlow = {
+                            id: newFlowId,
+                            sourceRef: srcId,
+                            targetRef: tgtId,
+                            extensionElements: [],
+                            unknownAttributes: {},
+                        };
+                        insertFlow(proc, newFlow);
+                        // Update diagram
+                        const plane = findDiPlane(defs, processId);
+                        if (plane) {
+                            plane.shapes = plane.shapes.filter((s) => s.bpmnElement !== gwId);
+                            plane.edges = plane.edges.filter((e) => e.bpmnElement !== inFlowId && e.bpmnElement !== outFlowId);
+                            const srcShape = plane.shapes.find((s) => s.bpmnElement === srcId);
+                            const tgtShape = plane.shapes.find((s) => s.bpmnElement === tgtId);
+                            if (srcShape && tgtShape) {
+                                plane.edges.push({
+                                    id: `${newFlowId}_di`,
+                                    bpmnElement: newFlowId,
+                                    waypoints: [
+                                        {
+                                            x: srcShape.bounds.x + srcShape.bounds.width,
+                                            y: srcShape.bounds.y + srcShape.bounds.height / 2,
+                                        },
+                                        {
+                                            x: tgtShape.bounds.x,
+                                            y: tgtShape.bounds.y + tgtShape.bounds.height / 2,
+                                        },
+                                    ],
+                                    unknownAttributes: {},
+                                });
+                            }
+                        }
+                        return {
+                            description: `Removed redundant gateway "${gwId}" and connected "${srcId}" → "${tgtId}"`,
+                        };
+                    },
+                });
+            }
+        }
+        // flow/mixed-gateway: gateway acting as both split AND join simultaneously
+        if (isGateway(el.type)) {
+            const gwInflows = byTarget.get(el.id) ?? [];
+            const gwOutflows = bySource.get(el.id) ?? [];
+            if (gwInflows.length >= 2 && gwOutflows.length >= 2) {
+                findings.push({
+                    id: "flow/mixed-gateway",
+                    category: "flow",
+                    severity: "warning",
+                    message: `Gateway "${el.id}" (${el.type}) has ${gwInflows.length} incoming and ${gwOutflows.length} outgoing flows — it acts as both a join and a split simultaneously.`,
+                    suggestion: "Separate into two gateways: one join (merging incoming flows) followed by one split (branching outgoing flows).",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+        // flow/empty-subprocess
+        if (el.type === "subProcess" || el.type === "adHocSubProcess" || el.type === "transaction") {
+            if (el.flowElements.length === 0) {
+                findings.push({
+                    id: "flow/empty-subprocess",
+                    category: "flow",
+                    severity: "warning",
+                    message: `Sub-process "${el.id}" (${el.type}) contains no flow elements.`,
+                    suggestion: "Add flow elements inside the sub-process or remove it.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=flow.js.map

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

@@ -0,0 +1,5 @@
+import type { BpmnDefinitions } from "../bpmn-model.js";
+import type { OptimizationReport, OptimizeOptions } from "./types.js";
+/** Run static analysis on a BPMN definitions object. */
+export declare function optimize(defs: BpmnDefinitions, options?: OptimizeOptions): OptimizationReport;
+//# sourceMappingURL=index.d.ts.map

package/dist/bpmn/optimize/index.js

@@ -0,0 +1,51 @@
+import { analyzeFeel } from "./feel.js";
+import { analyzeFlow } from "./flow.js";
+import { analyzeNaming } from "./naming.js";
+import { analyzeTasks } from "./tasks.js";
+const ALL_CATEGORIES = ["feel", "flow", "naming", "task-reuse", "extract"];
+function resolveOptions(opts) {
+    return {
+        feelLengthThreshold: opts?.feelLengthThreshold ?? 80,
+        feelNestingThreshold: opts?.feelNestingThreshold ?? 3,
+        feelOperatorThreshold: opts?.feelOperatorThreshold ?? 5,
+        feelVariableThreshold: opts?.feelVariableThreshold ?? 4,
+        reuseThreshold: opts?.reuseThreshold ?? 2,
+        categories: opts?.categories ?? [...ALL_CATEGORIES],
+    };
+}
+/** Run static analysis on a BPMN definitions object. */
+export function optimize(defs, options) {
+    const resolved = resolveOptions(options);
+    const findings = [];
+    for (const process of defs.processes) {
+        if (resolved.categories.includes("feel")) {
+            findings.push(...analyzeFeel(process, resolved));
+        }
+        if (resolved.categories.includes("flow")) {
+            findings.push(...analyzeFlow(process, resolved));
+        }
+        if (resolved.categories.includes("naming")) {
+            findings.push(...analyzeNaming(process, resolved));
+        }
+        if (resolved.categories.includes("task-reuse")) {
+            findings.push(...analyzeTasks(process, resolved));
+        }
+    }
+    const byCategory = Object.fromEntries(["feel", "flow", "naming", "task-reuse", "extract"].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,
+    ]));
+    return {
+        findings,
+        summary: {
+            total: findings.length,
+            byCategory,
+            bySeverity,
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,8 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding, ResolvedOptions } from "./types.js";
+/**
+ * Analyze BPMN naming conventions based on Camunda best practices:
+ * https://docs.camunda.io/docs/components/best-practices/modeling/naming-bpmnkit-elements/
+ */
+export declare function analyzeNaming(p: BpmnProcess, _opts: ResolvedOptions): OptimizationFinding[];
+//# sourceMappingURL=naming.d.ts.map