<?php
/**
 * The ai.txt 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\Endpoints\Router;
use AcidStudios\AEO\Generators\AiTxtGenerator;
use AcidStudios\AEO\Options;

defined( 'ABSPATH' ) || exit;

/**
 * Publishes `/ai.txt`: the AI crawler policy, in a file AI tooling looks for.
 *
 * There is no standard behind `ai.txt`, so the file is secondary by design: it
 * mirrors the policy that robots.txt and the `Content-Signal` header state, and
 * says as much in its own header. Because both files are rendered from
 * `Data\SiteData::policy()` through the same generator code, they cannot
 * contradict each other.
 */
final class AiTxt extends AbstractModule {

	/**
	 * What the file says while the policy module is switched off.
	 *
	 * The file keeps answering — a 404 where a crawler expected a policy reads
	 * as a misconfiguration, and this file exists to be unambiguous — but it
	 * states nothing, because `policy.enabled` is the one switch for the whole
	 * policy surface and robots.txt and the `Content-Signal` header have gone
	 * quiet with it. The marker line stays so that a physical copy written by
	 * `Modules\StaticFiles` is still recognised as this plugin's to remove.
	 *
	 * @var string
	 */
	private const DISABLED_BODY = "# AI policy module disabled\n# generated by Acid AEO\n";

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

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

	/**
	 * Hooks the module into WordPress.
	 *
	 * @return void
	 */
	public function register(): void {
		Router::add_file( 'ai_txt', 'ai\.txt', 'text/plain', [ $this, 'render' ], [ 'path' => 'ai.txt' ] );

		add_action( 'acid_aeo_settings_updated', [ $this, 'on_settings_updated' ] );
	}

	/**
	 * Renders `/ai.txt`.
	 *
	 * @return string File body.
	 */
	public function render(): string {
		if ( ! (bool) Options::get( 'policy.enabled', true ) ) {
			return self::DISABLED_BODY;
		}

		return ( new AiTxtGenerator() )->generate( $this->data() );
	}

	/**
	 * Audit checks contributed by this module.
	 *
	 * @return array<int,Check> Checks.
	 */
	public function checks(): array {
		return [
			Checks::reachable(
				'ai_txt_reachable',
				$this->slug(),
				__( 'ai.txt is reachable', 'acid-aeo' ),
				Router::url( 'ai_txt' ),
				[
					'type'   => 'text/plain',
					'weight' => Check::WEIGHT_IMPORTANT,
					'fix'    => 'flush_rewrite',
				]
			),
			Checks::physical_conflict( 'ai_txt_physical_conflict', $this->slug(), 'ai.txt', 'ai.txt' ),
		];
	}

	/**
	 * The policy the file is rendered from.
	 *
	 * @return array<string,mixed> Input for `Generators\AiTxtGenerator`.
	 */
	public function data(): array {
		$policy   = SiteData::policy();
		$identity = SiteData::identity();
		$files    = SiteData::file_urls();

		$data = array_merge(
			$policy,
			[
				'owner'   => (string) ( $identity['name'] ?? '' ),
				'contact' => (string) ( $policy['permissions_contact'] ?? '' ),
				'links'   => [
					'context'  => $this->published_url( 'ai_context', $files ),
					'summary'  => $this->published_url( 'llms', $files ),
					'humans'   => $this->published_url( 'humans', $files ),
					'security' => $this->published_url( 'security', $files ),
				],
			]
		);

		/**
		 * Filters the policy `ai.txt` is built from.
		 *
		 * @param array<string,mixed> $data Policy, as described by `Modules\AiTxt::data()`.
		 */
		$data = apply_filters( 'acid_aeo_ai_txt_data', $data );

		return is_array( $data ) ? $data : [];
	}

	/**
	 * The URL of a file this plugin publishes, while it is published.
	 *
	 * A module that is switched off leaves no dead link behind.
	 *
	 * @param string               $slug  Router slug, e.g. `humans`.
	 * @param array<string,string> $files URLs from `Data\SiteData::file_urls()`.
	 * @return string Absolute URL, or an empty string when the file is not registered.
	 */
	private function published_url( string $slug, array $files ): string {
		return null !== Router::file( $slug ) ? (string) ( $files[ $slug ] ?? '' ) : '';
	}
}