@bpmnkit/core 1.6.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/AGENTS.md +19 -0
  2. package/README.md +2 -0
  3. package/agent-cards/bpmn.md +86 -0
  4. package/agent-cards/dmn.md +105 -0
  5. package/agent-cards/form.md +72 -0
  6. package/builder-reference.md +211 -0
  7. package/dist/bpmn/auto-layout.js +34 -5
  8. package/dist/bpmn/bpmn-builder.d.ts +127 -5
  9. package/dist/bpmn/bpmn-builder.js +270 -40
  10. package/dist/bpmn/bpmn-model.d.ts +2 -0
  11. package/dist/bpmn/bpmn-parser.js +8 -0
  12. package/dist/bpmn/bpmn-serializer.js +1 -1
  13. package/dist/bpmn/builder-coverage.js +4 -12
  14. package/dist/bpmn/camunda7/export.d.ts +25 -0
  15. package/dist/bpmn/camunda7/export.js +218 -0
  16. package/dist/bpmn/camunda7/migrate.d.ts +4 -1
  17. package/dist/bpmn/camunda7/migrate.js +4 -4
  18. package/dist/bpmn/compact.d.ts +21 -0
  19. package/dist/bpmn/compact.js +86 -1
  20. package/dist/bpmn/full-operations.js +338 -3
  21. package/dist/bpmn/index.d.ts +2 -0
  22. package/dist/bpmn/index.js +2 -0
  23. package/dist/bpmn/operations.d.ts +42 -1
  24. package/dist/bpmn/operations.js +12 -2
  25. package/dist/bpmn/optimize/deploy.js +14 -0
  26. package/dist/bpmn/optimize/index.d.ts +2 -0
  27. package/dist/bpmn/optimize/index.js +5 -0
  28. package/dist/bpmn/optimize/types.d.ts +7 -0
  29. package/dist/bpmn/stable-ids.d.ts +15 -0
  30. package/dist/bpmn/stable-ids.js +26 -0
  31. package/dist/bpmn/strip-camunda8.d.ts +22 -0
  32. package/dist/bpmn/strip-camunda8.js +55 -0
  33. package/dist/bpmn/svg.js +5 -6
  34. package/dist/bpmn/utils.js +151 -1
  35. package/dist/bpmn/zeebe-extensions.d.ts +59 -2
  36. package/dist/bpmn/zeebe-extensions.js +89 -1
  37. package/dist/check-finding.d.ts +19 -0
  38. package/dist/check-finding.js +5 -0
  39. package/dist/connectors/apply-element.d.ts +7 -3
  40. package/dist/connectors/apply-element.js +115 -4
  41. package/dist/connectors/apply-many.d.ts +5 -1
  42. package/dist/connectors/apply-many.js +5 -2
  43. package/dist/connectors/apply.d.ts +24 -3
  44. package/dist/connectors/apply.js +103 -3
  45. package/dist/connectors/catalog.js +5 -0
  46. package/dist/connectors/index.d.ts +1 -1
  47. package/dist/connectors/template-types.d.ts +30 -0
  48. package/dist/connectors/validate.js +33 -0
  49. package/dist/dmn/compact.js +14 -5
  50. package/dist/dmn/dmn-builder.js +3 -3
  51. package/dist/dmn/drd-builder.d.ts +53 -0
  52. package/dist/dmn/drd-builder.js +100 -0
  53. package/dist/dmn/index.d.ts +35 -0
  54. package/dist/dmn/index.js +36 -0
  55. package/dist/dmn/lint.d.ts +19 -0
  56. package/dist/dmn/lint.js +414 -0
  57. package/dist/form/form-builder.d.ts +9 -1
  58. package/dist/form/form-builder.js +34 -1
  59. package/dist/form/form-model.d.ts +7 -0
  60. package/dist/form/form-parser.js +22 -0
  61. package/dist/form/form-serializer.js +10 -0
  62. package/dist/form/index.d.ts +11 -2
  63. package/dist/form/index.js +10 -1
  64. package/dist/form/lint.d.ts +19 -0
  65. package/dist/form/lint.js +356 -0
  66. package/dist/index.d.ts +19 -5
  67. package/dist/index.js +12 -2
  68. package/dist/layout/annotations.d.ts +3 -1
  69. package/dist/layout/annotations.js +72 -14
  70. package/dist/layout/grid/edge-labels.d.ts +7 -1
  71. package/dist/layout/grid/edge-labels.js +62 -1
  72. package/dist/layout/semantic/index.js +78 -8
  73. package/dist/layout/semantic/place.d.ts +19 -4
  74. package/dist/layout/semantic/place.js +245 -29
  75. package/dist/layout/semantic/route.js +60 -12
  76. package/dist/layout/types.d.ts +2 -1
  77. package/llms.txt +9 -0
  78. package/package.json +6 -1
