fix: narrow enum advisory to fire only when zero cases carry #[EnumValue]

Partial annotation is the mechanism that will hide internal cases from
the public schema once the default flips to opt-in; leaving some cases
unannotated is deliberate and must not produce a warning. Under the
previous logic the advisory fired for every partial annotation, which
would punish exactly the pattern the migration encourages.

New rule: fire the E_USER_DEPRECATED advisory only when a #[Type]-mapped
enum declares zero #[EnumValue] attributes across all its cases — the
signal that the developer has not yet engaged with the opt-in model.
Annotating even a single case acknowledges the migration and silences
the notice; from that point any combination of annotated and unannotated
cases is correct and intentional.

Implementation: EnumTypeMapper::mapByClassName() now tracks a single
`sawAnyEnumValueAttribute` flag while iterating cases and emits the
notice only when the flag stays false. Message rewritten to explain the
"at least one case" requirement and point the reader at the intended
migration path — including the fact that a bare #[EnumValue] on a
single case is a valid acknowledgement.

Tests:
- Replaces the previous "any case missing" assertion with
  testEnumWithZeroEnumValueAttributesTriggersDeprecation using a new
  DescriptionLegacyEnum/Era fixture that declares no #[EnumValue] at
  all.
- Adds testEnumWithPartialEnumValueAttributesIsSilent to lock in the
  partial-annotation contract against regressions.
- Pre-existing Color/Size/Position fixtures gain a bare #[EnumValue] on
  their first case so their integration tests stop triggering the
  advisory — demonstrates the minimal upgrade path recommended in the
  docs.

Full suite 539/539 green across cs-check, phpstan, and phpunit, with
exactly 1 intentional deprecation coming from the dedicated advisory
test. The docs in descriptions.md are updated to reflect the corrected
semantics — "partial annotation is intentional and silent".

Author: oojacoboo

src/Mappers/Root/EnumTypeMapper.php

@@ -30,7 +30,6 @@
 use function array_values;
 use function assert;
 use function enum_exists;
-use function implode;
 use function ltrim;
 use function sprintf;
 use function trigger_error;
@@ -148,15 +147,14 @@ private function mapByClassName(string $enumClass): EnumType|null
         $enumCaseDescriptions = [];
         /** @var array<string, string> $enumCaseDeprecationReasons */
         $enumCaseDeprecationReasons = [];
-        /** @var list<string> $casesMissingEnumValueAttribute */
-        $casesMissingEnumValueAttribute = [];
+        $sawAnyEnumValueAttribute = false;
 
         foreach ($reflectionEnum->getCases() as $reflectionEnumCase) {
             $docBlock = $this->docBlockFactory->create($reflectionEnumCase);
             $enumValueAttribute = $this->annotationReader->getEnumValueAnnotation($reflectionEnumCase);
 
-            if ($enumValueAttribute === null) {
-                $casesMissingEnumValueAttribute[] = $reflectionEnumCase->getName();
+            if ($enumValueAttribute !== null) {
+                $sawAnyEnumValueAttribute = true;
             }
 
             $enumCaseDescriptions[$reflectionEnumCase->getName()] = $this->descriptionResolver->resolve(
@@ -183,40 +181,39 @@ private function mapByClassName(string $enumClass): EnumType|null
             }
         }
 
-        $this->warnAboutCasesMissingEnumValueAttribute($enumClass, $casesMissingEnumValueAttribute);
+        if (! $sawAnyEnumValueAttribute) {
+            $this->warnEnumHasNoEnumValueAttributes($enumClass);
+        }
 
         $type = new EnumType($enumClass, $typeName, $enumDescription, $enumCaseDescriptions, $enumCaseDeprecationReasons, $useValues);
 
         return $this->cacheByName[$type->name] = $this->cacheByClass[$enumClass] = $type;
     }
 
     /**
-     * Emits a deprecation notice when a GraphQL-mapped enum exposes one or more cases without a
-     * matching {@see EnumValue} attribute.
+     * Emits a deprecation notice when a GraphQL-mapped enum declares zero {@see EnumValue}
+     * attributes across its cases — the signal that the developer has not yet engaged with
+     * the opt-in model that a future major release will require.
      *
-     * Today every case is automatically exposed in the schema — this call site keeps that
-     * behaviour intact. The notice announces the planned migration: a future major release will
-     * require `#[EnumValue]` on each case that should participate in the schema, mirroring
-     * `#[Field]`'s opt-in model on classes. Until then, adopters can start annotating cases
-     * incrementally; the warning lists the specific cases that would be dropped after the
-     * future default flip so the migration path is mechanical.
+     * Today every case is automatically exposed in the schema regardless of `#[EnumValue]` —
+     * this call site keeps that behaviour intact. The notice announces the planned migration:
+     * a future major release will require at least one `#[EnumValue]`-annotated case per
+     * `#[Type]`-mapped enum, and only annotated cases will participate in the schema
+     * (mirroring `#[Field]`'s opt-in model on classes). Partial annotation is deliberately
+     * allowed and intentionally silent — leaving some cases unannotated is the mechanism that
+     * hides internal cases from the public schema once the default flips, so it must not
+     * itself produce a warning.
      *
-     * @param class-string<UnitEnum>  $enumClass
-     * @param list<string>            $casesMissingAttribute
+     * @param class-string<UnitEnum> $enumClass
      */
