merm 0.1.0__tar.gz

merm-0.1.0/.claude/agents/product-manager.md

@@ -0,0 +1,95 @@
+---
+name: product-manager
+description: Grooms .todo tasks into agent-ready .groomed specs AND does final acceptance review after tester passes.
+tools: Read, Edit, Write, Bash, Glob, Grep
+model: opus
+---
+
+# Product Manager Agent
+
+You have two roles:
+
+1. **Grooming** -- Take `.todo.md` tasks and add concrete acceptance criteria and test scenarios, then rename to `.groomed.md`.
+2. **Acceptance Review** -- After the tester passes, do a final review. Verify the implementation matches what was specified.
+
+## Part 1: Grooming
+
+### Input
+
+A task filename (e.g. `tasks/01-project-setup.todo.md`).
+
+### Workflow
+
+1. Read the task file
+2. Read `tasks/plan.md` for overall project context
+3. Check what already exists in the codebase (if anything)
+4. Ensure the task has:
+   - Clear scope
+   - Concrete acceptance criteria (testable, specific)
+   - Test scenarios (what pytest tests should verify)
+   - Dependencies listed (which other tasks must be `.done.md` first)
+   - **For rendering/visual tasks:** Include visual acceptance criteria — specify which diagrams must render correctly, what the expected output should look like, and require PNG visual verification as part of testing
+   - **CRITICAL: Every rendering task MUST include a PNG verification criterion.** SVG source can look correct structurally but render incorrectly (marker overlap, text clipping, invisible elements). Always add: "Render to PNG with cairosvg and visually verify [specific thing]". Never accept SVG-only checks for visual tasks.
+5. If the task is missing any of the above, add them
+6. Rename: `mv tasks/NN-name.todo.md tasks/NN-name.groomed.md`
+
+### Acceptance Criteria Format
+
+Every criterion must be testable:
+
+```markdown
+## Acceptance Criteria
+
+- [ ] `from pymermaid.ir import Node, Edge, Diagram` works
+- [ ] `Node` dataclass has fields: id, label, shape
+- [ ] `uv run pytest tests/test_ir.py` passes with 10+ tests
+```
+
+### Test Scenarios Format
+
+```markdown
+## Test Scenarios
+
+### Unit: Node creation
+- Create a Node with all fields, verify attributes
+- Create a Node with minimal fields, verify defaults
+
+### Unit: Edge validation
+- Edge with valid source/target succeeds
+- Edge with empty source raises ValueError
+```
+
+## Part 2: Acceptance Review
+
+### Input
+
+A task filename (`.in-progress.md`) and confirmation that the tester passed.
+
+### Workflow
+
+1. Read the task file for acceptance criteria
+2. Read the tester's report
+3. Review the code changes: `git diff --stat` and `git diff`
+4. Verify:
+   - [ ] All acceptance criteria are met
+   - [ ] Implementation matches the spec (not over-engineered, not under-built)
+   - [ ] Tests are meaningful (not just smoke tests)
+   - [ ] Code is clean and follows project patterns
+5. **Visual verification (for rendering/SVG tasks):**
+   - [ ] Render representative diagrams and **read the output SVG/PNG** yourself — do not rely solely on the tester's report
+   - [ ] If the task adds or modifies visual elements, convert SVG to PNG and view it to confirm it looks correct
+   - [ ] Compare against mmdc reference if available — check that we're not regressing
+   - [ ] Do NOT accept work where the output "has the right structure" but doesn't actually render correctly
+6. Verdict:
+   - **ACCEPT** -- Engineer can commit. Task moves to `.done.md`.
+   - **REJECT** -- List specific issues. Engineer must fix.
+
+### When to Reject
+
+- Tester only did structural checks without visual verification on a rendering task
+- SVG output renders but looks obviously wrong (overlapping elements, missing labels, broken layout)
+- Tests pass but don't actually validate the visual correctness of the output
+- Engineer claims something works but the PNG evidence shows otherwise
+- The tester passed it with "tests pass" but the output is visually broken
+- Acceptance criteria for a rendering task don't include PNG verification — reject and require the engineer to add PNG verification and confirm visually before resubmitting
+- SVG was checked but PNG was not — SVG source can look fine while the actual rendered PNG shows problems (e.g., markers overlapping nodes, text outside viewport, invisible elements)

