@bpmnkit/core 1.15.0 → 1.16.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.
@@ -24,6 +24,7 @@ import { parseExpression } from "@bpmnkit/feel";
24
24
  import { slugify, uniqueId } from "../plan/slug.js";
25
25
  import { expand } from "./compact.js";
26
26
  import { CONNECTOR_LINE, parseConnectorLine } from "./connector-line.js";
27
+ import { messageEndProblem } from "./swimlanes.js";
27
28
  /**
28
29
  * How to write the format — the part of a system prompt that teaches it.
29
30
  *
@@ -43,6 +44,8 @@ Names after |: msg=<message name> key=<FEEL> (key required where a message is wa
43
44
  Also after |: form=<form id> (start, user), in.<name>=<FEEL> and out.<name>=<FEEL> map variables in and out of a step (value runs to the next word=; write comparisons with spaces: a = 1)
44
45
  Ad-hoc: agent[adhoc Name] is a container with flows like any node; tool[service Name | inside=agent] has no flows of its own; note <id>: text annotates a node
45
46
  doc <id>: text the element's documentation; for a tool inside an ad-hoc agent it is the description the agent chooses the tool by
47
+ lane sales[Sales team]: a, b a and b are done by the Sales team: one line per role, after the paths
48
+ pool bank[Bank] another party; msg pay >(Payment) bank is a message to it, msg bank > paid one from it
46
49
  Ad-hoc example:
47
50
  ask[start Question asked] > agent[adhoc Answer with tools] > review[user Review answer] > done[end Answered]
48
51
  users[service Look up users | inside=agent]
@@ -55,6 +58,7 @@ Rules:
55
58
  - A boundary leads only to the handling. What happens next when nothing fails follows the task itself (read > count), never the boundary.
56
59
  - A step that only works on process data (count, sum, filter, compare, pick, format a message) is a script task, never a service or plain task: its FEEL reads the variables earlier steps set with result=. read[service Read issues | result=issues] > count[script Count open issues | result=openCount feel=count(issues[state = "open"])]
57
60
  - Branches that meet again are joined automatically; join parallel branches with an and node.
61
+ - Lanes and pools only when the description names roles or other parties; then every node is in one lane.
58
62
  - Steps done at the same time start from an and node and meet at another. A deadline is a boundary:timer with after= on the task that may run late. A step done for every item of a list takes each=<list>; use it only when the description says every or each.
59
63
 
60
64
  Example:
@@ -133,6 +137,27 @@ const ID = /^[A-Za-z_][\w.-]*/;
133
137
  export const NOTE_LINE = /^note\s+([A-Za-z_][\w.-]*)\s*:\s*(.*)$/i;
134
138
  /** `doc <id>: text`, the element's documentation; free text like a note. */
135
139
  export const DOC_LINE = /^doc\s+([A-Za-z_][\w.-]*)\s*:\s*(.*)$/i;
140
+ /**
141
+ * `lane <id>[Name]: a, b`, the swimlane a role works in. Whitespace after the
142
+ * keyword is required, so `lane_check[user …] > x` is still a path. The keywords
143
+ * of this and the next two lines are lowercase only, as the guides teach them:
144
+ * prose such as "Lane changes: move review into sales" starts with a capital.
145
+ * Without a bracket the lane is named after its id, as a node is; `[]` leaves
146
+ * it unnamed.
147
+ */
148
+ export const LANE_LINE = /^lane\s+([A-Za-z_][\w.-]*)\s*(?:\[([^\]]*)\])?\s*:\s*(.*)$/;
149
+ /**
150
+ * `pool <id>[Name]`, another party drawn as an empty pool; `[]` leaves it
151
+ * unnamed. The bracket is required: without it, two words of prose such as
152
+ * "pool party" would declare a pool.
153
+ */
154
+ export const POOL_LINE = /^pool\s+([A-Za-z_][\w.-]*)\s*\[([^\]]*)\]\s*$/;
155
+ /**
156
+ * `msg a >(Label) b`, a message between a node and a pool. Its own keyword, so a
157
+ * path can never mix sequence and message flows; the label is kept as written,
158
+ * colons included, because a message has no condition.
159
+ */
160
+ export const MESSAGE_LINE = /^msg\s+([A-Za-z_][\w.-]*)\s*-{0,2}>\s*(?:\(([^()]*)\)\s*)?([A-Za-z_][\w.-]*)\s*$/;
136
161
  /** A title segment that is only attributes of a known key: `camunda=8.10`. */
