<?php
/**
 * A deliberately small robots.txt reader: group structure and access to `/`.
 *
 * @package PressRoost\AIVE
 */

namespace PressRoost\AIVE\Robots;

/**
 * Parses robots.txt text into groups and answers one question about each bot.
 *
 * The question is narrow on purpose: **is this token allowed to fetch the site
 * root?** That is what an administrator needs in order to see whether the
 * declared policy took effect, and it is answerable deterministically from the
 * subset of the format implemented here. Anything wider would be a claim this
 * parser cannot back:
 *
 * - Only `User-agent`, `Allow` and `Disallow` are recognised. Unknown
 *   directives - `Crawl-delay`, `Sitemap`, vendor extensions - are ignored and
 *   change no status.
 * - Only the exact path `/` is evaluated. A directive for some other path, such
 *   as `/wp-admin/`, imposes no restriction at the root, which is why a group
 *   holding nothing else reads as allowed there.
 * - A path containing `*` or `$` is not evaluated at all. Wildcard and anchor
 *   syntax is an extension that crawlers implement with real differences
 *   between them, so a group that depends on one yields `unknown` rather than a
 *   guess in either direction.
 *
 * Group structure follows the format: one or more consecutive `User-agent`
 * lines followed by directives form a group, a group naming several agents
 * applies to each of them, and repeated groups for the same token merge in
 * appearance order. Agent comparison is case-insensitive. An exact-token group
 * takes the place of `User-agent: *` entirely rather than inheriting from it,
 * which is the behaviour the format specifies and the one crawlers implement.
 *
 * Pure string work with no WordPress dependency, so the Unit suite covers it.
 *
 * @since 1.2.0
 */
final class RobotsParser {

	/**
	 * The token may fetch the site root.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const STATUS_ALLOWED = 'allowed';

	/**
	 * The token is disallowed from the site root.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const STATUS_BLOCKED = 'blocked';

	/**
	 * No group names the token and there is no wildcard group.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const STATUS_NOT_MENTIONED = 'not-mentioned';

	/**
	 * A group applies but uses syntax this parser does not evaluate.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const STATUS_UNKNOWN = 'unknown';

	/**
	 * There is no response to read, so no status can be derived.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const STATUS_UNAVAILABLE = 'unavailable';

	/**
	 * Basis: an applicable `Disallow: /` closes the root.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_DISALLOW_ROOT = 'disallow-root';

	/**
	 * Basis: an applicable `Allow: /` opens the root.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_ALLOW_ROOT = 'allow-root';

	/**
	 * Basis: `Allow: /` and `Disallow: /` are both present; Allow wins.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_ALLOW_TIE_BREAK = 'allow-tie-break';

	/**
	 * Basis: the group restricts other paths but not the root.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_ALLOWED_AT_ROOT = 'allowed-at-root';

	/**
	 * Basis: the group depends on wildcard or anchor syntax.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_WILDCARD_UNSUPPORTED = 'wildcard-unsupported';

	/**
	 * Basis: nothing in the response names the token.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_NOT_MENTIONED = 'not-mentioned';

	/**
	 * Basis: there was no response to evaluate.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const BASIS_NO_RESPONSE = 'no-response';

	/**
	 * Scope: the status comes from a group naming the token exactly.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const SCOPE_EXACT = 'exact';

	/**
	 * Scope: the status comes from a `User-agent: *` group.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const SCOPE_WILDCARD = 'wildcard';

	/**
	 * Scope: no group applies.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	public const SCOPE_NONE = 'none';

	/**
	 * The wildcard agent token.
	 *
	 * @since 1.2.0
	 * @var string
	 */
	private const WILDCARD_AGENT = '*';

	/**
	 * Parses robots.txt text into groups.
	 *
	 * @since 1.2.0
	 *
	 * @param string $text Robots.txt response text.
	 * @return array<int, array{agents: array<int, string>, directives: array<int, array{type: string, path: string}>}> Groups in appearance order.
	 */
	public static function parse( $text ) {
		$lines = preg_split( '/\R/', (string) $text );
		$lines = is_array( $lines ) ? $lines : array();

		$groups     = array();
		$agents     = array();
		$directives = array();

		foreach ( $lines as $line ) {
			$line = self::strip_comment( (string) $line );

			if ( '' === $line ) {
				continue;
			}

			$parts = explode( ':', $line, 2 );

			if ( 2 !== count( $parts ) ) {
				continue;
			}

			$field = strtolower( trim( $parts[0] ) );
			$value = trim( $parts[1] );

			if ( 'user-agent' === $field ) {
				/*
				 * A User-agent line after directives opens a new group; one that
				 * follows another User-agent line adds to the current group's
				 * agents. That is the whole of the format's grouping rule.
				 */
				if ( array() !== $directives ) {
					$groups[]   = array(
						'agents'     => $agents,
						'directives' => $directives,
					);
					$agents     = array();
					$directives = array();
				}

				if ( '' !== $value ) {
					$agents[] = strtolower( $value );
				}

				continue;
			}

			if ( 'allow' !== $field && 'disallow' !== $field ) {
				continue;
			}

			// A directive before any User-agent line belongs to no group.
			if ( array() === $agents ) {
				continue;
			}

			$directives[] = array(
				'type' => $field,
				'path' => $value,
			);
		}

		if ( array() !== $agents ) {
			$groups[] = array(
				'agents'     => $agents,
				'directives' => $directives,
			);
		}

		return $groups;
	}

