werkrevisor/docs/prs/2026-10-06-PR#20-findings-as-line-comments.md

PR#20: findings become line comments, and earlier results fold away

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.

The Problem

werkrevisor 0.16.1 writes its findings into one comment in the conversation of a PR. Gitea can resolve only comments on a code line, so these findings stay open forever. After several review rounds, the reviewer scrolls past every earlier result to find the current one.

Non-Goals

• No change of comments written before this version.
• No resolving by the bot: a human resolves a line comment after checking the fix.

The Scenarios

Feature: findings hang at their code line

Scenario#20.01: a finding with a line becomes a line comment

So that the reviewer resolves a finding where it is, and Gitea marks it as outdated when the line changes.

• Given the model reports a finding at app.py:40-41, a line of the PR
• When werkrevisor publishes the result
• Then a bot review on the head commit carries the finding as a comment at line 40 of app.py
  • and the comment shows the color and Jev's values of the finding

Verified by

• test_line_comments.LineCommentTest.test_finding_with_a_line_becomes_a_line_comment

Scenario#20.02: a finding without a usable line stays in the result comment

So that no finding gets lost.

• Given the model reports a finding <where>
• When werkrevisor publishes the result
• Then the result comment lists the finding

where
without a line
in a file that the PR does not change
at a line that Gitea refuses for a line comment

Verified by

• test_line_comments.LineCommentTest.test_finding_without_a_usable_line_stays_in_the_result

Scenario#20.03: the kind of the bot review follows the verdict

So that the line comments do not change what the gate does.

• Given the review ends with <verdict> and has line comments
• When werkrevisor publishes the result
• Then the bot review is <kind>

verdict	kind
GREEN	APPROVED
YELLOW or ORANGE	COMMENT
RED	REQUEST_CHANGES

This holds with yellow_gate = "approval"; with another gate mode the bot review is a COMMENT for every verdict, and only if it has line comments.

Verified by

• test_line_comments.LineCommentTest.test_review_kind_follows_the_verdict

Scenario#20.04: a finding that is still open is not repeated

So that a finding found again in the next round does not stand there twice in other words.

• Given an earlier bot review has a line comment at app.py:42 that nobody has resolved
• When the next round reports a finding at app.py:40-41
• Then werkrevisor writes no new line comment
  • and the result comment links the earlier line comment as still open
• But a resolved earlier comment, or one more than two lines away, gets a new line comment

Verified by

• test_line_comments.ReuseTest.test_open_earlier_line_comment_is_reused
• test_line_comments.ReuseTest.test_resolved_far_or_other_file_comments_are_not_reused

Feature: only the current result stays open

Scenario#20.05: a new result folds the earlier ones

So that the current result is the only open one in the conversation.

• Given a PR has a result comment of werkrevisor for an earlier commit
• When werkrevisor publishes the result for a new commit
• Then the earlier comment shows one line with its verdict, its commit and a link to the new result
  • and its full text stays readable after a click on that line

Verified by

• test_line_comments.FoldTest.test_new_result_folds_the_earlier_ones
• test_line_comments.FoldTest.test_folded_comment_keeps_its_markers
• test_line_comments.FoldTest.test_a_failed_fold_is_retried_by_a_rerun
• test_line_comments.FoldTest.test_a_mention_of_the_head_does_not_protect_a_comment_from_folding

The Solution

• The bot review on the head commit carries the findings with a line as line comments (new_position).
• The result comment comes before the bot review, so that a failure never leaves an approval without its result.
• If Gitea refuses the line comments, werkrevisor edits the result comment to list them in full, and submits an approval or a change request again without them; if that second call fails too, its cause is another one, and the run ends with ERROR.
• If the review fails in another way, the result comment gets the findings in full, and the run ends with ERROR. A rerun on the same head knows only the verdict: it submits the missing approval or change request, but no line comments, because the findings already stand in full in the result comment.
• An unresolved bot line comment within two lines of a new finding is reused instead of repeated.
• After each publish, werkrevisor edits its earlier result comments into a <details> block; a failed fold is retried on the next run. The markers stay outside the block, so a rerun on an earlier commit still finds its result.
• werkrevisor 0.17.0.