@bpmnkit/core 1.8.0 → 1.9.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.
@@ -71,6 +71,8 @@ if (report.counts.error > 0) process.exit(1)
71
71
  - FEEL in the builder starts with `=` (`"=amount > 1000"`); a value without `=` is a literal string.
72
72
  - Unknown option names are silently dropped: `timer: { duration }` does nothing; use `timerDuration`.
73
73
 
74
+ - **Gate the export.** `Bpmn.export(defs, { validate: "error" })` lints first and throws on what a deploy would reject (`"warn"` logs; default off). `build()` already rejects invalid ids (NCName), non-boolean `cancelActivity`/`isInterrupting`/`isSequential` and non-numeric `retries`.
75
+
74
76
  ## Lint before you deploy or test
75
77
 
76
78
  ```sh
@@ -4,6 +4,7 @@ import { applyAutoLayout } from "./auto-layout.js";
4
4
  import { createFlowElement } from "./element-shape.js";
5
5
  import { REST_CONNECTOR_TEMPLATE_VERSION, restConnectorRetries, restConnectorTaskType, restConnectorToIoMappingInputs, restConnectorToTaskHeaders, } from "./rest-connector.js";
6
6
  import { assertExplicitFlowIdsUnique, assignEventDefinitionIds, assignStableFlowIds, markExplicitFlowId, rootDefinitionId, setFlowDiscriminatorSource, } from "./stable-ids.js";
7
+ import { assertRetriesOption, assertXsdValues } from "./xsd-guards.js";
7
8
  import { assertZeebePlacement, bpmnElementName, ensureZeebeExtension, makeConditionalDefinition, zeebeExtensionsToXmlElements, } from "./zeebe-extensions.js";
8
9
  // Keep in sync with packages/core/package.json version
9
10
  const EXPORTER_VERSION = "0.0.23";
@@ -349,6 +350,7 @@ function buildMappingExtensions(options) {
349
350
  return extensions;
350
351
  }
351
352
  function buildServiceTaskExtensions(options) {
353
+ assertRetriesOption(options.retries, options.taskType);
352
354
  const extensions = {
353
355
  taskDefinition: {
354
356
  type: options.taskType,
@@ -2747,6 +2749,14 @@ export class ProcessBuilder {
2747
2749
  }
2748
2750
  }
2749
2751
  validate() {
2752
+ // A parsed document keeps whatever ids it came with; only new builds are held to the XSD.
2753
+ if (this._source === undefined) {
2754
+ assertXsdValues({
2755
+ id: this.processId,
2756
+ flowElements: this.flowElements,
2757
+ sequenceFlows: this.sequenceFlows,
2758
+ });
2759
+ }
2750
2760
  const elementIds = new Set(this.flowElements.map((el) => el.id));
2751
2761
  for (const flow of this.sequenceFlows) {
2752
2762
  if (!elementIds.has(flow.targetRef)) {
@@ -26,6 +26,11 @@ export declare const SAMPLE_BPMN_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\"
26
26
  *
27
27
  * @see node_modules/@bpmnkit/core/agent-cards/bpmn.md — runnable script and traps (~1k tokens)
28
28
  */
29
+ /** Options for {@link Bpmn.export}. */
30
+ export interface ExportOptions {
31
+ /** Lint before writing: `"warn"` logs deploy errors, `"error"` throws; `false` (default) skips. */
32
+ validate?: "warn" | "error" | false;
33
+ }
29
34
  export declare const Bpmn: {
30
35
  /**
31
36
  * Create a new BPMN process using the fluent builder API.
@@ -100,6 +105,7 @@ export declare const Bpmn: {
100
105
  * Serialise a {@link BpmnDefinitions} model back to BPMN 2.0 XML.
101
106
  *
102
107
  * @param definitions - The typed BPMN model to export.
108
+ * @param options - `validate: "warn" | "error"` lints first and reports what a deploy would reject (default `false`: no lint).
103
109
  * @returns A BPMN 2.0 XML string.
104
110
  *
105
111
  * @example
@@ -108,7 +114,7 @@ export declare const Bpmn: {
108
114
  * fs.writeFileSync("diagram.bpmn", xml, "utf-8")
109
115
  * ```
110
116
  */
