ApiInstanceofRule - report "maybe" on @api-covered classes

Author: ondrejmirtes

src/Rules/Api/ApiInstanceofRule.php

@@ -4,9 +4,12 @@
 
 use PhpParser\Node;
 use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ClassReflection;
 use PHPStan\Reflection\ReflectionProvider;
 use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleError;
 use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\Constant\ConstantBooleanType;
 use function count;
 use function sprintf;
 
@@ -61,11 +64,32 @@ public function processNode(Node $node, Scope $scope): array
 		foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
 			$apiTags = $phpDocNode->getTagsByName('@api');
 			if (count($apiTags) > 0) {
-				return [];
+				return $this->processCoveredClass($node, $scope, $classReflection);
 			}
 		}
 
 		return [$ruleError];
 	}
 
+	/**
+	 * @return RuleError[]
+	 */
+	private function processCoveredClass(Node\Expr\Instanceof_ $node, Scope $scope, ClassReflection $classReflection): array
+	{
+		$instanceofType = $scope->getType($node);
+		if ($instanceofType instanceof ConstantBooleanType) {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				'Although %s is covered by backward compatibility promise, this instanceof assumption might break because it\'s not guaranteed to always stay the same.',
+				$classReflection->getDisplayName(),
+			))->tip(sprintf(
+				"In case of questions how to solve this correctly, open a discussion:\n   %s\n\n   See also:\n   https://phpstan.org/developing-extensions/backward-compatibility-promise",
+				'https://github.com/phpstan/phpstan/discussions',
+			))->build(),
+		];
+	}
+
 }

tests/PHPStan/Rules/Api/ApiInstanceofRuleTest.php

@@ -28,13 +28,27 @@ public function testRuleOutOfPhpStan(): void
 			"If you think it should be covered by backward compatibility promise, open a discussion:\n   %s\n\n   See also:\n   https://phpstan.org/developing-extensions/backward-compatibility-promise",
 			'https://github.com/phpstan/phpstan/discussions',
 		);
+		$instanceofTip = sprintf(
+			"In case of questions how to solve this correctly, open a discussion:\n   %s\n\n   See also:\n   https://phpstan.org/developing-extensions/backward-compatibility-promise",
+			'https://github.com/phpstan/phpstan/discussions',
+		);
 
 		$this->analyse([__DIR__ . '/data/instanceof-out-of-phpstan.php'], [
+			[
+				'Although PHPStan\Reflection\ClassReflection is covered by backward compatibility promise, this instanceof assumption might break because it\'s not guaranteed to always stay the same.',
+				13,
+				$instanceofTip,
+			],
 			[
 				'Asking about instanceof PHPStan\Reflection\BetterReflection\SourceLocator\AutoloadSourceLocator is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
 				17,
 				$tip,
 			],
+			[
+				'Although PHPStan\Reflection\ClassReflection is covered by backward compatibility promise, this instanceof assumption might break because it\'s not guaranteed to always stay the same.',
+				37,
+				$instanceofTip,
+			],
 		]);
 	}
 

tests/PHPStan/Rules/Api/data/instanceof-out-of-phpstan.php

@@ -20,3 +20,23 @@ public function doFoo(object $o): void
 	}
 
 }
+
+class Bar
+{
+
+	public function doBar(ClassReflection $classReflection, object $o): void
+	{
+		if ($classReflection instanceof ClassReflection) { // yes - do not report
+
+		}
+
+		if ($classReflection instanceof ClassReflection) { // no - do not report
+
+		}
+
+		if ($o instanceof ClassReflection) { // maybe - report
+
+		}
+	}
+
+}