feat: Allow Custom Directives

[michael-georgiadis]

Description

As discussed in #807, the library can support custom defined directives as well. This PR addresses that concern by adding:

• Discovery — DirectiveClassFinder scans the registered namespaces for classes implementing TypeSystemDirective (cached like ClassFinderTypeMapper). No new configuration: a directive class in a namespace you already addNamespace() is picked up automatically.
• Registration & validation — DirectiveRegistry now discovers user directives alongside the built-ins (@oneOf, @deprecated), validating each at discovery time and enforcing unique names.
• Validation split into focused units: AttributeTargetValidator (the #[Attribute(...)] targets cover the declared GraphQL locations) and InterfaceLocationValidator (family interface ⇄ location agreement).
• Wiring — SchemaFactory injects the class finder into the registry; behavioral directives wrap their resolver at runtime, metadata directives land on each element's astNode->directives.

Directive definition

Defining a directive

#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_PROPERTY)]
final class UppercaseDirective implements BehavioralFieldDirective
{
    public static function definition(): DirectiveDefinition
    {
        return new DirectiveDefinition(name: 'uppercase', locations: [DirectiveLocation::FIELD_DEFINITION]);
    }

    public function applyToField(QueryFieldDescriptor $descriptor, FieldHandlerInterface $next): FieldDefinition|null
    { /* wrap the resolver */ }

Name reservation

• @oneOf / @deprecated (names we bind): reserved for custom use unless the directive declares builtIn: true to intentionally override the bundled binding.
• @skip / @include / @specifiedBy (webonyx directives we don't bind): hard-reserved — sourced from Directive::*_NAME constants — so a custom directive can't collide with them at schema build.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 93.87755% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.28%. Comparing base (53f9d49) to head (0028530).
⚠️ Report is 176 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Directives/DirectiveRegistry.php	84.61%	4 Missing ⚠️
src/Directives/DirectiveValidator.php	83.33%	1 Missing ⚠️
...rectives/Validation/InterfaceLocationValidator.php	93.33%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #815      +/-   ##
============================================
- Coverage     95.72%   94.28%   -1.45%     
- Complexity     1773     2138     +365     
============================================
  Files           154      207      +53     
  Lines          4586     5718    +1132     
============================================
+ Hits           4390     5391    +1001     
- Misses          196      327     +131     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[oojacoboo]

@michael-georgiadis any updates on this one?

[michael-georgiadis]

@oojacoboo, kinda. I can make the CI green but I have to up the lowest support version of webonyx/graphql since directives were added in a later version. Would that be ok with you?

[oojacoboo]

@michael-georgiadis yes, that would be okay. Are there any known BC breaks? Even if so, that's not an issue. I can hold off on the next tagged release and determine that accordingly.

[michael-georgiadis]

@oojacoboo made the CI go green. Feel free to have a look