@bpmnkit/core 0.1.1 → 0.2.0

package/dist/bpmn/optimize/deploy.js

@@ -0,0 +1,143 @@
+import { readZeebeIoMapping, readZeebeTaskHeaders, readZeebeTaskType } from "./utils.js";
+function findExt(el, name) {
+    return el.extensionElements.find((e) => e.name === name);
+}
+/**
+ * Zeebe/Reebe deploy-parity checks — mirrors what Camunda 8 rejects at
+ * deployment time (`apps/reebe/crates/reebe-bpmn/src/validator.rs`), so a
+ * process that passes this profile deploys without a validation error.
+ */
+export function analyzeDeploy(p, resolveConnectorRequirements) {
+    const findings = [];
+    const processId = p.id;
+    if (p.isExecutable !== true) {
+        findings.push({
+            id: "deploy/process-not-executable",
+            category: "deploy",
+            severity: "error",
+            message: `Process "${processId}" is not marked executable.`,
+            suggestion: 'Set isExecutable="true" — Camunda 8 refuses to deploy a non-executable process.',
+            processId,
+            elementIds: [],
+        });
+    }
+    for (const el of p.flowElements) {
+        if (el.type === "serviceTask" || el.type === "sendTask") {
+            const type = readZeebeTaskType(el.extensionElements);
+            if (!type) {
+                findings.push({
+                    id: "deploy/service-task-no-type",
+                    category: "deploy",
+                    severity: "error",
+                    message: `"${el.name ?? el.id}" (${el.type}) has no zeebe:taskDefinition type.`,
+                    suggestion: "Set a job type — Camunda 8 refuses to deploy a task with no task definition.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+        if (el.type === "businessRuleTask") {
+            const hasType = readZeebeTaskType(el.extensionElements) !== null;
+            const hasDecision = findExt(el, "zeebe:calledDecision") !== undefined;
+            if (!hasType && !hasDecision) {
+                findings.push({
+                    id: "deploy/service-task-no-type",
+                    category: "deploy",
+                    severity: "error",
+                    message: `"${el.name ?? el.id}" (businessRuleTask) has neither a zeebe:taskDefinition type nor a zeebe:calledDecision.`,
+                    suggestion: "Set a decisionId or a job type.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+        if (el.type === "callActivity") {
+            const called = findExt(el, "zeebe:calledElement");
+            if (!called?.attributes.processId) {
+                findings.push({
+                    id: "deploy/call-activity-no-process",
+                    category: "deploy",
+                    severity: "error",
+                    message: `Call activity "${el.name ?? el.id}" has no zeebe:calledElement processId.`,
+                    suggestion: "Set the process id to call.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+        if (el.type === "startEvent") {
+            const messageDef = el.eventDefinitions.find((d) => d.type === "message");
+            if (messageDef && !messageDef.messageRef) {
+                findings.push({
+                    id: "deploy/message-start-no-name",
+                    category: "deploy",
+                    severity: "error",
+                    message: `Message start event "${el.name ?? el.id}" has no message name.`,
+                    suggestion: "Set a message name — Camunda 8 refuses to deploy an unnamed message reference.",
+                    processId,
+                    elementIds: [el.id],
+                });
+            }
+        }
+        if (el.type === "intermediateCatchEvent" ||
+            el.type === "boundaryEvent" ||
+            el.type === "receiveTask") {
+            const messageDef = el.type === "receiveTask"
+                ? undefined
+                : el.eventDefinitions.find((d) => d.type === "message");
+            const isMessageCatch = el.type === "receiveTask" ? el.messageRef !== undefined : messageDef !== undefined;
+            if (isMessageCatch) {
+                const subscription = findExt(el, "zeebe:subscription");
+                if (!subscription?.attributes.correlationKey) {
+                    findings.push({
+                        id: "deploy/message-catch-no-correlation",
+                        category: "deploy",
+                        severity: "error",
+                        message: `Message catch "${el.name ?? el.id}" (${el.type}) has no zeebe:subscription correlationKey.`,
+                        suggestion: "Set a correlation key — required for every message catch in Camunda 8.",
+                        processId,
+                        elementIds: [el.id],
+                    });
+                }
+            }
+        }
+        if (resolveConnectorRequirements) {
+            const templateId = el.unknownAttributes["zeebe:modelerTemplate"];
+            if (templateId) {
+                const boundKeys = new Set();
+                const io = readZeebeIoMapping(el.extensionElements);
+                if (io) {
+                    for (const i of io.inputs)
+                        boundKeys.add(i.target);
+                    for (const o of io.outputs)
+                        boundKeys.add(o.target);
+                }
+                const headers = readZeebeTaskHeaders(el.extensionElements);
+                if (headers)
+                    for (const h of headers.headers)
+                        boundKeys.add(h.key);
+                const propsExt = findExt(el, "zeebe:properties");
+                if (propsExt) {
+                    for (const child of propsExt.children ?? []) {
+                        if (child.attributes.name)
+                            boundKeys.add(child.attributes.name);
+                    }
+                }
+                const missing = resolveConnectorRequirements(templateId, [...boundKeys]);
+                for (const key of missing) {
+                    findings.push({
+                        id: "connector/missing-required",
+                        category: "connector",
+                        severity: "error",
+                        message: `"${el.name ?? el.id}" is missing required connector value "${key}" for template "${templateId}".`,
+                        suggestion: `Set a value for "${key}".`,
+                        processId,
+                        elementIds: [el.id],
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=deploy.js.map

package/dist/bpmn/optimize/feel-syntax.d.ts

@@ -0,0 +1,12 @@
+import type { BpmnProcess } from "../bpmn-model.js";
+import type { OptimizationFinding } from "./types.js";
+/**
+ * Parse-validates every FEEL-looking expression (leading "=") in the process:
+ * sequence-flow conditions, zeebe:input/output sources, script task
+ * expressions, and ad-hoc sub-process completion conditions/outputElement —
+ * including inside nested sub-processes. Unlike `feel.ts` (heuristic
+ * complexity scoring), this uses the real `@bpmnkit/feel` parser and reports
+ * genuine syntax errors, not style suggestions.
+ */
+export declare function analyzeFeelSyntax(p: BpmnProcess): OptimizationFinding[];
+//# sourceMappingURL=feel-syntax.d.ts.map

package/dist/bpmn/optimize/feel-syntax.js

@@ -0,0 +1,87 @@
+import { parseExpression } from "@bpmnkit/feel";
+import { readZeebeIoMapping } from "./utils.js";
+/** Recursively yields every flow element in a process, including inside sub-processes/ad-hoc sub-processes. */
+function* walkElements(elements) {
+    for (const el of elements) {
+        yield el;
+        if (el.type === "subProcess" ||
+            el.type === "adHocSubProcess" ||
+            el.type === "eventSubProcess" ||
+            el.type === "transaction") {
+            yield* walkElements(el.flowElements);
+        }
+    }
+}
+/** Recursively yields every sequence flow, including inside sub-processes/ad-hoc sub-processes. */
+function* walkFlows(elements, topLevel) {
+    yield* topLevel;
+    for (const el of elements) {
+        if (el.type === "subProcess" ||
+            el.type === "adHocSubProcess" ||
+            el.type === "eventSubProcess" ||
+            el.type === "transaction") {
+            yield* walkFlows(el.flowElements, el.sequenceFlows);
+        }
+    }
+}
+function checkFeel(text, elementId, processId, surface, findings) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("="))
+        return;
+    const { errors } = parseExpression(trimmed.slice(1));
+    for (const err of errors) {
+        findings.push({
+            id: "feel-syntax/parse-error",
+            category: "feel-syntax",
+            severity: "error",
+            message: `Invalid FEEL expression on ${surface} of "${elementId}": ${err.message}`,
+            suggestion: "Fix the FEEL syntax — see the error position for the offending token.",
+            processId,
+            elementIds: [elementId],
+        });
+    }
+}
+/**
+ * Parse-validates every FEEL-looking expression (leading "=") in the process:
+ * sequence-flow conditions, zeebe:input/output sources, script task
+ * expressions, and ad-hoc sub-process completion conditions/outputElement —
+ * including inside nested sub-processes. Unlike `feel.ts` (heuristic
+ * complexity scoring), this uses the real `@bpmnkit/feel` parser and reports
+ * genuine syntax errors, not style suggestions.
+ */
+export function analyzeFeelSyntax(p) {
+    const findings = [];
+    const processId = p.id;
+    for (const flow of walkFlows(p.flowElements, p.sequenceFlows)) {
+        if (flow.conditionExpression?.text) {
+            checkFeel(flow.conditionExpression.text, flow.id, processId, "condition", findings);
+        }
+    }
+    for (const el of walkElements(p.flowElements)) {
+        const io = readZeebeIoMapping(el.extensionElements);
+        if (io) {
+            for (const input of io.inputs)
+                checkFeel(input.source, el.id, processId, `input "${input.target}"`, findings);
+            for (const output of io.outputs)
+                checkFeel(output.source, el.id, processId, `output "${output.target}"`, findings);
+        }
+        const scriptExt = el.extensionElements.find((e) => e.name === "zeebe:script");
+        if (scriptExt?.attributes.expression) {
+            checkFeel(scriptExt.attributes.expression, el.id, processId, "script expression", findings);
+        }
+        if (el.type === "adHocSubProcess") {
+            if (el.completionCondition?.text) {
+                checkFeel(el.completionCondition.text, el.id, processId, "completion condition", findings);
+            }
+            const adHocExt = el.extensionElements.find((e) => e.name === "zeebe:adHoc");
+            if (adHocExt?.attributes.outputElement) {
+                checkFeel(adHocExt.attributes.outputElement, el.id, processId, "outputElement", findings);
+            }
+            if (adHocExt?.attributes.activeElementsCollection) {
+                checkFeel(adHocExt.attributes.activeElementsCollection, el.id, processId, "activeElementsCollection", findings);
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=feel-syntax.js.map

package/dist/bpmn/optimize/feel.js

@@ -58,15 +58,18 @@ function scoreFeelExpression(expr, opts) {
 // ---------------------------------------------------------------------------
 export function analyzeFeel(p, opts) {
     const findings = [];
-    const { bySource } = buildFlowIndex(p);
+    const { byId, 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);
+        // Determine if source is an exclusive/inclusive gateway with more than one
+        // outgoing flow — a join (single outgoing flow) makes no decision, so its
+        // one outgoing flow needs neither a condition nor a default marker.
+        const srcEl = byId.get(flow.sourceRef);
         const srcIsDecisionGateway = srcEl !== undefined &&
-            (srcEl.type === "exclusiveGateway" || srcEl.type === "inclusiveGateway");
+            (srcEl.type === "exclusiveGateway" || srcEl.type === "inclusiveGateway") &&
+            (bySource.get(srcEl.id)?.length ?? 0) > 1;
         if (srcIsDecisionGateway && srcEl !== undefined) {
             const defaultFlowId = srcEl.type === "exclusiveGateway" || srcEl.type === "inclusiveGateway"
                 ? srcEl.default

package/dist/bpmn/optimize/flow.js

@@ -32,8 +32,28 @@ export function analyzeFlow(p, _opts) {
             elementIds: [],
         });
     }
-    // BFS reachability from start events
-    const reachable = reachableFrom(startIds, bySource);
+    // BFS reachability from start events. Boundary events have no incoming
+    // sequence flow by design (they attach via `attachedToRef`), so add a
+    // synthetic edge from each host element to its boundary event(s) —
+    // otherwise every boundary event (and everything chained after it) would
+    // always be flagged as unreachable.
+    const reachabilityEdges = new Map(bySource);
+    for (const el of p.flowElements) {
+        if (el.type !== "boundaryEvent")
+            continue;
+        const hostEdges = reachabilityEdges.get(el.attachedToRef) ?? [];
+        reachabilityEdges.set(el.attachedToRef, [
+            ...hostEdges,
+            {
+                id: `synthetic-attachment-${el.id}`,
+                sourceRef: el.attachedToRef,
+                targetRef: el.id,
+                extensionElements: [],
+                unknownAttributes: {},
+            },
+        ]);
+    }
+    const reachable = reachableFrom(startIds, reachabilityEdges);
     for (const el of p.flowElements) {
         // flow/unreachable
         if (!reachable.has(el.id)) {

package/dist/bpmn/optimize/index.js

@@ -1,3 +1,6 @@
+import { analyzeAgentic } from "./agentic.js";
+import { analyzeDeploy } from "./deploy.js";
+import { analyzeFeelSyntax } from "./feel-syntax.js";
 import { analyzeFeel } from "./feel.js";
 import { analyzeFlow } from "./flow.js";
 import { analyzeNaming } from "./naming.js";
@@ -6,12 +9,16 @@ import { analyzeTasks } from "./tasks.js";
 import { analyzeVariableFlow } from "./variable-flow.js";
 const ALL_CATEGORIES = [
     "feel",
+    "feel-syntax",
     "flow",
     "naming",
     "task-reuse",
     "extract",
     "pattern",
     "data-flow",
+    "deploy",
+    "agentic",
+    "connector",
 ];
 function resolveOptions(opts) {
     return {
@@ -21,6 +28,7 @@ function resolveOptions(opts) {
         feelVariableThreshold: opts?.feelVariableThreshold ?? 4,
         reuseThreshold: opts?.reuseThreshold ?? 2,
         categories: opts?.categories ?? [...ALL_CATEGORIES],
+        resolveConnectorRequirements: opts?.resolveConnectorRequirements,
     };
 }
 /** Run static analysis on a BPMN definitions object. */
@@ -31,6 +39,9 @@ export function optimize(defs, options) {
         if (resolved.categories.includes("feel")) {
             findings.push(...analyzeFeel(process, resolved));
         }
+        if (resolved.categories.includes("feel-syntax")) {
+            findings.push(...analyzeFeelSyntax(process));
+        }
         if (resolved.categories.includes("flow")) {
             findings.push(...analyzeFlow(process, resolved));
         }
@@ -46,16 +57,16 @@ export function optimize(defs, options) {
         if (resolved.categories.includes("data-flow")) {
             findings.push(...analyzeVariableFlow(process));
         }
+        if (resolved.categories.includes("deploy") || resolved.categories.includes("connector")) {
+            const deployFindings = analyzeDeploy(process, resolved.resolveConnectorRequirements);
+            findings.push(...deployFindings.filter((f) => (f.category === "deploy" && resolved.categories.includes("deploy")) ||
+                (f.category === "connector" && resolved.categories.includes("connector"))));
+        }
+        if (resolved.categories.includes("agentic")) {
+            findings.push(...analyzeAgentic(process));
+        }
     }
-    const byCategory = Object.fromEntries([
-        "feel",
-        "flow",
-        "naming",
-        "task-reuse",
-        "extract",
-        "pattern",
-        "data-flow",
-    ].map((c) => [c, findings.filter((f) => f.category === c).length]));
+    const byCategory = Object.fromEntries(ALL_CATEGORIES.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.js

@@ -2,19 +2,25 @@ import { buildFlowIndex, readZeebeIoMapping, readZeebeTaskType } from "./utils.j
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-/** Returns true if the element has a boundary event of the given type attached. */
-function hasBoundaryOf(elementId, eventType, p) {
+/** hostId → event-definition types of the boundary events attached to it. */
+function indexBoundaryTypes(p) {
+    const index = new Map();
     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;
+        let types = index.get(el.attachedToRef);
+        if (!types) {
+            types = new Set();
+            index.set(el.attachedToRef, types);
         }
+        for (const def of el.eventDefinitions)
+            types.add(def.type);
     }
-    return false;
+    return index;
+}
+/** Returns true if the element has a boundary event of the given type attached. */
+function hasBoundaryOf(elementId, eventType, boundaryTypes) {
+    return boundaryTypes.get(elementId)?.has(eventType) ?? false;
 }
 /** Returns true if the condition expression text appears to contain only literals (no variable names). */
 function isLiteralOnlyCondition(text) {
@@ -36,7 +42,8 @@ function isLiteralOnlyCondition(text) {
 export function analyzePatterns(p) {
     const findings = [];
     const processId = p.id;
-    const { bySource, byTarget } = buildFlowIndex(p);
+    const { byId, bySource, byTarget } = buildFlowIndex(p);
+    const boundaryTypes = indexBoundaryTypes(p);
     // ── Rule 1: HTTP/REST service task without error boundary ───────────────
     for (const el of p.flowElements) {
         if (el.type !== "serviceTask")
@@ -47,7 +54,7 @@ export function analyzePatterns(p) {
             jobType === "io.camunda.connector.HttpJson:1";
         if (!isHttp)
             continue;
-        if (!hasBoundaryOf(el.id, "error", p)) {
+        if (!hasBoundaryOf(el.id, "error", boundaryTypes)) {
             findings.push({
                 id: "pattern/http-no-error-boundary",
                 category: "pattern",
@@ -82,7 +89,7 @@ export function analyzePatterns(p) {
     for (const el of p.flowElements) {
         if (el.type !== "subProcess" && el.type !== "adHocSubProcess" && el.type !== "transaction")
             continue;
-        if (!hasBoundaryOf(el.id, "error", p)) {
+        if (!hasBoundaryOf(el.id, "error", boundaryTypes)) {
             findings.push({
                 id: "pattern/subprocess-no-error-boundary",
                 category: "pattern",
@@ -98,7 +105,7 @@ export function analyzePatterns(p) {
     for (const el of p.flowElements) {
         if (el.type !== "callActivity")
             continue;
-        if (!hasBoundaryOf(el.id, "error", p)) {
+        if (!hasBoundaryOf(el.id, "error", boundaryTypes)) {
             findings.push({
                 id: "pattern/call-activity-no-error-boundary",
                 category: "pattern",
@@ -121,7 +128,7 @@ export function analyzePatterns(p) {
         const branchTargets = [];
         for (const flow of outflows) {
             const targets = [];
-            const branchEl = p.flowElements.find((e) => e.id === flow.targetRef);
+            const branchEl = byId.get(flow.targetRef);
             if (branchEl !== undefined) {
                 const io = readZeebeIoMapping(branchEl.extensionElements);
                 if (io !== null) {
@@ -158,7 +165,7 @@ export function analyzePatterns(p) {
     for (const el of p.flowElements) {
         if (el.type !== "userTask")
             continue;
-        if (!hasBoundaryOf(el.id, "timer", p)) {
+        if (!hasBoundaryOf(el.id, "timer", boundaryTypes)) {
             findings.push({
                 id: "pattern/user-task-no-timer",
                 category: "pattern",
@@ -200,7 +207,7 @@ export function analyzePatterns(p) {
             continue;
         const outflows = bySource.get(el.id) ?? [];
         for (const flow of outflows) {
-            const target = p.flowElements.find((e) => e.id === flow.targetRef);
+            const target = byId.get(flow.targetRef);
             if (target !== undefined && target.type === "endEvent") {
                 findings.push({
                     id: "pattern/catch-and-swallow",
@@ -348,7 +355,7 @@ export function analyzePatterns(p) {
         if (cond === undefined || cond === "")
             continue;
         if (isLiteralOnlyCondition(cond)) {
-            const sourceEl = p.flowElements.find((e) => e.id === flow.sourceRef);
+            const sourceEl = byId.get(flow.sourceRef);
             findings.push({
                 id: "pattern/literal-condition",
                 category: "pattern",

package/dist/bpmn/optimize/tasks.js

@@ -53,21 +53,45 @@ function computeSimilarity(a, b) {
         score += 0.15;
     return score;
 }
-/** Cluster service tasks into connected components above the similarity threshold. */
+/**
+ * Cluster service tasks into connected components above the similarity
+ * threshold. Similarity requires an identical job type, so tasks are bucketed
+ * by type first and the pairwise comparison only runs within a bucket.
+ */
 function cluster(tasks, threshold) {
+    const byType = new Map();
+    const clusters = [];
+    for (const task of tasks) {
+        const type = readZeebeTaskType(task.extensionElements);
+        // Without a job type nothing is similar to this task; it stands alone.
+        if (type === null) {
+            clusters.push([task]);
+            continue;
+        }
+        const bucket = byType.get(type);
+        if (bucket)
+            bucket.push(task);
+        else
+            byType.set(type, [task]);
+    }
+    for (const bucket of byType.values())
+        clusterBucket(bucket, threshold, clusters);
+    // Report clusters in declaration order of their first member.
+    const order = new Map(tasks.map((task, index) => [task, index]));
+    clusters.sort((a, b) => (order.get(a[0]) ?? 0) - (order.get(b[0]) ?? 0));
+    return clusters;
+}
+function clusterBucket(tasks, threshold, clusters) {
     const n = tasks.length;
     const visited = new Array(n).fill(false);
-    const clusters = [];
     for (let i = 0; i < n; i++) {
         if (visited[i])
             continue;
         const group = [];
         const queue = [i];
         visited[i] = true;
-        while (queue.length > 0) {
-            const curr = queue.shift();
-            if (curr === undefined)
-                break;
+        for (let head = 0; head < queue.length; head++) {
+            const curr = queue[head];
             const task = tasks[curr];
             if (task === undefined)
                 break;
@@ -87,7 +111,6 @@ function cluster(tasks, threshold) {
         }
         clusters.push(group);
     }
-    return clusters;
 }
 // ---------------------------------------------------------------------------
 // Build the extracted BpmnDefinitions

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" | "pattern" | "data-flow";
+export type OptimizationCategory = "feel" | "feel-syntax" | "flow" | "naming" | "task-reuse" | "extract" | "pattern" | "data-flow" | "deploy" | "agentic" | "connector";
 export interface ApplyFixResult {
     description: string;
     /** New BpmnDefinitions generated by the fix (e.g. extracted reusable sub-process). */
@@ -36,6 +36,14 @@ export interface OptimizeOptions {
     feelVariableThreshold?: number;
     reuseThreshold?: number;
     categories?: OptimizationCategory[];
+    /**
+     * Resolves a bundled connector template's missing required value keys —
+     * pass `(templateId, boundKeys) => applyConnectorTemplate(templateId,
+     * Object.fromEntries(boundKeys.map(k => [k, "x"]))).problems...` or an
+     * equivalent from `@bpmnkit/connectors`. Without it, `connector/*` findings
+     * are skipped (core has no dependency on the connector catalog).
+     */
+    resolveConnectorRequirements?: (templateId: string, boundKeys: string[]) => string[];
 }
 export interface ResolvedOptions {
     feelLengthThreshold: number;
@@ -44,5 +52,6 @@ export interface ResolvedOptions {
     feelVariableThreshold: number;
     reuseThreshold: number;
     categories: OptimizationCategory[];
+    resolveConnectorRequirements?: (templateId: string, boundKeys: string[]) => string[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/bpmn/optimize/utils.js

@@ -70,10 +70,8 @@ export function buildFlowIndex(p) {
 export function reachableFrom(startIds, bySource) {
     const visited = new Set(startIds);
     const queue = [...startIds];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (current === undefined)
-            break;
+    for (let head = 0; head < queue.length; head++) {
+        const current = queue[head];
         const outflows = bySource.get(current) ?? [];
         for (const flow of outflows) {
             if (!visited.has(flow.targetRef)) {