	/**
	 * Returns the agent tokens a response names, lower-cased.
	 *
	 * The wildcard is excluded: callers use this to decide whether a response
	 * already addresses a bot by name, and `*` addresses no bot by name.
	 *
	 * @since 1.2.0
	 *
	 * @param string $text Robots.txt response text.
	 * @return array<string, true> Lower-cased agent tokens as keys.
	 */
	public static function agents( $text ) {
		$agents = array();

		foreach ( self::parse( $text ) as $group ) {
			foreach ( $group['agents'] as $agent ) {
				if ( self::WILDCARD_AGENT === $agent ) {
					continue;
				}

				$agents[ $agent ] = true;
			}
		}

		return $agents;
	}

	/**
	 * Reports what the parsed groups say about one token's access to `/`.
	 *
	 * @since 1.2.0
	 *
	 * @param array<int, array{agents: array<int, string>, directives: array<int, array{type: string, path: string}>}> $groups Parsed groups.
	 * @param string                                                                                                   $token  Registry token to evaluate.
	 * @return array{status: string, basis: string, scope: string} Status, its basis and the group scope it came from.
	 */
	public static function root_status( array $groups, $token ) {
		$directives = self::directives_for( $groups, strtolower( (string) $token ) );
		$scope      = self::SCOPE_EXACT;

		if ( null === $directives ) {
			$directives = self::directives_for( $groups, self::WILDCARD_AGENT );
			$scope      = self::SCOPE_WILDCARD;
		}

		if ( null === $directives ) {
			return array(
				'status' => self::STATUS_NOT_MENTIONED,
				'basis'  => self::BASIS_NOT_MENTIONED,
				'scope'  => self::SCOPE_NONE,
			);
		}

		$evaluated          = self::evaluate_root( $directives );
		$evaluated['scope'] = $scope;

		return $evaluated;
	}

	/**
	 * Returns every directive of every group naming an agent, or null.
	 *
	 * Null and an empty array mean different things: null is "no group names
	 * this agent", which falls through to the wildcard, while an empty array is
	 * "a group names it and carries no directive", which does not.
	 *
	 * @since 1.2.0
	 *
	 * @param array<int, array{agents: array<int, string>, directives: array<int, array{type: string, path: string}>}> $groups Parsed groups.
	 * @param string                                                                                                   $agent  Lower-cased agent token.
	 * @return array<int, array{type: string, path: string}>|null Merged directives in appearance order, or null.
	 */
	private static function directives_for( array $groups, $agent ) {
		$found      = false;
		$directives = array();

		foreach ( $groups as $group ) {
			if ( ! in_array( $agent, $group['agents'], true ) ) {
				continue;
			}

			$found      = true;
			$directives = array_merge( $directives, $group['directives'] );
		}

		return $found ? $directives : null;
	}

	/**
	 * Decides access to `/` from a group's directives.
	 *
	 * Only `/` itself is an applicable path at the root: every other literal
	 * path is longer and more specific, so it cannot match `/`. Where an
	 * applicable Allow and Disallow are both present they are necessarily the
	 * same length, and the format's tie-break awards equal-length matches to
	 * Allow.
	 *
	 * @since 1.2.0
	 *
	 * @param array<int, array{type: string, path: string}> $directives Directives in appearance order.
	 * @return array{status: string, basis: string} Status and its basis.
	 */
	private static function evaluate_root( array $directives ) {
		$allow_root    = false;
		$disallow_root = false;
		$unsupported   = false;

		foreach ( $directives as $directive ) {
			$path = (string) $directive['path'];

			if ( false !== strpos( $path, '*' ) || false !== strpos( $path, '$' ) ) {
				$unsupported = true;

				continue;
			}

			/*
			 * An empty value - "Disallow:" on its own - imposes no restriction,
			 * and is handled by this same test rather than as a special case.
			 */
			if ( '/' !== $path ) {
				continue;
			}

			if ( 'allow' === $directive['type'] ) {
				$allow_root = true;

				continue;
			}

			$disallow_root = true;
		}

		if ( $allow_root && $disallow_root ) {
			return array(
				'status' => self::STATUS_ALLOWED,
				'basis'  => self::BASIS_ALLOW_TIE_BREAK,
			);
		}

		if ( $disallow_root ) {
			return array(
				'status' => self::STATUS_BLOCKED,
				'basis'  => self::BASIS_DISALLOW_ROOT,
			);
		}

		if ( $allow_root ) {
			return array(
				'status' => self::STATUS_ALLOWED,
				'basis'  => self::BASIS_ALLOW_ROOT,
			);
		}

		if ( $unsupported ) {
			return array(
				'status' => self::STATUS_UNKNOWN,
				'basis'  => self::BASIS_WILDCARD_UNSUPPORTED,
			);
		}

		return array(
			'status' => self::STATUS_ALLOWED,
			'basis'  => self::BASIS_ALLOWED_AT_ROOT,
		);
	}

	/**
	 * Removes a comment and surrounding whitespace from one line.
	 *
	 * `#` starts a comment anywhere on a line in robots.txt, so this also
	 * handles a whole-line comment without a separate test for it.
	 *
	 * @since 1.2.0
	 *
	 * @param string $line Raw line.
	 * @return string Line without its comment, trimmed.
	 */
	private static function strip_comment( $line ) {
		$hash = strpos( $line, '#' );

		if ( false !== $hash ) {
			$line = substr( $line, 0, $hash );
		}

		return trim( $line );
	}
}