Add Phpat usage provider

phpat registers architecture tests as services tagged "phpat.test" in the
PHPStan DI container, and at runtime invokes their public methods that are
either named `test*` or carry the #[TestRule] attribute (see
PHPat\Test\TestParser / TestExtractor). These invocations are invisible in
source code, so the methods were reported as dead.

PhpatUsageProvider resolves the tagged services from the container and marks
those test methods as used. Constructors of the test classes are already
covered by PhpStanUsageProvider (they are registered DIC services), so this
provider only handles the invoked methods.

Autoenabled when phpat/phpat is installed.

Closes #378

Co-Authored-By: Claude Code
Claude-Session: https://claude.ai/code/session_01WqA3SLHn3vQEytN5C1KCJj

Author: janedbal

README.md

@@ -99,6 +99,9 @@ parameters:
 #### PHPStan:
 - constructor calls for DIC services (rules, extensions, ...)
 
+#### PHPat:
+- architecture test methods (`test*` or `#[TestRule]`) of classes registered via the `phpat.test` service tag
+
 #### Nette:
 - `handleXxx`, `renderXxx`, `actionXxx`, `injectXxx`, `createComponentXxx`
 - `SmartObject` magic calls for `@property` annotations

composer-dependency-analyser.php

@@ -11,6 +11,7 @@
 $config = (new Configuration())
     ->ignoreErrorsOnPath(__DIR__ . '/src/Provider', [ErrorType::DEV_DEPENDENCY_IN_PROD]) // providers are designed that way
     ->ignoreErrorsOnExtensionAndPath('ext-simplexml', __DIR__ . '/src/Provider/SymfonyUsageProvider.php', [ErrorType::SHADOW_DEPENDENCY]) // guarded with extension_loaded()
+    ->addPathToExclude(__DIR__ . '/tests/Provider/data')
     ->addPathToExclude(__DIR__ . '/tests/Rule/data');
 
 return $config;

composer.json

@@ -29,6 +29,7 @@
         "nette/tester": "^2.4",
         "nette/utils": "^3.0 || ^4.0",
         "nikic/php-parser": "^5.4.0",
+        "phpat/phpat": "^0.12",
         "phpbench/phpbench": "^1.2",
         "phpstan/phpstan-phpunit": "^2.0.16",
         "phpstan/phpstan-strict-rules": "^2.0.10",
@@ -65,6 +66,7 @@
             "ShipMonk\\PHPStan\\DeadCode\\": "tests/"
         },
         "classmap": [
+            "tests/Provider/data",
             "tests/Rule/data"
         ]
     },

composer.lock

@@ -119,6 +119,13 @@ services:
         arguments:
             enabled: %shipmonkDeadCode.usageProviders.phpstan.enabled%
 
+    -
+        class: ShipMonk\PHPStan\DeadCode\Provider\PhpatUsageProvider
+        tags:
+            - shipmonk.deadCode.memberUsageProvider
+        arguments:
+            enabled: %shipmonkDeadCode.usageProviders.phpat.enabled%
+
     -
         class: ShipMonk\PHPStan\DeadCode\Provider\EloquentUsageProvider
         tags:
@@ -268,6 +275,8 @@ parameters:
                 enabled: true
             phpstan:
                 enabled: true
+            phpat:
+                enabled: null
             phpunit:
                 enabled: null
             phpbench:
@@ -354,6 +363,9 @@ parametersSchema:
             phpstan: structure([
                 enabled: bool()
             ])
+            phpat: structure([
+                enabled: schema(bool(), nullable())
+            ])
             phpunit: structure([
                 enabled: schema(bool(), nullable())
             ])

rules.neon

