Implement require-extends rules

conf/config.level2.neon

@@ -42,6 +42,11 @@ rules:
 	- PHPStan\Rules\PhpDoc\IncompatiblePropertyPhpDocTypeRule
 	- PHPStan\Rules\PhpDoc\InvalidThrowsPhpDocValueRule
 	- PHPStan\Rules\Properties\AccessPrivatePropertyThroughStaticRule
+	- PHPStan\Rules\Classes\RequireImplementsRule
+	- PHPStan\Rules\Classes\RequireExtendsRule
+	- PHPStan\Rules\PhpDoc\RequireImplementsDefinitionClassRule
+	- PHPStan\Rules\PhpDoc\RequireExtendsDefinitionClassRule
+	- PHPStan\Rules\PhpDoc\RequireExtendsDefinitionTraitRule
 
 conditionalTags:
 	PHPStan\Rules\Functions\IncompatibleArrowFunctionDefaultParameterTypeRule:
@@ -64,6 +69,19 @@ services:
 			checkClassCaseSensitivity: %checkClassCaseSensitivity%
 		tags:
 			- phpstan.rules.rule
+
+	-
+		class: PHPStan\Rules\PhpDoc\RequireExtendsCheck
+		arguments:
+			checkClassCaseSensitivity: %checkClassCaseSensitivity%
+
+	-
+		class: PHPStan\Rules\PhpDoc\RequireImplementsDefinitionTraitRule
+		arguments:
+			checkClassCaseSensitivity: %checkClassCaseSensitivity%
+		tags:
+			- phpstan.rules.rule
+
 	-
 		class: PHPStan\Rules\Functions\IncompatibleArrowFunctionDefaultParameterTypeRule
 	-

phpstan-baseline.neon

@@ -448,6 +448,16 @@ parameters:
 			count: 2
 			path: src/Rules/Classes/ImpossibleInstanceOfRule.php
 
+		-
+			message: "#^Doing instanceof PHPStan\\\\Type\\\\ObjectType is error\\-prone and deprecated\\. Use Type\\:\\:isObject\\(\\) or Type\\:\\:getObjectClassNames\\(\\) instead\\.$#"
+			count: 2
+			path: src/Rules/Classes/RequireExtendsRule.php
+
+		-
+			message: "#^Doing instanceof PHPStan\\\\Type\\\\ObjectType is error\\-prone and deprecated\\. Use Type\\:\\:isObject\\(\\) or Type\\:\\:getObjectClassNames\\(\\) instead\\.$#"
+			count: 1
+			path: src/Rules/Classes/RequireImplementsRule.php
+
 		-
 			message: "#^Doing instanceof PHPStan\\\\Type\\\\Constant\\\\ConstantBooleanType is error\\-prone and deprecated\\. Use Type\\:\\:isTrue\\(\\) or Type\\:\\:isFalse\\(\\) instead\\.$#"
 			count: 6
@@ -631,6 +641,16 @@ parameters:
 			count: 1
 			path: src/Rules/Methods/StaticMethodCallCheck.php
 
+		-
+			message: "#^Doing instanceof PHPStan\\\\Type\\\\ObjectType is error\\-prone and deprecated\\. Use Type\\:\\:isObject\\(\\) or Type\\:\\:getObjectClassNames\\(\\) instead\\.$#"
+			count: 1
+			path: src/Rules/PhpDoc/RequireExtendsCheck.php
+
+		-
+			message: "#^Doing instanceof PHPStan\\\\Type\\\\ObjectType is error\\-prone and deprecated\\. Use Type\\:\\:isObject\\(\\) or Type\\:\\:getObjectClassNames\\(\\) instead\\.$#"
+			count: 1
+			path: src/Rules/PhpDoc/RequireImplementsDefinitionTraitRule.php
+
 		-
 			message: "#^Doing instanceof PHPStan\\\\Type\\\\Generic\\\\GenericObjectType is error\\-prone and deprecated\\.$#"
 			count: 1

src/PhpDoc/PhpDocNodeResolver.php

