<?php
/**
 * Module 2: per-bot robots.txt policy and its generated output.
 *
 * @package PressRoost\AIVE
 */

namespace PressRoost\AIVE\Modules;

use PressRoost\AIVE\ModuleInterface;
use PressRoost\AIVE\Robots\RobotsAudit;
use PressRoost\AIVE\Robots\RobotsMarkers;
use PressRoost\AIVE\Robots\RobotsOwnership;
use PressRoost\AIVE\Robots\RobotsParser;
use PressRoost\AIVE\Utils\Helpers;

/**
 * Writes the site's AI bot policy into the robots.txt WordPress generates.
 *
 * What this module controls and what it does not, stated first because the
 * distinction is the whole feature:
 *
 * - It controls what the site *declares*. A `Disallow` is a request, honoured
 *   by the crawlers that choose to honour it. Nothing here authenticates a
 *   crawler or enforces anything, and no number on the audit screen should be
 *   read as access control.
 * - It only ever writes to the response WordPress generates. A physical
 *   `robots.txt` in the web root is served by the web server and never reaches
 *   PHP, so a site with one gets no contribution from this module at all - see
 *   `RobotsOwnership`, which owns that decision and every other precedence
 *   question.
 * - It writes inside one bounded marker block and nowhere else. Text outside
 *   the markers belongs to WordPress, another plugin or the site owner, and is
 *   passed through unchanged.
 *
 * Two deliberate omissions in the generated output. A bot already named by a
 * group outside the markers gets no AIVE group: the existing rule is
 * authoritative, and a second group for the same token is exactly the duplicate
 * output this module exists to avoid. And a bot set to Don't manage gets no
 * group either, which is what makes that setting different from Allow - it
 * leaves the bot to whatever `User-agent: *` says.
 *
 * The module slug is `robots_audit`, matching the `enable_robots_audit` key the
 * settings array has carried since 1.0.0. Renaming it would orphan that key on
 * every existing install for no behavioural gain.
 *
 * @since 1.2.0
 */
final class RobotsPolicy implements ModuleInterface {

	/**
	 * Module slug, which also keys `enable_robots_audit` in settings.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const SLUG = 'robots_audit';

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

	/**
	 * Attaches the module's WordPress hooks.
	 *
	 * The enable setting is read inside the filter rather than here, for the
	 * reason Module 1 states: hooks are registered once per request, so
	 * deciding at registration time would freeze the answer for the whole
	 * request and an administrator could not observe a saved setting taking
	 * effect.
	 *
	 * The invalidation hooks cover the three inputs an audit result depends on
	 * besides the response itself: the saved policy, the site's visibility, and
	 * which plugins are active - the last of which is what ownership is decided
	 * from. Each hook passes arguments `RobotsAudit::flush()` does not declare,
	 * which PHP ignores.
	 *
	 * @since 1.2.0
	 *
	 * @return void
	 */
	public function register_hooks() {
		add_filter( 'robots_txt', array( $this, 'filter_robots_txt' ), 10, 2 );

		$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',
		);

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

	/**
	 * Adds AIVE's managed block to the generated robots.txt response.
	 *
	 * Returns the input unchanged whenever AIVE must not write: the module is
	 * off, something else owns the file, or the response carries marker text
	 * that cannot be safely replaced.
	 *
	 * @since 1.2.0
	 *
	 * @param string|mixed $output    Robots.txt response assembled so far.
	 * @param bool|mixed   $is_public Whether the site asks to be indexed.
	 * @return string Response text, with AIVE's block when AIVE owns one.
	 */
	public function filter_robots_txt( $output, $is_public = true ) {
		$output = is_string( $output ) ? $output : '';

		if ( ! Helpers::is_module_enabled( self::SLUG ) ) {
			return $output;
		}

		/*
		 * WordPress's own view of the request, taken from the argument rather
		 * than re-read, so that a site filtering `blog_public` for this request
		 * is respected as well as the stored option that ownership reads.
		 */
		if ( ! (bool) $is_public ) {
			return $output;
		}

		if ( ! RobotsOwnership::allows_injection( RobotsOwnership::detect() ) ) {
			return $output;
		}

		if ( RobotsMarkers::STATE_MALFORMED === RobotsMarkers::state( $output ) ) {
			return $output;
		}

		// Everything outside AIVE's own previous block, which is what it replaces.
		$base  = RobotsMarkers::strip( $output );
		$lines = $this->managed_lines( $base );

		if ( array() === $lines ) {
			return $base;
		}

		$prefix = $base;

		if ( '' !== $prefix && "\n" !== substr( $prefix, -1 ) ) {
			$prefix .= "\n";
		}

		return $prefix . "\n" . RobotsMarkers::wrap( $lines );
	}

	/**
	 * Builds the directive lines AIVE contributes for the current policy.
	 *
	 * @since 1.2.0
	 *
	 * @param string $existing_output Response text outside AIVE's markers.
	 * @return array<int, string> Directive lines, without the markers.
	 */
	public function managed_lines( $existing_output ) {
		$named = RobotsParser::agents( $existing_output );
		$lines = array();

		foreach ( Helpers::effective_bot_rules() as $token => $rule ) {
			if ( Helpers::RULE_NONE === $rule ) {
				continue;
			}

			// An existing group for this token stays authoritative.
			if ( isset( $named[ strtolower( $token ) ] ) ) {
				continue;
			}

			if ( array() !== $lines ) {
				$lines[] = '';
			}

			$lines[] = 'User-agent: ' . $token;

			if ( Helpers::RULE_ALLOW === $rule ) {
				/*
				 * The Disallow accompanying an Allow keeps the admin area out of
				 * a crawl the site is otherwise inviting. It mirrors what
				 * WordPress itself writes for `User-agent: *`.
				 */
				$lines[] = 'Allow: /';
				$lines[] = 'Disallow: /wp-admin/';

				continue;
			}

			$lines[] = 'Disallow: /';
		}

		return $lines;
	}

	/**
	 * Returns the generated robots.txt response without AIVE's contribution.
	 *
	 * Used by the admin screen to see the response as it would be if this
	 * module were not installed, which is the only way to tell marker text
	 * AIVE wrote from marker text left behind by a hand edit. Detaching and
	 * reattaching the filter around the call is what keeps it from recursing.
	 *
	 * @since 1.2.0
	 *
	 * @return string Generated response text without AIVE's block.
	 */
	public function foreign_output() {
		remove_filter( 'robots_txt', array( $this, 'filter_robots_txt' ), 10 );

		$output = RobotsAudit::local_output();

		add_filter( 'robots_txt', array( $this, 'filter_robots_txt' ), 10, 2 );

		return $output;
	}
}