Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

5.0 KB
Raw Blame
#!/usr/bin/env python3
"""Validate Mermaid diagram syntax in Markdown files by rendering them with Pele.

Every ```mermaid block under the current directory is rendered with the same
pinned, sha256-verified Pele bundle that the website and the EPUB use, so a
block that passes here renders there too. Identical blocks are rendered once.

Strict mode (``--strict``, or ``PELE_REQUIRED`` / ``CI`` set to 1/true/yes)
fails when Pele cannot run (Node.js >= 20 missing, bundle download or checksum
failure) and when no Mermaid block is found at all. Without strict mode a
missing Pele only prints a warning, so a contributor without Node.js can still
commit; CI and the pre-commit hooks run strict.
"""

from __future__ import annotations

import argparse
import logging
import os
import re
import sys
from collections import Counter
from dataclasses import dataclass
from pathlib import Path

# Make sibling script modules importable regardless of cwd.
sys.path.insert(0, str(Path(__file__).parent))

from pele_renderer import (
    MIN_NODE_MAJOR,
    PeleHelperError,
    PeleUnavailableError,
    render_diagrams,
)
from vendor_assets import PELE_VERSION

IGNORE_DIRS = {".venv", "node_modules", ".git", "blog-posts", ".agents"}
MERMAID_BLOCK_RE = re.compile(r"```mermaid\n(.*?)```", re.DOTALL)
TRUTHY = {"1", "true", "yes"}


@dataclass(frozen=True)
class MermaidBlock:
    """One ```mermaid block: where it is and what it contains."""

    path: Path
    line: int
    index: int
    source: str


def _env_truthy(name: str) -> bool:
    return os.environ.get(name, "").strip().lower() in TRUTHY


def is_strict(flag: bool) -> bool:
    """Strict when asked on the command line or when running in CI."""
    return flag or _env_truthy("PELE_REQUIRED") or _env_truthy("CI")


def find_markdown_files(root: Path) -> list[Path]:
    """All Markdown files under `root`, minus IGNORE_DIRS, in a stable order."""
    return sorted(
        f
        for f in root.rglob("*.md")
        if not any(part in IGNORE_DIRS for part in f.parts)
    )


def extract_blocks(path: Path) -> list[MermaidBlock]:
    """Return every ```mermaid block in `path` with its fence line number."""
    content = path.read_text(encoding="utf-8")
    return [
        MermaidBlock(
            path=path,
            line=content.count("\n", 0, match.start()) + 1,
            index=index,
            source=match.group(1),
        )
        for index, match in enumerate(MERMAID_BLOCK_RE.finditer(content), start=1)
    ]


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Validate Mermaid diagrams in Markdown files with Pele."
    )
    parser.add_argument(
        "--strict",
        action="store_true",
        help="fail when Pele cannot run or no Mermaid block is found "
        "(also enabled by PELE_REQUIRED or CI)",
    )
    args = parser.parse_args(argv)
    strict = is_strict(args.strict)

    md_files = find_markdown_files(Path())
    blocks = [block for path in md_files for block in extract_blocks(path)]
    if not blocks:
        if strict:
            print(
                f"❌ No Mermaid blocks found in {len(md_files)} Markdown file(s) "
                "— refusing a vacuous pass in strict mode"
            )
            return 1
        print("✅ No Mermaid blocks found")
        return 0
    return validate_blocks(blocks, strict=strict)


def validate_blocks(blocks: list[MermaidBlock], *, strict: bool) -> int:
    """Render the unique sources once and report failures per block."""
    unique_sources = list(dict.fromkeys(block.source for block in blocks))
    logger = logging.getLogger("check_mermaid")
    try:
        results = render_diagrams(unique_sources, logger)
    except PeleUnavailableError as exc:
        if strict:
            print(f"❌ Pele is unavailable: {exc}")
            return 1
        print(
            f"⚠ Pele is unavailable ({exc}) — skipping Mermaid validation "
            f"(install Node.js >= {MIN_NODE_MAJOR})"
        )
        return 0
    except PeleHelperError as exc:
        print(f"❌ Pele helper failed: {exc}")
        return 1

    by_source = dict(zip(unique_sources, results, strict=True))
    errors = []
    for block in blocks:
        error = by_source[block.source].error
        if error is not None:
            errors.append(
                f"{block.path}:{block.line} (block {block.index}): {error.describe()}"
            )

    if errors:
        print(f"❌ Pele {PELE_VERSION} rejected {len(errors)} Mermaid block(s):")
        for message in errors:
            print(f"  - {message}")
        return 1

    types = Counter(r.diagram_type or "unknown" for r in results)
    summary = ", ".join(f"{name} {count}" for name, count in sorted(types.items()))
    files = len({block.path for block in blocks})
    print(
        f"✅ Pele {PELE_VERSION} rendered {len(blocks)} Mermaid block(s) "
        f"({len(unique_sources)} unique) from {files} file(s): {summary}"
    )
    return 0


if __name__ == "__main__":
    sys.exit(main())