@miragon/wardley-dsl 0.5.3 → 0.7.0

package/dist/index.d.cts

@@ -1,6 +1,14 @@
 import { WardleyMap, Method } from '@miragon/wardley-schema-model';
 export { loadMap, parseMapJSON as mapFromJSON, serializeMap as mapToJSON } from '@miragon/wardley-schema-model';
 
+/**
+ * Serializes a WardleyMap into Online-Wardley-Maps text. Deterministic; writes only
+ * syntax the OWM parser reads back. `rawPassthrough` is appended unchanged.
+ * Coordinates are keyword-differentiated (component/anchor/note = [visibility, maturity];
+ * pipeline = [maturityStart, maturityEnd]).
+ */
+declare function serializeDSL(map: WardleyMap): string;
+
 /** Finding produced while parsing — line is 1-based; `text` is that source line, trimmed. */
 interface ParseDiagnostic {
     readonly line: number;
@@ -23,12 +31,40 @@ declare function parseDSL(text: string): WardleyMap;
 declare function parseDSLWithDiagnostics(text: string): ParseResult;
 
 /**
- * Serializes a WardleyMap into Online-Wardley-Maps text. Deterministic; writes only
- * syntax the OWM parser reads back. `rawPassthrough` is appended unchanged.
- * Coordinates are keyword-differentiated (component/anchor/note = [visibility, maturity];
- * pipeline = [maturityStart, maturityEnd]).
+ * Writes `map` back into `originalText`, the text it was read from, and keeps everything the edit
+ * did not touch verbatim: comments, blank lines, line order, number formatting, unknown lines and
+ * the line breaks. Changed statements are rewritten in place the way `serializeDSL` writes them,
+ * removed ones are deleted and new ones are inserted after the last statement of their kind. The
+ * result always reads back as the same map as `serializeDSL(map)`; when a patch cannot guarantee
+ * that, the result is `serializeDSL(map)` itself, in the line break style of the source. Never
+ * throws.
  */
-declare function serializeDSL(map: WardleyMap): string;
+declare function patchDSL(originalText: string, map: WardleyMap, options?: PatchOptions): string;
+interface PatchOptions {
+    /**
+     * The map `originalText` was last written from, in the caller's ids. An editor that keeps the
+     * ids of its first read (instead of re-reading every patched text) passes it, so an element
+     * renamed twice is still recognised: the re-read text derives its id from the first new name.
+     */
+    readonly previous?: WardleyMap;
+}
+
+/**
+ * The id each element of `map` carries once `serializeDSL(map)` is read back, keyed by its id in
+ * `map`. The OWM DSL writes no ids: the parser derives them from names, texts and the order of the
+ * lines, so an element created or renamed in an editor has another id in memory than in the
+ * document until the text is read again. Elements the text does not write (none today) are
+ * missing from the result.
+ */
+declare function readBackIds(map: WardleyMap): Map<string, string>;
+
+/**
+ * `rawPassthrough` without the uninterpreted statements of one keyword (e.g. an unreadable `size`
+ * line once the map writes a valid one). Lines are judged by their code outside comments, so text
+ * inside a block comment that merely starts with the keyword stays. A dropped statement keeps its
+ * own comment fragments, so an opened block comment still closes where it did.
+ */
+declare function withoutRawStatements(rawPassthrough: readonly string[] | undefined, keyword: string): readonly string[] | undefined;
 
 /**
  * Small, line-oriented helpers for the OWM DSL (concept doc §7.4).
@@ -78,4 +114,5 @@ declare function parseLabelOffset(line: string): {
 declare function keywordOf(line: string): string;
 declare function slug(label: string): string;
 
-export { type InlineDecorators, type LabelOffsetToken, type ParseDiagnostic, type ParseResult, type ParsedCoords, keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, serializeDSL, slug };
+export { keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, patchDSL, readBackIds, serializeDSL, slug, withoutRawStatements };
+export type { InlineDecorators, LabelOffsetToken, ParseDiagnostic, ParseResult, ParsedCoords, PatchOptions };

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 import { WardleyMap, Method } from '@miragon/wardley-schema-model';
 export { loadMap, parseMapJSON as mapFromJSON, serializeMap as mapToJSON } from '@miragon/wardley-schema-model';
 
+/**
+ * Serializes a WardleyMap into Online-Wardley-Maps text. Deterministic; writes only
+ * syntax the OWM parser reads back. `rawPassthrough` is appended unchanged.
+ * Coordinates are keyword-differentiated (component/anchor/note = [visibility, maturity];
+ * pipeline = [maturityStart, maturityEnd]).
+ */
+declare function serializeDSL(map: WardleyMap): string;
+
 /** Finding produced while parsing — line is 1-based; `text` is that source line, trimmed. */
 interface ParseDiagnostic {
     readonly line: number;
@@ -23,12 +31,40 @@ declare function parseDSL(text: string): WardleyMap;
 declare function parseDSLWithDiagnostics(text: string): ParseResult;
 
 /**
- * Serializes a WardleyMap into Online-Wardley-Maps text. Deterministic; writes only
- * syntax the OWM parser reads back. `rawPassthrough` is appended unchanged.
- * Coordinates are keyword-differentiated (component/anchor/note = [visibility, maturity];
- * pipeline = [maturityStart, maturityEnd]).
+ * Writes `map` back into `originalText`, the text it was read from, and keeps everything the edit
+ * did not touch verbatim: comments, blank lines, line order, number formatting, unknown lines and
+ * the line breaks. Changed statements are rewritten in place the way `serializeDSL` writes them,
+ * removed ones are deleted and new ones are inserted after the last statement of their kind. The
+ * result always reads back as the same map as `serializeDSL(map)`; when a patch cannot guarantee
+ * that, the result is `serializeDSL(map)` itself, in the line break style of the source. Never
+ * throws.
  */
-declare function serializeDSL(map: WardleyMap): string;
+declare function patchDSL(originalText: string, map: WardleyMap, options?: PatchOptions): string;
+interface PatchOptions {
+    /**
+     * The map `originalText` was last written from, in the caller's ids. An editor that keeps the
+     * ids of its first read (instead of re-reading every patched text) passes it, so an element
+     * renamed twice is still recognised: the re-read text derives its id from the first new name.
+     */
+    readonly previous?: WardleyMap;
+}
+
+/**
+ * The id each element of `map` carries once `serializeDSL(map)` is read back, keyed by its id in
+ * `map`. The OWM DSL writes no ids: the parser derives them from names, texts and the order of the
+ * lines, so an element created or renamed in an editor has another id in memory than in the
+ * document until the text is read again. Elements the text does not write (none today) are
+ * missing from the result.
+ */
+declare function readBackIds(map: WardleyMap): Map<string, string>;
+
+/**
+ * `rawPassthrough` without the uninterpreted statements of one keyword (e.g. an unreadable `size`
+ * line once the map writes a valid one). Lines are judged by their code outside comments, so text
+ * inside a block comment that merely starts with the keyword stays. A dropped statement keeps its
+ * own comment fragments, so an opened block comment still closes where it did.
+ */
+declare function withoutRawStatements(rawPassthrough: readonly string[] | undefined, keyword: string): readonly string[] | undefined;
 
 /**
  * Small, line-oriented helpers for the OWM DSL (concept doc §7.4).
@@ -78,4 +114,5 @@ declare function parseLabelOffset(line: string): {
 declare function keywordOf(line: string): string;
 declare function slug(label: string): string;
 
-export { type InlineDecorators, type LabelOffsetToken, type ParseDiagnostic, type ParseResult, type ParsedCoords, keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, serializeDSL, slug };
+export { keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, patchDSL, readBackIds, serializeDSL, slug, withoutRawStatements };
+export type { InlineDecorators, LabelOffsetToken, ParseDiagnostic, ParseResult, ParsedCoords, PatchOptions };