feat: Add rate limit and token permissions checking support

[ralflang]

Summary

This PR adds two essential features to the GitHub API client library:

• Rate Limit Checking - Monitor API quota usage
• Token Permissions/Scopes Checking - Verify what the access token can do

Features Added

1. Rate Limit Support

New Classes:

• RateLimit - Value object for rate limit data
• RateLimitRequestFactory - Creates requests for /rate_limit endpoint

API Method:

$rateLimit = $client->getRateLimit();
echo "Remaining: {$rateLimit->remaining}/{$rateLimit->limit}\n";
echo "Resets in: {$rateLimit->getSecondsUntilReset()} seconds\n";

Features:

• Track limit, remaining, used, and reset timestamp
• Helper methods: isExhausted(), getUsagePercentage(), getSecondsUntilReset(), getResetDateTime()

2. Token Permissions/Scopes Support

New Classes:

• TokenScopes - Value object for OAuth scope list
• AuthenticatedUserRequestFactory - Creates requests for /user endpoint

API Method:

$scopes = $client->getTokenScopes();
if ($scopes->canWriteRepositories()) {
    echo "Token has write access\n";
}
echo "Granted scopes: " . $scopes->toString() . "\n";

Features:

• Parse X-OAuth-Scopes header from API response
• Helper methods: has(), hasAny(), hasAll(), canReadRepositories(), canWriteRepositories(), canReadOrganizations()

3. Demo Script

Added bin/demo-token-info.php to demonstrate both features with formatted output.

Testing

✅ Comprehensive PHPUnit test coverage

• RateLimit: 10 tests, 22 assertions
• TokenScopes: 19 tests, 27 assertions
• Total: 29 new tests, 49 new assertions
• All tests passing with 0 failures, 0 errors

✅ PHPUnit 12 Compatible

• Upgraded all deprecated annotations to attribute syntax
• Zero deprecation warnings
• Added missing PSR HTTP interface dependencies

Code Quality

• ✅ All PHP syntax validated
• ✅ Follows existing library patterns and conventions
• ✅ Full type hints and doc blocks
• ✅ PSR-compliant code style
• ✅ Proper error handling with exceptions

Commits

1. feat: Add rate limit and token permissions checking support
2. fix: Add missing PSR HTTP interfaces and upgrade PHPUnit annotations
3. fix: Convert remaining @Covers annotations to PHPUnit 12 attributes

Files Changed

• 8 new files added (746 lines)
• 2 test files upgraded (PHPUnit 12 compatibility)
• 1 composer.json updated (PSR dependencies)

Usage Example

See bin/demo-token-info.php for a complete example.