[composer] Scope ProxyCommand under composer adapter

.agents/skills/phpunit-tests/SKILL.md

@@ -83,4 +83,57 @@ Choose the smallest command that proves the change.
 - Re-run after fixes until the targeted tests pass.
 - If failures come from unrelated pre-existing breakage, call that out separately and do not silently claim success.
 
+### Composer plugin validation flow
+
+Some repository test scenarios are only valid when DevTools is executed as a Composer plugin.
+Create a temporary fixture under `backup/` before running plugin-based verification.
+
+```bash
+PROJECT_ROOT="$(pwd)"
+PLUGIN_FIXTURE="$PROJECT_ROOT/backup/composer-plugin-consumer"
+mkdir -p "$PROJECT_ROOT/backup"
+rm -rf "$PLUGIN_FIXTURE"
+mkdir -p "$PLUGIN_FIXTURE"
+
+cat > "$PLUGIN_FIXTURE/composer.json" <<'JSON'
+{
+    "name": "fast-forward/dev-tools-composer-plugin-consumer-fixture",
+    "description": "Fixture project used to validate DevTools plugin behavior.",
+    "license": "MIT",
+    "type": "project",
+    "require": {
+        "fast-forward/dev-tools": "*@dev"
+    },
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../..",
+            "options": {
+                "symlink": true
+            }
+        }
+    ],
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "config": {
+        "allow-plugins": {
+            "ergebnis/composer-normalize": true,
+            "fast-forward/dev-tools": true,
+            "phpdocumentor/shim": true,
+            "phpro/grumphp-shim": true,
+            "pyrech/composer-changelogs": true
+        }
+    },
+    "scripts": {
+        "dev-tools": "dev-tools",
+        "dev-tools:fix": "@dev-tools --fix"
+    }
+}
+JSON
+
+cd "$PLUGIN_FIXTURE"
+composer install
+composer tests
+```
+
 Read [references/generation-checklist.md](references/generation-checklist.md) before writing or repairing tests in an unfamiliar repository.

.php-cs-fixer.dist.php

@@ -2,6 +2,10 @@
 
 declare(strict_types=1);
 