111
- readonly export: (definitions: BpmnDefinitions) => string;
117
+ readonly export: (definitions: BpmnDefinitions, options?: ExportOptions) => string;
112
118
  /**
113
119
  * Returns a minimal valid BPMN XML string containing one process with a
114
120
  * single start event. Useful for "New Diagram" / empty-canvas actions.
@@ -1,7 +1,9 @@
1
+ import { ValidationError } from "../errors.js";
1
2
  import { applyAutoLayout } from "./auto-layout.js";
2
3
  import { DiagramBuilder, ProcessBuilder } from "./bpmn-builder.js";
3
4
  import { parseBpmn } from "./bpmn-parser.js";
4
5
  import { serializeBpmn } from "./bpmn-serializer.js";
6
+ import { lintDiagram } from "./lint.js";
5
7
  /** A minimal 3-element BPMN diagram useful for first-launch or "New Diagram" defaults. */
6
8
  export const SAMPLE_BPMN_XML = `<?xml version="1.0" encoding="UTF-8"?>
7
9
  <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
@@ -45,30 +47,6 @@ export const SAMPLE_BPMN_XML = `<?xml version="1.0" encoding="UTF-8"?>
45
47
  </bpmndi:BPMNPlane>
46
48
  </bpmndi:BPMNDiagram>
47
49
  </bpmn:definitions>`;
48
- /**
49
- * Entry point for all BPMN operations — parsing, building, exporting, and
50
- * creating empty diagrams.
51
- *
52
- * @example
53
- * ```typescript
54
- * import { Bpmn } from "@bpmnkit/core"
55
- *
56
- * // Parse existing XML
57
- * const defs = Bpmn.parse(xml)
58
- *
59
- * // Build a new process
60
- * const defs2 = Bpmn.createProcess("order")
61
- * .startEvent("start")
62
- * .serviceTask("task", { name: "Process", taskType: "process" })
63
- * .endEvent("end")
64
- * .withAutoLayout()
65
- * .build()
66
- *
67
- * const xml2 = Bpmn.export(defs2)
68
- * ```
69
- *
70
- * @see node_modules/@bpmnkit/core/agent-cards/bpmn.md — runnable script and traps (~1k tokens)
71
- */
72
50
  export const Bpmn = {
73
51
  /**
74
52
  * Create a new BPMN process using the fluent builder API.
@@ -151,6 +129,7 @@ export const Bpmn = {
151
129
  * Serialise a {@link BpmnDefinitions} model back to BPMN 2.0 XML.
152
130
  *
153
131
  * @param definitions - The typed BPMN model to export.
132
+ * @param options - `validate: "warn" | "error"` lints first and reports what a deploy would reject (default `false`: no lint).
154
133
  * @returns A BPMN 2.0 XML string.
155
134
  *
156
135
  * @example
@@ -159,7 +138,21 @@ export const Bpmn = {
159
138
  * fs.writeFileSync("diagram.bpmn", xml, "utf-8")
160
139
  * ```
161
140
  */
