# PR Diagram Bot — reviewing `.drawio` changes as pictures

Goal: in CI, for every `.drawio` file a pull request touches, render the base
version, the head version, and a colour-coded diff, then post them as a
sticky PR comment (and the job summary) so reviewers see pictures instead of
raw XML diffs.

Read this when you're setting up (or troubleshooting) automated PR diagram
review for a repo.

## Pieces

- `scripts/prdiff.py` — the script. `changed_drawios()` finds what changed
  (`git diff --name-status`); for each file it exports base/head PNGs via the
  draw.io CLI and, for modified files, chains `drawiodiff.py` ->
  `autolayout.py` -> CLI export into a third diff PNG; `render_markdown()`
  turns all of that into one Markdown report.
- `.github/actions/drawio-diff/action.yml` — a composite action that checks
  out full history, installs draw.io + Graphviz, runs `prdiff.py`, uploads
  the PNGs + report as a build artifact, writes the report to
  `$GITHUB_STEP_SUMMARY`, and posts/updates a sticky PR comment.
- `.github/workflows/drawio-pr-diff.example.yml` — a template workflow that
  wires the action to `pull_request` events. It ships as `.example.yml` and
  gated with `if: false` so it does **nothing** until you copy and adapt it
  in your own repo (see the comment at the top of that file).

## Adopting it in your own repo

1. Copy `.github/actions/drawio-diff/` and `skills/drawio-skill/` (or at
   least `scripts/prdiff.py`, `scripts/drawiodiff.py`, `scripts/autolayout.py`)
   into your repo.
2. Copy `.github/workflows/drawio-pr-diff.example.yml` to
   `.github/workflows/drawio-pr-diff.yml`, drop the `if: false` guard, and
   uncomment the `pull_request: paths: ["**/*.drawio"]` trigger.
3. Give the job `permissions: pull-requests: write` (already set in the
   example) — the sticky comment step needs it; `contents: read` covers the
   checkout.
4. Push a PR that touches a `.drawio` file and watch it run.

## Runner tooling

The draw.io desktop CLI is Electron-based, so headless CI needs the same
setup documented in `docs/CI.md` "Option A" of this repo: Graphviz (`dot`,
for `autolayout.py`) and a virtual display (`xvfb-run`). The composite action
installs both by default (latest `drawio-desktop` `.deb` + `apt-get
graphviz xvfb`); pass `skip-tool-install: true` if your runner/container
already provides `drawio` and `dot` on PATH.

If the draw.io CLI is missing (or fails), `prdiff.py` does **not** hard-fail
the run — the Markdown report still lists every changed file and its status,
just without images, with a note that image export was skipped. `git`
missing (or `--repo` not being a git repository) IS fatal, since without git
there is nothing to diff.

## How the sticky comment works

The action tags its comment body with an HTML marker
(`<!-- drawio-pr-diff-bot -->`) and, before posting, searches the PR's
existing comments (via `gh api .../issues/<n>/comments`) for one starting
with that marker. If found, it `PATCH`es that comment in place; otherwise it
creates a new one with `gh pr comment`. This keeps one running comment per PR
instead of a new comment on every push.

## Running it locally

```
python3 skills/drawio-skill/scripts/prdiff.py --base origin/main --head HEAD \
  --out-dir drawio-pr -o drawio-pr/report.md
```

`--base`/`--head` are any git refs or SHAs (`--head` defaults to `HEAD`);
`--repo` points at a different working tree (default: current directory).
Open `drawio-pr/report.md` to preview exactly what the PR comment will say.