Fix mutable scalar type refinement in return generic contracts

Author: rcalicdan

src/Internal/StreamWrapper.php

@@ -219,14 +219,14 @@ public function stream_open(string $path, string $mode, int $options, ?string &$
 
         self::unregister();
 
-        $exists = (bool) self::silent(fn() => file_exists($path));
-        $resolvedPath = $exists ? self::silent(fn() => realpath($path)) : false;
+        $exists = (bool) self::silent(fn () => file_exists($path));
+        $resolvedPath = $exists ? self::silent(fn () => realpath($path)) : false;
 
         if (! $exists || $resolvedPath === false || ! self::isApplicationFile($path, $resolvedPath)) {
             $target = ($resolvedPath !== false) ? $resolvedPath : $path;
             /** @var resource|false $handle */
             $handle = self::silent(
-                fn() => ($this->context !== null)
+                fn () => ($this->context !== null)
                     ? fopen($target, $mode, false, $this->context)
                     : fopen($target, $mode)
             );
@@ -270,7 +270,7 @@ private function openDirectHandle(string $targetFile, string $mode, int $options
         self::unregister();
         /** @var resource|false $handle */
         $handle = self::silent(
-            fn() => ($this->context !== null)
+            fn () => ($this->context !== null)
                 ? fopen($targetFile, $mode, $useIncludePath, $this->context)
                 : fopen($targetFile, $mode, $useIncludePath)
         );
@@ -425,7 +425,7 @@ public function url_stat(string $path, int $flags): array|false
 
         self::unregister();
         /** @var array<int|string, int>|false $result */
-        $result = self::silent(fn() => $isLink ? @lstat($path) : @stat($path));
+        $result = self::silent(fn () => $isLink ? @lstat($path) : @stat($path));
         self::register();
 
         if ($result !== false) {
@@ -460,11 +460,11 @@ public function stream_metadata(string $path, int $option, mixed $value): bool
             $valueArray = \is_array($value) ? $value : [];
             $time = $valueArray[0] ?? time();
             $atime = $valueArray[1] ?? $time;
-            $result = (bool) self::silent(fn() => @touch($path, (int) $time, (int) $atime));
+            $result = (bool) self::silent(fn () => @touch($path, (int) $time, (int) $atime));
         } elseif ($option === STREAM_META_ACCESS) {
             /** @var int $mode */
             $mode = \is_int($value) ? $value : 0777;
-            $result = (bool) self::silent(fn() => @chmod($path, $mode));
+            $result = (bool) self::silent(fn () => @chmod($path, $mode));
         }
         self::register();
 
@@ -476,7 +476,7 @@ public function dir_opendir(string $path, int $options): bool
         self::unregister();
         /** @var resource|false $dh */
         $dh = self::silent(
-            fn() => ($this->context !== null)
+            fn () => ($this->context !== null)
                 ? @opendir($path, $this->context)
                 : @opendir($path)
         );
@@ -603,7 +603,7 @@ public function rename(string $pathFrom, string $pathTo): bool
      */
     private static function silent(callable $callback): mixed
     {
-        set_error_handler(static fn() => true);
+        set_error_handler(static fn () => true);
 
         try {
             return $callback();

src/Resolver/TemplateManager.php

@@ -627,6 +627,16 @@ private static function bindSingleTemplateArgument(
             $valid = self::checkVariance($existingTypeNode, $expectedTypeNode, $variance);
 
             if (! $valid) {
+                // In return context, allow methods to specialize broad bounds to narrower types
+                // (e.g. @return static<int, TValue> specializing TKey of array-key to int)
+                if ($isReturnContext && self::checkVariance($expectedTypeNode, $existingTypeNode, GenericTypeNode::VARIANCE_COVARIANT)) {
+                    $bindings = self::$instanceTemplateBindings[$instance] ?? [];
+                    $bindings[$templateName] = $expectedTypeNode;
+                    self::$instanceTemplateBindings[$instance] = $bindings;
+
+                    return null;
+                }
+
                 return ErrorFactory::createError(
                     $context . " expects {$className}<{$variance} {$expectedTypeNode}>, but {$className}<{$existingTypeNode}> was given"
                 );

tests/Internal/StreamWrapperTest.php

@@ -115,9 +115,10 @@ function testIgnoredFileFunc(int $id): int
             file_put_contents($targetFile, '<?php // target file');
 
             $symlinkCreated = false;
+
             try {
                 $symlinkCreated = @symlink($targetFile, $linkFile);
-            } catch (\Throwable $e) {
+            } catch (Throwable $e) {
                 // Windows without developer mode may disallow symlinks
             }
 
@@ -569,4 +570,4 @@ function dedicatedStreamAction(int $id): int
             }
         });
     });
-});
+});

tests/TypeChecking/Generics/FluentGenericSpecializationTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+use TypePHP\Exception\TypeError;
+use TypePHP\Tests\Fixtures\Domain\Car;
+use TypePHP\Tests\Fixtures\Domain\Dog;
+use TypePHP\TypePHP;
+
+/**
+ * Mutable collection modifying $this in place
+ *
+ * @template TKey of array-key = array-key
+ * @template TValue = mixed
+ */
+class MutableSpecializedCollection
+{
+    public array $items;
+
+    public function __construct(mixed $items = [])
+    {
+        $this->items = \is_array($items) ? $items : [$items];
+    }
+
+    /**
+     * Modifies $this in place and returns $this as static<int, TValue>
+     *
+     * @return static<int, TValue>
+     */
+    public function values(): static
+    {
+        $this->items = array_values($this->items);
+
+        return $this; // Returns $this which had TKey = array-key!
+    }
+
+    /**
+     * Modifies $this in place and returns $this as static<string, TValue>
+     *
+     * @return static<string, TValue>
+     */
+    public function stringKeys(): static
+    {
+        $this->items = ['key_1' => reset($this->items)];
+
+        return $this;
+    }
+
+    /**
+     * Method returning invalid specialization violating the existing TValue = Dog binding
+     *
+     * @return static<int, Car>
+     */
+    public function badValueSpecialization(): static
+    {
+        return $this;
+    }
+}
+
+describe('Fluent Mutable Generic Return Type Specialization (static<NarrowerKey, TValue>)', function () {
+    test('allows mutable methods like values() to specialize broad TKey of array-key down to int on returned $this instance', function () {
+        /** @var MutableSpecializedCollection<array-key, string> $collection */
+        $collection = new MutableSpecializedCollection(['first' => 'Alice', 'second' => 'Bob']);
+
+        $valuesResult = $collection->values();
+
+        expect($valuesResult)->toBe($collection)
+            ->and(TypePHP::getGenericType($valuesResult, 'TKey'))->toBe('int')
+            ->and($valuesResult->items)->toBe(['Alice', 'Bob'])
+        ;
+    });
+
+    test('allows mutable methods to specialize broad TKey down to string on returned $this instance', function () {
+        /** @var MutableSpecializedCollection<array-key, string> $collection */
+        $collection = new MutableSpecializedCollection([0 => 'Alice']);
+
+        $stringKeysResult = $collection->stringKeys();
+
+        expect($stringKeysResult)->toBe($collection)
+            ->and(TypePHP::getGenericType($stringKeysResult, 'TKey'))->toBe('string')
+        ;
+    });
+
+    test('strictly throws TypeError when return specialization violates underlying value type', function () {
+        /** @var MutableSpecializedCollection<array-key, Dog> $collection */
+        $collection = new MutableSpecializedCollection();
+
+        expect(fn () => $collection->badValueSpecialization())
+            ->toThrow(TypeError::class)
+        ;
+    });
+});