<?php
/**
 * Contract for an automated repair.
 *
 * @package OrbitstemSEO
 */

namespace Orbitstem\SEO\Repair;

use WP_Error;

defined( 'ABSPATH' ) || exit;

/**
 * Every repair follows the same path through the Repair Center:
 * candidates() lists what would change (the preview), find() re-reads one
 * item right before changing it, apply() makes the change and returns the
 * before and after state, verify() checks the result, rollback() restores
 * the before state only if nothing changed since.
 */
interface Fixer {

	/**
	 * Machine id, stored in the change log.
	 *
	 * @return string
	 */
	public function id();

	/**
	 * Name shown in the Repair Center.
	 *
	 * @return string
	 */
	public function label();

	/**
	 * What the fixer does, in plain words.
	 *
	 * @return string
	 */
	public function description();

	/**
	 * Issue ids (from Issues) this fixer resolves.
	 *
	 * @return string[]
	 */
	public function issue_ids();

	/**
	 * Whether the change removes content and needs an explicit confirmation.
	 *
	 * @return bool
	 */
	public function is_destructive();

	/**
	 * Items that would change: key, object_type, object_id, summary, before, after.
	 *
	 * @param int $limit Maximum items.
	 * @return array<int,array>
	 */
	public function candidates( $limit );

	/**
	 * Current version of one candidate, or null when it no longer applies.
	 *
	 * @param string $key Candidate key.
	 * @return array|null
	 */
	public function find( $key );

	/**
	 * Whether the current user may change this item.
	 *
	 * @param array $item Candidate.
	 * @return bool
	 */
	public function can_apply( array $item );

	/**
	 * Makes the change.
	 *
	 * @param array $item Candidate from find().
	 * @return array{before:mixed,after:mixed,summary:string}|WP_Error
	 */
	public function apply( array $item );

	/**
	 * Checks that an applied change had the intended result.
	 *
	 * @param array $change Change-log row.
	 * @return array{ok:bool,note:string}
	 */
	public function verify( array $change );

	/**
	 * Restores the before state if the object still has the after state.
	 *
	 * @param array $change Change-log row.
	 * @return true|WP_Error
	 */
	public function rollback( array $change );
}