mermaid-ast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Emily
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# mermaid-ast
+
+[![Built with Slate](https://img.shields.io/badge/Built%20with-Slate-blue)](https://randomlabs.ai)
+
+Parse and render Mermaid diagrams to/from AST (Abstract Syntax Tree).
+
+This library provides a way to programmatically work with Mermaid diagrams by parsing them into a structured AST and rendering them back to Mermaid syntax. It uses the official mermaid.js JISON parsers to ensure compatibility.
+
+## Features
+
+- **Parse** Mermaid diagrams into typed AST structures
+- **Render** ASTs back to valid Mermaid syntax
+- **Round-trip guarantee**: `render(parse(text))` produces semantically equivalent diagrams
+- **Full TypeScript support** with comprehensive type definitions
+- **Cross-runtime support**: Works in Bun, Node.js, and Deno
+
+## Supported Diagram Types
+
+- **Flowchart** (`flowchart`, `graph`)
+- **Sequence Diagram** (`sequenceDiagram`)
+
+## Installation
+
+```bash
+# Bun
+bun add mermaid-ast
+
+# npm
+npm install mermaid-ast
+
+# pnpm
+pnpm add mermaid-ast
+```
+
+## Usage
+
+### Basic Parsing and Rendering
+
+```typescript
+import { parse, render } from "mermaid-ast";
+
+// Parse any supported diagram
+const ast = parse(`flowchart LR
+    A[Start] --> B{Decision}
+    B -->|Yes| C[OK]
+    B -->|No| D[Cancel]`);
+
+// Render back to Mermaid syntax
+const output = render(ast);
+```
+
+### Flowchart Diagrams
+
+```typescript
+import { parseFlowchart, renderFlowchart } from "mermaid-ast";
+
+const ast = parseFlowchart(`flowchart TD
+    A[Start] --> B{Is it working?}
+    B -->|Yes| C[Great!]
+    B -->|No| D[Debug]
+    D --> B`);
+
+// Access AST properties
+console.log(ast.direction); // "TD"
+console.log(ast.nodes.size); // 4
+console.log(ast.links.length); // 4
+
+// Modify the AST
+ast.nodes.get("A")!.text = { text: "Begin", type: "text" };
+
+// Render back
+const output = renderFlowchart(ast);
+```
+
+### Sequence Diagrams
+
+```typescript
+import { parseSequence, renderSequence } from "mermaid-ast";
+
+const ast = parseSequence(`sequenceDiagram
+    participant A as Alice
+    participant B as Bob
+    A->>B: Hello Bob!
+    B-->>A: Hi Alice!`);
+
+// Access AST properties
+console.log(ast.actors.size); // 2
+console.log(ast.statements.length); // 2
+
+// Render back
+const output = renderSequence(ast);
+```
+
+### Diagram Type Detection
+
+```typescript
+import { detectDiagramType } from "mermaid-ast";
+
+detectDiagramType("flowchart LR\n  A --> B"); // "flowchart"
+detectDiagramType("sequenceDiagram\n  A->>B: Hi"); // "sequence"
+detectDiagramType("unknown diagram"); // null
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `parse(input: string): MermaidAST` | Parse any supported diagram |
+| `render(ast: MermaidAST): string` | Render any supported AST |
+| `detectDiagramType(input: string): DiagramType \| null` | Detect diagram type |
+
+### Flowchart Functions
+
+| Function | Description |
+|----------|-------------|
+| `parseFlowchart(input: string): FlowchartAST` | Parse flowchart diagram |
+| `renderFlowchart(ast: FlowchartAST): string` | Render flowchart AST |
+| `isFlowchartDiagram(input: string): boolean` | Check if input is flowchart |
+
+### Sequence Diagram Functions
+
+| Function | Description |
+|----------|-------------|
+| `parseSequence(input: string): SequenceAST` | Parse sequence diagram |
+| `renderSequence(ast: SequenceAST): string` | Render sequence AST |
+| `isSequenceDiagram(input: string): boolean` | Check if input is sequence |
+
+## Supported Flowchart Features
+
+- **Directions**: LR, RL, TB, TD, BT
+- **Node shapes**: Rectangle, rounded, diamond, stadium, subroutine, cylinder, circle, asymmetric, rhombus, hexagon, parallelogram, trapezoid, double-circle
+- **Link types**: Arrow, open, cross, circle
+- **Link strokes**: Normal, thick, dotted
+- **Link labels**: Text on connections
+- **Subgraphs**: With titles and directions
+- **Styling**: `classDef`, `class`, `style`, `linkStyle`
+- **Interactions**: `click` handlers with callbacks or URLs
+
+## Supported Sequence Diagram Features
+
+- **Participants/Actors**: With aliases
+- **Message types**: Solid/dashed lines, arrows/open ends, async
+- **Activations**: `activate`/`deactivate`
+- **Control flow**: `loop`, `alt`/`else`, `opt`, `par`, `critical`, `break`
+- **Grouping**: `rect` backgrounds
+- **Notes**: `note left of`, `note right of`, `note over`
+- **Actor lifecycle**: `create`, `destroy`
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) runtime
+
+### Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run specific test suites
+bun test tests/unit          # Unit tests
+bun test tests/roundtrip     # Round-trip tests
+bun test tests/compatibility # Mermaid.js compatibility tests
+
+# Type checking
+bun run typecheck
+
+# Build
+bun run build
+```
+
+### Using the Justfile
+
+If you have [just](https://github.com/casey/just) installed:
+
+```bash
+just mermaid-ast test              # Run all tests
+just mermaid-ast test-roundtrip    # Run round-trip tests
+just mermaid-ast dagger-test-all   # Test in all runtimes via Dagger
+just mermaid-ast sync-parsers 11.4.2  # Sync parsers from mermaid version
+```
+
+## Updating Mermaid Parsers
+
+This library vendors JISON parsers from mermaid.js. To update to a new mermaid version:
+
+```bash
+# Sync from a specific version
+bun run sync-parsers -- 11.4.2
+
+# Or using just
+just mermaid-ast sync-parsers 11.4.2
+```
+
+The sync script will:
+1. Clone the specified mermaid version
+2. Extract the JISON grammar files
+3. Compile them to JavaScript parsers
+4. Update the VERSION file
+5. Run tests to verify compatibility
+
+### Manual Update Process
+
+If you need to update manually:
+
+1. Check the [mermaid releases](https://github.com/mermaid-js/mermaid/releases) for the target version
+2. Run the sync script with that version
+3. Run the full test suite to verify compatibility
+4. Review any failing tests - they may indicate breaking changes in the grammar
+
+## Architecture
+
+```
+mermaid-ast/
+├── src/
+│   ├── parser/           # Diagram parsers
+│   │   ├── flowchart-parser.ts
+│   │   └── sequence-parser.ts
+│   ├── renderer/         # AST to text renderers
+│   │   ├── flowchart-renderer.ts
+│   │   └── sequence-renderer.ts
+│   ├── types/            # TypeScript type definitions
+│   │   ├── flowchart.ts
+│   │   └── sequence.ts
+│   └── vendored/         # Vendored mermaid parsers
+│       ├── grammars/     # Original JISON grammar files
+│       └── parsers/      # Compiled JavaScript parsers
+├── tests/
+│   ├── unit/             # Unit tests for parser/renderer
+│   ├── roundtrip/        # Round-trip verification tests
+│   └── compatibility/    # Mermaid.js SVG compatibility tests
+└── scripts/
+    └── sync-parsers.ts   # Parser sync script
+```
+
+## License
+
+MIT
+
+---
+
+## How This Library Was Built
+
+This library was built entirely through conversation with [Slate](https://randomlabs.ai), an AI coding assistant. Below are the prompts used:
+
+### Initial Request
+
+> I want a TypeScript library to parse and render Mermaid AST, with extensive unit tests, support for the entire syntax supported by the current version of mermaid-js, tests that show specifically that mermaid.js produces absolutely the same output for before-the-roundtrip and after-the-roundtrip diagrams, and documentation on how to bring itself up to date with newer versions of mermaid.js.
+
+### Runtime & Scope
+
+> go with bun
+>
+> tests in Dagger that demonstrate that it works the same in bun, deno, and node.js
+>
+> subset for now
+>
+> depend, sure (on @mermaid-js/parser)
+
+### Parser Approach
+
+> absolutely you must not use any regex approach whatsoever
+>
+> study the mermaidjs/parser package thoroughly
+>
+> ok please study first how mermaidjs parses diagrams and then we'll discuss
+>
+> ok but would you vendor the parsers and have like a script to re-vendor, or what would you do? how's it done usually?
+>
+> lets have a sync script ok
+
+### Project Setup
+
+> all these commands must be in justfile in mermaid-ast/
+>
+> can we make it work from the root?
+
+### Quality Check
+
+> ok cool now tell me if theres any tech debt or like anything halfassed
+
+### Final Polish
+
+> ok cool do 1 2, no need for 3, need everything in 5, need 6, need 7. make a todo list then discuss
+>
+> use mermaid js rendering to svg. readme should include just implemented. for (3) explain how exactly it happened
+
+### Publishing
+
+> create a repo in neongreen github and move the package there
+>
+> and make it private at first
+>
+> ok now finally in ~/code/mermaid-ast/AGENTS.md please document how this library was made etc. because i'm going to start a new agent there to continue work
+>
+> add a badge there: proudly built with Slate. and include my prompts from this convo

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * mermaid-ast
+ *
+ * A library for parsing and rendering Mermaid diagrams to/from AST.
+ *
+ * @example
+ * ```typescript
+ * import { parse, render } from "mermaid-ast";
+ *
+ * const diagram = `
+ * flowchart LR
+ *   A[Start] --> B[End]
+ * `;
+ *
+ * const ast = parse(diagram);
+ * const output = render(ast);
+ * ```
+ */
+export * from "./types/index.js";
+export { parse, parseFlowchart, parseSequence, detectDiagramType, isFlowchartDiagram, isSequenceDiagram, } from "./parser/index.js";
+export { render, renderFlowchart, renderSequence, } from "./renderer/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,KAAK,EACL,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,MAAM,EACN,eAAe,EACf,cAAc,GACf,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * mermaid-ast
+ *
+ * A library for parsing and rendering Mermaid diagrams to/from AST.
+ *
+ * @example
+ * ```typescript
+ * import { parse, render } from "mermaid-ast";
+ *
+ * const diagram = `
+ * flowchart LR
+ *   A[Start] --> B[End]
+ * `;
+ *
+ * const ast = parse(diagram);
+ * const output = render(ast);
+ * ```
+ */
+// Export types
+export * from "./types/index.js";
+// Export parser functions
+export { parse, parseFlowchart, parseSequence, detectDiagramType, isFlowchartDiagram, isSequenceDiagram, } from "./parser/index.js";
+// Export renderer functions (to be implemented)
+export { render, renderFlowchart, renderSequence, } from "./renderer/index.js";

package/dist/parser/flowchart-parser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Flowchart Parser
+ *
+ * Parses Mermaid flowchart syntax into an AST using the vendored JISON parser.
+ * The JISON parser calls methods on a `yy` object - we provide our own implementation
+ * that builds an AST instead of mermaid's internal db structure.
+ */
+import { type FlowchartAST } from "../types/flowchart.js";
+/**
+ * Parse a flowchart diagram string into an AST
+ */
+export declare function parseFlowchart(input: string): FlowchartAST;
+/**
+ * Detect if input is a flowchart diagram
+ */
+export declare function isFlowchartDiagram(input: string): boolean;
+//# sourceMappingURL=flowchart-parser.d.ts.map

package/dist/parser/flowchart-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowchart-parser.d.ts","sourceRoot":"","sources":["../../src/parser/flowchart-parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,KAAK,YAAY,EAalB,MAAM,uBAAuB,CAAC;AA+Z/B;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAkB1D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQzD"}