Bleeding edge - Backward Compatible PHPStan API rules

conf/bleedingEdge.neon

@@ -18,3 +18,4 @@ parameters:
 		skipCheckGenericClasses: []
 		rememberFunctionValues: true
 		preciseExceptionTracking: true
+		apiRules: true

conf/config.level0.neon

@@ -3,6 +3,8 @@ parameters:
 	missingClosureNativeReturnCheckObjectTypehint: false
 
 conditionalTags:
+	PHPStan\Rules\Api\ApiInstantiationRule:
+		phpstan.rules.rule: %featureToggles.apiRules%
 	PHPStan\Rules\Functions\ClosureUsesThisRule:
 		phpstan.rules.rule: %featureToggles.closureUsesThis%
 	PHPStan\Rules\Missing\MissingClosureNativeReturnTypehintRule:
@@ -58,6 +60,9 @@ rules:
 	- PHPStan\Rules\Variables\UnsetRule
 
 services:
+	-
+		class: PHPStan\Rules\Api\ApiInstantiationRule
+
 	-
 		class: PHPStan\Rules\Classes\ExistingClassInInstanceOfRule
 		tags:

conf/config.neon

@@ -40,6 +40,7 @@ parameters:
 			- RecursiveIterator
 		rememberFunctionValues: false
 		preciseExceptionTracking: false
+		apiRules: false
 	fileExtensions:
 		- php
 	checkAlwaysTrueCheckTypeFunctionCall: false
@@ -208,7 +209,8 @@ parametersSchema:
 		objectFromNewClass: bool(),
 		skipCheckGenericClasses: listOf(string()),
 		rememberFunctionValues: bool(),
-		preciseExceptionTracking: bool()
+		preciseExceptionTracking: bool(),
+		apiRules: bool()
 	])
 	fileExtensions: listOf(string())
 	checkAlwaysTrueCheckTypeFunctionCall: bool()
@@ -725,6 +727,9 @@ services:
 		class: PHPStan\Reflection\SignatureMap\SignatureMapProvider
 		factory: @PHPStan\Reflection\SignatureMap\SignatureMapProviderFactory::create()
 
+	-
+		class: PHPStan\Rules\Api\ApiRuleHelper
+
 	-
 		class: PHPStan\Rules\AttributesCheck
 

src/Rules/Api/ApiInstantiationRule.php

@@ -0,0 +1,80 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Api;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Reflection\ReflectionProvider;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+
+/**
+ * @implements Rule<Node\Expr\New_>
+ */
+class ApiInstantiationRule implements Rule
+{
+
+	private ApiRuleHelper $apiRuleHelper;
+
+	private ReflectionProvider $reflectionProvider;
+
+	public function __construct(
+		ApiRuleHelper $apiRuleHelper,
+		ReflectionProvider $reflectionProvider
+	)
+	{
+		$this->apiRuleHelper = $apiRuleHelper;
+		$this->reflectionProvider = $reflectionProvider;
+	}
+
+	public function getNodeType(): string
+	{
+		return Node\Expr\New_::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if ($this->apiRuleHelper->isInPhpStanNamespace($scope->getNamespace())) {
+			return [];
+		}
+
+		if (!$node->class instanceof Node\Name) {
+			return [];
+		}
+
+		$className = $scope->resolveName($node->class);
+		if (!$this->reflectionProvider->hasClass($className)) {
+			return [];
+		}
+
+		$classReflection = $this->reflectionProvider->getClass($className);
+		if (!$this->apiRuleHelper->isInPhpStanNamespace($classReflection->getName())) {
+			return [];
+		}
+
+		$ruleError = RuleErrorBuilder::message(sprintf(
+			'Creating new %s is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
+			$classReflection->getDisplayName()
+		))->tip(sprintf(
+			"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'
+		))->build();
+
+		if (!$classReflection->hasConstructor()) {
+			return [$ruleError];
+		}
+
+		$constructor = $classReflection->getConstructor();
+		$docComment = $constructor->getDocComment();
+		if ($docComment === null) {
+			return [$ruleError];
+		}
+
+		if (strpos($docComment, '@api') === false) {
+			return [$ruleError];
+		}
+
+		return [];
+	}
+
+}

src/Rules/Api/ApiRuleHelper.php

@@ -0,0 +1,21 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Api;
+
+class ApiRuleHelper
+{
+
+	public function isInPhpStanNamespace(?string $namespace): bool
+	{
+		if ($namespace === null) {
+			return false;
+		}
+
+		if (strtolower($namespace) === 'phpstan') {
+			return true;
+		}
+
+		return stripos($namespace, 'PHPStan\\') === 0;
+	}
+
+}

src/Type/Constant/ConstantIntegerType.php

@@ -21,8 +21,10 @@ class ConstantIntegerType extends IntegerType implements ConstantScalarType
 
 	private int $value;
 
