feat!: make #[EnumValue] control per-case enum schema exposure

Once any case of a #[Type]-mapped enum carries #[EnumValue], the enum enters
opt-in mode: only annotated cases are exposed and unannotated cases are hidden
from the schema. A fully-unannotated mapped enum stays in legacy mode (every
case exposed) and emits the existing deprecation advisory.

Adds Types\ExposedEnumCase and reshapes EnumType's internal constructor to take
the resolved exposed cases the mapper decided, replacing the parallel per-name
metadata arrays.

BREAKING CHANGE: partially-annotated #[Type] enums now hide their unannotated
cases from the schema. Annotate every case you want exposed.

Author: oojacoboo

src/Mappers/Root/EnumTypeMapper.php

@@ -21,6 +21,7 @@
 use TheCodingMachine\GraphQLite\Discovery\ClassFinder;
 use TheCodingMachine\GraphQLite\Reflection\DocBlock\DocBlockFactory;
 use TheCodingMachine\GraphQLite\Types\EnumType;
+use TheCodingMachine\GraphQLite\Types\ExposedEnumCase;
 use TheCodingMachine\GraphQLite\Utils\DescriptionResolver;
 use UnitEnum;
 
@@ -138,64 +139,73 @@ private function mapByClassName(string $enumClass): EnumType|null
                 : null,
         );
 
