<?php
/**
 * One audit finding.
 *
 * @package AcidStudios\AEO
 */

declare(strict_types=1);

namespace AcidStudios\AEO\Audit;

defined( 'ABSPATH' ) || exit;

/**
 * A single thing the audit looked at, and what it found.
 *
 * Immutable by construction: a check is an observation, and an observation that
 * can be edited after the fact is worth nothing. `Audit\Runner` scores and
 * orders checks; the admin screen, the REST API and the CLI all read them
 * through `to_array()`, so the wire shape is defined in exactly one place.
 *
 * The weight says how much the finding matters, not how hard it is to fix: a
 * critical check is one an answer engine trips over, a nice one is polish.
 */
final class Check {

	/**
	 * The site does what the check looked for.
	 *
	 * @var string
	 */
	public const PASS = 'pass';

	/**
	 * The site works, but not as well as it could.
	 *
	 * @var string
	 */
	public const WARN = 'warn';

	/**
	 * Something an answer engine relies on is missing or broken.
	 *
	 * @var string
	 */
	public const FAIL = 'fail';

	/**
	 * The check could not be run, and is left out of the score.
	 *
	 * @var string
	 */
	public const SKIP = 'skip';

	/**
	 * Weight of a check an answer engine trips over.
	 *
	 * @var int
	 */
	public const WEIGHT_CRITICAL = 10;

	/**
	 * Weight of a check that costs the site reach.
	 *
	 * @var int
	 */
	public const WEIGHT_IMPORTANT = 5;

	/**
	 * Weight of a check that is polish.
	 *
	 * @var int
	 */
	public const WEIGHT_NICE = 2;

	/**
	 * Stable identifier, e.g. `llms_reachable`.
	 *
	 * @var string
	 */
	private string $id;

	/**
	 * Slug of the module that contributed the check, or `core`.
	 *
	 * @var string
	 */
	private string $module;

	/**
	 * Human readable, translated name of what was checked.
	 *
	 * @var string
	 */
	private string $label;

	/**
	 * One of `pass`, `warn`, `fail` or `skip`.
	 *
	 * @var string
	 */
	private string $status;

	/**
	 * Translated sentence explaining the result.
	 *
	 * @var string
	 */
	private string $message;

	/**
	 * How much the finding counts towards the score.
	 *
	 * @var int
	 */
	private int $weight;

	/**
	 * Id of the one-click fix that repairs this, or null when there is none.
	 *
	 * @var string|null
	 */
	private ?string $fix;

	/**
	 * URL of the documentation explaining the check.
	 *
	 * @var string
	 */
	private string $docs;

	/**
	 * Builds a finding.
	 *
	 * @param string      $id      Stable identifier, e.g. `llms_reachable`.
	 * @param string      $module  Module slug, or `core`.
	 * @param string      $label   Translated name of what was checked.
	 * @param string      $status  One of `pass`, `warn`, `fail` or `skip`.
	 * @param string      $message Translated sentence explaining the result.
	 * @param int         $weight  Weight, one of the `WEIGHT_*` constants.
	 * @param string|null $fix     Id of the one-click fix, or null.
	 * @param string      $docs    Documentation URL.
	 */
	public function __construct( string $id, string $module, string $label, string $status, string $message = '', int $weight = self::WEIGHT_IMPORTANT, ?string $fix = null, string $docs = '' ) {
		$this->id      = $id;
		$this->module  = $module;
		$this->label   = $label;
		$this->status  = in_array( $status, [ self::PASS, self::WARN, self::FAIL, self::SKIP ], true ) ? $status : self::SKIP;
		$this->message = $message;
		$this->weight  = max( 0, $weight );
		$this->fix     = '' !== (string) $fix ? $fix : null;
		$this->docs    = $docs;
	}

