feat: Enhance PR comment script with context and filters

This commit significantly enhances the `scripts/gha/get_pr_review_comments.py`
script and its underlying library function in `scripts/gha/firebase_github.py`.

Key improvements include:
- Copyright year updated to 2025.
- Output now includes comment ID, in_reply_to_id (if applicable), and
  the comment creation timestamp.
- Comments are marked as [OUTDATED] if their diff position is no longer
  current (i.e., API 'position' field is null).
- Added a `--context-lines <N>` argument (default 10) to control the
  amount of diff hunk context displayed. N=0 shows the full hunk.
- Introduced a `--since <ISO_8601_timestamp>` argument to filter
  comments, showing only those created at or after the specified time.
  The `get_pull_request_review_comments` function in the library
  was updated to support this `since` parameter in the API call.

These changes provide more comprehensive comment information and allow
for better control over the data fetched, making it more useful for
reviewing and addressing PR feedback, especially in complex PRs with
multiple review rounds.

Author: google-labs-jules[bot]

scripts/gha/firebase_github.py

@@ -225,33 +225,45 @@ def get_reviews(token, pull_number):
   return results
 
 
-def get_pull_request_review_comments(token, pull_number):
+def get_pull_request_review_comments(token, pull_number, since=None): # Added since=None
   """https://docs.github.com/en/rest/pulls/comments#list-review-comments-on-a-pull-request"""
   url = f'{GITHUB_API_URL}/pulls/{pull_number}/comments'
   headers = {'Accept': 'application/vnd.github.v3+json', 'Authorization': f'token {token}'}
+
   page = 1
   per_page = 100
   results = []
-  keep_going = True
-  while keep_going:
-    params = {'per_page': per_page, 'page': page}
-    page = page + 1
-    keep_going = False
-    # Use a try-except block to catch potential errors during the API request
+
+  # Base parameters for the API request
+  base_params = {'per_page': per_page}
+  if since:
+    base_params['since'] = since
+
+  while True: # Loop indefinitely until explicitly broken
+    current_page_params = base_params.copy()
+    current_page_params['page'] = page
+
     try:
