mermaid-ast 0.2.0 → 0.4.0

package/README.md

@@ -17,9 +17,25 @@ This library provides a way to programmatically work with Mermaid diagrams by pa
 
 ## Supported Diagram Types
 
-- **Flowchart** (`flowchart`, `graph`)
-- **Sequence Diagram** (`sequenceDiagram`)
-- **Class Diagram** (`classDiagram`)
+| Diagram Type | Parse | Render | Builder |
+|--------------|-------|--------|---------|
+| Flowchart (`flowchart`, `graph`) | ✅ | ✅ | ✅ |
+| Sequence (`sequenceDiagram`) | ✅ | ✅ | ✅ |
+| Class (`classDiagram`) | ✅ | ✅ | ✅ |
+| State (`stateDiagram`) | ✅ | ✅ | ✅ |
+| ER Diagram (`erDiagram`) | ❌ | ❌ | ❌ |
+| Gantt (`gantt`) | ❌ | ❌ | ❌ |
+| Journey (`journey`) | ❌ | ❌ | ❌ |
+| Mindmap (`mindmap`) | ❌ | ❌ | ❌ |
+| Timeline (`timeline`) | ❌ | ❌ | ❌ |
+| Pie (`pie`) | ❌ | ❌ | ❌ |
+| Quadrant (`quadrantChart`) | ❌ | ❌ | ❌ |
+| Requirement (`requirementDiagram`) | ❌ | ❌ | ❌ |
+| Git Graph (`gitGraph`) | ❌ | ❌ | ❌ |
+| C4 (`C4Context`, etc.) | ❌ | ❌ | ❌ |
+| Sankey (`sankey`) | ❌ | ❌ | ❌ |
+| XY Chart (`xychart`) | ❌ | ❌ | ❌ |
+| Block (`block`) | ❌ | ❌ | ❌ |
 
 ## Installation
 
