Add dev-tools metrics command for code metrics analysis (PHP Metrics integration)

[coisa]

Description

Problem

There is currently no standardized way in dev-tools to analyze code metrics such as complexity, maintainability, and structural quality.

While tools like ECS and Rector cover formatting and automated refactoring, and a future analyse command covers static analysis, there is still no built-in support for quantitative code quality metrics.

As a result:

• projects lack visibility into complexity and maintainability trends
• teams must manually install and run tools like PHP Metrics
• there is no unified interface for metrics in CI pipelines
• code quality signals remain fragmented across different tools

Proposal

Introduce a new command:

composer metrics

Alias:

dev-tools metrics

Goals

• provide a standardized entry point for code metrics analysis
• expose complexity and maintainability insights in a consistent way
• integrate with CI pipelines easily
• complement existing tooling (ecs, rector, analyse)

Tooling

Primary integration:

• phpmetrics/phpmetrics → provides:
  • Cyclomatic Complexity
  • Maintainability Index
  • Halstead metrics
  • Coupling and cohesion indicators
  • Visual and JSON/HTML reports

Expected Behavior

Running:

dev-tools metrics

Should:

• execute PHP Metrics on the project source
• generate a report (CLI + optional HTML/JSON)
• output a summary of key indicators:
  • average complexity
  • maintainability index
  • number of classes/functions analyzed

Example:

Code Metrics Summary

Classes: 120
Average Complexity: 4.2
Maintainability Index: 78 (Good)

Suggested CLI Options

dev-tools metrics
dev-tools metrics --report-html=./build/metrics
dev-tools metrics --report-json=./build/metrics.json
dev-tools metrics --src=src
dev-tools metrics --exclude=tests

Optional future flags

dev-tools metrics --fail-on-high-complexity
dev-tools metrics --threshold=maintainability:70

Implementation Strategy

1. Process execution

Use Symfony\Component\Process\Process to run:

vendor/bin/phpmetrics

2. Default behavior

• analyze src/ by default
• ignore common folders like vendor/, tests/, build/
• provide sensible defaults with minimal configuration

3. Output handling

• stream CLI output directly
• optionally parse summary for cleaner output
• support exporting reports (HTML/JSON)

4. Exit code behavior

• default: always exit 0
• future: allow failure thresholds

Requirements

• must work out-of-the-box with PHP Metrics installed
• must fail with a clear error message if the tool is missing
• must not require configuration for basic usage
• must be deterministic and CI-friendly
• must support report generation

Non-goals

• replacing PHP Metrics
• implementing custom metric algorithms
• enforcing thresholds in the first version

Benefits

• provides visibility into code complexity and maintainability
• helps identify refactoring opportunities
• enables tracking technical debt over time
• complements static analysis and refactoring tools
• improves overall developer insight into code quality

Additional Context

Metrics tools like PHP Metrics provide a different dimension of code quality compared to static analysis: instead of correctness, they focus on structure, complexity, and maintainability.

This makes them a natural addition alongside:

• ECS → style
• Rector → refactoring
• Analyse → static analysis
• Metrics → structural quality

Acceptance Criteria

• a new command dev-tools metrics is available
• the command executes PHP Metrics successfully
• outputs a readable summary of key metrics
• supports optional HTML/JSON report generation
• works with sensible defaults without configuration
• fails clearly if PHP Metrics is not installed

Architecture / Isolation Requirements

• the metrics execution logic must be isolated into dedicated classes instead of being implemented directly in the command
• responsibilities must be clearly separated, for example:
  • one class for building PHP Metrics command arguments
  • one class for executing the process
  • one class for parsing or summarizing results
  • one class for handling report generation/output
• the command must act only as an orchestrator
• the design must allow adding other metrics tools in the future without major refactoring
• the implementation must make it easy to extract this functionality into an external reusable package
• the core logic must avoid tight coupling to CLI I/O and be reusable in other contexts