Merge pull request #12 from script-development/ci/coverage-gate-pcov

ci: add line-coverage measurement and threshold gate

Author: Goosterhof

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
               uses: shivammathur/setup-php@v2
               with:
                   php-version: ${{ matrix.php }}
-                  coverage: none
+                  coverage: pcov
                   tools: composer:v2
 
             - name: Install dependencies
@@ -35,5 +35,17 @@ jobs:
             - name: Static analysis (self)
               run: composer phpstan
 
-            - name: Tests
-              run: composer test
+            - name: Tests with coverage
+              run: composer test:coverage
+
+            - name: Coverage threshold gate
+              run: composer coverage:check
+
+            - name: Upload coverage report
+              if: always()
+              uses: actions/upload-artifact@v4
+              with:
+                  name: clover-php-${{ matrix.php }}
+                  path: build/logs/clover.xml
+                  retention-days: 14
+                  if-no-files-found: ignore

CHANGELOG.md

@@ -10,6 +10,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 - **`LogRule` (BREAKING):** extended to cover the static-call shapes `Model::destroy(...)` and `Model::forceDestroy(...)` on Log-named classes. `getNodeType()` broadened from `MethodCall::class` to `CallLike::class` and `processNode` branches on `MethodCall` vs `StaticCall`. Both shapes emit the same `logRule.logModification` identifier so consumer `phpstan.neon` `ignoreErrors` entries cover the whole rule with one identifier (the previous rule's compliance teeth depended on `delete`/`forceDelete` instance shapes; on a non-soft-delete log model `Model::destroy([1])` purges and `Model::forceDestroy([1])` always purges — both slipped through). `DB::table('logs')->truncate()` is intentionally still out of scope — Builder receiver type carries no Log-named class reference and the table name lives in a string argument; matching that needs a shape-specific call-chain rule. Tracked separately. Versioning: per ADR-0021 §Versioning, this is a Major bump (new errors in code that previously passed); within 0.x this ships as `v0.3.0`. **Pre-cascade audit required across emmie, kendo, entreezuil, ublgenie before tagging** — surface any `::destroy(`/`::forceDestroy(` calls on Log-named classes and route operational-log false positives to consumer-side `phpstan.neon` `ignoreErrors` (same convention used in v0.2.0 for `ublgenie/app/Actions/DeleteBranch.php`). Resolves issue #4.
 - **CI:** added PHP 8.5 to the `ci.yml` and `release.yml` test matrices alongside 8.4 (`['8.4']` → `['8.4', '8.5']`). PHP 8.5.0 was released 2025-11-20; the war-room dev environment already runs 8.5.5 locally, so PRs were getting ad-hoc 8.5 coverage during pre-push but no CI signal. Adding (rather than replacing) keeps 8.4 — the `composer.json` `^8.4` contractual minimum — covered. `shivammathur/setup-php@v2` supports 8.5 since GA. Resolves issue #5.
+- **CI:** added line-coverage measurement and a threshold gate. `ci.yml` switches `coverage: none` → `coverage: pcov` on both 8.4 and 8.5 matrix legs (PCOV is line-coverage-only and faster than Xdebug — debugger features aren't needed). New composer scripts: `test:coverage` (runs PHPUnit with `--coverage-clover=build/logs/clover.xml --coverage-text`) and `coverage:check` (runs `bin/coverage-check.php`, a standalone clover parser — no extra runtime dependency added to a static-analysis package for a single CI gate). Two new CI steps replace the `Tests` step: **Tests with coverage** and **Coverage threshold gate**. Clover XML is uploaded as a per-leg artifact (`clover-php-${{ matrix.php }}`, 14-day retention) so reviewers can inspect uncovered lines without spelunking through workflow logs. **Initial threshold: 83%** — the measured baseline is 83.92% (240/286 lines across `src/`), set 0.92 percentage points lower to absorb trivial fluctuation on equivalent-but-renamed code. Class coverage (0/6) and method coverage (39%) are intentionally unmeasured by the gate v1; per the issue's deliberation, line coverage is the right v1 signal and branch/method coverage is a follow-up after the line gate is bedded in. The 16-percentage-point gap to 100% audits as defensive guard clauses on unexpected node shapes (the kind of branch the issue itself flagged as "genuinely hard to fixture" — `LogRule`'s static-call branch falls back when `$node->class` is `Expr` rather than `Name`); a follow-up issue will audit and ratchet the threshold upward to 90%+. Versioning: none (pure CI/test-infra, no consumer-visible behaviour). Resolves issue #9.
 
 ## [0.2.0] — 2026-05-04
 

bin/coverage-check.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types = 1);
+
+/**
+ * Parse a PHPUnit clover XML report and fail if line coverage falls below
+ * a threshold. Standalone script — no Composer/runtime dependency on a
+ * coverage-check library, since the package itself is consumed as a static-
+ * analysis library and adding a runtime dep for a single CI gate is overhead
+ * without commensurate value.
+ *
+ * Usage: php bin/coverage-check.php <clover.xml> <threshold>
+ */
+$cloverPath = $argv[1] ?? null;
+$threshold = isset($argv[2]) ? (float) $argv[2] : null;
+
+if ($cloverPath === null || $threshold === null) {
+    fwrite(\STDERR, "Usage: coverage-check.php <clover.xml> <threshold>\n");
+    exit(2);
+}
+
+if (!is_file($cloverPath)) {
+    fwrite(\STDERR, "Clover report not found: {$cloverPath}\n");
+    exit(2);
+}
+
+$xml = simplexml_load_file($cloverPath);
+
+if ($xml === false) {
+    fwrite(\STDERR, "Failed to parse clover XML: {$cloverPath}\n");
+    exit(2);
+}
+
+$metrics = $xml->project->metrics ?? null;
+
+if ($metrics === null) {
+    fwrite(\STDERR, "No <project><metrics> element in clover XML\n");
+    exit(2);
+}
+
+$statements = (int) $metrics['statements'];
+$covered = (int) $metrics['coveredstatements'];
+
+if ($statements === 0) {
+    fwrite(\STDERR, "No statements measured — cannot evaluate coverage\n");
+    exit(2);
+}
+
+$percent = ($covered / $statements) * 100.0;
+
+printf("Line coverage: %.2f%% (%d/%d) — threshold: %.2f%%\n", $percent, $covered, $statements, $threshold);
+
+if ($percent + 1e-9 < $threshold) {
+    fwrite(\STDERR, "FAIL: line coverage below threshold\n");
+    exit(1);
+}
+
+echo "PASS\n";
+exit(0);

composer.json

@@ -47,6 +47,8 @@
     },
     "scripts": {
         "test": "phpunit",
+        "test:coverage": "phpunit --coverage-clover=build/logs/clover.xml --coverage-text",
+        "coverage:check": "@php bin/coverage-check.php build/logs/clover.xml 83",
         "phpstan": "phpstan analyse",
         "format": "pint",
         "format:check": "pint --test"