	/**
	 * A check the site passed.
	 *
	 * @param string $id      Stable identifier.
	 * @param string $module  Module slug, or `core`.
	 * @param string $label   Translated name of what was checked.
	 * @param string $message Translated sentence explaining the result.
	 * @param int    $weight  Weight, one of the `WEIGHT_*` constants.
	 * @param string $docs    Documentation URL.
	 * @return Check The finding.
	 */
	public static function pass( string $id, string $module, string $label, string $message = '', int $weight = self::WEIGHT_IMPORTANT, string $docs = '' ): Check {
		return new self( $id, $module, $label, self::PASS, $message, $weight, null, $docs );
	}

	/**
	 * A check the site could do better.
	 *
	 * @param string      $id      Stable identifier.
	 * @param string      $module  Module slug, or `core`.
	 * @param string      $label   Translated name of what was checked.
	 * @param string      $message Translated sentence explaining the result.
	 * @param int         $weight  Weight, one of the `WEIGHT_*` constants.
	 * @param string|null $fix     Id of the one-click fix, or null.
	 * @param string      $docs    Documentation URL.
	 * @return Check The finding.
	 */
	public static function warn( string $id, string $module, string $label, string $message = '', int $weight = self::WEIGHT_IMPORTANT, ?string $fix = null, string $docs = '' ): Check {
		return new self( $id, $module, $label, self::WARN, $message, $weight, $fix, $docs );
	}

	/**
	 * A check the site failed.
	 *
	 * @param string      $id      Stable identifier.
	 * @param string      $module  Module slug, or `core`.
	 * @param string      $label   Translated name of what was checked.
	 * @param string      $message Translated sentence explaining the result.
	 * @param int         $weight  Weight, one of the `WEIGHT_*` constants.
	 * @param string|null $fix     Id of the one-click fix, or null.
	 * @param string      $docs    Documentation URL.
	 * @return Check The finding.
	 */
	public static function fail( string $id, string $module, string $label, string $message = '', int $weight = self::WEIGHT_IMPORTANT, ?string $fix = null, string $docs = '' ): Check {
		return new self( $id, $module, $label, self::FAIL, $message, $weight, $fix, $docs );
	}

	/**
	 * A check that could not be run, and is left out of the score.
	 *
	 * @param string $id      Stable identifier.
	 * @param string $module  Module slug, or `core`.
	 * @param string $label   Translated name of what was checked.
	 * @param string $message Translated sentence explaining why it was skipped.
	 * @param int    $weight  Weight, one of the `WEIGHT_*` constants.
	 * @param string $docs    Documentation URL.
	 * @return Check The finding.
	 */
	public static function skip( string $id, string $module, string $label, string $message = '', int $weight = self::WEIGHT_IMPORTANT, string $docs = '' ): Check {
		return new self( $id, $module, $label, self::SKIP, $message, $weight, null, $docs );
	}

	/**
	 * Stable identifier.
	 *
	 * @return string Check id.
	 */
	public function id(): string {
		return $this->id;
	}

	/**
	 * Slug of the module that contributed the check.
	 *
	 * @return string Module slug, or `core`.
	 */
	public function module(): string {
		return $this->module;
	}

	/**
	 * Result of the check.
	 *
	 * @return string One of `pass`, `warn`, `fail` or `skip`.
	 */
	public function status(): string {
		return $this->status;
	}

	/**
	 * How much the finding counts towards the score.
	 *
	 * @return int Weight.
	 */
	public function weight(): int {
		return $this->weight;
	}

	/**
	 * Id of the one-click fix that repairs this.
	 *
	 * @return string|null Fix id, or null when there is none.
	 */
	public function fix(): ?string {
		return $this->fix;
	}

	/**
	 * The finding as plain data, ready for the REST API, the admin and the CLI.
	 *
	 * @return array<string,mixed> Keys `id`, `module`, `label`, `status`, `message`,
	 *                             `weight`, `fix` and `docs`, in that order.
	 */
	public function to_array(): array {
		return [
			'id'      => $this->id,
			'module'  => $this->module,
			'label'   => $this->label,
			'status'  => $this->status,
			'message' => $this->message,
			'weight'  => $this->weight,
			'fix'     => $this->fix,
			'docs'    => $this->docs,
		];
	}
}