chore: align standards php-cs-fixer naming and harden command loader

Author: coisa

.github/wiki

@@ -11,6 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - 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
+
+- Align the standards pipeline to invoke PHPDoc checks via the `php-cs-fixer` command name/alias and route standards cache to `.dev-tools/cache/php-cs-fixer`, preserving backwards compatibility for existing `dockblock`-style entry points.
+- Rename the command entry point from `standards:phpdoc` to `standards:dockblock` and keep both `dockblock` and `php-cs-fixer` aliases for compatibility (`standards:phpdoc` is intentionally not kept as a command name).
+
 ## [1.22.3] - 2026-04-25
 
 ### Fixed

CHANGELOG.md

@@ -44,7 +44,10 @@
  * Provides operations to inspect, lint, and repair PHPDoc comments across the project.
  * The class MUST NOT be extended and SHALL coordinate tools like PHP-CS-Fixer and Rector.
  */
-#[AsCommand(name: 'standards:phpdoc', description: 'Checks and fixes PHPDocs.', aliases: ['phpdoc'])]
+#[AsCommand(name: 'standards:dockblock', description: 'Checks and fixes PHPDocs.', aliases: [
+    'dockblock',
+    'php-cs-fixer',
+])]
 final class PhpDocCommand extends Command
 {
     use HasCacheOption;

src/Console/Command/PhpDocCommand.php

@@ -113,7 +113,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             'input' => $input,
         ]);
 
-        foreach (['refactor', 'phpdoc', 'code-style', 'reports'] as $command) {
+        foreach (['refactor', 'php-cs-fixer', 'code-style', 'reports'] as $command) {
             $commands[] = $command;
             $processBuilder = $this->processBuilder;
 
@@ -129,13 +129,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 $processBuilder = $processBuilder->withArgument('--fix');
             }
 
-            if (\in_array($command, ['phpdoc', 'reports'], true) && null !== $cacheArgument) {
+            if (\in_array($command, ['php-cs-fixer', 'reports'], true) && null !== $cacheArgument) {
                 $processBuilder = $processBuilder->withArgument($cacheArgument);
             }
 
             if (
                 $cacheDirEnabled
-                && \in_array($command, ['phpdoc', 'reports'], true)
+                && \in_array($command, ['php-cs-fixer', 'reports'], true)
                 && null !== $cacheDir = $this->resolveCacheDirArgument($input, $command)
             ) {
                 $processBuilder = $processBuilder->withArgument('--cache-dir', $cacheDir);
@@ -181,7 +181,7 @@ private function getProcessLabel(string $command): string
     {
         return match ($command) {
             'refactor' => 'Refactoring Code with DevTools',
-            'phpdoc' => 'Checking PHPDoc with DevTools',
+            'php-cs-fixer', 'dockblock' => 'Checking PHPDoc with DevTools',
             'code-style' => 'Checking Code Style with DevTools',
             'reports' => 'Generating Reports with DevTools',
             default => 'Running DevTools Command',

src/Console/Command/StandardsCommand.php

@@ -22,6 +22,7 @@
 use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use Psr\Container\ContainerInterface;
 use ReflectionClass;
+use RuntimeException;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\CommandLoader\ContainerCommandLoader;
@@ -96,13 +97,27 @@ private function getCommandMap(FinderFactoryInterface $finderFactory): array
             }
 
             $arguments = $attribute->getArguments();
-            $commandNames = [$arguments['name'], ...($arguments['aliases'] ?? [])];
+            $commandName = $arguments['name'] ?? $arguments[0] ?? '';
+            $aliases = $arguments['aliases'] ?? $arguments[2] ?? [];
+            $commandNames = [$commandName, ...((array) $aliases)];
 
             foreach ($commandNames as $commandName) {
+                if (! \is_string($commandName)) {
+                    continue;
+                }
+
                 if ('' === $commandName) {
                     continue;
                 }
 
+                if (\array_key_exists($commandName, $commandMap) && $commandMap[$commandName] !== $class) {
+                    throw new RuntimeException(\sprintf(
+                        'Command %s is already registered and cannot be assigned to %s.',
+                        $commandName,
+                        $class
+                    ));
+                }
+
                 $commandMap[$commandName] = $class;
             }
         }

src/Console/CommandLoader/DevToolsCommandLoader.php

@@ -118,7 +118,7 @@ public function executeWillRunSuiteSequentially(): void
             'Code standards checks completed successfully.',
             Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
                 && $context['output'] instanceof OutputInterface
-                && ['refactor', 'phpdoc', 'code-style', 'reports'] === $context['commands']),
+                && ['refactor', 'php-cs-fixer', 'code-style', 'reports'] === $context['commands']),
         )->shouldBeCalled();
 
         self::assertSame(StandardsCommand::SUCCESS, $this->invokeExecute());