-        /** @var array<string, string|null> $enumCaseDescriptions */
-        $enumCaseDescriptions = [];
-        /** @var array<string, string> $enumCaseDeprecationReasons */
-        $enumCaseDeprecationReasons = [];
-        $hasEnumValueAttribute = false;
+        // Single pass: build an ExposedEnumCase for every case, resolving its metadata, and bucket
+        // it by whether it carries #[EnumValue]. The moment any case is annotated the enum is in
+        // opt-in mode and only the annotated bucket is exposed; otherwise every case is exposed.
+        /** @var list<ExposedEnumCase> $annotatedCases */
+        $annotatedCases = [];
+        /** @var list<ExposedEnumCase> $unannotatedCases */
+        $unannotatedCases = [];
 
         foreach ($reflectionEnum->getCases() as $reflectionEnumCase) {
+            $attribute = $this->annotationReader->getEnumValueAnnotation($reflectionEnumCase);
             $docBlock = $this->docBlockFactory->create($reflectionEnumCase);
-            $enumValueAttribute = $this->annotationReader->getEnumValueAnnotation($reflectionEnumCase);
 
-            if ($enumValueAttribute !== null) {
-                $hasEnumValueAttribute = true;
-            }
-
-            $enumCaseDescriptions[$reflectionEnumCase->getName()] = $this->descriptionResolver->resolve(
-                $enumValueAttribute?->description,
+            $description = $this->descriptionResolver->resolve(
+                $attribute?->description,
                 $docBlock->getSummary() ?: null,
             );
 
-            $explicitDeprecation = $enumValueAttribute?->deprecationReason;
+            $deprecationReason = null;
+            $explicitDeprecation = $attribute?->deprecationReason;
             if ($explicitDeprecation !== null) {
                 // Explicit `deprecationReason` always wins; an empty string deliberately clears
                 // any @deprecated tag on the case docblock the same way an empty description
                 // blocks the docblock fallback.
                 if ($explicitDeprecation !== '') {
-                    $enumCaseDeprecationReasons[$reflectionEnumCase->getName()] = $explicitDeprecation;
+                    $deprecationReason = $explicitDeprecation;
+                }
+            } else {
+                $deprecation = $docBlock->getTagsByName('deprecated')[0] ?? null;
+                if ($deprecation) {
+                    $deprecationReason = (string) $deprecation;
                 }
-                continue;
             }
 
-            $deprecation = $docBlock->getTagsByName('deprecated')[0] ?? null;
+            $exposedCase = new ExposedEnumCase($reflectionEnumCase->getValue(), $description, $deprecationReason);
 
-            // phpcs:ignore
-            if ($deprecation) {
-                $enumCaseDeprecationReasons[$reflectionEnumCase->getName()] = (string) $deprecation;
+            if ($attribute !== null) {
+                $annotatedCases[] = $exposedCase;
+            } else {
+                $unannotatedCases[] = $exposedCase;
             }
         }
 
-        if (! $hasEnumValueAttribute) {
+        $exposedCases = $annotatedCases !== [] ? $annotatedCases : $unannotatedCases;
+
+        if ($annotatedCases === []) {
             $this->warnEnumHasNoEnumValueAttribute($enumClass);
         }
 
-        $type = new EnumType($enumClass, $typeName, $enumDescription, $enumCaseDescriptions, $enumCaseDeprecationReasons, $useValues);
+        $type = new EnumType($exposedCases, $typeName, $enumDescription, $useValues);
 
         return $this->cacheByName[$type->name] = $this->cacheByClass[$enumClass] = $type;
     }
 
     /**
      * 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.
+     * attributes across its cases — the signal that the developer has not yet engaged with the
+     * per-case opt-in model.
+     *
+     * `#[EnumValue]` is now the per-case exposure toggle. As soon as an enum carries the attribute
+     * on at least one case it enters opt-in mode: only the annotated cases are exposed and every
+     * unannotated case is hidden from the schema (mirroring `#[Field]`'s opt-in model on classes).
+     * A fully-unannotated enum stays in legacy mode — every case is still exposed — and this notice
+     * fires to flag that the enum has not opted in, so a future major release that makes the
+     * attribute mandatory would otherwise hide all of its cases.
      *
-     * 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 `#[EnumValue]` on each case that should participate
-     * in the schema, and unannotated cases will be hidden (mirroring `#[Field]`'s opt-in
-     * model on classes). Partial annotation is deliberately allowed and intentionally silent
-     * so that leaving some cases unannotated can be used to hide them once the default flips.
+     * Partial annotation is deliberately silent: leaving a case unannotated is now the supported
+     * mechanism for keeping it out of the public schema, so it must not itself produce an advisory.
      *
      * @param class-string<UnitEnum> $enumClass
      */
@@ -204,8 +214,8 @@ private function warnEnumHasNoEnumValueAttribute(string $enumClass): void
         trigger_error(
             sprintf(
                 '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 #[EnumValue] on each case that should participate in the schema, and unannotated cases will be hidden (mirroring #[Field]\'s opt-in model on classes). '
-                . 'Add #[EnumValue] to every case you want to keep exposed. Omit it only from cases you want hidden from the public schema after the future default flip.',
+                . 'Every case is exposed in legacy mode; adding #[EnumValue] to any case switches the enum to opt-in mode, where only annotated cases are exposed and unannotated ones are hidden (mirroring #[Field]\'s opt-in model on classes). '
+                . 'Add #[EnumValue] to every case you want exposed. Omit it only from cases you want hidden from the public schema.',
                 $enumClass,
             ),
             E_USER_DEPRECATED,

src/Types/EnumType.php

@@ -14,30 +14,30 @@
 
 /**
  * An extension of the EnumType to support native enums.
+ *
+ * @internal The constructor shape (an explicit list of exposed cases with resolved metadata) is a
+ *     framework-internal contract with EnumTypeMapper, not a public API.
  */
 class EnumType extends BaseEnumType
 {
     /**
-     * @param class-string<UnitEnum> $enumName
-     * @param array<string, string|null> $caseDescriptions
-     * @param array<string, string> $caseDeprecationReasons
+     * @param list<ExposedEnumCase> $cases The enum cases that participate in the schema, each
+     *     paired with its resolved metadata.
      */
     public function __construct(
-        string $enumName,
+        array $cases,
         string $typeName,
         string|null $description,
-        array $caseDescriptions,
-        array $caseDeprecationReasons,
         private readonly bool $useValues = false,
     ) {
         $typeValues = [];
-        foreach ($enumName::cases() as $case) {
-            $key = $this->serialize($case);
+        foreach ($cases as $exposed) {
+            $key = $this->serialize($exposed->case);
             $typeValues[$key] = [
                 'name' => $key,
-                'value' => $case,
-                'description' => $caseDescriptions[$case->name] ?? null,
-                'deprecationReason' => $caseDeprecationReasons[$case->name] ?? null,
+                'value' => $exposed->case,
+                'description' => $exposed->description,
+                'deprecationReason' => $exposed->deprecationReason,
             ];
         }
 

src/Types/ExposedEnumCase.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Types;
+
+use UnitEnum;
+
+/**
+ * A single enum case exposed in the GraphQL schema, paired with its resolved metadata.
+ *
+ * @internal Built by EnumTypeMapper and consumed by EnumType; not part of the public API.
+ */
+final class ExposedEnumCase
+{
+    public function __construct(
+        public readonly UnitEnum $case,
+        public readonly string|null $description,
+        public readonly string|null $deprecationReason,
+    ) {
+    }
+}

tests/Fixtures/EnumExposure/EnumExposureController.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\EnumExposure;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+
+class EnumExposureController
+{
+    #[Query]
+    public function publishStatus(): PublishStatus
+    {
+        return PublishStatus::Published;
+    }
+}

tests/Fixtures/EnumExposure/PublishStatus.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\EnumExposure;
+
+use TheCodingMachine\GraphQLite\Annotations\EnumValue;
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+/**
+ * Partially-annotated enum: it carries #[EnumValue] on some cases, which puts it in opt-in mode.
+ * Only the annotated cases must reach the schema; the unannotated internal cases stay hidden.
+ */
+#[Type]
+enum PublishStatus: string
+{
+    #[EnumValue(description: 'Visible to everyone.')]
+    case Published = 'published';
+
+    #[EnumValue]
+    case Scheduled = 'scheduled';
+
+    // Internal-only working state — deliberately left unannotated so it never enters the schema.
+    case Draft = 'draft';
+
+    // Internal-only terminal state — likewise hidden.
+    case Archived = 'archived';
+}

tests/Fixtures/EnumExposureLegacy/Weekday.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\EnumExposureLegacy;
+
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+/**
+ * Fully-unannotated enum: it declares zero #[EnumValue] attributes, so it stays in legacy mode
+ * where every case is exposed and case descriptions still fall back to the docblock summary.
+ */
+#[Type]
+enum Weekday: string
+{
+    /**
+     * The first working day of the week.
+     */
+    case Monday = 'monday';
+    case Tuesday = 'tuesday';
+    case Wednesday = 'wednesday';
+}

tests/Fixtures/EnumExposureLegacy/WeekdayController.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Fixtures\EnumExposureLegacy;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+
+class WeekdayController
+{
+    #[Query]
+    public function weekday(): Weekday
+    {
+        return Weekday::Monday;
+    }
+}

tests/Integration/DescriptionTest.php

@@ -108,11 +108,11 @@ public function testEnumValueAttributeProvidesCaseDescription(): void
 
     public function testEnumWithZeroEnumValueAttributesTriggersDeprecation(): void
     {
-        // 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
+        // The Era fixture deliberately declares zero #[EnumValue] attributes, so it stays in
+        // legacy mode (every case exposed) and the advisory fires. 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');
+        // namespace) is deliberately silent because it has already opted in.
+        $this->expectUserDeprecationMessageMatches('/declares no #\[EnumValue\] attributes.*legacy mode/s');
 
         $schema = $this->buildSchema(Era::class);
         // Force enum resolution — types are lazy-mapped until referenced.
@@ -149,18 +149,19 @@ static function (int $errno, string $errstr) use (&$captured): bool {
         $this->assertSame([], $captured, 'Partial #[EnumValue] annotation must not trigger the advisory notice.');
     }
 
-    public function testEnumCaseWithoutAttributeFallsBackToDocblock(): void
+    public function testUnannotatedCaseIsHiddenInOptInMode(): void
     {
         $schema = $this->buildSchema(Book::class);
 
         $genreType = $schema->getType('Genre');
-        $nonFictionValue = $genreType->getValue('NonFiction');
-        // The NonFiction case has no #[EnumValue] attribute, so its description comes from the docblock.
-        $this->assertNotNull($nonFictionValue->description);
-        $this->assertStringContainsString(
-            'This docblock description should appear on the NonFiction enum value',
-            $nonFictionValue->description,
-        );
+
+        // Genre carries #[EnumValue] on Fiction and Poetry, which puts it in opt-in mode. The
+        // NonFiction case has no #[EnumValue] attribute, so it is now hidden from the schema
+        // entirely rather than falling back to its docblock description.
+        $this->assertNull($genreType->getValue('NonFiction'));
+
+        $exposedNames = array_map(static fn ($value) => $value->name, $genreType->getValues());
+        $this->assertSame(['Fiction', 'Poetry'], $exposedNames);
     }
 
     public function testEnumValueAttributeProvidesDeprecationReason(): void
@@ -172,20 +173,20 @@ public function testEnumValueAttributeProvidesDeprecationReason(): void
         $this->assertSame('Use Fiction::Verse instead.', $poetryValue->deprecationReason);
     }
 
-    public function testDisablingDocblockFallbackSuppressesEnumCaseDescription(): void
+    public function testDisablingDocblockFallbackKeepsExplicitDescriptionOnExposedCase(): void
     {
         $schema = $this->buildSchema(Book::class, docblockDescriptions: false);
 
         $genreType = $schema->getType('Genre');
 
-        // Fiction has an explicit #[EnumValue] description — still present.
+        // Fiction has an explicit #[EnumValue] description — still present with the toggle off.
         $this->assertSame(
             'Fiction works including novels and short stories.',
             $genreType->getValue('Fiction')->description,
         );
 
-        // NonFiction relied on its docblock summary — with the toggle off, it must disappear.
-        $this->assertNull($genreType->getValue('NonFiction')->description);
+        // NonFiction is unannotated, so opt-in mode hides it regardless of the docblock toggle.
+        $this->assertNull($genreType->getValue('NonFiction'));
     }
 
     public function testExtendTypeSuppliesDescriptionWhenBaseTypeHasNone(): void