WIP - Limit inheritance to a subset of classes #1450

config.xsd

@@ -250,6 +250,7 @@
             <xs:element name="InaccessibleClassConstant" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="InaccessibleMethod" type="MethodIssueHandlerType" minOccurs="0" />
             <xs:element name="InaccessibleProperty" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="InheritorViolation" type="ClassIssueHandlerType" minOccurs="0" />
             <xs:element name="InterfaceInstantiation" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="InternalClass" type="ClassIssueHandlerType" minOccurs="0" />
             <xs:element name="InternalMethod" type="MethodIssueHandlerType" minOccurs="0" />

docs/annotating_code/supported_annotations.md

@@ -737,6 +737,22 @@ any explicit references to them in your code. You should mark these classes with
 class UnreferencedClass {}
 ```
 
+### `@psalm-inheritors`
+
+Used to tell Psalm that a class can only be extended by a certain subset of classes.
+
+For example, 
+```php
+<?php
+/**
+ * @psalm-inheritors FooClass|BarClass
+ */
+class BaseClass {}
+class FooClass extends BaseClass {}
+class BarClass extends BaseClass {}
+class BazClass extends BaseClass {} // this is an error
+```
+
 ## Type Syntax
 
 Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/latest/guide/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).

docs/running_psalm/issues.md

@@ -52,6 +52,7 @@
  - [InaccessibleClassConstant](issues/InaccessibleClassConstant.md)
  - [InaccessibleMethod](issues/InaccessibleMethod.md)
  - [InaccessibleProperty](issues/InaccessibleProperty.md)
+ - [InheritorViolation](issues/InheritorViolation.md)
  - [InterfaceInstantiation](issues/InterfaceInstantiation.md)
  - [InternalClass](issues/InternalClass.md)
  - [InternalMethod](issues/InternalMethod.md)

docs/running_psalm/issues/InheritorViolation.md

@@ -0,0 +1,17 @@
+# InheritorViolation
+
+Emitted when a class/interface using `@psalm-inheritors` is extended/implemented
+by a class that does not fulfil it's requirements.
+
+```php
+<?php
+
+/**
+ * @psalm-inheritors FooClass|BarClass
+ */
+class BaseClass {}
+class BazClass extends BaseClass {}
+// InheritorViolation is emitted, as BaseClass can only be extended
+// by FooClass|BarClass, which is not the case
+$a = new BazClass();
+```

docs/running_psalm/issues/InvalidExtendClass.md

@@ -1,6 +1,6 @@
 # InvalidExtendClass
 
-Emitted when attempting to extend a final class or a class annotated with `@final`.
+Emitted when attempting to extend a final class, a class annotated with `@final` or a class using @psalm-inheritors and not in the inheritor list
 
 ```php
 <?php
@@ -15,4 +15,11 @@ class B extends A {}
 class DoctrineA {}
 
 class DoctrineB extends DoctrineA {}
-```
+
+/**
+ * @psalm-inheritors A|B
+ */
+class C {}
+
+class D extends C {}
+```

src/Psalm/DocComment.php