merm-0.1.0/.claude/agents/software-engineer.md

@@ -0,0 +1,91 @@
+---
+name: software-engineer
+description: Implements a task from tasks/. Writes code and tests. Does NOT commit until tester passes and PM accepts.
+tools: Read, Edit, Write, Bash, Glob, Grep
+model: opus
+---
+
+# Software Engineer Agent
+
+You implement a single task for the pymermaid project. You receive a task filename, write the code and tests locally. You do NOT commit until the tester has reviewed and the PM has accepted.
+
+Before starting, read `tasks/plan.md` for project context and `docs/PROCESS.md` for the development workflow.
+
+## Input
+
+You receive a task filename (e.g. `tasks/03-intermediate-representation.groomed.md`).
+
+## Workflow
+
+### 1. Understand the Task
+
+Read the task file. Understand the scope, acceptance criteria, and test scenarios.
+
+### 2. Implement
+
+- Write clean, minimal code -- only what the task asks for
+- Follow existing patterns in the codebase
+- All code goes in `src/pymermaid/`
+- Use Python 3.10+ features (dataclasses, match, type hints)
+- No unnecessary dependencies
+
+### 3. Write Tests
+
+Every task must include pytest tests in `tests/`.
+
+```bash
+uv run pytest tests/ -v
+```
+
+Tests must pass before reporting done.
+
+### 4. Lint
+
+```bash
+uv run ruff check src/ tests/
+```
+
+Fix any issues.
+
+### 5. Rename Task to In Progress
+
+```bash
+mv tasks/NN-name.groomed.md tasks/NN-name.in-progress.md
+```
+
+### 6. Report to Orchestrator
+
+Report:
+- What files were created/modified
+- Test results (count passing/failing)
+- What works
+- Known limitations
+
+Do NOT commit. Wait for tester review.
+
+### 7. Handle Tester Feedback
+
+When you receive feedback:
+1. Fix each issue
+2. Run tests again
+3. Report fixes
+
+Repeat until tester passes.
+
+### 8. Commit (only after PM accepts)
+
+Only after PM reports "ACCEPT":
+
+```bash
+mv tasks/NN-name.in-progress.md tasks/NN-name.done.md
+git add .
+git commit -m "Implement task NN: short description"
+```
+
+## Rules
+
+- Do NOT commit until PM accepts
+- Implement exactly what the task asks for -- no extra features
+- Every task must include tests
+- Follow existing patterns
+- Use `uv` for all Python commands

merm-0.1.0/.claude/agents/tester.md

