feat(er): add Graphviz DOT export

[JJordan0C]

Summary

• add a Graphviz DOT serializer with app clusters and table-shaped model nodes
• render primary keys, relation fields, and crow's-foot-style cardinalities
• expose dot through both the CLI and MCP ER-diagram interfaces
• add edge-parity, path-safety, CLI, and MCP coverage

Why

Graphviz DOT is a common interchange format for Django schema diagrams, especially for users migrating from django-extensions graph_models. This adds it alongside the existing Mermaid, DBML, D2, and PlantUML exporters.

Closes #48.

Validation

• python -m pytest -q — 317 passed, 20 subtests passed
• python -m ruff check django_orm_lens tests
• python -m mypy django_orm_lens
• generated the miniapp fixture with er --format dot
• rendered the generated document with dot -Tsvg without warnings

Summary by CodeRabbit

• New Features

  • Added Graphviz DOT support for entity-relationship diagrams.
  • Added dot as an available output format for the CLI and diagram tool.
  • DOT diagrams include model tables, primary keys, foreign-key relationships, and relationship metadata.

• Documentation

  • Updated command help and format descriptions to document Graphviz DOT output.

• Tests

  • Added coverage for DOT generation through the CLI and diagram tool.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 88b1af8d-a40f-4073-ae51-de40677a76cd

📥 Commits

Reviewing files that changed from the base of the PR and between a1aa276 and 8dd7000.

📒 Files selected for processing (5)

• cli/django_orm_lens/cli.py
• cli/django_orm_lens/er_formats.py
• cli/django_orm_lens/mcp_server.py
• cli/tests/test_er_formats.py
• cli/tests/test_mcp_server.py

---

📝 Walkthrough

Walkthrough

Graphviz DOT ER-diagram output is added, registered with existing serializers, exposed through CLI and MCP interfaces, and covered by integration tests for structure, relationships, key metadata, path filtering, and format selection.

Changes

Graphviz DOT ER export

Layer / File(s)	Summary
DOT serializer and builder registration cli/django_orm_lens/er_formats.py	Adds build_dot() with escaped HTML table labels, app clusters, primary/foreign-key metadata, and relationship edges; registers the dot builder.
CLI and MCP format exposure cli/django_orm_lens/cli.py, cli/django_orm_lens/mcp_server.py	Adds dot to CLI choices and help text, command summaries, MCP validation, and tool descriptions.
DOT integration and format consistency tests cli/tests/test_er_formats.py, cli/tests/test_mcp_server.py	Validates DOT structure, edge counts, key resolution, path filtering, CLI output, and MCP responses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: frowningdev

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant MCP_er_diagram
  participant ER_BUILDERS
  participant build_dot
  participant WorkspaceIndex
  CLI->>ER_BUILDERS: request format dot
  MCP_er_diagram->>ER_BUILDERS: request diagram_format dot
  ER_BUILDERS->>build_dot: resolve dot builder
  build_dot->>WorkspaceIndex: read models and relationships
  build_dot-->>CLI: return DOT string
  build_dot-->>MCP_er_diagram: return DOT string

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding Graphviz DOT export for ER diagrams.
Linked Issues check	✅ Passed	The summary shows DOT renderer, CLI/MCP exposure, clusters, path safety, and parity tests all implemented as requested in #48.
Out of Scope Changes check	✅ Passed	The changes stay focused on DOT export support, related help text, and tests, with no clear unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[FROWNINGdev]

Merged — thank you, this is a genuinely well-executed first contribution.

I pulled the branch and verified rather than taking the description on trust:

• pytest — 317 passed, 20 subtests
• ruff check and mypy — both clean
• er --format dot on the Mezzanine and Wagtail fixtures — emits a digraph, apps come out as subgraph "cluster_*", no absolute paths leak into the output
• edge parity with Mermaid is covered, which is the part that keeps the formats from drifting apart

Two things I want to call out specifically, because they are the difference between a patch that works and one that is maintainable:

1. You wired dot through both the CLI and the MCP tool, and updated the help text in every place it is listed. That was in the issue, but it is the step people usually miss.
2. Using shape="plain" with an HTML table for the node body, rather than a record label — record shapes break on field names containing | or <, which is exactly the kind of thing a real Django project will eventually hand you.

The crow's-foot cardinalities on the self-referential M2M render correctly too, which I did not expect to work first time.

Credited in the changelog and on the roadmap. If you want another, #49 (django-mptt) and #50 (django-taggit) are the same shape of work in the parser rather than the formatters — but no obligation, and thanks again for this one.

[FROWNINGdev]

Correction to my previous comment: I said "merged" and it is not — the PR is still marked as a draft, so the merge was refused. My mistake, and I would rather say so than leave you with the wrong impression.

Everything else in that comment stands. The review was real: I checked the branch out, ran the suite (317 passed), ruff and mypy clean, and rendered er --format dot on the Mezzanine and Wagtail fixtures. I have also approved and run the full CI matrix here — 14 Python/Django combinations, CodeQL and the lint job — and it is all green, with mergeStateStatus: CLEAN.

So the only thing standing between this and main is the draft flag, which is yours to clear. Mark it "Ready for review" and I will merge it immediately — no further changes needed from you.

Sorry for the false alarm.