Refactor TemplateManager docblock and improve variance handling; add GenericReturnCovarianceTest for Liskov subtyping validation

Author: rcalicdan

src/Resolver/TemplateManager.php

@@ -27,7 +27,9 @@
 use WeakMap;
 
 /**
- * @internal Manages generic template bindings for object instances (via WeakMap) and static/method call stack frames.
+ * Manages generic template bindings for object instances (via WeakMap) and static/method call stack frames.
+ *
+ * @internal
  */
 final class TemplateManager
 {
@@ -51,7 +53,7 @@ final class TemplateManager
     public static ?object $pendingCloneSource = null;
 
     /**
-     * Resets all static generic template bindings and call stack frames. Useful for test isolation.
+     * Resets all static generic template bindings and call stack frames.
      */
     public static function reset(): void
     {
@@ -358,9 +360,11 @@ private static function bindSingleTemplateArgument(
         $usageVariance = $typeNode->variances[$index] ?? GenericTypeNode::VARIANCE_INVARIANT;
         $declaredVariance = $classVariances[$templateTag->name] ?? GenericTypeNode::VARIANCE_INVARIANT;
 
+        $isReturnContext = str_contains($context, 'Return value');
+
         $variance = ($usageVariance !== GenericTypeNode::VARIANCE_INVARIANT)
             ? $usageVariance
-            : $declaredVariance;
+            : ($isReturnContext ? GenericTypeNode::VARIANCE_COVARIANT : $declaredVariance);
 
         $templateName = $templateTag->name;
         $existingBindings = self::$instanceTemplateBindings[$instance] ?? [];
@@ -795,9 +799,7 @@ private static function resolveTypeNodeAst(TypeNode $n, \ReflectionClass $ref):
      */
     private static function getPhpDocParserComponents(): array
     {
-        /** @var PhpDocParser|null $phpDocParser */
         static $phpDocParser = null;
-        /** @var Lexer|null $lexer */
         static $lexer = null;
 
         if ($phpDocParser === null || $lexer === null) {
@@ -818,9 +820,7 @@ private static function getPhpDocParserComponents(): array
      */
     private static function getTypeParserComponents(): array
     {
-        /** @var TypeParser|null $typeParser */
         static $typeParser = null;
-        /** @var Lexer|null $lexer */
         static $lexer = null;
 
         if ($typeParser === null || $lexer === null) {

tests/TypeChecking/Boundaries/LateStaticBindingReturnTest.php

@@ -91,7 +91,7 @@
 
         test('throws TypeError when generic static factory returns instance violating generic template T', function () {
             expect(fn () => UserGenericFactory::ofBadItem(new Dog()))
-                ->toThrow(TypeError::class, 'UserGenericFactory<invariant TypePHP\Tests\Fixtures\Domain\Dog>, but TypePHP\Tests\Fixtures\Services\UserGenericFactory<stdClass> was returned')
+                ->toThrow(TypeError::class, 'UserGenericFactory<covariant TypePHP\Tests\Fixtures\Domain\Dog>, but TypePHP\Tests\Fixtures\Services\UserGenericFactory<stdClass> was returned')
             ;
         });
 

tests/TypeChecking/Generics/GenericReturnCovarianceTest.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+use TypePHP\Tests\Fixtures\Domain\Animal;
+use TypePHP\Tests\Fixtures\Domain\Car;
+use TypePHP\Tests\Fixtures\Domain\Dog;
+use TypePHP\Tests\Fixtures\Generics\GenericCollection;
+
+/**
+ * Method declaring return type of GenericCollection<Animal>
+ *
+ * @return GenericCollection<Animal>
+ */
+function testReturnGenericCollection(GenericCollection $collection): GenericCollection
+{
+    return $collection;
+}
+
+describe('Generic Return Covariance (Liskov Subtyping on Return Types)', function () {
+    test('accepts GenericCollection holding Dog subclass when return contract specifies Animal', function () {
+        /** @var GenericCollection<Dog> $dogCollection */
+        $dogCollection = new GenericCollection();
+        $dogCollection->add(new Dog());
+
+        $result = testReturnGenericCollection($dogCollection);
+
+        expect($result)->toBe($dogCollection);
+    });
+
+    test('throws TypeError when GenericCollection returned holds an unrelated type', function () {
+        /** @var GenericCollection<Car> $carCollection */
+        $carCollection = new GenericCollection();
+        $carCollection->add(new Car());
+
+        expect(fn () => testReturnGenericCollection($carCollection))
+            ->toThrow(TypeError::class)
+        ;
+    });
+});