@miragon/wardley-dsl 0.5.2 → 0.6.0

package/dist/index.d.cts

@@ -1,7 +1,15 @@
 import { WardleyMap, Method } from '@miragon/wardley-schema-model';
 export { loadMap, parseMapJSON as mapFromJSON, serializeMap as mapToJSON } from '@miragon/wardley-schema-model';
 
-/** Finding produced while parsing — line is 1-based; `text` is the (comment-stripped) line. */
+/**
+ * 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;
     readonly message: string;
@@ -23,12 +31,31 @@ 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;
+}
+
+/**
+ * `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).
@@ -52,6 +79,10 @@ interface InlineDecorators {
  * - parenthesized: `(market)`, `(ecosystem)`, `(build|buy|outsource)`, combined `(market, outsource)`
  * - trailing keyword: `inertia`
  * Returns the decorators found and the line stripped of them.
+ *
+ * @deprecated Kept for API compatibility; the parser no longer uses it. It reads every `( … )` group
+ * and `inertia` anywhere on the line and lets the last method win, while `parseDSL` reads decorators
+ * only after the coordinates and keeps the first method.
  */
 declare function parseDecorators(line: string): {
     decorators: InlineDecorators;
@@ -61,13 +92,17 @@ interface LabelOffsetToken {
     readonly dx: number;
     readonly dy: number;
 }
-/** Reads an optional `label [dx, dy]` (pixel offset) and returns it plus the stripped line. */
+/**
+ * Reads an optional `label [dx, dy]` (pixel offset) and returns it plus the stripped line.
+ * `unreadable` holds the matched text when a number in it cannot be read.
+ */
 declare function parseLabelOffset(line: string): {
     labelOffset: LabelOffsetToken | null;
     rest: string;
+    unreadable?: string;
 };
 /** First word (keyword) of a line, lowercased. */
 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 { type InlineDecorators, type LabelOffsetToken, type ParseDiagnostic, type ParseResult, type ParsedCoords, type PatchOptions, keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, patchDSL, serializeDSL, slug, withoutRawStatements };

package/dist/index.d.ts

@@ -1,7 +1,15 @@
 import { WardleyMap, Method } from '@miragon/wardley-schema-model';
 export { loadMap, parseMapJSON as mapFromJSON, serializeMap as mapToJSON } from '@miragon/wardley-schema-model';
 
-/** Finding produced while parsing — line is 1-based; `text` is the (comment-stripped) line. */
+/**
+ * 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;
     readonly message: string;
@@ -23,12 +31,31 @@ 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;
+}
+
+/**
+ * `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).
@@ -52,6 +79,10 @@ interface InlineDecorators {
  * - parenthesized: `(market)`, `(ecosystem)`, `(build|buy|outsource)`, combined `(market, outsource)`
  * - trailing keyword: `inertia`
  * Returns the decorators found and the line stripped of them.
+ *
+ * @deprecated Kept for API compatibility; the parser no longer uses it. It reads every `( … )` group
+ * and `inertia` anywhere on the line and lets the last method win, while `parseDSL` reads decorators
+ * only after the coordinates and keeps the first method.
  */
 declare function parseDecorators(line: string): {
     decorators: InlineDecorators;
@@ -61,13 +92,17 @@ interface LabelOffsetToken {
     readonly dx: number;
     readonly dy: number;
 }
-/** Reads an optional `label [dx, dy]` (pixel offset) and returns it plus the stripped line. */
+/**
+ * Reads an optional `label [dx, dy]` (pixel offset) and returns it plus the stripped line.
+ * `unreadable` holds the matched text when a number in it cannot be read.
+ */
 declare function parseLabelOffset(line: string): {
     labelOffset: LabelOffsetToken | null;
     rest: string;
+    unreadable?: string;
 };
 /** First word (keyword) of a line, lowercased. */
 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 { type InlineDecorators, type LabelOffsetToken, type ParseDiagnostic, type ParseResult, type ParsedCoords, type PatchOptions, keywordOf, parseCoords, parseDSL, parseDSLWithDiagnostics, parseDecorators, parseLabelOffset, patchDSL, serializeDSL, slug, withoutRawStatements };