Improve PR comments with GitHub suggestions (#6)

## Summary
- Remove "Tool: ClaudeCode AI Review" line from comments
- Add support for GitHub suggestion blocks when a code fix is available
- Add `suggestion` field to finding schema in all prompts

When the AI provides a `suggestion` field with exact replacement code,
it will now render as a GitHub suggestion block that can be committed
directly from the PR.

## Test plan
- [x] Python tests pass (177)
- [ ] Bun tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: matej

claudecode/prompts.py

@@ -180,6 +180,9 @@ def get_unified_review_prompt(
       "description": "What is wrong and where it happens",
       "impact": "Concrete impact or failure mode (use exploit scenario for security issues)",
       "recommendation": "Actionable fix or mitigation",
+      "suggestion": "Exact replacement code (optional). Can be multi-line. Must replace lines from suggestion_start_line to suggestion_end_line.",
+      "suggestion_start_line": 42,
+      "suggestion_end_line": 44,
       "confidence": 0.95
     }}
   ],
@@ -192,6 +195,12 @@ def get_unified_review_prompt(
   }}
 }}
 
+SUGGESTION GUIDELINES:
+- Only include `suggestion` if you can provide exact, working replacement code
+- For single-line fixes: set suggestion_start_line = suggestion_end_line = the line number
+- For multi-line fixes: set the range of lines being replaced
+- The suggestion replaces all lines from suggestion_start_line to suggestion_end_line (inclusive)
+
 SEVERITY GUIDELINES:
 - **HIGH**: Likely production bug, data loss, significant regression, or directly exploitable security vulnerability
 - **MEDIUM**: Real issue with limited scope or specific triggering conditions
@@ -343,6 +352,9 @@ def get_code_review_prompt(
       "description": "What is wrong and where it happens",
       "impact": "Concrete impact or failure mode",
       "recommendation": "Actionable fix or mitigation",
+      "suggestion": "Exact replacement code (optional). Can be multi-line. Must replace lines from suggestion_start_line to suggestion_end_line.",
+      "suggestion_start_line": 42,
+      "suggestion_end_line": 44,
       "confidence": 0.95
     }}
   ],
@@ -355,6 +367,12 @@ def get_code_review_prompt(
   }}
 }}
 
+SUGGESTION GUIDELINES:
+- Only include `suggestion` if you can provide exact, working replacement code
+- For single-line fixes: set suggestion_start_line = suggestion_end_line = the line number
+- For multi-line fixes: set the range of lines being replaced
+- The suggestion replaces all lines from suggestion_start_line to suggestion_end_line (inclusive)
+
 SEVERITY GUIDELINES:
 - **HIGH**: Likely production bug, data loss, or significant regression
 - **MEDIUM**: Real issue with limited scope or specific triggering conditions
@@ -506,6 +524,9 @@ def get_security_review_prompt(
       "description": "What is wrong and where it happens",
       "impact": "Exploit scenario or concrete impact",
       "recommendation": "Actionable fix or mitigation",
+      "suggestion": "Exact replacement code (optional). Can be multi-line. Must replace lines from suggestion_start_line to suggestion_end_line.",
+      "suggestion_start_line": 42,
+      "suggestion_end_line": 44,
       "confidence": 0.95
     }}
   ],
@@ -518,6 +539,12 @@ def get_security_review_prompt(
   }}
 }}
 
+SUGGESTION GUIDELINES:
+- Only include `suggestion` if you can provide exact, working replacement code
+- For single-line fixes: set suggestion_start_line = suggestion_end_line = the line number
+- For multi-line fixes: set the range of lines being replaced
+- The suggestion replaces all lines from suggestion_start_line to suggestion_end_line (inclusive)
+
 SEVERITY GUIDELINES:
 - **HIGH**: Directly exploitable vulnerabilities leading to RCE, data breach, or authentication bypass
 - **MEDIUM**: Vulnerabilities requiring specific conditions but with significant impact

