@miragon/event-storming-dsl 0.2.2 → 0.3.0

package/dist/index.js

@@ -5,12 +5,19 @@ export { parseBoardJSON as boardFromJSON, serializeBoard as boardToJSON, loadBoa
 
 // src/lexer.ts
 var COORDS_RE = /\[\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\]/;
+var LARGEST_DRAWABLE_NUMBER = 1e38;
+function isDrawable(value) {
+  return Math.abs(value) <= LARGEST_DRAWABLE_NUMBER;
+}
+function drawablePair(a, b) {
+  return isDrawable(a) && isDrawable(b);
+}
 function parseCoords(line) {
   const m = COORDS_RE.exec(line);
   if (!m) return null;
   const a = Number(m[1]);
   const b = Number(m[2]);
-  if (Number.isNaN(a) || Number.isNaN(b)) return null;
+  if (!drawablePair(a, b)) return null;
   return { a, b };
 }
 function splitAtCoords(line) {
@@ -18,7 +25,7 @@ function splitAtCoords(line) {
   if (!m) return null;
   const a = Number(m[1]);
   const b = Number(m[2]);
-  if (Number.isNaN(a) || Number.isNaN(b)) return null;
+  if (!drawablePair(a, b)) return null;
   return {
     name: line.slice(0, m.index).trim(),
     coords: { a, b },
@@ -35,7 +42,8 @@ function parseMultiCoords(line) {
   while (t = inner.exec(m[1])) {
     const a = Number(t[1]);
     const b = Number(t[2]);
-    if (!Number.isNaN(a) && !Number.isNaN(b)) tuples.push({ a, b });
+    if (!drawablePair(a, b)) return null;
+    tuples.push({ a, b });
   }
   if (!tuples.length) return null;
   return { tuples, rest: line.replace(MULTI_COORDS_RE, " ") };
@@ -97,7 +105,7 @@ function parseSize(line) {
   if (m) {
     const width = Number(m[1]);
     const height = Number(m[2]);
-    if (width > 0 && height > 0) {
+    if (width > 0 && height > 0 && isDrawable(width) && isDrawable(height)) {
       return { size: { width, height }, rest: line.replace(SIZE_RE, " ") };
     }
   }
@@ -122,6 +130,9 @@ function parseAlign(line) {
   if (!p) return { rest: line };
   return { invalid: p[0], rest: line.replace(ALIGN_PRESENT_RE, " ") };
 }
+function decodeName(name) {
+  return name.replace(/\\n/g, "\n");
+}
 function keywordOf(line) {
   const m = /^\s*([A-Za-z][\w-]*)/.exec(line);
   return m ? m[1].toLowerCase() : "";
@@ -130,6 +141,44 @@ function slug(label) {
   return label.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_/, "").replace(/_$/, "") || "x";
 }
 
+// src/ids.ts
+var STICKY_ID_PREFIXES = {
+  event: "event",
+  command: "cmd",
+  actor: "actor",
+  aggregate: "agg",
+  policy: "policy",
+  readmodel: "read",
+  external: "ext",
+  hotspot: "hot"
+};
+var ENGINE_ID_RE = /^(?:event-storming-root$|__implicitroot)/;
+function isEngineId(id) {
+  return ENGINE_ID_RE.test(id);
+}
+var IdAllocator = class {
+  used = /* @__PURE__ */ new Set();
+  /** Explicit `(id …)` — false when the id is taken or reserved (caller reports + allocates). */
+  claim(id) {
+    if (this.used.has(id) || isEngineId(id)) return false;
+    this.used.add(id);
+    return true;
+  }
+  /** The id `alloc(prefix, label)` would return, without taking it. */
+  peek(prefix, label) {
+    const base = `${prefix}_${slug(label)}`;
+    let id = base;
+    let i = 2;
+    while (this.used.has(id)) id = `${base}_${i++}`;
+    return id;
+  }
+  alloc(prefix, label) {
+    const id = this.peek(prefix, label);
+    this.used.add(id);
+    return id;
+  }
+};
+
 // src/parser.ts
 function splitArrow(core) {
   const arrow = core.indexOf("->");
@@ -142,19 +191,6 @@ var KNOWN_STYLES = /* @__PURE__ */ new Set(["classic", "dark"]);
 var ATTACHABLE_KINDS = new Set(ATTACHABLE_STICKY_KINDS);
 var HOST_KINDS = new Set(HOST_STICKY_KINDS);
 var KNOWN_LEVELS = /* @__PURE__ */ new Set(["big-picture", "process", "design"]);
-function decodeName(name) {
-  return name.replace(/\\n/g, "\n");
-}
-var STICKY_ID_PREFIXES = {
-  event: "event",
-  command: "cmd",
-  actor: "actor",
-  aggregate: "agg",
-  policy: "policy",
-  readmodel: "read",
-  external: "ext",
-  hotspot: "hot"
-};
 var STICKY_KINDS = new Set(Object.keys(STICKY_ID_PREFIXES));
 function compact(obj) {
   const out = {};
@@ -169,23 +205,6 @@ function modelAlign(align) {
   });
   return Object.keys(out).length ? out : void 0;
 }
-var IdAllocator = class {
-  used = /* @__PURE__ */ new Set();
-  /** Explicit `(id …)` — false when the id is already taken (caller reports + allocates). */
-  claim(id) {
-    if (this.used.has(id)) return false;
-    this.used.add(id);
-    return true;
-  }
-  alloc(prefix, label) {
-    const base = `${prefix}_${slug(label)}`;
-    let id = base;
-    let i = 2;
-    while (this.used.has(id)) id = `${base}_${i++}`;
-    this.used.add(id);
-    return id;
-  }
-};
 function parseDSL(text) {
   return parseDSLWithDiagnostics(text).board;
 }
@@ -222,12 +241,13 @@ function parseDSLWithDiagnostics(text) {
   const diag = (message, atLine = lineNo, text_ = currentLine) => diagnostics.push({ line: atLine, message, text: text_ });
   const failed = (l) => {
     rawPassthrough.push(l);
-    diag("Line could not be interpreted (kept losslessly in rawPassthrough)");
+    diag("Couldn't read this line. It stays in the file unchanged.");
   };
   const pos = (x, y) => ({ x, y });
   const sourceLines = text.split(/\r?\n/);
   for (let i = 0; i < sourceLines.length; i++) {
     const raw = sourceLines[i];
+    if (raw === "" && i === sourceLines.length - 1) continue;
     lineNo = i + 1;
     currentLine = raw.trim();
     let working = raw;
@@ -301,12 +321,14 @@ function parseDSLWithDiagnostics(text) {
         }
         if (node.idInvalid) {
           diag(
-            `Id: could not read "${node.idInvalid.trim()}" \u2014 expected (id <id>) with letters, digits, '_' or '-'`
+            `Couldn't read the id \u201C${node.idInvalid.trim()}\u201D. An id has letters, digits, \u201C_\u201D or \u201C-\u201D, as in (id order_1).`
           );
         }
         const explicit = node.id !== void 0 && ids.claim(node.id) ? node.id : void 0;
         if (node.id !== void 0 && explicit === void 0) {
-          diag(`Id: "${node.id}" is already taken \u2014 the element got a fresh id`);
+          diag(
+            isEngineId(node.id) ? `The id \u201C${node.id}\u201D belongs to the board itself, so this sticky got a new id.` : `The id \u201C${node.id}\u201D is already taken, so this sticky got a new id.`
+          );
         }
         const id = explicit ?? ids.alloc(STICKY_ID_PREFIXES[kw], node.name);
         elements.push(
@@ -328,14 +350,14 @@ function parseDSLWithDiagnostics(text) {
               lineNo
             });
           } else {
-            diag(`Attachment: a ${kw} cannot be pinned \u2014 only actor/hotspot/note support (on \u2026)`);
+            diag(`A ${kw} can't be pinned. Only an actor, a hotspot or a note takes (on \u2026).`);
           }
         }
         if (node.sizeSuffix) {
-          diag(`Size: a ${kw} cannot be resized \u2014 only notes support (size \u2026)`);
+          diag(`A ${kw} can't be resized. Only a note takes (size \u2026).`);
         }
         if (node.alignSuffix) {
-          diag(`Align: a ${kw} cannot be aligned \u2014 only notes support (align \u2026)`);
+          diag(`A ${kw} can't be aligned. Only a note takes (align \u2026).`);
         }
         break;
       }
@@ -352,16 +374,16 @@ function parseDSLWithDiagnostics(text) {
         const col = parseColor(idp.rest);
         if (al.invalid) {
           diag(
-            `Align: could not read "${al.invalid.trim()}" \u2014 expected (align left|center|right top|middle|bottom)`
+            `Couldn't read the alignment \u201C${al.invalid.trim()}\u201D. Write (align left|center|right top|middle|bottom).`
           );
         }
         if (sz.invalid) {
           diag(
-            `Size: could not read "${sz.invalid.trim()}" \u2014 expected (size <w>x<h>) with positive numbers`
+            `Couldn't read the size \u201C${sz.invalid.trim()}\u201D. Write (size <w>x<h>) with positive numbers.`
           );
         }
         if (idp.id !== void 0 || idp.invalid) {
-          diag("Id: a note cannot be referenced \u2014 only sticky kinds support (id \u2026)");
+          diag("A note can't have an id. Only a sticky takes (id \u2026).");
         }
         const textPart = decodeName((split ? split.name : col.rest).trim());
         const id = ids.alloc("note", textPart || "note");
@@ -389,19 +411,19 @@ function parseDSLWithDiagnostics(text) {
         }
         const onDrawing = parseOn(multi.rest);
         if (onDrawing.host !== void 0) {
-          diag("Attachment: a drawing cannot be pinned \u2014 only actor/hotspot/note support (on \u2026)");
+          diag("A drawing can't be pinned. Only an actor, a hotspot or a note takes (on \u2026).");
         }
         const szDrawing = parseSize(onDrawing.rest);
         if (szDrawing.size || szDrawing.invalid) {
-          diag("Size: a drawing cannot be resized \u2014 only notes support (size \u2026)");
+          diag("A drawing can't be resized. Only a note takes (size \u2026).");
         }
         const alDrawing = parseAlign(onDrawing.rest);
         if (alDrawing.align || alDrawing.invalid) {
-          diag("Align: a drawing cannot be aligned \u2014 only notes support (align \u2026)");
+          diag("A drawing can't be aligned. Only a note takes (align \u2026).");
         }
         const idDrawing = parseId(onDrawing.rest);
         if (idDrawing.id !== void 0 || idDrawing.invalid) {
-          diag("Id: a drawing cannot be referenced \u2014 only sticky kinds support (id \u2026)");
+          diag("A drawing can't have an id. Only a sticky takes (id \u2026).");
         }
         const flags = onDrawing.rest.toLowerCase();
         const strokeStyle = flags.includes("(dashed)") ? "dashed" : flags.includes("(dotted)") ? "dotted" : void 0;
@@ -435,12 +457,12 @@ function parseDSLWithDiagnostics(text) {
   for (const att of pendingAttachments) {
     const host = resolve(att.host);
     if (!host) {
-      diag(`Attachment: "${att.host}" not found`, att.lineNo, att.raw);
+      diag(`There's no \u201C${att.host}\u201D on the board to pin this to.`, att.lineNo, att.raw);
       continue;
     }
     if (!HOST_KINDS.has(host.elementType)) {
       diag(
-        `Attachment: "${att.host}" is a ${host.elementType} \u2014 actors/hotspots/notes may only attach to host stickies`,
+        `\u201C${att.host}\u201D is a ${host.elementType}. An actor, a hotspot or a note is pinned to an event, a command, an aggregate, a policy, a read model or an external system.`,
         att.lineNo,
         att.raw
       );
@@ -462,7 +484,7 @@ function parseDSLWithDiagnostics(text) {
     if (!from || !to) {
       rawPassthrough.push(arrow.raw);
       diag(
-        `Arrow: ${!from ? `"${arrow.left}"` : `"${arrow.right}"`} not found`,
+        !from ? `This arrow starts at \u201C${arrow.left}\u201D, which isn't on the board.` : `This arrow points to \u201C${arrow.right}\u201D, which isn't on the board.`,
         arrow.lineNo,
         arrow.raw
       );
@@ -472,7 +494,7 @@ function parseDSLWithDiagnostics(text) {
     if (nonSticky) {
       rawPassthrough.push(arrow.raw);
       diag(
-        `Arrow: "${nonSticky[0]}" is a ${nonSticky[1].elementType} \u2014 arrows may only connect stickies`,
+        `\u201C${nonSticky[0]}\u201D is a ${nonSticky[1].elementType}, and an arrow only connects stickies.`,
         arrow.lineNo,
         arrow.raw
       );
@@ -593,21 +615,22 @@ function serializeDSL(board) {
   const nameOf = (el) => names.get(el.id) ?? el.label;
   const nameCount = /* @__PURE__ */ new Map();
   for (const name of names.values()) nameCount.set(name, (nameCount.get(name) ?? 0) + 1);
-  const needsId = (id) => {
+  const referencedById = (id) => {
     const name = names.get(id);
     return name !== void 0 && (nameCount.get(name) > 1 || name.startsWith("#"));
   };
   const emitIds = /* @__PURE__ */ new Map();
   const taken = new Set(board.elements.map((e) => e.id));
   for (const el of board.elements) {
-    if (!needsId(el.id) || ID_CHARSET_RE.test(el.id)) continue;
+    if (!referencedById(el.id) || ID_CHARSET_RE.test(el.id)) continue;
     let candidate = slug(el.id);
     for (let i = 2; taken.has(candidate); i++) candidate = `${slug(el.id)}_${i}`;
     taken.add(candidate);
     emitIds.set(el.id, candidate);
   }
   const idOf = (id) => emitIds.get(id) ?? id;
-  const ref = (id) => needsId(id) ? `#${idOf(id)}` : names.get(id) ?? id;
+  const declaredIds = idsToDeclare(board, nameOf, referencedById, idOf);
+  const ref = (id) => referencedById(id) ? `#${idOf(id)}` : names.get(id) ?? id;
   lines.push(`title ${board.config.title}`);
   if (board.config.style) lines.push(`style ${board.config.style}`);
   if (board.config.level) lines.push(`level ${board.config.level}`);
@@ -616,7 +639,7 @@ function serializeDSL(board) {
     return hostId ? ` (on ${ref(hostId)})` : "";
   };
   for (const el of board.elements) {
-    const idSuffix = needsId(el.id) ? ` (id ${idOf(el.id)})` : "";
+    const idSuffix = declaredIds.has(el.id) ? ` (id ${idOf(el.id)})` : "";
     lines.push(elementLine(el, nameOf(el), idSuffix, onSuffix(el)));
   }
   for (const edge of board.edges) {
@@ -634,6 +657,30 @@ function serializeDSL(board) {
   }
   return lines.join("\n") + "\n";
 }
+function idsToDeclare(board, nameOf, referencedById, emittedId) {
+  const allocator = new IdAllocator();
+  const declared = /* @__PURE__ */ new Set();
+  for (const el of board.elements) {
+    const prefix = STICKY_ID_PREFIXES[el.elementType];
+    if (prefix === void 0) {
+      allocator.alloc(el.elementType === "note" ? "note" : "draw", noteOrDrawingName(el));
+      continue;
+    }
+    const parsedName = decodeName(nameOf(el));
+    const declare = referencedById(el.id) || ID_CHARSET_RE.test(el.id) && allocator.peek(prefix, parsedName) !== el.id;
+    if (declare) {
+      declared.add(el.id);
+      allocator.claim(emittedId(el.id));
+    } else {
+      allocator.alloc(prefix, parsedName);
+    }
+  }
+  return declared;
+}
+function noteOrDrawingName(el) {
+  if (el.elementType === "drawing") return "line";
+  return decodeName(escapeText(el.label)) || "note";
+}
 function elementLine(el, name, idSuffix, attach) {
   const p = el.position;
   switch (el.elementType) {