Calculate Churn with Code Coverage (#49)

Author: floriankraemer

.gitignore

@@ -13,3 +13,4 @@
 infection.log
 phive.phar
 phpcca.phar
+/*.xml

composer.json

@@ -26,7 +26,11 @@
             "name": "Florian Krämer"
         }
     ],
+    "suggest": {
+        "ext-dom": "Required for some rules and code analysis features."
+    },
     "require-dev": {
+        "ext-dom": "*",
         "roave/security-advisories": "dev-latest",
         "phpunit/phpunit": "^11.3",
         "infection/infection": "^0.29.6",
@@ -40,7 +44,8 @@
         "bin-dir": "bin",
         "allow-plugins": {
             "infection/extension-installer": true
-        }
+        },
+        "process-timeout": 0
     },
     "bin": [
       "bin/phpcca"
@@ -53,10 +58,10 @@
             "infection"
         ],
         "test-coverage": [
-            "phpunit --coverage-text"
+            "phpunit --coverage-text --path-coverage"
         ],
         "test-coverage-html": [
-            "phpunit --coverage-html tmp/coverage/"
+            "phpunit --coverage-html tmp/coverage/ --path-coverage"
         ],
         "cscheck": [
             "phpcs src/ tests/ -s"

coverage.xml

@@ -5,61 +5,174 @@ Churn is a measure of how much code has changed over time. The `churn` command h
 ## Usage
 
 ```bash
-bin/phpcca churn <path-to-folder> [--config=<file>] [--git=<vcs>] [--debug]
+bin/phpcca churn <path-to-folder> [options]
 ```
 
+**Options:**
 - `<path-to-folder>`: **Required.** Path to the PHP file or directory to analyze.
 - `--config, -c`: Path to a configuration file (optional).
 - `--vcs, -s`: Version control system to use for change detection (default: `git`).
+- `--since`: Start date for counting changes (default: `2000-01-01`).
 - `--report-type, -r`: Type of report to generate (`json`, `csv`, `html`).
 - `--report-file, -f`: File to save the report (default: `phpcca-churn-report.html`).
+- `--coverage-cobertura`: Path to Cobertura XML coverage file to include coverage analysis.
 - `--debug`: Enables debug output.
 
 ## What it does
 
 1. **Collects cognitive metrics** for each class in the given path.
 2. **Counts how many times each file/class has changed** using your VCS (default: Git).
-3. **Calculates a churn score**:
-   `churn = timesChanged * score`
-4. **Ranks classes by churn score** so you can focus on the most critical hotspots.
+3. **Calculates churn scores**:
+   - **Standard Churn**: `churn = timesChanged × cognitiveScore`
+   - **Risk Churn** (with coverage): `riskChurn = timesChanged × cognitiveScore × (1 - coverage)`
+4. **Assigns risk levels** based on churn and coverage (when coverage data is provided).
+5. **Ranks classes by churn score** so you can focus on the most critical hotspots.
 
 ⚠️ **For the time being only Git is supported as the VCS backend!** ⚠️
 
-## Example Output
+## Basic Example Output
 
 ```
-+----------------------+--------------+--------+-------+
-| Class                | TimesChanged | Score  | Churn |
-+----------------------+--------------+--------+-------+
-| App\Service\Foo      | 12           | 8      | 96    |
-| App\Controller\Bar   | 7            | 10     | 70    |
-+----------------------+--------------+--------+-------+
++-------------------------+-------+--------+---------------+
+| Class                   | Score | Churn  | Times Changed |
++-------------------------+-------+--------+---------------+
+| App\Service\Foo         | 8.0   | 96.0   | 12            |
+| App\Controller\Bar      | 10.0  | 70.0   | 7             |
++-------------------------+-------+--------+---------------+
 ```
 
+## Coverage-Weighted Churn Analysis
+
+### Generating Coverage Data
+
+The tool supports both **Cobertura** and **Clover** XML coverage formats.
+
+**Generate Cobertura coverage:**
+```bash
+XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-cobertura=coverage.xml
+```
+
+**Generate Clover coverage:**
+```bash
+XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover=coverage.xml
+```
+
+### Running Churn with Coverage
+
+**Using Cobertura format:**
+```bash
+bin/phpcca churn src --coverage-cobertura=coverage.xml
+```
+
+**Using Clover format:**
+```bash
+bin/phpcca churn src --coverage-clover=coverage.xml
+```
+
+**Note:** The tool will auto-detect the format if you use a standard filename, but explicit format options are recommended for clarity.
+
+### Enhanced Output with Coverage
+
+When coverage data is provided, the output includes additional risk analysis columns:
+
+```
++-------------------------+-------+--------+------------+---------------+----------+------------+
+| Class                   | Score | Churn  | Risk Churn | Times Changed | Coverage | Risk Level |
++-------------------------+-------+--------+------------+---------------+----------+------------+
+| App\Service\Foo         | 8.0   | 96.0   | 86.4       | 12            | 10.00%   | CRITICAL   |
+| App\Controller\Bar      | 10.0  | 70.0   | 3.5        | 7             | 95.00%   | LOW        |
+| App\Model\Baz           | 6.5   | 26.0   | 13.0       | 4             | 50.00%   | MEDIUM     |
++-------------------------+-------+--------+------------+---------------+----------+------------+
+```
+
+### How Risk Churn is Calculated
+
+**Risk Churn** multiplies standard churn by the coverage gap:
+
+```
+Risk Churn = Times Changed × Cognitive Score × (1 - Coverage)
+```
+
+**Example:**
+- Class with 12 changes, score 8.0, and 10% coverage:
+  - Standard Churn: `12 × 8.0 = 96.0`
+  - Risk Churn: `12 × 8.0 × (1 - 0.10) = 86.4`
+
+This formula prioritizes classes that are:
+- Frequently changed (high `timesChanged`)
+- Complex (high `cognitiveScore`)
+- Poorly tested (low `coverage`)
+
+### Risk Level Thresholds
+
+Risk levels help you prioritize which classes need immediate attention:
+
+| Risk Level | Criteria | Action Required |
+|-----------|----------|-----------------|
+| **CRITICAL** | Churn > 30 AND Coverage < 50% | Urgent: Add tests and refactor immediately |
+| **HIGH** | Churn > 20 AND Coverage < 70% | High Priority: Increase test coverage |
+| **MEDIUM** | Churn > 10 AND Coverage < 80% | Medium Priority: Consider adding tests |
+| **LOW** | Everything else | Low Priority: Monitor |
+
+### Interpreting the Results
+
+**High Risk Churn** indicates:
+- Code that changes frequently without adequate test protection
+- Areas where bugs are most likely to be introduced
+- Prime candidates for refactoring and test coverage improvement
+
+**Low Risk Churn** indicates:
+- Well-tested code that changes frequently (good!)
+- Stable code with high coverage (safe to modify)
+
+### Use Cases
+
+1. **Prioritize Testing Efforts**: Focus on CRITICAL and HIGH risk classes first
+2. **Refactoring Planning**: Target high churn + low coverage areas
+3. **Code Review Focus**: Extra scrutiny for changes in high-risk classes
+4. **Technical Debt Tracking**: Monitor risk levels over time
+
 ## Exporting Reports
 
-You can export the churn report in various formats. The command supports three report types: `html`, `json`, and `csv`.
+You can export the churn report in various formats. The command supports four report types: `html`, `json`, `csv`, and `svg-treemap`.
 
 You must use the `--report-type` option to specify the format and the `--report-file` option to specify the output file name together to generate a report.
 
 ```bash
 bin/phpcca churn <path-to-folder> --report-type=<report-type> --report-file=<filename>
 ```
 
-Supported report types:
+### Supported Report Types
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `html` | Interactive HTML report | Easy sharing and viewing in browsers |
+| `json` | Structured JSON data | Integration with other tools, APIs |
+| `csv` | Comma-separated values | Import into spreadsheets, data analysis |
+| `svg-treemap` | Visual treemap representation | Visual overview of churn distribution |
 
-- `html`: Generates an HTML report.
-- `json`: Generates a JSON report.
-- `csv`: Generates a CSV report.
+### Examples
 
-## When to use
+```bash
+# Generate HTML report
+bin/phpcca churn src --report-type=html --report-file=churn-report.html
+
+# Generate JSON report for CI/CD integration
+bin/phpcca churn src --report-type=json --report-file=churn-report.json
+
+# Generate CSV for spreadsheet analysis
+bin/phpcca churn src --report-type=csv --report-file=churn-report.csv
+
+# Generate SVG treemap for visual analysis
+bin/phpcca churn src --report-type=svg-treemap --report-file=churn-treemap.svg
+```
 
-- To prioritize refactoring or testing efforts.
-- To identify risky or unstable parts of your codebase.
-- To monitor the impact of frequent changes on complex code.
+**Note:** Coverage data is currently only available in console output, not in exported reports.
 
 ## Notes
 
 - Only classes with a valid class name are included in the results.
 - The command supports extensible VCS backends (default is Git).
   - For now only Git is supported.
+- Coverage data is optional; the command works with or without it.
+- When coverage is not found for a class, it assumes 0% coverage for risk calculation.

docs/Churn-Finding-Hotspots.md

@@ -4,6 +4,7 @@
 
 namespace Phauthentic\CognitiveCodeAnalysis\Business\Churn;
 
+use Phauthentic\CognitiveCodeAnalysis\Business\CodeCoverage\CoverageReportReaderInterface;
 use Phauthentic\CognitiveCodeAnalysis\Business\Cognitive\CognitiveMetricsCollection;
 
 /**
@@ -15,13 +16,16 @@ class ChurnCalculator
      * Calculate the churn for each class based on the metrics collection.
      *
      * @param CognitiveMetricsCollection $metricsCollection
+     * @param CoverageReportReaderInterface|null $coverageReader
      * @return array<string, array<string, mixed>>
      */
-    public function calculate(CognitiveMetricsCollection $metricsCollection): array
-    {
+    public function calculate(
+        CognitiveMetricsCollection $metricsCollection,
+        ?CoverageReportReaderInterface $coverageReader = null
+    ): array {
         $classes = [];
         $classes = $this->groupByClasses($metricsCollection, $classes);
-        $classes = $this->calculateChurn($classes);
+        $classes = $this->calculateChurn($classes, $coverageReader);
 
         return $this->sortClassesByChurnDescending($classes);
     }
@@ -41,12 +45,29 @@ public function sortClassesByChurnDescending(array $classes): array
 
     /**
      * @param array<string, array<string, mixed>> $classes
+     * @param CoverageReportReaderInterface|null $coverageReader
      * @return array<string, array<string, mixed>>
      */
-    public function calculateChurn(array $classes): array
+    public function calculateChurn(array $classes, ?CoverageReportReaderInterface $coverageReader = null): array
     {
         foreach ($classes as $className => $data) {
+            // Calculate standard churn
             $classes[$className]['churn'] = $data['timesChanged'] * $data['score'];
+
+            // Add coverage information if available
+            $coverage = null;
+            $riskChurn = null;
+            $riskLevel = null;
+
+            if ($coverageReader !== null) {
+                $coverage = $this->getCoverageForClass($className, $coverageReader);
+                $riskChurn = $data['timesChanged'] * $data['score'] * (1 - $coverage);
+                $riskLevel = $this->calculateRiskLevel($classes[$className]['churn'], $coverage);
+            }
+
+            $classes[$className]['coverage'] = $coverage;
+            $classes[$className]['riskChurn'] = $riskChurn;
+            $classes[$className]['riskLevel'] = $riskLevel;
         }
 
         return $classes;
@@ -77,4 +98,45 @@ public function groupByClasses(CognitiveMetricsCollection $metricsCollection, ar
         }
         return $classes;
     }
+
+    /**
+     * Get coverage for a class, normalizing the class name
+     *
+     * @param string $className
+     * @param CoverageReportReaderInterface $coverageReader
+     * @return float Coverage value between 0.0 and 1.0
+     */
+    private function getCoverageForClass(string $className, CoverageReportReaderInterface $coverageReader): float
+    {
+        // Remove leading backslash for coverage lookup
+        $lookupClassName = ltrim($className, '\\');
+        $coverage = $coverageReader->getLineCoverage($lookupClassName);
+
+        // Return coverage or 0.0 if not found
+        return $coverage ?? 0.0;
+    }
+
+    /**
+     * Calculate risk level based on churn and coverage
+     *
+     * @param float $churn
+     * @param float $coverage
+     * @return string Risk level: CRITICAL, HIGH, MEDIUM, or LOW
+     */
+    private function calculateRiskLevel(float $churn, float $coverage): string
+    {
+        if ($churn > 30 && $coverage < 0.5) {
+            return 'CRITICAL';
+        }
+
+        if ($churn > 20 && $coverage < 0.7) {
+            return 'HIGH';
+        }
+
+        if ($churn > 10 && $coverage < 0.8) {
+            return 'MEDIUM';
+        }
+
+        return 'LOW';
+    }
 }