feat: Core Contracts - Define all package interfaces

[jordanpartridge]

Closes #27

Summary

Implements comprehensive interface contracts for the entire package following interface-first design pattern, ensuring clean architecture and testability.

Changes

Core Contract Interfaces (10 new interfaces)

1. PullRequestQueryInterface - Fluent query builder for pull requests

   • Chainable filter methods (whereOpen, whereClosed, whereMerged, whereState, etc.)
   • Sorting (orderByCreated, orderByUpdated)
   • Pagination (perPage, page)
   • Execution (get, first, count, exists)

2. PullRequestManagerInterface - CRUD operations for pull requests

   • find() and get() for retrieval
   • query() returns PullRequestQueryInterface
   • create() returns PullRequestBuilderInterface

3. PullRequestBuilderInterface - Builder pattern for PR creation

   • Fluent methods: title(), body(), head(), base(), draft(), maintainerCanModify()
   • Returns PullRequest DTO on create()

4. ReviewBuilderInterface - Builder pattern for reviews

   • Fluent methods: approve(), requestChanges(), comment()
   • Inline comments: addInlineComment(), addSuggestion()
   • Returns Review DTO on submit()

5. ReviewQueryInterface - Query operations for reviews

   • Filter methods: whereApproved(), whereChangesRequested(), wherePending()
   • Filter by user: byUser()
   • Get latest review

6. CheckRunQueryInterface - Query operations for CI checks

   • Status filters: wherePassing(), whereFailing(), wherePending(), whereNeutral(), whereSkipped()
   • Find by name: byName()
   • Summary statistics: summary() returns CheckSummary DTO

7. MergeManagerInterface - Merge operations

   • Merge strategies: merge(), squash(), rebase()
   • Validation: canMerge()
   • Cleanup: deleteBranch()

8. FileQueryInterface - Query operations for changed files

   • Status filters: whereAdded(), whereModified(), whereRemoved(), whereRenamed()
   • Path filters: wherePath(), whereExtension()
   • Statistics: stats() returns FileStats DTO

9. PullRequestActionsInterface - State-changing operations

   • State: close(), reopen(), markDraft(), markReady()
   • Labels: addLabel(), addLabels(), removeLabel(), setLabels()
   • Reviews: requestReview(), requestReviews(), requestTeamReview()
   • Assignees: assign(), unassign()
   • Comments: comment()

10. CommentManagerInterface - Comment management

    • get(), create(), update(), delete()

Supporting DTOs (2 new DTOs)

1. CheckSummary - Aggregated check run statistics

   • Counts: total, passing, failing, pending, neutral, skipped
   • Helper methods: allPassing(), hasFailures(), hasPending()

2. FileStats - Aggregated file change statistics

   • File counts by status: total, added, modified, removed, renamed
   • Line counts: totalAdditions, totalDeletions, totalChanges

Interface Design Principles

1. Fluent Chainability

All builder/action interfaces return self for method chaining:

->title('foo')
->body('bar')
->draft()
->create()

2. Query Segregation

Separate interfaces by responsibility:

• *QueryInterface - Read operations returning Collections
• *BuilderInterface - Creation operations
• *ManagerInterface - CRUD operations
• *ActionsInterface - State-changing operations

3. Type Safety

All interfaces use strict typing:

public function find(int $number): PullRequest;
public function get(): Collection;
public function exists(): bool;

4. Collection Returns

Query operations return Laravel Collections for filtering/mapping:

public function get(): Collection; // Collection<PullRequest>
public function whereApproved(): Collection; // Collection<Review>

Dependencies

• Added illuminate/support: ^11.0 for Collection support
• This aligns with the package's Laravel service provider integration

Quality Gates

Tests

• 205 tests passing, 536 assertions
• 100% code coverage
• Interface compliance tests
• Type safety tests
• DTO serialization tests

Static Analysis

• PHPStan: No errors
• Laravel Pint: Code formatted

Benefits

1. Testability - Easy to mock interfaces for testing
2. Extensibility - Swap implementations without changing consumer code
3. Documentation - Interfaces serve as contracts and documentation
4. Type Safety - IDE autocomplete and static analysis support
5. Dependency Injection - Clean DI with interface bindings
6. Architecture - Clear separation of concerns

Next Steps

These contracts lay the foundation for:

• Service implementations (Core: PullRequestQuery builder with fluent filtering API #20, Data: PullRequest DTO with chainable actions #21, Reviews: Fluent review workflow API #22, Checks: CI/CD status and check runs integration #23, Merge: Expressive merge strategies API #24, Files: Diff and changed files API #25, Creation: Fluent PR creation builder API #26)
• Service provider bindings
• Facade improvements
• Clean architecture patterns

Related Issues

• Core: PullRequestQuery builder with fluent filtering API #20 (PullRequestQuery)
• Data: PullRequest DTO with chainable actions #21 (PullRequest DTO)
• Reviews: Fluent review workflow API #22 (Review workflow)
• Checks: CI/CD status and check runs integration #23 (Check runs)
• Merge: Expressive merge strategies API #24 (Merge strategies)
• Files: Diff and changed files API #25 (Files API)
• Creation: Fluent PR creation builder API #26 (PR creation)

[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 13 minutes and 22 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 52a40fa and 77334cc.

📒 Files selected for processing (16)

• composer.json (1 hunks)
• src/Contracts/CheckRunQueryInterface.php (1 hunks)
• src/Contracts/CommentManagerInterface.php (1 hunks)
• src/Contracts/FileQueryInterface.php (1 hunks)
• src/Contracts/MergeManagerInterface.php (1 hunks)
• src/Contracts/PullRequestActionsInterface.php (1 hunks)
• src/Contracts/PullRequestBuilderInterface.php (1 hunks)
• src/Contracts/PullRequestManagerInterface.php (1 hunks)
• src/Contracts/PullRequestQueryInterface.php (1 hunks)
• src/Contracts/ReviewBuilderInterface.php (1 hunks)
• src/Contracts/ReviewQueryInterface.php (1 hunks)
• src/DataTransferObjects/CheckSummary.php (1 hunks)
• src/DataTransferObjects/FileStats.php (1 hunks)
• tests/Unit/ContractsTest.php (1 hunks)
• tests/Unit/DataTransferObjects/CheckSummaryTest.php (1 hunks)
• tests/Unit/DataTransferObjects/FileStatsTest.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/contracts

---

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.}

[jordanpartridge]

Rebased onto post-#41 master and salvaged to scope.

Kept (7 interfaces + 2 DTOs):

• `CheckRunQueryInterface` (Checks: CI/CD status and check runs integration #23)
• `CommentManagerInterface` (Comments: PR comment and inline comment management #29)
• `FileQueryInterface` (Files: Diff and changed files API #25)
• `MergeManagerInterface` (Merge: Expressive merge strategies API #24)
• `PullRequestBuilderInterface` (Creation: Fluent PR creation builder API #26)
• `PullRequestManagerInterface`
• `ReviewQueryInterface`
• `CheckSummary` and `FileStats` DTOs

Dropped:

• `PullRequestQueryInterface` — already shipped via feat: Implement Core PullRequestQuery Builder #38 with a different method set; master's version kept.
• `ReviewBuilderInterface` — already shipped via feat: Fluent review workflow API #36; master's version kept.
• `PullRequestActionsInterface` — superseded by the role-trait pattern (`Assignable`, `Closeable`, `Mergeable`, `Labelable`, `Commentable`, `Reviewable`, `Auditable`) already on master.

composer.json conflict: resolved to master's (`php: ^8.3`, `conduit-ui/connector: ^1.0.1`, `illuminate/support: ^12.43|^13.0`). The original PR's attempt to promote illuminate/support to `require` was dropped; the package currently keeps it as a dev dep.

Quality gates:

• 332/332 tests pass (310 prior + 22 new from the contracts/DTO tests)
• PHPStan: 16 pre-existing errors, 0 new
• composer audit: clean

`ContractsTest.php` was trimmed to drop assertions tied to the dropped interfaces.