[path] Add runtime-aware tooling binary fallback

Author: coisa

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- Prefer project-local tooling binaries when available and fall back to the active DevTools runtime for `php-cs-fixer`, Rector, ECS, Jack, and Composer Dependency Analyser during global `dev-tools` runs (#292)
+
 ## [1.24.1] - 2026-04-30
 
 ### Fixed

src/Console/Command/CodeStyleCommand.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 Psr\Log\LoggerInterface;
@@ -148,7 +149,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $processBuilder = $processBuilder->withArgument('--fix');
         }
 
-        $ecs = $processBuilder->build('vendor/bin/ecs');
+        $ecs = $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('ecs'));
 
         $this->processQueue->add(process: $composerUpdate, label: 'Refreshing Composer Lock');
         $this->processQueue->add(

src/Console/Command/DependenciesCommand.php

@@ -22,6 +22,7 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use FastForward\DevTools\Config\ComposerDependencyAnalyserConfig;
+use FastForward\DevTools\Path\DevToolsPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use InvalidArgumentException;
@@ -199,7 +200,9 @@ private function getComposerDependencyAnalyserCommand(InputInterface $input): Pr
         }
 
         $showShadowDependencies = (bool) $input->getOption('show-shadow-dependencies');
-        $process = $processBuilder->build('vendor/bin/composer-dependency-analyser');
+        $process = $processBuilder->build(
+            DevToolsPathResolver::getPreferredToolBinaryPath('composer-dependency-analyser')
+        );
         $process->setEnv([
             ComposerDependencyAnalyserConfig::ENV_SHOW_SHADOW_DEPENDENCIES => $showShadowDependencies ? '1' : '0',
         ]);