+require __DIR__ . '/vendor/autoload.php';
+
+use FastForward\DevTools\Path\WorkingProjectPathResolver;
+
 $rules = [
     'phpdoc_indent' => true,
     'phpdoc_order' => [
@@ -39,11 +43,7 @@
 
 $finder = PhpCsFixer\Finder::create()
     ->in([getcwd()])
-    ->exclude('public')
-    ->exclude('resources')
-    ->exclude('vendor')
-    ->exclude('tmp')
-;
+    ->exclude(WorkingProjectPathResolver::TOOLING_EXCLUDED_DIRECTORIES);
 
 return (new PhpCsFixer\Config())
     ->setRiskyAllowed(false)

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add a hybrid command runtime bootstrap and capability bridge that keeps command discovery split between migrated Symfony commands (`DevTools`) and legacy Composer `BaseCommand` commands (`DevToolsComposer`) while exposing proxy commands during Composer execution for the first migration step (#199)
+
+### Changed
+
+- Restore `standards:phpdoc` as the command entry point for PHPDoc checks while keeping
+  the legacy aliases `docheader` and `php-cs-fixer`.
+- Remove the `phpdoc` alias from `reports:docs` to avoid command-name collisions with
+  the standards PHPDoc check command.
+
 ## [1.22.3] - 2026-04-25
 
 ### Fixed

bin/dev-tools.php

@@ -20,11 +20,10 @@
 namespace FastForward\DevTools;
 
 use FastForward\DevTools\Console\DevTools;
-use Symfony\Component\Console\Input\ArgvInput;
 
 $projectVendorAutoload = \dirname(__DIR__, 4) . '/vendor/autoload.php';
 $pluginVendorAutoload = \dirname(__DIR__) . '/vendor/autoload.php';
 
 require_once file_exists($projectVendorAutoload) ? $projectVendorAutoload : $pluginVendorAutoload;
 
-DevTools::create()->run(new ArgvInput([...$argv, '--no-plugins']));
+DevTools::create()->run();

composer.json

@@ -41,7 +41,6 @@
     "require": {
         "php": "^8.3",
         "composer-plugin-api": "^2.0",
-        "composer/composer": "^2.9",
         "container-interop/service-provider": "^0.4.1",
         "dg/bypass-finals": "^1.9",
         "ergebnis/agent-detector": "^1.1",
@@ -82,6 +81,9 @@
         "thecodingmachine/safe": "^3.4",
         "twig/twig": "^3.24"
     },
+    "require-dev": {
+        "composer/composer": "^2.9"
+    },
     "minimum-stability": "stable",
     "autoload": {
         "psr-4": {

docs/api/commands.rst

@@ -37,8 +37,9 @@ subprocess execution is needed.
      - ``refactor``
      - Runs Rector with local or packaged configuration.
    * - ``FastForward\DevTools\Console\Command\PhpDocCommand``
-     - ``phpdoc``
-     - Runs PHP-CS-Fixer and a focused Rector PHPDoc pass.
+     - ``standards:phpdoc``
+     - Runs PHP-CS-Fixer and a focused Rector PHPDoc pass. Supported aliases:
+       ``phpdoc``, ``docheader`` and ``php-cs-fixer``.
    * - ``FastForward\DevTools\Console\Command\CodeStyleCommand``
      - ``code-style``
      - Runs Composer Normalize and ECS.

docs/commands/funding.rst

@@ -33,7 +33,7 @@ Options
 
 ``--composer-file`` (optional)
    Path to the Composer manifest to synchronize. Default:
-   ``Factory::getComposerFile()``.
+   ``composer.json``.
 
 ``--funding-file`` (optional)
    Path to the GitHub funding file to synchronize. Default:

docs/commands/metrics.rst

@@ -33,7 +33,7 @@ Options
    Comma-separated directories that should be excluded from analysis.
 
    Default:
-   ``vendor,tmp,cache,spec,build,.dev-tools,backup,resources,tests/Fixtures``.
+   ``vendor,tmp,cache,spec,build,.dev-tools,backup,resources``.
 
 ``--target=<directory>``
    Output directory for the generated metrics reports.

docs/commands/phpdoc.rst

@@ -7,6 +7,7 @@ Description
 -----------
 
 The ``phpdoc`` command coordinates PHPDoc checking and fixing using:
+(alias ``docheader`` and ``php-cs-fixer``)
 
 - PHP-CS-Fixer - fixes PHPDoc formatting
 - Rector with ``AddMissingMethodPhpDocRector`` - adds missing method PHPDoc

src/Changelog/Checker/UnreleasedEntryChecker.php

@@ -74,7 +74,7 @@ public function hasPendingChanges(string $file, ?string $againstReference = null
         }
 
         try {
-            $baseline = $this->gitClient->show($againstReference, $file, $this->filesystem->dirname($file));
+            $baseline = $this->gitClient->show($againstReference, $file, $this->filesystem->getDirectory($file));
         } catch (Throwable) {
             return true;
         }

src/Changelog/Manager/ChangelogManager.php

@@ -189,7 +189,7 @@ private function persist(string $file, ChangelogDocument $document): void
     {
         $this->filesystem->dumpFile(
             $file,
-            $this->renderer->render($document, $this->resolveRepositoryUrl($this->filesystem->dirname($file))),
+            $this->renderer->render($document, $this->resolveRepositoryUrl($this->filesystem->getDirectory($file))),
         );
     }
 }

src/Composer/Capability/DevToolsCommandProvider.php

@@ -19,8 +19,8 @@
 
 namespace FastForward\DevTools\Composer\Capability;
 
-use Composer\Command\BaseCommand;
 use Composer\Plugin\Capability\CommandProvider;
+use FastForward\DevTools\Composer\Command\ProxyCommand;
 use FastForward\DevTools\Console\DevTools;
 
 /**
@@ -29,14 +29,35 @@
  */
 final class DevToolsCommandProvider implements CommandProvider
 {
+    /**
+     * @var string the namespace prefix for dev-tools console commands to be registered as Composer commands
+     */
+    private const string COMMAND_NAMESPACE = 'FastForward\DevTools\Console\Command';
+
     /**
      * {@inheritDoc}
      */
     public function getCommands()
     {
-        return array_values(array_filter(
-            DevTools::create()->all(),
-            static fn(object $command): bool => $command instanceof BaseCommand,
-        ));
+        $commands = [];
+
+        foreach (DevTools::create()->all() as $registeredName => $command) {
+            /**
+             * Composer plugin registrations must be canonicalized to one command per Symfony command.
+             * The application exposes alias keys in `all()`, but Composer interprets each entry as
+             * an independent command and emits override warnings.
+             */
+            if ($registeredName !== $command->getName()) {
+                continue;
+            }
+
+            if (! str_starts_with($command::class, self::COMMAND_NAMESPACE)) {
+                continue;
+            }
+
+            $commands[] = new ProxyCommand($command);
+        }
+
+        return $commands;
     }
 }

src/Composer/Command/ProxyCommand.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Composer\Command;
+
+use Composer\Command\BaseCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Adapts migrated Symfony commands to Composer's BaseCommand contract.
+ */
+final class ProxyCommand extends BaseCommand
+{
+    /**
+     * @param Command $command the Symfony command adapted for Composer plugin execution
+     */
+    public function __construct(
+        private readonly Command $command,
+    ) {
+        parent::__construct($this->command->getName());
+
+        $this
+            ->setAliases($this->command->getAliases())
+            ->setDescription($this->command->getDescription())
+            ->setHelp($this->command->getHelp())
+            ->setDefinition(clone $this->command->getDefinition())
+            ->setHidden($this->command->isHidden());
+    }
+
+    /**
+     * @param InputInterface $input
+     * @param OutputInterface $output
+     *
+     * @return int
+     */
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        return $this->command->run($input, $output);
+    }
+}