chore: type improvements

src/ArchPresets/AbstractPreset.php

@@ -53,7 +53,7 @@ abstract class AbstractPreset // @pest-arch-ignore-line
     /**
      * Runs the given callback for each namespace.
      *
-     * @param  callable(Expectation<string|null>): ArchExpectation  ...$callbacks
+     * @param  callable(Expectation<string>): ArchExpectation  ...$callbacks
      */
     final public function eachUserNamespace(callable ...$callbacks): void
     {

src/Functions.php

@@ -4,7 +4,6 @@ declare(strict_types=1);
 
 use Pest\Browser\Api\ArrayablePendingAwaitablePage;
 use Pest\Browser\Api\PendingAwaitablePage;
-use Pest\Concerns\Expectable;
 use Pest\Configuration;
 use Pest\Exceptions\AfterAllWithinDescribe;
 use Pest\Exceptions\BeforeAllWithinDescribe;
@@ -62,8 +61,6 @@ if (! function_exists('beforeEach')) {
      * Runs the given closure before each test in the current file.
      *
      * @param-closure-this TestCase  $closure
-     *
-     * @return HigherOrderTapProxy<Expectable|TestCall|TestCase>|Expectable|TestCall|TestCase|mixed
      */
     function beforeEach(?Closure $closure = null): BeforeEachCall
     {
@@ -92,8 +89,6 @@ if (! function_exists('describe')) {
      * Adds the given closure as a group of tests. The first argument
      * is the group description; the second argument is a closure
      * that contains the group tests.
-     *
-     * @return HigherOrderTapProxy<Expectable|TestCall|TestCase>|Expectable|TestCall|TestCase|mixed
      */
     function describe(string $description, Closure $tests): DescribeCall
     {
@@ -136,7 +131,7 @@ if (! function_exists('test')) {
      *
      * @param-closure-this TestCase  $closure
      *
-     * @return Expectable|TestCall|TestCase|mixed
+     * @return ($description is string ? TestCall : HigherOrderTapProxy|TestCall)
      */
     function test(?string $description = null, ?Closure $closure = null): HigherOrderTapProxy|TestCall
     {
@@ -157,33 +152,22 @@ if (! function_exists('it')) {
      * a closure that contains the test expectations.
      *
      * @param-closure-this TestCase  $closure
-     *
-     * @return Expectable|TestCall|TestCase|mixed
      */
     function it(string $description, ?Closure $closure = null): TestCall
     {
         $description = sprintf('it %s', $description);
 
-        /** @var TestCall $test */
-        $test = test($description, $closure);
-
-        return $test;
+        return test($description, $closure);
     }
 }
 
 if (! function_exists('todo')) {
     /**
      * Creates a new test that is marked as "todo".
-     *
-     * @return Expectable|TestCall|TestCase|mixed
      */
     function todo(string $description): TestCall
     {
-        $test = test($description);
-
-        assert($test instanceof TestCall);
-
-        return $test->todo();
+        return test($description)->todo();
     }
 }
 
@@ -192,8 +176,6 @@ if (! function_exists('afterEach')) {
      * Runs the given closure after each test in the current file.
      *
      * @param-closure-this TestCase  $closure
-     *
-     * @return Expectable|HigherOrderTapProxy<Expectable|TestCall|TestCase>|TestCall|mixed
      */
     function afterEach(?Closure $closure = null): AfterEachCall
     {

src/PHPStan/HigherOrderExpectationTypeExtension.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\PHPStan;
+
+use Pest\Expectations\HigherOrderExpectation;
+use PhpParser\Node\Expr;
+use PhpParser\Node\Expr\PropertyFetch;
+use PhpParser\Node\Identifier;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Type\ExpressionTypeResolverExtension;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\Type;
+
+/**
+ * Prevents native declared properties of HigherOrderExpectation (like $original,
+ * $expectation, $opposite, $shouldReset) from being incorrectly resolved as
+ * higher-order value property accesses by downstream ExpressionTypeResolverExtensions.
+ *
+ * This extension must be registered BEFORE the peststan HigherOrderExpectationTypeExtension.
+ *
+ * @internal
+ */
+final readonly class HigherOrderExpectationTypeExtension implements ExpressionTypeResolverExtension
+{
+    public function __construct(
+        private ReflectionProvider $reflectionProvider,
+    ) {}
+
+    public function getType(Expr $expr, Scope $scope): ?Type
+    {
+        if (! $expr instanceof PropertyFetch || ! $expr->name instanceof Identifier) {
+            return null;
+        }
+
+        $varType = $scope->getType($expr->var);
+
+        if (! (new ObjectType(HigherOrderExpectation::class))->isSuperTypeOf($varType)->yes()) {
+            return null;
+        }
+
+        if (! $this->reflectionProvider->hasClass(HigherOrderExpectation::class)) {
+            return null;
+        }
+
+        $propertyName = $expr->name->name;
+        $classReflection = $this->reflectionProvider->getClass(HigherOrderExpectation::class);
+
+        if (! $classReflection->hasNativeProperty($propertyName)) {
+            return null;
+        }
+
+        return $varType->getProperty($propertyName, $scope)->getReadableType();
+    }
+}