@bpmnkit/core 1.7.0 → 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 (50) 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/dist/bpmn/auto-layout.js +2 -1
  7. package/dist/bpmn/bpmn-builder.d.ts +2 -2
  8. package/dist/bpmn/bpmn-builder.js +17 -6
  9. package/dist/bpmn/camunda7/migrate.d.ts +1 -1
  10. package/dist/bpmn/camunda7/migrate.js +1 -1
  11. package/dist/bpmn/compact.js +3 -0
  12. package/dist/bpmn/full-operations.js +2 -0
  13. package/dist/bpmn/index.d.ts +2 -0
  14. package/dist/bpmn/index.js +2 -0
  15. package/dist/bpmn/optimize/deploy.js +14 -0
  16. package/dist/bpmn/optimize/index.d.ts +2 -0
  17. package/dist/bpmn/optimize/index.js +5 -0
  18. package/dist/bpmn/optimize/types.d.ts +7 -0
  19. package/dist/bpmn/stable-ids.d.ts +15 -0
  20. package/dist/bpmn/stable-ids.js +26 -0
  21. package/dist/bpmn/svg.js +5 -6
  22. package/dist/check-finding.d.ts +19 -0
  23. package/dist/check-finding.js +5 -0
  24. package/dist/dmn/compact.js +14 -5
  25. package/dist/dmn/dmn-builder.js +3 -3
  26. package/dist/dmn/drd-builder.d.ts +53 -0
  27. package/dist/dmn/drd-builder.js +100 -0
  28. package/dist/dmn/index.d.ts +35 -0
  29. package/dist/dmn/index.js +36 -0
  30. package/dist/dmn/lint.d.ts +19 -0
  31. package/dist/dmn/lint.js +414 -0
  32. package/dist/form/form-builder.d.ts +9 -1
  33. package/dist/form/form-builder.js +34 -1
  34. package/dist/form/form-model.d.ts +7 -0
  35. package/dist/form/form-parser.js +22 -0
  36. package/dist/form/form-serializer.js +10 -0
  37. package/dist/form/index.d.ts +11 -2
  38. package/dist/form/index.js +10 -1
  39. package/dist/form/lint.d.ts +19 -0
  40. package/dist/form/lint.js +356 -0
  41. package/dist/index.d.ts +13 -3
  42. package/dist/index.js +10 -2
  43. package/dist/layout/grid/edge-labels.d.ts +7 -1
  44. package/dist/layout/grid/edge-labels.js +62 -1
  45. package/dist/layout/semantic/index.js +78 -8
  46. package/dist/layout/semantic/place.d.ts +19 -4
  47. package/dist/layout/semantic/place.js +232 -34
  48. package/dist/layout/semantic/route.js +47 -14
  49. package/llms.txt +9 -0
  50. package/package.json +5 -1
@@ -0,0 +1,19 @@
1
+ /** Appends the pointer to a card's trap list, so a fix loop learns where the rule is explained. */
2
+ export declare function withCardHint(findings: CheckFinding[], card: "bpmn" | "dmn" | "form"): CheckFinding[];
3
+ /** How bad a {@link CheckFinding} is. `error` means the resource will not deploy or run as written. */
4
+ export type CheckSeverity = "error" | "warning" | "info";
5
+ /**
6
+ * One problem in a DMN or form resource, shaped for an agent's fix loop:
7
+ * which rule fired, where, what is wrong and what to change.
8
+ */
9
+ export interface CheckFinding {
10
+ /** Stable rule id, e.g. `dmn/unresolved-requirement` or `form/duplicate-key`. */
11
+ rule: string;
12
+ severity: CheckSeverity;
13
+ /** The element (DMN) or component (form) the finding is about, when there is one. */
14
+ elementId?: string;
15
+ message: string;
16
+ /** A concrete change that resolves the finding. */
17
+ fix: string;
18
+ }
19
+ //# sourceMappingURL=check-finding.d.ts.map
@@ -0,0 +1,5 @@
1
+ /** Appends the pointer to a card's trap list, so a fix loop learns where the rule is explained. */
2
+ export function withCardHint(findings, card) {
3
+ return findings.map((f) => ({ ...f, fix: `${f.fix} (agent-cards/${card}.md#traps)` }));
4
+ }
5
+ //# sourceMappingURL=check-finding.js.map
@@ -1,3 +1,4 @@
1
+ import { ValidationError } from "../errors.js";
1
2
  import { generateId } from "../types/id-generator.js";
