<?php
/**
 * AI crawler policy module.
 *
 * @package AcidStudios\AEO
 */

declare(strict_types=1);

namespace AcidStudios\AEO\Modules;

use AcidStudios\AEO\AbstractModule;
use AcidStudios\AEO\Audit\Check;
use AcidStudios\AEO\Audit\Checks;
use AcidStudios\AEO\Data\SiteData;
use AcidStudios\AEO\Detect\Environment;
use AcidStudios\AEO\Generators\RobotsGenerator;
use AcidStudios\AEO\Options;

defined( 'ABSPATH' ) || exit;

/**
 * Appends the site's AI crawler rules to the virtual robots.txt.
 *
 * Runs at priority 20 so anything WordPress core and other plugins add is
 * already in `$output` and can be preserved (and de-duplicated against).
 */
final class RobotsPolicy extends AbstractModule {

	/**
	 * Machine name, matching the settings section the module reads.
	 *
	 * @return string Module slug.
	 */
	public function slug(): string {
		return 'policy';
	}

	/**
	 * Human readable, translated module name.
	 *
	 * @return string Module title.
	 */
	public function title(): string {
		return __( 'AI crawler policy', 'acid-aeo' );
	}

	/**
	 * Priority the robots.txt filter runs at.
	 *
	 * Deliberately late. The generator drops a `Sitemap:` line that the text it
	 * is handed already carries, and it can only dedupe against what has been
	 * written by the time it runs: Yoast SEO appends its own block — sitemap
	 * line included — well after priority 20, so running early produced a
	 * robots.txt naming the same sitemap twice. Running last means every other
	 * plugin has had its say, and the block lands at the end of the file, which
	 * robots.txt does not care about: a crawler matches its own group wherever
	 * it sits.
	 *
	 * @var int
	 */
	private const FILTER_PRIORITY = 100000;

	/**
	 * Hooks the module into WordPress.
	 *
	 * @return void
	 */
	public function register(): void {
		add_filter( 'robots_txt', [ $this, 'filter' ], self::FILTER_PRIORITY, 2 );
	}

	/**
	 * Appends the AI crawler block to robots.txt.
	 *
	 * The module's own switch is read here rather than only at boot. `Plugin`
	 * registers this filter only for an enabled module, but that is not the
	 * only way it gets attached: `Rest\Handlers\Preview` hooks a fresh instance
	 * in to render a preview, and a preview may be rendering a draft that
	 * switches the policy off. A disabled policy has to mean an untouched
	 * robots.txt wherever the filter runs from.
	 *
	 * @param string $output    robots.txt content built so far.
	 * @param mixed  $is_public Whether the site is set to be indexed (`blog_public`).
	 * @return string Filtered robots.txt content.
	 */
	public function filter( $output, $is_public ): string {
		$output = is_string( $output ) ? $output : '';

		if ( ! $is_public || ! (bool) Options::get( 'policy.enabled', true ) ) {
			return $output;
		}

		$policy = SiteData::policy() + [
			'existing' => $output,
			'sitemaps' => [ SiteData::file_urls()['sitemap'] ],
		];

		return rtrim( $output ) . "\n\n" . ( new RobotsGenerator() )->generate( $policy );
	}

	/**
	 * Audit checks contributed by this module.
	 *
	 * @return array<int,Check> Checks.
	 */
	public function checks(): array {
		$slug = $this->slug();
		$url  = home_url( '/robots.txt' );

		return [
			Checks::reachable(
				'robots_reachable',
				$slug,
				__( 'robots.txt is reachable', 'acid-aeo' ),
				$url,
				[
					'weight' => Check::WEIGHT_CRITICAL,
					'fix'    => 'flush_rewrite',
				]
			),
			Checks::observed(
				'robots_has_ai_policy',
				$slug,
				__( 'AI crawler rules in robots.txt', 'acid-aeo' ),
				$url,
				static fn( string $body ): bool => false !== strpos( $body, 'User-agent: GPTBot' ),
				[
					'ok'     => __( 'robots.txt names the AI crawlers your policy decides about, one group each.', 'acid-aeo' ),
					'bad'    => __( 'robots.txt is served but carries no AI crawler rules, so every assistant falls back to its own defaults.', 'acid-aeo' ),
					'weight' => Check::WEIGHT_CRITICAL,
					'fix'    => 'flush_rewrite',
				]
			),
			Checks::observed(
				'robots_content_signal',
				$slug,
				__( 'Content-Signal in robots.txt', 'acid-aeo' ),
				$url,
				static fn( string $body ): bool => false !== strpos( $body, 'Content-Signal:' ),
				[
					'ok'     => __( 'robots.txt states what your content may be used for.', 'acid-aeo' ),
					'bad'    => __( 'robots.txt carries no Content-Signal line, so a crawler learns which bots may read the site but not what it may do with what it reads.', 'acid-aeo' ),
					'status' => Check::WARN,
					'weight' => Check::WEIGHT_IMPORTANT,
					'fix'    => 'flush_rewrite',
				]
			),
			$this->physical_file(),
		];
	}

	/**
	 * Whether a robots.txt on disk is shadowing the generated one.
	 *
	 * The web server answers a request for a file that exists before WordPress
	 * ever sees it, so a robots.txt in the site root silently replaces the
	 * whole policy.
	 *
	 * @return Check The finding.
	 */
	private function physical_file(): Check {
		$files = Environment::detect()['physical_files'] ?? [];
		$label = __( 'No robots.txt on disk', 'acid-aeo' );

		if ( empty( $files['robots.txt'] ) ) {
			return Check::pass(
				'robots_physical_file',
				$this->slug(),
				$label,
				__( 'Nothing on disk shadows the robots.txt WordPress serves.', 'acid-aeo' ),
				Check::WEIGHT_CRITICAL
			);
		}

		return Check::fail(
			'robots_physical_file',
			$this->slug(),
			$label,
			__( 'A robots.txt file sits in the site root. The web server answers with that file, so nothing this plugin generates is ever read. Delete or rename it.', 'acid-aeo' ),
			Check::WEIGHT_CRITICAL
		);
	}
}