@@ -0,0 +1,93 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonk\PHPStan\DeadCode\Provider;
+
+use Composer\InstalledVersions;
+use PHPStan\DependencyInjection\Container;
+use ReflectionMethod;
+use function is_object;
+use function str_starts_with;
+
+/**
+ * phpat registers architecture tests as services tagged "phpat.test" in the PHPStan DIC.
+ * At runtime, phpat iterates those services and invokes their public methods that either
+ * carry the #[TestRule] attribute or whose name starts with "test" (see PHPat\Test\TestParser).
+ *
+ * Their constructors are already covered by PhpStanUsageProvider (registered DIC services),
+ * so this provider only marks the invoked test methods as used.
+ */
+final class PhpatUsageProvider extends ReflectionBasedMemberUsageProvider
+{
+
+    private const TEST_TAG = 'phpat.test';
+
+    private const TEST_RULE_ATTRIBUTE = 'PHPat\Test\Attributes\TestRule';
+
+    private readonly bool $enabled;
+
+    private readonly Container $container;
+
+    /**
+     * @var array<string, true>|null Set of class names tagged as phpat tests, lazily resolved.
+     */
+    private ?array $testClasses = null;
+
+    public function __construct(
+        ?bool $enabled,
+        Container $container,
+    )
+    {
+        $this->enabled = $enabled ?? InstalledVersions::isInstalled('phpat/phpat');
+        $this->container = $container;
+    }
+
+    public function shouldMarkMethodAsUsed(ReflectionMethod $method): ?VirtualUsageData
+    {
+        if (!$this->enabled) {
+            return null;
+        }
+
+        if (!$method->isPublic()) {
+            return null;
+        }
+
+        if (!isset($this->getTestClasses()[$method->getDeclaringClass()->getName()])) {
+            return null;
+        }
+
+        if (!$this->isTestMethod($method)) {
+            return null;
+        }
+
+        return VirtualUsageData::withNote('Architecture test method invoked by phpat');
+    }
+
+    private function isTestMethod(ReflectionMethod $method): bool
+    {
+        if ($method->getAttributes(self::TEST_RULE_ATTRIBUTE) !== []) {
+            return true;
+        }
+
+        // phpat invokes every public method whose name starts with "test"
+        return str_starts_with($method->getName(), 'test');
+    }
+
+    /**
+     * @return array<string, true>
+     */
+    private function getTestClasses(): array
+    {
+        if ($this->testClasses === null) {
+            $this->testClasses = [];
+
+            foreach ($this->container->getServicesByTag(self::TEST_TAG) as $service) {
+                if (is_object($service)) {
+                    $this->testClasses[$service::class] = true;
+                }
+            }
+        }
+
+        return $this->testClasses;
+    }
+
+}

src/Provider/PhpatUsageProvider.php

@@ -19,6 +19,7 @@ public function testAutodetectComposerDevPaths(): void
 
         self::assertSame([
             realpath(__DIR__ . '/../../tests'),
+            realpath(__DIR__ . '/../../tests/Provider/data'),
             realpath(__DIR__ . '/../../tests/Rule/data'),
         ], $devPathsPropertyReflection->getValue($excluder));
     }

tests/Excluder/TestsUsageExcluderTest.php

