[DowngradePhp82] Add DowngradeArrowFunctionNeverReturnTypeRector (#399)

PHP 8.1 accepts the "never" return type on functions, methods and closures, but rejects it on arrow functions: the implicit return of the body expression trips "A never-returning function must not return" at compile time (php/php-src#7900, fixed in 8.2). #397 taught DowngradeNeverTypeDeclarationRector to strip it from arrow functions, but that rule sits in the 8.1 set, which removes 8.1 features when downgrading *from* 8.1 to 8.0. Code downgraded *to* 8.1 never reaches it, so `fn (): never => throw ...` survived and still failed to compile on 8.1. The arrow-function case is an 8.2 feature and belongs in the 8.2 set; this rule puts it there and leaves every other function-like to the 8.1 set.

Assisted-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: roxblnfk

config/set/downgrade-php82.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 use Rector\Config\RectorConfig;
+use Rector\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector;
 use Rector\DowngradePhp82\Rector\Class_\DowngradeReadonlyClassRector;
 use Rector\DowngradePhp82\Rector\Class_\DowngradeUnionIntersectionRector;
 use Rector\DowngradePhp82\Rector\FuncCall\DowngradeIteratorCountToArrayRector;
@@ -18,5 +19,6 @@
         DowngradeIteratorCountToArrayRector::class,
         DowngradeUnionIntersectionRector::class,
         DowngradeReflectionMethodHasPrototypeRector::class,
+        DowngradeArrowFunctionNeverReturnTypeRector::class,
     ]);
 };

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/DowngradeArrowFunctionNeverReturnTypeRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class DowngradeArrowFunctionNeverReturnTypeRectorTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/Fixture/arrow_function_never.php.inc

@@ -0,0 +1,15 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+$callable = fn (): never => throw new \RuntimeException();
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+$callable = fn () => throw new \RuntimeException();
+
+?>

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/Fixture/skip_closure_never.php.inc

@@ -0,0 +1,12 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+$callable = function (): never {
+    throw new \RuntimeException();
+};
+
+function fail(): never
+{
+    throw new \RuntimeException();
+}

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/Fixture/skip_other_return_type.php.inc

@@ -0,0 +1,6 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+$callable = fn (): int => 1;
+$untyped = fn () => throw new \RuntimeException();

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/Fixture/static_arrow_function_as_argument.php.inc

@@ -0,0 +1,21 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+function run(int $code)
+{
+    return array_map(static fn (int $item): never => throw new \LogicException('boom', $code), [1]);
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\Fixture;
+
+function run(int $code)
+{
+    return array_map(static fn (int $item) => throw new \LogicException('boom', $code), [1]);
+}
+
+?>

rules-tests/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector/config/configured_rule.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(DowngradeArrowFunctionNeverReturnTypeRector::class);
+};

rules/DowngradePhp82/Rector/ArrowFunction/DowngradeArrowFunctionNeverReturnTypeRector.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\DowngradePhp82\Rector\ArrowFunction;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\ArrowFunction;
+use PHPStan\Type\NeverType;
+use Rector\PhpDocDecorator\PhpDocFromTypeDeclarationDecorator;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * PHP 8.1 accepts the "never" return type everywhere except on arrow functions, where the implicit
+ * return of the body expression trips "A never-returning function must not return" at compile time.
+ * PHP 8.2 fixed that, so only the arrow-function case has to go when targeting 8.1; other
+ * function-likes keep "never" until the 8.1 set removes it.
+ *
+ * @changelog https://github.com/php/php-src/issues/7900
+ *
+ * @see \Rector\Tests\DowngradePhp82\Rector\ArrowFunction\DowngradeArrowFunctionNeverReturnTypeRector\DowngradeArrowFunctionNeverReturnTypeRectorTest
+ */
+final class DowngradeArrowFunctionNeverReturnTypeRector extends AbstractRector
+{
+    public function __construct(
+        private readonly PhpDocFromTypeDeclarationDecorator $phpDocFromTypeDeclarationDecorator
+    ) {
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [ArrowFunction::class];
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Remove "never" return type from arrow functions, which PHP 8.1 rejects at compile time',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+$callable = fn (): never => throw new \RuntimeException();
+CODE_SAMPLE
+                    ,
+                    <<<'CODE_SAMPLE'
+$callable = fn () => throw new \RuntimeException();
+CODE_SAMPLE
+                ),
+            ]
+        );
+    }
+
+    /**
+     * @param ArrowFunction $node
+     */
+    public function refactor(Node $node): ?Node
+    {
+        if (! $this->phpDocFromTypeDeclarationDecorator->decorateReturnWithSpecificType($node, new NeverType())) {
+            return null;
+        }
+
+        return $node;
+    }
+}