[cache] Standardize cache contract across commands (#162)

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Require GitHub issue write readback verification in the github-issues skill (#165)
+- Standardize cache flags and nested cache-dir propagation across cache-aware commands (#162)
 
 ## [1.18.0] - 2026-04-23
 

docs/commands/docs.rst

@@ -42,6 +42,12 @@ Options
    Path to the cache directory for phpDocumentor.
    Default: ``.dev-tools/cache/phpdoc``.
 
+``--cache``
+   Force phpDocumentor caching on for this run.
+
+``--no-cache``
+   Force phpDocumentor caching off for this run.
+
 ``--progress``
    Enable progress output from phpDocumentor.
 
@@ -73,6 +79,12 @@ Use custom source:
 
    composer docs --source=docs/user-guide
 
+Generate without cache:
+
+.. code-block:: bash
+
+   composer docs --no-cache
+
 Exit Codes
 ---------
 
@@ -92,7 +104,12 @@ Behavior
 - ``docs/`` must exist unless you pass another ``--source`` directory.
 - API pages are built from the PSR-4 paths declared in ``composer.json``.
 - Guide pages are built from the selected source directory.
-- A temporary ``phpdocumentor.xml`` is created in the cache directory.
+- Cache stays enabled by default; omit both flags to keep the command default,
+  pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
+- When ``--cache-dir`` is omitted, phpDocumentor keeps its default cache
+  directory. The option only affects phpDocumentor when caching is enabled.
+- A temporary ``phpdocumentor.xml`` is created for the run and uses the
+  configured cache directory only when caching stays enabled.
 - Progress output is disabled by default; use ``--progress`` to re-enable it in
   text mode.
 - ``--json`` and ``--pretty-json`` suppress phpDocumentor progress rendering so

docs/commands/phpdoc.rst

@@ -38,6 +38,12 @@ Options
 ``--cache-dir`` (optional)
    Path to the cache directory for PHP-CS-Fixer. Default: ``.dev-tools/cache/php-cs-fixer``.
 
+``--cache``
+   Force PHP-CS-Fixer caching on for this run.
+
+``--no-cache``
+   Force PHP-CS-Fixer caching off for this run.
+
 ``--progress``
    Enable progress output from PHP-CS-Fixer and the Rector phase.
 
@@ -69,6 +75,12 @@ Check specific directory:
 
    composer phpdoc ./src
 
+Check without cache:
+
+.. code-block:: bash
+
+   composer phpdoc --no-cache
+
 Exit Codes
 ---------
 
@@ -88,6 +100,10 @@ Behavior
 - Creates ``.docheader`` from the packaged template when the file is missing.
 - Uses ``.php-cs-fixer.dist.php`` and ``rector.php`` through local-first fallback.
 - The Rector phase explicitly runs ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``.
+- Cache stays enabled by default; omit both flags to keep the command default,
+  pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
+- When ``--cache-dir`` is omitted, PHP-CS-Fixer keeps its default cache
+  directory. The option only affects PHP-CS-Fixer when caching is enabled.
 - Progress output is disabled by default; use ``--progress`` to re-enable it in
   text mode.
 - ``--json`` and ``--pretty-json`` forward JSON mode to PHP-CS-Fixer and

docs/commands/reports.rst

@@ -40,6 +40,16 @@ Options
    The target directory for the generated metrics report.
    Default: ``.dev-tools/metrics``.
 
+``--cache-dir`` (optional)
+   Base cache directory for nested ``docs`` and ``tests`` caches.
+   When omitted, each nested tool keeps its own default cache directory.
+
+``--cache``
+   Force cache-aware nested documentation and test steps to keep caching enabled.
+
+``--no-cache``
+   Force cache-aware nested documentation and test steps to disable caching.
+
 ``--progress``
    Enable progress output in nested ``docs``, ``tests``, and ``metrics`` steps.
 
@@ -71,6 +81,12 @@ Generate reports with a custom metrics directory:
 
    composer reports --metrics=.dev-tools/metrics
 
+Generate reports with cache disabled for nested docs and tests:
+
+.. code-block:: bash
+
+   composer reports --no-cache
+
 Exit Codes
 ---------
 
@@ -89,6 +105,14 @@ Behavior
 
 - Runs ``docs`` in parallel with ``tests --coverage``.
 - Runs ``metrics --target`` after tests so the JUnit report is available.
+- Cache stays enabled by default for nested cache-aware steps; 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 ``docs`` and ``tests``
+  steps. The ``metrics`` step does not consume this contract.
+- When ``--cache-dir`` is provided, ``docs`` and ``tests`` receive nested cache
+  directories under that base path. When it is omitted, each nested tool keeps
+  its own default cache directory.
 - Runs tests with progress disabled by default and ``--coverage-summary`` so
   report builds keep PHPUnit output concise.
 - Progress output stays disabled by default across nested steps; use

docs/commands/standards.rst

@@ -35,6 +35,10 @@ Options
 
 This command supports:
 
+- ``--cache-dir`` to provide a base cache directory for nested cache-aware
+  phases;
+- ``--cache`` to force cache-aware nested phases to keep caching enabled;
+- ``--no-cache`` to force cache-aware nested phases to disable caching;
 - ``--progress`` to re-enable progress output from the nested phases in text
   mode;
 - ``--json`` to emit a structured machine-readable payload instead of the
@@ -61,6 +65,15 @@ Behavior
 - This is the default command when running ``composer dev-tools`` without args.
 - Each phase runs in sequence; if any phase fails, the command returns failure.
 - The ``--fix`` option is passed to all phases that support it.
+- 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 ``phpdoc`` and
+  ``reports`` phases. ``refactor`` and ``code-style`` do not consume this
+  contract.
+- 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
   ``--progress`` to re-enable it in text mode.
 - ``--json`` and ``--pretty-json`` are forwarded through every phase so the

docs/commands/tests.rst

@@ -41,8 +41,11 @@ Options
 ``--cache-dir`` (optional)
    Path to the PHPUnit cache directory. Default: ``.dev-tools/cache/phpunit``.
 
+``--cache``
+   Force PHPUnit result caching on for this run.
+
 ``--no-cache``
-   Disable PHPUnit caching.
+   Force PHPUnit result caching off for this run.
 
 ``--progress``
    Enable PHPUnit progress output.
@@ -114,6 +117,12 @@ Run without cache:
 
    composer tests --no-cache
 
+Force cache on explicitly:
+
+.. code-block:: bash
+
+   composer tests --cache
+
 Run with PHPUnit progress output enabled:
 
 .. code-block:: bash
@@ -141,6 +150,10 @@ Behavior
 - Local ``phpunit.xml`` is preferred over the packaged default.
 - Coverage filters are automatically applied to all PSR-4 paths from composer.json.
 - Multiple coverage formats are generated: HTML, Testdox HTML, Clover XML, and PHP.
+- Cache stays enabled by default; omit both flags to keep the command default,
+  pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
+- When ``--cache-dir`` is omitted, PHPUnit keeps its default cache directory.
+  The option only affects the result cache when caching is enabled.
 - ``--coverage-summary`` forwards PHPUnit's ``--only-summary-for-coverage-text``
   only when coverage text output is generated.
 - progress output is disabled by default.

docs/commands/wiki.rst

@@ -29,6 +29,12 @@ Options
    Path to the cache directory for phpDocumentor.
    Default: ``.dev-tools/cache/phpdoc``.
 
+``--cache``
+   Force phpDocumentor caching on for this run.
+
+``--no-cache``
+   Force phpDocumentor caching off for this run.
+
 ``--init``
    Initialize the configured wiki target as a Git submodule.
 
@@ -60,6 +66,12 @@ Initialize wiki as submodule:
 
    composer wiki --init
 
+Generate without cache:
+
+.. code-block:: bash
+
+   composer wiki --no-cache
+
 Exit Codes
 ---------
 
@@ -77,5 +89,9 @@ Behavior
 ---------
 
 - Default output directory is ``.github/wiki``.
+- Cache stays enabled by default; omit both flags to keep the command default,
+  pass ``--cache`` to force it on, and pass ``--no-cache`` to force it off.
+- When ``--cache-dir`` is omitted, phpDocumentor keeps its default cache
+  directory. The option only affects phpDocumentor when caching is enabled.
 - Uses the Markdown template from ``vendor/saggre/phpdocumentor-markdown/themes/markdown``.
 - The ``--init`` option creates the wiki as a Git submodule pointing to the repository wiki.

docs/running/specialized-commands.rst

@@ -55,11 +55,14 @@ Important details:
 - local ``phpunit.xml`` is preferred over the packaged default;
 - ``--coverage=<path>`` creates HTML, Testdox, Clover, and raw coverage output;
 - ``--coverage-summary`` keeps coverage text output to PHPUnit's summary;
+- cache stays enabled by default; ``--cache`` forces it on and ``--no-cache``
+  forces it off for a single run;
+- when ``--cache-dir`` is omitted, PHPUnit keeps its default cache directory;
+- ``--cache-dir`` only affects PHPUnit's result cache when caching is enabled;
 - progress output is disabled by default;
 - ``--progress`` re-enables PHPUnit progress output in text mode;
 - ``--json`` and ``--pretty-json`` still suppress PHPUnit progress output
   automatically;
-- ``--no-cache`` disables ``.dev-tools/cache/phpunit``;
 - the packaged configuration registers the DevTools PHPUnit extension.
 
 ``dependencies``
@@ -184,6 +187,10 @@ Important details:
   local-first fallback logic;
 - the Rector phase explicitly runs
   ``FastForward\DevTools\Rector\AddMissingMethodPhpDocRector``;
+- cache stays enabled by default; ``--cache`` forces it on and ``--no-cache``
+  forces it off for the PHP-CS-Fixer phase;
+- when ``--cache-dir`` is omitted, PHP-CS-Fixer keeps its default cache directory;
+- ``--cache-dir`` only affects PHP-CS-Fixer when caching is enabled;
 - progress output is disabled by default; ``--progress`` re-enables it for text
   mode;
 - ``--json`` and ``--pretty-json`` switch PHP-CS-Fixer to JSON output with
@@ -206,6 +213,10 @@ Important details:
 - guide pages are built from the selected source directory;
 - ``--template`` defaults to
   ``vendor/fast-forward/phpdoc-bootstrap-template``;
+- cache stays enabled by default; ``--cache`` forces it on and ``--no-cache``
+  forces it off for a single run;
+- when ``--cache-dir`` is omitted, phpDocumentor keeps its default cache directory;
+- ``--cache-dir`` only affects phpDocumentor when caching is enabled;
 - progress output is disabled by default; ``--progress`` re-enables it for text
   mode;
 - ``--json`` and ``--pretty-json`` also disable phpDocumentor's progress output.
@@ -224,6 +235,10 @@ Important details:
 - the default output directory is ``.github/wiki``;
 - it uses the Markdown template from
   ``vendor/saggre/phpdocumentor-markdown/themes/markdown``;
+- cache stays enabled by default; ``--cache`` forces it on and ``--no-cache``
+  forces it off for a single run;
+- when ``--cache-dir`` is omitted, phpDocumentor keeps its default cache directory;
+- ``--cache-dir`` only affects phpDocumentor when caching is enabled;
 - it is especially useful together with the reusable wiki workflow.
 
 ``reports``
@@ -242,6 +257,10 @@ Important details:
 - it calls ``metrics --target .dev-tools/metrics --junit .dev-tools/coverage/junit.xml``;
 - ``docs`` remains detached, while ``tests`` and ``metrics`` run in sequence so
   PhpMetrics can reuse the JUnit report generated by PHPUnit;
+- cache stays enabled by default for the nested ``docs`` and ``tests`` steps;
+  ``--cache`` forces that explicit intent on and ``--no-cache`` forces it off;
+- when ``--cache-dir`` is omitted, nested tools keep their own default cache
+  directories;
 - progress output stays disabled by default across the nested steps, and
   ``--progress`` re-enables it for human-readable runs;
 - ``--json`` and ``--pretty-json`` are propagated to each subprocess, while

docs/usage/testing-and-coverage.rst

@@ -12,7 +12,10 @@ When you run ``tests``, DevTools:
 - resolves ``phpunit.xml`` from the consumer root first and falls back to the
   packaged default;
 - uses ``vendor/autoload.php`` as the default bootstrap file;
-- stores cache data in ``.dev-tools/cache/phpunit`` unless ``--no-cache`` is used;
+- keeps PHPUnit result caching enabled by default;
+- treats ``--cache`` as an explicit force-on flag and ``--no-cache`` as an
+  explicit force-off flag for the current run;
+- uses ``.dev-tools/cache/phpunit`` only when caching stays enabled;
 - can generate HTML coverage, Testdox, Clover, and raw PHP coverage output
   when ``--coverage`` is provided.
 
@@ -23,8 +26,8 @@ Useful Examples
 
    composer tests
    composer tests -- --filter=PluginTest
-   vendor/bin/dev-tools tests --coverage=.dev-tools/coverage
-   vendor/bin/dev-tools tests --no-cache --bootstrap=tests/bootstrap.php
+   composer tests --coverage=.dev-tools/coverage
+   composer tests --no-cache --bootstrap=tests/bootstrap.php
 
 Coverage Outputs
 ----------------

src/Console/Command/DocsCommand.php

@@ -21,6 +21,7 @@
 
 use FastForward\DevTools\Console\Command\Traits\LogsCommandResults;
 use FastForward\DevTools\Composer\Json\ComposerJsonInterface;
+use FastForward\DevTools\Console\Input\HasCacheOption;
 use FastForward\DevTools\Console\Input\HasJsonOption;
 use Twig\Environment;
 use Composer\Command\BaseCommand;
@@ -52,6 +53,7 @@
 )]
 final class DocsCommand extends BaseCommand implements LoggerAwareCommandInterface
 {
+    use HasCacheOption;
     use HasJsonOption;
     use LogsCommandResults;
 
@@ -81,7 +83,13 @@ public function __construct(
      */
     protected function configure(): void
     {
-        $this->addJsonOption()
+        $this
+            ->addJsonOption()
+            ->addCacheOption('Whether to enable phpDocumentor caching.')
+            ->addCacheDirOption(
+                description: 'Path to the cache directory for phpDocumentor.',
+                default: ManagedWorkspace::getCacheDirectory(ManagedWorkspace::PHPDOC),
+            )
             ->addOption(
                 name: 'progress',
                 mode: InputOption::VALUE_NONE,
@@ -106,12 +114,6 @@ protected function configure(): void
                 mode: InputOption::VALUE_OPTIONAL,
                 description: 'Path to the template directory for the generated HTML documentation.',
                 default: 'vendor/fast-forward/phpdoc-bootstrap-template',
-            )
-            ->addOption(
-                name: 'cache-dir',
-                mode: InputOption::VALUE_OPTIONAL,
-                description: 'Path to the cache directory for phpDocumentor.',
-                default: ManagedWorkspace::getCacheDirectory(ManagedWorkspace::PHPDOC),
             );
     }
 
@@ -128,6 +130,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $jsonOutput = $this->isJsonOutput($input);
         $processOutput = $jsonOutput ? new BufferedOutput() : $output;
         $progress = ! $jsonOutput && (bool) $input->getOption('progress');
+        $cacheEnabled = $this->isCacheEnabled($input);
 
         $source = $this->filesystem->getAbsolutePath($input->getOption('source'));
         $target = $this->filesystem->getAbsolutePath($input->getOption('target'));
@@ -147,14 +150,18 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             source: $source,
             target: $target,
             template: $input->getOption('template'),
-            cacheDir: $cacheDir
+            cacheDir: $cacheEnabled ? $cacheDir : sys_get_temp_dir(),
         );
 
         $processBuilder = $this->processBuilder
             ->withArgument('--config', $config)
             ->withArgument('--ansi')
             ->withArgument('--markers', 'TODO,FIXME,BUG,HACK');
 
+        if ($cacheEnabled) {
+            $processBuilder = $processBuilder->withArgument('--cache-folder', $cacheDir);
+        }
+
         if (! $progress) {
             $processBuilder = $processBuilder->withArgument('--no-progress');
         }