Add phpstan-sealed support

Author: VincentLanglet

src/PhpDoc/PhpDocNodeResolver.php

@@ -19,6 +19,7 @@
 use PHPStan\PhpDoc\Tag\RequireExtendsTag;
 use PHPStan\PhpDoc\Tag\RequireImplementsTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
+use PHPStan\PhpDoc\Tag\SealedTypeTag;
 use PHPStan\PhpDoc\Tag\SelfOutTypeTag;
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\ThrowsTag;
@@ -524,6 +525,24 @@ public function resolveRequireImplementsTags(PhpDocNode $phpDocNode, NameScope $
 		return $resolved;
 	}
 
+	/**
+	 * @return array<SealedTypeTag>
+	 */
+	public function resolveSealedTags(PhpDocNode $phpDocNode, NameScope $nameScope): array
+	{
+		$resolved = [];
+
+		foreach (['@psalm-inheritors', '@phpstan-sealed'] as $tagName) {
+			foreach ($phpDocNode->getSealedTagValues($tagName) as $tagValue) {
+				$resolved[] = new SealedTypeTag(
+					$this->typeNodeResolver->resolve($tagValue->type, $nameScope)
+				);
+			}
+		}
+
+		return $resolved;
+	}
+
 	/**
 	 * @return array<string, TypeAliasTag>
 	 */

src/PhpDoc/ResolvedPhpDocBlock.php

@@ -16,6 +16,7 @@
 use PHPStan\PhpDoc\Tag\RequireExtendsTag;
 use PHPStan\PhpDoc\Tag\RequireImplementsTag;
 use PHPStan\PhpDoc\Tag\ReturnTag;
+use PHPStan\PhpDoc\Tag\SealedTypeTag;
 use PHPStan\PhpDoc\Tag\SelfOutTypeTag;
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\ThrowsTag;
@@ -111,6 +112,9 @@ final class ResolvedPhpDocBlock
 	/** @var array<RequireImplementsTag>|false */
 	private array|false $requireImplementsTags = false;
 
+	/** @var array<SealedTypeTag>|false */
+	private array|false $sealedTypeTags = false;
+
 	/** @var array<TypeAliasTag>|false */
 	private array|false $typeAliasTags = false;
 
@@ -282,6 +286,7 @@ public function merge(array $parents, array $parentPhpDocBlocks): self
 		$result->mixinTags = $this->getMixinTags();
 		$result->requireExtendsTags = $this->getRequireExtendsTags();
 		$result->requireImplementsTags = $this->getRequireImplementsTags();
+		$result->sealedTypeTags = $this->getSealedTags();
 		$result->typeAliasTags = $this->getTypeAliasTags();
 		$result->typeAliasImportTags = $this->getTypeAliasImportTags();
 		$result->assertTags = self::mergeAssertTags($this->getAssertTags(), $parents, $parentPhpDocBlocks);
@@ -663,6 +668,21 @@ public function getRequireImplementsTags(): array
 		return $this->requireImplementsTags;
 	}
 
+	/**
+	 * @return array<SealedTypeTag>
+	 */
+	public function getSealedTags(): array
+	{
+		if ($this->sealedTypeTags === false) {
+			$this->sealedTypeTags = $this->phpDocNodeResolver->resolveSealedTags(
+				$this->phpDocNode,
+				$this->getNameScope(),
+			);
+		}
+
+		return $this->sealedTypeTags;
+	}
+
 	/**
 	 * @return array<TypeAliasTag>
 	 */

src/PhpDoc/Tag/SealedTypeTag.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\PhpDoc\Tag;
+
+use PHPStan\Type\Type;
+
+/**
+ * @api
+ */
+final class SealedTypeTag implements TypedTag
+{
+
+	public function __construct(private Type $type)
+	{
+	}
+
+	public function getType(): Type
+	{
+		return $this->type;
+	}
+
+	public function withType(Type $type): self
+	{
+		return new self($type);
+	}
+
+}

src/Reflection/ClassReflection.php

@@ -23,6 +23,7 @@
 use PHPStan\PhpDoc\Tag\PropertyTag;
 use PHPStan\PhpDoc\Tag\RequireExtendsTag;
 use PHPStan\PhpDoc\Tag\RequireImplementsTag;
+use PHPStan\PhpDoc\Tag\SealedTypeTag;
 use PHPStan\PhpDoc\Tag\TemplateTag;
 use PHPStan\PhpDoc\Tag\TypeAliasImportTag;
 use PHPStan\PhpDoc\Tag\TypeAliasTag;
@@ -1887,6 +1888,19 @@ public function getRequireImplementsTags(): array
 		return $resolvedPhpDoc->getRequireImplementsTags();
 	}
 
+	/**
+	 * @return array<SealedTypeTag>
+	 */
+	public function getSealedTags(): array
+	{
+		$resolvedPhpDoc = $this->getResolvedPhpDoc();
+		if ($resolvedPhpDoc === null) {
+			return [];
+		}
+
+		return $resolvedPhpDoc->getSealedTags();
+	}
+
 	/**
 	 * @return array<string, PropertyTag>
 	 */

src/Rules/ClassNameUsageLocation.php

@@ -38,6 +38,7 @@ final class ClassNameUsageLocation
 	public const PHPDOC_TAG_PROPERTY = 'propertyTag';
 	public const PHPDOC_TAG_REQUIRE_EXTENDS = 'requireExtends';
 	public const PHPDOC_TAG_REQUIRE_IMPLEMENTS = 'requireImplements';
+	public const PHPDOC_TAG_SEALED = 'sealed';
 	public const STATIC_METHOD_CALL = 'staticMethod';
 	public const PHPDOC_TAG_TEMPLATE_BOUND = 'templateBound';
 	public const PHPDOC_TAG_TEMPLATE_DEFAULT = 'templateDefault';