+	/** @api */
 	public function __construct(int $value)
 	{
+		parent::__construct();
 		$this->value = $value;
 	}
 

src/Type/Generic/TemplateIntegerType.php

@@ -21,6 +21,7 @@ public function __construct(
 		IntegerType $bound
 	)
 	{
+		parent::__construct();
 		$this->scope = $scope;
 		$this->strategy = $templateTypeStrategy;
 		$this->variance = $templateTypeVariance;

src/Type/IntegerRangeType.php

@@ -15,6 +15,7 @@ class IntegerRangeType extends IntegerType implements CompoundType
 
 	private function __construct(?int $min, ?int $max)
 	{
+		parent::__construct();
 		assert($min === null || $max === null || $min <= $max);
 		assert($min !== null || $max !== null);
 

src/Type/IntegerType.php

@@ -24,6 +24,11 @@ class IntegerType implements Type
 	use UndecidedComparisonTypeTrait;
 	use NonGenericTypeTrait;
 
+	/** @api */
+	public function __construct()
+	{
+	}
+
 	public function describe(VerbosityLevel $level): string
 	{
 		return 'int';

tests/PHPStan/Rules/Api/ApiInstantiationRuleTest.php

@@ -0,0 +1,46 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Api;
+
+use PHPStan\Testing\RuleTestCase;
+
+/**
+ * @extends RuleTestCase<ApiInstantiationRule>
+ */
+class ApiInstantiationRuleTest extends RuleTestCase
+{
+
+	protected function getRule(): \PHPStan\Rules\Rule
+	{
+		return new ApiInstantiationRule(
+			new ApiRuleHelper(),
+			$this->createReflectionProvider()
+		);
+	}
+
+	public function testRuleInPhpStan(): void
+	{
+		$this->analyse([__DIR__ . '/data/new-in-phpstan.php'], []);
+	}
+
+	public function testRuleOutOfPhpStan(): void
+	{
+		$tip = sprintf(
+			"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'
+		);
+		$this->analyse([__DIR__ . '/data/new-out-of-phpstan.php'], [
+			[
+				'Creating new PHPStan\Type\FileTypeMapper is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
+				17,
+				$tip,
+			],
+			[
+				'Creating new PHPStan\DependencyInjection\NeonAdapter is not covered by backward compatibility promise. The class might change in a minor PHPStan version.',
+				18,
+				$tip,
+			],
+		]);
+	}
+
+}

tests/PHPStan/Rules/Api/ApiRuleHelperTest.php

@@ -0,0 +1,59 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Api;
+
+use PHPUnit\Framework\TestCase;
+
+class ApiRuleHelperTest extends TestCase
+{
+
+	public function dataIsInPhpStanNamespace(): array
+	{
+		return [
+			[
+				null,
+				false,
+			],
+			[
+				'PHPStan',
+				true,
+			],
+			[
+				'PhpStan',
+				true,
+			],
+			[
+				'PHPStan\\Foo',
+				true,
+			],
+			[
+				'PhpStan\\Foo',
+				true,
+			],
+			[
+				'App\\Foo',
+				false,
+			],
+			[
+				'PHPStanWorkshop',
+				false,
+			],
+			[
+				'PHPStanWorkshop\\',
+				false,
+			],
+		];
+	}
+
+	/**
+	 * @dataProvider dataIsInPhpStanNamespace
+	 * @param string|null $namespace
+	 * @param bool $expected
+	 */
+	public function testIsInPhpStanNamespace(?string $namespace, bool $expected): void
+	{
+		$rule = new ApiRuleHelper();
+		$this->assertSame($expected, $rule->isInPhpStanNamespace($namespace));
+	}
+
+}

tests/PHPStan/Rules/Api/data/new-in-phpstan.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace PHPStan\Foo;
+
+use PHPStan\DependencyInjection\NeonAdapter;
+use PHPStan\Type\FileTypeMapper;
+use PHPStan\Type\IntegerType;
+
+class Foo
+{
+
+	public function doFoo(): void
+	{
+		new Nonexistent();
+		new Bar();
+		new IntegerType();
+		new FileTypeMapper();
+		new NeonAdapter();
+	}
+
+}
+
+class Bar
+{
+
+}

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

@@ -0,0 +1,26 @@
+<?php
+
+namespace App;
+
+use PHPStan\DependencyInjection\NeonAdapter;
+use PHPStan\Type\FileTypeMapper;
+use PHPStan\Type\IntegerType;
+
+class Foo
+{
+
+	public function doFoo(): void
+	{
+		new Nonexistent();
+		new Bar();
+		new IntegerType();
+		new FileTypeMapper(); // error - has constructor
+		new NeonAdapter(); // error - does not have a constructor
+	}
+
+}
+
+class Bar
+{
+
+}