@@ -0,0 +1,101 @@
+---
+name: tester
+description: Reviews engineer's uncommitted work against task acceptance criteria. Runs tests. Gives concrete feedback. Approves before commit.
+tools: Read, Edit, Write, Bash, Glob, Grep
+model: opus
+---
+
+# Tester Agent
+
+You review the software engineer's work for a specific task. The code is local and uncommitted. You verify it meets the acceptance criteria, find issues, and give concrete feedback. You iterate with the engineer until the task is complete.
+
+Before starting, read `tasks/plan.md` for project context and `docs/PROCESS.md` for the development workflow.
+
+## Input
+
+You receive a task filename (e.g. `tasks/03-intermediate-representation.in-progress.md`) and a summary of what the engineer did.
+
+## Workflow
+
+### 1. Understand What Was Expected
+
+Read the task file for acceptance criteria.
+
+### 2. Review the Code
+
+Check what changed:
+
+```bash
+git diff --stat
+git diff
+```
+
+Verify:
+
+#### Code Quality
+- [ ] Code follows existing patterns
+- [ ] Type hints present
+- [ ] No unnecessary dependencies
+- [ ] No hardcoded values that should be configurable
+
+#### Tests
+- [ ] Tests exist in `tests/`
+- [ ] All tests pass (`uv run pytest -v`)
+- [ ] Tests cover the acceptance criteria
+- [ ] Edge cases tested
+
+#### Visual Output Verification (for rendering/SVG tasks)
+- [ ] Render at least 3 representative diagrams to SVG using `render_diagram()`
+- [ ] Read each SVG file and verify the output is structurally valid (proper XML, no empty/broken elements)
+- [ ] If the task involves SVG path data (icons, shapes, markers), verify path `d` attributes contain valid SVG path commands (M, L, C, Z, etc.), NOT placeholder text or garbage
+- [ ] Convert SVGs to PNG using cairosvg and **read the PNG** to visually confirm correctness — do not trust structural checks alone
+- [ ] If a reference mmdc rendering exists in `tests/reference/`, compare against it
+- [ ] Any visual regression (elements missing, overlapping, misaligned) is a **FAIL**
+
+#### Lint
+- [ ] `uv run ruff check src/ tests/` passes
+
+### 3. Run All Tests
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check src/ tests/
+```
+
+Both must pass.
+
+### 4. Check Acceptance Criteria
+
+Go through each criterion from the task. Mark pass/fail with specifics.
+
+### 5. Give Verdict
+
+**FAIL** -- issues found. List each issue with what's wrong, what was expected, and how to fix it.
+
+**PASS** -- approve for PM review. Confirm all acceptance criteria met.
+
+### 6. Re-review After Fixes
+
+When the engineer applies fixes:
+1. Review changed files
+2. Run tests
+3. Check only the specific issues you flagged
+4. Verify fixes don't break anything else
+
+## When to Fail vs Pass
+
+### Always fail
+- Missing tests
+- Tests fail
+- Core acceptance criteria not met
+- Lint errors
+- SVG output contains invalid/broken elements (empty paths, placeholder text in `d` attributes, missing required elements)
+- Visual output doesn't render correctly when converted to PNG (cairosvg crash, blank image, missing elements)
+- Tests only check structural existence (e.g. "path element exists") without verifying the content is valid/correct
+- Rendered output has obvious visual defects (overlapping text, misaligned nodes, disconnected edges)
+
+### Pass with note (don't block)
+- Minor style issues
+- Edge cases not in acceptance criteria
+- Could be more efficient (if it works)
+- Minor visual differences from mmdc reference (different fonts, slight spacing differences)

merm-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install uv
+      - run: uv sync
+      - run: uv run pytest

merm-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+.ruff_cache/
+.pytest_cache/
+*.so
+.eggs/
+.tmp/
+docs/comparisons/
+docs/comparison_scores.json
+.mutmut-cache/
+mutants/

merm-0.1.0/Makefile

@@ -0,0 +1,25 @@
+.PHONY: test setup shell coverage publish-build publish-test publish publish-clean
+
+test:
+	uv run pytest
+
+setup:
+	uv sync --dev
+
+shell:
+	uv shell
+
+coverage:
+	uv run pytest --cov=merm --cov-report=term-missing
+
+publish-build:
+	uv run hatch build
+
+publish-test:
+	uv run hatch publish --repo test
+
+publish:
+	uv run hatch publish
+
+publish-clean:
+	rm -r dist/

merm-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: merm
+Version: 0.1.0
+Summary: Pure Python Mermaid diagram renderer
+License-Expression: MIT
+Keywords: diagram,flowchart,mermaid,sequence-diagram,svg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Provides-Extra: fonts
+Requires-Dist: fonttools; extra == 'fonts'
+Provides-Extra: png
+Requires-Dist: pillow; extra == 'png'
+Description-Content-Type: text/markdown
+
+# merm
+
+Pure Python Mermaid diagram renderer. Converts Mermaid markup to SVG with zero JavaScript dependencies.
+
+## Install
+
+```bash
+pip install merm
+```
+
+## Usage
+
+### Command line
+
+```bash
+# File to file
+merm -i diagram.mmd -o diagram.svg
+
+# Pipe
+echo 'graph LR
+    A --> B --> C' | merm > diagram.svg
+
+# With uvx (no install needed)
+uvx merm -i diagram.mmd -o diagram.svg
+```
+
+### Python API
+
+```python
+from merm import render_diagram
+
+svg = render_diagram("""
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[OK]
+    B -->|No| D[End]
+""")
+```
+
+## Supported diagram types
+
+- **Flowchart** (`graph` / `flowchart`) — all directions (TD, LR, BT, RL), subgraphs, shapes, edge labels
+- **Sequence** (`sequenceDiagram`) — participants, messages, loops, alt/opt/par fragments
+- **Class** (`classDiagram`) — classes, methods, attributes, relationships
+- **State** (`stateDiagram`) — states, transitions, composite states, forks/joins
+
+## Features
+
+- Pure Python — no Node.js, no browser, no Puppeteer
+- Fast — ~200x faster than mermaid-cli (mmdc)
+- SVG output with clean markup
+- All flowchart shapes and edge types
+- Subgraph nesting and styling
+- Edge labels and arrow markers
+
+## Performance
+
+Benchmarked against mermaid-cli (mmdc) across 28 scenarios:
+
+| | merm | mmdc |
+|---|---|---|
+| Average render time | ~1 ms | ~200 ms |
+| Dependencies | 0 | Node.js + Puppeteer |
+| Startup overhead | None | ~500 ms |
+
+## License
+
+MIT

merm-0.1.0/README.md

@@ -0,0 +1,68 @@
+# merm
+
+Pure Python Mermaid diagram renderer. Converts Mermaid markup to SVG with zero JavaScript dependencies.
+
+## Install
+
+```bash
+pip install merm
+```
+
+## Usage
+
+### Command line
+
+```bash
+# File to file
+merm -i diagram.mmd -o diagram.svg
+
+# Pipe
+echo 'graph LR
+    A --> B --> C' | merm > diagram.svg
+
+# With uvx (no install needed)
+uvx merm -i diagram.mmd -o diagram.svg
+```
+
+### Python API
+
+```python
+from merm import render_diagram
+
+svg = render_diagram("""
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[OK]
+    B -->|No| D[End]
+""")
+```
+
+## Supported diagram types
+
+- **Flowchart** (`graph` / `flowchart`) — all directions (TD, LR, BT, RL), subgraphs, shapes, edge labels
+- **Sequence** (`sequenceDiagram`) — participants, messages, loops, alt/opt/par fragments
+- **Class** (`classDiagram`) — classes, methods, attributes, relationships
+- **State** (`stateDiagram`) — states, transitions, composite states, forks/joins
+
+## Features
+
+- Pure Python — no Node.js, no browser, no Puppeteer
+- Fast — ~200x faster than mermaid-cli (mmdc)
+- SVG output with clean markup
+- All flowchart shapes and edge types
+- Subgraph nesting and styling
+- Edge labels and arrow markers
+
+## Performance
+
+Benchmarked against mermaid-cli (mmdc) across 28 scenarios:
+
+| | merm | mmdc |
+|---|---|---|
+| Average render time | ~1 ms | ~200 ms |
+| Dependencies | 0 | Node.js + Puppeteer |
+| Startup overhead | None | ~500 ms |
+
+## License
+
+MIT

merm-0.1.0/benchmark/README.md

@@ -0,0 +1,43 @@
+# merm Benchmarks
+
+Performance benchmarks comparing merm (pure Python) against mmdc (mermaid-cli, Node.js + Puppeteer).
+
+## Running
+
+```bash
+# Full benchmark with mmdc comparison
+uv run benchmark/run_benchmark.py --save
+
+# merm only (skip mmdc)
+uv run benchmark/run_benchmark.py --no-mmdc
+
+# Custom iterations
+uv run benchmark/run_benchmark.py --iterations 200 --mmdc-iterations 5
+```
+
+## Scenarios
+
+**Synthetic** (`benchmark/scenarios/`):
+- `small_linear` — 5-node chain (baseline)
+- `medium_branching` — fan-out/fan-in with 15 nodes
+- `large_chain_50` — 50-node linear chain (stress test)
+- `wide_fan` — 10-way fan with 33 nodes
+- `nested_subgraphs` — 3 levels of nesting
+- `mixed_shapes` — all supported shape types
+- `lr_complex` — left-to-right with subgraphs
+
+**Real-world** (`tests/fixtures/github/`):
+- CI pipelines, ETL flows, API request handling, registration flows, etc.
+
+**Corpus** (`tests/fixtures/corpus/`):
+- One representative from each diagram type: sequence, class, state, ER, gantt, mindmap, gitgraph, pie
+
+## Results
+
+Results are saved as JSON in `benchmark/results/` with timestamps.
+
+Each result includes:
+- `total_ms` — end-to-end render time
+- `parse_ms`, `layout_ms`, `render_ms` — breakdown (flowcharts only)
+- `peak_memory_bytes` — peak memory for a single render
+- `mmdc.total_ms` — mmdc comparison time (when available)