src/Rules/Classes/SealedRule.php

@@ -0,0 +1,68 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Classes;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\RegisteredRule;
+use PHPStan\Node\InClassNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\VerbosityLevel;
+use function sprintf;
+
+/**
+ * @implements Rule<InClassNode>
+ */
+#[RegisteredRule(level: 0)]
+final class SealedRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+		if ($classReflection->isEnum()) {
+			return [];
+		}
+
+		$className = $classReflection->getName();
+
+		$parents = array_values($classReflection->getImmediateInterfaces());
+		$parentClass = $classReflection->getParentClass();
+		if ($parentClass !== null) {
+			$parents[] = $parentClass;
+		}
+
+		$errors = [];
+		foreach ($parents as $parent) {
+			$sealedTags = $parent->getSealedTags();
+			foreach ($sealedTags as $sealedTag) {
+				$type = $sealedTag->getType();
+				if ($type->isSuperTypeOf(new ObjectType($className))->yes()) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(
+					sprintf(
+						'%s %s is sealed and only permits %s as subtypes, %s given.',
+						$parent->isInterface() ? 'Interface' : 'Class',
+						$parent->getDisplayName(),
+						$type->describe(VerbosityLevel::typeOnly()),
+						$classReflection->getDisplayName(),
+					),
+				)
+					->identifier('class.sealed')
+					->build();
+			}
+		}
+
+		return $errors;
+	}
+
+}

src/Rules/PhpDoc/InvalidPHPStanDocTagRule.php

@@ -58,6 +58,7 @@ final class InvalidPHPStanDocTagRule implements Rule
 		'@phpstan-readonly-allow-private-mutation',
 		'@phpstan-require-extends',
 		'@phpstan-require-implements',
+		'@phpstan-sealed',
 		'@phpstan-param-immediately-invoked-callable',
 		'@phpstan-param-later-invoked-callable',
 		'@phpstan-param-closure-this',

src/Rules/PhpDoc/SealedDefinitionClassRule.php

@@ -0,0 +1,97 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredParameter;
+use PHPStan\DependencyInjection\RegisteredRule;
+use PHPStan\Node\InClassNode;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\ClassNameCheck;
+use PHPStan\Rules\ClassNameNodePair;
+use PHPStan\Rules\ClassNameUsageLocation;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\VerbosityLevel;
+use function array_column;
+use function array_map;
+use function array_merge;
+use function count;
+use function sprintf;
+
+/**
+ * @implements Rule<InClassNode>
+ */
+#[RegisteredRule(level: 0)]
+final class SealedDefinitionClassRule implements Rule
+{
+
+	public function __construct(
+		private ClassNameCheck $classCheck,
+		#[AutowiredParameter]
+		private bool $checkClassCaseSensitivity,
+		#[AutowiredParameter(ref: '%tips.discoveringSymbols%')]
+		private bool $discoveringSymbolsTip,
+	)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+		$sealedTags = $classReflection->getSealedTags();
+
+		if ($classReflection->isEnum()) {
+			return [
+				RuleErrorBuilder::message('PHPDoc tag @phpstan-sealed is only valid on class or interface.')
+					->identifier('sealed.onEnum')
+					->build(),
+			];
+		}
+
+		$errors = [];
+		foreach ($sealedTags as $sealedTag) {
+			$type = $sealedTag->getType();
+			$classNames = $type->getObjectClassNames();
+			if (count($classNames) === 0) {
+				$errors[] = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-sealed contains non-object type %s.', $type->describe(VerbosityLevel::typeOnly())))
+					->identifier('sealed.nonObject')
+					->build();
+				continue;
+			}
+
+			$referencedClassReflections = array_map(static fn ($reflection) => [$reflection, $reflection->getName()], $type->getObjectClassReflections());
+			$referencedClassReflectionsMap = array_column($referencedClassReflections, 0, 1);
+			foreach ($classNames as $class) {
+				$referencedClassReflection = $referencedClassReflectionsMap[$class] ?? null;
+				if ($referencedClassReflection === null) {
+					$errorBuilder = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-sealed contains unknown class %s.', $class))
+					->identifier('class.notFound');
+
+					if ($this->discoveringSymbolsTip) {
+						$errorBuilder->discoveringSymbolsTip();
+					}
+
+					$errors[] = $errorBuilder->build();
+					continue;
+				}
+
+				$errors = array_merge(
+					$errors,
+					$this->classCheck->checkClassNames($scope, [
+						new ClassNameNodePair($class, $node),
+					], ClassNameUsageLocation::from(ClassNameUsageLocation::PHPDOC_TAG_SEALED), $this->checkClassCaseSensitivity),
+				);
+			}
+		}
+
+		return $errors;
+	}
+
+}

src/Rules/PhpDoc/SealedDefinitionTraitRule.php

@@ -0,0 +1,53 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\RegisteredRule;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function count;
+
+/**
+ * @implements Rule<Node\Stmt\Trait_>
+ */
+#[RegisteredRule(level: 0)]
+final class SealedDefinitionTraitRule implements Rule
+{
+	public function __construct(
+		private ReflectionProvider $reflectionProvider,
+	)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return Node\Stmt\Trait_::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if (
+			$node->namespacedName === null
+			|| !$this->reflectionProvider->hasClass($node->namespacedName->toString())
+		) {
+			return [];
+		}
+
+		$traitReflection = $this->reflectionProvider->getClass($node->namespacedName->toString());
+		$sealedTags = $traitReflection->getSealedTags();
+
+		if (count($sealedTags) === 0) {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message('PHPDoc tag @phpstan-sealed is only valid on class or interface.')
+				->identifier('sealed.onTrait')
+				->build(),
+		];
+	}
+
+}