English | Русский

Mermaid Guard

Mermaid Guard is a deterministic, line-based heuristic linter, guardrail, and conservative repair tool for Mermaid diagrams. It is useful in CI/CD, pre-commit checks, AI agent workflows, and development that needs instant local validation.

It is not a complete Mermaid grammar parser, a renderer, or a promise that every accepted diagram will render in every Mermaid release. The tool reports the scope of its checks and leaves uncertain input unchanged.

Capabilities

The heuristic scope currently covers:

• flowchart and graph headers, including basic quote and delimiter balance checks and subgraph blocks;

• sequenceDiagram headers, including nested alt, opt, loop, critical, par, rect, box, and break blocks;

• basic recognition of stateDiagram and classDiagram headers;

• Markdown files containing one or more mermaid fenced blocks;

• UTF-8 input, UTF-8 BOM, and CRLF or LF line endings.

Other Mermaid diagram families are reported as unsupported or unknown rather than being silently treated as flowcharts. The linter does not attempt full grammar validation, participant inference, or renderer compatibility checks.

Repair is non-destructive:

• a missing header is added only when an explicit expected type and strong diagram-like syntax make that inference reasonably safe;

• unclosed sequence blocks and simple flowchart delimiters may be completed;

• autonumber is not a mandatory repair and is never inserted just because it is absent;

• prose, unsupported types, orphan blocks, ambiguous delimiters, and a type mismatch retain the original source and produce a failed repair result;

• no generic skeleton is substituted for user input.

Related MCP server: Mermaid Lint MCP

Requirements

• Python 3.9 or newer;

• the core package has no mandatory runtime dependencies.

Installation

python -m pip install .

Install the development tools without optional model integrations:

python -m pip install ".[dev]"

Install only the integration needed for the selected provider:

python -m pip install ".[ai]"
python -m pip install ".[openai]"
python -m pip install ".[ollama]"
python -m pip install ".[env]"

ai installs the OpenAI-compatible LangChain integration used by the openai, deepseek, and custom providers. ollama installs the separate Ollama integration. Core linting, repair, Markdown handling, and offline synthesis do not import those extras.

Command-line usage

The installed command is mermaid-repair. The module form python -m mermaid_repair.cli is also supported.

mermaid-repair --version
mermaid-repair lint diagram.mmd
mermaid-repair lint document.md --json
mermaid-repair repair diagram.mmd --output fixed.mmd
mermaid-repair repair diagram.mmd --output fixed.mmd --force
mermaid-repair generate "Collect an order, validate payment, and send a receipt" --type flowchart

lint accepts regular .mmd and .mermaid files or Markdown files. For Markdown, every mermaid fenced block is checked and diagnostics use the original file line and column. A file without a Mermaid block is an error; prose is not accepted as a diagram. File inputs default to a 1 MiB byte limit; use --max-bytes to choose a different positive limit.

repair preserves Markdown prose and non-Mermaid fenced blocks. It only changes Mermaid block contents. Existing output paths are not overwritten without --force; output is written through a temporary file and an atomic replace. An input and output path that resolve to the same file is rejected unless --force is explicit.

Exit status values are stable for CI use:

• 0: requested operation completed without heuristic errors;

• 1: lint or repair found residual errors, or repair was intentionally not applied;

• 2: invalid arguments, input/output error, or unsafe path;

• 3: an explicitly requested LLM path used deterministic fallback.

A provider or model option without --llm is an error. A missing optional integration, credential, or LLM service is not reported as a successful LLM generation.

Python API

The original string API remains available:

from mermaid_repair import MermaidLinter

valid, messages = MermaidLinter.validate_mermaid(
    "sequenceDiagram\n    actor User\n    participant API\n"
)

For diagnostics that retain codes, severity, and source positions, use the structured API:

from mermaid_repair import MermaidLinter

report = MermaidLinter.validate_mermaid_report(
    "sequenceDiagram\n    actor User\n    alt Login\n",
    filename="login.mmd",
)
for diagnostic in report.diagnostics:
    print(diagnostic.severity, diagnostic.code, diagnostic.line, diagnostic.column)

