Core: PullRequestQuery builder with fluent filtering API

[jordanpartridge]

Summary

Implement the core PullRequestQuery builder class with fluent filtering API for querying pull requests.

Acceptance Criteria

Query Builder Interface

• Create Contracts\PullRequestQueryInterface with all query method signatures
• Implement Services\PullRequestQuery implementing the interface
• Support repository context initialization
• Return strongly-typed collections of PR DTOs

Filtering Methods

// State filters
->whereOpen()
->whereClosed()
->whereMerged()
->whereDraft()
->whereState(string $state) // 'open' | 'closed' | 'all'

// Branch filters
->whereBase(string $branch)
->whereHead(string $branch)

// Author filters
->whereAuthor(string $username)

// Label filters
->whereLabel(string $label)
->whereLabels(array $labels) // Match any
->whereAllLabels(array $labels) // Match all

// Time filters
->whereStaleDays(int $days) // Updated more than X days ago
->whereSince(Carbon $date)
->whereUpdatedAfter(Carbon $date)
->whereCreatedAfter(Carbon $date)

// Review filters
->whereApproved()
->whereChangesRequested()
->whereReviewPending()

// Check filters
->whereChecksPassing()
->whereChecksFailing()

// Sort options
->orderByCreated(string $direction = 'desc')
->orderByUpdated(string $direction = 'desc')
->orderByPopularity() // comments count
->orderByLongRunning() // oldest updated first

Pagination

->perPage(int $count)
->page(int $page)

Execution Methods

->get(): Collection<PullRequest>
->first(): ?PullRequest
->count(): int
->exists(): bool
->pluck(string $key): Collection

Batch Operations

// Laravel collection proxying
->each(callable $callback)
->filter(callable $callback)
->map(callable $callback)

Technical Implementation

Class Structure

namespace ConduitUI\Pr\Services;

use ConduitUI\Connector\GitHub;
use ConduitUI\Pr\Contracts\PullRequestQueryInterface;
use ConduitUI\Pr\Data\PullRequest;
use Illuminate\Support\Collection;

final class PullRequestQuery implements PullRequestQueryInterface
{
    protected ?string $state = null;
    protected ?string $head = null;
    protected ?string $base = null;
    protected ?string $sort = 'created';
    protected string $direction = 'desc';
    protected int $perPage = 30;
    protected int $page = 1;
    
    public function __construct(
        protected GitHub $github,
        protected string $fullName,
    ) {}
    
    protected function buildEndpoint(): string
    {
        return "/repos/{$this->fullName}/pulls";
    }
    
    protected function buildParams(): array
    {
        // Build GitHub API query params
    }
    
    public function get(): Collection
    {
        $response = $this->github->get(
            $this->buildEndpoint(),
            $this->buildParams()
        );
        
        return collect($response->json())
            ->map(fn(array $pr) => PullRequest::fromArray($pr));
    }
}

Interface Definition

namespace ConduitUI\Pr\Contracts;

use Illuminate\Support\Collection;
use ConduitUI\Pr\Data\PullRequest;

interface PullRequestQueryInterface
{
    public function whereOpen(): self;
    public function whereClosed(): self;
    public function whereMerged(): self;
    public function whereState(string $state): self;
    public function whereBase(string $branch): self;
    public function whereHead(string $branch): self;
    public function whereAuthor(string $username): self;
    public function orderByCreated(string $direction = 'desc'): self;
    public function orderByUpdated(string $direction = 'desc'): self;
    public function perPage(int $count): self;
    public function page(int $page): self;
    public function get(): Collection;
    public function first(): ?PullRequest;
    public function count(): int;
}

Dependencies

• conduit-ui/connector (GitHub API client)
• Data\PullRequest DTO (created in separate issue)

Testing Requirements

it('filters open PRs')
    ->expect(fn() => PullRequests::forRepo('test/repo')->whereOpen()->get())
    ->toBeInstanceOf(Collection::class);

it('filters by base branch')
    ->expect(fn() => PullRequests::forRepo('test/repo')->whereBase('main')->get())
    ->toBeInstanceOf(Collection::class);

it('chains multiple filters')
    ->expect(fn() => 
        PullRequests::forRepo('test/repo')
            ->whereOpen()
            ->whereAuthor('jordan')
            ->whereBase('main')
            ->get()
    )->toBeInstanceOf(Collection::class);

References

• GitHub API: https://docs.github.com/en/rest/pulls/pulls#list-pull-requests
• Similar pattern: conduit-ui/repo RepositoryQuery
• Related: Add PrService interface for clean dependency injection #2 (PullRequest DTO)

Labels

• enhancement
• core
• query-builder

[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

• Test: QueryBuilder fluent methods #13

Related Issues

• Implement expressive fluent RepositoryQuery builder repo#2
• Scaffold prs package - extract from github-client prs#1
• Add PrService interface for clean dependency injection #2

🔗 Related PRs

conduit-ui/issues#1 - Refactor IssuesServiceInterface to extend individual interfaces [merged]
conduit-ui/conduit#47 - 🚀 Phase 1 GitHub Integration + Security Enhancements [merged]
conduit-ui/conduit#73 - 🧵 FEATURE: Complete PR Comment Threading System [merged]
#6 - Add Saloon Request classes, service layer, and pagination [merged]
#17 - Define key agent interfaces for PRs and issues [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 40 seconds before sending another message.