chore: normalize phpdoc command naming and docs

coisa · coisa · commit 545461938e86 · 2026-04-26T18:27:28.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,8 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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 `docheader`-style entry points.
-- Rename the command entry point from `standards:phpdoc` to `standards:docheader` and keep both `docheader` and `php-cs-fixer` aliases for compatibility (`standards:phpdoc` is intentionally not kept as a command name).
+- 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
 
diff --git a/README.md b/README.md
@@ -107,7 +107,7 @@ composer code-style
 composer refactor
 
 # Check and fix PHPDoc comments
-composer docheader
+composer phpdoc
 
 # Generate HTML API documentation using phpDocumentor
 composer docs
diff --git a/docs/advanced/rector-and-phpdoc.rst b/docs/advanced/rector-and-phpdoc.rst
@@ -1,14 +1,14 @@
-Rector and Docheader Automation
+Rector and PHPDoc Automation
 ===============================
 
 The package uses two different Rector entry points, and that difference matters
 when you are trying to understand why a rule did or did not run.
 
-``refactor`` Versus ``docheader``
+``refactor`` Versus ``phpdoc``
 ------------------------------
 
 - ``refactor`` uses the full ``rector.php`` file.
-- ``docheader`` runs PHP-CS-Fixer first and then executes Rector with
+- ``phpdoc`` runs PHP-CS-Fixer first and then executes Rector with
   ``--only \FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``.
 
 Rules Shipped by the Package
@@ -19,7 +19,7 @@ Rules Shipped by the Package
 
    * - Rule
      - Enabled in packaged ``rector.php``
-     - Used directly by ``docheader``
+     - Used directly by ``phpdoc``
      - Purpose
    * - ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``
      - Yes
@@ -45,7 +45,7 @@ rules when ``thecodingmachine/safe`` is installed.
 Why ``.docheader`` Appears Automatically
 ----------------------------------------
 
-The ``docheader`` command creates ``.docheader`` in the consumer root when it is
+The ``phpdoc`` command creates ``.docheader`` in the consumer root when it is
 missing. The template comes from the packaged file and the package name is
 rewritten to match the current project whenever Composer metadata is
 available.
diff --git a/docs/api/commands.rst b/docs/api/commands.rst
@@ -37,9 +37,9 @@ subprocess execution is needed.
      - ``refactor``
      - Runs Rector with local or packaged configuration.
    * - ``FastForward\DevTools\Console\Command\PhpDocCommand``
-     - ``standards:docheader``
+     - ``standards:phpdoc``
      - Runs PHP-CS-Fixer and a focused Rector PHPDoc pass. Supported aliases:
-       ``docheader`` and ``php-cs-fixer``.
+       ``phpdoc``, ``docheader`` and ``php-cs-fixer``.
    * - ``FastForward\DevTools\Console\Command\CodeStyleCommand``
      - ``code-style``
      - Runs Composer Normalize and ECS.
diff --git a/docs/commands/phpdoc.rst b/docs/commands/phpdoc.rst
@@ -1,12 +1,12 @@
-docheader
-=========
+phpdoc
+======
 
 Checks and fixes PHPDoc comments.
 
 Description
 -----------
 
-The ``docheader`` command coordinates PHPDoc checking and fixing using:
+The ``phpdoc`` command coordinates PHPDoc checking and fixing using:
 (alias ``docheader`` and ``php-cs-fixer``)
 
 - PHP-CS-Fixer - fixes PHPDoc formatting
@@ -19,11 +19,10 @@ Usage
 
 .. code-block:: bash
 
-   composer docheader
-   composer php-cs-fixer
-   composer docheader [options]
-   composer dev-tools docheader -- [options]
-   vendor/bin/dev-tools docheader [options]
+   composer phpdoc
+   composer phpdoc [options]
+   composer dev-tools phpdoc -- [options]
+   vendor/bin/dev-tools phpdoc [options]
 
 Arguments
 ---------
@@ -63,25 +62,25 @@ Check PHPDocs (dry-run):
 
 .. code-block:: bash
 
-   composer docheader
+   composer phpdoc
 
 Fix PHPDocs automatically:
 
 .. code-block:: bash
 
