Implement Core IssueQuery Builder with Fluent Filtering API

[jordanpartridge]

Summary

Implement a fluent IssueQuery builder that provides an expressive, Laravel-style API for filtering and querying GitHub issues. This should follow the established patterns from conduit-ui/repo (RepositoryQuery, BranchQuery).

Requirements

Query Building Pattern

use ConduitUI\Issue\Facades\Issues;

// Basic queries
Issues::forRepo('owner/repo')
    ->whereOpen()
    ->get();

Issues::forRepo('owner/repo')
    ->whereClosed()
    ->get();

// Label filtering
Issues::forRepo('owner/repo')
    ->whereLabel('bug')
    ->get();

Issues::forRepo('owner/repo')
    ->whereLabels(['bug', 'priority-high'])
    ->get();

// Assignee filtering
Issues::forRepo('owner/repo')
    ->assignedTo('username')
    ->get();

Issues::forRepo('owner/repo')
    ->whereUnassigned()
    ->get();

// Author filtering
Issues::forRepo('owner/repo')
    ->createdBy('username')
    ->get();

// Time-based filtering
Issues::forRepo('owner/repo')
    ->createdAfter(now()->subWeek())
    ->get();

Issues::forRepo('owner/repo')
    ->updatedBefore(now()->subDays(90))
    ->get();

Issues::forRepo('owner/repo')
    ->older(days: 90)
    ->get();

// Sorting
Issues::forRepo('owner/repo')
    ->orderByCreated('desc')
    ->get();

Issues::forRepo('owner/repo')
    ->orderByUpdated('asc')
    ->get();

// Pagination
Issues::forRepo('owner/repo')
    ->perPage(50)
    ->page(2)
    ->get();

// Complex queries
Issues::forRepo('owner/repo')
    ->whereOpen()
    ->whereLabel('bug')
    ->assignedTo('jordan')
    ->createdAfter(now()->subWeek())
    ->orderByCreated('desc')
    ->get();

Implementation Details

Class Structure:

• ConduitUI\Issue\Services\IssueQuery
• Constructor should accept GitHub $github (from conduit-ui/connector)
• All query methods return $this for chaining
• Final get() method returns Collection of Issue DTOs

Query Methods:

• forRepo(string $fullName): self - Set repository context
• whereOpen(): self - Filter to open issues
• whereClosed(): self - Filter to closed issues
• whereState(string $state): self - Filter by state (open|closed|all)
• whereLabel(string $label): self - Filter by single label
• whereLabels(array $labels): self - Filter by multiple labels
• assignedTo(string $username): self - Filter by assignee
• whereUnassigned(): self - Filter to unassigned issues
• createdBy(string $username): self - Filter by author
• mentioning(string $username): self - Filter by mentioned user
• createdAfter(Carbon|string $date): self - Filter by creation date
• updatedBefore(Carbon|string $date): self - Filter by update date
• older(int $days): self - Convenience method for stale issues
• orderBy(string $field, string $direction = 'desc'): self - Sort results
• orderByCreated(string $direction = 'desc'): self - Convenience method
• orderByUpdated(string $direction = 'desc'): self - Convenience method
• perPage(int $perPage): self - Set pagination limit
• page(int $page): self - Set page number
• get(): Collection - Execute query and return results
• count(): int - Get count of matching issues
• exists(): bool - Check if any issues match
• first(): ?Issue - Get first matching issue

Protected Helper Methods:

• buildEndpoint(): string - Build API endpoint
• buildParams(): array - Build query parameters

GitHub API Mapping

Reference: https://docs.github.com/en/rest/issues/issues#list-repository-issues

Query Parameters:

• state → open, closed, all (default: open)
• labels → comma-separated list
• assignee → username or "none"
• creator → username
• mentioned → username
• since → ISO 8601 timestamp
• sort → created, updated, comments (default: created)
• direction → asc, desc (default: desc)
• per_page → 1-100 (default: 30)
• page → page number

Return Type

use ConduitUI\Issue\Data\Issue;
use Illuminate\Support\Collection;

