<?php
/**
 * Operation base class.
 *
 * @package Recast\WCS
 */

namespace Recast\WCS\Operation;

use Recast\WCS\Diff\DiffSet;
use Recast\WCS\Run\RunItem;
use Recast\WCS\State\Fingerprint;
use Recast\WCS\State\StateExtractor;

defined( 'ABSPATH' ) || exit;

/**
 * Shared helpers: validation through the descriptor's schema, diff scaffolding, purity guard.
 */
abstract class AbstractOperation implements OperationInterface {

	/**
	 * Validates via the descriptor schema.
	 *
	 * @param array<string, mixed> $params Params.
	 * @return ValidationResult
	 */
	public function validate( array $params ) {
		return $this->describe()->schema->validate( $params );
	}

	/**
	 * Default: nothing blocks undo.
	 *
	 * @param RunItem          $item    Item.
	 * @param \WC_Subscription $current Current subscription.
	 * @return array<int, array{code: string, message: string, blocking: bool}>
	 */
	public function undo_constraints( RunItem $item, \WC_Subscription $current ) {
		return array();
	}

	/**
	 * Fields fingerprinted for a run of this operation.
	 *
	 * @param array<string, mixed> $params Params.
	 * @return string[]
	 */
	public function fingerprint_fields( array $params ) {
		return Fingerprint::fields_for( $this->touched_fields( $params ), $this->id(), $params );
	}

	/**
	 * Creates a DiffSet pre-filled with the before state (after = before until changed).
	 *
	 * @param \WC_Subscription     $subscription Subscription.
	 * @param array<string, mixed> $params       Params.
	 * @return DiffSet
	 */
	protected function start_diff( \WC_Subscription $subscription, array $params ) {
		$diff               = new DiffSet();
		$diff->before_state = StateExtractor::extract( $subscription, $this->fingerprint_fields( $params ) );
		$diff->after_state  = $diff->before_state;
		return $diff;
	}

	/**
	 * Records a predicted change on both the change list and the predicted after-state.
	 *
	 * @param DiffSet     $diff      Diff.
	 * @param string      $field     Field.
	 * @param mixed       $after     Predicted value.
	 * @param string|null $item_name Item name.
	 * @return void
	 */
	protected function predict( DiffSet $diff, $field, $after, $item_name = null ) {
		$before = array_key_exists( $field, $diff->before_state ) ? $diff->before_state[ $field ] : null;
		$diff->change( $field, $before, $after, $item_name );
		$diff->after_state[ $field ] = $after;
	}

	/**
	 * Runs compute_diff() and asserts it left the subscription untouched.
	 *
	 * @param \WC_Subscription     $subscription Subscription.
	 * @param array<string, mixed> $params       Params.
	 * @return DiffSet
	 * @throws \LogicException When compute_diff() mutated the subscription (only when WP_DEBUG).
	 */
	public function compute_diff_guarded( \WC_Subscription $subscription, array $params ) {
		$diff = $this->compute_diff( $subscription, $params );
		if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
			$dirty = $subscription->get_changes();
			foreach ( $subscription->get_items() as $item ) {
				if ( $item->get_changes() ) {
					$dirty['items'] = true;
				}
			}
			if ( ! empty( $dirty ) ) {
				throw new \LogicException( esc_html( sprintf( 'Operation %s mutated the subscription during compute_diff(): %s', $this->id(), implode( ',', array_keys( $dirty ) ) ) ) );
			}
		}
		return $diff;
	}

	/**
	 * Helper to build a descriptor.
	 *
	 * @param string      $label       Label.
	 * @param string      $description Description.
	 * @param ParamSchema $schema      Schema.
	 * @param string      $group       Group.
	 * @param bool        $undoable    Undoable.
	 * @param string[]    $flags       Flags.
	 * @return OperationDescriptor
	 */
	protected function descriptor( $label, $description, ParamSchema $schema, $group, $undoable = true, array $flags = array() ) {
		return new OperationDescriptor( $this->id(), $label, $description, $schema, $undoable, $flags, $group );
	}
}