Figurehead

A Rust utility to convert Mermaid.js diagram markup into ASCII diagrams, inspired by mermaid-ascii.

Ideas: add a small banner/screenshot of a rendered flowchart once we have more diagram types; a light/dark pair of ASCII captures would fit the theme. Swap the crates.io/docs.rs badges to live ones after publishing.

Features

🎨 Convert Mermaid.js flowcharts to ASCII art
🔧 Modular, plugin-based architecture inspired by mermaid.js
🚀 Fast parsing using chumsky
🧪 Test-Driven Development approach
🌐 WASM-compatible core library (future browser support)
🎯 SOLID principles and Rust idioms

Architecture

Figurehead follows a modular pipeline architecture:

Input → Detector → Parser → Database → Layout → Renderer → Output

Core Components

Detector: Identifies diagram types from markup patterns
Parser: Parses markup into structured data using chumsky
Database: Stores diagram nodes and edges
Layout: Arranges elements in coordinate space (Dagre-inspired)
Renderer: Generates ASCII output

Diagram Types

Currently supported:

Flowchart with subgraphs (single-level nesting)
Git graphs
Sequence diagrams
Class diagrams (with relationships)

Planned:

Nested subgraphs
Styling with terminal colors

Quick Start

For layout/rendering review targets, see docs/ideal-output/.

CLI Usage

# Basic conversion
echo "graph TD\n    A --> B" | figurehead

# Choose output character set (ascii|unicode|unicode-math|compact)
figurehead convert --style ascii -i input.mmd

# Output to file
figurehead -i input.mmd -o output.txt

# Respect FIGUREHEAD_STYLE environment variable
FIGUREHEAD_STYLE=compact figurehead convert -i input.mmd

# Enable debug logging
figurehead convert --log-level debug --log-format pretty -i input.mmd

# Use environment variables for logging
FIGUREHEAD_LOG_LEVEL=debug FIGUREHEAD_LOG_FORMAT=json figurehead convert -i input.mmd

Library Usage

use figurehead::{plugins::flowchart::FlowchartDiagram, core::Diagram};

// Create a flowchart diagram
let diagram = FlowchartDiagram;

// Create parser and database
let mut parser = diagram.create_parser();
let mut database = diagram.create_database();

// Parse some markup
parser.parse("graph TD\n    A --> B", &mut database)?;

// Render to ASCII
let renderer = diagram.create_renderer();
let output = renderer.render(&database)?;
println!("{}", output);

Subgraph Support

Figurehead supports single-level subgraphs to group related nodes:

echo 'graph LR
    subgraph "Backend"
        API --> DB
    end
    Client --> API' | figurehead convert -i -

Output:

            ┌── Backend ───┐
┌────────┐  │ ┌─────┐ ┌────┐ │
│ Client │──┼▶│ API │─▶│ DB │ │
└────────┘  │ └─────┘ └────┘ │
            └────────────────┘

Limitations:

Only single-level nesting is supported (nested subgraphs are flattened)
Subgraph borders may overlap if their nodes are not visually separated

Logging

Figurehead includes comprehensive structured logging using the tracing crate. This helps with debugging diagram processing and understanding performance.

Log Levels

trace: Very detailed information for deep debugging
debug: Detailed information for debugging (recommended for development)
info: General informational messages (default)
warn: Warning messages
error: Error messages only

Log Formats

compact: Single-line format, good for production (default)
pretty: Multi-line format with colors, good for development
json: JSON format, good for log aggregation systems

Usage Examples

# Enable debug logging with pretty format
figurehead convert --log-level debug --log-format pretty -i input.mmd

# Use environment variables (overrides CLI flags)
FIGUREHEAD_LOG_LEVEL=trace FIGUREHEAD_LOG_FORMAT=json figurehead convert -i input.mmd

# Filter logs by component
RUST_LOG="figurehead::plugins::flowchart::parser=debug" figurehead convert -i input.mmd

Debugging with Logs

When debugging diagram processing issues, enable debug logging to see:

Detection: Which diagram type was detected and confidence scores
Parsing: Parsing stages, node/edge counts, and any skipped statements
Layout: Layer assignment, node positioning, edge routing, and canvas dimensions
Rendering: Canvas creation, nodes/edges drawn, and final output size

Example output with --log-level debug --log-format pretty:

INFO  figurehead::plugins::orchestrator: Starting diagram processing pipeline
DEBUG figurehead::plugins::orchestrator: Diagram type detected diagram_type=flowchart
DEBUG figurehead::plugins::flowchart::parser: Parsing completed node_count=3 edge_count=2
DEBUG figurehead::plugins::flowchart::layout: Layout completed node_count=3 edge_count=2 width=45 height=12
DEBUG figurehead::plugins::flowchart::renderer: Rendering completed output_len=234 canvas_width=45 canvas_height=12
INFO  figurehead::plugins::orchestrator: Pipeline completed successfully

Development

Building

cargo build
cargo test

Running Tests

# All tests
cargo test

# Core trait tests
cargo test --test core_traits

# Run with colors
cargo test -- --nocapture

# Run with logging enabled
RUST_LOG=debug cargo test

Project Structure

src/
├── core/           # Core trait abstractions
├── plugins/        # Diagram type implementations
│   └── flowchart/  # Flowchart plugin
├── layout/         # Layout algorithms
├── rendering/      # Rendering implementations
└── cli/           # CLI interface
tests/
└── core_traits.rs  # Core functionality tests

WASM Support

The core library is fully WASM-compatible and includes a web example:

Building WASM Module

# Install wasm-pack if needed
cargo install wasm-pack

# Build for web
cd examples/web
./build.sh

Running Web Example

# Build WASM module
cd examples/web
./build.sh

# Serve with Rust HTTP server
cargo run --bin server
# Then visit http://localhost:8000/

The web examples provide:

Interactive Editor (index.html): Full-featured editor with examples
Live Editor (editor.html): Minimal split-pane editor with real-time updates
Multiple character set styles
Parse-only mode to inspect diagram structure

See examples/web-editor/README.md for more details.

Dependencies

chumsky - Parsing library
clap - CLI framework
crossterm - Terminal handling
anyhow - Error handling
thiserror - Error types
unicode-width - Text width calculation

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

See AGENTS.md for development guidelines.

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by mermaid-ascii
Architecture inspired by mermaid.js
Built with the Rust ecosystem

figurehead 0.3.1