fix: report Graphviz stderr when dot fails to render a diagram

[fgmacedo]

Fixes #649

Why

When dot rejects a graph, every library path that renders it (the svg format, _repr_svg_(), the CLI, the Sphinx directive) fails with "dot" with args [...] returned code: 1. The reason (Error: ...: syntax error in line 25 near ',') is printed to stdout by pydot 4.0.1 and never reaches the exception or the Sphinx warning (#649).

What changes

• The paths above run dot -T<fmt> directly, with the DOT source on stdin, and raise GraphvizError carrying the format and Graphviz's stderr; the Sphinx directive reports the same text in its warning.
• A dot that is not on PATH raises GraphvizError with a link to the Graphviz download page; one that cannot run (permissions) or dies by a signal is reported as such.
• On success the output is byte-identical to pydot's create()/write() (svg, png, dot, pdf checked); write_image to .raw still writes the DOT text without running dot; no partial file is written and nothing reaches stdout on failure.
• GraphvizError subclasses StateMachineError and is documented in the diagram page; release note added to 3.2.2.

Evidence

Before (pydot) vs after, same malformed DOT:

BEFORE (pydot): "dot" with args ['-Tsvg', '/var/folders/.../tmptbtmwinq'] returned code: 1
AFTER: dot -Tsvg failed with exit code 1.
Error: <stdin>: syntax error in line 1 near ';'

$ timeout 120 uv run pytest -n 4
2358 passed, 1 skipped, 44 xfailed in 24s

$ timeout 120 uv run pytest tests/test_contrib_diagram.py tests/test_contrib_diagram_graphviz.py --cov=statemachine.contrib.diagram --cov-branch --cov-report=term-missing
statemachine/contrib/diagram/formatter.py   100%
statemachine/contrib/diagram/graphviz.py    100%

$ env PATH=/usr/bin:/bin .venv/bin/python -m pytest tests/test_contrib_diagram_graphviz.py --no-cov
6 passed

ruff check, ruff format --check, mypy, pyright and sphinx-build clean (the {class} reference resolves). docs/images/readme_trafficlightmachine.png was regenerated by the generate-images hook with the local Graphviz 16.1.0; the new path and pydot's write(format="png") produce the same bytes.

Not verified

• Windows: dot.exe resolution through CreateProcess, CREATE_NO_WINDOW, and the .raw file now being UTF-8 with \n where pydot used the locale encoding and text mode.
• Graphviz versions other than 16.1.0 (local) and the one on CI; the stderr wording asserted in tests (syntax error ... near ';') is Graphviz's parser message and has been stable, but was not checked against 2.43 from the report.
• The curly quotes in the report could not be reproduced: the renderer emits straight quotes with pydot 4.0.1.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (98eaca5) to head (beee9b4).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #672   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           52        53    +1     
  Lines         5685      5714   +29     
  Branches       896       900    +4     
=========================================
+ Hits          5685      5714   +29     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud