feat: Contracts and Interfaces Architecture

[jordanpartridge]

Closes #26

Summary

This PR implements a comprehensive contracts/interfaces architecture following the interface-first pattern. It establishes explicit contracts for all major components, facilitating testing and enabling dependency injection capabilities.

Changes

Query Interfaces

• IssueQueryInterface: Provides filtering (state, labels, people, time), sorting, pagination, and execution methods (get(), first(), count())
• MilestoneQueryInterface: Manages milestone queries with state, sorting, and pagination options

Manager Interfaces

• IssueManagerInterface: Handles issue data retrieval, updates, label/assignment management, state control, and relations to comments/reactions
• CommentManagerInterface: Manages comment operations including creation, updates, and deletion
• LabelManagerInterface: Controls label addition, removal, and clearing on issues
• ReactionManagerInterface: Manages emoji reactions with type filtering and convenient shortcuts (thumbsUp(), heart(), etc.)
• MilestoneManagerInterface: Oversees milestone CRUD operations and querying
• RepositoryLabelManagerInterface: Repository-level label management (list, get, create, update, delete)

Additional Interfaces

• IssuesFacadeInterface: High-level facade providing unified access to all manager interfaces
• IssueBuilderInterface: Fluent interface for building issues before creation
• LabelBuilderInterface: Fluent interface for building repository labels
• MilestoneBuilderInterface: Fluent interface for building milestones

Benefits

• Clear Contracts: Explicit interfaces document expected behavior
• Testing: Streamlined testing via interface mocking
• Dependency Injection: Flexible DI with container bindings
• Focused Design: Single responsibility per interface
• Substitutability: Easy to swap implementations
• Documentation: Interfaces serve as living documentation
• IDE Support: Enhanced autocomplete and type checking

Testing

• 100% test coverage maintained across all new contracts
• Comprehensive architecture tests validate:
  • All contracts are proper interfaces
  • Required methods are present on each contract
  • Return types are correctly specified
  • Query methods are chainable
  • Manager methods return appropriate data objects
  • Builder methods are chainable
• All existing tests pass
• PHPStan analysis passes with no errors

Implementation Details

All interfaces follow consistent patterns:

• Query interfaces support fluent API with chainable filter methods
• Manager interfaces provide high-level operations with clean method signatures
• Builder interfaces enable step-by-step construction of complex objects
• All methods are properly type-hinted with return types
• Docblocks provide additional context and generic type information

Next Steps

Future PRs can:

• Implement concrete classes for query builders
• Create builder implementations
• Add service provider bindings for DI
• Update existing classes to use new contracts in type hints
• Create facade implementations using the IssuesFacadeInterface

Test Results

Tests:    386 passed (853 assertions)
Coverage: 100.0%
PHPStan:  No errors

[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 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 8606f72 and 36c590e.

📒 Files selected for processing (13)

• src/Contracts/CommentManagerInterface.php (1 hunks)
• src/Contracts/IssueBuilderInterface.php (1 hunks)
• src/Contracts/IssueManagerInterface.php (1 hunks)
• src/Contracts/IssueQueryInterface.php (1 hunks)
• src/Contracts/IssuesFacadeInterface.php (1 hunks)
• src/Contracts/LabelBuilderInterface.php (1 hunks)
• src/Contracts/LabelManagerInterface.php (1 hunks)
• src/Contracts/MilestoneBuilderInterface.php (1 hunks)
• src/Contracts/MilestoneManagerInterface.php (1 hunks)
• src/Contracts/MilestoneQueryInterface.php (1 hunks)
• src/Contracts/ReactionManagerInterface.php (1 hunks)
• src/Contracts/RepositoryLabelManagerInterface.php (1 hunks)
• tests/Architecture/ContractsTest.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.}