<?php
/**
 * Module 6: the aggregate Conflict Detector report and its cache lifecycle.
 *
 * @package PressRoost\AIVE
 */

namespace PressRoost\AIVE\Modules;

use PressRoost\AIVE\Conflict\ConflictCache;
use PressRoost\AIVE\Conflict\ConflictReport;
use PressRoost\AIVE\ModuleInterface;
use PressRoost\AIVE\Utils\Helpers;

/**
 * Wires the Conflict Detector's cache invalidation and exposes its state.
 *
 * This module has no frontend behaviour of its own: it neither emits nor
 * intercepts a public response, so it attaches no public hook. Its only job
 * is keeping the cached aggregate report current for the admin screen and for
 * the statistics a later Dashboard will read, which is why `register_hooks()`
 * attaches only cache-invalidation actions.
 *
 * The invalidation hooks are registered unconditionally, the same way every
 * other module in this plugin attaches its own cache invalidation regardless
 * of its own enable setting - the cost is one more no-op `delete_transient()`
 * call on an already-rare option update, and the alternative is a stale cache
 * surviving a save that re-enables the module. `report()` and `stats()` are
 * what actually gate on the setting: when `enable_conflict_detector` is off,
 * they report the module as disabled and contribute nothing, without ever
 * invoking a delegated feature's ownership check merely to populate a report.
 *
 * @since 1.6.0
 */
final class ConflictDetector implements ModuleInterface {

	/**
	 * Module slug, which also keys `enable_conflict_detector` in settings.
	 *
	 * @since 1.6.0
	 * @var string
	 */
	public const SLUG = 'conflict_detector';

	/**
	 * Returns the module slug.
	 *
	 * @since 1.6.0
	 *
	 * @return string Module slug.
	 */
	public function slug() {
		return self::SLUG;
	}

	/**
	 * Attaches the module's cache-invalidation hooks.
	 *
	 * Covers the same settings, visibility and plugin-activation inputs the
	 * other features' caches invalidate on, plus the specific options the
	 * robots, schema and llms.txt ownership adapters read as evidence. Each
	 * hook passes arguments `ConflictCache::flush()` does not declare, which
	 * PHP ignores. Belt-and-braces by design: a change to any of these would
	 * already move `ConflictReport::fingerprint()`, but deleting the entry
	 * keeps the options table from holding an hour of an unreachable row.
	 *
	 * @since 1.6.0
	 *
	 * @return void
	 */
	public function register_hooks() {
		$invalidators = array(
			'add_option_' . Helpers::OPTION_KEY,
			'update_option_' . Helpers::OPTION_KEY,
			'delete_option_' . Helpers::OPTION_KEY,
			'add_option_blog_public',
			'update_option_blog_public',
			'update_option_active_plugins',
			'update_site_option_active_sitewide_plugins',
			'activated_plugin',
			'deactivated_plugin',

			// Evidence the robots, schema and llms.txt ownership adapters read.
			'add_option_wpseo',
			'update_option_wpseo',
			'add_option_rank_math_modules',
			'update_option_rank_math_modules',
			'add_option_rank-math-options-general',
			'update_option_rank-math-options-general',
			'add_option_rank-math-options-titles',
			'update_option_rank-math-options-titles',
			'add_option_aioseo_options',
			'update_option_aioseo_options',
			'add_option_seopress_toggle',
			'update_option_seopress_toggle',
			'add_option_seopress_pro_option_name',
			'update_option_seopress_pro_option_name',
		);

		foreach ( $invalidators as $hook ) {
			add_action( $hook, array( ConflictCache::class, 'flush' ) );
		}
	}

	/**
	 * Returns the module's current state for the admin screen.
	 *
	 * Never recomputes: it reads the cache, or reports `not-run`. When the
	 * module is disabled, `report` is null and nothing else contributes -
	 * no cached report is read or shown, however fresh it might still be.
	 *
	 * @since 1.6.0
	 *
	 * @return array{enabled: bool, report: array<string, mixed>|null, fresh: bool} Current state.
	 */
	public static function report() {
		if ( ! Helpers::is_module_enabled( self::SLUG ) ) {
			return array(
				'enabled' => false,
				'report'  => null,
				'fresh'   => false,
			);
		}

		$cached = ConflictCache::cached();

		if ( null === $cached ) {
			return array(
				'enabled' => true,
				'report'  => ConflictReport::not_run(),
				'fresh'   => false,
			);
		}

		return array(
			'enabled' => true,
			'report'  => $cached['report'],
			'fresh'   => $cached['fresh'],
		);
	}

	/**
	 * Recomputes the report and stores it, superseding any cached entry.
	 *
	 * Only an authorised admin request may call this; see
	 * `ConflictDetectorPage`, which checks `manage_options` and a dedicated
	 * nonce before it does. Not attached to any hook, so no cron, REST, AJAX
	 * or front-end path can reach it.
	 *
	 * @since 1.6.0
	 *
	 * @return array<string, mixed> Freshly computed report.
	 */
	public static function retest() {
		return ConflictCache::store( ConflictReport::build() );
	}

	/**
	 * Returns the statistics a later Dashboard will consume.
	 *
	 * Reads whatever `report()` currently has - never recomputes - so this is
	 * safe to call from anywhere, including a frontend request. A disabled
	 * module, or one that has never completed a report, contributes zero to
	 * every count rather than a fabricated figure.
	 *
	 * @since 1.6.0
	 *
	 * @return array{active_conflict_count: int, unknown_feature_count: int, unavailable_feature_count: int, active_supported_plugins: int} Statistics.
	 */
	public static function stats() {
		$state = self::report();

		if ( ! $state['enabled'] || null === $state['report'] ) {
			return array(
				'active_conflict_count'     => 0,
				'unknown_feature_count'     => 0,
				'unavailable_feature_count' => 0,
				'active_supported_plugins'  => 0,
			);
		}

		return $state['report']['stats'];
	}
}