From 5bcf3fc2acb7a73f4117f3aa48bf8701d0b54eff Mon Sep 17 00:00:00 2001 From: Ramon Roche Date: Fri, 2 Oct 2026 15:38:38 -0700 Subject: [PATCH] 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 --- Tools/ci/pr-review-poster.py | 98 ++++++++++++++++++- Tools/ci/test_pr_review_poster.py | 152 ++++++++++++++++++++++++++++++ 2 files changed, 245 insertions(+), 5 deletions(-) create mode 100644 Tools/ci/test_pr_review_poster.py diff --git a/Tools/ci/pr-review-poster.py b/Tools/ci/pr-review-poster.py index f46f8616a60..8a62575a706 100644 --- a/Tools/ci/pr-review-poster.py +++ b/Tools/ci/pr-review-poster.py @@ -22,9 +22,18 @@ Artifact contract (directory passed on the command line): "marker": "", (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 = '' +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.', '', + '
Previous review', '', old, '', + '
']) + + +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)) diff --git a/Tools/ci/test_pr_review_poster.py b/Tools/ci/test_pr_review_poster.py new file mode 100644 index 00000000000..d9b27e4517e --- /dev/null +++ b/Tools/ci/test_pr_review_poster.py @@ -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 = '' +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, '\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()