@bpmnkit/core 0.1.2 → 0.3.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 (63) hide show
  1. package/README.md +30 -1
  2. package/dist/bpmn/bpmn-builder.d.ts +209 -3
  3. package/dist/bpmn/bpmn-builder.js +456 -16
  4. package/dist/bpmn/bpmn-model.d.ts +110 -0
  5. package/dist/bpmn/bpmn-parser.js +1413 -528
  6. package/dist/bpmn/bpmn-serializer.js +171 -19
  7. package/dist/bpmn/compact.d.ts +17 -2
  8. package/dist/bpmn/compact.js +3 -3
  9. package/dist/bpmn/diagram-diff.d.ts +71 -0
  10. package/dist/bpmn/diagram-diff.js +124 -0
  11. package/dist/bpmn/full-operations.d.ts +89 -0
  12. package/dist/bpmn/full-operations.js +478 -0
  13. package/dist/bpmn/index.d.ts +19 -0
  14. package/dist/bpmn/index.js +21 -0
  15. package/dist/bpmn/lint.d.ts +97 -0
  16. package/dist/bpmn/lint.js +135 -0
  17. package/dist/bpmn/optimize/feel.js +2 -2
  18. package/dist/bpmn/optimize/patterns.js +23 -16
  19. package/dist/bpmn/optimize/tasks.js +30 -7
  20. package/dist/bpmn/optimize/utils.js +2 -4
  21. package/dist/bpmn/optimize/variable-flow.js +58 -67
  22. package/dist/bpmn/preserving-writer.d.ts +64 -0
  23. package/dist/bpmn/preserving-writer.js +70 -0
  24. package/dist/bpmn/semantic-hash.d.ts +93 -0
  25. package/dist/bpmn/semantic-hash.js +155 -0
  26. package/dist/bpmn/sha256.d.ts +17 -0
  27. package/dist/bpmn/sha256.js +95 -0
  28. package/dist/bpmn/zeebe-extensions.d.ts +56 -0
  29. package/dist/bpmn/zeebe-extensions.js +79 -0
  30. package/dist/bpmn/zeebe-placement.d.ts +12 -0
  31. package/dist/bpmn/zeebe-placement.js +140 -0
  32. package/dist/dmn/dmn-serializer.js +7 -2
  33. package/dist/dmn/preserving-writer.d.ts +31 -0
  34. package/dist/dmn/preserving-writer.js +36 -0
  35. package/dist/errors.d.ts +40 -1
  36. package/dist/errors.js +41 -0
  37. package/dist/form/preserving-writer.d.ts +47 -0
  38. package/dist/form/preserving-writer.js +50 -0
  39. package/dist/index.d.ts +22 -5
  40. package/dist/index.js +14 -4
  41. package/dist/json/index.d.ts +5 -0
  42. package/dist/json/index.js +3 -0
  43. package/dist/json/json-patch.d.ts +65 -0
  44. package/dist/json/json-patch.js +416 -0
  45. package/dist/json/json-spans.d.ts +48 -0
  46. package/dist/json/json-spans.js +153 -0
  47. package/dist/layout/semantic/graph.d.ts +9 -1
  48. package/dist/layout/semantic/graph.js +42 -17
  49. package/dist/layout/semantic/route.js +102 -42
  50. package/dist/node/index.d.ts +10 -0
  51. package/dist/node/index.js +9 -0
  52. package/dist/node/write.d.ts +81 -0
  53. package/dist/node/write.js +167 -0
  54. package/dist/types/id-generator.js +11 -3
  55. package/dist/xml/index.d.ts +7 -1
  56. package/dist/xml/index.js +4 -1
  57. package/dist/xml/xml-parser.d.ts +71 -0
  58. package/dist/xml/xml-parser.js +437 -145
  59. package/dist/xml/xml-patch.d.ts +109 -0
  60. package/dist/xml/xml-patch.js +459 -0
  61. package/dist/xml/xml-spans.d.ts +45 -0
  62. package/dist/xml/xml-spans.js +74 -0
  63. package/package.json +8 -1
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Rewriting a document in place, so an edit reads as an edit.
3
+ *
4
+ * A serializer given a model produces its own formatting: its indentation, its
5
+ * attribute order, its choice of `
` over `
`. That is correct output
6
+ * and a terrible diff. Move one element in a visual editor and every line of
7
+ * the file changes, so the commit says "the whole diagram" when it means "a box
8
+ * moved forty pixels" — and a reviewer has no way to tell those apart.
9
+ *
10
+ * {@link preserveFormatting} closes that gap without either side having to know
11
+ * about the other. It takes the document as it was and the document as the
12
+ * serializer would write it, and returns a third: the *content* of the second
13
+ * carried by the *bytes* of the first, everywhere the two agree. No model is
14
+ * involved, which is why it serves BPMN, DMN, forms and anything else this
15
+ * toolkit learns to write.
16
+ *
17
+ * @packageDocumentation
18
+ */
19
+ /** How to treat children that appear in both documents in a different order. */
20
+ export type SiblingOrder =
21
+ /**
22
+ * Reorder to match `updated`. Correct for any document, and the default:
23
+ * sibling order carries meaning in plenty of XML, and nothing here can tell
24
+ * which document that is.
25
+ */
26
+ "follow"
27
+ /**
28
+ * Leave matched children where the original had them, patching each in
29
+ * place. Only correct where sibling order says nothing — which is a fact
30
+ * about a *schema*, so a caller choosing this should check the result rather
31
+ * than assume it. `exportPreserving` in the BPMN module is the worked
32
+ * example: it tries this, verifies the parsed model is unchanged, and falls
33
+ * back when it is not.
34
+ */
35
+ | "keep";
36
+ export interface PreserveOptions {
37
+ /** Default `"follow"`. */
38
+ readonly siblingOrder?: SiblingOrder;
39
+ /**
40
+ * What to do about an attribute the original has and the update does not.
41
+ *
42
+ * - `"remove"` (default) — take it out, because the update says so.
43
+ * - `"keep"` — leave it. A serializer omits an attribute set to its schema
44
+ * default, so `isExecutable="false"` disappears from a file that said it
45
+ * out loud. Keeping it is only safe when re-reading the result gives the
46
+ * same model, which is a check the caller has to make; see
47
+ * `exportPreserving` in the BPMN module.
48
+ */
49
+ readonly droppedAttributes?: "remove" | "keep";
50
+ }
51
+ /**
52
+ * Rewrites `original` to say what `updated` says, changing as little as it can.
53
+ *
54
+ * The result is `updated`'s document — the same elements, attributes and text —
55
+ * written with `original`'s formatting wherever the two agree. An element
56
+ * nobody touched comes back byte for byte, comments and all; a moved shape
57
+ * comes back as two changed numbers.
58
+ *
59
+ * Falls back to returning `updated` unchanged whenever it cannot do better:
60
+ * either document failing to parse, a different root element, or an alignment
61
+ * that would produce overlapping edits. The result is then exactly what the
62
+ * caller would have written anyway, so calling this is never worse than not.
63
+ *
64
+ * @param original - The document as it stands.
65
+ * @param updated - The same document as the serializer would write it now.
66
+ * @param options - `siblingOrder` decides what happens to children that appear
67
+ * in both documents in a different order. See {@link SiblingOrder}.
68
+ *
69
+ * @example
70
+ * ```typescript
71
+ * const onDisk = await readFile("order.bpmn", "utf8");
72
+ * const next = preserveFormatting(onDisk, Bpmn.export(edited));
73
+ * // `next` differs from `onDisk` only where `edited` differs from what it held.
74
+ * ```
75
+ */
76
+ export declare function preserveFormatting(original: string, updated: string, options?: PreserveOptions): string;
77
+ /** How a verified preserve turned out, for a caller that wants to know. */
78
+ export interface VerifiedPreserve {
79
+ /** The document to write. */
80
+ readonly xml: string;
81
+ /**
82
+ * Which rung produced it.
83
+ *
84
+ * - `preserved` — the file's own order and formatting were kept.
85
+ * - `reordered` — formatting kept, children reordered as the update wants.
86
+ * Reached when the document really does depend on sibling order.
87
+ * - `rewritten` — the update itself, because neither of the above survived
88
+ * the check. Nothing is lost; the file is simply reformatted.
89
+ */
90
+ readonly outcome: "preserved" | "reordered" | "rewritten";
91
+ }
92
+ /**
93
+ * Preserves as much of `original` as a reader of the document will allow.
94
+ *
95
+ * The choices {@link preserveFormatting} cannot make safely on its own —
96
+ * whether sibling order carries meaning, whether an attribute the update
97
+ * dropped was a schema default — are made here by *trying and checking*. Each
98
+ * candidate is parsed with the caller's own reader and compared against the
99
+ * update; the first that reads the same is used, and the update itself is the
100
+ * floor. So the aggressive strategies are never assumed to be safe for a
101
+ * particular schema, only observed to be safe for a particular document.
102
+ *
103
+ * @param original - The document as it stands.
104
+ * @param updated - The same document as the serializer would write it now.
105
+ * @param read - Parses a document into something comparable with
106
+ * `JSON.stringify`. Anything it cannot parse counts as a failed check.
107
+ */
108
+ export declare function preserveFormattingVerified(original: string, updated: string, read: (xml: string) => unknown): VerifiedPreserve;
109
+ //# sourceMappingURL=xml-patch.d.ts.map
@@ -0,0 +1,459 @@
1
+ /**
2
+ * Rewriting a document in place, so an edit reads as an edit.
3
+ *
4
+ * A serializer given a model produces its own formatting: its indentation, its
5
+ * attribute order, its choice of `
` over `
`. That is correct output
6
+ * and a terrible diff. Move one element in a visual editor and every line of
7
+ * the file changes, so the commit says "the whole diagram" when it means "a box
8
+ * moved forty pixels" — and a reviewer has no way to tell those apart.
9
+ *
10
+ * {@link preserveFormatting} closes that gap without either side having to know
11
+ * about the other. It takes the document as it was and the document as the
12
+ * serializer would write it, and returns a third: the *content* of the second
13
+ * carried by the *bytes* of the first, everywhere the two agree. No model is
14
+ * involved, which is why it serves BPMN, DMN, forms and anything else this
15
+ * toolkit learns to write.
16
+ *
17
+ * @packageDocumentation
18
+ */
19
+ import { escapeAttr, escapeText } from "./xml-parser.js";
20
+ import { parseXmlSpans } from "./xml-spans.js";
21
+ const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
22
+ function isBlank(text) {
23
+ return text.trim() === "";
24
+ }
25
+ /** Offset of the first whitespace character in the run before `offset`. */
26
+ function whitespaceStart(source, offset) {
27
+ let start = offset;
28
+ while (start > 0 && WHITESPACE.has(source[start - 1]))
29
+ start -= 1;
30
+ return start;
31
+ }
32
+ /** The indentation of the line `offset` sits on, when it starts that line. */
33
+ function indentAt(source, offset) {
34
+ const start = whitespaceStart(source, offset);
35
+ const lineStart = source.lastIndexOf("\n", offset - 1) + 1;
36
+ return start <= lineStart ? source.slice(lineStart, offset) : "";
37
+ }
38
+ /**
39
+ * Where a whole attribute begins, walking back from its value.
40
+ *
41
+ * The scanner reports where a *value* sits; removing an attribute needs the
42
+ * name and the `=` and the space in front of them as well, or the document is
43
+ * left holding a stray `foo=` and stops parsing.
44
+ */
45
+ function attributeStart(source, valueStart) {
46
+ // The opening quote, then whitespace, then "=", then whitespace, then the
47
+ // name, then the whitespace separating it from whatever came before.
48
+ let i = valueStart - 1;
49
+ while (i > 0 && WHITESPACE.has(source[i - 1]))
50
+ i -= 1;
51
+ if (source[i - 1] === "=")
52
+ i -= 1;
53
+ while (i > 0 && WHITESPACE.has(source[i - 1]))
54
+ i -= 1;
55
+ while (i > 0 && !WHITESPACE.has(source[i - 1]) && source[i - 1] !== '"')
56
+ i -= 1;
57
+ return whitespaceStart(source, i);
58
+ }
59
+ /** Where a new attribute goes: after the last one, before the tag closes. */
60
+ function attributeInsertPoint(source, element) {
61
+ const close = element.contentStart - (element.selfClosing ? 2 : 1);
62
+ return whitespaceStart(source, close);
63
+ }
64
+ /**
65
+ * A child's identity, for lining up two versions of the same parent.
66
+ *
67
+ * An `id` is the answer whenever there is one, which in BPMN is nearly always.
68
+ * Without one — a `di:waypoint`, a `bpmn:incoming` — the name plus what the
69
+ * element says is enough: two waypoints with the same coordinates really are
70
+ * interchangeable, so pairing them either way round is correct.
71
+ */
72
+ function childKey(element) {
73
+ const id = element.attributes.get("id");
74
+ if (id !== undefined)
75
+ return `#${id.value}`;
76
+ const attributes = [...element.attributes]
77
+ .map(([name, attribute]) => `${name}=${attribute.value}`)
78
+ .sort()
79
+ .join(" ");
80
+ return `${element.name} ${attributes} ${element.text.trim()}`;
81
+ }
82
+ /**
83
+ * Lines up two sequences by longest common subsequence.
84
+ *
85
+ * Returns, for each index in `a`, the index in `b` it pairs with, or -1. An
86
+ * alignment rather than a set of pairs, because reordered children have to come
87
+ * out reordered: matching on keys alone would rewrite each element where it
88
+ * stands and silently keep the old order.
89
+ */
90
+ function align(a, b) {
91
+ const rows = a.length;
92
+ const columns = b.length;
93
+ // A standard LCS table. The sequences are one element's children, so the
94
+ // quadratic cost is bounded by how many children a single element has.
95
+ const table = Array.from({ length: rows + 1 }, () => new Array(columns + 1).fill(0));
96
+ for (let i = rows - 1; i >= 0; i -= 1) {
97
+ for (let j = columns - 1; j >= 0; j -= 1) {
98
+ const row = table[i];
99
+ const next = table[i + 1];
100
+ row[j] =
101
+ a[i] === b[j]
102
+ ? next[j + 1] + 1
103
+ : Math.max(next[j], row[j + 1]);
104
+ }
105
+ }
106
+ const pairing = new Array(rows).fill(-1);
107
+ let i = 0;
108
+ let j = 0;
109
+ while (i < rows && j < columns) {
110
+ if (a[i] === b[j]) {
111
+ pairing[i] = j;
112
+ i += 1;
113
+ j += 1;
114
+ }
115
+ else if ((table[i + 1]?.[j] ?? 0) >= (table[i]?.[j + 1] ?? 0)) {
116
+ i += 1;
117
+ }
118
+ else {
119
+ j += 1;
120
+ }
121
+ }
122
+ return pairing;
123
+ }
124
+ /**
125
+ * Pairs each child with the first unused child of the same key, whatever
126
+ * position it holds.
127
+ *
128
+ * Where {@link align} produces the reordering the two sequences differ by, this
129
+ * produces none: an element that moved is patched where it already stands.
130
+ */
131
+ function matchByKey(a, b) {
132
+ const available = new Map();
133
+ for (const [index, key] of b.entries()) {
134
+ const list = available.get(key);
135
+ if (list === undefined)
136
+ available.set(key, [index]);
137
+ else
138
+ list.push(index);
139
+ }
140
+ return a.map((key) => available.get(key)?.shift() ?? -1);
141
+ }
142
+ /**
143
+ * Pairs up leftovers that share a tag name, in order.
144
+ *
145
+ * The key-based passes above only recognise an element that is *identical* or
146
+ * carries the same `id`. That leaves out an id-less element whose attributes
147
+ * changed — a `dc:Bounds` that moved, a `bpmn:multiInstanceLoopCharacteristics`
148
+ * that lost a flag — and without this those are deleted and written out again,
149
+ * which throws away the formatting of everything inside them. Pairing them
150
+ * turns that back into an attribute edit.
151
+ *
152
+ * A pair where *both* sides carry an `id` is left alone, and that restriction is
153
+ * what keeps this from undoing a deliberate move: two elements with ids that
154
+ * the earlier pass could not put together are two different elements, and one
155
+ * of them really did change position.
156
+ *
157
+ * One side having an id and the other not is a different situation, and pairing
158
+ * them is right. They cannot have been matched by id in the first place, so
159
+ * there is no move to preserve — and it is the everyday case wherever a model
160
+ * does not carry an id the file has. A DMN file names its `DMNDiagram` and
161
+ * `DMNShape`; the model does not; without this the whole diagram section is
162
+ * deleted and written out again on every save.
163
+ *
164
+ * Both lists are walked forward only, so the pairs this adds never cross the
165
+ * ones already made and the resulting edits stay in document order.
166
+ */
167
+ function pairRemainingByName(a, b, pairing) {
168
+ const taken = new Set(pairing.filter((index) => index >= 0));
169
+ let cursor = 0;
170
+ for (const [index, child] of a.entries()) {
171
+ if ((pairing[index] ?? -1) >= 0) {
172
+ // Never pair across an existing match: doing so would reorder edits.
173
+ cursor = Math.max(cursor, pairing[index] + 1);
174
+ continue;
175
+ }
176
+ for (let j = cursor; j < b.length; j += 1) {
177
+ const candidate = b[j];
178
+ if (taken.has(j) || candidate.name !== child.name)
179
+ continue;
180
+ if (child.attributes.has("id") && candidate.attributes.has("id"))
181
+ continue;
182
+ pairing[index] = j;
183
+ taken.add(j);
184
+ cursor = j + 1;
185
+ break;
186
+ }
187
+ }
188
+ }
189
+ /** Everything that has to change inside one matched pair of elements. */
190
+ function diffElement(original, updated, a, b, edits, settings) {
191
+ if (a.name !== b.name) {
192
+ // The pairing put two different elements together — a renamed tag, or an
193
+ // id reused for something else. Neither can be patched attribute by
194
+ // attribute, so the whole element is replaced.
195
+ edits.push({ start: a.start, end: a.end, text: updated.slice(b.start, b.end) });
196
+ return;
197
+ }
198
+ diffAttributes(original, a, b, edits, settings);
199
+ if (a.children.length === 0 && b.children.length === 0) {
200
+ diffText(a, b, edits);
201
+ return;
202
+ }
203
+ diffChildren(original, updated, a, b, edits, settings);
204
+ }
205
+ function diffAttributes(original, a, b, edits, settings) {
206
+ for (const [name, wanted] of b.attributes) {
207
+ const present = a.attributes.get(name);
208
+ if (present === undefined) {
209
+ const at = attributeInsertPoint(original, a);
210
+ edits.push({ start: at, end: at, text: ` ${name}="${escapeAttr(wanted.value)}"` });
211
+ continue;
212
+ }
213
+ // Compare decoded values. `&#10;` and `&#xA;` are the same newline, and
214
+ // rewriting one into the other is a diff that says nothing.
215
+ if (present.value === wanted.value)
216
+ continue;
217
+ edits.push({ start: present.start, end: present.end, text: escapeAttr(wanted.value) });
218
+ }
219
+ if (settings.droppedAttributes === "keep")
220
+ return;
221
+ for (const [name, present] of a.attributes) {
222
+ if (b.attributes.has(name))
223
+ continue;
224
+ edits.push({ start: attributeStart(original, present.start), end: present.end + 1, text: "" });
225
+ }
226
+ }
227
+ function diffText(a, b, edits) {
228
+ if (a.text === b.text)
229
+ return;
230
+ // Whitespace-only content on both sides is formatting, not content: an
231
+ // element pretty-printed as `<a>\n</a>` says exactly what `<a></a>` says.
232
+ if (isBlank(a.text) && isBlank(b.text))
233
+ return;
234
+ // There is nothing to replace inside a self-closing tag, so an element that
235
+ // gains content has to be written out again.
236
+ if (a.selfClosing) {
237
+ edits.push({
238
+ start: a.start,
239
+ end: a.end,
240
+ text: `<${a.name}${attributesOf(a, b)}>${escapeText(b.text)}</${a.name}>`,
241
+ });
242
+ return;
243
+ }
244
+ edits.push({ start: a.contentStart, end: a.contentEnd, text: escapeText(b.text) });
245
+ }
246
+ /**
247
+ * The attribute list for an element being written out again.
248
+ *
249
+ * Takes `b`'s values in `a`'s order, so an element that has to be regenerated
250
+ * still comes out looking as much like the original as it can.
251
+ */
252
+ function attributesOf(a, b) {
253
+ const parts = [];
254
+ for (const [name] of a.attributes) {
255
+ const wanted = b.attributes.get(name);
256
+ if (wanted !== undefined)
257
+ parts.push(` ${name}="${escapeAttr(wanted.value)}"`);
258
+ }
259
+ for (const [name, wanted] of b.attributes) {
260
+ if (!a.attributes.has(name))
261
+ parts.push(` ${name}="${escapeAttr(wanted.value)}"`);
262
+ }
263
+ return parts.join("");
264
+ }
265
+ function diffChildren(original, updated, a, b, edits, settings) {
266
+ const aKeys = a.children.map(childKey);
267
+ const bKeys = b.children.map(childKey);
268
+ const pairing = settings.siblingOrder === "keep" ? matchByKey(aKeys, bKeys) : align(aKeys, bKeys);
269
+ pairRemainingByName(a.children, b.children, pairing);
270
+ const matchedInB = new Set(pairing.filter((index) => index >= 0));
271
+ // What indentation new children should take: whatever the existing ones use,
272
+ // and failing that one step in from the parent.
273
+ const sample = a.children[0];
274
+ const indent = sample === undefined
275
+ ? `${indentAt(original, a.start)}${indentUnit(original)}`
276
+ : indentAt(original, sample.start);
277
+ for (const [index, child] of a.children.entries()) {
278
+ const match = pairing[index] ?? -1;
279
+ if (match < 0) {
280
+ // Take the whitespace that put the child on its own line with it;
281
+ // anything else between siblings — a comment — stays where it is.
282
+ edits.push({ start: whitespaceStart(original, child.start), end: child.end, text: "" });
283
+ continue;
284
+ }
285
+ diffElement(original, updated, child, b.children[match], edits, settings);
286
+ }
287
+ for (const [index, child] of b.children.entries()) {
288
+ if (matchedInB.has(index))
289
+ continue;
290
+ const at = insertionPoint(original, a, pairing, b, index);
291
+ const written = reindent(updated.slice(child.start, child.end), indentAt(updated, child.start), indent, indentUnit(updated), indentUnit(original));
292
+ edits.push({ start: at, end: at, text: `\n${indent}${written}` });
293
+ }
294
+ }
295
+ /** Where a new child belongs in the original text. */
296
+ function insertionPoint(original, a, pairing, b, index) {
297
+ // Straight after the original sibling paired with the nearest kept child
298
+ // before it.
299
+ for (let before = index - 1; before >= 0; before -= 1) {
300
+ const inA = pairing.indexOf(before);
301
+ if (inA >= 0)
302
+ return a.children[inA].end;
303
+ }
304
+ // Nothing kept before it, so in front of the first surviving child — or at
305
+ // the end of the parent's content, when none survive.
306
+ for (let after = index + 1; after < b.children.length; after += 1) {
307
+ const inA = pairing.indexOf(after);
308
+ if (inA >= 0)
309
+ return whitespaceStart(original, a.children[inA].start);
310
+ }
311
+ return whitespaceStart(original, a.contentEnd);
312
+ }
313
+ /** The document's own indentation step, read from its first indented line. */
314
+ function indentUnit(source) {
315
+ const match = /\n([ \t]+)\S/.exec(source);
316
+ return match?.[1] ?? " ";
317
+ }
318
+ /**
319
+ * Re-indents a block written at one depth so it sits at another.
320
+ *
321
+ * By depth, not by string replacement: the two documents may not indent with
322
+ * the same characters at all, and a block moved from a two-space update into a
323
+ * tab-indented file has to have its *inner* lines converted too, or it arrives
324
+ * with tabs outside and spaces inside.
325
+ */
326
+ function reindent(text, from, to, fromUnit, toUnit) {
327
+ if (from === to && fromUnit === toUnit)
328
+ return text;
329
+ const lines = text.split("\n");
330
+ return lines
331
+ .map((line, index) => {
332
+ if (index === 0)
333
+ return line;
334
+ const body = line.trimStart();
335
+ const indent = line.slice(0, line.length - body.length);
336
+ if (!indent.startsWith(from))
337
+ return line;
338
+ const deeper = indent.slice(from.length);
339
+ const depth = fromUnit === "" ? 0 : Math.floor(deeper.length / fromUnit.length);
340
+ return `${to}${toUnit.repeat(depth)}${body}`;
341
+ })
342
+ .join("\n");
343
+ }
344
+ /** Applies edits to the source, refusing any pair that overlaps. */
345
+ function applyEdits(source, edits) {
346
+ const ordered = [...edits].sort((x, y) => x.start - y.start || x.end - y.end);
347
+ const parts = [];
348
+ let cursor = 0;
349
+ for (const edit of ordered) {
350
+ if (edit.start < cursor) {
351
+ // Two edits claiming the same characters mean the walk paired one
352
+ // element with two, and the result would be nonsense. Refuse to produce
353
+ // it; the caller falls back to the plain serialization.
354
+ throw new Error("overlapping edits");
355
+ }
356
+ parts.push(source.slice(cursor, edit.start), edit.text);
357
+ cursor = edit.end;
358
+ }
359
+ parts.push(source.slice(cursor));
360
+ return parts.join("");
361
+ }
362
+ /**
363
+ * Rewrites `original` to say what `updated` says, changing as little as it can.
364
+ *
365
+ * The result is `updated`'s document — the same elements, attributes and text —
366
+ * written with `original`'s formatting wherever the two agree. An element
367
+ * nobody touched comes back byte for byte, comments and all; a moved shape
368
+ * comes back as two changed numbers.
369
+ *
370
+ * Falls back to returning `updated` unchanged whenever it cannot do better:
371
+ * either document failing to parse, a different root element, or an alignment
372
+ * that would produce overlapping edits. The result is then exactly what the
373
+ * caller would have written anyway, so calling this is never worse than not.
374
+ *
375
+ * @param original - The document as it stands.
376
+ * @param updated - The same document as the serializer would write it now.
377
+ * @param options - `siblingOrder` decides what happens to children that appear
378
+ * in both documents in a different order. See {@link SiblingOrder}.
379
+ *
380
+ * @example
381
+ * ```typescript
382
+ * const onDisk = await readFile("order.bpmn", "utf8");
383
+ * const next = preserveFormatting(onDisk, Bpmn.export(edited));
384
+ * // `next` differs from `onDisk` only where `edited` differs from what it held.
385
+ * ```
386
+ */
387
+ export function preserveFormatting(original, updated, options = {}) {
388
+ let before;
389
+ let after;
390
+ try {
391
+ before = parseXmlSpans(original);
392
+ after = parseXmlSpans(updated);
393
+ }
394
+ catch {
395
+ return updated;
396
+ }
397
+ if (before.name !== after.name)
398
+ return updated;
399
+ try {
400
+ const edits = [];
401
+ diffElement(original, updated, before, after, edits, {
402
+ siblingOrder: options.siblingOrder ?? "follow",
403
+ droppedAttributes: options.droppedAttributes ?? "remove",
404
+ });
405
+ if (edits.length === 0)
406
+ return original;
407
+ return applyEdits(original, edits);
408
+ }
409
+ catch {
410
+ return updated;
411
+ }
412
+ }
413
+ /**
414
+ * Preserves as much of `original` as a reader of the document will allow.
415
+ *
416
+ * The choices {@link preserveFormatting} cannot make safely on its own —
417
+ * whether sibling order carries meaning, whether an attribute the update
418
+ * dropped was a schema default — are made here by *trying and checking*. Each
419
+ * candidate is parsed with the caller's own reader and compared against the
420
+ * update; the first that reads the same is used, and the update itself is the
421
+ * floor. So the aggressive strategies are never assumed to be safe for a
422
+ * particular schema, only observed to be safe for a particular document.
423
+ *
424
+ * @param original - The document as it stands.
425
+ * @param updated - The same document as the serializer would write it now.
426
+ * @param read - Parses a document into something comparable with
427
+ * `JSON.stringify`. Anything it cannot parse counts as a failed check.
428
+ */
429
+ export function preserveFormattingVerified(original, updated, read) {
430
+ let wanted;
431
+ try {
432
+ wanted = JSON.stringify(read(updated));
433
+ }
434
+ catch {
435
+ return { xml: updated, outcome: "rewritten" };
436
+ }
437
+ // Most to least faithful to the file.
438
+ const attempts = [
439
+ ["preserved", { siblingOrder: "keep", droppedAttributes: "keep" }],
440
+ ["preserved", { siblingOrder: "keep" }],
441
+ ["reordered", { siblingOrder: "follow" }],
442
+ ];
443
+ for (const [outcome, options] of attempts) {
444
+ const candidate = preserveFormatting(original, updated, options);
445
+ // `preserveFormatting` returns the update when it cannot do better, which
446
+ // needs no checking: it is the floor already.
447
+ if (candidate === updated)
448
+ continue;
449
+ try {
450
+ if (JSON.stringify(read(candidate)) === wanted)
451
+ return { xml: candidate, outcome };
452
+ }
453
+ catch {
454
+ // A candidate that will not parse is simply not a candidate.
455
+ }
456
+ }
457
+ return { xml: updated, outcome: "rewritten" };
458
+ }
459
+ //# sourceMappingURL=xml-patch.js.map
@@ -0,0 +1,45 @@
1
+ /**
2
+ * An XML document parsed into a tree that remembers where everything was.
3
+ *
4
+ * `parseXml` builds a clean tree with the source thrown away, which is right
5
+ * for everything that reads a document. Rewriting one in place needs the
6
+ * opposite: the exact offsets of each tag and each attribute value, so an edit
7
+ * can replace four characters instead of regenerating the file.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ /** An attribute, and where its value sits between the quotes. */
12
+ export interface SpannedAttribute {
13
+ /** The value with entities decoded — what a comparison should use. */
14
+ readonly value: string;
15
+ /** Offset of the first character of the value, inside the quotes. */
16
+ readonly start: number;
17
+ /** Offset just past the last character of the value. */
18
+ readonly end: number;
19
+ }
20
+ /** An element, and where it was written. */
21
+ export interface SpannedElement {
22
+ /** Qualified name, e.g. `bpmn:serviceTask`. */
23
+ readonly name: string;
24
+ readonly attributes: Map<string, SpannedAttribute>;
25
+ readonly children: SpannedElement[];
26
+ /** Character data directly inside, entities decoded, concatenated. */
27
+ text: string;
28
+ /** Offset of the `<` opening the start tag. */
29
+ readonly start: number;
30
+ /** Offset just past the `>` closing the whole element. */
31
+ end: number;
32
+ /** Offset just past the `>` closing the start tag. */
33
+ readonly contentStart: number;
34
+ /** Offset of the `<` opening the end tag; equals {@link end} when self-closing. */
35
+ contentEnd: number;
36
+ readonly selfClosing: boolean;
37
+ }
38
+ /**
39
+ * Parses a document into a tree that knows its own offsets.
40
+ *
41
+ * @param xml - A well-formed XML document.
42
+ * @throws Error when there is no root element, or the document is malformed.
43
+ */
44
+ export declare function parseXmlSpans(xml: string): SpannedElement;
45
+ //# sourceMappingURL=xml-spans.d.ts.map
@@ -0,0 +1,74 @@
1
+ /**
2
+ * An XML document parsed into a tree that remembers where everything was.
3
+ *
4
+ * `parseXml` builds a clean tree with the source thrown away, which is right
5
+ * for everything that reads a document. Rewriting one in place needs the
6
+ * opposite: the exact offsets of each tag and each attribute value, so an edit
7
+ * can replace four characters instead of regenerating the file.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ import { Visit, scanXml } from "./xml-parser.js";
12
+ class SpanBuilder {
13
+ root;
14
+ position;
15
+ stack = [];
16
+ cursor(cursor) {
17
+ this.position = cursor;
18
+ }
19
+ start(name, _local, attributes, selfClosing) {
20
+ const spans = new Map();
21
+ for (const [key, value] of Object.entries(attributes)) {
22
+ const span = this.position.attributeSpan(key);
23
+ // A span is always there for an attribute the scanner just read; the
24
+ // fallback keeps the tree usable rather than asserting about it.
25
+ spans.set(key, {
26
+ value,
27
+ start: span?.start ?? this.position.tagStart,
28
+ end: span?.end ?? this.position.tagStart,
29
+ });
30
+ }
31
+ const element = {
32
+ name,
33
+ attributes: spans,
34
+ children: [],
35
+ text: "",
36
+ start: this.position.tagStart,
37
+ end: this.position.tagEnd,
38
+ contentStart: this.position.tagEnd,
39
+ contentEnd: this.position.tagEnd,
40
+ selfClosing,
41
+ };
42
+ this.stack[this.stack.length - 1]?.children.push(element);
43
+ if (this.root === undefined)
44
+ this.root = element;
45
+ this.stack.push(element);
46
+ return Visit.All;
47
+ }
48
+ text(text) {
49
+ const element = this.stack[this.stack.length - 1];
50
+ if (element !== undefined)
51
+ element.text += text;
52
+ }
53
+ end() {
54
+ const element = this.stack.pop();
55
+ if (element === undefined)
56
+ return;
57
+ element.contentEnd = this.position.endTagStart;
58
+ element.end = this.position.endTagEnd;
59
+ }
60
+ }
61
+ /**
62
+ * Parses a document into a tree that knows its own offsets.
63
+ *
64
+ * @param xml - A well-formed XML document.
65
+ * @throws Error when there is no root element, or the document is malformed.
66
+ */
67
+ export function parseXmlSpans(xml) {
68
+ const builder = new SpanBuilder();
69
+ if (!scanXml(xml, builder) || builder.root === undefined) {
70
+ throw new Error("Failed to parse XML: no root element found");
71
+ }
72
+ return builder.root;
73
+ }
74
+ //# sourceMappingURL=xml-spans.js.map