mermaid-ast 0.2.0 → 0.3.0

package/README.md

@@ -131,6 +131,55 @@ detectDiagramType("classDiagram\n  class Animal"); // "class"
 detectDiagramType("unknown diagram"); // null
 ```
 
+### Render Options (Pretty-Print)
+
+All render functions accept an optional `RenderOptions` object to customize output formatting:
+
+```typescript
+import { renderFlowchart, parseFlowchart } from "mermaid-ast";
+import type { RenderOptions } from "mermaid-ast";
+
+const ast = parseFlowchart(`flowchart LR
+    A[Start] --> B[Middle] --> C[End]
+    classDef highlight fill:#f9f
+    class A highlight`);
+
+// Default output (4-space indent)
+renderFlowchart(ast);
+
+// Custom indent (2 spaces)
+renderFlowchart(ast, { indent: 2 });
+
+// Tab indent
+renderFlowchart(ast, { indent: "tab" });
+
+// Sort nodes alphabetically
+renderFlowchart(ast, { sortNodes: true });
+
+// Flowchart-specific: inline classes (A:::highlight instead of separate class statement)
+renderFlowchart(ast, { inlineClasses: true });
+
+// Flowchart-specific: chain links (A --> B --> C on one line)
+renderFlowchart(ast, { compactLinks: true });
+
+// Combine options
+renderFlowchart(ast, {
+  indent: 2,
+  sortNodes: true,
+  inlineClasses: true,
+  compactLinks: true,
+});
+```
+
+#### Available Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `indent` | `number \| "tab"` | `4` | Number of spaces for indentation, or `"tab"` for tabs |
+| `sortNodes` | `boolean` | `false` | Sort node/actor/class declarations alphabetically |
+| `inlineClasses` | `boolean` | `false` | (Flowchart only) Use `A:::className` instead of separate `class` statements |
+| `compactLinks` | `boolean` | `false` | (Flowchart only) Chain consecutive links: `A --> B --> C` |
+
 ## API Reference
 
 ### Core Functions
@@ -138,7 +187,7 @@ detectDiagramType("unknown diagram"); // null
 | Function | Description |
 |----------|-------------|
 | `parse(input: string): MermaidAST` | Parse any supported diagram |
-| `render(ast: MermaidAST): string` | Render any supported AST |
+| `render(ast: MermaidAST, options?: RenderOptions): string` | Render any supported AST |
 | `detectDiagramType(input: string): DiagramType \| null` | Detect diagram type |
 
 ### Flowchart Functions
@@ -146,7 +195,7 @@ detectDiagramType("unknown diagram"); // null
 | Function | Description |
 |----------|-------------|
 | `parseFlowchart(input: string): FlowchartAST` | Parse flowchart diagram |
-| `renderFlowchart(ast: FlowchartAST): string` | Render flowchart AST |
+| `renderFlowchart(ast: FlowchartAST, options?: RenderOptions): string` | Render flowchart AST |
 | `isFlowchartDiagram(input: string): boolean` | Check if input is flowchart |
 
 ### Sequence Diagram Functions
@@ -154,7 +203,7 @@ detectDiagramType("unknown diagram"); // null
 | Function | Description |
 |----------|-------------|
 | `parseSequence(input: string): SequenceAST` | Parse sequence diagram |
-| `renderSequence(ast: SequenceAST): string` | Render sequence AST |
+| `renderSequence(ast: SequenceAST, options?: RenderOptions): string` | Render sequence AST |
 | `isSequenceDiagram(input: string): boolean` | Check if input is sequence |
 
 ### Class Diagram Functions
@@ -162,7 +211,7 @@ detectDiagramType("unknown diagram"); // null
 | Function | Description |
 |----------|-------------|
 | `parseClassDiagram(input: string): ClassDiagramAST` | Parse class diagram |
-| `renderClassDiagram(ast: ClassDiagramAST): string` | Render class diagram AST |
+| `renderClassDiagram(ast: ClassDiagramAST, options?: RenderOptions): string` | Render class diagram AST |
 | `isClassDiagram(input: string): boolean` | Check if input is class diagram |
 
 ## Supported Flowchart Features
@@ -186,6 +235,25 @@ detectDiagramType("unknown diagram"); // null
 - **Notes**: `note left of`, `note right of`, `note over`
 - **Actor lifecycle**: `create`, `destroy`
 
+## Limitations
+
+### Comments Not Preserved
+
+Mermaid supports `%%` line comments, but **comments are not preserved** during parsing. The JISON parsers discard comments during lexing, so they are not included in the AST and will not appear in rendered output.
+
+```mermaid
+flowchart LR
+    %% This comment will be lost
+    A --> B
+```
+
+After round-trip, the comment is gone:
+
+```mermaid
+flowchart LR
+    A --> B
+```
+
 ## Supported Class Diagram Features
 
 - **Classes**: With labels, members (attributes and methods)
@@ -296,6 +364,8 @@ mermaid-ast/
 
 MIT
 
+This project includes JISON parsers from [mermaid.js](https://github.com/mermaid-js/mermaid) (MIT License, Copyright (c) 2014 - 2022 Knut Sveidqvist). See [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md) for details.
+
 ---
 
 ## How This Library Was Built

package/dist/renderer/class-renderer.d.ts

@@ -4,8 +4,9 @@
  * Renders a Class Diagram AST back to Mermaid syntax.
  */
 import type { ClassDiagramAST } from "../types/class.js";
+import type { RenderOptions } from "../types/render-options.js";
 /**
  * Render a ClassDiagramAST to Mermaid syntax
  */
-export declare function renderClassDiagram(ast: ClassDiagramAST): string;
+export declare function renderClassDiagram(ast: ClassDiagramAST, options?: RenderOptions): string;
 //# sourceMappingURL=class-renderer.d.ts.map

package/dist/renderer/class-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class-renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/class-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,mBAAmB,CAAC;AA2N3B;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,CAiE/D"}
+{"version":3,"file":"class-renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/class-renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AA4KhE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAgExF"}

package/dist/renderer/class-renderer.js

@@ -3,6 +3,8 @@
  *
  * Renders a Class Diagram AST back to Mermaid syntax.
  */
+import { resolveOptions } from "../types/render-options.js";
+import { indent, when, block, render } from "./doc.js";
 /**
  * Render relation type to symbol
  */
@@ -30,167 +32,128 @@ function renderLineType(lineType) {
     return lineType === "dotted" ? ".." : "--";
 }
 /**
- * Render a relationship
+ * Render a relationship to a string
  */
 function renderRelation(relation) {
     const { id1, id2, relation: rel, relationTitle1, relationTitle2, title } = relation;
-    // Build the arrow
     const startType = renderRelationType(rel.type1, true);
     const endType = renderRelationType(rel.type2, false);
     const line = renderLineType(rel.lineType);
-    let arrow = `${startType}${line}${endType}`;
-    // Build the full statement
+    const arrow = `${startType}${line}${endType}`;
     let result = id1;
-    // Add cardinality/title on id1 side
-    if (relationTitle1) {
+    if (relationTitle1)
         result += ` "${relationTitle1}"`;
-    }
     result += ` ${arrow}`;
-    // Add cardinality/title on id2 side
-    if (relationTitle2) {
+    if (relationTitle2)
         result += ` "${relationTitle2}"`;
-    }
     result += ` ${id2}`;
-    // Add label if present
-    if (title) {
+    if (title)
         result += ` : ${title}`;
-    }
     return result;
 }
 /**
- * Render a class member
+ * Render a class member to a string
  */
 function renderMember(member) {
     const visibility = member.visibility || "";
     return `${visibility}${member.text}`;
 }
 /**
- * Render a class definition
+ * Render a class definition to a Doc
  */
-function renderClass(cls, inNamespace = false, isReferencedInRelations = false) {
-    const lines = [];
-    const indent = inNamespace ? "        " : "    ";
-    // Check if class needs a body
+function renderClass(cls, isReferencedInRelations) {
     const hasBody = cls.members.length > 0;
     const hasLabel = cls.label && cls.label !== cls.id;
     if (hasBody) {
-        // Class with body
-        if (hasLabel) {
-            lines.push(`${indent}class ${cls.id}["${cls.label}"] {`);
-        }
-        else {
-            lines.push(`${indent}class ${cls.id} {`);
-        }
-        // Render members
-        for (const member of cls.members) {
-            lines.push(`${indent}    ${renderMember(member)}`);
-        }
-        lines.push(`${indent}}`);
+        const header = hasLabel
+            ? `class ${cls.id}["${cls.label}"] {`
+            : `class ${cls.id} {`;
+        return block(header, cls.members.map(renderMember), "}");
     }
-    else if (hasLabel) {
-        // Class with label but no body
-        lines.push(`${indent}class ${cls.id}["${cls.label}"]`);
+    if (hasLabel) {
+        return `class ${cls.id}["${cls.label}"]`;
     }
-    else if (!isReferencedInRelations) {
-        // Class with no body, no label, and not referenced in relations - must declare explicitly
-        lines.push(`${indent}class ${cls.id}`);
+    // Class with no body, no label - only declare if not referenced in relations
+    if (!isReferencedInRelations) {
+        return `class ${cls.id}`;
     }
-    // If no body and no label but referenced in relations, it's declared implicitly
-    return lines;
+    // Implicitly declared via relations
+    return null;
 }
 /**
- * Render annotations for a class
+ * Render annotations for a class to a Doc
  */
 function renderAnnotations(cls) {
-    const lines = [];
-    for (const annotation of cls.annotations) {
-        lines.push(`    <<${annotation}>> ${cls.id}`);
-    }
-    return lines;
+    return cls.annotations.map((annotation) => `<<${annotation}>> ${cls.id}`);
 }
 /**
- * Render a namespace
+ * Render a namespace to a Doc
  */
-function renderNamespace(namespaceName, classIds, ast) {
-    const lines = [];
-    lines.push(`    namespace ${namespaceName} {`);
-    for (const classId of classIds) {
+function renderNamespace(namespaceName, classIds, ast, classesInRelations) {
+    const classesDoc = classIds
+        .map((classId) => {
         const cls = ast.classes.get(classId);
-        if (cls) {
-            lines.push(...renderClass(cls, true));
-        }
-    }
-    lines.push(`    }`);
-    return lines;
+        if (!cls)
+            return null;
+        return renderClass(cls, classesInRelations.has(classId));
+    })
+        .filter(Boolean);
+    return block(`namespace ${namespaceName} {`, classesDoc, "}");
 }
 /**
- * Render notes
+ * Render notes to a Doc
  */
 function renderNotes(notes) {
-    const lines = [];
-    for (const note of notes) {
-        if (note.forClass) {
-            lines.push(`    note for ${note.forClass} "${note.text}"`);
-        }
-        else {
-            lines.push(`    note "${note.text}"`);
-        }
-    }
-    return lines;
+    return notes.map((note) => note.forClass
+        ? `note for ${note.forClass} "${note.text}"`
+        : `note "${note.text}"`);
 }
 /**
- * Render class definitions (classDef)
+ * Render class definitions (classDef) to a Doc
  */
 function renderClassDefs(ast) {
-    const lines = [];
-    for (const [name, def] of ast.classDefs) {
+    const entries = [...ast.classDefs.entries()];
+    return entries.map(([name, def]) => {
         const styles = def.styles.join(",");
-        lines.push(`    classDef ${name} ${styles}`);
-    }
-    return lines;
+        return `classDef ${name} ${styles}`;
+    });
 }
 /**
- * Render CSS class assignments
+ * Render CSS class assignments to a Doc
  */
 function renderCssClasses(ast) {
-    const lines = [];
+    const assignments = [];
     for (const [, cls] of ast.classes) {
         for (const cssClass of cls.cssClasses) {
-            lines.push(`    cssClass "${cls.id}" ${cssClass}`);
+            assignments.push(`cssClass "${cls.id}" ${cssClass}`);
         }
     }
-    return lines;
+    return assignments;
 }
 /**
- * Render click handlers and links
+ * Render click handlers and links to a Doc
  */
 function renderClicks(ast) {
-    const lines = [];
+    const clicks = [];
     for (const [, cls] of ast.classes) {
         if (cls.link) {
             const target = cls.linkTarget ? ` ${cls.linkTarget}` : "";
             const tooltip = cls.tooltip ? ` "${cls.tooltip}"` : "";
-            lines.push(`    link ${cls.id} "${cls.link}"${tooltip}${target}`);
+            clicks.push(`link ${cls.id} "${cls.link}"${tooltip}${target}`);
         }
         else if (cls.callback) {
             const args = cls.callbackArgs ? `("${cls.callbackArgs}")` : "";
             const tooltip = cls.tooltip ? ` "${cls.tooltip}"` : "";
-            lines.push(`    callback ${cls.id} "${cls.callback}"${args}${tooltip}`);
+            clicks.push(`callback ${cls.id} "${cls.callback}"${args}${tooltip}`);
         }
     }
-    return lines;
+    return clicks;
 }
 /**
  * Render a ClassDiagramAST to Mermaid syntax
  */
-export function renderClassDiagram(ast) {
-    const lines = [];
-    // Header
-    lines.push("classDiagram");
-    // Direction if not default
-    if (ast.direction && ast.direction !== "TB") {
-        lines.push(`    direction ${ast.direction}`);
-    }
+export function renderClassDiagram(ast, options) {
+    const opts = resolveOptions(options);
     // Track classes rendered in namespaces
     const classesInNamespaces = new Set();
     for (const [, ns] of ast.namespaces) {
@@ -204,35 +167,38 @@ export function renderClassDiagram(ast) {
         classesInRelations.add(relation.id1);
         classesInRelations.add(relation.id2);
     }
-    // Render namespaces
-    for (const [name, ns] of ast.namespaces) {
-        lines.push(...renderNamespace(name, ns.classes, ast));
-    }
-    // Render annotations (before classes)
-    for (const [, cls] of ast.classes) {
-        if (cls.annotations.length > 0) {
-            lines.push(...renderAnnotations(cls));
-        }
-    }
-    // Render classes not in namespaces
-    for (const [classId, cls] of ast.classes) {
-        if (!classesInNamespaces.has(classId)) {
-            const isReferencedInRelations = classesInRelations.has(classId);
-            const classLines = renderClass(cls, false, isReferencedInRelations);
-            lines.push(...classLines);
-        }
-    }
-    // Render relations
-    for (const relation of ast.relations) {
-        lines.push(`    ${renderRelation(relation)}`);
-    }
-    // Render notes
-    lines.push(...renderNotes(ast.notes));
-    // Render class definitions
-    lines.push(...renderClassDefs(ast));
-    // Render CSS class assignments
-    lines.push(...renderCssClasses(ast));
-    // Render click handlers
-    lines.push(...renderClicks(ast));
-    return lines.join("\n");
+    // Get classes (optionally sorted)
+    let classEntries = [...ast.classes.entries()];
+    if (opts.sortNodes) {
+        classEntries.sort((a, b) => a[0].localeCompare(b[0]));
+    }
+    // Build the document
+    const doc = [
+        "classDiagram",
+        indent([
+            // Direction
+            when(ast.direction && ast.direction !== "TB", `direction ${ast.direction}`),
+            // Namespaces
+            ...[...ast.namespaces.entries()].map(([name, ns]) => renderNamespace(name, ns.classes, ast, classesInRelations)),
+            // Annotations (before classes)
+            ...classEntries
+                .filter(([, cls]) => cls.annotations.length > 0)
+                .map(([, cls]) => renderAnnotations(cls)),
+            // Classes not in namespaces
+            ...classEntries
+                .filter(([classId]) => !classesInNamespaces.has(classId))
+                .map(([classId, cls]) => renderClass(cls, classesInRelations.has(classId))),
+            // Relations
+            ...ast.relations.map(renderRelation),
+            // Notes
+            renderNotes(ast.notes),
+            // Class definitions
+            renderClassDefs(ast),
+            // CSS class assignments
+            renderCssClasses(ast),
+            // Click handlers
+            renderClicks(ast),
+        ]),
+    ];
+    return render(doc, opts.indent);
 }