[metrics] Add PhpMetrics command (#15)

.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)
@@ -53,6 +54,11 @@ composer dev-tools tests
 composer dependencies
 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
 
@@ -70,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
@@ -102,6 +109,10 @@ The `dependencies` command ships with both dependency analyzers as direct
 dependencies of `fast-forward/dev-tools`, so it works without extra
 installation in the consumer project.
 
+The `metrics` command ships with `phpmetrics/phpmetrics` as a direct
+dependency of `fast-forward/dev-tools`, so consumer repositories can generate
+metrics reports without extra setup.
+
 The `skills` command keeps `.agents/skills` aligned with the packaged Fast
 Forward skill set. It creates missing links, repairs broken links, and
 preserves existing non-symlink directories. The `dev-tools:sync` command calls
@@ -115,6 +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 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

@@ -43,6 +43,7 @@
         "php-di/php-di": "^7.1",
         "php-parallel-lint/php-parallel-lint": "^1.4",
         "phpdocumentor/shim": "^3.9",
+        "phpmetrics/phpmetrics": "^2.9",
         "phpro/grumphp-shim": "^2.19",
         "phpspec/prophecy": "^1.26",
         "phpspec/prophecy-phpunit": "^2.5",

docs/commands/index.rst

@@ -9,6 +9,7 @@ Detailed documentation for each dev-tools command.
    standards
    tests
    dependencies
+   metrics
    code-style
    refactor
    phpdoc
@@ -22,4 +23,4 @@ Detailed documentation for each dev-tools command.
    license
    copy-resource
    git-hooks
-   update-composer-json
+   update-composer-json

docs/commands/metrics.rst

@@ -0,0 +1,73 @@
+metrics
+=======
+
+Analyzes code metrics with PhpMetrics.
+
+Overview
+--------
+
+The ``metrics`` command runs `PhpMetrics <https://phpmetrics.github.io/website/>`_
+against the current working directory and forwards the requested report
+artifacts.
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer metrics
+   composer dev-tools 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.
+
+   Default: the current working directory.
+
+``--exclude=<list>``
+   Comma-separated directories that should be excluded from analysis.
+
+   Default:
+   ``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.
+
+``--report-summary-json=<file>``
+   Optional output file for the generated summary JSON report.
+
+Examples
+--------
+
+Analyze the current repository with defaults:
+
+.. code-block:: bash
+
+   composer metrics
+
+Generate an HTML report for manual inspection:
+
+.. code-block:: bash
+
+   composer dev-tools metrics -- --report-html=build/metrics
+
+Generate JSON and HTML reports for CI artifacts:
+
+.. code-block:: bash
+
+   vendor/bin/dev-tools metrics --report-json=build/metrics.json --report-html=build/metrics
+
+Behavior
+--------
+
+- 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

@@ -42,6 +42,28 @@ Important details:
 - it returns a non-zero exit code when missing or unused dependencies are
   found.
 
+``metrics``
+-----------
+
+Analyzes code metrics with PhpMetrics.
+
+.. code-block:: bash
+
+   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 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``
 --------------
 
@@ -139,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``