@miragon/wardley-dsl 0.6.0 → 0.7.1

package/README.md

@@ -1,10 +1,10 @@
 # @miragon/wardley-dsl
 
 [![npm](https://img.shields.io/npm/v/@miragon/wardley-dsl)](https://www.npmjs.com/package/@miragon/wardley-dsl)
-[![License: MIT](https://img.shields.io/github/license/Miragon/wardley-maps-modeler)](https://github.com/Miragon/wardley-maps-modeler/blob/main/LICENSE)
+[![License: MIT](https://img.shields.io/github/license/Miragon/modeler-suite)](https://github.com/Miragon/modeler-suite/blob/main/modelers/wardley-maps/LICENSE)
 
 DOM-free bridge between the [Online-Wardley-Maps](https://docs.onlinewardleymaps.com/) text DSL and
-the `WardleyMap` model — a lossless round-trip.
+the `WardleyMap` model, as a lossless round-trip.
 
 ## Install
 
@@ -15,7 +15,7 @@ npm install @miragon/wardley-dsl
 ## Usage
 
 ```ts
-import { parseDSL, serializeDSL } from '@miragon/wardley-dsl';
+import { parseDSL, serializeDSL } from "@miragon/wardley-dsl";
 
 const map = parseDSL(`title Tea Shop
 component Kettle [0.43, 0.35]
@@ -31,7 +31,7 @@ the end, numbers like `0.80` as `0.8`. Where the text file is the source of trut
 file under Git), write an edited map back with `patchDSL` instead:
 
 ```ts
-import { parseDSL, patchDSL } from '@miragon/wardley-dsl';
+import { parseDSL, patchDSL } from "@miragon/wardley-dsl";
 
 const map = parseDSL(fileText);
 // … the user moves, renames, adds or deletes something …
@@ -49,7 +49,20 @@ The result always reads back as the same map as `serializeDSL(map)`. When an edi
 safely into the source layout, `patchDSL` falls back to the canonical `serializeDSL(map)` text (in
 the source's line break style). It never throws.
 
-Part of the [Wardley Maps](https://github.com/Miragon/wardley-maps-modeler) monorepo.
+### Ids in the document
+
+The OWM DSL writes no ids: the parser derives them from names (`cmp_cup_of_tea`), note texts and
+annotation numbers, with a `_2` suffix for a repeat in line order. An editor that creates or renames
+an element holds an id the text does not give it until the text is read again. `readBackIds(map)`
+tells, by the ids of `map`, which id each element carries once `serializeDSL(map)` is read back:
+
+```ts
+import { readBackIds } from "@miragon/wardley-dsl";
+
+readBackIds(editedMap).get("shape_42"); // 'cmp_hot_water'
+```
+
+Part of the [Wardley Maps Modeler](https://github.com/Miragon/modeler-suite/tree/main/modelers/wardley-maps) in the [Miragon modeler suite](https://github.com/Miragon/modeler-suite).
 
 ## License
 

package/dist/index.cjs

@@ -465,7 +465,7 @@ function unknownStatementMessage(line) {
   const core = linkCore(line);
   if (/->|\+('[^']*')?(<>|>|<)/.test(core)) return "Link needs a name on both sides";
   const flowValue = /\+'[^']*'/.exec(core);
-  if (flowValue) return `Flow ${flowValue[0]} has no direction \u2014 add ">", "<" or "<>"`;
+  if (flowValue) return `Flow ${flowValue[0]} has no direction: add ">", "<" or "<>"`;
   return `Unknown statement "${line.split(/\s/)[0]}"`;
 }
 function buildEdges(links, idOfName, unresolved, labelOf, built) {
@@ -595,7 +595,7 @@ var MapReader = class {
   }
   /** For a line that looks like a known construct but cannot be parsed. */
   failed(line) {
-    this.keep(line, "Line could not be interpreted (kept losslessly in rawPassthrough)");
+    this.keep(line, "Line not understood: kept as written");
   }
   // A reference binds to the name as written first, so `X 2` stays bound to an explicit "X 2" even
   // when a duplicate "X" was renamed to "X 2"; the serializer then writes that reference by the
@@ -610,7 +610,7 @@ var MapReader = class {
   setConfig(keyword, update) {
     const earlier = this.lineThatSetConfig.get(keyword);
     if (earlier !== void 0) {
-      this.diag(`Repeated "${keyword}" \u2014 replaces the one on line ${earlier}`);
+      this.diag(`Repeated "${keyword}": replaces the one on line ${earlier}`);
     }
     this.lineThatSetConfig.set(keyword, this.lineNo);
     const configLines2 = this.configLinesByKeyword.get(keyword) ?? [];
@@ -648,7 +648,7 @@ var MapReader = class {
       return true;
     }
     this.keywordLinks.push(link);
-    if (leftDeclared) this.diag(`Link: "${link.right}" not found \u2014 read as a "${kw}" statement`);
+    if (leftDeclared) this.diag(`Link: "${link.right}" not found; read as a "${kw}" statement`);
     return false;
   }
   /** Clamps a normalized value to [0,1] — with a diagnostic instead of a later validation crash. */
@@ -664,7 +664,7 @@ var MapReader = class {
   }
   /** A suffix written in front of the coordinates is part of the name or text (OWM). */
   reportMisplacedSuffix(groups, where, fix) {
-    if (groups.length) this.diag(`"${groups.join(" ")}" ${where} \u2014 ${fix}`);
+    if (groups.length) this.diag(`"${groups.join(" ")}" ${where}: ${fix}`);
   }
   /**
    * A text as the serializer writes it. Its comment markers are protected only by flow values
@@ -675,7 +675,7 @@ var MapReader = class {
     const written = escapeCommentMarkers(text);
     if (written !== text) {
       this.diag(
-        `"${text}" read as "${written}" \u2014 "//" or "/*" there would start a comment once saved`,
+        `"${text}" read as "${written}", because "//" or "/*" there would start a comment once saved`,
         line,
         source
       );
@@ -688,7 +688,7 @@ var MapReader = class {
     const name = this.namesInUse.claim(base);
     if (name !== base) {
       this.diag(
-        `Duplicate name "${sourceName}" \u2014 renamed to "${name}"; links bind to the first "${sourceName}"`,
+        `Duplicate name "${sourceName}": renamed to "${name}"; links bind to the first "${sourceName}"`,
         atLine,
         atText
       );
@@ -702,20 +702,20 @@ var MapReader = class {
       this.blockPipeline = this.lastPipeline;
       this.recordBlockLine(this.blockPipeline, "open");
       this.blockOpening = { line: this.lineNo, text: this.currentLine };
-    } else this.diag('Ignored "{" \u2014 a block must directly follow a pipeline line');
+    } else this.diag('Ignored "{": a block must directly follow a pipeline line');
     this.lastPipeline = null;
   }
   closeBlock() {
     if (this.blockPipeline) {
       this.recordBlockLine(this.blockPipeline, "close");
       this.blockPipeline = null;
-    } else this.diag('Ignored "}" \u2014 no pipeline block is open');
+    } else this.diag('Ignored "}": no pipeline block is open');
     this.lastPipeline = null;
   }
   endUnclosedBlock() {
     if (!this.blockPipeline) return;
     this.diag(
-      `Pipeline block of "${this.blockPipeline.name}" is never closed \u2014 add "}"`,
+      `Pipeline block of "${this.blockPipeline.name}" is never closed: add "}"`,
       this.blockOpening.line,
       this.blockOpening.text
     );
@@ -755,7 +755,7 @@ var MapReader = class {
     if (blockCommentStart) {
       const { line, text: startText } = blockCommentStart;
       this.diag(
-        'Block comment "/*" is never closed \u2014 the rest of the file is a comment',
+        'Block comment "/*" is never closed: the rest of the file is a comment',
         line,
         startText
       );
@@ -856,7 +856,7 @@ var MapReader = class {
     }
     if (splitAtCoords(after)?.name) {
       this.diag(
-        `Component with [visibility, maturity] inside the block of pipeline "${blockPipeline.name}" is not a child \u2014 use [maturity]`
+        `Component with [visibility, maturity] inside the block of pipeline "${blockPipeline.name}" is not a child: use [maturity]`
       );
     }
     return false;
@@ -924,7 +924,7 @@ var MapReader = class {
     let body = after;
     let opensBlock = false;
     while (body.endsWith("{")) {
-      if (opensBlock) this.diag('Ignored "{" \u2014 a block must directly follow a pipeline line');
+      if (opensBlock) this.diag('Ignored "{": a block must directly follow a pipeline line');
       opensBlock = true;
       body = body.slice(0, -1).trim();
     }
@@ -991,7 +991,7 @@ var MapReader = class {
     if (problem) this.diag(problem);
     if (!Number.isInteger(coords.a) || !Number.isInteger(coords.b)) {
       this.diag(
-        `Map size ${coords.a}\xD7${coords.b} is not in whole pixels \u2014 OWM only reads whole-pixel sizes`
+        `Map size ${coords.a}\xD7${coords.b} is not in whole pixels: OWM only reads whole-pixel sizes`
       );
     }
   }
@@ -1020,7 +1020,7 @@ var MapReader = class {
     });
     if (written.length !== 1 && !(written.length === 3 && written.every(Boolean))) {
       const read = [label, ...ends ?? []].join("->");
-      this.diag(`y-axis takes "Label" or "Label->Bottom->Top" \u2014 read as "${read}"`);
+      this.diag(`y-axis takes "Label" or "Label->Bottom->Top": read as "${read}"`);
     }
   }
   readAnnotationsBox(line, after) {
@@ -1028,7 +1028,7 @@ var MapReader = class {
     if (!split) {
       return this.keep(
         line,
-        "Annotations box has no position \u2014 not used; add [visibility, maturity]"
+        "Annotations box has no position: not used; add [visibility, maturity]"
       );
     }
     this.reportTextBefore(split.name);
@@ -1043,7 +1043,7 @@ var MapReader = class {
     if (!Number.isSafeInteger(number)) return this.failed(line);
     const found = parsePositions(after.replace(/^\s*\d+\s*/, ""));
     if (!found) {
-      return this.keep(line, "Annotation has no position \u2014 not drawn; add [visibility, maturity]");
+      return this.keep(line, "Annotation has no position: not drawn; add [visibility, maturity]");
     }
     if (!found.tuples.length) return this.failed(line);
     for (const unreadable of found.unreadable) this.diag(unreadableNumberMessage(unreadable));
@@ -1110,7 +1110,7 @@ var MapReader = class {
    */
   readMethod(line, after, kw) {
     if (this.pushComponent(after, kw)) return;
-    if (!after) return this.keep(line, `${kw}: needs a component name \u2014 not used`);
+    if (!after) return this.keep(line, `${kw}: needs a component name; not used`);
     this.pendingMethod.push({
       name: after,
       method: kw,
@@ -1282,7 +1282,7 @@ var MapReader = class {
         this.keepLine(p.raw, p.lineNo, p.text);
         if (!component) {
           this.diag(
-            `Pipeline "${p.name}" has no range \u2014 not drawn; add [start, end] or child components`,
+            `Pipeline "${p.name}" has no range: not drawn; add [start, end] or child components`,
             p.lineNo,
             p.text
           );
@@ -1295,7 +1295,7 @@ var MapReader = class {
       const widened = range.start !== writtenRange.start || range.end !== writtenRange.end;
       if (widened && !writtenRange.fromChildren) {
         this.diag(
-          `Pipeline "${p.name}" range is empty or reversed \u2014 changed to [${range.start}, ${range.end}]`,
+          `Pipeline "${p.name}" range is empty or reversed: changed to [${range.start}, ${range.end}]`,
           p.lineNo,
           p.text
         );
@@ -1344,7 +1344,7 @@ var MapReader = class {
       const component = this.elements[index];
       const earlier = evolveLineOf.get(component.id);
       if (earlier !== void 0) {
-        const message = `Repeated evolve for "${ev.name}" \u2014 replaces the one on line ${earlier}`;
+        const message = `Repeated evolve for "${ev.name}": replaces the one on line ${earlier}`;
         this.diag(message, ev.lineNo, ev.text);
       }
       evolveLineOf.set(component.id, ev.lineNo);
@@ -1372,7 +1372,7 @@ var MapReader = class {
       const el = this.elements[index];
       const replaced = el.decorators?.method;
       if (replaced && replaced !== pm.method) {
-        const message = `${pm.method}: "${pm.name}" already has the method "${replaced}" \u2014 replaced`;
+        const message = `${pm.method}: replaces the method "${replaced}" of "${pm.name}"`;
         this.diag(message, pm.lineNo, pm.text);
       }
       this.elements[index] = { ...el, decorators: { ...el.decorators, method: pm.method } };
@@ -1383,7 +1383,7 @@ var MapReader = class {
   }
 };
 function renamedMessage(sourceName, name) {
-  return `Name "${sourceName}" renamed to "${name}" \u2014 a name cannot hold link operators ("->", "+>", "+<", "+'"), comment markers or a leading "{"`;
+  return `Name "${sourceName}" renamed to "${name}", because a name cannot hold link operators ("->", "+>", "+<", "+'"), comment markers or a leading "{"`;
 }
 function withoutTrailingCarriageReturns(line) {
   let end = line.length;
@@ -1397,7 +1397,7 @@ function withoutClosersOfKeptComments(entries, report) {
     if (!entry.isComment && nextParse.insideBlockComment && text.includes("*/")) {
       text = text.replaceAll("*/", " ");
       report(
-        'Ignored "*/" \u2014 this line is kept after an unclosed "/*" and would end that comment',
+        'Ignored "*/": this line is kept after an unclosed "/*" and would end that comment',
         entry.lineNo,
         entry.source
       );
@@ -1416,7 +1416,7 @@ function replacedConfigLines(unusedLines, config, report) {
     const replaced = configIsSet[unused.keyword];
     if (replaced) replacedIndexes.add(unused.index);
     const outcome = replaced ? `removed; another "${unused.keyword}" line sets it` : "not used";
-    report(`${unused.reason} \u2014 ${outcome}`, unused.line, unused.text);
+    report(`${unused.reason}: ${outcome}`, unused.line, unused.text);
   }
   return replacedIndexes;
 }
@@ -1428,7 +1428,7 @@ function resolveUrlReferences(elements, refs, definitions, report, resolved) {
     if (earlier) {
       replaced.add(earlier);
       report(
-        `Repeated url definition "${definition.name}" \u2014 replaces the one on line ${earlier.lineNo}, which is kept unused`,
+        `Repeated url definition "${definition.name}": replaces the one on line ${earlier.lineNo}, which is kept unused`,
         definition.lineNo,
         definition.text
       );
@@ -1441,7 +1441,7 @@ function resolveUrlReferences(elements, refs, definitions, report, resolved) {
     if (definition) used.add(definition);
     const address = definition?.address ?? (/^[a-z][\w+.-]*:\/\//i.test(ref) ? ref : void 0);
     if (!address) {
-      report(`url(${ref}) has no matching "url ${ref} [address]" line \u2014 ignored`, line, text);
+      report(`url(${ref}) has no matching "url ${ref} [address]" line: ignored`, line, text);
       continue;
     }
     const el = elements[index];
@@ -1576,7 +1576,7 @@ function splitPipelineLine(body) {
   return { name: rest, range: null, suffixText: groups.join(" "), misplaced: [] };
 }
 function unreadableNumberMessage(text) {
-  return `Unreadable number in "${text}" \u2014 ignored`;
+  return `Unreadable number in "${text}": ignored`;
 }
 function pipelineRange(p) {
   if (p.start !== void 0 && p.end !== void 0) {
@@ -1668,7 +1668,7 @@ function splitMisplacedEvolveSuffix(name) {
   return rest ? { name: rest, suffix: m[0] } : null;
 }
 function misplacedEvolveSuffixHint({ name, suffix }) {
-  return suffix.startsWith("(") ? ` \u2014 for component "${name}", write "${suffix}" after the target` : ` \u2014 for component "${name}", write "${suffix}" on its component line`;
+  return suffix.startsWith("(") ? `; for component "${name}", write "${suffix}" after the target` : `; for component "${name}", write "${suffix}" on its component line`;
 }
 var NUMBER_TOKEN_RE = /(^|\s)([-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?)(?=\s|\(|$)/gi;
 function parseEvolve(after, report) {
@@ -1707,7 +1707,7 @@ function sizeOutsideLimits(width, height) {
   const minimum = `${wardleySchemaModel.PLOT_MIN.width}\xD7${wardleySchemaModel.PLOT_MIN.height}`;
   const maximum = `${wardleySchemaModel.PLOT_MAX.width}\xD7${wardleySchemaModel.PLOT_MAX.height}`;
   const limit = below && above ? `outside ${minimum} to ${maximum}` : below ? `below the minimum ${minimum}` : `above the maximum ${maximum}`;
-  return `Map size ${width}\xD7${height} is ${limit} \u2014 drawn at ${drawnWidth}\xD7${drawnHeight}`;
+  return `Map size ${width}\xD7${height} is ${limit}: drawn at ${drawnWidth}\xD7${drawnHeight}`;
 }
 
 // src/serializer.ts
@@ -2485,6 +2485,28 @@ function fingerprint(map) {
   return entries.sort().join("\n");
 }
 
+// src/read-back-ids.ts
+var ELEMENT_KEY = /^(?:element|child):(.*)$/s;
+function elementIdOf(key) {
+  return ELEMENT_KEY.exec(key)?.[1];
+}
+function readBackIds(map) {
+  const lines = serializeKeyedLines(map);
+  const { sourceMap } = parseDSLWithSourceMap([...lines.map((line) => line.text), ""].join("\n"));
+  const readIdByLine = /* @__PURE__ */ new Map();
+  for (const [key, line] of sourceMap.primaryLineOf) {
+    const id = elementIdOf(key);
+    if (id !== void 0) readIdByLine.set(line, id);
+  }
+  const ids = /* @__PURE__ */ new Map();
+  lines.forEach((line, index) => {
+    const id = elementIdOf(line.key);
+    const readId = readIdByLine.get(index + 1);
+    if (id !== void 0 && readId !== void 0) ids.set(id, readId);
+  });
+  return ids;
+}
+
 // src/raw-passthrough.ts
 function withoutRawStatements(rawPassthrough, keyword) {
   if (!rawPassthrough) return rawPassthrough;
@@ -2524,6 +2546,7 @@ exports.parseDSLWithDiagnostics = parseDSLWithDiagnostics;
 exports.parseDecorators = parseDecorators;
 exports.parseLabelOffset = parseLabelOffset;
 exports.patchDSL = patchDSL;
+exports.readBackIds = readBackIds;
 exports.serializeDSL = serializeDSL;
 exports.slug = slug;
 exports.withoutRawStatements = withoutRawStatements;