@@ -27,8 +27,6 @@
 use PHPStan\PhpDocParser\Ast\ConstExpr\ConstExprNullNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\MixinTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
-use PHPStan\PhpDocParser\Ast\PhpDoc\RequireExtendsTagValueNode;
-use PHPStan\PhpDocParser\Ast\PhpDoc\RequireImplementsTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\TemplateTagValueNode;
 use PHPStan\Reflection\PassedByReference;
 use PHPStan\Rules\PhpDoc\UnresolvableTypeHelper;
@@ -418,19 +416,35 @@ public function resolveMixinTags(PhpDocNode $phpDocNode, NameScope $nameScope):
 	 */
 	public function resolveRequireExtendsTags(PhpDocNode $phpDocNode, NameScope $nameScope): array
 	{
-		return array_map(fn (RequireExtendsTagValueNode $requireExtendsTagValueNode): RequireExtendsTag => new RequireExtendsTag(
-			$this->typeNodeResolver->resolve($requireExtendsTagValueNode->type, $nameScope),
-		), $phpDocNode->getRequireExtendsTagValues());
+		$resolved = [];
+
+		foreach (['@psalm-require-extends', '@phpstan-require-extends'] as $tagName) {
+			foreach ($phpDocNode->getRequireExtendsTagValues($tagName) as $tagValue) {
+				$resolved[] = new RequireExtendsTag(
+					$this->typeNodeResolver->resolve($tagValue->type, $nameScope),
+				);
+			}
+		}
+
+		return $resolved;
 	}
 
 	/**
 	 * @return array<RequireImplementsTag>
 	 */
 	public function resolveRequireImplementsTags(PhpDocNode $phpDocNode, NameScope $nameScope): array
 	{
-		return array_map(fn (RequireImplementsTagValueNode $requireImplementsTagValueNode): RequireImplementsTag => new RequireImplementsTag(
-			$this->typeNodeResolver->resolve($requireImplementsTagValueNode->type, $nameScope),
-		), $phpDocNode->getRequireImplementsTagValues());
+		$resolved = [];
+
+		foreach (['@psalm-require-implements', '@phpstan-require-implements'] as $tagName) {
+			foreach ($phpDocNode->getRequireImplementsTagValues($tagName) as $tagValue) {
+				$resolved[] = new RequireImplementsTag(
+					$this->typeNodeResolver->resolve($tagValue->type, $nameScope),
+				);
+			}
+		}
+
+		return $resolved;
 	}
 
 	/**

src/Reflection/ClassReflection.php

@@ -924,7 +924,7 @@ public function getTraits(bool $recursive = false): array
 	}
 
 	/**
-	 * @return string[]
+	 * @return list<class-string>
 	 */
 	public function getParentClassesNames(): array
 	{

src/Rules/Classes/RequireExtendsRule.php

@@ -0,0 +1,79 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Classes;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+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>
+ */
+class RequireExtendsRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+
+		$errors = [];
+		foreach ($classReflection->getImmediateInterfaces() as $interface) {
+			$extendsTags = $interface->getRequireExtendsTags();
+			foreach ($extendsTags as $extendsTag) {
+				$type = $extendsTag->getType();
+				if (!$type instanceof ObjectType) {
+					continue;
+				}
+
+				if ($classReflection->isSubclassOf($type->getClassName())) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(
+					sprintf(
+						'Interface %s requires implementing class to extend %s, but %s does not.',
+						$interface->getName(),
+						$type->describe(VerbosityLevel::typeOnly()),
+						$classReflection->getName(),
+					),
+				)->build();
+			}
+		}
+
+		foreach ($classReflection->getTraits() as $trait) {
+			$extendsTags = $trait->getRequireExtendsTags();
+			foreach ($extendsTags as $extendsTag) {
+				$type = $extendsTag->getType();
+				if (!$type instanceof ObjectType) {
+					continue;
+				}
+
+				if ($classReflection->isSubclassOf($type->getClassName())) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(
+					sprintf(
+						'Trait %s requires using class to extend %s, but %s does not.',
+						$trait->getName(),
+						$type->describe(VerbosityLevel::typeOnly()),
+						$classReflection->getName(),
+					),
+				)->build();
+			}
+		}
+
+		return $errors;
+	}
+
+}

