werkrevisor/docs/prs/2026-10-20-PR#129-hs-review-diagrams.md

PR#129: hs-review Puts the Diagrams of PR Lens Next to Its Draft

Version: minor

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Related Links

• PR#121: diagrams of PR Lens in the result comment.
• PR#125: diagrams for werkrevisor, only for PRs that a human reviews.

Problem

On dev.hostsharing.net werkrevisor runs only through hs-review on the workstation (Hostsharing-internal). It writes a draft, read-only, and the human posts the findings. The diagrams of PR Lens need a published result comment, and tools/dry-run runs in the PR-Agent image without Node.js, so hs-review draws none.

Non-Goals

• No upload to dev.hostsharing.net; the human attaches the SVGs when posting.

Specification

Feature: the draft of hs-review shows the diagrams

Scenario#129.01: a dry run writes the diagrams to a directory

… so that a run without Gitea access for writing still gets the diagrams.

• Given a config with [diagrams] enabled = true and a directory with the SVGs of an earlier run
• When werkrevisor reviews a PR with --no-publish --diagrams-out <dir>
• Then the directory holds the SVGs of this run only, and werkrevisor writes nothing to Gitea; a GREEN result, or one that ends in ERROR, leaves it empty

Verified by

• test_prlens.DiagramsInTheResultCommentTest.test_a_dry_run_writes_the_diagrams_to_a_directory
• test_prlens.DiagramsInTheResultCommentTest.test_a_green_dry_run_writes_no_diagrams
• test_prlens.DiagramsInTheResultCommentTest.test_a_failed_dry_run_leaves_no_diagrams_of_an_earlier_run

Scenario#129.02: the draft links the diagrams next to it

… so that the human finds the SVGs to attach when posting.

• Given the SVGs of the dry run, and SVGs of an earlier report next to the draft
• When tools/review-report writes the draft
• Then only the SVGs of this run stand next to report.md, and it links them under "Diagrams", before the Codex part; a run that draws none shows none of an earlier run

Verified by

• test_reviewreport.ReviewReportTest.test_the_draft_links_the_diagrams_next_to_it
• test_reviewreport.ReviewReportTest.test_without_diagrams_the_draft_has_no_section
• test_reviewreport.ReviewReportTest.test_a_run_without_new_diagrams_shows_none_of_an_earlier_run

Scenario#129.03: hs-review draws the diagrams also for a GREEN result

… so that the human sees them for each PR, since a human reviews every PR of hs-review.

• Given config/hsadmin-ng.toml, the config of hs-review
• When the review of a PR is GREEN
• Then the draft still gets the diagrams

Verified by

• test_prlens.DiagramsConfigTest.test_hs_review_draws_also_for_green

Solution

• werkrevisor --diagrams-out <dir> needs --no-publish; each run first removes the old pr-lens-*.svg of the directory, then writes the new ones, under the same rules as in the result comment: a fresh review with the model and no possible secret; a GREEN result only with skip_green = false, as config/hsadmin-ng.toml sets it.
• tools/dry-run: with --llm and WERKREVISOR_DIAGRAMS_OUT under build/, it passes --diagrams-out and runs in localhost/werkrevisor-base:<hash>, the stage base of the Dockerfile; it builds that image once, with the hash of tools/release_rootfs.py base-name. Without the variable it runs in the PR-Agent image, as before.
• tools/review-report sets the variable to build/diagrams/<host>/<owner>/<repo>-<n>, copies the SVGs next to report.md and links them.
• config/hsadmin-ng.toml switches the diagrams on, also for GREEN (skip_green = false); the review model, Sonnet 5.5, draws them.
• tools/review-report empties the directory of the diagrams before each dry run, so that a run that draws none shows no SVGs of an earlier run; the Codex review of 0426c14 found it.

End to end on 2026-10-20: tools/dry-run on hsadmin-ng PR#319 gave ORANGE and 3 SVGs in 1:33 min, including the build of the base image.