Enhance type handling in ContractParser and add tests for Constructor-Property type conflicts in Doctrine simulation classes

Author: rcalicdan

src/Contract/ContractParser.php

@@ -668,7 +668,8 @@ private static function resolveTargetParamName(
     }
 
     /**
-     * Falls back to property @var docblocks for constructor promoted parameters if un-annotated.
+     * Falls back to property @var docblocks for constructor parameters if un-annotated,
+     * ensuring scalar constructor parameters are never overridden by conflicting object property types.
      *
      * @param \ReflectionMethod $ref
      * @param array<string, TypeNode> $types
@@ -687,6 +688,22 @@ private static function applyConstructorPromotionFallback(\ReflectionMethod $ref
                 if ($propDoc !== false) {
                     $propType = DocblockExtractor::extractTypeFromPropertyDoc($propDoc, $paramName);
                     if ($propType !== null) {
+                        if ($p->hasType()) {
+                            $nativeType = $p->getType();
+                            if ($nativeType instanceof \ReflectionNamedType) {
+                                $nativeName = strtolower($nativeType->getName());
+                                $propTypeStr = strtolower((string) $propType);
+
+                                if (
+                                    $nativeType->isBuiltin()
+                                    && ! \in_array($nativeName, ['array', 'iterable', 'mixed'], true)
+                                    && ! \in_array($propTypeStr, [$nativeName, 'mixed'], true)
+                                ) {
+                                    continue;
+                                }
+                            }
+                        }
+
                         $isVariadic = $p->isVariadic();
                         if ($isVariadic) {
                             $propType = new ArrayTypeNode($propType);

src/Internal/ErrorFactory.php

@@ -83,6 +83,7 @@ private static function isCallSiteError(string $lowerMessage): bool
      * Filters out internal TypePHP frames from the raw stack trace.
      *
      * @param list<array<string, mixed>> $trace
+     *
      * @return list<array<string, mixed>>
      */
     private static function filterTrace(

tests/Fixtures/Doctrine/AbstractNamedObject.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Doctrine;
+
+/**
+ * Simulates Doctrine DBAL's AbstractNamedObject
+ *
+ * @template N of Name
+ */
+abstract class AbstractNamedObject
+{
+    /**
+     * The property is an object of type Name (template N)
+     *
+     * @var N
+     */
+    protected Name $name;
+
+    /**
+     * The constructor parameter is a native scalar string
+     */
+    public function __construct(string $name)
+    {
+    }
+}

tests/Fixtures/Doctrine/Column.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Doctrine;
+
+/**
+ * Simulates Doctrine DBAL's Column
+ *
+ * @extends AbstractNamedObject<UnqualifiedName>
+ */
+class Column extends AbstractNamedObject
+{
+    public function __construct(string $name)
+    {
+        parent::__construct($name);
+    }
+}

tests/Fixtures/Doctrine/Name.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Doctrine;
+
+abstract class Name
+{
+    public function __construct(public string $identifier)
+    {
+    }
+}

tests/Fixtures/Doctrine/UnqualifiedName.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypePHP\Tests\Fixtures\Doctrine;
+
+class UnqualifiedName extends Name
+{
+}

tests/TypeChecking/InheritanceAndAttributes/ConstructorPropertyTypeMismatchTest.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use TypePHP\Tests\Fixtures\Doctrine\Column;
+
+describe('Constructor Parameter vs Property Type Conflict (Doctrine DBAL AbstractNamedObject)', function () {
+    test('does not override native scalar constructor parameter with conflicting object property @var docblock', function () {
+        $column = new Column('"id"');
+
+        expect($column)->toBeInstanceOf(Column::class);
+    });
+});