added Nette\Schema\Expect::array() return type narrowing

Author: dg

CLAUDE.md

@@ -36,6 +36,14 @@ Each extension class is registered as a service in NEON with the appropriate tag
 - `phpstan.broker.methodsClassReflectionExtension` — magic methods
 - `phpstan.broker.typeSpecifyingExtension` — type narrowing
 
+### Namespace conventions
+
+Extensions for specific Nette packages use dedicated namespaces: `Nette\PHPStan\Schema\` for nette/schema, future packages follow the same pattern (`Nette\PHPStan\Forms\`, `Nette\PHPStan\Application\`, etc.). Generic extensions use `Nette\PHPStan\Type\` or `Nette\PHPStan\Analyser\`.
+
+### ExpectArrayReturnTypeExtension
+
+`ExpectArrayReturnTypeExtension` (`DynamicStaticMethodReturnTypeExtension`) narrows the return type of `Expect::array()` from `Structure|Type` to `Structure` or `Type`. It inspects the argument: no argument, null, empty array, or non-Schema values → `Type`; all values implementing `Schema` → `Structure`; mixed/unknown → fallback to declared union. Config: `extension-schema.neon`.
+
 ### NarrowReturnTypeResolver
 
 `NarrowReturnTypeResolver` (`ExpressionTypeResolverExtension`) removes `|false` from return types of native PHP functions and methods where false is trivial or outdated. It handles `FuncCall`, `MethodCall`, and `StaticCall` in a single class. Configuration uses a flat list in NEON — plain names for functions (`json_encode`), `Class::method` notation for methods (`Normalizer::normalize`). It runs before all `DynamicReturnTypeExtension` implementations, delegates to them via `DynamicReturnTypeExtensionRegistry`, and strips `|false` from the result.

composer.json

@@ -16,7 +16,8 @@
 		"phpstan/phpstan": "^2.1"
 	},
 	"require-dev": {
-		"nette/tester": "^2.6"
+		"nette/tester": "^2.6",
+		"nette/schema": "^1.3"
 	},
 	"autoload": {
 		"psr-4": {

extension-schema.neon

@@ -0,0 +1,4 @@
+services:
+	-
+		class: Nette\PHPStan\Schema\ExpectArrayReturnTypeExtension
+		tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]

extension.neon

@@ -15,6 +15,7 @@ parameters:
 
 includes:
 	- extension-narrowReturnType.neon
+	- extension-schema.neon
 
 services:
 	-

readme.md

@@ -55,6 +55,12 @@ $cwd = getcwd();
 
  <!---->
 
+### Other
+
+- Narrows the return type of `Expect::array()` from `Structure|Type` to `Structure` or `Type` based on the argument
+
+ <!---->
+
 ### Type Validation Call Ignore
 
 Suppresses `expr.resultUnused` for the runtime type validation pattern commonly used in Nette:

src/Schema/ExpectArrayReturnTypeExtension.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Nette\PHPStan\Schema;
+
+use Nette\Schema\Elements\Structure;
+use Nette\Schema\Elements\Type;
+use Nette\Schema\Expect;
+use Nette\Schema\Schema;
+use PhpParser\Node\Expr\StaticCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicStaticMethodReturnTypeExtension;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\Type as PhpStanType;
+
+
+/**
+ * Narrows the return type of Expect::array() from Structure|Type
+ * to Structure or Type based on the argument content.
+ */
+class ExpectArrayReturnTypeExtension implements DynamicStaticMethodReturnTypeExtension
+{
+	public function getClass(): string
+	{
+		return Expect::class;
+	}
+
+
+	public function isStaticMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return $methodReflection->getName() === 'array';
+	}
+
+
+	public function getTypeFromStaticMethodCall(
+		MethodReflection $methodReflection,
+		StaticCall $methodCall,
+		Scope $scope,
+	): ?PhpStanType
+	{
+		$args = $methodCall->getArgs();
+		if ($args === []) {
+			return new ObjectType(Type::class);
+		}
+
+		$argType = $scope->getType($args[0]->value);
+
+		if ($argType->isNull()->yes()) {
+			return new ObjectType(Type::class);
+		}
+
+		$constantArrays = $argType->getConstantArrays();
+		if ($constantArrays === []) {
+			return null;
+		}
+
+		$valueTypes = $constantArrays[0]->getValueTypes();
+		if ($valueTypes === []) {
+			return new ObjectType(Type::class);
+		}
+
+		$schemaType = new ObjectType(Schema::class);
+		$hasSchema = false;
+		$hasNonSchema = false;
+
+		foreach ($valueTypes as $valueType) {
+			if ($schemaType->isSuperTypeOf($valueType)->yes()) {
+				$hasSchema = true;
+			} else {
+				$hasNonSchema = true;
+			}
+		}
+
+		if ($hasSchema && !$hasNonSchema) {
+			return new ObjectType(Structure::class);
+		}
+
+		if ($hasNonSchema && !$hasSchema) {
+			return new ObjectType(Type::class);
+		}
+
+		return null;
+	}
+}

tests/Schema/ExpectArrayReturnTypeTest.phpt

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+/**
+ * Test: Expect::array() return type narrowing.
+ */
+
+require __DIR__ . '/../bootstrap.php';
+
+use Nette\PHPStan\Tester\TypeAssert;
+
+TypeAssert::assertTypes(__DIR__ . '/../data/schema/expect-array-return-type.php', [__DIR__ . '/../../extension.neon']);

tests/data/schema/expect-array-return-type.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use Nette\Schema\Elements\Structure;
+use Nette\Schema\Elements\Type;
+use Nette\Schema\Expect;
+use function PHPStan\Testing\assertType;
+
+
+// No argument → Type
+assertType(Type::class, Expect::array());
+
+// Empty array → Type
+assertType(Type::class, Expect::array([]));
+
+// Non-Schema values → Type
+assertType(Type::class, Expect::array(['key1' => 'val1', 'val3']));
+
+// Schema values (shape definition) → Structure
+assertType(Structure::class, Expect::array(['a' => Expect::string()]));
+assertType(Structure::class, Expect::array([Expect::int(), Expect::string()]));
+
+// Null argument → Type
+assertType(Type::class, Expect::array(null));