A repair result makes the outcome explicit:

from mermaid_repair import MermaidLinter

result = MermaidLinter.repair_mermaid(
    "sequenceDiagram\n    actor User\n    alt Login\n",
    expected_type="sequence",
    filename="login.mmd",
)
if not result.success:
    print(result.text)
    print(result.warnings)
else:
    print(result.text)
    print(result.changes)

MermaidLinter.sanitize_and_repair(code) is retained for callers that need a string. It returns the original text when a safe repair cannot be made. Use repair_mermaid or repair_document when the caller needs to inspect success, diagnostics, changes, and warnings.

For a Markdown string:

from mermaid_repair import MermaidLinter

result = MermaidLinter.repair_document(
    markdown_text,
    file_format="markdown",
)
if result.success:
    updated_markdown = result.text

Offline synthesis

Without an LLM, the synthesizer extracts deterministic steps from process_description and uses them as labels or messages. It does not contact a network service:

from mermaid_repair.synthesizer import generate_flowchart

diagram = generate_flowchart(
    "Receive a support ticket. Assign an agent. Send a confirmation email."
)

The generated text is passed through the same heuristic repair checks. This is a deterministic transformation; it does not establish semantic completeness or correctness of the description.

Optional LLM providers

The factory creates LangChain-compatible clients only when their optional integration and credentials are available:

from mermaid_repair.llm import get_llm

llm = get_llm(
    provider="deepseek",
    model="deepseek-chat",
    api_key="explicit-key",
    timeout=30,
    max_tokens=800,
    max_retries=1,
)

Provider credentials are isolated: openai uses OPENAI_API_KEY, deepseek uses DEEPSEEK_API_KEY, and custom uses CUSTOM_API_KEY. An OpenAI key is never used as a fallback for DeepSeek or a custom endpoint. Unknown providers raise ValueError. Automatic provider selection uses available environment variables in a fixed order, so production callers should normally specify the provider explicitly.

Environment files are not loaded at import time. Loading is explicit:

llm = get_llm(
    provider="openai",
    load_env=True,
    env_file=".env",
)

The env extra is required for that form. The equivalent CLI form is mermaid-repair generate ... --llm --load-env --env-file .env.

An LLM request sends the supplied process description and title to the selected provider or endpoint. Do not put secrets, personal data, or confidential source code in a description unless that transmission is intended and approved. The tool does not log API keys. Provider availability, retention, and privacy policies remain the responsibility of the selected service.

External Verification & Status Semantics

While the core linter operates entirely in-process using fast Python heuristics, an optional authoritative verification adapter is available:

from mermaid_repair.verifier import MermaidCliVerifier

verifier = MermaidCliVerifier()
result = verifier.verify("flowchart TD\nA-->B")
print(result.status)  # 'verified' (if mmdc installed) or 'unverified'

If mermaid-cli (mmdc) is not installed, the tool gracefully reports status = "unverified" instead of falsely claiming renderability. See ARCHITECTURE.md for details.

Model Context Protocol (MCP)

Mermaid Flow Repair provides native tools for AI Agents and MCP runners:

• validate_mermaid: In-process linting with exact line and column diagnostics.

• repair_mermaid: Conservative, non-destructive syntax repair.

• validate_markdown: Multi-block documentation linting.

• verify_external_mermaid: Authoritative rendering check via mmdc.

Run as an MCP tool provider:

python -m mermaid_repair.mcp.server

Development

python -m pip install ".[dev]"
ruff check src tests examples
mypy
python -m pytest -p no:cacheprovider
python -m pytest -p no:cacheprovider --cov=mermaid_repair --cov-report=term-missing

Run tests with PYTHONDONTWRITEBYTECODE=1 when the working tree must remain free of Python cache files. The CI workflow tests the core package in a clean environment and does not require an LLM key.

License

MIT. See LICENSE.