162
- export(definitions) {
141
+ export(definitions, options = {}) {
142
+ const mode = options.validate ?? false;
143
+ if (mode !== false) {
144
+ // Only the errors a Camunda 8 deploy would reject; an engine-neutral model is not judged.
145
+ const errors = lintDiagram(definitions).diagnostics.filter((d) => d.severity === "error");
146
+ if (errors.length > 0) {
147
+ const text = errors
148
+ .map((d) => `${d.id} [${d.elementIds.join(", ")}]: ${d.message} Fix: ${d.suggestion}`)
149
+ .join("\n");
150
+ if (mode === "error") {
151
+ throw new ValidationError(`Bpmn.export: ${errors.length} deploy error(s):\n${text}`);
152
+ }
153
+ console.warn(`Bpmn.export: ${errors.length} deploy error(s):\n${text}`);
154
+ }
155
+ }
163
156
  return serializeBpmn(definitions);
164
157
  },
165
158
  /**
@@ -0,0 +1,8 @@
1
+ import type { BpmnProcess } from "./bpmn-model.js";
2
+ /** xsd:ID is an NCName: no spaces or colons, and it never starts with a digit. */
3
+ export declare function assertNcName(id: unknown, what: string): void;
4
+ /** @throws {ValidationError} On the first value the XSD would reject at deploy. */
5
+ export declare function assertXsdValues(process: BpmnProcess): void;
6
+ /** Checks `retries` as typed on the builder option, before it is serialised. */
7
+ export declare function assertRetriesOption(value: unknown, id: string): void;
8
+ //# sourceMappingURL=xsd-guards.d.ts.map
@@ -0,0 +1,56 @@
1
+ import { ValidationError } from "../errors.js";
2
+ /**
3
+ * Build-time checks for attributes the BPMN/Zeebe XSD types strictly.
4
+ *
5
+ * A script-supplied value outside the type serialises fine and is only
6
+ * rejected at deploy ("cvc-datatype-valid", "cvc-enumeration-valid") with the
7
+ * attribute name redacted, so these throw at the call site's `build()` with the
8
+ * allowed values instead.
9
+ */
10
+ const NCNAME = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
11
+ // Zeebe accepts a whole number or a FEEL expression ("=retryCount").
12
+ const RETRIES = /^(=.+|\d+)$/;
13
+ const HINT = " See agent-cards/bpmn.md#traps.";
14
+ /** xsd:ID is an NCName: no spaces or colons, and it never starts with a digit. */
15
+ export function assertNcName(id, what) {
16
+ if (typeof id !== "string" || !NCNAME.test(id)) {
17
+ throw new ValidationError(`${what} id ${JSON.stringify(id)} is not a valid XML id (xsd:ID). Allowed: letters, digits, "_", "-", "." — starting with a letter or "_", no spaces or ":". Example: "Task_ApproveOrder".${HINT}`);
18
+ }
19
+ }
20
+ function assertBoolean(value, attr, id) {
21
+ if (value !== undefined && typeof value !== "boolean") {
22
+ throw new ValidationError(`${attr} on "${id}" must be a boolean (true | false), got ${JSON.stringify(value)}.${HINT}`);
23
+ }
24
+ }
25
+ function assertRetries(value, id) {
26
+ if (value === undefined)
27
+ return;
28
+ if (typeof value !== "string" || !RETRIES.test(value)) {
29
+ throw new ValidationError(`retries on "${id}" must be a whole-number string like "3" or a FEEL expression like "=retries", got ${JSON.stringify(value)}.${HINT}`);
30
+ }
31
+ }
32
+ function checkElements(elements) {
33
+ for (const el of elements) {
34
+ assertNcName(el.id, "Element");
35
+ const loose = el;
36
+ assertBoolean(loose.cancelActivity, "cancelActivity", el.id);
37
+ assertBoolean(loose.isInterrupting, "isInterrupting", el.id);
38
+ const loop = loose.loopCharacteristics;
39
+ assertBoolean(loop?.isSequential, "multiInstance.isSequential", el.id);
40
+ if (Array.isArray(loose.flowElements)) {
41
+ checkElements(loose.flowElements);
42
+ }
43
+ }
44
+ }
45
+ /** @throws {ValidationError} On the first value the XSD would reject at deploy. */
46
+ export function assertXsdValues(process) {
47
+ assertNcName(process.id, "Process");
48
+ checkElements(process.flowElements);
49
+ for (const flow of process.sequenceFlows)
50
+ assertNcName(flow.id, "Sequence flow");
51
+ }
52
+ /** Checks `retries` as typed on the builder option, before it is serialised. */
53
+ export function assertRetriesOption(value, id) {
54
+ assertRetries(value, id);
55
+ }
56
+ //# sourceMappingURL=xsd-guards.js.map
package/dist/index.d.ts CHANGED
@@ -9,6 +9,7 @@ export type { ErrorCode } from "./errors.js";
9
9
  export { isBpmnActivity, isBpmnAdHocSubProcess, isBpmnBoundaryEvent, isBpmnBusinessRuleTask, isBpmnCallActivity, isBpmnComplexGateway, isBpmnDataObject, isBpmnDataObjectReference, isBpmnDataStoreReference, isBpmnEndEvent, isBpmnEvent, isBpmnEventBasedGateway, isBpmnEventSubProcess, isBpmnExclusiveGateway, isBpmnGateway, isBpmnInclusiveGateway, isBpmnIntermediateCatchEvent, isBpmnIntermediateThrowEvent, isBpmnManualTask, isBpmnParallelGateway, isBpmnReceiveTask, isBpmnScriptTask, isBpmnSendTask, isBpmnServiceTask, isBpmnStartEvent, isBpmnSubProcess, isBpmnTask, isBpmnTransaction, isBpmnUserTask, } from "./bpmn/type-guards.js";
10
10
  export { findElement, findElementInProcess, findProcess, findSequenceFlow, getAllElements, getElementType, getZeebeExtensions, } from "./bpmn/utils.js";
11
11
  export { Bpmn, SAMPLE_BPMN_XML } from "./bpmn/index.js";
12
+ export type { ExportOptions } from "./bpmn/index.js";
12
13
  export { stripCamunda8 } from "./bpmn/strip-camunda8.js";
13
14
  export type { DroppedCamunda8Item, StripCamunda8Result } from "./bpmn/strip-camunda8.js";
14
15
  export { applyAutoLayout } from "./bpmn/auto-layout.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",