[Capability] Stop a union type losing a branch (#434)

* [Capability] Stop a union type losing a branch

mapPhpTypeToJsonSchemaType() tested for array syntax before splitting the
union, so string[]|int mapped to array alone; applyArrayConstraints() then
overwrote the type with array whenever the union contained one, dropping the
scalar branch a second time. A tool declaring such a parameter rejected a
valid integer argument.

The split now happens first and only at the top level, so array<int|string>
and array{a: int|string} stay one type rather than two that do not exist, and
the array branch keeps its items alongside the others - which is what 2020-12
means by items: a constraint that applies only when the instance is an array.

* Apply suggestion from @chr-hertel

* Isolate the array branch before inferring its element type

* Don't apply items to arrays whose union branches disagree on element type

src/Capability/Discovery/SchemaGenerator.php

@@ -443,7 +443,23 @@ final class SchemaGenerator implements SchemaGeneratorInterface
         }
         // Handle regular arrays
         elseif (\in_array('array', $this->mapPhpTypeToJsonSchemaType($typeString))) {
-            $itemsType = $this->inferArrayItemsType($typeString);
+            // `inferArrayItemsType()` expects a single array type, not a union — for
+            // `string[]|int` it would see the whole string, match nothing, and lose
+            // the element-type constraint. Isolate the branch(es) that are arrays.
+            $arrayBranches = array_values(array_filter(
+                self::splitUnion($typeString),
+                fn (string $branch): bool => \in_array('array', $this->mapPhpTypeToJsonSchemaType($branch), true),
+            ));
+            if ([] === $arrayBranches) {
+                $arrayBranches = [$typeString];
+            }
+
+            // Several array branches (`string[]|int[]`) can disagree on their
+            // element type. Applying just one would reject values valid under
+            // the other, so `items` only applies when every array branch agrees.
+            $itemsTypes = array_map($this->inferArrayItemsType(...), $arrayBranches);
+            $itemsType = 1 === \count(array_unique(array_map(json_encode(...), $itemsTypes))) ? $itemsTypes[0] : 'any';
+
             if ('any' !== $itemsType) {
                 if (\is_string($itemsType)) {
                     $paramSchema['items'] = ['type' => $itemsType];
@@ -455,11 +471,25 @@ final class SchemaGenerator implements SchemaGeneratorInterface
                 }
             }
 
-            if ($allowsNull) {
-                $paramSchema['type'] = ['array', 'null'];
+            // Only when the parameter is an array and nothing else. A union
+            // like `string[]|int` keeps both branches: `items` constrains the
+            // instance only when it *is* an array, so the two coexist and
+            // overwriting the type here would drop the scalar branch —
+            // rejecting a value the handler accepts.
+            $otherTypes = array_values(array_diff(
+                (array) $paramSchema['type'],
+                ['array', 'null'],
+            ));
+
+            if ([] === $otherTypes) {
+                $paramSchema['type'] = $allowsNull ? ['array', 'null'] : 'array';
+
+                if (\is_array($paramSchema['type'])) {
+                    sort($paramSchema['type']);
+                }
+            } elseif ($allowsNull && !\in_array('null', (array) $paramSchema['type'], true)) {
+                $paramSchema['type'] = [...(array) $paramSchema['type'], 'null'];
                 sort($paramSchema['type']);
-            } else {
-                $paramSchema['type'] = 'array';
             }
         }
 
@@ -655,6 +685,42 @@ final class SchemaGenerator implements SchemaGeneratorInterface
         return $typeString ?: 'mixed';
     }
 
+    /**
+     * Splits a type string on its top-level `|`, leaving generics and shapes
+     * intact.
+     *
+     * `int|string` splits; `array<int|string>` and `array{a: int|string}` do
+     * not, because the `|` there is a parameter of the outer type rather than
+     * an alternative to it.
+     *
+     * @return list<string>
+     */
+    public static function splitUnion(string $type): array
+    {
+        $branches = [];
+        $depth = 0;
+        $current = '';
+
+        foreach (str_split($type) as $character) {
+            if (\in_array($character, ['<', '{', '('], true)) {
+                ++$depth;
+            } elseif (\in_array($character, ['>', '}', ')'], true)) {
+                $depth = max(0, $depth - 1);
+            } elseif ('|' === $character && 0 === $depth) {
+                $branches[] = trim($current);
+                $current = '';
+
+                continue;
+            }
+
+            $current .= $character;
+        }
+
+        $branches[] = trim($current);
+
+        return array_values(array_filter($branches, static fn (string $branch): bool => '' !== $branch));
+    }
+
     /**
      * Maps a PHP type string (potentially a union) to an array of JSON Schema type names.
      *
@@ -664,12 +730,28 @@ final class SchemaGenerator implements SchemaGeneratorInterface
     {
         $normalizedType = strtolower(trim($phpTypeString));
 
-        // PRIORITY 1: Check for array{} syntax which should be treated as object
+        // PRIORITY 1: Handle unions before anything else. A `|` at the top
+        // level joins alternatives; one inside `<>` or `{}` belongs to a
+        // generic (`array<int|string>`) and is not a union of the whole type.
+        // Checked first because a branch may itself be an array shape — and
+        // `string[]|int` read as "an array" silently loses the `int`.
+        $branches = self::splitUnion($normalizedType);
+
+        if (\count($branches) > 1) {
+            $jsonTypes = [];
+            foreach ($branches as $branch) {
+                $jsonTypes = array_merge($jsonTypes, $this->mapPhpTypeToJsonSchemaType($branch));
+            }
+
+            return array_values(array_unique($jsonTypes));
+        }
+
+        // PRIORITY 2: Check for array{} syntax which should be treated as object
         if (preg_match('/^array\s*{/i', $normalizedType)) {
             return ['object'];
         }
 
-        // PRIORITY 2: Check for array syntax first (T[] or generics)
+        // PRIORITY 3: Check for array syntax (T[] or generics)
         if (
             str_contains($normalizedType, '[]')
             || preg_match('/^(array|list|iterable|collection)</i', $normalizedType)
@@ -677,23 +759,11 @@ final class SchemaGenerator implements SchemaGeneratorInterface
             return ['array'];
         }
 
-        // PRIORITY 3: Treat PHPStan/Psalm integer ranges as their base type
+        // PRIORITY 4: Treat PHPStan/Psalm integer ranges as their base type
         if (preg_match('/^int\s*<\s*[^<>]+\s*>$/i', $normalizedType)) {
             return ['integer'];
         }
 
-        // PRIORITY 4: Handle unions (recursive)
-        if (str_contains($normalizedType, '|')) {
-            $types = explode('|', $normalizedType);
-            $jsonTypes = [];
-            foreach ($types as $type) {
-                $mapped = $this->mapPhpTypeToJsonSchemaType(trim($type));
-                $jsonTypes = array_merge($jsonTypes, $mapped);
-            }
-
-            return array_values(array_unique($jsonTypes));
-        }
-
         // PRIORITY 5: Handle simple built-in types
         return match ($normalizedType) {
             'string', 'scalar' => ['string'],