/** @return Collection<int, Issue> */
public function get(): Collection

Testing Requirements

Unit Tests:

• Test each filter method sets correct internal state
• Test method chaining returns self
• Test buildParams() generates correct query parameters
• Test buildEndpoint() generates correct API path

Integration Tests:

• Test get() returns Collection of Issue DTOs
• Test filtering by labels
• Test filtering by assignee
• Test time-based filtering
• Test sorting
• Test pagination
• Test complex multi-filter queries

Related Files to Reference

From conduit-ui/repo:

• src/Services/RepositoryQuery.php - Query pattern
• src/Services/BranchQuery.php - Advanced filtering example
• src/Services/CommitQuery.php - Time-based filtering

Acceptance Criteria

• IssueQuery class implements all query methods
• All methods return self for chaining
• get() method returns Collection of Issue DTOs
• Query parameters correctly map to GitHub API
• Time-based filtering handles Carbon and string dates
• Full test coverage (unit + integration)
• Follows existing conduit-ui patterns
• Type hints and return types on all methods
• PHPDoc blocks on all public methods

Dependencies

• Requires: ConduitUI\Connector\GitHub
• Requires: ConduitUI\Issue\Data\Issue (from Add Active Record entity layer (matching conduit-ui/pr pattern) #2)
• Related to: 🔒 Security audit for production release #7 (Contracts)

Technical Notes

Pattern Consistency:
Follow the established patterns from conduit-ui/repo:

1. Constructor injection of GitHub client
2. Fluent method chaining
3. Protected state properties
4. Single get() execution method
5. Helper methods for building endpoint/params

Date Handling:

use Carbon\Carbon;

protected function formatDate(Carbon|string $date): string
{
    return $date instanceof Carbon 
        ? $date->toIso8601String()
        : Carbon::parse($date)->toIso8601String();
}

Examples

Triage Bot:

Issues::forRepo('laravel/framework')
    ->whereOpen()
    ->whereUnassigned()
    ->whereLabel('bug')
    ->createdAfter(now()->subDay())
    ->get()
    ->each(fn($issue) => triageIssue($issue));

Stale Issue Detection:

$staleIssues = Issues::forRepo('owner/repo')
    ->whereOpen()
    ->older(days: 90)
    ->get();

Team Dashboard:

$myIssues = Issues::forRepo('owner/repo')
    ->whereOpen()
    ->assignedTo('jordan')
    ->orderByUpdated('asc')
    ->get();

[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 pr#13

Related Issues

• Implement expressive fluent RepositoryQuery builder repo#2
• Add Issue Events and Timeline functionality issues#4
• Add Issue Milestones functionality issues#3
• Add Active Record entity layer (matching conduit-ui/pr pattern) #2
• Implement comprehensive release management API repo#5

🔗 Related PRs

conduit-ui/issues#6 - Add comprehensive test suite and CI workflows [closed]
conduit-ui/conduit#48 - 🔒 SECURITY: Make Conduit Great Again - CodeRabbit Security Revolution [merged]
conduit-ui/pr#6 - Add Saloon Request classes, service layer, and pagination [merged]
#3 - feat: Add explicit Saloon requests and comprehensive error handling [merged]
#18 - feat: add Comment Reactions functionality (#8) [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]

Coding Plan

Approach

Ticket Overview

Implement a fluent IssueQuery builder that provides a Laravel-style chainable API for filtering and querying GitHub issues. The builder will support filtering by state, labels, assignees, authors, time ranges, sorting, and pagination, and will return a Collection of Issue DTOs.

Observations

Codebase Summary

This is a Laravel package for interacting with the GitHub Issues API, following a service-oriented architecture with Saloon HTTP library for API communication. The package includes an IssuesService that uses trait-based composition for different GitHub issue operations, DTOs for Issue/Comment/Label/User/Milestone entities, Saloon request classes for API endpoints, a GithubIssues facade for static access, and Pest PHP-based testing. The existing ListIssuesRequest already handles the /repos/{owner}/{repo}/issues endpoint with filter arrays passed through constructor parameters.

Assumptions

Assumption 1: Repository identifier format in forRepo() method

Options Considered:

• Accept single string 'owner/repo' and parse internally (matches ticket examples exactly)
• Accept two separate parameters forRepo(string $owner, string $repo) (matches existing patterns)

Chosen Option: Accept single string 'owner/repo' and parse internally (matches ticket examples exactly)

Rationale: This provides the most expressive, developer-friendly API as shown in the ticket examples, aligns with the referenced conduit-ui/repo patterns, and keeps method signatures clean. The internal parsing adds minimal complexity (simple explode('/', $fullName, 2)) and provides better validation opportunities.

Assumption 2: Integration point for query builder

Options Considered:

• Add factory method to IssuesService that returns IssueQuery instances
• Create static factory method on IssueQuery class directly
• Register IssueQuery as separate container binding

Chosen Option: Add factory method to IssuesService that returns IssueQuery instances

Rationale: Add factory method forRepo() to IssuesService that instantiates and returns an IssueQuery with the connector dependency injected. This maintains consistency with the existing service layer pattern, ensures proper dependency injection through the service, and allows the facade to proxy naturally. The service acts as the entry point for all issue-related functionality, keeping architecture clean.

Assumption 3: Date parameter handling for time-based filtering

Options Considered:

• Use union types Carbon|string and handle both (ticket specification)
• Accept only Carbon instances, requiring callers to convert strings
• Use Carbon|\DateTimeInterface|string to support broader date types

Chosen Option: Use union types Carbon|string and handle both (ticket specification)

Rationale: Use Carbon|string union type with internal conversion helper method that uses Carbon::parse() for strings. This exactly matches the ticket specification, provides maximum flexibility for developers (they can pass Carbon objects from Laravel helpers or string dates from external sources), and follows the pattern shown in the ticket's technical notes. The internal formatDate() helper ensures consistent ISO 8601 formatting for the GitHub API.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Query Builder Implementation

Create the IssueQuery class with fluent filtering API, protected state management, and GitHub API integration through the existing ListIssuesRequest class.

Task 1: Create IssueQuery Class Structure

Set up the query builder class with constructor dependency injection and protected state properties.

• Create src/Services/IssueQuery.php with constructor accepting Connector $connector (readonly property)
• Add protected properties for query state: $owner, $repo, $filters (array), $sort, $direction, $perPage, $page
• Implement forRepo(string $fullName): self that parses owner/repo from format like 'owner/repo' using explode('/', $fullName, 2)
• Ensure all state properties are initialized to appropriate defaults (filters as empty array, direction as 'desc', etc.)

Task 2: Implement State Filter Methods

Add fluent methods for filtering by issue state (open/closed/all).

• Implement whereOpen(): self that sets $this->filters['state'] = 'open'
• Implement whereClosed(): self that sets $this->filters['state'] = 'closed'
• Implement whereState(string $state): self for explicit state setting with validation
• Ensure all methods return $this for method chaining

Task 3: Implement Label and Assignee Filtering

Add methods for filtering by labels and assignees using GitHub API query parameters.

• Implement whereLabel(string $label): self that appends to labels array in filters
• Implement whereLabels(array $labels): self that merges/sets multiple labels
• Implement assignedTo(string $username): self that sets $this->filters['assignee']
• Implement whereUnassigned(): self that sets $this->filters['assignee'] = 'none'
• Handle label array to comma-separated string conversion in buildParams() method

Task 4: Implement Author and Mention Filtering

Add methods for filtering by issue creator and mentioned users.

• Implement createdBy(string $username): self that sets $this->filters['creator']
• Implement mentioning(string $username): self that sets $this->filters['mentioned']
• Store values in filters array for later API parameter building

Task 5: Implement Time-Based Filtering

Add date filtering methods with Carbon/string support and convenience helpers.

• Implement createdAfter(Carbon|string $date): self that stores formatted date in filters['since']
• Implement updatedBefore(Carbon|string $date): self (note: GitHub API uses 'since' for created after, may need custom handling for updated before through result filtering)
• Implement older(int $days): self as convenience method that calculates date and calls appropriate filter method
• Create protected formatDate(Carbon|string $date): string helper that converts to ISO 8601 format using Carbon::toIso8601String() or Carbon::parse($date)->toIso8601String()

Task 6: Implement Sorting and Pagination

Add methods for controlling result ordering and pagination parameters.

• Implement orderBy(string $field, string $direction = 'desc'): self that sets sort field and direction
• Implement orderByCreated(string $direction = 'desc'): self as convenience wrapper
• Implement orderByUpdated(string $direction = 'desc'): self as convenience wrapper
• Implement perPage(int $perPage): self that sets pagination limit (1-100 range)
• Implement page(int $page): self that sets page number
• Store values in dedicated properties for buildParams() to use

Task 7: Implement Query Execution Methods

Add methods that execute the query and return results in various formats.

• Implement get(): Collection that calls buildParams(), creates ListIssuesRequest with owner/repo/filters, sends via connector, maps response to Issue DTOs using Issue::fromArray(), returns Illuminate Collection
• Implement count(): int that calls get() and returns collection count (or consider API efficiency if GitHub provides count endpoint)
• Implement exists(): bool that returns count() > 0
• Implement first(): ?Issue that returns get()->first()
• Handle API response array structure and ensure proper DTO hydration

Task 8: Implement Helper Methods

Create protected methods for building API requests from accumulated state.

• Implement buildEndpoint(): string that constructs /repos/{$this->owner}/{$this->repo}/issues path
• Implement buildParams(): array that transforms internal state to GitHub API query parameters (state, labels as comma-separated, assignee, creator, mentioned, since, sort, direction, per_page, page)
• Handle special cases like 'none' for unassigned, label array joining, date formatting
• Ensure param keys match GitHub API expectations (per_page not perPage, etc.)

🤖 Prompt for AI agents

Implement the IssueQuery class with fluent chainable API for filtering GitHub
issues. Create the core query builder that accumulates filter state and executes
queries against the GitHub API.

Create src/Services/IssueQuery.php with:
- Constructor accepting readonly Connector $connector
- Protected properties: $owner, $repo, $filters (array), $sort, $direction,
$perPage, $page
- forRepo(string $fullName) method that parses 'owner/repo' format using explode

Add filter methods that modify state and return $this:
- whereOpen(), whereClosed(), whereState(string $state) for issue state
- whereLabel(string $label), whereLabels(array $labels) for label filtering
- assignedTo(string $username), whereUnassigned() for assignee filtering
- createdBy(string $username), mentioning(string $username) for user filtering
- createdAfter(Carbon|string $date), updatedBefore(Carbon|string $date),
older(int $days) for date filtering
- orderBy(string $field, string $direction), orderByCreated(), orderByUpdated()
for sorting
- perPage(int $perPage), page(int $page) for pagination

Add execution methods:
- get(): Collection - executes query via ListIssuesRequest, maps to Issue DTOs,
returns Collection
- count(): int - returns count of results
- exists(): bool - checks if any results exist
- first(): ?Issue - returns first result or null

Add protected helpers:
- formatDate(Carbon|string $date): string - converts to ISO 8601 format
- buildEndpoint(): string - constructs API path from owner/repo
- buildParams(): array - transforms internal state to GitHub API parameters
(state, labels as comma-separated, assignee, creator, mentioned, since, sort,
direction, per_page, page)

Phase 2: Service and Facade Integration

Integrate the query builder with the existing service layer and facade to enable the fluent API from static calls.

Task 1: Add Query Factory Method to IssuesService

Update the service to provide a factory method that instantiates IssueQuery with proper dependencies.

• Add forRepo(string $fullName): IssueQuery method to src/Services/IssuesService.php
• Method should instantiate new IssueQuery with $this->connector and immediately call ->forRepo($fullName) to set context
• Return the configured IssueQuery instance ready for method chaining
• Ensure proper type hints and PHPDoc annotations

Task 2: Update Facade PHPDoc

Add method signature documentation to the facade for IDE autocomplete support.

• Update src/Facades/GithubIssues.php PHPDoc block with @method static IssueQuery forRepo(string $fullName)
• Add additional @method annotations for any other query builder convenience methods if needed
• Ensure return type is documented as IssueQuery for proper IDE chaining support

Task 3: Update Service Provider (if needed)

Review and update service provider registration if IssueQuery needs explicit container binding.

• Review src/GithubIssuesServiceProvider.php to determine if IssueQuery needs registration
• Since IssueQuery is instantiated by IssuesService directly, explicit binding likely not needed
• Verify Connector dependency is properly resolved when service creates query instances
• Update only if testing reveals dependency resolution issues

🤖 Prompt for AI agents

Integrate the IssueQuery builder with the existing service layer and facade.
Enable static facade access to the fluent query API.

Update src/Services/IssuesService.php:
- Add forRepo(string $fullName): IssueQuery method
- Instantiate IssueQuery with $this->connector
- Call ->forRepo($fullName) on the instance to set repository context
- Return the configured IssueQuery ready for chaining

Update src/Facades/GithubIssues.php:
- Add @method static IssueQuery forRepo(string $fullName) to PHPDoc block
- Ensure proper IDE support for method chaining

Review src/GithubIssuesServiceProvider.php:
- Verify Connector dependency resolution works correctly
- Add explicit binding only if needed based on testing

Phase 3: Comprehensive Testing

Create unit and integration tests following the existing Pest PHP patterns to verify query builder functionality.

Task 1: Create Unit Tests for Query Builder

Test individual filter methods and internal state management in isolation.

• Create tests/Unit/Services/IssueQueryTest.php using Pest's describe/it syntax
• Test each filter method (whereOpen, whereLabel, assignedTo, etc.) verifies correct internal state using reflection
• Test method chaining returns self for all fluent methods
• Test buildParams() generates correct GitHub API parameter structure for various filter combinations
• Test buildEndpoint() constructs correct API path from owner/repo
• Test date formatting helper converts Carbon and string dates to ISO 8601
• Use reflection to access protected methods and properties for verification

Task 2: Create Integration Tests for Query Execution

Test end-to-end query execution with mocked GitHub API responses.

• Create tests/Integration/IssueQueryTest.php with Saloon MockClient for API mocking
• Test get() method returns Collection of Issue DTOs when API returns issue data
• Test filtering by various combinations (state + labels, assignee + dates, etc.) produces correct API calls
• Test pagination parameters are correctly passed to request
• Test sorting parameters affect API request correctly
• Test count(), exists(), and first() methods work with mocked responses
• Use MockResponse::make() to simulate GitHub API responses with realistic issue data

Task 3: Create Facade Integration Tests

Verify the facade correctly proxies to the service and query builder.

• Add test cases to existing facade tests or create tests/Integration/IssueQueryFacadeTest.php
• Test GithubIssues::forRepo('owner/repo') returns IssueQuery instance
• Test full fluent chain through facade executes correctly
• Test static facade calls work with method chaining
• Verify service layer properly injects dependencies into query instances

Task 4: Add Architecture Tests (if applicable)

Ensure query builder follows architectural patterns established in the package.

• Update tests/Architecture/ArchitectureTest.php if needed to include IssueQuery class checks
• Verify IssueQuery follows naming conventions
• Ensure proper namespace structure
• Check that constructor uses readonly properties where appropriate
• Verify no debugging functions are present in production code

🤖 Prompt for AI agents

Create comprehensive Pest PHP tests for the IssueQuery builder covering unit,
integration, and architectural concerns.

Create tests/Unit/Services/IssueQueryTest.php:
- Test all filter methods set correct internal state (use reflection to access
protected properties)
- Test method chaining returns $this for fluent API
- Test buildParams() generates correct GitHub API parameters for various filter
combinations
- Test buildEndpoint() constructs correct API path
- Test formatDate() converts Carbon and string dates to ISO 8601

Create tests/Integration/IssueQueryTest.php:
- Mock GitHub API responses using Saloon MockClient
- Test get() returns Collection of Issue DTOs
- Test various filter combinations produce correct API calls
- Test pagination and sorting parameters
- Test count(), exists(), first() methods with mocked data

Create tests/Integration/IssueQueryFacadeTest.php or update existing facade
tests:
- Test GithubIssues::forRepo('owner/repo') returns IssueQuery
- Test full fluent chain through facade
- Verify dependency injection works correctly

Update tests/Architecture/ArchitectureTest.php:
- Add checks for IssueQuery class structure
- Verify naming conventions and namespace
- Check readonly properties usage
- Ensure no debugging code

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the IssueQuery class with fluent chainable API for filtering GitHub
issues. Create the core query builder that accumulates filter state and executes
queries against the GitHub API.

Create src/Services/IssueQuery.php with:
- Constructor accepting readonly Connector $connector
- Protected properties: $owner, $repo, $filters (array), $sort, $direction,
$perPage, $page
- forRepo(string $fullName) method that parses 'owner/repo' format using explode

Add filter methods that modify state and return $this:
- whereOpen(), whereClosed(), whereState(string $state) for issue state
- whereLabel(string $label), whereLabels(array $labels) for label filtering
- assignedTo(string $username), whereUnassigned() for assignee filtering
- createdBy(string $username), mentioning(string $username) for user filtering
- createdAfter(Carbon|string $date), updatedBefore(Carbon|string $date),
older(int $days) for date filtering
- orderBy(string $field, string $direction), orderByCreated(), orderByUpdated()
for sorting
- perPage(int $perPage), page(int $page) for pagination

Add execution methods:
- get(): Collection - executes query via ListIssuesRequest, maps to Issue DTOs,
returns Collection
- count(): int - returns count of results
- exists(): bool - checks if any results exist
- first(): ?Issue - returns first result or null

Add protected helpers:
- formatDate(Carbon|string $date): string - converts to ISO 8601 format
- buildEndpoint(): string - constructs API path from owner/repo
- buildParams(): array - transforms internal state to GitHub API parameters
(state, labels as comma-separated, assignee, creator, mentioned, since, sort,
direction, per_page, page)
===============================================================================

Task: 2

Integrate the IssueQuery builder with the existing service layer and facade.
Enable static facade access to the fluent query API.

Update src/Services/IssuesService.php:
- Add forRepo(string $fullName): IssueQuery method
- Instantiate IssueQuery with $this->connector
- Call ->forRepo($fullName) on the instance to set repository context
- Return the configured IssueQuery ready for chaining

Update src/Facades/GithubIssues.php:
- Add @method static IssueQuery forRepo(string $fullName) to PHPDoc block
- Ensure proper IDE support for method chaining

Review src/GithubIssuesServiceProvider.php:
- Verify Connector dependency resolution works correctly
- Add explicit binding only if needed based on testing
===============================================================================

Task: 3

Create comprehensive Pest PHP tests for the IssueQuery builder covering unit,
integration, and architectural concerns.

Create tests/Unit/Services/IssueQueryTest.php:
- Test all filter methods set correct internal state (use reflection to access
protected properties)
- Test method chaining returns $this for fluent API
- Test buildParams() generates correct GitHub API parameters for various filter
combinations
- Test buildEndpoint() constructs correct API path
- Test formatDate() converts Carbon and string dates to ISO 8601

Create tests/Integration/IssueQueryTest.php:
- Mock GitHub API responses using Saloon MockClient
- Test get() returns Collection of Issue DTOs
- Test various filter combinations produce correct API calls
- Test pagination and sorting parameters
- Test count(), exists(), first() methods with mocked data

Create tests/Integration/IssueQueryFacadeTest.php or update existing facade
tests:
- Test GithubIssues::forRepo('owner/repo') returns IssueQuery
- Test full fluent chain through facade
- Verify dependency injection works correctly

Update tests/Architecture/ArchitectureTest.php:
- Add checks for IssueQuery class structure
- Verify naming conventions and namespace
- Check readonly properties usage
- Ensure no debugging code

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

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