src/Rules/Classes/RequireImplementsRule.php

@@ -0,0 +1,56 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Classes;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+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>
+ */
+class RequireImplementsRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+
+		$errors = [];
+		foreach ($classReflection->getTraits() as $trait) {
+			$implementsTags = $trait->getRequireImplementsTags();
+			foreach ($implementsTags as $implementsTag) {
+				$type = $implementsTag->getType();
+				if (!$type instanceof ObjectType) {
+					continue;
+				}
+
+				if ($classReflection->implementsInterface($type->getClassName())) {
+					continue;
+				}
+
+				$errors[] = RuleErrorBuilder::message(
+					sprintf(
+						'Trait %s requires using class to implement %s, but %s does not.',
+						$trait->getName(),
+						$type->describe(VerbosityLevel::typeOnly()),
+						$classReflection->getName(),
+					),
+				)->build();
+			}
+		}
+
+		return $errors;
+	}
+
+}

src/Rules/PhpDoc/RequireExtendsCheck.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\PhpDoc\Tag\RequireExtendsTag;
+use PHPStan\Rules\ClassCaseSensitivityCheck;
+use PHPStan\Rules\ClassNameNodePair;
+use PHPStan\Rules\RuleError;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\VerbosityLevel;
+use function array_merge;
+use function sprintf;
+
+final class RequireExtendsCheck
+{
+
+	public function __construct(
+		private ClassCaseSensitivityCheck $classCaseSensitivityCheck,
+		private bool $checkClassCaseSensitivity,
+	)
+	{
+	}
+
+	/**
+	 * @param  array<RequireExtendsTag> $extendsTags
+	 * @return RuleError[]
+	 */
+	public function checkExtendsTags(Node $node, array $extendsTags): array
+	{
+		$errors = [];
+		foreach ($extendsTags as $extendsTag) {
+			$type = $extendsTag->getType();
+			if (!$type instanceof ObjectType) {
+				$errors[] = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-require-extends contains non-object type %s.', $type->describe(VerbosityLevel::typeOnly())))->build();
+				continue;
+			}
+
+			$class = $type->getClassName();
+			$referencedClassReflection = $type->getClassReflection();
+
+			if ($referencedClassReflection === null) {
+				$errors[] = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-require-extends contains unknown class %s.', $class))->discoveringSymbolsTip()->build();
+				continue;
+			}
+
+			if (!$referencedClassReflection->isClass()) {
+				$errors[] = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-require-extends cannot contain non-class type %s.', $class))->build();
+			} elseif ($referencedClassReflection->isFinal()) {
+				$errors[] = RuleErrorBuilder::message(sprintf('PHPDoc tag @phpstan-require-extends cannot contain final class %s.', $class))->build();
+			} elseif ($this->checkClassCaseSensitivity) {
+				$errors = array_merge(
+					$errors,
+					$this->classCaseSensitivityCheck->checkClassNames([
+						new ClassNameNodePair($class, $node),
+					]),
+				);
+			}
+		}
+
+		return $errors;
+	}
+
+}

src/Rules/PhpDoc/RequireExtendsDefinitionClassRule.php

@@ -0,0 +1,47 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function count;
+
+/**
+ * @implements Rule<InClassNode>
+ */
+class RequireExtendsDefinitionClassRule implements Rule
+{
+
+	public function __construct(
+		private RequireExtendsCheck $requireExtendsCheck,
+	)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return InClassNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$classReflection = $node->getClassReflection();
+		$extendsTags = $classReflection->getRequireExtendsTags();
+
+		if (count($extendsTags) === 0) {
+			return [];
+		}
+
+		if (!$classReflection->isInterface()) {
+			return [
+				RuleErrorBuilder::message('PHPDoc tag @phpstan-require-extends is only valid on trait or interface.')->build(),
+			];
+		}
+
+		return $this->requireExtendsCheck->checkExtendsTags($node, $extendsTags);
+	}
+
+}