Reviews: Fluent review workflow API

[jordanpartridge]

Summary

Implement expressive review workflow API for approving, requesting changes, commenting, and managing PR reviews.

Acceptance Criteria

Review Builder Interface

namespace ConduitUI\Pr\Contracts;

interface ReviewBuilderInterface
{
    public function approve(string $comment = null): self;
    public function requestChanges(string $comment = null): self;
    public function comment(string $body): self;
    public function addInlineComment(string $path, int $line, string $comment): self;
    public function addSuggestion(string $path, int $startLine, int $endLine, string $suggestion): self;
    public function submit(): Review;
}

Review Builder Implementation

namespace ConduitUI\Pr\Services;

use ConduitUI\Pr\Contracts\ReviewBuilderInterface;
use ConduitUI\Pr\Data\Review;

final class ReviewBuilder implements ReviewBuilderInterface
{
    protected ?string $event = null; // APPROVE | REQUEST_CHANGES | COMMENT
    protected ?string $body = null;
    protected array $comments = [];
    
    public function __construct(
        protected GitHub $github,
        protected string $fullName,
        protected int $prNumber,
    ) {}
    
    public function approve(string $comment = null): self
    {
        $this->event = 'APPROVE';
        $this->body = $comment;
        return $this;
    }
    
    public function requestChanges(string $comment = null): self
    {
        $this->event = 'REQUEST_CHANGES';
        $this->body = $comment ?? 'Changes requested';
        return $this;
    }
    
    public function comment(string $body): self
    {
        $this->event = 'COMMENT';
        $this->body = $body;
        return $this;
    }
    
    public function addInlineComment(
        string $path,
        int $line,
        string $comment
    ): self {
        $this->comments[] = [
            'path' => $path,
            'line' => $line,
            'body' => $comment,
        ];
        return $this;
    }
    
    public function addSuggestion(
        string $path,
        int $startLine,
        int $endLine,
        string $suggestion
    ): self {
        $this->comments[] = [
            'path' => $path,
            'start_line' => $startLine,
            'line' => $endLine,
            'body' => "```suggestion\n{$suggestion}\n```",
        ];
        return $this;
    }
    
    public function submit(): Review
    {
        $response = $this->github->post(
            "/repos/{$this->fullName}/pulls/{$this->prNumber}/reviews",
            [
                'event' => $this->event,
                'body' => $this->body,
                'comments' => $this->comments,
            ]
        );
        
        return Review::fromArray($response->json());
    }
}

Review Query

namespace ConduitUI\Pr\Services;

final class ReviewQuery
{
    public function __construct(
        protected GitHub $github,
        protected string $fullName,
        protected int $prNumber,
    ) {}
    
    public function get(): Collection
    {
        $response = $this->github->get(
            "/repos/{$this->fullName}/pulls/{$this->prNumber}/reviews"
        );
        
        return collect($response->json())
            ->map(fn($review) => Review::fromArray($review));
    }
    
    public function whereApproved(): Collection
    {
        return $this->get()->where('state', 'APPROVED');
    }
    
    public function whereChangesRequested(): Collection
    {
        return $this->get()->where('state', 'CHANGES_REQUESTED');
    }
    
    public function wherePending(): Collection
    {
        return $this->get()->where('state', 'PENDING');
    }
    
    public function byUser(string $username): Collection
    {
        return $this->get()->where('user.login', $username);
    }
    
    public function latest(): ?Review
    {
        return $this->get()->sortByDesc('submitted_at')->first();
    }
}

Review DTO

namespace ConduitUI\Pr\Data;

final readonly class Review
{
    public function __construct(
        public int $id,
        public User $user,
        public string $state, // APPROVED | CHANGES_REQUESTED | COMMENTED | PENDING
        public ?string $body,
        public string $htmlUrl,
        public Carbon $submittedAt,
    ) {}
    
    public static function fromArray(array $data): self;
    
    public function isApproved(): bool
    {
        return $this->state === 'APPROVED';
    }
    
    public function isChangesRequested(): bool
    {
        return $this->state === 'CHANGES_REQUESTED';
    }
    
    public function isPending(): bool
    {
        return $this->state === 'PENDING';
    }
}

