feat(ci): add opt-in summary and supersede modes to the PR review poster

Two optional manifest fields for producers that need them:

- post_without_comments posts the summary as a COMMENT review even when
  there are no inline comments.
- supersede_previous replaces the body of the producer's earlier COMMENT
  review with a superseded note, keeping the old text collapsed, since
  GitHub cannot dismiss COMMENT reviews.

Both default to false, which is the behaviour clang-tidy relies on. Adds
the poster's first unit tests, including ones that pin the defaults.

Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Ramon Roche committed 2026-10-02 15:50:14 -07:00
1 parent 3f8dd2bb6d
commit 5bcf3fc2ac
2 files changed
+245 -5

No files matched your search

+93 -5
View File
@@ -22,9 +22,18 @@ Artifact contract (directory passed on the command line):
"marker": "<!-- pr-review-poster:clang-tidy -->", (required, printable ASCII)
"event": "COMMENT", (required, "COMMENT" only)
"commit_sha": "0123456789abcdef0123456789abcdef01234567",(required, 40 hex chars)
"summary": "Optional review body text" (optional)
"summary": "Optional review body text", (optional)
"post_without_comments": false, (optional bool)
"supersede_previous": false (optional bool)
}
post_without_comments: post the summary as a review even when there are
no comments (default: post nothing). Requires a non-empty summary.
supersede_previous: GitHub cannot dismiss COMMENT reviews, so replace the
body of this producer's earlier COMMENT reviews with a "superseded" note,
keeping the old text collapsed (default: leave them). Both default to
false, the behaviour existing producers such as clang-tidy rely on.
comments.json
JSON array of line-anchored review comment objects:
[
@@ -210,6 +219,13 @@ def validate_manifest(directory):
if not isinstance(summary, str):
_fail('summary must be a string if present')
# Opt-in behaviours. Both default to False, which is the original
# behaviour existing producers (clang-tidy) rely on.
post_without_comments = _optional_bool(manifest, 'post_without_comments')
supersede_previous = _optional_bool(manifest, 'supersede_previous')
if post_without_comments and not summary.strip():
_fail('post_without_comments requires a non-empty summary')
try:
with open(comments_path, 'r', encoding='utf-8') as f:
comments = json.load(f)
@@ -229,9 +245,18 @@ def validate_manifest(directory):
'commit_sha': commit_sha,
'summary': summary,
'comments': comments,
'post_without_comments': post_without_comments,
'supersede_previous': supersede_previous,
}
def _optional_bool(manifest, key):
value = manifest.get(key, False)
if not isinstance(value, bool):
_fail('{} must be true or false if present'.format(key))
return value
# ---------------------------------------------------------------------------
# Stale-review dismissal
# ---------------------------------------------------------------------------
@@ -300,6 +325,56 @@ def dismiss_stale_reviews(client, repo, pr_number, marker):
return failed_dismissals
SUPERSEDED_TAG = '<!-- pr-review-poster:superseded -->'
SUPERSEDED_MAX_OLD_BYTES = 50000
def superseded_body(marker, old_body):
"""Replacement body for an older COMMENT review from the same producer.
Keeps the marker (so the review is still recognisably ours) and the old
text, collapsed, so nothing a human may have replied to disappears.
"""
old = old_body.replace(marker, '').strip()
old = old.encode('utf-8')[:SUPERSEDED_MAX_OLD_BYTES].decode(
'utf-8', 'ignore')
return '\n'.join([
marker, SUPERSEDED_TAG, '',
'**Superseded** by a newer review from the same check on this pull '
'request. Its inline comments may refer to an older commit.', '',
'<details><summary>Previous review</summary>', '', old, '',
'</details>'])
def supersede_comment_reviews(client, repo, pr_number, marker):
"""Mark earlier COMMENT reviews from this producer as superseded.
GitHub cannot dismiss a COMMENT review, so opted-in producers edit the
old review's body instead. Same ownership filter as dismissal: author
is github-actions[bot] AND the body contains the marker. Returns the
number of reviews edited.
"""
edited = 0
path = 'repos/{}/pulls/{}/reviews'.format(repo, pr_number)
for review in client.paginated(path):
user = review.get('user') or {}
body = review.get('body') or ''
if user.get('login') != BOT_LOGIN or marker not in body:
continue
if review.get('state') != 'COMMENTED' or SUPERSEDED_TAG in body:
continue
review_id = review.get('id')
print('Marking earlier review {} as superseded'.format(review_id))
try:
client.request('PUT', '{}/{}'.format(path, review_id),
json_body={'body': superseded_body(marker, body)})
edited += 1
except RuntimeError as e:
print('warning: failed to supersede review {}: {}'.format(
review_id, e), file=sys.stderr)
return edited
# ---------------------------------------------------------------------------
# Review posting
# ---------------------------------------------------------------------------
@@ -341,14 +416,17 @@ def _comment_to_api(entry):
def post_review(client, repo, pr_number, marker, event, commit_sha, summary,
comments):
comments, allow_empty=False):
"""Post one or more reviews containing the validated comments.
Comments are split into COMMENTS_PER_REVIEW-sized chunks. Each chunk
becomes its own review POST. A failed chunk logs a warning and the
loop continues to the next chunk.
loop continues to the next chunk. With allow_empty (opt-in), a review
with no comments is still posted, carrying only the summary.
"""
chunks = list(_chunk(comments, COMMENTS_PER_REVIEW))
if not chunks and allow_empty:
chunks = [[]]
total = len(chunks)
if total == 0:
print('No comments to post; skipping review creation.')
@@ -409,8 +487,9 @@ def cmd_post(args):
result = validate_manifest(args.directory)
# Empty comment lists short-circuit silently. A producer that ran but
# found nothing to flag should not generate noise on the PR.
if len(result['comments']) == 0:
# found nothing to flag should not generate noise on the PR, unless it
# opted in to posting its summary on its own.
if len(result['comments']) == 0 and not result['post_without_comments']:
print('No comments in artifact; nothing to post.')
return 0
@@ -436,6 +515,14 @@ def cmd_post(args):
print('{} prior review(s) could not be dismissed (likely '
'branch protection).'.format(undismissed))
if result['supersede_previous']:
supersede_comment_reviews(
client=client,
repo=repo,
pr_number=result['pr_number'],
marker=result['marker'],
)
post_review(
client=client,
repo=repo,
@@ -445,6 +532,7 @@ def cmd_post(args):
commit_sha=result['commit_sha'],
summary=result['summary'],
comments=result['comments'],
allow_empty=result['post_without_comments'],
)
except RuntimeError as e:
_fail(str(e))
+152
View File
@@ -0,0 +1,152 @@
#!/usr/bin/env python3
"""Tests for pr-review-poster.py's opt-in behaviours.
The poster is shared by clang-tidy and the AI review. These tests pin that
a manifest without the new fields behaves exactly as before (no review for
an empty comment list, COMMENT reviews left alone), and that the opt-in
fields post a summary-only review and supersede earlier COMMENT reviews
without touching anyone else's review.
"""
import importlib.util
import json
import os
import tempfile
import unittest
from typing import Any, Dict, List, Optional, Tuple
HERE = os.path.dirname(os.path.abspath(__file__))
_spec = importlib.util.spec_from_file_location(
'pr_review_poster', os.path.join(HERE, 'pr-review-poster.py'))
assert _spec and _spec.loader
poster: Any = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(poster)
MARKER = '<!-- pr-review-poster:ai-review -->'
SHA = 'a' * 40
class FakeClient:
def __init__(self, reviews: Optional[List[Dict[str, Any]]] = None
) -> None:
self.reviews = reviews or []
self.requests: List[Tuple[str, str, Any]] = []
def paginated(self, path: str) -> List[Dict[str, Any]]:
return self.reviews
def request(self, method: str, path: str,
json_body: Any = None) -> Tuple[Any, Dict[str, str]]:
self.requests.append((method, path, json_body))
return {}, {}
def write_artifact(tmp: str, manifest: Dict[str, Any],
comments: List[Dict[str, Any]]) -> None:
with open(os.path.join(tmp, 'manifest.json'), 'w') as f:
json.dump(manifest, f)
with open(os.path.join(tmp, 'comments.json'), 'w') as f:
json.dump(comments, f)
def manifest(**extra: Any) -> Dict[str, Any]:
base = {'pr_number': 7, 'marker': MARKER, 'event': 'COMMENT',
'commit_sha': SHA, 'summary': 'Summary.'}
base.update(extra)
return base
class TestManifestFlags(unittest.TestCase):
def validate(self, m: Dict[str, Any]) -> Dict[str, Any]:
with tempfile.TemporaryDirectory() as tmp:
write_artifact(tmp, m, [])
result: Dict[str, Any] = poster.validate_manifest(tmp)
return result
def test_flags_default_to_false(self) -> None:
# clang-tidy's manifest carries neither field
result = self.validate(manifest())
self.assertFalse(result['post_without_comments'])
self.assertFalse(result['supersede_previous'])
def test_flags_must_be_booleans(self) -> None:
for key in ('post_without_comments', 'supersede_previous'):
with self.subTest(key=key):
with self.assertRaises(SystemExit):
self.validate(manifest(**{key: 'yes'}))
def test_post_without_comments_needs_a_summary(self) -> None:
with self.assertRaises(SystemExit):
self.validate(manifest(summary=' ', post_without_comments=True))
class TestPostReview(unittest.TestCase):
def post(self, comments: List[Dict[str, Any]], allow_empty: bool
) -> FakeClient:
client = FakeClient()
poster.post_review(client, 'PX4/PX4-Autopilot', 7, MARKER,
'COMMENT', SHA, 'Summary.', comments,
allow_empty=allow_empty)
return client
def test_empty_without_opt_in_posts_nothing(self) -> None:
self.assertEqual(self.post([], allow_empty=False).requests, [])
def test_empty_with_opt_in_posts_summary_only_comment_review(
self) -> None:
reqs = self.post([], allow_empty=True).requests
self.assertEqual(len(reqs), 1)
method, path, body = reqs[0]
self.assertEqual((method, path),
('POST', 'repos/PX4/PX4-Autopilot/pulls/7/reviews'))
self.assertEqual(body['event'], 'COMMENT')
self.assertEqual(body['comments'], [])
self.assertIn('Summary.', body['body'])
self.assertTrue(body['body'].startswith(MARKER))
def test_comments_post_as_before(self) -> None:
c = {'path': 'a.cpp', 'line': 3, 'side': 'RIGHT', 'body': 'x'}
reqs = self.post([c], allow_empty=True).requests
self.assertEqual(len(reqs), 1)
self.assertEqual(len(reqs[0][2]['comments']), 1)
def review(rid: int, login: str, body: str,
state: str = 'COMMENTED') -> Dict[str, Any]:
return {'id': rid, 'user': {'login': login}, 'body': body,
'state': state}
class TestSupersede(unittest.TestCase):
def test_only_our_comment_reviews_are_edited(self) -> None:
client = FakeClient([
review(1, poster.BOT_LOGIN, MARKER + '\nold findings'),
review(2, 'alice', MARKER + '\nhuman quoting the marker'),
review(3, poster.BOT_LOGIN, '<!-- other-tool -->\nnot ours'),
review(4, poster.BOT_LOGIN, MARKER + '\nx', state='DISMISSED'),
review(5, poster.BOT_LOGIN,
MARKER + '\n' + poster.SUPERSEDED_TAG + '\nalready'),
])
edited = poster.supersede_comment_reviews(
client, 'PX4/PX4-Autopilot', 7, MARKER)
self.assertEqual(edited, 1)
method, path, body = client.requests[0]
self.assertEqual((method, path),
('PUT', 'repos/PX4/PX4-Autopilot/pulls/7/reviews/1'))
self.assertIn(poster.SUPERSEDED_TAG, body['body'])
self.assertIn(MARKER, body['body'])
self.assertIn('old findings', body['body'])
def test_dismissal_still_skips_comment_reviews(self) -> None:
# unchanged behaviour for producers that do not opt in
client = FakeClient([review(1, poster.BOT_LOGIN, MARKER)])
poster.dismiss_stale_reviews(client, 'PX4/PX4-Autopilot', 7, MARKER)
self.assertEqual(client.requests, [])
if __name__ == '__main__':
unittest.main()