@@ -1,6 +1,7 @@
1
1
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
2
2
  import { buildFlowElement, defaultFlows, makeEventDef, } from "./compact.js";
3
- import { bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, } from "./zeebe-extensions.js";
3
+ import { assignEventDefinitionIds } from "./stable-ids.js";
4
+ import { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
4
5
  /** Thrown by {@link applyBpmnOperations} in strict mode. */
5
6
  export class OperationError extends Error {
6
7
  problems;
@@ -96,7 +97,227 @@ const PATCH_EXTENSIONS = [
96
97
  ["outputs", "zeebe:ioMapping"],
97
98
  ["nativeUserTask", "zeebe:userTask"],
98
99
  ["taskHeaders", "zeebe:taskHeaders"],
100
+ ["assignee", "zeebe:assignmentDefinition"],
101
+ ["candidateGroups", "zeebe:assignmentDefinition"],
102
+ ["candidateUsers", "zeebe:assignmentDefinition"],
103
+ ["dueDate", "zeebe:taskSchedule"],
104
+ ["followUpDate", "zeebe:taskSchedule"],
105
+ ["priority", "zeebe:priorityDefinition"],
106
+ ["properties", "zeebe:properties"],
107
+ ["executionListeners", "zeebe:executionListeners"],
108
+ ["taskListeners", "zeebe:taskListeners"],
99
109
  ];
110
+ /** Activities that can carry a `bpmn:multiInstanceLoopCharacteristics`. */
111
+ const LOOPABLE = new Set([
112
+ "serviceTask",
113
+ "scriptTask",
114
+ "userTask",
115
+ "businessRuleTask",
116
+ "callActivity",
117
+ "sendTask",
118
+ "receiveTask",
119
+ "manualTask",
120
+ "task",
121
+ "subProcess",
122
+ "adHocSubProcess",
123
+ "transaction",
124
+ ]);
125
+ const ROOT_FIELDS = [
126
+ ["messageName", "message", "name"],
127
+ ["errorCode", "error", "errorCode"],
128
+ ["escalationCode", "escalation", "escalationCode"],
129
+ ["signalName", "signal", "name"],
130
+ ];
131
+ const TIMER_FIELDS = [
132
+ ["timerDuration", "timeDuration"],
133
+ ["timerDate", "timeDate"],
134
+ ["timerCycle", "timeCycle"],
135
+ ];
136
+ function rootsOf(definitions, kind) {
137
+ return kind === "message"
138
+ ? definitions.messages
139
+ : kind === "error"
140
+ ? definitions.errors
141
+ : kind === "escalation"
142
+ ? definitions.escalations
143
+ : definitions.signals;
144
+ }
145
+ function refKey(kind) {
146
+ return `${kind}Ref`;
147
+ }
148
+ function eventDefinitionOf(element, type) {
149
+ return "eventDefinitions" in element
150
+ ? element.eventDefinitions.find((d) => d.type === type)
151
+ : undefined;
152
+ }
153
+ /** How many events reference the root element, so a shared one is not edited for all. */
154
+ function referenceCount(definitions, kind, id) {
155
+ let count = 0;
156
+ for (const container of containersOf(definitions)) {
157
+ for (const candidate of container.flowElements) {
158
+ // A send/receive task points at its message directly.
159
+ if (asRecord(candidate)[refKey(kind)] === id)
160
+ count++;
161
+ if (!("eventDefinitions" in candidate))
162
+ continue;
163
+ for (const definition of candidate.eventDefinitions) {
164
+ if (definition.type === kind && asRecord(definition)[refKey(kind)] === id)
165
+ count++;
166
+ }
167
+ }
168
+ }
169
+ return count;
170
+ }
171
+ /**
172
+ * Checks the event-definition fields of a patch without writing, so a failure
173
+ * leaves the element as it was. Returns the reason, or nothing.
174
+ */
175
+ function misplacedEventFields(definitions, element, patch) {
176
+ for (const [field, kind] of ROOT_FIELDS) {
177
+ if (patch[field] === undefined)
178
+ continue;
179
+ const definition = eventDefinitionOf(element, kind);
180
+ if (!definition)
181
+ return `${field} needs a ${kind} event definition, and "${element.id}" has none`;
182
+ const ref = asRecord(definition)[refKey(kind)];
183
+ if (typeof ref === "string" &&
184
+ rootsOf(definitions, kind).some((root) => root.id === ref) &&
185
+ referenceCount(definitions, kind, ref) > 1) {
186
+ return `${field}: the ${kind} "${ref}" is shared by ${referenceCount(definitions, kind, ref)} elements; changing it would change them all`;
187
+ }
188
+ }
189
+ for (const [field] of TIMER_FIELDS) {
190
+ if (patch[field] !== undefined && !eventDefinitionOf(element, "timer")) {
191
+ return `${field} needs a timer event definition, and "${element.id}" has none`;
192
+ }
193
+ }
194
+ if (patch.condition !== undefined && !eventDefinitionOf(element, "conditional")) {
195
+ return `condition needs a conditional event definition, and "${element.id}" has none`;
196
+ }
197
+ if (patch.messageName === "" && patch.correlationKey !== undefined) {
198
+ return 'correlationKey needs a message, and messageName: "" clears it';
199
+ }
200
+ if (patch.multiInstance !== undefined) {
201
+ if (!LOOPABLE.has(element.type)) {
202
+ return `multiInstance is not allowed on <${bpmnElementName(element)}>: only activities can run multi-instance`;
203
+ }
204
+ const current = "loopCharacteristics" in element ? element.loopCharacteristics : undefined;
205
+ if (!current && !patch.multiInstance.collection && patch.multiInstance.collection !== "") {
206
+ return "multiInstance needs a collection to add a loop to this element";
207
+ }
208
+ }
209
+ return undefined;
210
+ }
211
+ function idTaken(definitions, id) {
212
+ return (findElement(definitions, id) !== undefined ||
213
+ definitions.processes.some((p) => p.id === id) ||
214
+ [
215
+ ...definitions.messages,
216
+ ...definitions.errors,
217
+ ...definitions.escalations,
218
+ ...definitions.signals,
219
+ ].some((root) => root.id === id));
220
+ }
221
+ /** Index access on a model object, for fields chosen by name at runtime. */
222
+ function asRecord(value) {
223
+ return value;
224
+ }
225
+ /** Sets or, for `""`, removes a field on a plain record. */
226
+ function setOrDelete(target, key, value) {
227
+ const record = asRecord(target);
228
+ if (value === "")
229
+ delete record[key];
230
+ else
231
+ record[key] = value;
232
+ }
233
+ function applyEventFields(definitions, element, patch) {
234
+ for (const [field, kind, target] of ROOT_FIELDS) {
235
+ const value = patch[field];
236
+ if (value === undefined)
237
+ continue;
238
+ const found = eventDefinitionOf(element, kind);
239
+ if (!found)
240
+ continue;
241
+ const definition = asRecord(found);
242
+ const roots = rootsOf(definitions, kind);
243
+ let root = roots.find((candidate) => candidate.id === definition[refKey(kind)]);
244
+ if (!root) {
245
+ if (value === "")
246
+ continue;
247
+ let id = `${kind[0]?.toUpperCase()}${kind.slice(1)}_${element.id}`;
248
+ // Ids are unique across the whole document, not per kind.
249
+ while (idTaken(definitions, id))
250
+ id += "_";
251
+ root = { id, unknownAttributes: {} };
252
+ roots.push(root);
253
+ definition[refKey(kind)] = id;
254
+ }
255
+ setOrDelete(root, target, value);
256
+ }
257
+ const timer = eventDefinitionOf(element, "timer");
258
+ if (timer) {
259
+ for (const [field, key] of TIMER_FIELDS) {
260
+ const value = patch[field];
261
+ if (value === undefined)
262
+ continue;
263
+ setOrDelete(timer, key, value);
264
+ if (value === "")
265
+ delete asRecord(timer)[`${key}Attributes`];
266
+ }
267
+ }
268
+ const conditional = eventDefinitionOf(element, "conditional");
269
+ if (conditional?.type === "conditional" && patch.condition !== undefined) {
270
+ // "" stays "" rather than deleting the key: that is how the parser
271
+ // represents an empty condition, so a no-change reconcile stays a no-op.
272
+ conditional.condition = patch.condition;
273
+ if (patch.condition !== "") {
274
+ conditional.conditionAttributes ??= { "xsi:type": "bpmn:tFormalExpression" };
275
+ }
276
+ }
277
+ }
278
+ /** Applies the named parts of a multi-instance loop; see {@link ElementPatch.multiInstance}. */
279
+ function applyMultiInstance(element, patch) {
280
+ if (!("loopCharacteristics" in element) && !LOOPABLE.has(element.type))
281
+ return;
282
+ const holder = element;
283
+ if (patch.collection === "") {
284
+ Reflect.deleteProperty(holder, "loopCharacteristics");
285
+ return;
286
+ }
287
+ holder.loopCharacteristics ??= { extensionElements: [] };
288
+ const loop = holder.loopCharacteristics;
289
+ const zeebe = ensureLoopExtension(loop);
290
+ if (patch.collection !== undefined)
291
+ zeebe.attributes.inputCollection = patch.collection;
292
+ if (patch.sequential !== undefined)
293
+ loop.isSequential = patch.sequential || undefined;
294
+ for (const key of ["element", "outputCollection", "outputElement"]) {
295
+ const value = patch[key];
296
+ if (value === undefined)
297
+ continue;
298
+ setOrDelete(zeebe.attributes, key === "element" ? "inputElement" : key, value);
299
+ }
300
+ const wanted = patch.completionCondition;
301
+ if (wanted === "")
302
+ loop.completionCondition = undefined;
303
+ // Keeps the existing attributes (namespace declarations) when only the text changes.
304
+ else if (wanted !== undefined && loop.completionCondition)
305
+ loop.completionCondition.text = wanted;
306
+ else if (wanted !== undefined) {
307
+ loop.completionCondition = {
308
+ text: wanted,
309
+ attributes: { "xsi:type": "bpmn:tFormalExpression" },
310
+ };
311
+ }
312
+ }
313
+ function ensureLoopExtension(loop) {
314
+ const existing = loop.extensionElements.find((e) => e.name === "zeebe:loopCharacteristics");
315
+ if (existing)
316
+ return existing;
317
+ const created = { name: "zeebe:loopCharacteristics", attributes: {}, children: [] };
318
+ loop.extensionElements.push(created);
319
+ return created;
320
+ }
100
321
  /**
101
322
  * Reports a patch field that would write an extension the Zeebe schema does not
102
323
  * allow on this element — `decisionId` on a service task, say.
@@ -128,6 +349,24 @@ function misplacedExtensions(element, patch) {
128
349
  function setExtensionAttribute(element, extensionName, attribute, value) {
129
350
  ensureExtension(element, extensionName).attributes[attribute] = value;
130
351
  }
352
+ /**
353
+ * Like {@link setExtensionAttribute}, but an empty string removes the attribute
354
+ * and an extension left with nothing in it. The only way for a patch to unset a
355
+ * value, since `""` is never a meaningful assignee, schedule or priority.
356
+ */
357
+ function setOrClearAttribute(element, extensionName, attribute, value) {
358
+ if (value !== "") {
359
+ setExtensionAttribute(element, extensionName, attribute, value);
360
+ return;
361
+ }
362
+ const extension = element.extensionElements.find((candidate) => candidate.name === extensionName);
363
+ if (!extension)
364
+ return;
365
+ delete extension.attributes[attribute];
366
+ if (Object.keys(extension.attributes).length === 0 && extension.children.length === 0) {
367
+ element.extensionElements.splice(element.extensionElements.indexOf(extension), 1);
368
+ }
369
+ }
131
370
  /** Replaces the `zeebe:taskHeaders` children, which are a map and move together. */
132
371
  function setTaskHeaders(element, headers) {
133
372
  const extension = ensureExtension(element, "zeebe:taskHeaders");
@@ -137,6 +376,57 @@ function setTaskHeaders(element, headers) {
137
376
  children: [],
138
377
  }));
139
378
  }
