Major bug fixes and edge cases resolve

composer.json

@@ -27,7 +27,7 @@
     "require": {
         "php": "^8.1",
         "phpstan/phpdoc-parser": "^2.0",
-        "nikic/php-parser": "^5.0"
+        "nikic/php-parser": "^5.3"
     },
     "require-dev": {
         "laravel/pint": "^1.10",

src/Contract/ContractParser.php

@@ -619,16 +619,10 @@ private static function parseFunction(\ReflectionFunction $ref): array
 
         foreach (DocblockExtractor::getParamTags($phpDocNode) as $paramName => $paramTag) {
             $type = $paramTag->type;
-            $isVariadic = $paramTag->isVariadic || ($baseParamVariadic[$paramName] ?? false);
-            if (
-                $isVariadic
-                && ! ($type instanceof ArrayTypeNode)
-                && ! ($type instanceof GenericTypeNode && \in_array(strtolower($type->type->name), ['array', 'list', 'iterable', 'traversable', 'non-empty-array', 'non-empty-list'], true))
-            ) {
-                $type = new ArrayTypeNode($type);
-            }
-
             $pObj = $baseParamObjects[$paramName] ?? null;
+
+            $type = self::wrapVariadicParameterType($type, $paramTag->isVariadic, $baseParamVariadic[$paramName] ?? false, $pObj);
+
             if (
                 Config::isRespectNativeNullabilityEnabled()
                 && $pObj !== null
@@ -796,16 +790,10 @@ private static function parseMethodHierarchyDocs(
 
                 if ($targetParamName !== null && ! isset($types[$targetParamName])) {
                     $type = $paramTag->type;
-                    $isVariadic = $paramTag->isVariadic || ($baseParamVariadic[$targetParamName] ?? false);
-                    if (
-                        $isVariadic
-                        && ! ($type instanceof ArrayTypeNode)
-                        && ! ($type instanceof GenericTypeNode && \in_array(strtolower($type->type->name), ['array', 'list', 'iterable', 'traversable', 'non-empty-array', 'non-empty-list'], true))
-                    ) {
-                        $type = new ArrayTypeNode($type);
-                    }
-
                     $pObj = $baseParamObjects[$targetParamName] ?? null;
+
+                    $type = self::wrapVariadicParameterType($type, $paramTag->isVariadic, $baseParamVariadic[$targetParamName] ?? false, $pObj);
+
                     if (
                         Config::isRespectNativeNullabilityEnabled()
                         && $pObj !== null
@@ -897,10 +885,15 @@ private static function applyConstructorPromotionFallback(
             $paramName = $p->getName();
 
             if (! isset($types[$paramName]) && $declaringClass->hasProperty($paramName)) {
+                $propertyRef = $declaringClass->getProperty($paramName);
+
+                // For non-promoted parameters, ensure constructor param and property native types are compatible
+                if (! self::areConstructorParamAndPropertyCompatible($p, $propertyRef)) {
+                    continue;
+                }
+
                 $className = $declaringClass->getName();
                 $stubDoc = StubManager::getPropertyDoc($className, $paramName);
-
-                $propertyRef = $declaringClass->getProperty($paramName);
                 $propDoc = $stubDoc ?? $propertyRef->getDocComment();
 
                 if ($propDoc !== false && $propDoc !== null) {
@@ -926,14 +919,7 @@ private static function applyConstructorPromotionFallback(
                             }
                         }
 
-                        $isVariadic = $p->isVariadic();
-                        if (
-                            $isVariadic
-                            && ! ($resolvedProp instanceof ArrayTypeNode)
-                            && ! ($resolvedProp instanceof GenericTypeNode && \in_array(strtolower($resolvedProp->type->name), ['array', 'list', 'iterable', 'traversable', 'non-empty-array', 'non-empty-list'], true))
-                        ) {
-                            $resolvedProp = new ArrayTypeNode($resolvedProp);
-                        }
+                        $resolvedProp = self::wrapVariadicParameterType($resolvedProp, false, $p->isVariadic(), $p);
 
                         if (
                             Config::isRespectNativeNullabilityEnabled()
@@ -954,6 +940,70 @@ private static function applyConstructorPromotionFallback(
         }
     }
 
+    /**
+     * Checks whether an un-promoted constructor parameter is compatible with a class property.
+     */
+    private static function areConstructorParamAndPropertyCompatible(
+        \ReflectionParameter $p,
+        \ReflectionProperty $propertyRef
+    ): bool {
+        if ($p->isPromoted()) {
+            return true;
+        }
+
+        if ($p->hasType() && $propertyRef->hasType()) {
+            $pType = (string) $p->getType();
+            $propType = (string) $propertyRef->getType();
+
+            $normP = strtolower(ltrim($pType, '?'));
+            $normProp = strtolower(ltrim($propType, '?'));
+
+            if ($normP !== $normProp) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Wraps a variadic parameter type into an ArrayTypeNode, accounting for variadic arrays/iterables.
+     */
+    private static function wrapVariadicParameterType(
+        TypeNode $type,
+        bool $tagIsVariadic,
+        bool $nativeIsVariadic,
+        ?\ReflectionParameter $reflectionParam = null
+    ): TypeNode {
+        if (! $tagIsVariadic && ! $nativeIsVariadic) {
+            return $type;
+        }
+
+        $isNativeArrayOrIterable = false;
+        if ($reflectionParam !== null && $reflectionParam->hasType()) {
+            $nativeType = $reflectionParam->getType();
+            if ($nativeType instanceof \ReflectionNamedType) {
+                $nativeName = strtolower($nativeType->getName());
+                $isNativeArrayOrIterable = \in_array($nativeName, ['array', 'iterable'], true);
+            }
+        }
+
+        // If native parameter is array ...$items, each argument is an array, so wrap in ArrayTypeNode
+        if ($isNativeArrayOrIterable) {
+            return new ArrayTypeNode($type);
+        }
+
+        // If DocBlock type is not already an ArrayTypeNode or list/array GenericTypeNode
+        if (
+            ! ($type instanceof ArrayTypeNode)
+            && ! ($type instanceof GenericTypeNode && \in_array(strtolower($type->type->name), ['array', 'list', 'iterable', 'traversable', 'non-empty-array', 'non-empty-list'], true))
+        ) {
+            return new ArrayTypeNode($type);
+        }
+
+        return $type;
+    }
+
     /**
      * Checks if a scalar refinement type is compatible with a native PHP builtin type.
      */

src/Internal/Checker/InlineChecker.php

@@ -139,6 +139,10 @@ public static function checkVariable(mixed $value, string $typeString, string $v
                 return $value;
             }
 
+            if ($value === [] && $varName !== 'return' && self::isArrayShapeType($typeNode)) {
+                return $value;
+            }
+
             $context = ($varName === 'return') ? 'Return value' : "Variable \$$varName";
 
             if ($typeNode instanceof CallableTypeNode || ($typeNode instanceof IdentifierTypeNode && strtolower($typeNode->name) === 'callable')) {
@@ -166,6 +170,30 @@ public static function checkVariable(mixed $value, string $typeString, string $v
         return $value;
     }
 
+    /**
+     * Checks if a TypeNode is or contains an ArrayShapeNode.
+     */
+    private static function isArrayShapeType(TypeNode $node): bool
+    {
+        if ($node instanceof ArrayShapeNode) {
+            return true;
+        }
+
+        if ($node instanceof NullableTypeNode) {
+            return self::isArrayShapeType($node->type);
+        }
+
+        if ($node instanceof UnionTypeNode) {
+            foreach ($node->types as $subType) {
+                if (self::isArrayShapeType($subType)) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
     /**
      * Evaluates class property validation dynamically based on configuration.
      */