feat: PullRequest DTO with chainable actions

[jordanpartridge]

Summary

Implements issue #21 by adding chainable action methods directly to the PullRequest DTO. The DTO now accepts optional connector, owner, and repo parameters, enabling developers to perform PR operations without needing the wrapper class.

Changes

PullRequest DTO Enhancement

• Modified PullRequest::fromArray() to accept optional connector, owner, and repo parameters
• Added private readonly properties for connector configuration
• Implemented ensureConnectorAvailable() guard method with PHPStan assertions

State Management Methods

• merge(string $method, ?string $message, ?string $title) - Merge PR with specified strategy
• squashMerge(?string $message) - Convenience method for squash merge
• rebaseMerge() - Convenience method for rebase merge
• close() - Close the pull request
• reopen() - Reopen a closed pull request
• markDraft() - Convert PR to draft
• markReady() - Mark draft PR as ready for review

Review Methods

• approve(?string $body) - Approve the PR
• requestChanges(string $body) - Request changes on the PR
• submitReview(string $event, ?string $body, array $comments) - Generic review submission
• comment(string $body) - Add a comment to the PR

Label Management

• addLabel(string $label) - Add a single label
• addLabels(array $labels) - Add multiple labels
• removeLabel(string $label) - Remove a label
• setLabels(array $labels) - Replace all labels

Reviewer Management

• requestReviewer(string $username) - Request a single reviewer
• requestReviewers(array $usernames) - Request multiple reviewers
• requestTeamReview(string $teamSlug) - Request a team review

Assignee Management

• assignUser(string $username) - Assign a single user
• assign(array $usernames) - Assign multiple users
• unassign(array $usernames) - Unassign users

Usage Example

use ConduitUI\Pr\DataTransferObjects\PullRequest;
use ConduitUi\GitHubConnector\Connector;

$connector = new Connector('token');
$pr = PullRequest::fromArray($apiResponse, $connector, 'owner', 'repo');

// Chain multiple actions
$pr->addLabel('ready-for-review')
   ->requestReviewer('senior-dev')
   ->comment('Ready for review!');

// Approve and merge
if ($pr->checksPass()) {
    $pr->approve('LGTM!')
       ->squashMerge('Implemented feature X');
}

// Read-only usage (without connector)
$pr = PullRequest::fromArray($apiResponse);
echo $pr->title; // Works fine
$pr->merge(); // Throws RuntimeException

Test Coverage

• 26 comprehensive test cases covering all action methods
• Tests for method chaining
• Tests for error handling (missing connector)
• Tests for read-only operations
• 100% code coverage achieved

Quality Gates

• All tests passing (204 tests, 445 assertions)
• PHPStan level 9 strict mode: No errors
• Laravel Pint: Code formatted correctly
• 100% test coverage

Backward Compatibility

The changes are fully backward compatible:

• fromArray() has optional parameters with null defaults
• Existing code calling PullRequest::fromArray($data) continues to work
• Read-only operations work without connector
• Only action methods require connector configuration

Closes #21

[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 12 minutes and 40 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 2d550c1.

📒 Files selected for processing (2)

• src/DataTransferObjects/PullRequest.php (4 hunks)
• tests/Unit/DataTransferObjects/PullRequestActionsTest.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/pr-dto

---

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