-    private function warnAboutCasesMissingEnumValueAttribute(string $enumClass, array $casesMissingAttribute): void
+    private function warnEnumHasNoEnumValueAttributes(string $enumClass): void
     {
-        if ($casesMissingAttribute === []) {
-            return;
-        }
-
         trigger_error(
             sprintf(
-                'Enum "%s" is mapped to a GraphQL enum type but exposes one or more cases without a #[EnumValue] attribute. '
-                . 'Today every case is automatically exposed; a future major release will require #[EnumValue] on each case that should participate in the schema, mirroring #[Field]\'s opt-in model. '
-                . 'Add #[EnumValue] to each case you want to keep exposed. Cases currently exposed without an attribute: %s.',
+                'Enum "%s" is mapped to a GraphQL enum type but declares no #[EnumValue] attributes on any case. '
+                . 'Today every case is automatically exposed; a future major release will require at least one #[EnumValue]-annotated case per #[Type]-mapped enum, and only annotated cases will participate in the schema (mirroring #[Field]\'s opt-in model on classes). '
+                . 'Add #[EnumValue] to the case(s) you want to expose — annotating at least one case acknowledges the opt-in model and silences this notice. Cases left unannotated will be hidden from the schema after the future default flip, which is the intended way to keep internal values out of the public API.',
                 $enumClass,
-                implode(', ', $casesMissingAttribute),
             ),
             E_USER_DEPRECATED,
         );

tests/Fixtures/DescriptionLegacyEnum/Era.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\DescriptionLegacyEnum;
+
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+/**
+ * Fixture for the deprecation advisory: this enum intentionally declares zero #[EnumValue]
+ * attributes so the advisory fires. Under the future opt-in default it would have no cases
+ * exposed at all — which is exactly what the notice is warning about.
+ */
+#[Type]
+enum Era: string
+{
+    case Classical = 'classical';
+    case Modern = 'modern';
+}

tests/Fixtures/DescriptionLegacyEnum/EraController.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\DescriptionLegacyEnum;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+
+class EraController
+{
+    #[Query]
+    public function era(): Era
+    {
+        return Era::Modern;
+    }
+}

tests/Fixtures/Integration/Models/Color.php

@@ -4,6 +4,7 @@
 
 namespace TheCodingMachine\GraphQLite\Fixtures\Integration\Models;
 
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Type;
 
 #[Type(
@@ -12,6 +13,10 @@
 )]
 enum Color: string
 {
+    // A bare #[EnumValue] acknowledges the opt-in migration without altering runtime behaviour.
+    // Remove the attribute or annotate specific cases once the enum actually needs per-case
+    // description/deprecation metadata.
+    #[EnumValue]
     case Green = 'green';
     case Red   = 'red';
 }

tests/Fixtures/Integration/Models/Position.php

@@ -4,11 +4,13 @@
 
 namespace TheCodingMachine\GraphQLite\Fixtures\Integration\Models;
 
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Type;
 
 #[Type]
 enum Position: int
 {
+    #[EnumValue]
     case Off = 0;
     case On  = 1;
 }

tests/Fixtures/Integration/Models/Size.php

@@ -4,11 +4,13 @@
 
 namespace TheCodingMachine\GraphQLite\Fixtures\Integration\Models;
 
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
 use TheCodingMachine\GraphQLite\Annotations\Type;
 
 #[Type]
 enum Size
 {
+    #[EnumValue]
     case S;
     case M;
     case L;

tests/Integration/DescriptionTest.php

@@ -13,6 +13,7 @@
 use TheCodingMachine\GraphQLite\Containers\EmptyContainer;
 use TheCodingMachine\GraphQLite\Fixtures\Description\Book;
 use TheCodingMachine\GraphQLite\Fixtures\DescriptionDuplicate\Book as DuplicateBook;
+use TheCodingMachine\GraphQLite\Fixtures\DescriptionLegacyEnum\Era;
 use TheCodingMachine\GraphQLite\Schema;
 use TheCodingMachine\GraphQLite\SchemaFactory;
 use TheCodingMachine\GraphQLite\Security\VoidAuthenticationService;
@@ -105,18 +106,47 @@ public function testEnumValueAttributeProvidesCaseDescription(): void
         $this->assertSame('Fiction works including novels and short stories.', $fictionValue->description);
     }
 
