Add @group legacy deprecated scope resolver (#595)

* Add `@group legacy` deprecated scope resolver

* Ignore DeprecatedScope test data

* Try and workaround adding deprecation rules as dependency

* fix phpcs

* Make phpstan/phpstan-deprecation-rules a direct dependency

* Update README docs

Author: mglaman

README.md

@@ -49,19 +49,8 @@ parameters:
 
 ## Deprecation testing
 
-Add the deprecation rules to your Drupal project's dependencies
-
-```
-composer require --dev phpstan/phpstan-deprecation-rules
-```
-
-Edit your `phpstan.neon` to look like the following:
-
-```
-includes:
-	- vendor/mglaman/phpstan-drupal/extension.neon
-	- vendor/phpstan/phpstan-deprecation-rules/rules.neon
-```
+This project depends on `phpstan/phpstan-deprecation-rules` which adds deprecation rules. We provide Drupal-specific 
+deprecated scope resolvers.
 
 To only handle deprecation testing, use a `phpstan.neon` like this:
 
@@ -80,6 +69,22 @@ includes:
 	- vendor/phpstan/phpstan-deprecation-rules/rules.neon
 ```
 
+To disable deprecation rules while using `phpstan/extension-installer`, you can do the following:
+
+```json
+{
+  "extra": {
+    "phpstan/extension-installer": {
+      "ignore": [
+        "phpstan/phpstan-deprecation-rules"
+      ]
+    }
+  }
+}
+```
+
+See the `extension-installer` documentation for more information: https://github.com/phpstan/extension-installer#ignoring-a-particular-extension
+
 ## Adapting to your project
 
 ### Specifying your Drupal project's root

composer.json

@@ -13,6 +13,7 @@
         "php": "^7.4 || ^8.0",
         "symfony/finder": "~3.4.5 ||^4.2 || ^5.0 || ^6.0",
         "phpstan/phpstan": "^1.10.1",
+        "phpstan/phpstan-deprecation-rules": "^1.1.4",
         "symfony/yaml": "~3.4.5 || ^4.2|| ^5.0 || ^6.0",
         "webflo/drupal-finder": "^1.2"
     },
@@ -22,7 +23,6 @@
         "drupal/core-recommended": "^8.8@alpha || ^9.0",
         "drush/drush": "^9.6 || ^10.0 || ^11",
         "phpstan/extension-installer": "^1.1",
-        "phpstan/phpstan-deprecation-rules": "^1.0",
         "phpstan/phpstan-strict-rules": "^1.0",
         "phpunit/phpunit": "^6.5 || ^7.5 || ^8.0 || ^9",
         "slevomat/coding-standard": "^7.1",

extension.neon

@@ -298,3 +298,7 @@ services:
 		class: mglaman\PHPStanDrupal\Type\EntityQuery\AccessCheckTypeSpecifyingExtension
 		tags:
 			- phpstan.typeSpecifier.methodTypeSpecifyingExtension
+	-
+		class: mglaman\PHPStanDrupal\DeprecatedScope\GroupLegacyScope
+		tags:
+			- phpstan.deprecations.deprecatedScopeResolver

phpstan.neon

@@ -11,6 +11,7 @@ parameters:
 		-  tests/src/data/*.php
 		-  tests/src/Type/data/*.php
 		-  tests/src/Rules/data/*.php
+		-  tests/src/DeprecatedScope/data/*.php
 	dynamicConstantNames:
 		- Drupal::VERSION
 includes:

src/DeprecatedScope/GroupLegacyScope.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace mglaman\PHPStanDrupal\DeprecatedScope;
+
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Deprecations\DeprecatedScopeResolver;
+
+final class GroupLegacyScope implements DeprecatedScopeResolver
+{
+
+    public function isScopeDeprecated(Scope $scope): bool
+    {
+        if ($scope->isInClass()) {
+            $class = $scope->getClassReflection();
+            $phpDoc = $class->getResolvedPhpDoc();
+            if ($phpDoc !== null && strpos($phpDoc->getPhpDocString(), '@group legacy') !== false) {
+                return true;
+            }
+        }
+
+        $function = $scope->getFunction();
+        return $function !== null
+            && $function->getDocComment() !== null
+            && strpos($function->getDocComment(), '@group legacy') !== false;
+    }
+}

tests/src/DeprecatedScope/GlobalLegacyScopeTest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace mglaman\PHPStanDrupal\Tests\DeprecatedScope;
+
+use mglaman\PHPStanDrupal\Tests\DrupalRuleTestCase;
+use PHPStan\Rules\Deprecations\CallToDeprecatedFunctionRule;
+use PHPStan\Rules\Deprecations\DeprecatedScopeHelper;
+use PHPStan\Rules\Rule;
+
+final class GlobalLegacyScopeTest extends DrupalRuleTestCase {
+
+    protected function getRule(): Rule
+    {
+        // @phpstan-ignore-next-line
+        return new CallToDeprecatedFunctionRule(
+            self::createReflectionProvider(),
+            self::getContainer()->getByType(DeprecatedScopeHelper::class)
+        );
+    }
+
+    public function testCustomScope(): void
+    {
+        require_once __DIR__ . '/data/deprecated-data-definition.php';
+        $this->analyse(
+            [__DIR__ . '/data/group-legacy.php'],
+            [
+                [
+                    'Call to deprecated function Deprecated\deprecated_function().',
+                    21,
+                ],
+            ]
+        );
+    }
+}

tests/src/DeprecatedScope/data/deprecated-data-definition.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Deprecated;
+
+/**
+ * @deprecated
+ */
+function deprecated_function(): void {
+
+}

tests/src/DeprecatedScope/data/group-legacy.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace GroupLegacy;
+
+use function Deprecated\deprecated_function;
+
+/**
+ * @group legacy
+ */
+final class FooTest {
+
+    public function foo(): void {
+        deprecated_function();
+    }
+
+}
+
+final class BarTest {
+
+    public function bar(): void {
+        deprecated_function();
+    }
+
+    /**
+     * @group legacy
+     */
+    public function barNot(): void {
+        deprecated_function();
+    }
+
+}