@@ -131,6 +147,156 @@ detectDiagramType("classDiagram\n  class Animal"); // "class"
 detectDiagramType("unknown diagram"); // null
 ```
 
+## Fluent Builder API
+
+Build diagrams programmatically with a chainable, type-safe API:
+
+### Flowchart Builder
+
+```typescript
+import { flowchart, render } from "mermaid-ast";
+
+const ast = flowchart("LR")
+  .node("A", "Start", { shape: "stadium" })
+  .node("B", "Process")
+  .node("C", "End", { shape: "circle" })
+  .link("A", "B", { text: "begin" })
+  .link("B", "C", { stroke: "dotted" })
+  .subgraph("sub1", "My Group", (s) => {
+    s.node("D", "Inner").link("D", "B");
+  })
+  .classDef("highlight", { fill: "#f9f" })
+  .class("A", "highlight")
+  .build();
+
+const text = render(ast);
+```
+
+### Sequence Builder
+
+```typescript
+import { sequence, render } from "mermaid-ast";
+
+const ast = sequence()
+  .participant("A", "Alice")
+  .actor("B", "Bob")
+  .message("A", "B", "Hello!", { arrow: "solid" })
+  .loop("Every minute", (l) => {
+    l.message("B", "A", "Ping");
+  })
+  .alt([
+    { condition: "Success", build: (b) => b.message("A", "B", "OK") },
+    { condition: "Failure", build: (b) => b.message("A", "B", "Error") },
+  ])
+  .note("A", "Important!", { placement: "right_of" })
+  .build();
+
+const text = render(ast);
+```
+
+### Class Diagram Builder
+
+```typescript
+import { classDiagram, render } from "mermaid-ast";
+
+const ast = classDiagram()
+  .class("Animal", (c) => {
+    c.property("name: string", "+")
+      .property("age: int", "-")
+      .method("speak()", "+");
+  })
+  .class("Dog")
+  .extends("Dog", "Animal")
+  .composition("Dog", "Tail")
+  .class("Tail")
+  .build();
+
+const text = render(ast);
+```
+
+### State Diagram Builder
+
+```typescript
+import { stateDiagram, render } from "mermaid-ast";
+
+const ast = stateDiagram()
+  .state("Idle", { description: "Waiting for input" })
+  .state("Running")
+  .state("Done")
+  .initial("Idle")
+  .transition("Idle", "Running", { label: "start" })
+  .transition("Running", "Done", { label: "complete" })
+  .final("Done")
+  .composite("Running", (c) => {
+    c.state("Step1").state("Step2").transition("Step1", "Step2");
+  })
+  .build();
+
+const text = render(ast);
+```
+
+### Builder Validation
+
+By default, `.build()` validates the diagram (e.g., ensures links reference existing nodes):
+
+```typescript
+// This throws FlowchartValidationError
+flowchart().node("A").link("A", "B").build();
+// Error: Link target node 'B' does not exist
+
+// Skip validation if needed
+flowchart().node("A").link("A", "B").build({ validate: false });
+```
+
+### 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 +304,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 +312,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 +320,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 +328,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 +352,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 +481,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/builder/class-builder.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Class Diagram Builder
+ *
+ * Fluent API for constructing Class Diagram ASTs programmatically.
+ */
+import { type ClassDiagramAST, type ClassDirection, type ClassMember, type LineType, type RelationType } from '../types/class.js';
+/**
+ * Options for adding a class
+ */
+export interface ClassOptions {
+    label?: string;
+    annotations?: string[];
+    cssClasses?: string[];
+}
+/**
+ * Options for adding a relation
+ */
+export interface RelationOptions {
+    type1?: RelationType;
+    type2?: RelationType;
+    lineType?: LineType;
+    label1?: string;
+    label2?: string;
+    label?: string;
+}
+/**
+ * Options for build()
+ */
+export interface ClassBuildOptions {
+    validate?: boolean;
+}
+/**
+ * Validation error for invalid AST
+ */
+export declare class ClassDiagramValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Builder for class members
+ */
+export declare class ClassMemberBuilder {
+    private members;
+    /**
+     * Add a property/attribute
+     */
+    property(text: string, visibility?: '+' | '-' | '#' | '~'): this;
+    /**
+     * Add a method
+     */
+    method(text: string, visibility?: '+' | '-' | '#' | '~'): this;
+    /**
+     * Get the members
+     */
+    getMembers(): ClassMember[];
+}
+/**
+ * Fluent builder for Class Diagram ASTs
+ */
+export declare class ClassDiagramBuilder {
+    private ast;
+    private currentNamespace;
+    constructor(direction?: ClassDirection);
+    /**
+     * Set the direction
+     */
+    direction(direction: ClassDirection): this;
+    /**
+     * Add a class
+     */
+    class(id: string, builderFn?: (builder: ClassMemberBuilder) => void, options?: ClassOptions): this;
+    /**
+     * Add a relation between two classes
+     */
+    relation(id1: string, id2: string, options?: RelationOptions): this;
+    /**
+     * Add an inheritance/extension relation (A extends B)
+     */
+    extends(child: string, parent: string, label?: string): this;
+    /**
+     * Add an implementation relation (A implements B)
+     */
+    implements(implementer: string, interface_: string, label?: string): this;
+    /**
+     * Add a composition relation (A has B, strong ownership)
+     */
+    composition(owner: string, owned: string, label?: string): this;
+    /**
+     * Add an aggregation relation (A has B, weak ownership)
+     */
+    aggregation(owner: string, owned: string, label?: string): this;
+    /**
+     * Add a dependency relation (A depends on B)
+     */
+    dependency(dependent: string, dependency: string, label?: string): this;
+    /**
+     * Add a namespace
+     */
+    namespace(name: string, builderFn: (builder: ClassDiagramBuilder) => void): this;
+    /**
+     * Add a note
+     */
+    note(text: string, forClass?: string): this;
+    /**
+     * Define a CSS class style
+     */
+    classDef(name: string, styles: string[]): this;
+    /**
+     * Apply a CSS class to a class
+     */
+    cssClass(classId: string, cssClassName: string): this;
+    /**
+     * Add a link to a class
+     */
+    link(classId: string, url: string, target?: string): this;
+    /**
+     * Add a callback to a class
+     */
+    callback(classId: string, callback: string, args?: string): this;
+    /**
+     * Add a tooltip to a class
+     */
+    tooltip(classId: string, tooltip: string): this;
+    /**
+     * Add an annotation to a class (e.g., <<interface>>, <<abstract>>)
+     */
+    annotate(classId: string, annotation: string): this;
+    /**
+     * Set the accessibility title
+     */
+    accTitle(title: string): this;
+    /**
+     * Set the accessibility description
+     */
+    accDescription(description: string): this;
+    /**
+     * Validate the AST
+     */
+    private validate;
+    /**
+     * Build and return the ClassDiagramAST
+     */
+    build(options?: ClassBuildOptions): ClassDiagramAST;
+}
+/**
+ * Create a new ClassDiagramBuilder
+ */
+export declare function classDiagram(direction?: ClassDirection): ClassDiagramBuilder;
+//# sourceMappingURL=class-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"class-builder.d.ts","sourceRoot":"","sources":["../../src/builder/class-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,WAAW,EAIhB,KAAK,QAAQ,EAEb,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAE3B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,OAAO,CAAqB;IAEpC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI;IAShE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI;IAS9D;;OAEG;IACH,UAAU,IAAI,WAAW,EAAE;CAG5B;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,gBAAgB,CAAuB;gBAEnC,SAAS,GAAE,cAAqB;IAK5C;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI;IAK1C;;OAEG;IACH,KAAK,CACH,EAAE,EAAE,MAAM,EACV,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,EACjD,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI;IA4BP;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI;IAkBnE;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAS5D;;OAEG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IASzE;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAS/D;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAS/D;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IASvE;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IAehF;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAS3C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAS9C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAQrD;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IASzD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAShE;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQ/C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAQnD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKzC;;OAEG;IACH,OAAO,CAAC,QAAQ;IAkChB;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,eAAe;CASpD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,GAAE,cAAqB,GAAG,mBAAmB,CAElF"}