Usage Examples

Simple Approval

PullRequests::find('owner/repo', 123)
    ->approve('LGTM! Great work.')
    ->submit();

Request Changes with Inline Comments

PullRequests::find('owner/repo', 456)
    ->requestChanges('Please address the following concerns:')
    ->addInlineComment('src/Service.php', 42, 'This could cause a race condition')
    ->addInlineComment('tests/ServiceTest.php', 15, 'Missing edge case test')
    ->submit();

Add Code Suggestions

PullRequests::find('owner/repo', 789)
    ->comment('Few suggestions for improvement')
    ->addSuggestion('src/Controller.php', 20, 22, 
        'return $this->repository->findOrFail($id);'
    )
    ->submit();

Query Reviews

$pr = PullRequests::find('owner/repo', 123);

// Get all reviews
$reviews = $pr->reviews()->get();

// Filter reviews
$approvals = $pr->reviews()->whereApproved();
$changesRequested = $pr->reviews()->whereChangesRequested();

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

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

Automation: Auto-approve Dependabot

PullRequests::forRepo('owner/repo')
    ->whereOpen()
    ->whereAuthor('dependabot[bot]')
    ->get()
    ->filter(fn($pr) => $pr->checksPass())
    ->each(fn($pr) => 
        $pr->approve('Auto-approving passing dependency update')
           ->submit()
    );

Testing Requirements

it('submits approval review')
    ->expect(fn() => 
        PullRequests::find('test/repo', 1)
            ->approve('LGTM')
            ->submit()
    )->toBeInstanceOf(Review::class);

it('submits changes requested with comments')
    ->expect(fn() => 
        PullRequests::find('test/repo', 1)
            ->requestChanges('Please fix')
            ->addInlineComment('src/File.php', 10, 'Issue here')
            ->submit()
    )->toBeInstanceOf(Review::class);

it('queries approved reviews')
    ->expect(fn() => 
        PullRequests::find('test/repo', 1)
            ->reviews()
            ->whereApproved()
    )->toBeInstanceOf(Collection::class);

Dependencies

• conduit-ui/connector
• Data\Review DTO
• Data\User DTO
• Related to Add PrService interface for clean dependency injection #2 (PullRequest DTO)

References

• GitHub API Reviews: https://docs.github.com/en/rest/pulls/reviews
• GitHub API Review Comments: https://docs.github.com/en/rest/pulls/comments

Labels

• enhancement
• reviews
• workflow

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• Data: PullRequest DTO with chainable actions #21

Related Issues

• Core: PullRequestQuery builder with fluent filtering API #20
• Scaffold prs package - extract from github-client prs#1
• 🔄 Feature: PR Workflow Automation conduit#59
• 🔍 Feature: PR Review Analysis Command conduit#55

🔗 Related PRs

conduit-ui/connector#1 - Update package namespace to conduit-ui [merged]
conduit-ui/conduit#47 - 🚀 Phase 1 GitHub Integration + Security Enhancements [merged]
conduit-ui/conduit#73 - 🧵 FEATURE: Complete PR Comment Threading System [merged]
#9 - feat: add Laravel service provider for zero-config setup [merged]
#10 - feat: support inline comments in submitReview [merged]

👤 Suggested Assignees

• jordanpartridge

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[jordanpartridge]

@coderabbitai create plan

[coderabbitai]

Rate Limit Exceeded

@jordanpartridge have exceeded the limit for the number of chat messages per hour. Please wait 1 minutes and 34 seconds before sending another message.

[jordanpartridge]

Implemented and merged via #36. src/Services/ReviewBuilder.php and src/Services/ReviewQuery.php provide the fluent review workflow API, with approve() / requestChanges() / review() / reviews() entry points on PullRequest.