scripts/comment-pr-findings.bun.test.js

@@ -488,9 +488,133 @@ describe('comment-pr-findings.js', () => {
       expect(comment.body).toContain('🤖 **Code Review Finding:');
       expect(comment.body).toContain('**Severity:** HIGH');
       expect(comment.body).toContain('**Category:** security');
-      expect(comment.body).toContain('**Tool:** ClaudeCode AI Review');
       expect(consoleLogSpy).toHaveBeenCalledWith('Created review with 1 inline comments');
     });
+
+    test('should include GitHub suggestion block when suggestion is provided', async () => {
+      const mockFindings = [{
+        file: 'test.py',
+        line: 10,
+        description: 'Unsafe pickle usage',
+        severity: 'HIGH',
+        category: 'security',
+        recommendation: 'Use json.loads instead',
+        suggestion: 'data = json.loads(user_input)'
+      }];
+
+      const mockPrFiles = [{
+        filename: 'test.py',
+        patch: '@@ -10,1 +10,1 @@'
+      }];
+
+      readFileSyncSpy.mockImplementation((path) => {
+        if (path.includes('github-event.json')) {
+          return JSON.stringify({
+            pull_request: { number: 123, head: { sha: 'abc123' } }
+          });
+        }
+        if (path === 'findings.json') {
+          return JSON.stringify(mockFindings);
+        }
+      });
+
+      let capturedReviewData;
+      spawnSyncSpy.mockImplementation((cmd, args, options) => {
+        if (cmd === 'gh' && args.includes('api')) {
+          const endpoint = args[1];
+          const method = args[args.indexOf('--method') + 1] || 'GET';
+
+          if (endpoint.includes('/pulls/123/files')) {
+            return { status: 0, stdout: JSON.stringify(mockPrFiles), stderr: '' };
+          }
+          if (endpoint.includes('/pulls/123/comments') && method === 'GET') {
+            return { status: 0, stdout: '[]', stderr: '' };
+          }
+          if (endpoint.includes('/pulls/123/reviews') && method === 'POST') {
+            if (options && options.input) {
+              capturedReviewData = JSON.parse(options.input);
+            }
+            return { status: 0, stdout: '{}', stderr: '' };
+          }
+          return { status: 0, stdout: '{}', stderr: '' };
+        }
+        return { status: 0, stdout: '{}', stderr: '' };
+      });
+
+      await import('./comment-pr-findings.js');
+
+      expect(capturedReviewData).toBeDefined();
+      expect(capturedReviewData.comments).toHaveLength(1);
+
+      const comment = capturedReviewData.comments[0];
+      expect(comment.body).toContain('```suggestion');
+      expect(comment.body).toContain('data = json.loads(user_input)');
+      expect(comment.body).toContain('```');
+    });
+
+    test('should include start_line for multi-line suggestions', async () => {
+      const mockFindings = [{
+        file: 'test.py',
+        line: 12,
+        description: 'Unsafe database query',
+        severity: 'HIGH',
+        category: 'security',
+        recommendation: 'Use parameterized queries',
+        suggestion: 'cursor.execute(\n    "SELECT * FROM users WHERE id = ?",\n    (user_id,)\n)',
+        suggestion_start_line: 10,
+        suggestion_end_line: 12
+      }];
+
+      const mockPrFiles = [{
+        filename: 'test.py',
+        patch: '@@ -10,3 +10,3 @@'
+      }];
+
+      readFileSyncSpy.mockImplementation((path) => {
+        if (path.includes('github-event.json')) {
+          return JSON.stringify({
+            pull_request: { number: 123, head: { sha: 'abc123' } }
+          });
+        }
+        if (path === 'findings.json') {
+          return JSON.stringify(mockFindings);
+        }
+      });
+
+      let capturedReviewData;
+      spawnSyncSpy.mockImplementation((cmd, args, options) => {
+        if (cmd === 'gh' && args.includes('api')) {
+          const endpoint = args[1];
+          const method = args[args.indexOf('--method') + 1] || 'GET';
+
+          if (endpoint.includes('/pulls/123/files')) {
+            return { status: 0, stdout: JSON.stringify(mockPrFiles), stderr: '' };
+          }
+          if (endpoint.includes('/pulls/123/comments') && method === 'GET') {
+            return { status: 0, stdout: '[]', stderr: '' };
+          }
+          if (endpoint.includes('/pulls/123/reviews') && method === 'POST') {
+            if (options && options.input) {
+              capturedReviewData = JSON.parse(options.input);
+            }
+            return { status: 0, stdout: '{}', stderr: '' };
+          }
+          return { status: 0, stdout: '{}', stderr: '' };
+        }
+        return { status: 0, stdout: '{}', stderr: '' };
+      });
+
+      await import('./comment-pr-findings.js');
+
+      expect(capturedReviewData).toBeDefined();
+      expect(capturedReviewData.comments).toHaveLength(1);
+
+      const comment = capturedReviewData.comments[0];
+      expect(comment.body).toContain('```suggestion');
+      expect(comment.start_line).toBe(10);
+      expect(comment.line).toBe(12);
+      expect(comment.start_side).toBe('RIGHT');
+    });
   });
 
   describe('Error Handling', () => {

scripts/comment-pr-findings.js

@@ -133,41 +133,57 @@ async function run() {
       const title = finding.title || message;
       const severity = finding.severity || 'HIGH';
       const category = finding.category || 'review_issue';
-      
+
       // Check if this file is part of the PR diff
       if (!fileMap[file]) {
         console.log(`File ${file} not in PR diff, skipping`);
         continue;
       }
-      
+
       // Build the comment body
       let commentBody = `🤖 **Code Review Finding: ${title}**\n\n`;
       commentBody += `**Severity:** ${severity}\n`;
       commentBody += `**Category:** ${category}\n`;
-      commentBody += `**Tool:** ClaudeCode AI Review\n`;
-      
+
       const extraMetadata = (finding.extra && finding.extra.metadata) || {};
 
       // Add impact/exploit scenario if available
       if (finding.impact || finding.exploit_scenario || extraMetadata.impact || extraMetadata.exploit_scenario) {
         const impact = finding.impact || finding.exploit_scenario || extraMetadata.impact || extraMetadata.exploit_scenario;
         commentBody += `\n**Impact:** ${impact}\n`;
       }
-      
+
       // Add recommendation if available
-      if (finding.recommendation || extraMetadata.recommendation) {
-        const recommendation = finding.recommendation || extraMetadata.recommendation;
+      const recommendation = finding.recommendation || extraMetadata.recommendation;
+      if (recommendation) {
         commentBody += `\n**Recommendation:** ${recommendation}\n`;
       }
-      
+
+      // Add GitHub suggestion block if a code suggestion is available
+      const suggestion = finding.suggestion || extraMetadata.suggestion;
+      if (suggestion) {
+        commentBody += `\n\`\`\`suggestion\n${suggestion}\n\`\`\`\n`;
+      }
+
       // Prepare the review comment
       const reviewComment = {
         path: file,
         line: line,
         side: 'RIGHT',
         body: commentBody
       };
-      
+
+      // Handle multi-line suggestions by adding start_line
+      const suggestionStartLine = finding.suggestion_start_line || extraMetadata.suggestion_start_line;
+      const suggestionEndLine = finding.suggestion_end_line || extraMetadata.suggestion_end_line;
+
+      if (suggestion && suggestionStartLine && suggestionEndLine && suggestionStartLine !== suggestionEndLine) {
+        // Multi-line suggestion: start_line is the first line, line is the last line
+        reviewComment.start_line = suggestionStartLine;
+        reviewComment.line = suggestionEndLine;
+        reviewComment.start_side = 'RIGHT';
+      }
+
       reviewComments.push(reviewComment);
     }