-   composer docheader --fix
+   composer phpdoc --fix
 
 Check specific directory:
 
 .. code-block:: bash
 
-   composer docheader ./src
+   composer phpdoc ./src
 
 Check without cache:
 
 .. code-block:: bash
 
-   composer docheader --no-cache
+   composer phpdoc --no-cache
 
 Exit Codes
 ---------
diff --git a/docs/commands/standards.rst b/docs/commands/standards.rst
@@ -9,7 +9,7 @@ Description
 The ``standards`` command runs the full quality pipeline:
 
 1. ``refactor`` - Rector code refactoring
-2. ``docheader`` - PHPDoc checks and fixes
+2. ``phpdoc`` - PHPDoc checks and fixes
 3. ``code-style`` - Code style checking
 4. ``reports`` - Documentation and test reports
 
@@ -68,10 +68,10 @@ Behavior
 - Cache stays enabled by default for nested cache-aware phases; omit both flags
   to keep the command default, pass ``--cache`` to force it on, and pass
   ``--no-cache`` to force it off.
-- The explicit cache intent is propagated to the nested ``docheader`` and
+- The explicit cache intent is propagated to the nested ``phpdoc`` and
   ``reports`` phases. ``refactor`` and ``code-style`` do not consume this
   contract.
-- When ``--cache-dir`` is provided, ``docheader`` and ``reports`` receive nested
+- When ``--cache-dir`` is provided, ``phpdoc`` and ``reports`` receive nested
   cache directories under that base path. When it is omitted, each nested tool
   keeps its own default cache directory.
 - Progress output is disabled by default across nested phases; use
diff --git a/docs/configuration/overriding-defaults.rst b/docs/configuration/overriding-defaults.rst
@@ -38,7 +38,7 @@ Commands and Their Configuration Files
    * - ``dependencies``
      - ``composer-dependency-analyser.php``
      - Falls back to the packaged Composer Dependency Analyser configuration.
-   * - ``docheader``
+   * - ``phpdoc``
      - ``.php-cs-fixer.dist.php`` and ``rector.php``
      - Falls back to the packaged files; ``.docheader`` is created locally
        when missing.
@@ -62,7 +62,7 @@ A Practical Example
 -------------------
 
 To customize Rector for one library, create ``rector.php`` in the consumer
-project root. The ``refactor`` command and the Rector phase inside ``docheader``
+project root. The ``refactor`` command and the Rector phase inside ``phpdoc``
 will use that file instead of the packaged default.
 
 Extending ECS Configuration
diff --git a/docs/configuration/tooling-defaults.rst b/docs/configuration/tooling-defaults.rst
@@ -14,16 +14,16 @@ create them on day one.
      - ``code-style``
      - Fallback ECS configuration.
    * - ``rector.php``
-     - ``refactor`` and ``docheader``
+     - ``refactor`` and ``phpdoc``
      - Fallback Rector configuration.
    * - ``phpunit.xml``
      - ``tests``
      - Registers ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
    * - ``.php-cs-fixer.dist.php``
-     - ``docheader``
+     - ``phpdoc``
      - Controls header and PHPDoc fixer behavior.
    * - ``.docheader``
-     - ``docheader``
+     - ``phpdoc``
      - Created into the consumer root on demand when missing.
    * - ``.editorconfig``
      - ``dev-tools:sync``
diff --git a/docs/running/specialized-commands.rst b/docs/running/specialized-commands.rst
@@ -179,14 +179,14 @@ Important details:
 - ``--json`` and ``--pretty-json`` forward ``--output-format json`` to Rector
   and disable its progress bar.
 
-``docheader`` (alias: ``php-cs-fixer``)
+``phpdoc`` (alias: ``docheader`` and ``php-cs-fixer``)
 ---------------------------------------
 
 Coordinates PHP-CS-Fixer and a focused Rector pass for missing method PHPDoc.
 
 .. code-block:: bash
 
-   composer docheader
+   composer phpdoc
    composer php-cs-fixer --fix
 
 Important details:
diff --git a/docs/running/unified-command.rst b/docs/running/unified-command.rst
@@ -14,7 +14,7 @@ Execution Order
 ``standards`` runs these commands in sequence:
 
 1. ``refactor``
