Cactiplugin_thold/tests/bin/patch-coverage.php

<?php
/*
 +-------------------------------------------------------------------------+
 | Copyright (C) 2004-2026 The Cacti Group                                 |
 |                                                                         |
 | This program is free software; you can redistribute it and/or           |
 | modify it under the terms of the GNU General Public License             |
 | as published by the Free Software Foundation; either version 2          |
 | of the License, or (at your option) any later version.                  |
 +-------------------------------------------------------------------------+
 | Cacti: The Complete RRDtool-based Graphing Solution                     |
 +-------------------------------------------------------------------------+
 | http://www.cacti.net/                                                   |
 +-------------------------------------------------------------------------+
*/

/*
 * Report line coverage for the lines a branch changes.
 *
 * Whole-file coverage is not a useful gate here: most of the plugin only runs
 * inside a live Cacti, so the repository figure would sit near zero no matter
 * how well a change is tested.  What a reviewer wants to know is whether the
 * lines this branch adds are exercised, which is what this measures.
 *
 * Usage: php tests/bin/patch-coverage.php <clover.xml> <base-ref> [min-percent]
 *
 * Exits 1 if coverage is below the threshold, 2 on bad input.
 */

if ($argc < 3) {
	fwrite(STDERR, "usage: patch-coverage.php <clover.xml> <base-ref> [min-percent]\n");

	exit(2);
}

$clover_path = $argv[1];
$base_ref    = $argv[2];
$minimum     = isset($argv[3]) ? (float) $argv[3] : 100.0;

if (!is_readable($clover_path)) {
	fwrite(STDERR, "cannot read coverage report: $clover_path\n");

	exit(2);
}

/**
 * Line numbers each measured file changed, keyed by repository-relative path.
 *
 * Only added and modified lines count. Deletions have nothing left to cover,
 * and context lines were not part of this change.
 *
 * Paths stay repository-relative so the report can be produced in a container
 * and evaluated on the host, where the absolute paths differ.
 *
 * @param string $base_ref Git ref to diff against.
 *
 * @return array<string, array<int, bool>>
 */
function changed_lines($base_ref) {
	$command = 'git diff --no-ext-diff --unified=0 --no-color --diff-filter=AM ' . escapeshellarg($base_ref) . '...HEAD -- "*.php"';
	$output  = [];
	$status  = 0;

	$last_line = exec($command, $output, $status);

	if ($last_line === false || $status !== 0) {
		fwrite(STDERR, "git diff failed\n");

		exit(2);
	}

	$diff = implode("\n", $output);

	$changed = [];
	$file    = null;

	foreach (explode("\n", $diff) as $line) {
		if (strncmp($line, '+++ b/', 6) === 0) {
			$file           = substr($line, 6);

			if (strncmp($file, 'tests/', 6) === 0) {
				$file = null;

				continue;
			}

			$changed[$file] = [];
		} elseif (strncmp($line, '@@', 2) === 0 && $file !== null) {
			if (preg_match('/\+(\d+)(?:,(\d+))?/', $line, $match)) {
				$start = (int) $match[1];
				$count = isset($match[2]) ? (int) $match[2] : 1;

				for ($i = 0; $i < $count; $i++) {
					$changed[$file][$start + $i] = true;
				}
			}
		}
	}

	return $changed;
}

$changed = changed_lines($base_ref);
$clover  = simplexml_load_file($clover_path);

if ($clover === false) {
	fwrite(STDERR, "cannot parse coverage report: $clover_path\n");

	exit(2);
}

$covered  = 0;
$total    = 0;
$missing  = [];
$measured = [];

foreach ($clover->xpath('//file') as $file) {
	$path     = (string) $file['name'];
	$relative = null;

	foreach (array_keys($changed) as $candidate) {
		if ($path === $candidate || substr($path, -strlen('/' . $candidate)) === '/' . $candidate) {
			$relative = $candidate;

			break;
		}
	}

	if ($relative === null) {
		continue;
	}

	$measured[$relative] = true;

	foreach ($file->line as $line) {
		$number = (int) $line['num'];

		// Only statement lines are measurable; method markers double-count.
		if ((string) $line['type'] !== 'stmt' || !isset($changed[$relative][$number])) {
			continue;
		}

		$total++;

		if ((int) $line['count'] > 0) {
			$covered++;
		} else {
			$missing[] = $relative . ':' . $number;
		}
	}
}

/*
 * These entry points require a complete running Cacti and cannot safely be
 * loaded into the isolated unit process. Keep the exception explicit: any
 * newly changed production PHP file must either appear in Clover or be added
 * here with reviewable justification.
 */
$unmeasured_allowlist = [
	// Database migration/schema declarations require a live Cacti database.
	'includes/database.php',
	// Authenticated web entry point; its status mapping lives in the covered
	// thold_notification_queue_status_cells() helper.
	'notify_queue.php',
	'thold_notify.php',
	// Daemon entry point: does CLI bootstrap, pcntl signal handling, and
	// argv parsing at the top level, so it cannot be require()'d into the
	// isolated unit process. Its persistence/evaluation logic lives in the
	// covered thold_daemon_persist_sample()/thold_check_threshold() helpers.
	'thold_process.php',
	// CLI entry points: include cli_check.php / chdir and execute at the
	// top level, so they cannot be require()'d into the isolated unit process.
	'cli_import.php',
	'cli_thresholds.php',
	// Poller entry point: bootstraps the poller environment and executes
	// at the top level, so it cannot be require()'d into the isolated unit
	// process.
	'poller_thold.php',
	// Authenticated web entry points: chdir + include(auth.php) and several
	// lib/* includes at the top level, so they cannot be require()'d into
	// the isolated unit process.
	'thold.php',
	'thold_graph.php',
	'thold_templates.php',
	'notify_lists.php',
	// Daemon entry point, same category as thold_process.php above (pcntl
	// signal handling at the top level).
	'thold_daemon.php',
	// Settings-page and header-tab-bar hook callbacks: only meaningful when
	// invoked by Cacti's plugin hook dispatcher inside a live page render,
	// with the real $settings/$config arrays and database populated.
	'includes/settings.php',
	'includes/tab.php',
	// Web-page action handlers (thold_wizard() et al.) that read $_REQUEST
	// and read/write the Cacti database directly; only meaningful inside a
	// live authenticated request, not the isolated unit process.
	'includes/webapi.php',
];
$unmeasured            = array_values(array_diff(array_keys($changed), array_keys($measured)));
$unexpected_unmeasured = array_values(array_diff($unmeasured, $unmeasured_allowlist));

if ($unmeasured !== []) {
	print "Changed production PHP files absent from Clover:\n  " . implode("\n  ", $unmeasured) . "\n";
}

if ($unexpected_unmeasured !== []) {
	print "FAIL: changed production PHP files are not measured or allowlisted:\n  "
		. implode("\n  ", $unexpected_unmeasured) . "\n";

	exit(1);
}

if ($total === 0) {
	print "Patch coverage: no measured lines changed.\n";

	exit(0);
}

$percent = ($covered / $total) * 100;

printf("Patch coverage: %.2f%% (%d/%d lines)\n", $percent, $covered, $total);

if ($missing !== []) {
	print "Uncovered changed lines:\n  " . implode("\n  ", $missing) . "\n";
}

if ($percent + 0.005 < $minimum) {
	printf("FAIL: below the %.2f%% minimum.\n", $minimum);

	exit(1);
}

exit(0);