@@ -217,7 +220,7 @@ private function getComposerDependencyAnalyserCommand(InputInterface $input): Pr
      */
     private function getJackBreakpointCommand(InputInterface $input, int $maximumOutdated): Process
     {
-        $command = 'vendor/bin/jack breakpoint';
+        $command = DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' breakpoint';
 
         if ((bool) $input->getOption('dev')) {
             $command .= ' --dev';
@@ -239,7 +242,7 @@ private function getJackBreakpointCommand(InputInterface $input, int $maximumOut
      */
     private function getOpenVersionsCommand(InputInterface $input): Process
     {
-        $command = 'vendor/bin/jack open-versions';
+        $command = DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' open-versions';
 
         if ((bool) $input->getOption('dev')) {
             $command .= ' --dev';
@@ -261,7 +264,7 @@ private function getOpenVersionsCommand(InputInterface $input): Process
      */
     private function getRaiseToInstalledCommand(InputInterface $input): Process
     {
-        $command = 'vendor/bin/jack raise-to-installed';
+        $command = DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' raise-to-installed';
 
         if ((bool) $input->getOption('dev')) {
             $command .= ' --dev';

src/Console/Command/PhpDocCommand.php

@@ -24,6 +24,7 @@
 use FastForward\DevTools\Console\Input\HasCacheOption;
 use FastForward\DevTools\Console\Input\HasJsonOption;
 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;
@@ -185,7 +186,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $processBuilder = $processBuilder->withArgument('--dry-run');
         }
 
-        $phpCsFixer = $processBuilder->build('vendor/bin/php-cs-fixer fix');
+        $phpCsFixer = $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('php-cs-fixer') . ' fix');
 
         $processBuilder = $this->processBuilder
             ->withArgument('--ansi')
@@ -206,7 +207,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $processBuilder = $processBuilder->withArgument('--dry-run');
         }
 
-        $rector = $processBuilder->build('vendor/bin/rector process');
+        $rector = $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('rector') . ' process');
 
         $this->processQueue->add(process: $phpCsFixer, label: 'Fixing PHPDoc File Headers with PHP-CS-Fixer');
         $this->processQueue->add(process: $rector, label: 'Adding Missing PHPDoc with Rector');

src/Console/Command/RefactorCommand.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 Psr\Log\LoggerInterface;
@@ -143,7 +144,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         $this->processQueue->add(
-            process: $processBuilder->build('vendor/bin/rector'),
+            process: $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('rector')),
             label: 'Refactoring Code with Rector',
         );
 

src/Path/DevToolsPathResolver.php

@@ -108,6 +108,52 @@ public static function getRuntimeAutoloadPath(string $packagePath = ''): string
         return Path::join($packagePath, 'vendor', 'autoload.php');
     }
 
+    /**
+     * Returns the active Composer runtime binary path for the current DevTools installation mode.
+     *
+     * Repository checkouts use the package-local `vendor/bin/<binary>`, while
+     * dependency installs resolve binaries from the active Composer vendor root.
+     *
+     * @param string $binary the binary name relative to `vendor/bin`
+     * @param string $packagePath an optional package root path; defaults to the current package root
+     */
+    public static function getRuntimeToolBinaryPath(string $binary, string $packagePath = ''): string
+    {
+        $packagePath = Path::canonicalize('' === $packagePath ? self::getPackagePath() : $packagePath);
+
+        if (self::isInstalledAsDependency($packagePath)) {
+            return Path::canonicalize(Path::join($packagePath, '..', '..', 'bin', $binary));
+        }
+
+        return Path::join($packagePath, 'vendor', 'bin', $binary);
+    }
+
+    /**
+     * Returns the preferred tooling binary path for the active project and DevTools runtime.
+     *
+     * Consumer projects SHOULD take precedence when they provide a local
+     * `vendor/bin/<binary>` entry. If the binary is absent locally, the method
+     * MUST fall back to the active DevTools runtime binary path.
+     *
+     * @param string $binary the binary name relative to `vendor/bin`
+     * @param string $projectPath an optional project root path; defaults to the working project root
+     * @param string $packagePath an optional package root path; defaults to the current package root
+     */
+    public static function getPreferredToolBinaryPath(
+        string $binary,
+        string $projectPath = '',
+        string $packagePath = '',
+    ): string {
+        $projectPath = '' === $projectPath ? WorkingProjectPathResolver::getProjectPath() : $projectPath;
+        $projectBinaryPath = Path::join($projectPath, 'vendor', 'bin', $binary);
+
+        if (file_exists($projectBinaryPath)) {
+            return $projectBinaryPath;
+        }
+
+        return self::getRuntimeToolBinaryPath($binary, $packagePath);
+    }
+
     /**
      * Detects whether the provided path belongs to an installed vendor copy of DevTools.
      *

tests/Console/Command/CodeStyleCommandTest.php

@@ -21,10 +21,13 @@
 
 use FastForward\DevTools\Console\Command\CodeStyleCommand;
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
+use FastForward\DevTools\Path\DevToolsPathResolver;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\Attributes\UsesTrait;
 use PHPUnit\Framework\TestCase;
 use Prophecy\Argument;
@@ -39,6 +42,8 @@
 use Symfony\Component\Process\Process;
 
 #[CoversClass(CodeStyleCommand::class)]
+#[UsesClass(DevToolsPathResolver::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class CodeStyleCommandTest extends TestCase
 {
@@ -111,6 +116,9 @@ protected function setUp(): void
     #[Test]
     public function executeWillReturnSuccessWhenProcessQueueSucceeds(): void
     {
+        $this->processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('ecs'))
+            ->willReturn($this->process->reveal())
+            ->shouldBeCalled();
         $this->processQueue->run(Argument::type('object'))
             ->willReturn(CodeStyleCommand::SUCCESS)
             ->shouldBeCalled();

tests/Console/Command/DependenciesCommandTest.php

@@ -23,6 +23,7 @@
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Config\ComposerDependencyAnalyserConfig;
 use FastForward\DevTools\Path\DevToolsPathResolver;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use FastForward\DevTools\Process\ProcessBuilder;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
@@ -44,6 +45,7 @@
 
 #[CoversClass(DependenciesCommand::class)]
 #[UsesClass(DevToolsPathResolver::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesClass(ProcessBuilder::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class DependenciesCommandTest extends TestCase
@@ -225,7 +227,9 @@ private function assertComposerDependencyAnalyserEnvironment(string $expectedVal
         $processBuilder->withArgument('--config', '/app/composer-dependency-analyser.php')
             ->willReturn($configuredProcessBuilder->reveal())
             ->shouldBeCalledOnce();
-        $configuredProcessBuilder->build('vendor/bin/composer-dependency-analyser')
+        $configuredProcessBuilder->build(
+            DevToolsPathResolver::getPreferredToolBinaryPath('composer-dependency-analyser')
+        )
             ->willReturn($process->reveal())
             ->shouldBeCalledOnce();
         $process->setEnv([
@@ -236,4 +240,75 @@ private function assertComposerDependencyAnalyserEnvironment(string $expectedVal
         (new ReflectionMethod($command, 'getComposerDependencyAnalyserCommand'))
             ->invoke($command, $this->input->reveal());
     }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function jackBreakpointProcessWillUseTheResolvedJackBinary(): void
+    {
+        $processBuilder = $this->prophesize(ProcessBuilderInterface::class);
+        $process = $this->prophesize(Process::class);
+        $command = new DependenciesCommand(
+            $processBuilder->reveal(),
+            $this->processQueue->reveal(),
+            $this->fileLocator->reveal(),
+            $this->logger->reveal(),
+        );
+
+        $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' breakpoint --limit 5')
+            ->willReturn($process->reveal())
+            ->shouldBeCalledOnce();
+
+        (new ReflectionMethod($command, 'getJackBreakpointCommand'))
+            ->invoke($command, $this->input->reveal(), 5);
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function openVersionsProcessWillUseTheResolvedJackBinary(): void
+    {
+        $processBuilder = $this->prophesize(ProcessBuilderInterface::class);
+        $process = $this->prophesize(Process::class);
+        $command = new DependenciesCommand(
+            $processBuilder->reveal(),
+            $this->processQueue->reveal(),
+            $this->fileLocator->reveal(),
+            $this->logger->reveal(),
+        );
+
+        $processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' open-versions --dry-run')
+            ->willReturn($process->reveal())
+            ->shouldBeCalledOnce();
+
+        (new ReflectionMethod($command, 'getOpenVersionsCommand'))
+            ->invoke($command, $this->input->reveal());
+    }
+
+    /**
+     * @return void
+     */
+    #[Test]
+    public function raiseToInstalledProcessWillUseTheResolvedJackBinary(): void
+    {
+        $processBuilder = $this->prophesize(ProcessBuilderInterface::class);
+        $process = $this->prophesize(Process::class);
+        $command = new DependenciesCommand(
+            $processBuilder->reveal(),
+            $this->processQueue->reveal(),
+            $this->fileLocator->reveal(),
+            $this->logger->reveal(),
+        );
+
+        $processBuilder->build(
+            DevToolsPathResolver::getPreferredToolBinaryPath('jack') . ' raise-to-installed --dry-run'
+        )
+            ->willReturn($process->reveal())
+            ->shouldBeCalledOnce();
+
+        (new ReflectionMethod($command, 'getRaiseToInstalledCommand'))
+            ->invoke($command, $this->input->reveal());
+    }
 }