-2. ``docheader``
+2. ``phpdoc``
 3. ``code-style``
 4. ``reports``
 
@@ -31,7 +31,7 @@ To allow the tools to modify files, use one of the following entry points:
    composer dev-tools:fix
    vendor/bin/dev-tools --fix
 
-The flag mainly affects ``refactor``, ``docheader``, and ``code-style``. The
+The flag mainly affects ``refactor``, ``phpdoc``, and ``code-style``. The
 reporting steps still run, but they do not use the flag themselves.
 
 When the Unified Command Is the Right Choice
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -238,7 +238,7 @@ Recovery:
 
 .. code-block:: bash
 
-    composer dev-tools docheader
+    composer dev-tools phpdoc
     composer dev-tools docs
 
 Fix source PHPDoc first, then regenerate docs. Avoid editing generated API
diff --git a/docs/usage/common-workflows.rst b/docs/usage/common-workflows.rst
@@ -11,7 +11,7 @@ Most day-to-day work falls into one of the flows below.
      - What happens
    * - Check everything before a pull request
      - ``composer dev-tools``
-     - Runs ``refactor``, ``docheader``, ``code-style``, and ``reports`` in
+     - Runs ``refactor``, ``phpdoc``, ``code-style``, and ``reports`` in
        order.
    * - Auto-fix what can be changed safely
      - ``composer dev-tools:fix``
diff --git a/src/Console/Command/DocsCommand.php b/src/Console/Command/DocsCommand.php
@@ -49,7 +49,7 @@
 #[AsCommand(
     name: 'reports:docs',
     description: 'Generates API documentation.',
-    aliases: ['reports:phpdoc', 'phpdoc', 'phpDocumentor', 'docs'],
+    aliases: ['reports:phpdoc', 'phpDocumentor', 'docs'],
 )]
 final class DocsCommand extends Command
 {
diff --git a/src/Console/Command/PhpDocCommand.php b/src/Console/Command/PhpDocCommand.php
@@ -44,7 +44,8 @@
  * 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:docheader', description: 'Checks and fixes PHPDocs.', aliases: [
+#[AsCommand(name: 'standards:phpdoc', description: 'Checks and fixes PHPDocs.', aliases: [
+    'phpdoc',
     'docheader',
     'php-cs-fixer',
 ])]
diff --git a/src/Console/Command/StandardsCommand.php b/src/Console/Command/StandardsCommand.php
@@ -113,7 +113,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             'input' => $input,
         ]);
 
-        foreach (['refactor', 'php-cs-fixer', 'code-style', 'reports'] as $command) {
+        foreach (['refactor', 'phpdoc', '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, ['php-cs-fixer', 'reports'], true) && null !== $cacheArgument) {
+            if (\in_array($command, ['phpdoc', 'reports'], true) && null !== $cacheArgument) {
                 $processBuilder = $processBuilder->withArgument($cacheArgument);
             }
 
             if (
                 $cacheDirEnabled
-                && \in_array($command, ['php-cs-fixer', 'reports'], true)
+                && \in_array($command, ['phpdoc', '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',
-            'php-cs-fixer', 'docheader' => 'Checking PHPDoc with DevTools',
+            'phpdoc', 'docheader', 'php-cs-fixer' => 'Checking PHPDoc with DevTools',
             'code-style' => 'Checking Code Style with DevTools',
             'reports' => 'Generating Reports with DevTools',
             default => 'Running DevTools Command',
diff --git a/tests/Console/Command/StandardsCommandTest.php b/tests/Console/Command/StandardsCommandTest.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', 'php-cs-fixer', 'code-style', 'reports'] === $context['commands']),
+                && ['refactor', 'phpdoc', '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', 'php-cs-fixer', 'code-style', 'reports'] === $context['commands']),
+                && ['refactor', 'phpdoc', '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/php-cs-fixer')
+        $this->processBuilder->withArgument('--cache-dir', '.dev-tools/cache/phpdoc')
             ->willReturn($this->processBuilder->reveal())
             ->shouldBeCalledOnce();
         $this->processBuilder->withArgument('--cache-dir', '.dev-tools/cache/reports')