@@ -18,7 +18,7 @@
 
 final class DocComment
 {
     public const PSALM_ANNOTATIONS = [
         'return', 'param', 'template', 'var', 'type',
         'template-covariant', 'property', 'property-read', 'property-write', 'method',
         'assert', 'assert-if-true', 'assert-if-false', 'suppress',
@@ -34,7 +34,7 @@
         'taint-unescape', 'self-out', 'consistent-constructor', 'stub-override',
         'require-extends', 'require-implements', 'param-out', 'ignore-var',
         'consistent-templates', 'if-this-is', 'this-out', 'check-type', 'check-type-exact',
-        'api',
+        'api', 'inheritors',
     ];
 
     /**

src/Psalm/Internal/Analyzer/ClassLikeAnalyzer.php

@@ -14,6 +14,7 @@
 use Psalm\Internal\Type\TemplateResult;
 use Psalm\Internal\Type\TemplateStandinTypeReplacer;
 use Psalm\Issue\InaccessibleProperty;
+use Psalm\Issue\InheritorViolation;
 use Psalm\Issue\InvalidClass;
 use Psalm\Issue\InvalidTemplateParam;
 use Psalm\Issue\MissingDependency;
@@ -28,6 +29,7 @@
 use Psalm\StatementsSource;
 use Psalm\Storage\ClassLikeStorage;
 use Psalm\Type;
+use Psalm\Type\Atomic\TNamedObject;
 use Psalm\Type\Atomic\TTemplateParam;
 use Psalm\Type\Union;
 use UnexpectedValueException;
@@ -331,6 +333,23 @@ public static function checkFullyQualifiedClassLikeName(
             return null;
         }
 
+
+        $classUnion = new Union([new TNamedObject($fq_class_name)]);
+        foreach ($class_storage->parent_classes + $class_storage->direct_class_interfaces as $parent_class) {
+            $parent_storage = $codebase->classlikes->getStorageFor($parent_class);
+            if ($parent_storage && $parent_storage->inheritors) {
+                if (!UnionTypeComparator::isContainedBy($codebase, $classUnion, $parent_storage->inheritors)) {
+                    IssueBuffer::maybeAdd(
+                        new InheritorViolation(
+                            'Class ' . $fq_class_name . ' is not an allowed inheritor of parent class ' . $parent_class,
+                            $code_location,
+                        ),
+                        $suppressed_issues,
+                    );
+                }
+            }
+        }
+
         foreach ($class_storage->invalid_dependencies as $dependency_class_name => $_) {
             // if the implemented/extended class is stubbed, it may not yet have
             // been hydrated

src/Psalm/Internal/PhpVisitor/Reflector/ClassLikeDocblockParser.php

@@ -252,6 +252,14 @@ public static function parse(
             $info->sealed_methods = false;
         }
 
+        if (isset($parsed_docblock->tags['psalm-inheritors'])) {
+            foreach ($parsed_docblock->tags['psalm-inheritors'] as $template_line) {
+                $doc_line_parts = CommentAnalyzer::splitDocLine($template_line);
+                $doc_line_parts[0] = CommentAnalyzer::sanitizeDocblockType($doc_line_parts[0]);
+                $info->inheritors = $doc_line_parts[0];
+            }
+        }
+
         if (isset($parsed_docblock->tags['psalm-immutable'])
             || isset($parsed_docblock->tags['psalm-mutation-free'])
         ) {

src/Psalm/Internal/PhpVisitor/Reflector/ClassLikeNodeScanner.php

@@ -539,6 +539,31 @@ public function start(PhpParser\Node\Stmt\ClassLike $node): ?bool
             $storage->sealed_properties = $docblock_info->sealed_properties;
             $storage->sealed_methods = $docblock_info->sealed_methods;
 
+
+            if ($docblock_info->inheritors) {
+                try {
+                    $storage->inheritors = TypeParser::parseTokens(
+                        TypeTokenizer::getFullyQualifiedTokens(
+                            $docblock_info->inheritors,
+                            $storage->aliases,
+                            $storage->template_types ?? [],
+                            $storage->type_aliases,
+                            $fq_classlike_name,
+                        ),
+                        null,
+                        $storage->template_types ?? [],
+                        $storage->type_aliases,
+                        true,
+                    );
+                } catch (TypeParseTreeException $e) {
+                    $storage->docblock_issues[] = new InvalidDocblock(
+                        '@psalm-inheritors contains invalid reference:' . $e->getMessage(),
+                        $name_location ?? $class_location,
+                    );
+                }
+            }
+
+
             if ($docblock_info->properties) {
                 foreach ($docblock_info->properties as $property) {
                     $pseudo_property_type_tokens = TypeTokenizer::getFullyQualifiedTokens(

src/Psalm/Internal/Scanner/ClassLikeDocblockComment.php

@@ -87,6 +87,8 @@ class ClassLikeDocblockComment
      */
     public array $imported_types = [];
 
+    public ?string $inheritors = null;
+
     public bool $consistent_constructor = false;
 
     public bool $consistent_templates = false;

src/Psalm/Issue/InheritorViolation.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Psalm\Issue;
+
+final class InheritorViolation extends CodeIssue
+{
+    public const ERROR_LEVEL = 4;
+    public const SHORTCODE = 283;
+}

src/Psalm/Storage/ClassLikeStorage.php

@@ -314,6 +314,11 @@ final class ClassLikeStorage implements HasAttributesInterface
      */
     public $appearing_property_ids = [];
 
+    /**
+     * @var ?Union
+     */
+    public $inheritors = null;
+
     /**
      * @var array<string, string>
      */

tests/ClassTest.php

@@ -847,6 +847,96 @@ private final function __construct() {}
                     }
                     PHP,
             ],
+            'singleInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass
+                     */
+                    class BaseClass {}
+                    class FooClass extends BaseClass {}
+                    $a = new FooClass();
+                    PHP,
+            ],
+            'unionInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    class BaseClass {}
+                    class FooClass extends BaseClass {}
+                    $a = new FooClass();
+                    class BarClass extends FooClass {}
+                    $b = new BarClass();
+                    PHP,
+            ],
+            'multiInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|arClass
+                     */
+                    class BaseClass {}
+                    class FooClass extends BaseClass {}
+                    $a = new FooClass();
+                    class BarClass extends FooClass {}
+                    $b = new BarClass();
+                    PHP,
+            ],
+            'skippedInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    class BaseClass {}
+                    class FooClass extends BaseClass {}
+                    $a = new FooClass();
+                    class BarClass extends FooClass {}
+                    $b = new BarClass();
+                    PHP,
+            ],
+            'CompositeInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors BarClass&FooInterface
+                     */
+                    class BaseClass {}
+                    interface FooInterface {}
+                    class BarClass extends BaseClass implements FooInterface {}
+                    $b = new BarClass();
+                    PHP,
+            ],
+            'InterfaceInheritorIsAllowed' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    interface BaseInterface {}
+                    class FooClass implements BaseInterface {}
+                    $a = new FooClass();
+                    class BarClass implements BaseInterface {}
+                    $b = new BarClass();
+                    PHP,
+                ],
+                'MultiInterfaceInheritorIsAllowed' => [
+                    'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    interface InterfaceA {}
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    interface InterfaceB {}
+                    class FooClass implements InterfaceA, InterfaceB {}
+                    $a = new FooClass();
+                    PHP,
+            ],
         ];
     }
 
@@ -1293,6 +1383,49 @@ class Bar extends Foo {}
                 'ignored_issues' => [],
                 'php_version' => '8.2',
             ],
+            'classCannotExtendIfNotInInheritors' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    class BaseClass {}
+                    class BazClass extends BaseClass {} // this is an error
+                    $a = new BazClass();
+                    PHP,
+                'error_message' => 'InheritorViolation',
+                'ignored_issues' => [],
+            ],
+            'classCannotImplementIfNotInInheritors' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass|BarClass
+                     */
+                    interface BaseInterface {}
+                    class BazClass implements BaseInterface {}
+                    $a = new BazClass();
+                    PHP,
+                'error_message' => 'InheritorViolation',
+                'ignored_issues' => [],
+            ],
+            'UnfulfilledInterfaceInheritors' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @psalm-inheritors FooClass
+                     */
+                    interface InterfaceA {}
+                    /**
+                     * @psalm-inheritors BarClass
+                     */
+                    interface InterfaceB {}
+                    class BazClass implements InterFaceA, InterFaceB {}
+                    $a = new BazClass();
+                    PHP,
+                'error_message' => 'InheritorViolation',
+                'ignored_issues' => [],
+            ],
         ];
     }
 }