tests/Console/Command/PhpDocCommandTest.php

@@ -28,9 +28,11 @@
 use FastForward\DevTools\Console\Command\PhpDocCommand;
 use FastForward\DevTools\Console\Command\RefactorCommand;
 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;
@@ -53,6 +55,8 @@
 #[UsesClass(Author::class)]
 #[UsesClass(Support::class)]
 #[UsesClass(ManagedWorkspace::class)]
+#[UsesClass(DevToolsPathResolver::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class PhpDocCommandTest extends TestCase
 {
@@ -176,6 +180,12 @@ protected function setUp(): void
     public function executeWillCreateDocHeaderAndRunPhpDocProcesses(): void
     {
         $this->filesystem->dumpFile(PhpDocCommand::FILENAME, 'docheader')->shouldBeCalled();
+        $this->processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('php-cs-fixer') . ' fix')
+            ->willReturn($this->process->reveal())
+            ->shouldBeCalled();
+        $this->processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('rector') . ' process')
+            ->willReturn($this->process->reveal())
+            ->shouldBeCalled();
         $this->processBuilder->withArgument('--using-cache=yes')
             ->willReturn($this->processBuilder->reveal())
             ->shouldBeCalled();

tests/Console/Command/RefactorCommandTest.php

@@ -21,10 +21,13 @@
 
 use FastForward\DevTools\Console\Command\RefactorCommand;
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
+use FastForward\DevTools\Path\DevToolsPathResolver;
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\Attributes\UsesTrait;
 use PHPUnit\Framework\TestCase;
 use Prophecy\Argument;
@@ -39,6 +42,8 @@
 use Symfony\Component\Process\Process;
 
 #[CoversClass(RefactorCommand::class)]
+#[UsesClass(DevToolsPathResolver::class)]
+#[UsesClass(WorkingProjectPathResolver::class)]
 #[UsesTrait(LogsCommandResults::class)]
 final class RefactorCommandTest extends TestCase
 {
@@ -108,6 +113,9 @@ protected function setUp(): void
     #[Test]
     public function executeWillReturnSuccessWhenProcessQueueSucceeds(): void
     {
+        $this->processBuilder->build(DevToolsPathResolver::getPreferredToolBinaryPath('rector'))
+            ->willReturn($this->process->reveal())
+            ->shouldBeCalled();
         $this->processQueue->run($this->output->reveal())
             ->willReturn(RefactorCommand::SUCCESS)
             ->shouldBeCalled();