379
+ /** Replaces the listener container wholesale, like headers; an empty list removes it. */
380
+ function setListeners(element, extensionName, listeners) {
381
+ if (listeners.length > 0)
382
+ assertZeebePlacement(bpmnElementName(element), extensionName);
383
+ element.extensionElements = element.extensionElements.filter((e) => e.name !== extensionName);
384
+ if (listeners.length === 0)
385
+ return;
386
+ const [rebuilt] = zeebeExtensionsToXmlElements(extensionName === "zeebe:executionListeners"
387
+ ? { executionListeners: listeners }
388
+ : { taskListeners: listeners });
389
+ if (rebuilt)
390
+ element.extensionElements.push(rebuilt);
391
+ }
392
+ /** Replaces the `zeebe:properties` children, which, like headers, are a map. */
393
+ function setProperties(element, properties) {
394
+ if (Object.keys(properties).length === 0) {
395
+ element.extensionElements = element.extensionElements.filter((e) => e.name !== "zeebe:properties");
396
+ return;
397
+ }
398
+ const extension = ensureExtension(element, "zeebe:properties");
399
+ extension.children = Object.entries(properties).map(([name, value]) => ({
400
+ name: "zeebe:property",
401
+ attributes: { name, value },
402
+ children: [],
403
+ }));
404
+ }
405
+ /**
406
+ * The `zeebe:subscription` that holds this element's correlation key, created
407
+ * if missing. An element still carrying its own subscription keeps it there;
408
+ * otherwise it belongs on the referenced `bpmn:message`, where Camunda reads it.
409
+ */
410
+ function subscriptionFor(definitions, element) {
411
+ const own = element.extensionElements.find((e) => e.name === "zeebe:subscription");
412
+ if (own)
413
+ return own;
414
+ const ref = "messageRef" in element && typeof element.messageRef === "string"
415
+ ? element.messageRef
416
+ : "eventDefinitions" in element
417
+ ? element.eventDefinitions.find((d) => d.type === "message")?.messageRef
418
+ : undefined;
419
+ const message = ref === undefined ? undefined : definitions.messages.find((m) => m.id === ref);
420
+ if (!message)
421
+ return undefined;
422
+ message.extensionElements ??= [];
423
+ const existing = message.extensionElements.find((e) => e.name === "zeebe:subscription");
424
+ if (existing)
425
+ return existing;
426
+ const created = { name: "zeebe:subscription", attributes: {}, children: [] };
427
+ message.extensionElements.push(created);
428
+ return created;
429
+ }
140
430
  /** Sets the named mappings of one kind, keeping the others of the `zeebe:ioMapping`. */
