feat: add comprehensive pull request management API

[ralflang]

Summary

This PR adds comprehensive pull request management capabilities to the GitHub API Client, transforming it from a basic client into a full-featured PR automation tool.

Features Added

Pull Request Operations

• ✅ Create pull requests (including draft PRs and from forks)
• ✅ List pull requests with filters (base branch, head ref, state)
• ✅ Get detailed pull request information
• ✅ Update pull requests (title, body, base branch, state)
• ✅ Merge pull requests (merge, squash, rebase methods)
• ✅ Close pull requests
• ✅ Reopen closed pull requests

Comment Management

• ✅ List all comments on pull requests
• ✅ Create comments
• ✅ Update comments
• ✅ Delete comments

Review Management

• ✅ List pull request reviews
• ✅ Request reviewers (users and teams)
• ✅ Support for all review states (APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED)

Status Checks & CI/CD

• ✅ Get combined commit status
• ✅ List GitHub Actions check runs
• ✅ Monitor pipeline status and conclusions

Label Management

• ✅ List labels on issues/pull requests
• ✅ Add labels
• ✅ Set (replace) all labels
• ✅ Remove labels

Technical Implementation

Architecture

• Request Factory Pattern: Each API endpoint has a dedicated request factory
• Value Objects: Immutable domain objects with static factory methods
• DTOs: Clean data transfer objects for complex parameters
• Typed Collections: All collections implement Iterator and Countable
• PHP 8.2+ Features: Named parameters, readonly properties, strict types
• PSR Compliant: PSR-7, PSR-17, PSR-18

Code Quality

• 71 unit tests with 249 assertions - all passing ✅
• 52 files changed: 5,217 insertions, 7 deletions
• PER-1 coding standards throughout
• Conventional Commits for all commits

Documentation

Added Documentation Files

• README.md: Comprehensive usage guide with examples for all features
• doc/API.md: Complete API reference (574 lines)
• doc/MIGRATION.md: Upgrade guide with backwards compatibility notes (305 lines)
• bin/demo-client.php: Enhanced with 10 working examples

Breaking Changes

None - This is a backwards-compatible addition. Existing code continues to work unchanged.

Optional Enhancement: Add StreamFactoryInterface parameter to constructor to enable write operations:

$client = new GithubApiClient($httpClient, $requestFactory, $config, $streamFactory);

Example Usage

Create a Pull Request

use Horde\GithubApiClient\CreatePullRequestParams;

$params = new CreatePullRequestParams(
    title: 'Add new feature',
    head: 'feature-branch',
    base: 'main',
    body: 'This PR adds...'
);
$pr = $client->createPullRequest($repo, $params);

Merge a Pull Request

use Horde\GithubApiClient\MergePullRequestParams;

$params = new MergePullRequestParams(
    commitTitle: 'feat: add feature',
    mergeMethod: 'squash'
);
$result = $client->mergePullRequest($repo, 123, $params);

Manage Comments and Reviews

// Add a comment
$comment = $client->createPullRequestComment($repo, 123, 'LGTM!');

// Request reviewers
$client->requestReviewers($repo, 123, ['reviewer1', 'reviewer2']);

// Check CI status
$status = $client->getCombinedStatus($repo, 'main');
echo "Status: {$status->state}\n";

Test Plan

• All 71 unit tests passing
• Demo client tested with real GitHub API
• Documentation reviewed and examples verified
• Backwards compatibility verified
• Code follows PER-1 and Conventional Commits standards

Commits

This PR includes 10 well-structured commits:

1. Enhanced pull request API with user and label support
2. Pull request update capability
3. Pull request comment management
4. Pull request review management
5. Commit status and check runs support
6. Label management support
7. Pull request merge and close support
8. Comprehensive documentation and examples
9. Create and reopen pull request functionality
10. Factory method and constructor documentation improvements

Checklist

• Code follows project coding standards (PER-1)
• Unit tests added and passing (71 tests, 249 assertions)
• Documentation updated (README, API reference, migration guide)
• Backwards compatible (existing code unaffected)
• Conventional Commits used for all commits
• Demo client includes working examples
• No breaking changes introduced

Related Issues

Closes #[issue number if applicable]