[path] Complete runtime-aware binary fallbacks for remaining commands (#297)

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Keep global `dev-tools:sync` runs machine-independent by removing only deprecated DevTools-managed Composer GrumPHP default-path metadata while wiring packaged Git hooks to prefer a project-local `grumphp.yml` and otherwise use the active packaged DevTools config path resolved at sync time (#288)
+- Complete global runtime binary fallback support for phpdoc, phpunit, and phpmetrics commands (#297)
 
 ## [1.24.2] - 2026-04-30
 

src/Console/Command/DocsCommand.php

@@ -25,6 +25,7 @@
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use Twig\Environment;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
@@ -167,7 +168,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $processBuilder = $processBuilder->withArgument('--no-progress');
         }
 
-        $phpdoc = $processBuilder->build('vendor/bin/phpdoc');
+        $phpdoc = $processBuilder->build([DevToolsPathResolver::getPreferredToolBinaryPath('phpdoc')]);
 
         $this->processQueue->add(process: $phpdoc, label: 'Generating API Docs with phpDocumentor');
 

src/Console/Command/MetricsCommand.php

@@ -21,6 +21,7 @@
 
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Console\Input\HasJsonOption;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
@@ -45,9 +46,9 @@ final class MetricsCommand extends Command
     use LogsCommandResults;
 
     /**
-     * @var string the bundled PhpMetrics binary path relative to the consumer root
+     * @var string the PhpMetrics binary name resolved through the runtime-aware tooling lookup
      */
-    private const string BINARY = 'vendor/bin/phpmetrics';
+    private const string BINARY = 'phpmetrics';
 
     /**
      * @var int the PHP error reporting mask that suppresses deprecations emitted by PhpMetrics internals
@@ -161,7 +162,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                     \PHP_BINARY,
                     '-derror_reporting=' . self::PHP_ERROR_REPORTING,
                     '-ddefault_socket_timeout=' . self::PHP_DEFAULT_SOCKET_TIMEOUT,
-                    self::BINARY,
+                    DevToolsPathResolver::getPreferredToolBinaryPath(self::BINARY),
                 ]),
             label: 'Generating Metrics with PhpMetrics',
         );

src/Console/Command/TestsCommand.php

@@ -24,6 +24,7 @@
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use FastForward\DevTools\Composer\Json\ComposerJsonInterface;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\PhpUnit\Bootstrap\BootstrapShimGenerator;
 use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoaderInterface;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
@@ -209,7 +210,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $this->processQueue->add(
             process: $processBuilder
                 ->withArgument($input->getArgument('path'))
-                ->build('vendor/bin/phpunit'),
+                ->build([DevToolsPathResolver::getPreferredToolBinaryPath('phpunit')]),
             label: 'Running PHPUnit Tests',
         );
 

src/Console/Command/WikiCommand.php

@@ -25,6 +25,7 @@
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use FastForward\DevTools\Git\GitClientInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
@@ -157,7 +158,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         $this->processQueue->add(
-            process: $processBuilder->build('vendor/bin/phpdoc'),
+            process: $processBuilder->build([DevToolsPathResolver::getPreferredToolBinaryPath('phpdoc')]),
             label: 'Generating Wiki with phpDocumentor',
         );
 

tests/Console/Command/DocsCommandTest.php

@@ -23,9 +23,11 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Console\Command\DocsCommand;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -43,7 +45,9 @@
 use Twig\Environment;
 
 #[CoversClass(DocsCommand::class)]
+#[UsesClass(DevToolsPathResolver::class)]
 #[UsesClass(ManagedWorkspace::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class DocsCommandTest extends TestCase
 {
@@ -133,7 +137,7 @@ protected function setUp(): void
         $this->processBuilder->withArgument(Argument::any(), Argument::any())->willReturn(
             $this->processBuilder->reveal()
         );
-        $this->processBuilder->build('vendor/bin/phpdoc')
+        $this->processBuilder->build([DevToolsPathResolver::getPreferredToolBinaryPath('phpdoc')])
             ->willReturn($this->process->reveal());
 
         $this->command = new DocsCommand(

tests/Console/Command/MetricsCommandTest.php

@@ -21,9 +21,11 @@
 
 use FastForward\DevTools\Console\Command\MetricsCommand;
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -42,7 +44,9 @@
 use function Safe\putenv;
 
 #[CoversClass(MetricsCommand::class)]
+#[UsesClass(DevToolsPathResolver::class)]
 #[UsesClass(ManagedWorkspace::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class MetricsCommandTest extends TestCase
 {
@@ -99,7 +103,8 @@ protected function setUp(): void
         $this->processBuilder->build(Argument::that(static fn(array $command): bool => \PHP_BINARY === $command[0]
             && str_starts_with((string) $command[1], '-derror_reporting=')
             && '-ddefault_socket_timeout=1' === $command[2]
-            && 'vendor/bin/phpmetrics' === $command[3]))->willReturn($this->process->reveal());
+            && DevToolsPathResolver::getPreferredToolBinaryPath('phpmetrics') === $command[3]))
+            ->willReturn($this->process->reveal());
         $this->command = new MetricsCommand(
             $this->processBuilder->reveal(),
             $this->processQueue->reveal(),

tests/Console/Command/TestsCommandTest.php

@@ -30,6 +30,7 @@
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
 use FastForward\DevTools\Path\DevToolsPathResolver;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -54,6 +55,7 @@
 #[UsesClass(DevToolsPathResolver::class)]
 #[UsesClass(ProcessBuilder::class)]
 #[UsesClass(ManagedWorkspace::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class TestsCommandTest extends TestCase
 {
@@ -147,6 +149,9 @@ public function executeWillRunPhpUnitProcessWithConfigFile(): void
             ) && str_contains(
                 $process->getCommandLine(),
                 '--bootstrap=' . $generatedBootstrapPath,
+            ) && str_contains(
+                $process->getCommandLine(),
+                DevToolsPathResolver::getPreferredToolBinaryPath('phpunit'),
             ) && str_contains($process->getCommandLine(), '--cache-result') && str_contains(
                 $process->getCommandLine(),
                 '--cache-directory=' . getcwd() . '/.dev-tools/cache/phpunit',

tests/Console/Command/WikiCommandTest.php

@@ -24,9 +24,11 @@
 use FastForward\DevTools\Console\Command\WikiCommand;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use FastForward\DevTools\Git\GitClientInterface;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use FastForward\DevTools\Path\ManagedWorkspace;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -42,7 +44,9 @@
 use Symfony\Component\Process\Process;
 
 #[CoversClass(WikiCommand::class)]
+#[UsesClass(DevToolsPathResolver::class)]
 #[UsesClass(ManagedWorkspace::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class WikiCommandTest extends TestCase
 {
@@ -107,7 +111,8 @@ protected function setUp(): void
         $this->processBuilder->withArgument(Argument::any(), Argument::any())->willReturn(
             $this->processBuilder->reveal()
         );
-        $this->processBuilder->build(Argument::any())->willReturn($this->process->reveal());
+        $this->processBuilder->build([DevToolsPathResolver::getPreferredToolBinaryPath('phpdoc')])
+            ->willReturn($this->process->reveal());
 
         $this->command = new WikiCommand(
             $this->processBuilder->reveal(),

tests/Path/DevToolsPathResolverTest.php

@@ -112,6 +112,9 @@ public function itWillResolveRuntimeAutoloadPathsForRepositoryAndDependencyInsta
      */
     #[Test]
     #[TestWith(['php-cs-fixer'])]
+    #[TestWith(['phpdoc'])]
+    #[TestWith(['phpmetrics'])]
+    #[TestWith(['phpunit'])]
     #[TestWith(['rector'])]
     #[TestWith(['ecs'])]
     #[TestWith(['jack'])]