[metrics] Add PhpMetrics command (#15)

Author: coisa

README.md

@@ -53,6 +53,10 @@ 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
+
 # Check and fix code style using ECS and Composer Normalize
 composer dev-tools code-style
 
@@ -102,6 +106,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 +123,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 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,6 +42,7 @@
         "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",
         "phpro/grumphp-shim": "^2.19",
         "phpspec/prophecy": "^1.26",
@@ -113,6 +114,7 @@
     },
     "scripts": {
         "dev-tools": "dev-tools",
-        "dev-tools:fix": "@dev-tools --fix"
+        "dev-tools:fix": "@dev-tools --fix",
+        "metrics": "@dev-tools metrics"
     }
 }

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,80 @@
+metrics
+=======
+
+Analyzes code metrics with PhpMetrics.
+
+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.
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer metrics
+   composer dev-tools metrics -- [options]
+   vendor/bin/dev-tools metrics [options]
+
+Options
+-------
+
+``--src=<path>``
+   Source directory to analyze.
+
+   Default: ``src``.
+
+``--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``.
+
+``--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``.
+
+Examples
+--------
+
+Generate the reduced summary 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 both 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 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.

docs/running/specialized-commands.rst

@@ -42,6 +42,26 @@ 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
+
+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.
+
 ``code-style``
 --------------