<?php
/**
 * Outcome of checking one URL.
 *
 * @package ForensixDigital
 */

declare(strict_types=1);

namespace ForensixDigital\Services\Scan;

defined( 'ABSPATH' ) || exit;

/**
 * Whether a linked URL works, and how it got there.
 */
final class TargetResult {

	public const OK           = 'ok';
	public const BROKEN       = 'broken';
	public const INCONCLUSIVE = 'inconclusive';
	public const LOOP         = 'loop';

	/**
	 * Creates a result.
	 *
	 * @param string $verdict   One of the constants.
	 * @param int    $status    Last HTTP status, 0 when no response.
	 * @param string $final_url URL after redirects.
	 * @param int    $hops      Redirects followed.
	 * @param string $error     Transport error, if any.
	 */
	public function __construct(
		public readonly string $verdict,
		public readonly int $status,
		public readonly string $final_url,
		public readonly int $hops = 0,
		public readonly string $error = ''
	) {}

	/**
	 * Verdict for a final HTTP status (after redirects).
	 *
	 * Broken: 404, 410 and other 4xx; server errors on the site itself; unknown hosts.
	 * Inconclusive: 401, 403, 429 (the host refuses robots or wants a login), external 5xx,
	 * timeouts and other transport errors (F-SCAN-02 safeguard).
	 *
	 * @param int    $status   HTTP status, 0 for no response.
	 * @param bool   $internal Whether the URL is on the site itself.
	 * @param string $error    Transport error message.
	 */
	public static function verdict_for( int $status, bool $internal, string $error = '' ): string {
		if ( 0 === $status ) {
			return str_contains( strtolower( $error ), 'resolve host' ) ? self::BROKEN : self::INCONCLUSIVE;
		}
		if ( $status < 400 ) {
			return self::OK;
		}
		if ( in_array( $status, array( 401, 403, 429 ), true ) ) {
			return self::INCONCLUSIVE;
		}
		if ( $status >= 500 ) {
			return $internal ? self::BROKEN : self::INCONCLUSIVE;
		}
		return self::BROKEN;
	}
}