[metrics] Finalize metrics workflow and docs (#15)

Author: coisa

.agents/skills/package-readme/SKILL.md

@@ -44,7 +44,7 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 
 - **Badges**
 	- Read [references/badges.md](references/badges.md) before drafting the badge block.
-	- For current Fast Forward packages, default to this order: PHP Version, Composer Package, Tests, Coverage, Docs, License, GitHub Sponsors.
+	- For current Fast Forward packages, default to this order: PHP Version, Composer Package, Tests, Coverage, Metrics, Docs, License, GitHub Sponsors.
 	- Add a second standards row for relevant PSRs when the package contract is centered on them.
 	- Keep Packagist visible both in the badge block via `Composer Package` and in the links section.
 
@@ -54,6 +54,7 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 	[![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fcomponent-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/component)
 	[![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/component/tests.yml?logo=githubactions&logoColor=white&label=tests&color=22C55E)](https://github.com/php-fast-forward/component/actions/workflows/tests.yml)
 	[![Coverage](https://img.shields.io/badge/coverage-phpunit-4ADE80?logo=php&logoColor=white)](https://php-fast-forward.github.io/component/coverage/index.html)
+	[![Metrics](https://img.shields.io/badge/metrics-phpmetrics-8B5CF6?logo=php&logoColor=white)](https://php-fast-forward.github.io/component/metrics/index.html)
 	[![Docs](https://img.shields.io/github/deployments/php-fast-forward/component/github-pages?logo=readthedocs&logoColor=white&label=docs&labelColor=1E293B&color=38BDF8&style=flat)](https://php-fast-forward.github.io/component/index.html)
 	[![License](https://img.shields.io/github/license/php-fast-forward/component?color=64748B)](LICENSE)
 	[![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?logo=githubsponsors&logoColor=white&color=EC4899)](https://github.com/sponsors/php-fast-forward)
@@ -169,6 +170,7 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 	## 🔗 Links
 	- [Repository](https://github.com/php-fast-forward/component)
 	- [Packagist](https://packagist.org/packages/php-fast-forward/component)
+	- [Metrics Report](https://php-fast-forward.github.io/component/metrics/index.html)
 	- [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119)
 	- [PSR-11](https://www.php-fig.org/psr/psr-11/)
 	- [Sphinx Documentation](docs/index.rst)
@@ -205,7 +207,7 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 
 ## Quick Review Checklist
 - [ ] Project title and short description
-- [ ] Badges follow the current Fast Forward stack: PHP Version, Composer Package, Tests, Coverage, Docs, License, GitHub Sponsors, plus relevant standards badges
+- [ ] Badges follow the current Fast Forward stack: PHP Version, Composer Package, Tests, Coverage, Metrics, Docs, License, GitHub Sponsors, plus relevant standards badges
 - [ ] Features (bulleted, with emoji)
 - [ ] Installation (composer, requirements)
 - [ ] Usage (basic and advanced)
@@ -217,7 +219,7 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 - [ ] FAQ (if relevant)
 - [ ] License
 - [ ] Contributing
-- [ ] Links (repository, Packagist, docs, RFCs, PSRs)
+- [ ] Links (repository, Packagist, docs, metrics, RFCs, PSRs)
 - [ ] Comparison table (if relevant)
 - [ ] Formatting and style guidelines followed
 - [ ] SEO/discoverability (keywords, cross-links)

.github/workflows/reports.yml

@@ -72,7 +72,7 @@ jobs:
             - name: Generate reports
               env:
                 COMPOSER_ROOT_VERSION: ${{ env.REPORTS_ROOT_VERSION }}
-              run: composer dev-tools reports -- --target=tmp/reports --coverage=tmp/reports/coverage
+              run: composer dev-tools reports -- --target=tmp/reports --coverage=tmp/reports/coverage --metrics=tmp/reports/metrics
 
             - name: Fix permissions
               run: |
@@ -139,6 +139,7 @@ jobs:
 
                   - Docs: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/
                   - Coverage: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/coverage/
+                  - Metrics: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/previews/pr-${{ github.event.pull_request.number }}/metrics/
 
     cleanup_preview:
         if: github.event_name == 'pull_request' && github.event.action == 'closed'

README.md

@@ -8,6 +8,7 @@ across Fast Forward libraries.
 [![Composer Package](https://img.shields.io/badge/composer-fast--forward%2Fdev--tools-F28D1A.svg?logo=composer&logoColor=white)](https://packagist.org/packages/fast-forward/dev-tools)
 [![Tests](https://img.shields.io/github/actions/workflow/status/php-fast-forward/dev-tools/tests.yml?logo=githubactions&logoColor=white&label=tests&color=22C55E)](https://github.com/php-fast-forward/dev-tools/actions/workflows/tests.yml)
 [![Coverage](https://img.shields.io/badge/coverage-phpunit-4ADE80?logo=php&logoColor=white)](https://php-fast-forward.github.io/dev-tools/coverage/index.html)
+[![Metrics](https://img.shields.io/badge/metrics-phpmetrics-8B5CF6?logo=php&logoColor=white)](https://php-fast-forward.github.io/dev-tools/metrics/index.html)
 [![Docs](https://img.shields.io/github/deployments/php-fast-forward/dev-tools/github-pages?logo=readthedocs&logoColor=white&label=docs&labelColor=1E293B&color=38BDF8&style=flat)](https://php-fast-forward.github.io/dev-tools/index.html)
 [![License](https://img.shields.io/github/license/php-fast-forward/dev-tools?color=64748B)](LICENSE)
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/php-fast-forward?logo=githubsponsors&logoColor=white&color=EC4899)](https://github.com/sponsors/php-fast-forward)
@@ -56,6 +57,7 @@ vendor/bin/dev-tools dependencies
 # Analyze code metrics with PhpMetrics
 composer metrics
 composer dev-tools metrics -- --report-html=build/metrics
+composer dev-tools metrics -- --working-dir=packages/example
 
 # Check and fix code style using ECS and Composer Normalize
 composer dev-tools code-style
@@ -74,6 +76,7 @@ composer dev-tools wiki
 
 # Generate documentation frontpage and related reports
 composer dev-tools reports
+composer dev-tools reports -- --metrics
 
 # Synchronize packaged agent skills into .agents/skills
 composer dev-tools skills
@@ -123,7 +126,7 @@ automation assets.
 | `composer dev-tools` | Runs the full `standards` pipeline. |
 | `composer dev-tools tests` | Runs PHPUnit with local-or-packaged configuration. |
 | `composer dev-tools dependencies` | Reports missing and unused Composer dependencies. |
-| `composer dev-tools metrics` | Runs PhpMetrics and prints a reduced code-metrics summary. |
+| `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.json

@@ -42,8 +42,8 @@
         "nikic/php-parser": "^5.7",
         "php-di/php-di": "^7.1",
         "php-parallel-lint/php-parallel-lint": "^1.4",
-        "phpmetrics/phpmetrics": "^2.9",
         "phpdocumentor/shim": "^3.9",
+        "phpmetrics/phpmetrics": "^2.9",
         "phpro/grumphp-shim": "^2.19",
         "phpspec/prophecy": "^1.26",
         "phpspec/prophecy-phpunit": "^2.5",
@@ -114,7 +114,6 @@
     },
     "scripts": {
         "dev-tools": "dev-tools",
-        "dev-tools:fix": "@dev-tools --fix",
-        "metrics": "@dev-tools metrics"
+        "dev-tools:fix": "@dev-tools --fix"
     }
 }

docs/commands/metrics.rst

@@ -7,13 +7,8 @@ Overview
 --------
 
 The ``metrics`` command runs `PhpMetrics <https://phpmetrics.github.io/website/>`_
-against the selected source directory, generates a JSON report, and prints a
-reduced summary with:
-
-- average cyclomatic complexity by class;
-- average maintainability index by class;
-- number of classes analyzed;
-- number of functions analyzed.
+against the current working directory and forwards the requested report
+artifacts.
 
 Usage
 -----
@@ -27,33 +22,32 @@ Usage
 Options
 -------
 
-``--src=<path>``
-   Source directory to analyze.
+``--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.
 
-   Default: ``src``.
+   Default: the current working directory.
 
 ``--exclude=<list>``
    Comma-separated directories that should be excluded from analysis.
 
    Default:
-   ``vendor,test,Test,tests,Tests,testing,Testing,bower_components,node_modules,cache,spec,build``.
+   ``vendor,test,tests,tmp,cache,spec,build,backup,resources``.
 
 ``--report-html=<directory>``
    Optional output directory for the generated HTML report.
 
 ``--report-json=<file>``
    Optional output file for the generated JSON report.
 
-``--cache-dir=<directory>``
-   Cache directory used for temporary JSON reports when ``--report-json`` is
-   not provided.
-
-   Default: ``tmp/cache/phpmetrics``.
+``--report-summary-json=<file>``
+   Optional output file for the generated summary JSON report.
 
 Examples
 --------
 
-Generate the reduced summary with defaults:
+Analyze the current repository with defaults:
 
 .. code-block:: bash
 
@@ -65,7 +59,7 @@ Generate an HTML report for manual inspection:
 
    composer dev-tools metrics -- --report-html=build/metrics
 
-Generate both JSON and HTML reports for CI artifacts:
+Generate JSON and HTML reports for CI artifacts:
 
 .. code-block:: bash
 
@@ -74,7 +68,6 @@ Generate both JSON and HTML reports for CI artifacts:
 Behavior
 --------
 
-- the command fails early when ``vendor/bin/phpmetrics`` is not installed;
-- the source directory must exist;
-- the reduced summary is derived from the generated PhpMetrics JSON report;
-- optional HTML and JSON report destinations are created before execution.
+- the command forwards report options directly to PhpMetrics;
+- it runs PhpMetrics through the active PHP binary and suppresses PhpMetrics
+  deprecation notices emitted by the dependency itself.

docs/commands/reports.rst

@@ -11,6 +11,7 @@ coverage. It combines:
 
 - ``docs --target`` - generates API documentation
 - ``tests --coverage`` - generates test coverage reports
+- optionally ``metrics --report-html`` - generates PhpMetrics HTML reports
 
 These are run in parallel for efficiency.
 
@@ -34,6 +35,10 @@ Options
    The target directory for the generated test coverage report.
    Default: ``public/coverage``.
 
+``--metrics`` (optional)
+   Generate the metrics HTML report. When passed without a value, the report is
+   generated in ``public/metrics``.
+
 Examples
 --------
 
@@ -49,6 +54,13 @@ Generate to custom directories:
 
    composer reports --target=build --coverage=build/coverage
 
+Generate reports including metrics:
+
+.. code-block:: bash
+
+   composer reports --metrics
+   composer reports --metrics=build/metrics
+
 Exit Codes
 ---------
 
@@ -66,6 +78,7 @@ Behavior
 ---------
 
 - Runs ``docs`` and ``tests --coverage`` in parallel.
+- Runs ``metrics --report-html`` in parallel when ``--metrics`` is enabled.
 - Runs tests with ``--no-progress`` and ``--coverage-summary`` so report builds
   keep PHPUnit output concise.
 - Used by the ``standards`` command as the final phase.

docs/running/specialized-commands.rst

@@ -51,16 +51,18 @@ Analyzes code metrics with PhpMetrics.
 
    composer metrics
    composer dev-tools metrics -- --report-html=build/metrics
+   composer dev-tools metrics -- --working-dir=packages/example
 
 Important details:
 
 - it ships ``phpmetrics/phpmetrics`` as a direct dependency of
   ``fast-forward/dev-tools``;
-- it prints a reduced summary with average cyclomatic complexity, average
-  maintainability index, and analyzed class/function counts;
-- ``--report-html`` and ``--report-json`` allow persisting the native
-  PhpMetrics reports for CI artifacts or manual review;
-- it fails early when the PhpMetrics binary or source directory is missing.
+- it analyzes the selected ``--working-dir`` and forwards the requested
+  report options directly to PhpMetrics;
+- ``--report-html``, ``--report-json``, and ``--report-summary-json`` allow
+  persisting the native PhpMetrics reports for CI artifacts or manual review;
+- it suppresses deprecation notices emitted by the PhpMetrics dependency
+  itself so the command output stays readable.
 
 ``code-style``
 --------------
@@ -159,6 +161,7 @@ Important details:
 
 - it calls ``docs --target public``;
 - it calls ``tests --coverage public/coverage --no-progress --coverage-summary``;
+- ``--metrics`` adds ``metrics --report-html public/metrics``;
 - it is the reporting stage used by ``standards``.
 
 ``skills``