[docs] Refresh dependency and reporting guides (#105) (#106)

* [docs] Refresh dependency and reporting guides (#105)

* Update wiki submodule pointer for PR #106

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -34,7 +34,8 @@ composer require --dev fast-forward/dev-tools:dev-main
 
 ## 🛠️ Usage
 
-Once installed, the plugin automatically exposes the `dev-tools` command via Composer.
+Once installed, the plugin automatically exposes the aggregated `dev-tools`
+command and the individual Composer commands described below.
 
 ```bash
 # Run all standard checks (refactoring, code styling, docs, tests, and reports)
@@ -50,57 +51,56 @@ You can also run individual commands for specific development tasks:
 # Run PHPUnit tests
 composer dev-tools tests
 
-# Analyze missing and unused Composer dependencies
+# Analyze missing, unused, and outdated Composer dependencies
 composer dependencies
-vendor/bin/dev-tools dependencies
-composer dev-tools dependencies -- --max-outdated=8
-composer dev-tools dependencies -- --dev
-composer dev-tools dependencies -- --upgrade --dev
+composer dependencies --max-outdated=8
+composer dependencies --dev
+composer dependencies --upgrade --dev
 
 # Analyze code metrics with PhpMetrics
 composer metrics
-composer dev-tools metrics -- --target=build/metrics
-composer dev-tools metrics -- --working-dir=packages/example
+composer metrics --target=build/metrics
+composer --working-dir=packages/example metrics
 
 # Check and fix code style using ECS and Composer Normalize
-composer dev-tools code-style
+composer code-style
 
 # Refactor code using Rector
-composer dev-tools refactor
+composer refactor
 
 # Check and fix PHPDoc comments
-composer dev-tools phpdoc
+composer phpdoc
 
 # Generate HTML API documentation using phpDocumentor
-composer dev-tools docs
+composer docs
 
 # Generate Markdown documentation for the wiki
-composer dev-tools wiki
+composer wiki
 
 # Generate documentation frontpage and related reports
-composer dev-tools reports
-composer dev-tools reports -- --metrics
+composer reports
+composer reports --target=build --coverage=build/coverage
 
 # Synchronize packaged agent skills into .agents/skills
-composer dev-tools skills
+composer skills
 
 # Merges and synchronizes .gitignore files
-composer dev-tools gitignore
+composer gitignore
 
 # Manages .gitattributes export-ignore rules for leaner package archives
-composer dev-tools gitattributes
+composer gitattributes
 
 # Generates a LICENSE file from composer.json license information
-composer dev-tools license
+composer license
 
 # Copies packaged or local resources into the consumer repository
-composer dev-tools copy-resource --source resources/docblock --target .docheader
+composer copy-resource --source resources/docblock --target .docheader
 
 # Installs Fast Forward Git hooks
-composer dev-tools git-hooks
+composer git-hooks
 
 # Updates the composer.json file to match the packaged schema
-composer dev-tools update-composer-json --force
+composer update-composer-json --force
 
 # Installs and synchronizes dev-tools scripts, GitHub Actions workflows,
 # .editorconfig, .gitignore rules, packaged skills, and the repository wiki
@@ -128,12 +128,12 @@ automation assets.
 | Command | Purpose |
 |---------|---------|
 | `composer dev-tools` | Runs the full `standards` pipeline. |
-| `composer dev-tools tests` | Runs PHPUnit with local-or-packaged configuration. |
-| `composer dev-tools dependencies` | Previews Jack dependency updates, then reports missing, unused, and overly outdated Composer dependencies. |
-| `composer dev-tools metrics` | Runs PhpMetrics for a working directory and generates requested report artifacts. |
-| `composer dev-tools docs` | Builds the HTML documentation site from PSR-4 code and `docs/`. |
-| `composer dev-tools skills` | Creates or repairs packaged skill links in `.agents/skills`. |
-| `composer dev-tools gitattributes` | Manages export-ignore rules in .gitattributes. |
+| `composer tests` | Runs PHPUnit with local-or-packaged configuration. |
+| `composer dependencies` | Previews Jack dependency updates, then reports missing, unused, and overly outdated Composer dependencies. |
+| `composer metrics` | Runs PhpMetrics for the current project and generates requested report artifacts. |
+| `composer docs` | Builds the HTML documentation site from PSR-4 code and `docs/`. |
+| `composer skills` | Creates or repairs packaged skill links in `.agents/skills`. |
+| `composer gitattributes` | Manages export-ignore rules in `.gitattributes`. |
 | `composer dev-tools:sync` | Updates scripts, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, and packaged skills. |
 
 ## 🔌 Integration

README.md

@@ -28,7 +28,10 @@ dependencies through constructor injection. The architecture uses
      - Runs PHPUnit with optional coverage output.
    * - ``FastForward\DevTools\Console\Command\DependenciesCommand``
      - ``dependencies``
-     - Reports missing and unused Composer dependencies.
+     - Reports missing, unused, and outdated Composer dependencies.
+   * - ``FastForward\DevTools\Console\Command\MetricsCommand``
+     - ``metrics``
+     - Builds the PhpMetrics site and JSON artifacts for the current project.
    * - ``FastForward\DevTools\Console\Command\DocsCommand``
      - ``docs``
      - Builds the HTML documentation site.
@@ -37,7 +40,7 @@ dependencies through constructor injection. The architecture uses
      - Builds Markdown API documentation.
    * - ``FastForward\DevTools\Console\Command\ReportsCommand``
      - ``reports``
-     - Combines the documentation build with coverage generation.
+     - Combines documentation, coverage, and metrics generation.
    * - ``FastForward\DevTools\Console\Command\SkillsCommand``
      - ``skills``
      - Synchronizes packaged agent skills into ``.agents/skills``.

docs/api/commands.rst

@@ -1,34 +1,31 @@
 dependencies
 =============
 
-Analyzes missing and unused Composer dependencies.
+Analyzes missing, unused, and outdated Composer dependencies.
 
 Description
 -----------
 
 The ``dependencies`` command (alias: ``deps``) analyzes missing, unused, and
-overly outdated
-Composer dependencies using two tools:
+overly outdated Composer dependencies using three tools:
 
 - ``composer-unused`` - detects unused packages
 - ``composer-dependency-analyser`` - detects missing packages
 - ``jack breakpoint`` - fails when too many outdated packages accumulate
 
-This command ships as a direct dependency of ``fast-forward/dev-tools``.
+These analyzers ship as direct dependencies of ``fast-forward/dev-tools``, so
+consumer repositories do not need extra setup before running the command.
 
 Usage
 -----
 
 .. code-block:: bash
 
    composer dependencies
-   composer dev-tools dependencies
+   composer dependencies [options]
 
    composer deps
-   composer dev-tools deps
-
-   vendor/bin/dev-tools dependencies
-   vendor/bin/dev-tools deps
+   vendor/bin/dev-tools dependencies [options]
 
 Options
 -------
@@ -41,9 +38,10 @@ Options
 ``--upgrade`` (optional)
    Applies the Jack upgrade workflow before the analyzers:
 
-   - ``vendor/bin/jack open-versions``
    - ``vendor/bin/jack raise-to-installed``
+   - ``vendor/bin/jack open-versions``
    - ``composer update -W``
+   - ``composer normalize``
 
    Without ``--upgrade``, the command runs the Jack workflow in preview mode
    before the analyzers.
@@ -64,19 +62,19 @@ Allow up to 10 outdated packages:
 
 .. code-block:: bash
 
-   composer dev-tools dependencies -- --max-outdated=10
+   composer dependencies --max-outdated=10
 
 Preview the upgrade workflow:
 
 .. code-block:: bash
 
-   composer dev-tools dependencies -- --dev
+   composer dependencies --dev
 
 Apply the upgrade workflow and then analyze dependencies:
 
 .. code-block:: bash
 
-   composer dev-tools dependencies -- --upgrade --dev
+   composer dependencies --upgrade --dev
 
 Using the alias:
 
@@ -98,18 +96,18 @@ Exit Codes
      - Failure. A dependency analyzer or Jack reported findings or errors.
 
 Behavior
----------
+--------
 
+- Always previews or applies ``jack raise-to-installed`` first and then
+  ``jack open-versions`` before running the analyzers.
 - Runs ``composer-unused``, ``composer-dependency-analyser``, and
-  ``jack breakpoint``.
+  ``jack breakpoint`` after the Jack preview or upgrade phase.
 - ``composer-dependency-analyser`` is configured with:
   - ``--ignore-unused-deps`` (leaves unused detection to ``composer-unused``)
   - ``--ignore-prod-only-in-dev-deps`` (ignores dev-only usage in production code)
 - ``jack breakpoint`` maps ``--max-outdated`` to Jack's ``--limit`` option.
-- It always previews Jack's ``open-versions`` and ``raise-to-installed``
-  commands before the analyzers.
-- ``--upgrade`` applies Jack's ``open-versions`` and ``raise-to-installed``
-  commands before ``composer update -W``.
+- ``--upgrade`` applies Jack's ``raise-to-installed`` and ``open-versions``
+  commands before ``composer update -W`` and ``composer normalize``.
 - Returns a non-zero exit code when missing, unused, or too many outdated
   dependencies are found.
 - All three tools must be available in ``vendor/bin/``.

docs/commands/dependencies.rst

@@ -16,16 +16,16 @@ Usage
 .. code-block:: bash
 
    composer metrics
-   composer dev-tools metrics -- [options]
+   composer metrics [options]
    vendor/bin/dev-tools metrics [options]
 
 Options
 -------
 
 ``--working-dir=<path>``
-   Composer's inherited working-directory option. Use it when you want to run
-   the command from another directory without changing your current shell
-   session.
+   Composer's inherited working-directory option. Use it when you invoke the
+   command through Composer and want to analyze another checkout without
+   changing your current shell session first.
 
    Default: the current working directory.
 
@@ -59,13 +59,19 @@ Generate an HTML report for manual inspection:
 
 .. code-block:: bash
 
-   composer dev-tools metrics -- --target=build/metrics
+   composer metrics --target=build/metrics
 
 Generate the full metrics artifact set for CI previews:
 
 .. code-block:: bash
 
-   vendor/bin/dev-tools metrics --target=build/metrics
+   composer metrics --target=build/metrics
+
+Analyze another checkout through Composer's inherited working directory:
+
+.. code-block:: bash
+
+   composer --working-dir=packages/example metrics
 
 Behavior
 --------

docs/commands/metrics.rst

@@ -6,14 +6,15 @@ Generates the frontpage for Fast Forward documentation.
 Description
 -----------
 
-The ``reports`` command generates the documentation frontpage and runs tests with
-coverage. It combines:
+The ``reports`` command generates the documentation frontpage, runs tests with
+coverage, and generates code metrics. It combines:
 
 - ``docs --target`` - generates API documentation
 - ``tests --coverage`` - generates test coverage reports
-- optionally ``metrics --target`` - generates PhpMetrics HTML and JSON reports
+- ``metrics --target`` - generates PhpMetrics HTML and JSON reports
 
-These are run in parallel for efficiency.
+The documentation build runs in parallel with PHPUnit, and the metrics step
+runs after PHPUnit so it can reuse the generated JUnit report.
 
 Usage
 -----
@@ -36,8 +37,8 @@ Options
    Default: ``public/coverage``.
 
 ``--metrics`` (optional)
-   Generate the metrics HTML report. When passed without a value, the report is
-   generated in ``public/metrics``.
+   The target directory for the generated metrics report.
+   Default: ``public/metrics``.
 
 Examples
 --------
@@ -54,11 +55,10 @@ Generate to custom directories:
 
    composer reports --target=build --coverage=build/coverage
 
-Generate reports including metrics:
+Generate reports with a custom metrics directory:
 
 .. code-block:: bash
 
-   composer reports --metrics
    composer reports --metrics=build/metrics
 
 Exit Codes
@@ -70,16 +70,17 @@ Exit Codes
    * - Code
      - Meaning
    * - 0
-     - Success. Both docs and coverage generated.
+     - Success. Documentation, coverage, and metrics generated successfully.
    * - 1
-     - Failure. One or both commands failed.
+     - Failure. One or more report stages failed.
 
 Behavior
 ---------
 
-- Runs ``docs`` and ``tests --coverage`` in parallel.
-- Runs ``metrics --target`` after tests when ``--metrics`` is enabled.
+- Runs ``docs`` in parallel with ``tests --coverage``.
+- Runs ``metrics --target`` after tests so the JUnit report is available.
 - Runs tests with ``--no-progress`` and ``--coverage-summary`` so report builds
   keep PHPUnit output concise.
+- Passes ``--junit <coverage>/junit.xml`` to the metrics step.
 - Used by the ``standards`` command as the final phase.
 - This is the reporting stage used by GitHub Pages.

docs/commands/reports.rst

@@ -14,8 +14,8 @@ Runtime and Composer Integration
      - Why it matters
    * - ``composer/composer`` and ``composer-plugin-api``
      - Provide the Composer plugin API, command integration, and script hooks.
-   * - ``phpro/grumphp``
-     - Supplies the default GrumPHP configuration referenced by
+   * - ``phpro/grumphp-shim``
+     - Supplies the default GrumPHP executable and configuration referenced by
        ``dev-tools:sync``.
 
 QA and Refactoring
@@ -36,6 +36,13 @@ QA and Refactoring
      - Extends the default Rector configuration with shared rules.
    * - ``friendsofphp/php-cs-fixer``
      - Powers the PHPDoc fixer phase.
+   * - ``icanhazstring/composer-unused``
+     - Reports unused Composer dependencies in ``dependencies``.
+   * - ``shipmonk/composer-dependency-analyser``
+     - Reports missing Composer dependencies in ``dependencies``.
+   * - ``rector/jack``
+     - Previews or applies dependency version updates and enforces the
+       outdated dependency threshold.
    * - ``thecodingmachine/safe``
      - Enables optional Safe migration rules when present.
 
@@ -53,6 +60,9 @@ Documentation and Reporting
      - Generates the Markdown API pages for the wiki.
    * - ``fast-forward/phpdoc-bootstrap-template``
      - Provides the default HTML theme used by ``docs``.
+   * - ``phpmetrics/phpmetrics``
+     - Generates the metrics site and JSON artifacts used by ``metrics`` and
+       ``reports``.
    * - ``esi/phpunit-coverage-check``
      - Enforces the minimum coverage threshold in the reusable test workflow.
 
@@ -66,6 +76,12 @@ Testing and Local Developer Experience
      - Why it matters
    * - ``phpunit/phpunit``
      - Runs the test suite.
+   * - ``phpunit/php-code-coverage``
+     - Provides the coverage exporters consumed by ``tests`` and ``reports``.
+   * - ``php-parallel-lint/php-parallel-lint``
+     - Supports linting and validation in the packaged development workflow.
+   * - ``phpspec/prophecy``
+     - Provides Prophecy doubles used throughout the packaged test suite.
    * - ``phpspec/prophecy-phpunit``
      - Supports the repository's Prophecy-based test doubles.
    * - ``dg/bypass-finals``