-      with requests_retry_session().get(url, headers=headers, params=params,
+      with requests_retry_session().get(url, headers=headers, params=current_page_params,
                         stream=True, timeout=TIMEOUT) as response:
-        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
-        logging.info("get_pull_request_review_comments: %s page %s response: %s", url, params.get('page'), response)
+        response.raise_for_status()
+        # Log which page and if 'since' was used for clarity
+        logging.info("get_pull_request_review_comments: %s params %s response: %s", url, current_page_params, response)
+
         current_page_results = response.json()
-        if not current_page_results: # No more results
-            break
+        if not current_page_results: # No more results on this page
+            break # Exit loop, no more comments to fetch
+
         results.extend(current_page_results)
-        # If exactly per_page results were retrieved, there might be more.
-        keep_going = (len(current_page_results) == per_page)
+
+        # If fewer results than per_page were returned, it's the last page
+        if len(current_page_results) < per_page:
+            break # Exit loop, this was the last page
+
+        page += 1 # Increment page for the next iteration
+
     except requests.exceptions.RequestException as e:
-      logging.error(f"Error fetching review comments page {params.get('page')-1} for PR {pull_number}: {e}")
-      # Optionally, re-raise the exception or handle it by returning partial results or an empty list
+      logging.error(f"Error fetching review comments (page {page}, params: {current_page_params}) for PR {pull_number}: {e}")
       break # Stop trying if there's an error
   return results
 

scripts/gha/get_pr_review_comments.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -26,20 +26,47 @@
     # Set verbosity for absl logging if you want to see logs from firebase_github
     # absl_logging.set_verbosity(absl_logging.INFO)
 except ImportError:
-    # If absl is not used, standard logging can be configured if needed
-    # import logging as std_logging
-    # std_logging.basicConfig(level=std_logging.INFO)
     pass # firebase_github.py uses absl.logging.info, so this won't redirect.
 
 
+def print_contextual_diff_hunk(diff_hunk, comment_position, context_lines_count):
+    if not diff_hunk or not diff_hunk.strip(): # Handle empty or whitespace-only diff_hunk
+        print("(No diff hunk available or content is empty)")
+        return
+
+    hunk_lines = diff_hunk.split('\n')
+
+    # comment_position is 1-indexed from GitHub API. If None, or context is 0, print full hunk.
+    if context_lines_count == 0 or comment_position is None or comment_position < 1 or comment_position > len(hunk_lines):
+        print(diff_hunk)
+        return
+
+    comment_line_index = comment_position - 1 # Convert to 0-indexed for list access
+
+    start_index = max(0, comment_line_index - context_lines_count)
+    end_index = min(len(hunk_lines), comment_line_index + context_lines_count + 1)
+
+    # Ensure start_index is not greater than comment_line_index, in case of small hunks
+    # This also means that if comment_line_index is valid, start_index will be <= comment_line_index
+    start_index = min(start_index, comment_line_index if comment_line_index >=0 else 0)
+
+
+    for i in range(start_index, end_index):
+        # Basic safety for i, though start/end logic should make this robust
+        if i >= 0 and i < len(hunk_lines):
+            prefix = "> " if i == comment_line_index else "  "
+            print(f"{prefix}{hunk_lines[i]}")
+        # else: # This case should ideally not be reached with correct boundary conditions
+            # print(f"  Error: Skipped line index {i} in hunk processing due to boundary issue.")
+
+
 def main():
-    # Default owner and repo from firebase_github, ensuring it's loaded.
     default_owner = firebase_github.OWNER
     default_repo = firebase_github.REPO
 
     parser = argparse.ArgumentParser(
         description="Fetch review comments from a GitHub PR and format for use with Jules.",
-        formatter_class=argparse.RawTextHelpFormatter # To preserve formatting in help text
+        formatter_class=argparse.RawTextHelpFormatter
     )
     parser.add_argument(
         "--pull_number",
@@ -51,73 +78,100 @@ def main():
         "--owner",
         type=str,
         default=default_owner,
-        help=f"Repository owner. Defaults to '{default_owner}' (from firebase_github.py)."
+        help=f"Repository owner. Defaults to '{default_owner}'."
     )
     parser.add_argument(
         "--repo",
         type=str,
         default=default_repo,
-        help=f"Repository name. Defaults to '{default_repo}' (from firebase_github.py)."
+        help=f"Repository name. Defaults to '{default_repo}'."
     )
     parser.add_argument(
         "--token",
         type=str,
         default=os.environ.get("GITHUB_TOKEN"),
-        help="GitHub token. Can also be set via GITHUB_TOKEN environment variable."
+        help="GitHub token. Can also be set via GITHUB_TOKEN env var."
+    )
+    parser.add_argument(
+        "--context-lines",
+        type=int,
+        default=10,
+        help="Number of context lines around the commented line from the diff hunk. Use 0 for the full hunk. Default: 10."
+    )
+    parser.add_argument(
+        "--since",
+        type=str,
+        default=None,
+        help="Only show comments created at or after this ISO 8601 timestamp (e.g., YYYY-MM-DDTHH:MM:SSZ)."
     )
 
     args = parser.parse_args()
 
     if not args.token:
-        sys.stderr.write("Error: GitHub token not provided. Set GITHUB_TOKEN environment variable or use --token argument.\n")
+        sys.stderr.write("Error: GitHub token not provided. Set GITHUB_TOKEN or use --token.\n")
         sys.exit(1)
 
-    # Update the repository details in firebase_github module if different from default
     if args.owner != firebase_github.OWNER or args.repo != firebase_github.REPO:
         repo_url = f"https://github.com/{args.owner}/{args.repo}"
         if not firebase_github.set_repo_url(repo_url):
-            sys.stderr.write(f"Error: Invalid repository URL format for {args.owner}/{args.repo}. Expected format: https://github.com/owner/repo\n")
+            sys.stderr.write(f"Error: Invalid repo URL: {args.owner}/{args.repo}. Expected https://github.com/owner/repo\n")
             sys.exit(1)
-        # Using print to stderr for info, as absl logging might not be configured here for this script's own messages.
         print(f"Targeting repository: {firebase_github.OWNER}/{firebase_github.REPO}", file=sys.stderr)
 
+    print(f"Fetching comments for PR #{args.pull_number} from {firebase_github.OWNER}/{firebase_github.REPO}...", file=sys.stderr)
+    if args.since:
+        print(f"Filtering comments created since: {args.since}", file=sys.stderr)
 
-    print(f"Fetching review comments for PR #{args.pull_number} from {firebase_github.OWNER}/{firebase_github.REPO}...", file=sys.stderr)
-
-    comments = firebase_github.get_pull_request_review_comments(args.token, args.pull_number)
+    comments = firebase_github.get_pull_request_review_comments(
+        args.token,
+        args.pull_number,
+        since=args.since # Pass the 'since' argument
+    )
 
-    if not comments: # This will be true if list is empty (no comments or error in fetching first page)
-        print(f"No review comments found for PR #{args.pull_number}, or an error occurred during fetching.", file=sys.stderr)
-        # If firebase_github.py's get_pull_request_review_comments logs errors, those might provide more details.
-        return # Exit gracefully if no comments
+    if not comments:
+        print(f"No review comments found for PR #{args.pull_number} (or matching filters), or an error occurred.", file=sys.stderr)
+        return
 
-    # Output actual data to stdout
     print("\n--- Review Comments ---")
     for comment in comments:
         user = comment.get("user", {}).get("login", "Unknown user")
         path = comment.get("path", "N/A")
-        line = comment.get("line", "N/A")
-        body = comment.get("body", "").strip() # Strip whitespace from comment body
-        diff_hunk = comment.get("diff_hunk", "N/A")
+        file_line = comment.get("line", "N/A")
+        hunk_position = comment.get("position") # This is the 1-indexed position in the hunk
+
+        body = comment.get("body", "").strip()
+        diff_hunk = comment.get("diff_hunk") # Can be None or empty
         html_url = comment.get("html_url", "N/A")
 
-        # Only print comments that have a body
+        comment_id = comment.get("id")
+        in_reply_to_id = comment.get("in_reply_to_id")
+        created_at = comment.get("created_at")
+
         if not body:
             continue
 
-        print(f"Comment by: {user}")
+        print(f"Comment by: {user} (ID: {comment_id}){f' (In Reply To: {in_reply_to_id})' if in_reply_to_id else ''}")
+        if created_at:
+            print(f"Timestamp: {created_at}")
+
+        if diff_hunk: # Only show status if it's a diff-related comment
+            status_text = "[OUTDATED]" if hunk_position is None else "[CURRENT]"
+            print(f"Status: {status_text}")
+
         print(f"File: {path}")
-        # The 'line' field in GitHub's API for PR review comments refers to the line number in the diff.
-        # 'original_line' refers to the line number in the file at the time the comment was made.
-        # 'start_line' and 'original_start_line' for multi-line comments.
-        # For simplicity, we use 'line'.
-        print(f"Line in diff: {line}")
+        print(f"Line in File Diff: {file_line}")
         print(f"URL: {html_url}")
-        print("--- Diff Hunk ---")
-        print(diff_hunk)
+
+        print("--- Diff Hunk Context ---")
+        if diff_hunk:
+            print_contextual_diff_hunk(diff_hunk, hunk_position, args.context_lines)
+        else:
+            print("(Comment not associated with a specific diff hunk)")
+
         print("--- Comment ---")
         print(body)
-        print("----------------------------------------\n")
+        print("----------------------------------------\n") # Use
+ for newline
 
 if __name__ == "__main__":
     main()