@bpmnkit/docspack 0.0.3 → 0.0.5

package/.llms/chunks/packages.core.installation-expand-compact.md

@@ -11,5 +11,9 @@ const definitions = expand(compactDiagram);
 const xml = Bpmn.export(definitions);
 ```
 
+Every element type the model knows expands to itself, data elements included. The switch is
+exhaustive, so a new `BpmnElementType` fails the build here rather than silently arriving as a
+`task` — which is how `dataObject`, `dataObjectReference` and `dataStoreReference` were lost.
+
 ---
 Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.installation-processbuilder-methods.md

@@ -9,11 +9,20 @@ All builder methods return `this` for chaining.
 | `.serviceTask(id, options?)` | Add a service task |
 | `.userTask(id, options?)` | Add a user task |
 | `.scriptTask(id, options?)` | Add a script task |
+| `.sendTask(id, options?)` | Add a send task |
+| `.receiveTask(id, options?)` | Add a receive task |
+| `.businessRuleTask(id, options?)` | Add a business rule task |
+| `.manualTask(id, options?)` | Add a manual task — work done outside the engine, no job worker |
+| `.task(id, options?)` | Add an abstract task with no Zeebe extensions |
 | `.exclusiveGateway(id, options?)` | Add an XOR gateway |
 | `.parallelGateway(id, options?)` | Add a parallel gateway |
 | `.inclusiveGateway(id, options?)` | Add an inclusive gateway |
 | `.eventBasedGateway(id, options?)` | Add an event-based gateway |
+| `.complexGateway(id, options?)` | Add a complex gateway (aspirational — Zeebe does not execute these) |
 | `.subProcess(id, builder, options?)` | Add an embedded sub-process |
+| `.adHocSubProcess(id, builder, options?)` | Add an ad-hoc sub-process — its children are **not** auto-chained, see below |
+| `.eventSubProcess(id, builder, options?)` | Add an event sub-process (emits `subProcess triggeredByEvent="true"`) |
+| `.transaction(id, builder, options?)` | Add a transaction sub-process (atomic scope) |
 | `.callActivity(id, options?)` | Add a call activity |
 | `.intermediateCatchEvent(id, options?)` | Add a catch event |
 | `.intermediateThrowEvent(id, options?)` | Add a throw event |
@@ -25,5 +34,11 @@ All builder methods return `this` for chaining.
 | `.withAutoLayout()` | Apply Sugiyama layout before building |
 | `.build(options?)` | Return the completed `BpmnDefinitions`. Pass `{ explicitJoins: true }` to refuse inferred join gateways — see below |
 
+Every BPMN element type the model knows is reachable from a builder chain, except the three
+data types (`dataObject`, `dataObjectReference`, `dataStoreReference`) — those are wired by
+data associations rather than sequence flows, so the chain has nowhere to put them. A
+compile-time table, `BUILDER_COVERAGE`, holds the SDK to that: adding an element type without
+a builder method fails the build. Run `pnpm --filter @bpmnkit/core check:builder` to print it.
+
 ---
 Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.installation-retypeelement-element-type.md

@@ -0,0 +1,20 @@
+# @bpmnkit/core — Installation — `retypeElement(element, type)`
+
+Returns a copy of a flow element with a different `type`, keeping its id, name, documentation
+and — crucially — its incoming and outgoing sequence flows. Use this to change a task's type
+instead of removing and re-adding the element, which drops the wiring.
+
+```typescript
+import { retypeElement } from "@bpmnkit/core";
+
+const index = process.flowElements.findIndex((el) => el.id === "charge");
+process.flowElements[index] = retypeElement(process.flowElements[index], "manualTask");
+```
+
+Nested content is carried between container types, and a multi-instance marker between types
+that both allow one. Zeebe extensions the new type cannot legally hold are dropped, using the
+same placement table `ensureZeebeExtension` enforces — so a `serviceTask` retyped to
+`manualTask` does not keep a job worker the engine would refuse.
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.writing-files-bpmnkit-core-node-exportpreserving-original-definitions.md

@@ -0,0 +1,51 @@
+# @bpmnkit/core — Writing files — `@bpmnkit/core/node` — `exportPreserving(original, definitions)`
+
+Writes a model back over the file it came from, changing as little as possible.
+
+`Bpmn.export()` writes a model the way this toolkit writes models. That is the right output
+for a new document and the wrong one for an existing file: the first visual edit reformats
+every line, and the commit says "the whole diagram" when it means "a box moved".
+
+Exported from `@bpmnkit/core` itself, not the `/node` subpath — it is string work, and the
+caller owns the file:
+
+```typescript
+import { readFile, writeFile } from "node:fs/promises";
+import { Bpmn, exportPreserving } from "@bpmnkit/core";
+
+const onDisk = await readFile("order.bpmn", "utf8");
+const edited = Bpmn.parse(onDisk);
+edited.processes[0].flowElements[0].name = "Validate Order";
+
+await writeFile("order.bpmn", exportPreserving(onDisk, edited));
+// Renaming one task changes one line, not the whole file.
+```
+
+Indentation, attribute order, comments, the order children were written in, and attributes
+left at their schema default all survive. Opening a file and writing it back unchanged leaves
+it byte for byte.
+
+Nothing about that is assumed, though. The model cannot represent the order a file writes its
+children in — a process holds `flowElements` and `sequenceFlows` as separate lists — so each
+strategy is tried, **the result is parsed back and compared against a plain write**, and the
+first that reads the same is the one used. The plain write is the floor, so calling this is
+never worse than not.
+
+| Function | Takes | Returns |
+| --- | --- | --- |
+| `exportPreserving(original, definitions)` | the file's current text + a model | the new text |
+| `exportPreservingResult(original, definitions)` | same | the text plus what it managed to keep |
+| `preserveBpmnFormatting(original, updated)` | two documents as text | for a caller that already serialised, such as an editor's `exportXml()` |
+| `exportDmnPreserving` / `preserveDmnFormatting` | DMN | the same treatment |
+| `exportFormPreserving` / `preserveFormFormatting` | Camunda form JSON | indentation, key order and trailing newline |
+
+This is what the [VS Code extension](/docs/guides/vscode) saves through, and what makes a
+visual edit reviewable in a pull request.
+
+Builder output is stable for the same reason: sequence-flow and root-definition ids are
+derived from the model (`Flow_<source>_<target>`, `Message_<name>`, `Error_<code>`) rather
+than randomly generated, so rebuilding an unchanged model produces the same file and the one
+edge that changed is not buried in a diff of edges that did not.
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.writing-files-bpmnkit-core-node-writebpmn-definitions-options.md

@@ -0,0 +1,38 @@
+# @bpmnkit/core — Writing files — `@bpmnkit/core/node` — `writeBpmn(definitions, options)`
+
+The only supported way to write a BPMN file, and the only one that checks what it wrote.
+Before anything reaches disk it serialises the model, **parses the result back**, and compares
+the semantic hashes. If they differ the write is refused and nothing is written.
+
+```typescript
+import { writeBpmn } from "@bpmnkit/core/node";
+import { WriteError, WriteVerificationError } from "@bpmnkit/core";
+
+const result = await writeBpmn(definitions, {
+  output: "flow.bpmn",
+  force: false,        // default — refuses rather than replace an existing file
+  layout: "preserve",  // default — "auto" regenerates the diagram first
+});
+
+result.destination;    // absolute path written
+result.semanticHash;   // the model's hash, verified after reading it back
+result.outputSha256;   // digest of the exact bytes on disk
+result.changes;        // what this write changed about the file it replaced
+```
+
+The file appears complete or not at all: contents go to a temporary file in the destination's
+own directory and are then linked or renamed into place, so an interrupted write cannot leave
+a half-written model behind. Two concurrent writes to the same new path cannot both succeed.
+
+`WriteVerificationError` carries a `changes` field naming the elements that diverged.
+`WriteError` means the destination exists and `force` was not given, or the filesystem refused.
+
+**What the check does not cover.** It compares the model in memory against the model read back
+from the output, so it catches the serialiser losing something. It cannot catch the *parser*
+having dropped something on the way in — content the parser never saw is absent from both
+sides. That is what the round-trip corpus gate covers, and there is deliberately no option to
+skip verification: turning it off would only ever be used to get past the bug it exists to
+report. If you want unchecked serialisation, `Bpmn.export()` still returns a string.
+
+---
+Source: https://bpmnkit.com/docs/packages/core

package/.llms/chunks/packages.core.writing-files-bpmnkit-core-node.md

@@ -3,41 +3,5 @@
 Anything that touches the filesystem lives behind the `@bpmnkit/core/node` subpath, so
 importing `@bpmnkit/core` itself never pulls `node:` builtins into a browser bundle.
 
-### `writeBpmn(definitions, options)`
-
-The only supported way to write a BPMN file, and the only one that checks what it wrote.
-Before anything reaches disk it serialises the model, **parses the result back**, and compares
-the semantic hashes. If they differ the write is refused and nothing is written.
-
-```typescript
-import { writeBpmn } from "@bpmnkit/core/node";
-import { WriteError, WriteVerificationError } from "@bpmnkit/core";
-
-const result = await writeBpmn(definitions, {
-  output: "flow.bpmn",
-  force: false,        // default — refuses rather than replace an existing file
-  layout: "preserve",  // default — "auto" regenerates the diagram first
-});
-
-result.destination;    // absolute path written
-result.semanticHash;   // the model's hash, verified after reading it back
-result.outputSha256;   // digest of the exact bytes on disk
-result.changes;        // what this write changed about the file it replaced
-```
-
-The file appears complete or not at all: contents go to a temporary file in the destination's
-own directory and are then linked or renamed into place, so an interrupted write cannot leave
-a half-written model behind. Two concurrent writes to the same new path cannot both succeed.
-
-`WriteVerificationError` carries a `changes` field naming the elements that diverged.
-`WriteError` means the destination exists and `force` was not given, or the filesystem refused.
-
-**What the check does not cover.** It compares the model in memory against the model read back
-from the output, so it catches the serialiser losing something. It cannot catch the *parser*
-having dropped something on the way in — content the parser never saw is absent from both
-sides. That is what the round-trip corpus gate covers, and there is deliberately no option to
-skip verification: turning it off would only ever be used to get past the bug it exists to
-report. If you want unchecked serialisation, `Bpmn.export()` still returns a string.
-
 ---
 Source: https://bpmnkit.com/docs/packages/core