feat: Fluent review workflow API

[jordanpartridge]

Closes #22

Summary

• Implemented ReviewBuilder for fluent review creation with approve(), requestChanges(), comment()
• Implemented ReviewQuery for filtering reviews with whereApproved(), whereChangesRequested(), byUser()
• Updated Reviewable interface and PullRequest class to use new fluent API
• Maintained backward compatibility with existing submitReview() method

Features

ReviewBuilder

• approve(?string $comment): Create approval review
• requestChanges(?string $comment): Request changes with optional comment
• comment(string $body): Add comment review
• addInlineComment(string $path, int $line, string $comment): Line-level feedback
• addSuggestion(string $path, int $startLine, int $endLine, string $suggestion): Code suggestions
• submit(): Finalize and create the review

ReviewQuery

• get(): Retrieve all reviews
• whereApproved(): Filter approved reviews
• whereChangesRequested(): Filter reviews requesting changes
• whereCommented(): Filter comment-only reviews
• byUser(string $username): Filter by reviewer
• latest(): Get most recent review
• first(): Get first review
• count(): Count total reviews

Usage Examples

Simple Approval

$pr->approve('LGTM!')->submit();

Request Changes with Inline Comments

$pr->requestChanges('Please address the following')
   ->addInlineComment('src/Service.php', 42, 'Race condition here')
   ->addInlineComment('tests/ServiceTest.php', 15, 'Missing edge case')
   ->submit();

Code Suggestions

$pr->review()
   ->comment('Code improvement suggestions')
   ->addSuggestion('src/Controller.php', 20, 22, 'return $this->repository->findOrFail($id);')
   ->submit();

Query Reviews

// Get all approved reviews
$approvals = $pr->reviews()->whereApproved();

// Get latest review
$latest = $pr->reviews()->latest();

// Check if user approved
$userApproved = $pr->reviews()
    ->byUser('senior-dev')
    ->whereApproved()
    ->count() > 0;

Test Coverage

• 201 tests passing
• 100% code coverage
• All quality gates passing (PHPStan, Pint)

Breaking Changes

• reviews() method now returns ReviewQuery instead of array
  • Migration: Change $pr->reviews() to $pr->reviews()->get()
• approve() and requestChanges() now return ReviewBuilder instead of static
  • Migration: Add ->submit() call to execute the review

[coderabbitai]

Warning

Rate limit exceeded

@jordanpartridge has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 9 minutes and 39 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 999c734 and d090e68.

📒 Files selected for processing (9)

• src/Contracts/ReviewBuilderInterface.php (1 hunks)
• src/Contracts/Reviewable.php (2 hunks)
• src/PullRequest.php (3 hunks)
• src/Services/ReviewBuilder.php (1 hunks)
• src/Services/ReviewQuery.php (1 hunks)
• tests/Unit/PullRequestWrapperTest.php (1 hunks)
• tests/Unit/ReviewTest.php (3 hunks)
• tests/Unit/Services/ReviewBuilderTest.php (1 hunks)
• tests/Unit/Services/ReviewQueryTest.php (1 hunks)

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/reviews-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}