@@ -0,0 +1,79 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonk\PHPStan\DeadCode\Provider;
+
+use PhpatTestFixture\NotRegisteredArchitectureTest;
+use PhpatTestFixture\RegisteredArchitectureTest;
+use PHPStan\DependencyInjection\Container;
+use PHPStan\Testing\PHPStanTestCase;
+use ReflectionMethod;
+
+final class PhpatUsageProviderTest extends PHPStanTestCase
+{
+
+    public function testTestMethodsOfRegisteredTestsAreMarkedUsed(): void
+    {
+        $provider = $this->createProvider(enabled: true, registeredTests: [new RegisteredArchitectureTest()]);
+
+        // invoked by phpat: test-prefixed name
+        self::assertInstanceOf(VirtualUsageData::class, $this->shouldMarkMethodAsUsed($provider, RegisteredArchitectureTest::class, 'testSrcDoesNotDependOnTests'));
+
+        // invoked by phpat: #[TestRule] attribute regardless of name
+        self::assertInstanceOf(VirtualUsageData::class, $this->shouldMarkMethodAsUsed($provider, RegisteredArchitectureTest::class, 'customNamedRule'));
+    }
+
+    public function testNonTestMethodsAreNotMarkedUsed(): void
+    {
+        $provider = $this->createProvider(enabled: true, registeredTests: [new RegisteredArchitectureTest()]);
+
+        // public, but neither test-prefixed nor #[TestRule]
+        self::assertNull($this->shouldMarkMethodAsUsed($provider, RegisteredArchitectureTest::class, 'helperNotInvokedByPhpat'));
+
+        // phpat only invokes public methods
+        self::assertNull($this->shouldMarkMethodAsUsed($provider, RegisteredArchitectureTest::class, 'testPrivate'));
+    }
+
+    public function testMethodsOfUnregisteredClassesAreNotMarkedUsed(): void
+    {
+        // only RegisteredArchitectureTest is tagged phpat.test
+        $provider = $this->createProvider(enabled: true, registeredTests: [new RegisteredArchitectureTest()]);
+
+        self::assertNull($this->shouldMarkMethodAsUsed($provider, NotRegisteredArchitectureTest::class, 'testSomething'));
+    }
+
+    public function testDisabledProviderMarksNothing(): void
+    {
+        $provider = $this->createProvider(enabled: false, registeredTests: [new RegisteredArchitectureTest()]);
+
+        self::assertNull($this->shouldMarkMethodAsUsed($provider, RegisteredArchitectureTest::class, 'testSrcDoesNotDependOnTests'));
+    }
+
+    private function shouldMarkMethodAsUsed(
+        PhpatUsageProvider $provider,
+        string $class,
+        string $method,
+    ): mixed
+    {
+        $providerMethod = new ReflectionMethod($provider, 'shouldMarkMethodAsUsed');
+
+        return $providerMethod->invoke($provider, new ReflectionMethod($class, $method));
+    }
+
+    /**
+     * @param list<object> $registeredTests
+     */
+    private function createProvider(
+        bool $enabled,
+        array $registeredTests,
+    ): PhpatUsageProvider
+    {
+        $container = $this->createMock(Container::class);
+        $container->method('getServicesByTag')
+            ->willReturnCallback(
+                static fn (string $tag): array => $tag === 'phpat.test' ? $registeredTests : [],
+            );
+
+        return new PhpatUsageProvider($enabled, $container);
+    }
+
+}

tests/Provider/PhpatUsageProviderTest.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types = 1);
+
+namespace PhpatTestFixture;
+
+use PHPat\Test\Attributes\TestRule;
+
+class RegisteredArchitectureTest
+{
+
+    public function testSrcDoesNotDependOnTests(): void
+    {
+    }
+
+    #[TestRule]
+    public function customNamedRule(): void
+    {
+    }
+
+    public function helperNotInvokedByPhpat(): void
+    {
+    }
+
+    private function testPrivate(): void
+    {
+    }
+
+}
+
+class NotRegisteredArchitectureTest
+{
+
+    public function testSomething(): void
+    {
+    }
+
+}

tests/Provider/data/phpat.php

@@ -56,6 +56,7 @@
 use ShipMonk\PHPStan\DeadCode\Provider\MemberUsageProvider;
 use ShipMonk\PHPStan\DeadCode\Provider\NetteTesterUsageProvider;
 use ShipMonk\PHPStan\DeadCode\Provider\NetteUsageProvider;
+use ShipMonk\PHPStan\DeadCode\Provider\PhpatUsageProvider;
 use ShipMonk\PHPStan\DeadCode\Provider\PhpBenchUsageProvider;
 use ShipMonk\PHPStan\DeadCode\Provider\PhpStanUsageProvider;
 use ShipMonk\PHPStan\DeadCode\Provider\PhpUnitUsageProvider;
@@ -1224,6 +1225,10 @@ private function getMemberUsageProviders(): array
                 $this->providersEnabled,
                 $this->createPhpStanContainerMock(),
             ),
+            new PhpatUsageProvider(
+                $this->providersEnabled,
+                $this->createPhpStanContainerMock(),
+            ),
             new EloquentUsageProvider(
                 $this->providersEnabled,
             ),
@@ -1368,6 +1373,8 @@ static function (string $type): array {
                     return [];
                 },
             );
+        $mock->method('getServicesByTag')
+            ->willReturn([]);
         return $mock;
     }