[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

tests/Unit/Capability/Discovery/SchemaGeneratorUnionTest.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Discovery;
+
+use Mcp\Capability\Discovery\DocBlockParser;
+use Mcp\Capability\Discovery\SchemaGenerator;
+use Mcp\Capability\Discovery\SchemaValidator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+class SchemaGeneratorUnionTest extends TestCase
+{
+    /**
+     * @return iterable<string, array{string, list<string>}>
+     */
+    public static function unions(): iterable
+    {
+        yield 'not a union' => ['string', ['string']];
+        yield 'simple union' => ['int|string', ['int', 'string']];
+        yield 'three branches' => ['int|string|bool', ['int', 'string', 'bool']];
+        yield 'array branch alongside a scalar' => ['string[]|int', ['string[]', 'int']];
+        yield 'generic branch alongside a scalar' => ['array<string>|int', ['array<string>', 'int']];
+
+        // The `|` here parameterises the outer type; splitting it would turn
+        // one type into two that do not exist.
+        yield 'union inside a generic' => ['array<int|string>', ['array<int|string>']];
+        yield 'union inside a shape' => ['array{a: int|string}', ['array{a: int|string}']];
+        yield 'nested generics' => ['array<string, array<int|bool>>', ['array<string, array<int|bool>>']];
+        yield 'shape beside a scalar' => ['array{a: int|string}|null', ['array{a: int|string}', 'null']];
+
+        yield 'whitespace is trimmed' => ['int | string', ['int', 'string']];
+        yield 'empty branches are dropped' => ['int||string', ['int', 'string']];
+    }
+
+    /**
+     * @param list<string> $expected
+     */
+    #[DataProvider('unions')]
+    #[TestDox('a type string splits on its top-level union only')]
+    public function testSplitUnion(string $type, array $expected): void
+    {
+        $this->assertSame($expected, SchemaGenerator::splitUnion($type));
+    }
+
+    /**
+     * @return iterable<string, array{string, list<string>}>
+     */
+    public static function mappedTypes(): iterable
+    {
+        yield 'scalar union' => ['int|string', ['integer', 'string']];
+
+        // The regression: the `[]` check ran before the union split, so this
+        // came back as ['array'] and the `int` branch vanished.
+        yield 'array beside a scalar keeps both' => ['string[]|int', ['array', 'integer']];
+        yield 'scalar before an array keeps both' => ['int|string[]', ['integer', 'array']];
+        yield 'generic beside a scalar keeps both' => ['array<string>|bool', ['array', 'boolean']];
+
+        yield 'a generic union is still one array' => ['array<int|string>', ['array']];
+        yield 'a shape is still one object' => ['array{a: int|string}', ['object']];
+    }
+
+    /**
+     * @param list<string> $expected
+     */
+    #[DataProvider('mappedTypes')]
+    #[TestDox('a union maps to every JSON Schema type its branches need')]
+    public function testMappedTypes(string $type, array $expected): void
+    {
+        $generator = new SchemaGenerator(new DocBlockParser());
+
+        $map = new \ReflectionMethod($generator, 'mapPhpTypeToJsonSchemaType');
+
+        $this->assertSame($expected, $map->invoke($generator, $type));
+    }
+
+    #[TestDox('a generated schema keeps both branches of an array-or-scalar union')]
+    public function testGeneratedUnionSchemaKeepsBothBranches(): void
+    {
+        $schema = (new SchemaGenerator(new DocBlockParser()))
+            ->generate(new \ReflectionMethod(UnionFixture::class, 'handle'));
+
+        // `items` constrains the instance only when it *is* an array, so it
+        // coexists with the scalar branch instead of excluding it.
+        $this->assertSame(['array', 'integer'], $schema['properties']['mixedish']['type']);
+        // The array branch keeps its own element-type constraint rather than
+        // losing it to the union as a whole (`items` would otherwise be `{}`).
+        $this->assertSame(['type' => 'string'], $schema['properties']['mixedish']['items']);
+
+        $this->assertSame(['integer', 'string'], $schema['properties']['scalars']['type']);
+        $this->assertSame('array', $schema['properties']['arrayOnly']['type']);
+        $this->assertSame(['array', 'null'], $schema['properties']['nullableArray']['type']);
+
+        // Two array branches with different element types can't both be
+        // enforced without rejecting a value that is valid under one of
+        // them, so neither constraint is applied (falls back to the "matches
+        // anything" empty schema `ensureArrayItems()` defaults every array to).
+        $this->assertSame('array', $schema['properties']['disagreeingArrays']['type']);
+        $this->assertEquals(new \stdClass(), $schema['properties']['disagreeingArrays']['items']);
+    }
+
+    #[TestDox('a value from either branch validates against the generated schema')]
+    public function testBothBranchesValidate(): void
+    {
+        $schema = (new SchemaGenerator(new DocBlockParser()))
+            ->generate(new \ReflectionMethod(UnionFixture::class, 'handle'));
+
+        $validator = new SchemaValidator();
+        $base = ['scalars' => 1, 'arrayOnly' => ['a'], 'nullableArray' => null, 'disagreeingArrays' => []];
+
+        $this->assertSame([], $validator->validateAgainstJsonSchema([...$base, 'mixedish' => ['a', 'b']], $schema));
+        $this->assertSame([], $validator->validateAgainstJsonSchema([...$base, 'mixedish' => 42], $schema));
+
+        // A float is in neither branch, so it is still refused.
+        $this->assertNotSame([], $validator->validateAgainstJsonSchema([...$base, 'mixedish' => 1.5], $schema));
+
+        // Neither element type is enforced, so both branches' values pass.
+        $this->assertSame([], $validator->validateAgainstJsonSchema([...$base, 'mixedish' => 42, 'disagreeingArrays' => ['a', 'b']], $schema));
+        $this->assertSame([], $validator->validateAgainstJsonSchema([...$base, 'mixedish' => 42, 'disagreeingArrays' => [1, 2]], $schema));
+    }
+}

tests/Unit/Capability/Discovery/UnionFixture.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Discovery;
+
+class UnionFixture
+{
+    /**
+     * @param string[]|int   $mixedish          an array branch beside a scalar one
+     * @param int|string     $scalars           two scalar branches
+     * @param string[]       $arrayOnly         one branch, and it is an array
+     * @param string[]|null  $nullableArray     an array branch that may be null
+     * @param string[]|int[] $disagreeingArrays two array branches with different element types
+     */
+    public function handle(array|int $mixedish, int|string $scalars, array $arrayOnly, ?array $nullableArray, array $disagreeingArrays): string
+    {
+        return '';
+    }
+}