Rusty Mermaid Validator

rusty-mermaid is a high-performance command-line tool and WebAssembly library for validating the syntax of Mermaid diagrams. It helps ensure your diagrams are syntactically correct and can be rendered by Mermaid.js.

Features

• Fast Validation: Built in Rust for speed.
• Comprehensive Syntax Checking: Validates various diagram types including:
  • Flowcharts
  • Sequence Diagrams
  • Class Diagrams
  • State Diagrams
  • (More to come!)
• Detailed Error Reporting: Provides line and column numbers for errors.
• Multiple Output Formats: Human-readable, JSON, and compact formats.
• Recursive Directory Validation: Validate all Mermaid files in a directory.
• Direct String Input: Validate Mermaid diagrams passed directly as strings.
• Strict Validation: Treats all warnings as errors, ensuring high code quality.
• WebAssembly Support: Use in Node.js and browser environments.
• npm Package: Easy integration with JavaScript/TypeScript projects.

Installation

Prerequisites

• Rust (latest stable version)

From Source

1. Clone the repository:

   git clone https://github.com/yourusername/rusty-mermaid.git
   cd rusty-mermaid

2. Build the project:

   cargo build --release

3. The executable will be located at target/release/rusty-mermaid. You can copy it to a directory in your PATH, e.g., ~/.cargo/bin/ or /usr/local/bin.

From Crates.io (Once Published)

cargo install rusty-mermaid

Node.js/npm Package

npm install rusty-mermaid-wasm
# or
yarn add rusty-mermaid-wasm
# or
pnpm add rusty-mermaid-wasm

Usage

Command Line Interface

rusty-mermaid [OPTIONS] [FILE_OR_DIRECTORY]
rusty-mermaid [OPTIONS] --input <STRING>

Arguments

• <FILE_OR_DIRECTORY>: Path to the Mermaid diagram file (.mmd or .mermaid) or a directory containing Mermaid files. Required unless --input is provided.

Options

• -i, --input <STRING>: Direct Mermaid diagram string to validate. Cannot be used with <FILE_OR_DIRECTORY>.
• -f, --format <FORMAT>: Output format.
  • human (default): Human-readable output.
  • json: JSON output for machine processing.
  • compact: Compact output, suitable for editor integrations (e.g., filename:line:col: level: message).
• -q, --quiet: Suppress warnings.
• -v, --verbose: Verbose output, showing files being processed.
• -r, --recursive: Validate all .mmd and .mermaid files recursively in the specified directory.
• -h, --help: Print help information.
• -V, --version: Print version information.

Examples

• Validate a single file:

  rusty-mermaid my_diagram.mmd

• Validate all Mermaid files in a directory:

  rusty-mermaid ./diagrams/

• Validate recursively with JSON output:

  rusty-mermaid -r --format json ./project/docs/

• Validate a diagram string directly:

  rusty-mermaid --input "graph TD; A-->B;"

• Validate a diagram string with JSON output:

  rusty-mermaid --input "flowchart LR; Start-->End;" --format json

Node.js/JavaScript Usage

const mermaid = require('rusty-mermaid-wasm');

// Validate a Mermaid diagram
const diagram = `
graph TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    B -->|No| D[End]
`;

// Get detailed validation results
const result = mermaid.validateMermaid(diagram);
console.log(result);
// Output: { errors: [], warnings: [], is_valid: true }

// Simple boolean check
const isValid = mermaid.isValidMermaid(diagram);
console.log(isValid); // Output: true

// Get JSON string result
const jsonResult = mermaid.validateMermaidJson(diagram);

See wasm-readme.md for detailed Node.js API documentation.

Development

Running Tests

cargo test

Building

cargo build

Building WebAssembly Module

1. Install prerequisites:

   # Install wasm-pack
   curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

2. Build the WASM module:

   # Using the build script
   ./build-wasm.sh
      
   # Or manually
   wasm-pack build --target nodejs --out-dir pkg --features wasm --no-default-features

3. Test the Node.js module:

   npm test

The build process creates:

• pkg/ - Node.js-compatible WASM module
• pkg-web/ - Browser-compatible WASM module with demo

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Future Work

• Support for more diagram types.
• More granular validation rules.
• Integration with language servers.
• Auto-fixing for common simple errors.
• Browser extension for live validation.
• VS Code extension using WASM.

Performance

The WASM module provides near-native performance:

• ~0.1ms average validation time for simple diagrams
• ~1ms for complex diagrams with multiple subgraphs
• Minimal memory footprint
• Zero JavaScript dependencies