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](../../tests/test_line_comments.py)

#### 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](../../tests/test_line_comments.py)

#### 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](../../tests/test_line_comments.py)

#### 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](../../tests/test_line_comments.py)
- [test_line_comments.ReuseTest.test_resolved_far_or_other_file_comments_are_not_reused](../../tests/test_line_comments.py)

### 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](../../tests/test_line_comments.py)
- [test_line_comments.FoldTest.test_folded_comment_keeps_its_markers](../../tests/test_line_comments.py)
- [test_line_comments.FoldTest.test_a_failed_fold_is_retried_by_a_rerun](../../tests/test_line_comments.py)
- [test_line_comments.FoldTest.test_a_mention_of_the_head_does_not_protect_a_comment_from_folding](../../tests/test_line_comments.py)

## 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.