137
162
  const HEADER_SEGMENT = /^[\s,]*(?:camunda=[^\s,|]*[\s,]*)+$/;
138
163
  /** A line that ends in an arrow, with or without a branch label: the path goes on below. */
@@ -234,8 +259,11 @@ function typeFromId(id) {
234
259
  return "endEvent";
235
260
  return "task";
236
261
  }
237
- /** `send_email` / `sendEmail` → "Send email": a readable name for a node the model never named. */
238
- function nameFromId(id) {
262
+ /**
263
+ * `send_email` / `sendEmail` → "Send email": a readable name for a node, lane
264
+ * or pool the model never named.
265
+ */
266
+ export function nameFromId(id) {
239
267
  const words = id
240
268
  .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
241
269
  .replace(/[_.-]+/g, " ")
@@ -405,6 +433,12 @@ class Reader {
405
433
  notes = [];
406
434
  /** `doc` lines, with the written id resolved to the node it meant when read. */
407
435
  docs = [];
436
+ /** `lane` lines. A member already declared is resolved when read, as a note is. */
437
+ lanes = [];
438
+ /** `pool` lines. */
439
+ pools = [];
440
+ /** `msg` lines. */
441
+ messages = [];
408
442
  /** Catch and boundary events written without a trigger, and made message events. */
409
443
  guessedMessage = new Set();
410
444
  title;
@@ -414,6 +448,54 @@ class Reader {
414
448
  carry;
415
449
  /** The last node of the last path read, which a line starting with an arrow continues. */
416
450
  tail;
451
+ /** An id as written, and the node it meant when its line was read, if it was declared by then. */
452
+ ref(written) {
453
+ const resolved = this.current.get(written);
454
+ return resolved === undefined ? { written } : { written, resolved };
455
+ }
456
+ /**
457
+ * The node a reference means. One read before its node was declared means the
458
+ * first node declared under that id, as the line came before any reuse.
459
+ */
460
+ resolve(ref) {
461
+ return ref.resolved ?? this.declared.get(ref.written)?.[0] ?? ref.written;
462
+ }
463
+ /** Reads `lane`, `pool` and `msg` lines. Returns whether the line was one. */
464
+ swimlane(text, n) {
465
+ const lane = LANE_LINE.exec(text);
466
+ if (lane) {
467
+ const name = lane[2]?.trim();
468
+ const members = (lane[3] ?? "")
469
+ .split(/[\s,]+/)
470
+ .filter(Boolean)
471
+ .map((id) => this.ref(id));
472
+ this.lanes.push({
473
+ written: lane[1],
474
+ ...(name ? { name } : name === "" ? { unnamed: true } : {}),
475
+ members,
476
+ line: n,
477
+ });
478
+ return true;
479
+ }
480
+ const pool = POOL_LINE.exec(text);
481
+ if (pool) {
482
+ const name = pool[2]?.trim();
483
+ this.pools.push({ written: pool[1], ...(name ? { name } : {}), line: n });
484
+ return true;
485
+ }
486
+ const message = MESSAGE_LINE.exec(text);
487
+ if (message) {
488
+ const name = message[2]?.trim();
489
+ this.messages.push({
490
+ from: this.ref(message[1]),
491
+ to: this.ref(message[3]),
492
+ ...(name ? { name } : {}),
493
+ line: n,
494
+ });
495
+ return true;
496
+ }
497
+ return false;
498
+ }
417
499
  /** Reads the attributes after the bar of the title line. */
418
500
  header(attrs, n) {
419
501
  for (const attr of attrs.split(/[\s,|]+/).filter(Boolean)) {
@@ -483,6 +565,8 @@ class Reader {
483
565
  });
484
566
  return true;
485
567
  }
568
+ if (this.swimlane(text, n))
569
+ return true;
486
570
  // `> stop[end Done]`: the path above wrapped before its arrow
487
571
  if (/^-{0,2}>/.test(text) && this.tail !== undefined) {
488
572
  this.problems.push({
@@ -1881,6 +1965,12 @@ function assemble(reader, final) {
1881
1965
  fixes.push(`"${node.element.id}" calls decision "${decision}"; set decision= to call another`);
1882
1966
  }
1883
1967
  }
1968
+ // Before the process and flow ids are chosen, so those step around lane and pool ids.
1969
+ const lanes = readLanes(reader, nodes, childNodes, taken, final, problems);
1970
+ if (lanes.length > 0)
1971
+ fillLanes(lanes, nodes, edges, fixes);
1972
+ const pools = readPools(reader, nodes, lanes, taken, problems);
1973
+ const messageFlows = readMessages(reader, nodes, pools, taken, final, problems);
1884
1974
  const processBase = reader.title ? slugify(reader.title) : "Process_1";
1885
1975
  const processId = uniqueId(/^[A-Za-z_]/.test(processBase) ? processBase : `Process_${processBase}`, taken);
1886
1976
  let flowNumber = 0;
@@ -1975,8 +2065,11 @@ function assemble(reader, final) {
1975
2065
  elements: [...nodes.values()].map((node) => node.element),
1976
2066
  flows,
1977
2067
  ...(notes.length > 0 ? { notes } : {}),
2068
+ ...(lanes.length > 0 ? { lanes } : {}),
1978
2069
  },
1979
2070
  ],
2071
+ ...(pools.size > 0 ? { participants: [...pools.values()] } : {}),
2072
+ ...(messageFlows.length > 0 ? { messageFlows } : {}),
1980
2073
  },
1981
2074
  problems: problems.sort((a, b) => a.line - b.line),
1982
2075
  fixes,
@@ -1984,6 +2077,261 @@ function assemble(reader, final) {
1984
2077
  connectors,
1985
2078
  };
1986
2079
  }
2080
+ /**
2081
+ * The `lane` lines as compact lanes, in the order first written. A lane written
2082
+ * twice gathers both lines' members; a node listed in two lanes stays in the
2083
+ * later one. Members that are not top-level nodes are left out: while streaming
2084
+ * silently, since they may yet be declared.
2085
+ */
2086
+ function readLanes(reader, nodes, childNodes, taken, final, problems) {
2087
+ const byWritten = new Map();
2088
+ const laneOfNode = new Map();
2089
+ const listedOn = new Map();
2090
+ for (const line of reader.lanes) {
2091
+ let lane = byWritten.get(line.written);
2092
+ if (lane === undefined) {
2093
+ let id = line.written;
2094
+ if (taken.has(id)) {
2095
+ id = uniqueId(`${line.written}_lane`, taken);
2096
+ problems.push({
2097
+ line: line.line,
2098
+ message: `lane ${line.written}: the id is ${clashOwner(line.written, nodes, byWritten.values())}; wrote the lane as "${id}"`,
2099
+ });
2100
+ }
2101
+ else
2102
+ taken.add(id);
2103
+ lane = line.unnamed
2104
+ ? { id, members: [] }
2105
+ : { id, name: line.name ?? nameFromId(line.written), members: [] };
2106
+ byWritten.set(line.written, lane);
2107
+ }
2108
+ else if (line.name !== undefined)
2109
+ lane.name = line.name;
2110
+ for (const ref of line.members) {
2111
+ const id = reader.resolve(ref);
2112
+ if (!nodes.has(id)) {
2113
+ const container = childNodes.find((child) => child.element.id === id)?.inside;
2114
+ if (container !== undefined) {
2115
+ problems.push({
2116
+ line: line.line,
2117
+ message: `lane ${line.written}: "${ref.written}" is inside "${container}", and a lane holds only top-level nodes; left out`,
2118
+ });
2119
+ }
2120
+ else if (final) {
2121
+ problems.push({
2122
+ line: line.line,
2123
+ message: `lane ${line.written}: "${ref.written}" is not a node of the diagram; left out`,
2124
+ });
2125
+ }
2126
+ continue;
2127
+ }
2128
+ const before = laneOfNode.get(id);
2129
+ if (before === lane)
2130
+ continue;
2131
+ if (before !== undefined) {
2132
+ before.members = before.members.filter((member) => member !== id);
2133
+ problems.push({
2134
+ line: line.line,
2135
+ message: `lane ${line.written}: "${ref.written}" is already in lane ${before.id}; moved it to ${lane.id}`,
2136
+ });
2137
+ }
2138
+ lane.members.push(id);
2139
+ laneOfNode.set(id, lane);
2140
+ listedOn.set(id, line.line);
2141
+ }
2142
+ }
2143
+ const lanes = [...byWritten.values()];
2144
+ keepBoundariesWithHosts(lanes, laneOfNode, nodes, listedOn, problems);
2145
+ return lanes;
2146
+ }
2147
+ /** What an id already in use names, for a problem: "a node's" or "a lane's". */
2148
+ function clashOwner(id, nodes, lanes) {
2149
+ if (nodes.has(id))
2150
+ return "a node's";
2151
+ for (const lane of lanes)
2152
+ if (lane.id === id)
2153
+ return "a lane's";
2154
+ return "already used";
2155
+ }
2156
+ /**
2157
+ * Moves a boundary event a lane line put apart from its host into the host's
2158
+ * lane. Layout draws it on the host's border, so any other lane would claim a
2159
+ * node it does not contain.
2160
+ */
2161
+ function keepBoundariesWithHosts(lanes, laneOfNode, nodes, listedOn, problems) {
2162
+ for (const lane of lanes) {
2163
+ for (const id of [...lane.members]) {
2164
+ const host = nodes.get(id)?.element.attachedTo;
2165
+ const hostLane = host === undefined ? undefined : laneOfNode.get(host);
2166
+ if (hostLane === undefined || hostLane === lane)
2167
+ continue;
2168
+ lane.members = lane.members.filter((member) => member !== id);
2169
+ hostLane.members.push(id);
2170
+ laneOfNode.set(id, hostLane);
2171
+ problems.push({
2172
+ line: listedOn.get(id) ?? 0,
2173
+ message: `lane ${lane.id}: "${id}" is a boundary event on "${host}"; put it in ${host}'s lane ${hostLane.id}`,
2174
+ });
2175
+ }
2176
+ }
2177
+ }
2178
+ /**
2179
+ * Puts every node no lane names in a neighbour's lane: a boundary event in its
2180
+ * host's, anything else in its first predecessor's, else its first
2181
+ * successor's, else the first lane. Join gateways and end events the parser
2182
+ * added are such nodes, so they land beside what they connect.
2183
+ */
2184
+ function fillLanes(lanes, nodes, edges, fixes) {
2185
+ const laneOf = new Map();
2186
+ for (const lane of lanes)
2187
+ for (const id of lane.members ?? [])
2188
+ laneOf.set(id, lane);
2189
+ const put = (id, lane) => {
2190
+ lane.members = [...(lane.members ?? []), id];
2191
+ laneOf.set(id, lane);
2192
+ fixes.push(`put "${id}", which no lane named, in lane ${lane.id}`);
2193
+ };
2194
+ const unassigned = () => [...nodes.keys()].filter((id) => !laneOf.has(id));
2195
+ const byNeighbour = (id, side) => {
2196
+ const other = side === "from" ? "to" : "from";
2197
+ for (const edge of edges) {
2198
+ if (edge[other] !== id)
2199
+ continue;
2200
+ const lane = laneOf.get(edge[side]);
2201
+ if (lane !== undefined)
2202
+ return lane;
2203
+ }
2204
+ return undefined;
2205
+ };
2206
+ // Each pass places at least one node or stops, so this ends within nodes.size passes.
2207
+ for (let pass = 0; pass <= nodes.size; pass++) {
2208
+ let placed = false;
2209
+ for (const id of unassigned()) {
2210
+ const host = nodes.get(id)?.element.attachedTo;
2211
+ const lane = host !== undefined ? laneOf.get(host) : byNeighbour(id, "from");
2212
+ if (lane !== undefined) {
2213
+ put(id, lane);
2214
+ placed = true;
2215
+ }
2216
+ }
2217
+ if (placed)
2218
+ continue;
2219
+ for (const id of unassigned()) {
2220
+ const lane = byNeighbour(id, "to");
2221
+ if (lane !== undefined) {
2222
+ put(id, lane);
2223
+ placed = true;
2224
+ break;
2225
+ }
2226
+ }
2227
+ if (!placed)
2228
+ break;
2229
+ }
2230
+ const first = lanes[0];
2231
+ if (first !== undefined)
2232
+ for (const id of unassigned())
2233
+ put(id, first);
2234
+ }
2235
+ /** The `pool` lines as black-box participants, keyed by the id they were written with. */
2236
+ function readPools(reader, nodes, lanes, taken, problems) {
2237
+ const pools = new Map();
2238
+ for (const line of reader.pools) {
2239
+ const known = pools.get(line.written);
2240
+ if (known !== undefined) {
2241
+ if (line.name !== undefined)
2242
+ known.name = line.name;
2243
+ continue;
2244
+ }
2245
+ let id = line.written;
2246
+ if (taken.has(id)) {
2247
+ id = uniqueId(`${line.written}_pool`, taken);
2248
+ problems.push({
2249
+ line: line.line,
2250
+ message: `pool ${line.written}: the id is ${clashOwner(line.written, nodes, lanes)}; wrote the pool as "${id}"`,
2251
+ });
2252
+ }
2253
+ else
2254
+ taken.add(id);
2255
+ pools.set(line.written, line.name === undefined ? { id } : { id, name: line.name });
2256
+ }
2257
+ return pools;
2258
+ }
2259
+ /**
2260
+ * Resolves the two ends of a `msg` line. An id that names both a node and a
2261
+ * pool (the pool was renamed `<id>_pool`) means whichever makes one end a node
2262
+ * and the other a pool; when both ends are such ids, a node sends to a pool.
2263
+ */
2264
+ function messageEnds(reader, nodes, pools, from, to) {
2265
+ const candidates = (ref) => {
2266
+ const pool = pools.get(ref.written);
2267
+ const id = reader.resolve(ref);
2268
+ const element = nodes.get(id)?.element;
2269
+ return {
2270
+ pool: pool === undefined ? undefined : { kind: "pool", id: pool.id },
2271
+ node: element === undefined ? undefined : { kind: "node", id, element },
2272
+ };
2273
+ };
2274
+ const a = candidates(from);
2275
+ const b = candidates(to);
2276
+ if (a.pool && a.node && b.pool && b.node)
2277
+ return [a.node, b.pool];
2278
+ if (a.pool && a.node)
2279
+ return [b.pool && !b.node ? a.node : a.pool, b.pool ?? b.node];
2280
+ if (b.pool && b.node)
2281
+ return [a.pool ?? a.node, a.pool && !a.node ? b.node : b.pool];
2282
+ return [a.pool ?? a.node, b.pool ?? b.node];
2283
+ }
2284
+ /**
2285
+ * The `msg` lines as message flows. One end is a node of the process and the
2286
+ * other a pool: the process's own pool has no line, so a message inside it
2287
+ * would be a sequence flow drawn the wrong way.
2288
+ */
2289
+ function readMessages(reader, nodes, pools, taken, final, problems) {
2290
+ const flows = [];
2291
+ const seen = new Set();
2292
+ let number = 0;
2293
+ for (const line of reader.messages) {
2294
+ const what = `msg ${line.from.written} > ${line.to.written}`;
2295
+ const [from, to] = messageEnds(reader, nodes, pools, line.from, line.to);
2296
+ const refuse = (reason) => problems.push({ line: line.line, message: `${what}: ${reason}; left out` });
2297
+ if (from === undefined || to === undefined) {
2298
+ const missing = from === undefined ? line.from.written : line.to.written;
2299
+ if (final)
2300
+ refuse(`"${missing}" is not a node or a pool`);
2301
+ continue;
2302
+ }
2303
+ if (from.kind === "pool" && to.kind === "pool") {
2304
+ refuse("both ends are pools; one end must be a node of the process");
2305
+ continue;
2306
+ }
2307
+ if (from.kind === "node" && to.kind === "node") {
2308
+ refuse("both ends are in this process; a message goes to or comes from a pool line");
2309
+ continue;
2310
+ }
2311
+ const reason = (from.kind === "node"
2312
+ ? messageEndProblem(from.element.type, from.element.eventType, "source")
2313
+ : undefined) ??
2314
+ (to.kind === "node"
2315
+ ? messageEndProblem(to.element.type, to.element.eventType, "target")
2316
+ : undefined);
2317
+ if (reason !== undefined) {
2318
+ refuse(reason);
2319
+ continue;
2320
+ }
2321
+ const source = from.id;
2322
+ const target = to.id;
2323
+ if (seen.has(`${source}>${target}`))
2324
+ continue;
2325
+ seen.add(`${source}>${target}`);
2326
+ let id;
2327
+ do
2328
+ id = `MessageFlow_${++number}`;
2329
+ while (taken.has(id));
2330
+ taken.add(id);
2331
+ flows.push({ id, source, target, ...(line.name !== undefined ? { name: line.name } : {}) });
2332
+ }
2333
+ return flows;
2334
+ }
1987
2335
  /**
1988
2336
  * Reads a process written in the line format ({@link PROCESS_TEXT_GUIDE}).
1989
2337
  *
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Pure helpers for writing lanes and pools: every writer (builder, compact,
3
+ * process text, change scripts, editor) goes through these so they agree on
4
+ * one set of invariants. None of them mutates its input.
5
+ *
6
+ * Invariants a well-formed laned process meets (see {@link laneProblems}):
7
+ * every top-level flow node sits in exactly one leaf lane, a boundary event
8
+ * sits in its host's lane, sub-process children and data references sit in
9
+ * none. Ancestor lanes may or may not repeat their descendants' refs: Flowable
10
+ * and Camunda Modeler write the union, the editor writes leaves only, and both
11
+ * are accepted.
12
+ */
13
+ import type { BpmnDefinitions, BpmnLane, BpmnLaneSet, BpmnProcess } from "./bpmn-model.js";
14
+ /** A lane to build: a leaf when `lanes` is absent or empty. Same shape as compact's lane. */
15
+ export interface LaneSpec {
16
+ id: string;
17
+ name?: string;
18
+ lanes?: LaneSpec[];
19
+ }
20
+ /** The error a lane tree that loops back on itself is refused with. */
21
+ export declare function revisitMessage(laneId: string): string;
22
+ /**
23
+ * Every lane of `laneSet`, nested ones included, depth first (a parent before
24
+ * its children). Throws when the lane tree loops back on itself.
25
+ */
26
+ export declare function allLanes(laneSet?: BpmnLaneSet): BpmnLane[];
27
+ /**
28
+ * The lanes of `laneSet` that have no child lanes, depth first: the lanes a
29
+ * flow node is assigned to. Throws when the lane tree loops back on itself.
30
+ */
31
+ export declare function leafLanes(laneSet?: BpmnLaneSet): BpmnLane[];
32
+ /**
33
+ * The deepest lane of `process` whose refs list `nodeId`, so a union-convention
34
+ * ancestor never wins over the leaf. `undefined` when no lane lists it.
35
+ */
36
+ export declare function laneOf(process: BpmnProcess, nodeId: string): BpmnLane | undefined;
37
+ /**
38
+ * Returns a copy of `process` in which `nodeId` and the boundary events
39
+ * attached to it sit in leaf lane `laneId` and in no other lane.
40
+ *
41
+ * Ancestors of the target receive the node too only when the file already
42
+ * follows the union convention there; otherwise only the leaf is written.
43
+ * Whether `nodeId` exists is not checked ({@link laneProblems} reports it).
44
+ *
45
+ * @throws Error when `laneId` is not a lane of `process`, or has child lanes,
46
+ * or when `nodeId` is a boundary event whose host sits in another leaf lane:
47
+ * a boundary event goes where its host goes.
48
+ */
49
+ export declare function assignLane(process: BpmnProcess, nodeId: string, laneId: string): BpmnProcess;
50
+ /**
51
+ * Returns a copy of `process` whose lanes list only its top-level flow nodes:
52
+ * refs to missing ids, sub-process children and data references are dropped.
53
+ * A lane set without lanes is removed. A process without a lane set is
54
+ * returned as it is.
55
+ */
56
+ export declare function pruneLaneRefs(process: BpmnProcess): BpmnProcess;
57
+ /**
58
+ * Builds the lane set of `process` from `specs` and `leafOf` (flow node id to
59
+ * leaf lane id). Refs keep `leafOf`'s order and ids verbatim, so
60
+ * {@link laneProblems} can still report a ref to an unknown node. A boundary
61
+ * event always joins its host's lane when the host is mapped. Parent lanes list
62
+ * the union of their descendants' refs. Ids: `LaneSet_<processId>` for the set,
63
+ * `LaneSet_<laneId>` for a child set, with a numeric suffix when already in use.
64
+ *
65
+ * @throws Error listing every `leafOf` entry that names an undeclared lane or a
66
+ * lane with child lanes, or when `specs` loops back on itself or declares
67
+ * one id twice.
68
+ */
69
+ export declare function buildLaneSet(process: BpmnProcess, specs: readonly LaneSpec[], leafOf: ReadonlyMap<string, string>): BpmnLaneSet;
70
+ /**
71
+ * The leaf lane a node newly added to an already-laned `process` belongs in:
72
+ * its host's lane for a boundary event, else the lane of its first sequence-flow
73
+ * predecessor that has one, else of its first such successor, else the first
74
+ * leaf lane. `undefined` when the process has no lanes.
75
+ */
76
+ export declare function laneForNewNode(process: BpmnProcess, nodeId: string): BpmnLane | undefined;
77
+ /**
78
+ * The process a single-process writer edits: the first process, in the
79
+ * participant order of `collaborations[0]`, that is explicitly executable; else
80
+ * the first explicitly executable process; else the first process with flow
81
+ * elements or lanes. When every process is empty, the candidates are the ones
82
+ * not marked `isExecutable="false"` (Flowable reads an absent attribute as
83
+ * executable), or all of them when every one is; among them the one whose pool
84
+ * is drawn largest, else the first. Modeler files do not always put the
85
+ * executable pool first.
86
+ *
87
+ * {@link BpmnDefinitions.primaryProcessId}, while it names a process of
88
+ * `defs`, comes right after the explicitly executable process: it breaks the
89
+ * tie the semantics cannot, as an emptied own pool next to a partner's pool
90
+ * with content and `isExecutable="false"` reads exactly like a partner's empty
91
+ * pool next to a file's only process. An explicit `isExecutable="true"`, which
92
+ * another tool may have set since, is no tie and still wins.
93
+ */
94
+ export declare function primaryProcess(defs: Pick<BpmnDefinitions, "collaborations" | "processes"> & Partial<Pick<BpmnDefinitions, "diagrams" | "primaryProcessId">>): BpmnProcess | undefined;
95
+ /** The namespace of the `primaryProcess` attribute {@link pinnedPrimaryToWrite} puts on `<definitions>`. */
96
+ export declare const BPMNKIT_NAMESPACE = "https://bpmnkit.com/schema/bpmn";
97
+ /**
98
+ * `namespaces` with {@link BPMNKIT_NAMESPACE} declared, and its prefix: the one
99
+ * already declared, else `bpmnkit`, else the first free `bpmnkit<n>`.
100
+ */
101
+ export declare function withBpmnkitNamespace(namespaces: Record<string, string>): {
102
+ namespaces: Record<string, string>;
103
+ prefix: string;
104
+ };
105
+ /**
106
+ * `defs` with {@link BpmnDefinitions.primaryProcessId} set to `processId`, or
107
+ * cleared when it is `undefined`. Setting it also declares the bpmnkit
108
+ * namespace, and clearing it leaves the declaration: a document parsed from a
109
+ * pinned file keeps it too, so both write the same bytes whatever happens to
110
+ * the pin later.
111
+ */
112
+ export declare function pinPrimaryProcess(defs: BpmnDefinitions, processId: string | undefined): BpmnDefinitions;
113
+ /**
114
+ * The {@link BpmnDefinitions.primaryProcessId} a file must carry, or
115
+ * `undefined` when the file alone already leads {@link primaryProcess} there,
116
+ * so a document nobody emptied stays byte-identical.
117
+ */
118
+ export declare function pinnedPrimaryToWrite(defs: BpmnDefinitions): string | undefined;
119
+ /** What {@link documentIdList} reads; every part optional, so a builder can pass what it has. */
120
+ export type IdSource = Partial<Pick<BpmnDefinitions, "id" | "messages" | "errors" | "signals" | "escalations" | "processes" | "collaborations">>;
121
+ /**
122
+ * Every id the document uses, once per use, so an id listed twice is a clash:
123
+ * the definitions, root elements, processes with their flow elements, flows and
124
+ * artifacts at any depth, lane sets and lanes, and collaborations with what
125
+ * they hold. Duplicate checks and fresh ids both read this one list, so they
126
+ * cannot disagree about what is taken.
127
+ */
128
+ export declare function documentIdList(defs: IdSource): string[];
129
+ /** Every repeated use in {@link documentIdList}: an id used three times is listed twice. */
130
+ export declare function duplicateIds(defs: IdSource): string[];
131
+ /**
132
+ * `first` when free, else the first free `nth(2)`, `nth(3)`, …; claims it in `taken`.
133
+ * Bounded: at most `taken.size` candidates can be taken, so one of the first
134
+ * `taken.size + 1` distinct candidates is free.
135
+ */
136
+ export declare function freshId(first: string, nth: (n: number) => string, taken: Set<string>): string;
137
+ /**
138
+ * "Lanes imply a pool": auto-layout draws lanes only inside a participant, and
139
+ * once a collaboration exists a process without one is drawn pool-less.
140
+ *
141
+ * When any process has a lane set or any collaboration exists, returns a copy
142
+ * in which `collaborations[0]` exists (id `Collaboration_1` unless taken) and
143
+ * every process with flow elements or a lane set is referenced by a
144
+ * participant (`Participant_<processId>`, named after the process, else its
145
+ * id). A process pooled here that is not the {@link primaryProcess} and has no
146
+ * `isExecutable` gets `isExecutable: false`, because Flowable reads an absent
147
+ * attribute as executable. Otherwise returns `defs` itself.
148
+ */
149
+ export declare function poolLanedProcesses(defs: BpmnDefinitions): BpmnDefinitions;
150
+ /**
151
+ * Everything wrong with the lanes of `process`, one message per finding:
152
+ * duplicate lane ids, refs to missing ids, to sub-process children or to data
153
+ * references, a flow node in two leaf lanes, and — once lanes exist — a
154
+ * top-level flow node in no leaf lane (data references, and boundary events
155
+ * whose host is assigned, are exempt), and a boundary event in a leaf lane its
156
+ * host is not in. Whether parents repeat their children's refs is not checked.
157
+ * Empty for a process without lanes.
158
+ */
159
+ export declare function laneProblems(process: BpmnProcess): string[];
160
+ /**
161
+ * Why an element of `type` cannot be the `side` end of a message flow, or
162
+ * undefined when it can. `trigger` is an event's first event definition
163
+ * (`"message"`, `"timer"`, …), undefined for a plain event or anything else.
164
+ * A pool can be either end. One rule for every writer, so a change script, the
165
+ * process text reader and the editor refuse the same messages.
166
+ */
167
+ export declare function messageEndProblem(type: string, trigger: string | undefined, side: "source" | "target"): string | undefined;
168
+ /**
169
+ * Everything about the collaborations of `defs` that a modeler would refuse
170
+ * or open broken, one message per finding: duplicate participant or message
171
+ * flow ids, a participant naming a missing process, two participants claiming
172
+ * one process, a message-flow end that is neither a participant nor a flow node
173
+ * in one, a message flow that stays inside one pool, a message flow naming an
174
+ * undeclared message, and — once a collaboration exists — a process with
175
+ * content that no participant references. Empty without collaborations.
176
+ */
177
+ export declare function collaborationProblems(defs: Pick<BpmnDefinitions, "collaborations" | "processes" | "messages"> & IdSource): string[];
178
+ //# sourceMappingURL=swimlanes.d.ts.map