2
3
  import { layoutDmn } from "./dmn-layout.js";
3
4
  // ── Compactify ────────────────────────────────────────────────────────────────
@@ -50,11 +51,19 @@ export function expandDmn(compact) {
50
51
  const inputData = compact.inputData.map((d) => ({ id: d.id, name: d.name }));
51
52
  const decisions = compact.decisions.map((cd) => {
52
53
  // Build requirement links
53
- const informationRequirements = (cd.requires ?? []).map((srcId) => ({
54
- id: generateId("InformationRequirement"),
55
- requiredDecision: compact.decisions.some((d) => d.id === srcId) ? srcId : undefined,
56
- requiredInput: compact.inputData.some((d) => d.id === srcId) ? srcId : undefined,
57
- }));
54
+ const informationRequirements = (cd.requires ?? []).map((srcId) => {
55
+ const isDecision = compact.decisions.some((d) => d.id === srcId);
56
+ const isInput = compact.inputData.some((d) => d.id === srcId);
57
+ if (!isDecision && !isInput) {
58
+ const valid = [...compact.decisions, ...compact.inputData].map((d) => d.id).join(", ");
59
+ throw new ValidationError(`Decision "${cd.id}" requires unknown id "${srcId}". Valid ids: ${valid || "(none)"}. Use ids, not names. See agent-cards/dmn.md#traps.`);
60
+ }
61
+ return {
62
+ id: generateId("InformationRequirement"),
63
+ requiredDecision: isDecision ? srcId : undefined,
64
+ requiredInput: isInput ? srcId : undefined,
65
+ };
66
+ });
58
67
  // Build decision table
59
68
  let decisionTable;
60
69
  if (cd.inputs.length > 0 || cd.outputs.length > 0 || cd.rules.length > 0) {
@@ -64,10 +64,10 @@ export class DecisionTableBuilder {
64
64
  */
65
65
  rule(options) {
66
66
  if (options.inputs.length !== this.inputColumns.length) {
67
- throw new ValidationError(`Rule has ${options.inputs.length} inputs but table has ${this.inputColumns.length} input columns`);
67
+ throw new ValidationError(`Rule has ${options.inputs.length} inputs but table has ${this.inputColumns.length} input columns. See agent-cards/dmn.md#traps.`);
68
68
  }
69
69
  if (options.outputs.length !== this.outputColumns.length) {
70
- throw new ValidationError(`Rule has ${options.outputs.length} outputs but table has ${this.outputColumns.length} output columns`);
70
+ throw new ValidationError(`Rule has ${options.outputs.length} outputs but table has ${this.outputColumns.length} output columns. See agent-cards/dmn.md#traps.`);
71
71
  }
72
72
  const inputEntries = options.inputs.map((text) => ({
73
73
  id: generateId("UnaryTests"),
@@ -125,7 +125,7 @@ export class DecisionTableBuilder {
125
125
  },
126
126
  modelerAttributes: {
127
127
  executionPlatform: "Camunda Cloud",
128
- executionPlatformVersion: "8.5.0",
128
+ executionPlatformVersion: "8.10.0",
129
129
  },
130
130
  decisions: [decision],
131
131
  inputData: [],
@@ -0,0 +1,53 @@
1
+ import { DecisionTableBuilder } from "./dmn-builder.js";
2
+ import type { DmnDefinitions } from "./dmn-model.js";
3
+ declare const drgIdBrand: unique symbol;
4
+ /** Id of a decision or input data element in a DRD. Get one from a handle or `drgId()`. */
5
+ export type DrgId = string & {
6
+ readonly [drgIdBrand]: true;
7
+ };
8
+ /** Returned by `DrdBuilder.decision()`; pass it to `requires` of a later decision. */
9
+ export interface DecisionHandle {
10
+ readonly kind: "decision";
11
+ readonly id: DrgId;
12
+ readonly name: string;
13
+ }
14
+ /** Returned by `DrdBuilder.inputData()`. */
15
+ export interface InputDataHandle {
16
+ readonly kind: "inputData";
17
+ readonly id: DrgId;
18
+ readonly name: string;
19
+ }
20
+ /** Something a decision can require: a handle or a branded id. */
21
+ export type DrgRef = DecisionHandle | InputDataHandle | DrgId;
22
+ /** Brand a literal id string. Validated against the DRD at `build()`. */
23
+ export declare function drgId(id: string): DrgId;
24
+ export interface DrdDecisionOptions {
25
+ /** Decisions or input data this decision depends on (never labels). */
26
+ requires?: DrgRef[];
27
+ }
28
+ /** Fluent builder for multi-decision DRDs with information requirements. */
29
+ export declare class DrdBuilder {
30
+ private readonly decisions;
31
+ private readonly inputs;
32
+ private readonly drdName;
33
+ constructor(name?: string);
34
+ private assertFreeId;
35
+ /** Add an input data element. */
36
+ inputData(id: string, name?: string): InputDataHandle;
37
+ /**
38
+ * Add a decision. `table` configures its decision table (use `.name()` for the label).
39
+ * Returns a handle to pass in `requires` of decisions added later.
40
+ */
41
+ decision(id: string, table: (t: DecisionTableBuilder) => DecisionTableBuilder, options?: DrdDecisionOptions): DecisionHandle;
42
+ private resolve;
43
+ /**
44
+ * Build the DMN definitions with information requirements and DMNDI layout.
45
+ *
46
+ * @throws {ValidationError} If a `requires` entry is not the id of a decision or input data.
47
+ */
48
+ build(): DmnDefinitions;
49
+ /** Build and export as DMN XML string. */
50
+ toXml(): string;
51
+ }
52
+ export {};
53
+ //# sourceMappingURL=drd-builder.d.ts.map
@@ -0,0 +1,100 @@
1
+ import { ValidationError } from "../errors.js";
2
+ import { generateId } from "../types/id-generator.js";
3
+ import { DecisionTableBuilder } from "./dmn-builder.js";
4
+ import { layoutDmn } from "./dmn-layout.js";
5
+ import { serializeDmn } from "./dmn-serializer.js";
6
+ /** Brand a literal id string. Validated against the DRD at `build()`. */
7
+ export function drgId(id) {
8
+ return id;
9
+ }
10
+ /** Fluent builder for multi-decision DRDs with information requirements. */
11
+ export class DrdBuilder {
12
+ decisions = [];
13
+ inputs = [];
14
+ drdName;
15
+ constructor(name = "DRD") {
16
+ this.drdName = name;
17
+ }
18
+ assertFreeId(id) {
19
+ const taken = [...this.decisions.map((d) => d.decision.id), ...this.inputs.map((i) => i.id)];
20
+ if (taken.includes(id))
21
+ throw new ValidationError(`Duplicate DRD element id "${id}"`);
22
+ }
23
+ /** Add an input data element. */
24
+ inputData(id, name = id) {
25
+ this.assertFreeId(id);
26
+ this.inputs.push({ id, name });
27
+ return { kind: "inputData", id: id, name };
28
+ }
29
+ /**
30
+ * Add a decision. `table` configures its decision table (use `.name()` for the label).
31
+ * Returns a handle to pass in `requires` of decisions added later.
32
+ */
33
+ decision(id, table, options = {}) {
34
+ this.assertFreeId(id);
35
+ const built = table(new DecisionTableBuilder(id)).build().decisions[0];
36
+ if (!built)
37
+ throw new ValidationError(`Decision "${id}" produced no decision`);
38
+ this.decisions.push({ decision: built, requires: options.requires ?? [] });
39
+ return { kind: "decision", id: id, name: built.name ?? id };
40
+ }
41
+ resolve(owner, ref) {
42
+ const id = typeof ref === "string" ? ref : ref.id;
43
+ const decisionIds = this.decisions.map((d) => d.decision.id);
44
+ const known = [...decisionIds, ...this.inputs.map((i) => i.id)];
45
+ if (known.includes(id))
46
+ return id;
47
+ const byName = this.decisions.find((d) => d.decision.name === id)?.decision.id ??
48
+ this.inputs.find((i) => i.name === id)?.id;
49
+ const hint = byName
50
+ ? ` "${id}" is a name/label, not an id. Use the id "${byName}" (pass the handle returned by decision()).`
51
+ : "";
52
+ throw new ValidationError(`Decision "${owner}" requires unknown id "${id}". Valid ids: ${known.join(", ") || "(none)"}.${hint} See agent-cards/dmn.md#traps.`);
53
+ }
54
+ /**
55
+ * Build the DMN definitions with information requirements and DMNDI layout.
56
+ *
57
+ * @throws {ValidationError} If a `requires` entry is not the id of a decision or input data.
58
+ */
59
+ build() {
60
+ const decisions = this.decisions.map(({ decision, requires }) => ({
61
+ ...decision,
62
+ informationRequirements: requires.map((ref) => {
63
+ const target = this.resolve(decision.id, ref);
64
+ const isDecision = this.decisions.some((d) => d.decision.id === target);
65
+ return {
66
+ id: generateId("InformationRequirement"),
67
+ ...(isDecision ? { requiredDecision: target } : { requiredInput: target }),
68
+ };
69
+ }),
70
+ }));
71
+ return layoutDmn({
72
+ id: generateId("Definitions"),
73
+ name: this.drdName,
74
+ namespace: "http://camunda.org/schema/1.0/dmn",
75
+ exporter: "bpmn-sdk",
76
+ exporterVersion: "0.0.1",
77
+ namespaces: {
78
+ "": "https://www.omg.org/spec/DMN/20191111/MODEL/",
79
+ dmndi: "https://www.omg.org/spec/DMN/20191111/DMNDI/",
80
+ dc: "http://www.omg.org/spec/DMN/20180521/DC/",
81
+ modeler: "http://camunda.org/schema/modeler/1.0",
82
+ },
83
+ modelerAttributes: {
84
+ executionPlatform: "Camunda Cloud",
85
+ executionPlatformVersion: "8.10.0",
86
+ },
87
+ decisions,
88
+ inputData: this.inputs,
89
+ knowledgeSources: [],
90
+ businessKnowledgeModels: [],
91
+ textAnnotations: [],
92
+ associations: [],
93
+ });
94
+ }
95
+ /** Build and export as DMN XML string. */
96
+ toXml() {
97
+ return serializeDmn(this.build());
98
+ }
99
+ }
100
+ //# sourceMappingURL=drd-builder.js.map
@@ -1,14 +1,49 @@
1
1
  import { compactifyDmn, expandDmn } from "./compact.js";
2
2
  import { DecisionTableBuilder } from "./dmn-builder.js";
3
3
  import type { DmnDefinitions } from "./dmn-model.js";
4
+ import { DrdBuilder } from "./drd-builder.js";
4
5
  export { layoutDmn, benchmarkDmnLayout } from "./dmn-layout.js";
5
6
  export type { DmnBenchmarkResult, DmnElementPosition } from "./dmn-layout.js";
7
+ export { drgId } from "./drd-builder.js";
8
+ export type { DecisionHandle, DrdBuilder, DrdDecisionOptions, DrgId, DrgRef, InputDataHandle, } from "./drd-builder.js";
6
9
  export { compactifyDmn, expandDmn } from "./compact.js";
7
10
  export type { CompactDmn, CompactDmnDecision, CompactDmnInput, CompactDmnOutput, CompactDmnRule, } from "./compact.js";
8
11
  /** Entry point for DMN decision table operations. */
12
+ /**
13
+ * Top-level DMN namespace: build, parse and export decision tables and DRDs.
14
+ *
15
+ * @example
16
+ * ```typescript
17
+ * const defs = Dmn.createDecisionTable("risk")
18
+ * .input({ label: "Score", expression: "score", typeRef: "number" })
19
+ * .output({ label: "Level", name: "level", typeRef: "string" })
20
+ * .rule({ inputs: ["> 700"], outputs: ['"low"'] })
21
+ * .build()
22
+ * const xml = Dmn.export(defs)
23
+ * ```
24
+ *
25
+ * @see node_modules/@bpmnkit/core/agent-cards/dmn.md — runnable script and traps (~1k tokens)
26
+ */
9
27
  export declare const Dmn: {
10
28
  /** Create a new DMN decision table using the fluent builder API. */
11
29
  readonly createDecisionTable: (decisionId: string) => DecisionTableBuilder;
30
+ /**
31
+ * Create a multi-decision DRD. `decision()` returns a handle; pass it (or a
32
+ * `drgId()`) in `requires` of a later decision. Labels are rejected at build time.
33
+ *
34
+ * @example
35
+ * ```typescript
36
+ * const drd = Dmn.drd("Loan")
37
+ * const risk = drd.decision("risk", (t) => t.input({ expression: "score" }).output({ name: "level" }))
38
+ * drd.decision("offer", (t) => t.input({ expression: "level" }).output({ name: "rate" }), {
39
+ * requires: [risk], // the handle, not a name
40
+ * })
41
+ * const xml = drd.toXml()
42
+ * ```
43
+ *
44
+ * @see node_modules/@bpmnkit/core/agent-cards/dmn.md — the multi-decision DRD script
45
+ */
46
+ readonly drd: (name?: string) => DrdBuilder;
12
47
  /** Parse a DMN XML string into a typed model. */
13
48
  readonly parse: (xml: string) => DmnDefinitions;
14
49
  /** Export a typed DMN model to XML string. */
package/dist/dmn/index.js CHANGED
@@ -3,14 +3,50 @@ import { DecisionTableBuilder } from "./dmn-builder.js";
3
3
  import { layoutDmn } from "./dmn-layout.js";
4
4
  import { parseDmn } from "./dmn-parser.js";
5
5
  import { serializeDmn } from "./dmn-serializer.js";
6
+ import { DrdBuilder } from "./drd-builder.js";
6
7
  export { layoutDmn, benchmarkDmnLayout } from "./dmn-layout.js";
8
+ export { drgId } from "./drd-builder.js";
7
9
  export { compactifyDmn, expandDmn } from "./compact.js";
8
10
  /** Entry point for DMN decision table operations. */
11
+ /**
12
+ * Top-level DMN namespace: build, parse and export decision tables and DRDs.
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * const defs = Dmn.createDecisionTable("risk")
17
+ * .input({ label: "Score", expression: "score", typeRef: "number" })
18
+ * .output({ label: "Level", name: "level", typeRef: "string" })
19
+ * .rule({ inputs: ["> 700"], outputs: ['"low"'] })
20
+ * .build()
21
+ * const xml = Dmn.export(defs)
22
+ * ```
23
+ *
24
+ * @see node_modules/@bpmnkit/core/agent-cards/dmn.md — runnable script and traps (~1k tokens)
25
+ */
9
26
  export const Dmn = {
10
27
  /** Create a new DMN decision table using the fluent builder API. */
11
28
  createDecisionTable(decisionId) {
12
29
  return new DecisionTableBuilder(decisionId);
13
30
  },
31
+ /**
32
+ * Create a multi-decision DRD. `decision()` returns a handle; pass it (or a
33
+ * `drgId()`) in `requires` of a later decision. Labels are rejected at build time.
34
+ *
35
+ * @example
36
+ * ```typescript
37
+ * const drd = Dmn.drd("Loan")
38
+ * const risk = drd.decision("risk", (t) => t.input({ expression: "score" }).output({ name: "level" }))
39
+ * drd.decision("offer", (t) => t.input({ expression: "level" }).output({ name: "rate" }), {
40
+ * requires: [risk], // the handle, not a name
41
+ * })
42
+ * const xml = drd.toXml()
43
+ * ```
44
+ *
45
+ * @see node_modules/@bpmnkit/core/agent-cards/dmn.md — the multi-decision DRD script
46
+ */
47
+ drd(name) {
48
+ return new DrdBuilder(name);
49
+ },
14
50
  /** Parse a DMN XML string into a typed model. */
15
51
  parse(xml) {
16
52
  return parseDmn(xml);
@@ -0,0 +1,19 @@
1
+ import { type CheckFinding } from "../check-finding.js";
2
+ /**
3
+ * Checks a DMN document for the mistakes Zeebe either rejects at deploy time
4
+ * or reports with an error that hides the cause: malformed XML, duplicate ids,
5
+ * requirement references that resolve to nothing, FEEL that does not parse,
6
+ * invalid hit policies and unknown types.
7
+ *
8
+ * Reads the raw XML rather than the `Dmn` model so a document the model
9
+ * cannot represent is still reported on instead of thrown away.
10
+ *
11
+ * @param xml - The DMN document's text.
12
+ *
13
+ * @example
14
+ * ```typescript
15
+ * for (const f of lintDmn(xml)) console.log(`${f.rule} [${f.elementId}] ${f.message} — ${f.fix}`)
16
+ * ```
17
+ */
18
+ export declare function lintDmn(xml: string): CheckFinding[];
19
+ //# sourceMappingURL=lint.d.ts.map