Enhance TemplateManager to allow specialization of 'mixed' type in return context and add tests for unspecialized generic default objects

Author: rcalicdan

src/Resolver/TemplateManager.php

@@ -622,13 +622,19 @@ private static function bindSingleTemplateArgument(
         $templateName = $templateTag->name;
         $existingBindings = self::$instanceTemplateBindings[$instance] ?? [];
 
-        if (isset($existingBindings[$templateName])) {
+      if (isset($existingBindings[$templateName])) {
             $existingTypeNode = $existingBindings[$templateName];
             $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 ($existingTypeNode instanceof IdentifierTypeNode && strtolower($existingTypeNode->name) === 'mixed') {
+                    $bindings = self::$instanceTemplateBindings[$instance] ?? [];
+                    $bindings[$templateName] = $expectedTypeNode;
+                    self::$instanceTemplateBindings[$instance] = $bindings;
+
+                    return null;
+                }
+
                 if ($isReturnContext && self::checkVariance($expectedTypeNode, $existingTypeNode, GenericTypeNode::VARIANCE_COVARIANT)) {
                     $bindings = self::$instanceTemplateBindings[$instance] ?? [];
                     $bindings[$templateName] = $expectedTypeNode;

tests/TypeChecking/Generics/UnspecializedGenericDefaultTest.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
+use TypePHP\Exception\TypeError;
+use TypePHP\Resolver\TemplateManager;
+use TypePHP\TypePHP;
+
+interface SpecificAppMiddleware
+{
+}
+
+class ConcreteAppMiddleware implements SpecificAppMiddleware
+{
+}
+
+class IncompatibleOtherMiddleware
+{
+}
+
+/**
+ * Generic container with class template
+ *
+ * @template TMiddleware of object
+ */
+class GenericMiddlewareContainer
+{
+    /**
+     * @var array<int, TMiddleware>
+     */
+    public array $middlewares = [];
+}
+
+/**
+ * Function accepting specialized generic container
+ *
+ * @param GenericMiddlewareContainer<SpecificAppMiddleware> $container
+ */
+function consumeMiddlewareContainer(GenericMiddlewareContainer $container): bool
+{
+    return true;
+}
+
+describe('Unspecialized Generic Default Objects & First-Use Parameter Binding', function () {
+    test('reproduces tempest unspecialized mixed binding mismatch on un-annotated instance', function () {
+        $rawContainer = new GenericMiddlewareContainer();
+
+        TemplateManager::bindTemplate('none', $rawContainer, 'TMiddleware', new IdentifierTypeNode('mixed'));
+
+        expect(consumeMiddlewareContainer($rawContainer))->toBeTrue()
+            ->and(TypePHP::getGenericType($rawContainer))->toBe(SpecificAppMiddleware::class)
+        ;
+    });
+
+    test('strictly rejects explicitly annotated instance holding an incompatible generic type', function () {
+        $badContainer = new GenericMiddlewareContainer();
+        TemplateManager::bindTemplate('none', $badContainer, 'TMiddleware', new IdentifierTypeNode(IncompatibleOtherMiddleware::class));
+
+        expect(fn () => consumeMiddlewareContainer($badContainer))
+            ->toThrow(TypeError::class, 'expects GenericMiddlewareContainer<invariant SpecificAppMiddleware>, but GenericMiddlewareContainer<IncompatibleOtherMiddleware> was given')
+        ;
+    });
+});