werkrevisor/docs/prs/2026-10-23-PR#132-draft-review.md

PR#132: tools/draft-review Drafts a Review for a Human, with a Local Config and an HTML Report

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#129: the diagrams next to the draft.
• PR#130: --attach posts the checked draft.

Problem

hs-review drafts a review by werkrevisor and Codex for PRs that a human reviews, e.g. on dev.hostsharing.net. It is a script in ~/bin of one workstation, without version control and without review, and it holds the server, the repository, the config and the names of the tokens of one host.

The draft is Markdown; a browser shows it only after a conversion by hand, and its diagrams are images that open in no size of their own.

Non-Goals

• No change of the review itself.

Specification

Feature: a draft review for a human, from a local config

Scenario#132.01: the local config names the host

… so that the repository holds no server, repository or token name of a user.

• Given a local config with server, default repository, werkrevisor config, secrets file and token names
• When the human runs tools/draft-review 343
• Then it reviews PR 343 of the default repository with the read token, and prints the verdict with its strongest finding and the paths of the report

Verified by

• test_draftreview.SettingsTest.test_the_local_config_names_server_repository_config_and_tokens
• test_draftreview.ResolveTest.test_a_number_means_a_pr_of_the_default_repository
• test_draftreview.MainTest.test_a_review_reads_with_the_read_token_and_prints_the_verdict
• test_draftreview.LinkTest.test_a_link_to_the_tool_finds_the_package_of_the_checkout; red/green: with abspath instead of realpath the link did not find the package.

Scenario#132.02: a PR on another server gets no token

… so that the tokens of the configured server never go to another one.

• Given the local config of one server
• When the human runs tools/draft-review with the URL of a PR on another server
• Then it stops before any request and names the expected form of the URL

Verified by

• test_draftreview.ResolveTest.test_a_pr_on_another_server_is_refused
• test_draftreview.MainTest.test_a_pr_on_another_server_gets_no_token

Scenario#132.03: the report opens in a browser, with diagrams to zoom

… so that the human reads the draft in a browser and looks at each diagram at full size.

• Given a draft with diagrams, and pandoc on the workstation
• When tools/draft-review has written the draft
• Then report.html stands next to report.md, and a click on a diagram opens its SVG on its own

Verified by

• test_draftreview.HtmlTest.test_the_report_gets_an_html_page_with_clickable_diagrams
• test_draftreview.HtmlTest.test_without_pandoc_there_is_no_html

Scenario#132.04: the page runs no script of the draft

… so that a PR cannot place a script in a finding that runs when the human opens the report.

• Given a draft whose finding quotes <script> or a javascript: link, as a model may copy it from the PR
• When tools/draft-review writes report.html and the human opens it
• Then the script shows as text and runs not, and the page allows no script at all

Verified by

• test_draftreview.HtmlTest.test_the_page_runs_no_script_of_the_draft; red/green with pandoc 3: before the fix report.html held the <script> of the finding and no policy, after it the <script> is text and the page has Content-Security-Policy: default-src 'none'; ….
• test_draftreview.HtmlTest.test_a_draft_cannot_inject_a_script_with_pandoc, where pandoc is installed; red/green with pandoc 3: with markdown-raw_html and pandoc's template, a YAML block and raw attributes in a finding put 3 scripts into the page, 2 of them into the head before the policy; gfm-raw_html and commonmark-raw_html still kept the inline <script>; with markdown_strict-raw_html+pipe_tables and the own template none.

Solution

• tools/draft-review and werkrevisor/draftreview.py replace ~/bin/hs-review of one workstation: they read ~/.config/werkrevisor/draft-review.toml, resolve a PR number or URL against its server, read the secrets file, pass the read token, or the write token for --attach, to tools/review-report, print the summary line and write report.html with pandoc.
• report.html is strict Markdown without raw HTML, plus tables (--from markdown_strict-raw_html+pipe_tables): no raw HTML, no YAML metadata block, no raw attribute; an own template puts a Content Security Policy without scripts first into the head and takes only the body and our title from pandoc; a link with javascript:, vbscript: or data: leads to #blocked-…, also where a browser ignores the policy. The Codex reviews of 61b5b80 and cf1f13c found the holes.
• werkrevisor/reviewreport.py links each diagram to its SVG: [![name](name)](name); --attach points both to the attachment.
• README.md, "Draft review": the local config, with example values.
• On the workstation, ~/bin/hs-review becomes a link to tools/draft-review, and ~/.config/werkrevisor/draft-review.toml holds the values of dev.hostsharing.net.