[TypeDeclaration] Add typeGuardedClasses() to guard against breaking method signature changes (#8135)

Introduces ->withTypeGuardedClasses([...]) / RectorConfig::typeGuardedClasses([...]).
Listed classes and their non-final descendants are left untouched by type-declaration
rules, since adding a return or param type to an extendable class is a breaking change
for its child overrides. Final classes are never guarded (cannot be extended).

Logic lives in ParentClassMethodTypeOverrideGuard::isTypeGuardedClass() and is applied
at the shared choke points, covering the return and param rule families:
- ClassMethodReturnTypeOverrideGuard::shouldSkipClassMethod() (return family)
- ClassMethodParamVendorLockResolver::isVendorLocked() (param completer path)
- AbstractParamTypeByMethodCallTypeRector::shouldSkipClassMethod() (by-method-call param family)
- AddReturnTypeDeclarationRector / AddParamTypeDeclarationRector (configurable rules)

When no classes are configured the guard short-circuits, so existing behaviour is
unchanged.

Author: TomasVotruba

rules-tests/TypeDeclaration/TypeGuardedClasses/Fixture/final_child_applied.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\TypeGuardedClasses\Fixture;
+
+use Rector\Tests\TypeDeclaration\TypeGuardedClasses\Source\GuardedRepository;
+
+final class FinalChildApplied extends GuardedRepository
+{
+    public function getData()
+    {
+        return [];
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\TypeGuardedClasses\Fixture;
+
+use Rector\Tests\TypeDeclaration\TypeGuardedClasses\Source\GuardedRepository;
+
+final class FinalChildApplied extends GuardedRepository
+{
+    public function getData(): array
+    {
+        return [];
+    }
+}
+
+?>

rules-tests/TypeDeclaration/TypeGuardedClasses/Fixture/skip_child_of_guarded.php.inc

@@ -0,0 +1,13 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\TypeGuardedClasses\Fixture;
+
+use Rector\Tests\TypeDeclaration\TypeGuardedClasses\Source\GuardedRepository;
+
+class SkipChildOfGuarded extends GuardedRepository
+{
+    public function getData()
+    {
+        return [];
+    }
+}

rules-tests/TypeDeclaration/TypeGuardedClasses/Source/GuardedRepository.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclaration\TypeGuardedClasses\Source;
+
+class GuardedRepository
+{
+    public function getData()
+    {
+        return [];
+    }
+}

rules-tests/TypeDeclaration/TypeGuardedClasses/TypeGuardedClassesTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\TypeDeclaration\TypeGuardedClasses;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class TypeGuardedClassesTest 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/TypeDeclaration/TypeGuardedClasses/config/configured_rule.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+use PHPStan\Type\ArrayType;
+use PHPStan\Type\MixedType;
+use Rector\Config\RectorConfig;
+use Rector\Tests\TypeDeclaration\TypeGuardedClasses\Source\GuardedRepository;
+use Rector\TypeDeclaration\Rector\ClassMethod\AddReturnTypeDeclarationRector;
+use Rector\TypeDeclaration\ValueObject\AddReturnTypeDeclaration;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->typeGuardedClasses([GuardedRepository::class]);
+
+    $rectorConfig->ruleWithConfiguration(AddReturnTypeDeclarationRector::class, [
+        new AddReturnTypeDeclaration(
+            GuardedRepository::class,
+            'getData',
+            new ArrayType(new MixedType(), new MixedType())
+        ),
+    ]);
+};

rules/TypeDeclaration/Rector/ClassMethod/AbstractParamTypeByMethodCallTypeRector.php

@@ -99,6 +99,11 @@ abstract protected function isMatchingParamType(Type $type): bool;
 
     private function shouldSkipClassMethod(ClassMethod $classMethod): bool
     {
+        // user-guarded class: adding a param type here would break its child classes
+        if ($this->parentClassMethodTypeOverrideGuard->isTypeGuardedClass($classMethod)) {
+            return true;
+        }
+
         $isMissingParameterTypes = false;
         foreach ($classMethod->params as $param) {
             if ($param->type instanceof Node) {

rules/TypeDeclaration/Rector/ClassMethod/AddParamTypeDeclarationRector.php

@@ -20,6 +20,7 @@
 use Rector\StaticTypeMapper\StaticTypeMapper;
 use Rector\TypeDeclaration\ValueObject\AddParamTypeDeclaration;
 use Rector\ValueObject\PhpVersionFeature;
+use Rector\VendorLocker\ParentClassMethodTypeOverrideGuard;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\ConfiguredCodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 use Webmozart\Assert\Assert;
@@ -40,6 +41,7 @@ public function __construct(
         private readonly TypeComparator $typeComparator,
         private readonly PhpVersionProvider $phpVersionProvider,
         private readonly StaticTypeMapper $staticTypeMapper,
+        private readonly ParentClassMethodTypeOverrideGuard $parentClassMethodTypeOverrideGuard,
     ) {
     }
 
@@ -85,6 +87,11 @@ public function refactor(Node $node): ?Node
     {
         $this->hasChanged = false;
 
+        // skip guarded classes, where adding a param type would break child classes
+        if ($this->parentClassMethodTypeOverrideGuard->isTypeGuardedClass($node)) {
+            return null;
+        }
+
         foreach ($node->getMethods() as $classMethod) {
             if ($this->shouldSkip($node, $classMethod)) {
                 continue;

rules/TypeDeclaration/Rector/ClassMethod/AddReturnTypeDeclarationRector.php

@@ -89,6 +89,11 @@ public function refactor(Node $node): ?Node
     {
         $this->hasChanged = false;
 
+        // skip guarded classes, where adding a return type would break child classes
+        if ($this->parentClassMethodTypeOverrideGuard->isTypeGuardedClass($node)) {
+            return null;
+        }
+
         foreach ($this->methodReturnTypes as $methodReturnType) {
             $objectType = $methodReturnType->getObjectType();
             if (! $this->isObjectType($node, $objectType)) {

src/Config/RectorConfig.php

@@ -326,6 +326,20 @@ public function treatClassesAsFinal(bool $treatClassesAsFinal = true): void
         SimpleParameterProvider::setParameter(Option::TREAT_CLASSES_AS_FINAL, $treatClassesAsFinal);
     }
 
+    /**
+     * Guard the listed classes and their descendants against method signature changes that would
+     * break child classes - e.g. adding a return type or a param type. Only non-final classes are
+     * guarded, as final classes cannot be extended.
+     *
+     * @param string[] $classes
+     */
+    public function typeGuardedClasses(array $classes): void
+    {
+        Assert::allString($classes);
+
+        SimpleParameterProvider::setParameter(Option::TYPE_GUARDED_CLASSES, $classes);
+    }
+
     /**
      * @param string[] $extensions
      */

src/Configuration/Option.php

@@ -286,4 +286,10 @@ final class Option
      * @internal to allow process file without extension if explicitly registered
      */
     public const string FILES_WITHOUT_EXTENSION = 'files_without_extension';
+
+    /**
+     * @internal Use @see \Rector\Config\RectorConfig::typeGuardedClasses() instead
+     * @var string
+     */
+    public const string TYPE_GUARDED_CLASSES = 'type_guarded_classes';
 }