mermaid-ast 0.3.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,107 @@ 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:

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"}

package/dist/builder/class-builder.js

@@ -0,0 +1,318 @@
+/**
+ * Class Diagram Builder
+ *
+ * Fluent API for constructing Class Diagram ASTs programmatically.
+ */
+import { createClassDiagramAST, } from '../types/class.js';
+/**
+ * Validation error for invalid AST
+ */
+export class ClassDiagramValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClassDiagramValidationError';
+    }
+}
+/**
+ * Builder for class members
+ */
+export class ClassMemberBuilder {
+    members = [];
+    /**
+     * Add a property/attribute
+     */
+    property(text, visibility) {
+        this.members.push({
+            text,
+            visibility,
+            type: 'attribute',
+        });
+        return this;
+    }
+    /**
+     * Add a method
+     */
+    method(text, visibility) {
+        this.members.push({
+            text,
+            visibility,
+            type: 'method',
+        });
+        return this;
+    }
+    /**
+     * Get the members
+     */
+    getMembers() {
+        return this.members;
+    }
+}
+/**
+ * Fluent builder for Class Diagram ASTs
+ */
+export class ClassDiagramBuilder {
+    ast;
+    currentNamespace = null;
+    constructor(direction = 'TB') {
+        this.ast = createClassDiagramAST();
+        this.ast.direction = direction;
+    }
+    /**
+     * Set the direction
+     */
+    direction(direction) {
+        this.ast.direction = direction;
+        return this;
+    }
+    /**
+     * Add a class
+     */
+    class(id, builderFn, options) {
+        const memberBuilder = new ClassMemberBuilder();
+        if (builderFn) {
+            builderFn(memberBuilder);
+        }
+        const classDef = {
+            id,
+            label: options?.label,
+            members: memberBuilder.getMembers(),
+            annotations: options?.annotations ?? [],
+            cssClasses: options?.cssClasses ?? [],
+            styles: [],
+        };
+        this.ast.classes.set(id, classDef);
+        // Add to current namespace if inside one
+        if (this.currentNamespace) {
+            const ns = this.ast.namespaces.get(this.currentNamespace);
+            if (ns) {
+                ns.classes.push(id);
+            }
+        }
+        return this;
+    }
+    /**
+     * Add a relation between two classes
+     */
+    relation(id1, id2, options) {
+        const relation = {
+            id1,
+            id2,
+            relation: {
+                type1: options?.type1 ?? 'none',
+                type2: options?.type2 ?? 'none',
+                lineType: options?.lineType ?? 'solid',
+            },
+            relationTitle1: options?.label1,
+            relationTitle2: options?.label2,
+            title: options?.label,
+        };
+        this.ast.relations.push(relation);
+        return this;
+    }
+    /**
+     * Add an inheritance/extension relation (A extends B)
+     */
+    extends(child, parent, label) {
+        return this.relation(parent, child, {
+            type1: 'extension',
+            type2: 'none',
+            lineType: 'solid',
+            label,
+        });
+    }
+    /**
+     * Add an implementation relation (A implements B)
+     */
+    implements(implementer, interface_, label) {
+        return this.relation(interface_, implementer, {
+            type1: 'extension',
+            type2: 'none',
+            lineType: 'dotted',
+            label,
+        });
+    }
+    /**
+     * Add a composition relation (A has B, strong ownership)
+     */
+    composition(owner, owned, label) {
+        return this.relation(owner, owned, {
+            type1: 'composition',
+            type2: 'none',
+            lineType: 'solid',
+            label,
+        });
+    }
+    /**
+     * Add an aggregation relation (A has B, weak ownership)
+     */
+    aggregation(owner, owned, label) {
+        return this.relation(owner, owned, {
+            type1: 'aggregation',
+            type2: 'none',
+            lineType: 'solid',
+            label,
+        });
+    }
+    /**
+     * Add a dependency relation (A depends on B)
+     */
+    dependency(dependent, dependency, label) {
+        return this.relation(dependent, dependency, {
+            type1: 'none',
+            type2: 'dependency',
+            lineType: 'dotted',
+            label,
+        });
+    }
+    /**
+     * Add a namespace
+     */
+    namespace(name, builderFn) {
+        const ns = {
+            name,
+            classes: [],
+        };
+        this.ast.namespaces.set(name, ns);
+        // Set current namespace context
+        this.currentNamespace = name;
+        builderFn(this);
+        this.currentNamespace = null;
+        return this;
+    }
+    /**
+     * Add a note
+     */
+    note(text, forClass) {
+        const note = {
+            text,
+            forClass,
+        };
+        this.ast.notes.push(note);
+        return this;
+    }
+    /**
+     * Define a CSS class style
+     */
+    classDef(name, styles) {
+        const styleDef = {
+            name,
+            styles,
+        };
+        this.ast.classDefs.set(name, styleDef);
+        return this;
+    }
+    /**
+     * Apply a CSS class to a class
+     */
+    cssClass(classId, cssClassName) {
+        const classDef = this.ast.classes.get(classId);
+        if (classDef) {
+            classDef.cssClasses.push(cssClassName);
+        }
+        return this;
+    }
+    /**
+     * Add a link to a class
+     */
+    link(classId, url, target) {
+        const classDef = this.ast.classes.get(classId);
+        if (classDef) {
+            classDef.link = url;
+            classDef.linkTarget = target;
+        }
+        return this;
+    }
+    /**
+     * Add a callback to a class
+     */
+    callback(classId, callback, args) {
+        const classDef = this.ast.classes.get(classId);
+        if (classDef) {
+            classDef.callback = callback;
+            classDef.callbackArgs = args;
+        }
+        return this;
+    }
+    /**
+     * Add a tooltip to a class
+     */
+    tooltip(classId, tooltip) {
+        const classDef = this.ast.classes.get(classId);
+        if (classDef) {
+            classDef.tooltip = tooltip;
+        }
+        return this;
+    }
+    /**
+     * Add an annotation to a class (e.g., <<interface>>, <<abstract>>)
+     */
+    annotate(classId, annotation) {
+        const classDef = this.ast.classes.get(classId);
+        if (classDef) {
+            classDef.annotations.push(annotation);
+        }
+        return this;
+    }
+    /**
+     * Set the accessibility title
+     */
+    accTitle(title) {
+        this.ast.accTitle = title;
+        return this;
+    }
+    /**
+     * Set the accessibility description
+     */
+    accDescription(description) {
+        this.ast.accDescription = description;
+        return this;
+    }
+    /**
+     * Validate the AST
+     */
+    validate() {
+        const errors = [];
+        // Check that all relation classes exist
+        for (const relation of this.ast.relations) {
+            if (!this.ast.classes.has(relation.id1)) {
+                errors.push(`Relation references non-existent class '${relation.id1}'`);
+            }
+            if (!this.ast.classes.has(relation.id2)) {
+                errors.push(`Relation references non-existent class '${relation.id2}'`);
+            }
+        }
+        // Check that all namespace classes exist
+        for (const [nsName, ns] of this.ast.namespaces) {
+            for (const classId of ns.classes) {
+                if (!this.ast.classes.has(classId)) {
+                    errors.push(`Namespace '${nsName}' references non-existent class '${classId}'`);
+                }
+            }
+        }
+        // Check that all note references exist
+        for (const note of this.ast.notes) {
+            if (note.forClass && !this.ast.classes.has(note.forClass)) {
+                errors.push(`Note references non-existent class '${note.forClass}'`);
+            }
+        }
+        if (errors.length > 0) {
+            throw new ClassDiagramValidationError(errors.join('\n'));
+        }
+    }
+    /**
+     * Build and return the ClassDiagramAST
+     */
+    build(options) {
+        const shouldValidate = options?.validate !== false;
+        if (shouldValidate) {
+            this.validate();
+        }
+        return this.ast;
+    }
+}
+/**
+ * Create a new ClassDiagramBuilder
+ */
+export function classDiagram(direction = 'TB') {
+    return new ClassDiagramBuilder(direction);
+}