141
431
  function setMappings(element, kind, mappings) {
142
432
  const ioMapping = ensureExtension(element, "zeebe:ioMapping");
@@ -185,13 +475,26 @@ function setResultVariable(element, resultVariable) {
185
475
  * attribute rather than one extension element, so everything the compact form
186
476
  * does not model stays exactly as it was.
187
477
  */
188
- function patchElement(element, patch) {
478
+ function patchElement(definitions, element, patch) {
189
479
  if (patch.type !== undefined && patch.type !== element.type) {
190
480
  return `changing type (${element.type} → ${patch.type}) needs a delete and an insert, so that what the new element should carry is explicit`;
191
481
  }
192
482
  const misplaced = misplacedExtensions(element, patch);
193
483
  if (misplaced !== undefined)
194
484
  return misplaced;
485
+ const misplacedEvent = misplacedEventFields(definitions, element, patch);
486
+ if (misplacedEvent !== undefined)
487
+ return misplacedEvent;
488
+ // Resolved before anything is written, so a failure leaves the element as it was.
489
+ let subscription;
490
+ // With messageName in the same patch the message may not exist yet; it is
491
+ // looked up again once messageName has created it.
492
+ if (patch.correlationKey !== undefined && patch.messageName === undefined) {
493
+ subscription = subscriptionFor(definitions, element);
494
+ if (!subscription) {
495
+ return "correlationKey needs a message, and this element references no message";
496
+ }
497
+ }
195
498
  if (patch.name !== undefined)
196
499
  element.name = patch.name;
197
500
  if (patch.documentation !== undefined)
@@ -230,11 +533,43 @@ function patchElement(element, patch) {
230
533
  ensureExtension(element, "zeebe:userTask");
231
534
  if (patch.taskHeaders !== undefined)
232
535
  setTaskHeaders(element, patch.taskHeaders);
536
+ for (const key of ["assignee", "candidateGroups", "candidateUsers"]) {
537
+ const value = patch[key];
538
+ if (value !== undefined) {
539
+ setOrClearAttribute(element, "zeebe:assignmentDefinition", key, value);
540
+ }
541
+ }
542
+ for (const key of ["dueDate", "followUpDate"]) {
543
+ const value = patch[key];
544
+ if (value !== undefined)
545
+ setOrClearAttribute(element, "zeebe:taskSchedule", key, value);
546
+ }
547
+ if (patch.priority !== undefined) {
548
+ setOrClearAttribute(element, "zeebe:priorityDefinition", "priority", String(patch.priority));
549
+ }
550
+ if (patch.properties !== undefined)
551
+ setProperties(element, patch.properties);
552
+ if (patch.executionListeners !== undefined) {
553
+ setListeners(element, "zeebe:executionListeners", patch.executionListeners);
554
+ }
555
+ if (patch.taskListeners !== undefined) {
556
+ setListeners(element, "zeebe:taskListeners", patch.taskListeners);
557
+ }
558
+ applyEventFields(definitions, element, patch);
559
+ if (patch.multiInstance !== undefined)
560
+ applyMultiInstance(element, patch.multiInstance);
561
+ if (patch.correlationKey !== undefined && patch.messageName !== undefined) {
562
+ subscription = subscriptionFor(definitions, element);
563
+ }
564
+ if (subscription && patch.correlationKey !== undefined) {
565
+ subscription.attributes.correlationKey = patch.correlationKey;
566
+ }
233
567
  if (patch.eventType !== undefined && "eventDefinitions" in element) {
234
568
  const current = element.eventDefinitions[0]?.type;
235
569
  if (current !== patch.eventType) {
236
570
  const replacement = makeEventDef(patch.eventType);
237
571
  element.eventDefinitions = replacement ? [replacement] : [];
572
+ assignEventDefinitionIds(element.id, element.eventDefinitions);
238
573
  }
239
574
  }
240
575
  return undefined;
@@ -288,7 +623,7 @@ function applyOne(definitions, operation) {
288
623
  const found = findElement(definitions, operation.id);
289
624
  if (!found)
290
625
  return `no element with id "${operation.id}"`;
291
- return patchElement(found.element, operation.patch);
626
+ return patchElement(definitions, found.element, operation.patch);
292
627
  }
293
628
  case "delete": {
294
629
  const found = findElement(definitions, operation.id);
@@ -23,6 +23,8 @@ export declare const SAMPLE_BPMN_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\"
23
23
  *
24
24
  * const xml2 = Bpmn.export(defs2)
25
25
  * ```
26
+ *
27
+ * @see node_modules/@bpmnkit/core/agent-cards/bpmn.md — runnable script and traps (~1k tokens)
26
28
  */
27
29
  export declare const Bpmn: {
28
30
  /**
@@ -66,6 +66,8 @@ export const SAMPLE_BPMN_XML = `<?xml version="1.0" encoding="UTF-8"?>
66
66
  *
67
67
  * const xml2 = Bpmn.export(defs2)
68
68
  * ```
69
+ *
70
+ * @see node_modules/@bpmnkit/core/agent-cards/bpmn.md — runnable script and traps (~1k tokens)
69
71
  */
70
72
  export const Bpmn = {
71
73
  /**
@@ -1,4 +1,45 @@
1
1
  import type { CompactDiagram, CompactElement } from "./compact.js";
2
+ import type { ZeebeListener } from "./zeebe-extensions.js";
3
+ /**
4
+ * The fields an `update` operation may set: any {@link CompactElement} field,
5
+ * plus the ones that live outside the element itself.
6
+ */
7
+ export type ElementPatch = Partial<Omit<CompactElement, "multiInstance">> & {
8
+ /**
9
+ * Changes only the named parts of the element's multi-instance loop; an empty
10
+ * string clears one, and an empty `collection` removes the loop. Adding a loop
11
+ * needs a `collection`. Only {@link applyBpmnOperations} applies it.
12
+ */
13
+ multiInstance?: Partial<NonNullable<CompactElement["multiInstance"]>>;
14
+ /**
15
+ * Names the `bpmn:message` / sets the error, escalation or signal the element's
16
+ * event definition references: they are written on that root element, created
17
+ * if the reference is missing. A root shared by several elements is reported
18
+ * rather than changed for all of them. `""` clears. Only
19
+ * {@link applyBpmnOperations} applies these.
20
+ */
21
+ messageName?: string;
22
+ errorCode?: string;
23
+ escalationCode?: string;
24
+ signalName?: string;
25
+ /** A timer's date (`timeDate`) and cycle (`timeCycle`); `timerDuration` is the duration. */
26
+ timerDate?: string;
27
+ timerCycle?: string;
28
+ /**
29
+ * The message correlation key (`zeebe:subscription`). It is written onto the
30
+ * `bpmn:message` the element references, where Camunda reads it, so every
31
+ * element sharing that message gets it. Only {@link applyBpmnOperations}
32
+ * applies it: the compact form has no messages to hold it.
33
+ */
34
+ correlationKey?: string;
35
+ /**
36
+ * Replaces the element's `zeebe:executionListeners`; `[]` removes them. Only
37
+ * {@link applyBpmnOperations} applies it: the compact form carries no listeners.
38
+ */
39
+ executionListeners?: ZeebeListener[];
40
+ /** Replaces a user task's `zeebe:taskListeners`; `[]` removes them. Same scope as above. */
41
+ taskListeners?: ZeebeListener[];
42
+ };
2
43
  /**
3
44
  * An atomic edit operation on a {@link CompactDiagram}.
4
45
  * All element/flow references use stable string IDs, not array positions.
@@ -17,7 +58,7 @@ export type BpmnOperation =
17
58
  | {
18
59
  op: "update";
19
60
  id: string;
20
- patch: Partial<CompactElement>;
61
+ patch: ElementPatch;
21
62
  }
22
63
  /** Remove an element by ID. */
23
64
  | {
@@ -67,8 +67,18 @@ function applyOne(diagram, op) {
67
67
  }
68
68
  case "update": {
69
69
  const found = findElementIn(process, op.id);
70
- if (found)
71
- Object.assign(found.element, op.patch);
70
+ if (found) {
71
+ // Root-element fields have no home in the compact form.
72
+ const { correlationKey: _messageLevel, messageName: _m, errorCode: _e, escalationCode: _x, signalName: _s, timerDate: _d, timerCycle: _c, multiInstance, ...patch } = op.patch;
73
+ Object.assign(found.element, patch);
74
+ if (multiInstance?.collection === "")
75
+ found.element.multiInstance = undefined;
76
+ else if (multiInstance) {
77
+ const merged = { ...found.element.multiInstance, ...multiInstance };
78
+ if (merged.collection)
79
+ found.element.multiInstance = { ...merged, collection: merged.collection };
80
+ }
81
+ }
72
82
  break;
73
83
  }
74
84
  case "delete": {
@@ -35,6 +35,20 @@ messages = []) {
35
35
  });
36
36
  }
37
37
  for (const el of p.flowElements) {
38
+ if ("eventDefinitions" in el) {
39
+ const missingId = el.eventDefinitions.filter((d) => !d.id);
40
+ if (missingId.length > 0) {
41
+ findings.push({
42
+ id: "deploy/event-definition-no-id",
43
+ category: "deploy",
44
+ severity: "error",
45
+ message: `"${el.name ?? el.id}" has ${missingId.length} event definition(s) without an id.`,
46
+ suggestion: "Give every event definition an id (e.g. <ElementId>_TimerEventDefinition) — Zeebe rejects a definition without one.",
47
+ processId,
48
+ elementIds: [el.id],
49
+ });
50
+ }
51
+ }
38
52
  if (el.type === "serviceTask" || el.type === "sendTask") {
39
53
  const type = readZeebeTaskType(el.extensionElements);
40
54
  if (!type) {
@@ -1,5 +1,7 @@
1
1
  import type { BpmnDefinitions } from "../bpmn-model.js";
2
2
  import type { OptimizationReport, OptimizeOptions } from "./types.js";
3
+ /** The finding a user task with no form raises; see `OptimizeOptions.userTaskForms`. */
4
+ export declare const USER_TASK_FORM_RULE = "compat/user-task-definition";
3
5
  /** Run static analysis on a BPMN definitions object. */
4
6
  export declare function optimize(defs: BpmnDefinitions, options?: OptimizeOptions): OptimizationReport;
5
7
  //# sourceMappingURL=index.d.ts.map
@@ -8,6 +8,8 @@ import { analyzeNaming } from "./naming.js";
8
8
  import { analyzePatterns } from "./patterns.js";
9
9
  import { analyzeTasks } from "./tasks.js";
10
10
  import { analyzeVariableFlow } from "./variable-flow.js";
11
+ /** The finding a user task with no form raises; see `OptimizeOptions.userTaskForms`. */
12
+ export const USER_TASK_FORM_RULE = "compat/user-task-definition";
11
13
  const ALL_CATEGORIES = [
12
14
  "feel",
13
15
  "feel-syntax",
@@ -74,6 +76,9 @@ export function optimize(defs, options) {
74
76
  if (resolved.categories.includes("deploy") || options?.camundaVersion !== undefined) {
75
77
  findings.push(...analyzeCamundaCompat(defs, resolved.camundaVersion));
76
78
  findings = dedupeCamundaCompat(findings);
79
+ if (options?.userTaskForms === "off") {
80
+ findings = findings.filter((f) => f.id !== USER_TASK_FORM_RULE);
81
+ }
77
82
  }
78
83
  const byCategory = Object.fromEntries(ALL_CATEGORIES.map((c) => [c, findings.filter((f) => f.category === c).length]));
79
84
  const bySeverity = Object.fromEntries(["info", "warning", "error"].map((s) => [
@@ -57,6 +57,13 @@ export interface OptimizeOptions {
57
57
  * `compat` reports nothing.
58
58
  */
59
59
  camundaVersion?: string;
60
+ /**
61
+ * Whether a user task with no `zeebe:formDefinition` is reported
62
+ * (`compat/user-task-definition`). Default `"require"`. Zeebe deploys such a
63
+ * task fine; `"off"` suits a sketch or a gate that should not push an author
64
+ * to invent a form reference.
65
+ */
66
+ userTaskForms?: "require" | "off";
60
67
  }
61
68
  export interface ResolvedOptions {
62
69
  feelLengthThreshold: number;
@@ -38,4 +38,19 @@ export declare function assignStableFlowIds(elements: BpmnFlowElement[], flows:
38
38
  export declare function rootDefinitionId(prefix: string, source: string, existing: ReadonlyArray<{
39
39
  id: string;
40
40
  }>): string;
41
+ /**
42
+ * Id for an event definition that carries none. Zeebe rejects a definition
43
+ * without an `id` at deploy time, so one is derived from the owning event
44
+ * (`Start_TimerEventDefinition`), with a counter when an event holds several
45
+ * of one kind. Ids already present on sibling definitions are never reused.
46
+ */
47
+ export declare function eventDefinitionId(ownerId: string, defs: readonly {
48
+ id?: string;
49
+ type: string;
50
+ }[], index: number): string;
51
+ /** Gives every id-less definition of `defs` a derived id; see `eventDefinitionId`. */
52
+ export declare function assignEventDefinitionIds(ownerId: string, defs: {
53
+ id?: string;
54
+ type: string;
55
+ }[]): void;
41
56
  //# sourceMappingURL=stable-ids.d.ts.map
@@ -197,4 +197,30 @@ export function rootDefinitionId(prefix, source, existing) {
197
197
  const taken = new Set(existing.map((definition) => definition.id));
198
198
  return uniqueId(capLength(`${prefix}_${ncName(slugify(source))}`), taken);
199
199
  }
200
+ /**
201
+ * Id for an event definition that carries none. Zeebe rejects a definition
202
+ * without an `id` at deploy time, so one is derived from the owning event
203
+ * (`Start_TimerEventDefinition`), with a counter when an event holds several
204
+ * of one kind. Ids already present on sibling definitions are never reused.
205
+ */
206
+ export function eventDefinitionId(ownerId, defs, index) {
207
+ const def = defs[index];
208
+ if (def === undefined)
209
+ return `${ncName(ownerId)}_EventDefinition`;
210
+ const kind = def.type.charAt(0).toUpperCase() + def.type.slice(1);
211
+ const base = `${ncName(ownerId)}_${kind}EventDefinition`;
212
+ const taken = new Set(defs.map((d) => d.id).filter((id) => id !== undefined));
213
+ const sameKind = defs.slice(0, index + 1).filter((d) => d.type === def.type).length;
214
+ let candidate = sameKind > 1 ? `${base}_${sameKind}` : base;
215
+ for (let n = sameKind + 1; taken.has(candidate); n++)
216
+ candidate = `${base}_${n}`;
217
+ return candidate;
218
+ }
219
+ /** Gives every id-less definition of `defs` a derived id; see `eventDefinitionId`. */
220
+ export function assignEventDefinitionIds(ownerId, defs) {
221
+ defs.forEach((d, i) => {
222
+ if (d.id === undefined)
223
+ d.id = eventDefinitionId(ownerId, defs, i);
224
+ });
225
+ }
200
226
  //# sourceMappingURL=stable-ids.js.map
@@ -0,0 +1,22 @@
1
+ import type { BpmnDefinitions } from "./bpmn-model.js";
2
+ /** One Camunda 8 vendor bit removed by {@link stripCamunda8}. */
3
+ export interface DroppedCamunda8Item {
4
+ /** Id of the owning element (`"definitions"` when it has none). */
5
+ elementId: string;
6
+ kind: "extensionElement" | "attribute" | "namespace";
7
+ /** Qualified name, e.g. `zeebe:taskDefinition`, `modeler:executionPlatform`, `xmlns:zeebe`. */
8
+ name: string;
9
+ }
10
+ export interface StripCamunda8Result {
11
+ definitions: BpmnDefinitions;
12
+ dropped: DroppedCamunda8Item[];
13
+ }
14
+ /**
15
+ * Returns a copy of `definitions` without Camunda 8 vendor content (`zeebe:*`
16
+ * extension elements and attributes, `modeler:*` attributes) so the export is
17
+ * plain BPMN, e.g. as a base for Camunda 7/Operaton. Opt-in and non-mutating;
18
+ * `camunda:*` and other vendors are left alone. Their `xmlns` declarations go
19
+ * too, unless some remaining content still uses the prefix.
20
+ */
21
+ export declare function stripCamunda8(definitions: BpmnDefinitions): StripCamunda8Result;
22
+ //# sourceMappingURL=strip-camunda8.d.ts.map