@@ -143,7 +143,7 @@ public function executeWillReturnFailureWhenAnyCommandFails(): void
             'Code standards checks failed.',
             Argument::that(static fn(array $context): bool => $context['input'] instanceof InputInterface
                 && $context['output'] instanceof OutputInterface
-                && ['refactor', 'phpdoc', 'code-style', 'reports'] === $context['commands']),
+                && ['refactor', 'php-cs-fixer', 'code-style', 'reports'] === $context['commands']),
         )->shouldBeCalled();
 
         self::assertSame(StandardsCommand::FAILURE, $this->invokeExecute());
@@ -162,7 +162,7 @@ public function executeWithCacheWillForwardCacheOnlyToCacheAwareNestedCommands()
         $this->processBuilder->withArgument('--cache')
             ->willReturn($this->processBuilder->reveal())
             ->shouldBeCalledTimes(2);
-        $this->processBuilder->withArgument('--cache-dir', '.dev-tools/cache/phpdoc')
+        $this->processBuilder->withArgument('--cache-dir', '.dev-tools/cache/php-cs-fixer')
             ->willReturn($this->processBuilder->reveal())
             ->shouldBeCalledOnce();
         $this->processBuilder->withArgument('--cache-dir', '.dev-tools/cache/reports')

tests/Console/Command/StandardsCommandTest.php

@@ -25,6 +25,7 @@
 use FastForward\DevTools\Console\Command\TestsCommand;
 use FastForward\DevTools\Console\CommandLoader\DevToolsCommandLoader;
 use FastForward\DevTools\Filesystem\FinderFactoryInterface;
+use RuntimeException;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\Attributes\UsesClass;
@@ -171,6 +172,47 @@ public function constructorWillRegisterAliasesFromAsCommandAttribute(): void
         self::assertTrue($loader->has('phpunit'));
     }
 
+    /**
+     * @return void
+     */
+    #[Test]
+    public function constructorWillFailWhenCommandNameConflicts(): void
+    {
+        $commandDirectory = \dirname(__DIR__, 3);
+        $fixtureDirectory = $commandDirectory . '/tests/Fixtures/Console/Command';
+        $srcDirectory = $commandDirectory . '/src/Console/Command';
+
+        $this->finderFactory->create()
+            ->willReturn($this->finder->reveal())
+            ->shouldBeCalledOnce();
+        $this->finder->files()
+            ->willReturn($this->finder->reveal())
+            ->shouldBeCalled();
+        $this->finder->in(Argument::type('string'))->willReturn($this->finder->reveal())->shouldBeCalled();
+        $this->finder->notPath('Traits')
+            ->willReturn($this->finder->reveal())
+            ->shouldBeCalled();
+        $this->finder->name('*.php')
+            ->willReturn($this->finder->reveal())
+            ->shouldBeCalled();
+        $this->finder->getIterator()
+            ->willReturn(new ArrayIterator([
+                new SplFileInfo(
+                    $fixtureDirectory . '/FixtureDuplicateCommandName.php',
+                    '',
+                    'FixtureDuplicateCommandName.php'
+                ),
+                new SplFileInfo($srcDirectory . '/AgentsCommand.php', '', 'AgentsCommand.php'),
+            ]))->shouldBeCalled();
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage(
+            'Command agents is already registered and cannot be assigned to FastForward\\DevTools\\Console\\Command\\AgentsCommand.'
+        );
+
+        new DevToolsCommandLoader($this->finderFactory->reveal(), $this->container->reveal());
+    }
+
     /**
      * @return void
      */

tests/Console/CommandLoader/DevToolsCommandLoaderTest.php

@@ -0,0 +1,26 @@
+<?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\Console\Command;
+
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+
+#[AsCommand(name: 'agents')]
+final class FixtureDuplicateCommandName extends Command {}