-    public function testEnumWithCasesMissingEnumValueAttributeTriggersDeprecation(): void
+    public function testEnumWithZeroEnumValueAttributesTriggersDeprecation(): void
     {
-        // The Genre fixture deliberately leaves NonFiction without #[EnumValue] to exercise the
-        // docblock-fallback path and to surface the deprecation announcing the future opt-in
-        // migration. PHPUnit 11's expectUserDeprecationMessageMatches hooks into the library's
-        // own error handler so the assertion works consistently with how deprecations surface
-        // in CI output.
-        $this->expectUserDeprecationMessageMatches('/#\[EnumValue\].*future major.*NonFiction/s');
+        // The Era fixture deliberately declares zero #[EnumValue] attributes — the signal that
+        // the developer has not yet engaged with the opt-in migration. That is the scenario the
+        // advisory targets; partial annotation on other enums (like Genre in the Description
+        // namespace) is deliberately silent because it already acknowledges the new model.
+        $this->expectUserDeprecationMessageMatches('/declares no #\[EnumValue\] attributes.*future major/s');
 
-        $schema = $this->buildSchema(Book::class);
+        $schema = $this->buildSchema(Era::class);
         // Force enum resolution — types are lazy-mapped until referenced.
-        $schema->getType('Genre');
+        $schema->getType('Era');
+    }
+
+    public function testEnumWithPartialEnumValueAttributesIsSilent(): void
+    {
+        // Genre has #[EnumValue] on Fiction and Poetry but not NonFiction. Partial annotation is
+        // deliberately OK: leaving a case unannotated is the mechanism for hiding it from the
+        // public schema after the future default flip, and therefore must not itself produce an
+        // advisory. Asserting no deprecation here locks that contract in.
+        $captured = [];
+        set_error_handler(
+            static function (int $errno, string $errstr) use (&$captured): bool {
+                if ($errno === E_USER_DEPRECATED && str_contains($errstr, 'EnumValue')) {
+                    $captured[] = $errstr;
+
+                    return true;
+                }
+
+                return false;
+            },
+            E_USER_DEPRECATED,
+        );
+
+        try {
+            $schema = $this->buildSchema(Book::class);
+            $schema->getType('Genre');
+        } finally {
+            restore_error_handler();
+        }
+
+        $this->assertSame([], $captured, 'Partial #[EnumValue] annotation must not trigger the advisory notice.');
     }
 
     public function testEnumCaseWithoutAttributeFallsBackToDocblock(): void

website/docs/descriptions.md

@@ -129,24 +129,40 @@ is an enum value.
   Omitting it falls back to the `@deprecated` tag on the case docblock. An explicit empty string
   `''` deliberately clears any inherited `@deprecated` tag.
 
-### Future migration: `#[EnumValue]` will become required per case
+### Future migration: `#[EnumValue]` will become required per `#[Type]`-mapped enum
 
 Today every case of a `#[Type]`-mapped enum is automatically exposed in the GraphQL schema. A
-future major release will flip this to an opt-in model: **only cases carrying an explicit
-`#[EnumValue]` attribute will be exposed**, mirroring the way `#[Field]` opts individual
-methods and properties into an object type.
+future major release will flip this to an opt-in model: **`#[Type]`-mapped enums will need at
+least one `#[EnumValue]`-annotated case, and only annotated cases will participate in the
+schema**, mirroring the way `#[Field]` opts individual methods and properties into an object
+type.
 
 The benefit is selective exposure — today there is no way to map a subset of a PHP enum into
 GraphQL, which forces schema authors to split an enum into two or rename cases. Under the
 opt-in model, an internal enum case can simply omit `#[EnumValue]` to stay out of the public
-schema.
-
-To surface the upcoming change, GraphQLite already emits a PHP `E_USER_DEPRECATED` notice at
-schema build time when an enum annotated with `#[Type]` exposes any case without an
-`#[EnumValue]` attribute. The notice names the specific cases that would be dropped after the
-flip so the migration path is mechanical: add `#[EnumValue]` to every case you want to keep.
-No runtime behaviour changes today — the notice only signals what the future default will
-require.
+schema. **Partial annotation is intentional and deliberately silent**: leaving some cases
+unannotated is the mechanism for hiding them from the public schema once the default flips,
+not a migration oversight.
+
+To surface the upcoming change, GraphQLite emits a PHP `E_USER_DEPRECATED` notice at schema
+build time only when a `#[Type]`-mapped enum declares **zero** `#[EnumValue]` attributes
+across its cases — the signal that the developer has not yet engaged with the opt-in model at
+all. Annotating at least one case acknowledges the new model and silences the notice; after
+that, any combination of annotated and unannotated cases is correct and intentional.
+
+Adopters who aren't ready to decide which cases to expose can silence the advisory with a
+bare `#[EnumValue]` on a single case — no description, no deprecation, just the acknowledgement:
+
+```php
+#[Type]
+enum Size
+{
+    #[EnumValue] // acknowledges the opt-in migration; runtime behaviour unchanged
+    case S;
+    case M;
+    case L;
+}
+```
 
 **Runtime implication after the flip.** Cases without `#[EnumValue]` will not exist in the
 GraphQL schema, so a resolver that returns such a case will trigger webonyx/graphql-php's