feat(coverage): add CoverageSummary and CoverageSummaryLoader for programmatic access to PHPUnit coverage data

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

docs/api/phpunit-support.rst

@@ -19,9 +19,55 @@ The packaged test configuration includes a small integration layer under
    * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``
      - Enables ``DG\BypassFinals``
      - Allows tests to work with final constructs.
-   * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
-     - Sends desktop notifications
-     - Summarizes pass, failure, error, runtime, and memory data.
+    * - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
+      - Sends desktop notifications
+      - Summarizes pass, failure, error, runtime, and memory data.
+    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoaderInterface``
+      - Loads PHPUnit coverage reports
+      - Contract for loading serialized PHP coverage data.
+    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader``
+      - Loads PHPUnit coverage reports
+      - Implementation that reads ``coverage-php`` output.
+    * - ``FastForward\DevTools\PhpUnit\Coverage\CoverageSummary``
+      - Represents line coverage metrics
+      - Provides executed lines, total executable lines, and percentage calculations.
+
+Coverage Report Loading
+-----------------------
+
+DevTools provides a reusable layer for loading PHPUnit's serialized
+``coverage-php`` output. This is useful when you need to extract line
+coverage metrics programmatically.
+
+``CoverageSummaryLoaderInterface`` defines the contract:
+
+.. code-block:: php
+
+   namespace FastForward\DevTools\PhpUnit\Coverage;
+
+   interface CoverageSummaryLoaderInterface
+   {
+       public function load(string $coverageReportPath): CoverageSummary;
+   }
+
+``CoverageSummaryLoader`` implements this contract:
+
+.. code-block:: php
+
+   use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader;
+
+   $loader = new CoverageSummaryLoader();
+   $summary = $loader->load('public/coverage/coverage.php');
+
+   $summary->executedLines();      // Number of covered lines
+   $summary->executableLines();   // Total number of executable lines
+   $summary->percentage();        // Coverage as float (0-100)
+   $summary->percentageAsString(); // Formatted string like "85.50%"
+
+.. note::
+
+   The loader expects the PHP file produced by PHPUnit's ``--coverage-php`` option.
+   It must contain a ``SebastianBergmann\CodeCoverage\CodeCoverage`` instance.
 
 These classes are especially relevant when a consumer project overrides the
 packaged ``phpunit.xml`` and wants to preserve the same runtime behavior.

docs/usage/testing-and-coverage.rst

@@ -52,6 +52,25 @@ That extension wires together:
   which sends a desktop notification after the run when the local platform
   supports it.
 
+Programmatic Coverage Access
+-----------------------------
+
+The ``CoverageSummaryLoader`` class provides programmatic access to coverage
+data. This is useful when you need to integrate coverage metrics into
+external tooling or build custom reports:
+
+.. code-block:: php
+
+   use FastForward\DevTools\PhpUnit\Coverage\CoverageSummaryLoader;
+
+   $loader = new CoverageSummaryLoader();
+   $summary = $loader->load('public/coverage/coverage.php');
+
+   $summary->executedLines();      // e.g., 142
+   $summary->executableLines();   // e.g., 168
+   $summary->percentage();        // e.g., 84.52
+   $summary->percentageAsString(); // e.g., "84.52%"
+
 When to Override Locally
 ------------------------
 

src/PhpUnit/Coverage/CoverageSummary.php

@@ -24,32 +24,40 @@
 final readonly class CoverageSummary
 {
     /**
-     * @param int $executedLines the number of executable lines that were covered
-     * @param int $executableLines the total number of executable lines
+     * Initializes a new instance of the CoverageSummary class.
+     *
+     * @param int $executedLines Number of executable lines covered
+     * @param int $executableLines Total executable lines in the analyzed code
      */
     public function __construct(
         private int $executedLines,
         private int $executableLines,
     ) {}
 
     /**
-     * @return int the number of covered executable lines
+     * Returns the number of executable lines that were executed.
+     *
+     * @return int
      */
     public function executedLines(): int
     {
         return $this->executedLines;
     }
 
     /**
-     * @return int the total number of executable lines
+     * Returns the total number of executable lines.
+     *
+     * @return int
      */
     public function executableLines(): int
     {
         return $this->executableLines;
     }
 
     /**
-     * @return float the executed line coverage percentage
+     * Returns the executed line coverage as a percentage.
+     *
+     * @return float
      */
     public function percentage(): float
     {
@@ -61,7 +69,9 @@ public function percentage(): float
     }
 
     /**
-     * @return string the formatted executed line coverage percentage
+     * Returns the executed line coverage as a formatted percentage string.
+     *
+     * @return string
      */
     public function percentageAsString(): string
     {

src/PhpUnit/Coverage/CoverageSummaryLoader.php

@@ -29,9 +29,11 @@
 final readonly class CoverageSummaryLoader implements CoverageSummaryLoaderInterface
 {
     /**
-     * @param string $coverageReportPath the path to the PHPUnit `coverage-php` report
+     * @param string $coverageReportPath Path to the PHPUnit `coverage-php` report file
      *
-     * @return CoverageSummary the extracted line coverage summary
+     * @return CoverageSummary Extracted line coverage summary
+     *
+     * @throws RuntimeException When the report file does not exist or contains invalid data
      */
     public function load(string $coverageReportPath): CoverageSummary
     {

src/PhpUnit/Coverage/CoverageSummaryLoaderInterface.php

@@ -24,9 +24,13 @@
 interface CoverageSummaryLoaderInterface
 {
     /**
-     * @param string $coverageReportPath the path to the PHPUnit `coverage-php` report
+     * Loads the coverage summary from a PHPUnit `coverage-php` report file.
      *
-     * @return CoverageSummary the extracted coverage summary
+     * @param string $coverageReportPath Path to the PHPUnit `coverage-php` report file
+     *
+     * @return CoverageSummary Extracted coverage summary
+     *
+     * @throws RuntimeException When the report file does not exist or contains invalid data
      */
     public function load(string $coverageReportPath): CoverageSummary;
 }