Report @inheritDoc when there is no PHPDoc to inherit from

conf/bleedingEdge.neon

@@ -18,3 +18,4 @@ parameters:
 		curlSetOptArrayTypes: true
 		checkDateIntervalConstructor: true
 		reportMethodPurityOverride: true
+		reportInvalidInheritDocTag: true

conf/config.level2.neon

@@ -15,10 +15,15 @@ conditionalTags:
 		phpstan.restrictedPropertyUsageExtension: %featureToggles.internalTag%
 	PHPStan\Rules\InternalTag\RestrictedInternalMethodUsageExtension:
 		phpstan.restrictedMethodUsageExtension: %featureToggles.internalTag%
+	PHPStan\Rules\PhpDoc\InvalidInheritDocTagRule:
+		phpstan.rules.rule: %featureToggles.reportInvalidInheritDocTag%
 
 services:
 	-
 		class: PHPStan\Rules\InternalTag\RestrictedInternalPropertyUsageExtension
 
 	-
 		class: PHPStan\Rules\InternalTag\RestrictedInternalMethodUsageExtension
+
+	-
+		class: PHPStan\Rules\PhpDoc\InvalidInheritDocTagRule

conf/config.neon

@@ -45,6 +45,7 @@ parameters:
 		curlSetOptArrayTypes: false
 		checkDateIntervalConstructor: false
 		reportMethodPurityOverride: false
+		reportInvalidInheritDocTag: false
 	fileExtensions:
 		- php
 	checkAdvancedIsset: false

conf/parametersSchema.neon

@@ -47,6 +47,7 @@ parametersSchema:
 		curlSetOptArrayTypes: bool()
 		checkDateIntervalConstructor: bool()
 		reportMethodPurityOverride: bool()
+		reportInvalidInheritDocTag: bool()
 	])
 	fileExtensions: listOf(string())
 	checkAdvancedIsset: bool()

src/Rules/PhpDoc/InvalidInheritDocTagRule.php

@@ -0,0 +1,111 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassMethodNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
+use PHPStan\PhpDocParser\Lexer\Lexer;
+use PHPStan\PhpDocParser\Parser\PhpDocParser;
+use PHPStan\PhpDocParser\Parser\TokenIterator;
+use PHPStan\Rules\Methods\ParentMethodHelper;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function preg_match;
+use function sprintf;
+use function strtolower;
+
+/**
+ * @implements Rule<InClassMethodNode>
+ */
+final class InvalidInheritDocTagRule implements Rule
+{
+
+	private const INLINE_INHERIT_DOC_REGEX = '~`[^`]*`(*SKIP)(*FAIL)|(?<![a-zA-Z0-9])\{@inheritDoc\b[^}]*\}~i';
+
+	public function __construct(
+		private Lexer $phpDocLexer,
+		private PhpDocParser $phpDocParser,
+		private ParentMethodHelper $parentMethodHelper,
+	)
+	{
+	}
+
+	public function getNodeType(): string
+	{
+		return InClassMethodNode::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		$docComment = $node->getOriginalNode()->getDocComment();
+		if ($docComment === null) {
+			return [];
+		}
+
+		$tokens = new TokenIterator($this->phpDocLexer->tokenize($docComment->getText()));
+		$phpDocNode = $this->phpDocParser->parse($tokens);
+
+		$inheritDocTagName = null;
+		foreach ($phpDocNode->getTags() as $tag) {
+			if (strtolower($tag->name) !== '@inheritdoc') {
+				continue;
+			}
+
+			$inheritDocTagName = $tag->name;
+			break;
+		}
+
+		if ($inheritDocTagName === null) {
+			foreach ($phpDocNode->children as $child) {
+				if (!$child instanceof PhpDocTextNode) {
+					continue;
+				}
+
+				if (preg_match(self::INLINE_INHERIT_DOC_REGEX, $child->text, $matches) !== 1) {
+					continue;
+				}
+
+				$inheritDocTagName = $matches[0];
+				break;
+			}
+		}
+
+		if ($inheritDocTagName === null) {
+			return [];
+		}
+
+		$inheritanceClass = $scope->isInTrait() ? $scope->getTraitReflection() : $node->getClassReflection();
+		$methodName = $node->getMethodReflection()->getName();
+
+		$parentMethods = $this->parentMethodHelper->collectParentMethods($methodName, $inheritanceClass);
+
+		if ($parentMethods === []) {
+			return [
+				RuleErrorBuilder::message(sprintf(
+					'PHPDoc tag %s on method %s::%s() does not override or implement any other method.',
+					$inheritDocTagName,
+					$inheritanceClass->getDisplayName(),
+					$methodName,
+				))->identifier('inheritDoc.noParent')->build(),
+			];
+		}
+
+		foreach ($parentMethods as [$parentMethod]) {
+			if ($parentMethod->getResolvedPhpDoc() !== null) {
+				return [];
+			}
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'PHPDoc tag %s on method %s::%s() refers to a parent method that does not have a PHPDoc.',
+				$inheritDocTagName,
+				$inheritanceClass->getDisplayName(),
+				$methodName,
+			))->identifier('inheritDoc.parentWithoutPhpDoc')->build(),
+		];
+	}
+
+}

tests/PHPStan/Rules/PhpDoc/InvalidInheritDocTagRuleTest.php

@@ -0,0 +1,72 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PHPStan\PhpDocParser\Lexer\Lexer;
+use PHPStan\PhpDocParser\Parser\PhpDocParser;
+use PHPStan\Rules\Methods\ParentMethodHelper;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<InvalidInheritDocTagRule>
+ */
+class InvalidInheritDocTagRuleTest extends RuleTestCase
+{
+
+	protected function getRule(): Rule
+	{
+		return new InvalidInheritDocTagRule(
+			self::getContainer()->getByType(Lexer::class),
+			self::getContainer()->getByType(PhpDocParser::class),
+			self::getContainer()->getByType(ParentMethodHelper::class),
+		);
+	}
+
+	public function testRule(): void
+	{
+		$this->analyse([__DIR__ . '/data/invalid-inherit-doc-tag.php'], [
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\ChildWithInlineInheritDoc::methodWithoutPhpDoc() refers to a parent method that does not have a PHPDoc.',
+				31,
+			],
+			[
+				'PHPDoc tag @inheritdoc on method InvalidInheritDocTag\ChildWithBlockInheritDoc::methodWithoutPhpDoc() refers to a parent method that does not have a PHPDoc.',
+				52,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\ClassWithoutParent::orphanedInheritDoc() does not override or implement any other method.',
+				73,
+			],
+			[
+				'PHPDoc tag @inheritdoc on method InvalidInheritDocTag\ClassWithoutParent::orphanedBlockInheritDoc() does not override or implement any other method.',
+				81,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\ImplementsInterface::interfaceMethodWithoutPhpDoc() refers to a parent method that does not have a PHPDoc.',
+				106,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\UsesTraitWithoutPhpDoc::traitMethodWithoutPhpDoc() does not override or implement any other method.',
+				216,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\UsesTraitWithPhpDoc::traitMethodWithPhpDoc() does not override or implement any other method.',
+				231,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\IssueExampleChild::f() refers to a parent method that does not have a PHPDoc.',
+				254,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\ChildOfPrivateParentMethod::privateMethod() does not override or implement any other method.',
+				280,
+			],
+			[
+				'PHPDoc tag {@inheritdoc} on method InvalidInheritDocTag\OrphanedInheritDocTrait::orphaned() does not override or implement any other method.',
+				293,
+			],
+		]);
+	}
+
+}