<?php
/**
 * Immutable value object representing a link suggestion.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

use Postlinkly\Post\PostModel;

/**
 * Immutable value object representing one link suggestion.
 *
 * A suggestion is a candidate link from a source post to a target post
 * (or term) using a specific anchor inside a specific sentence. It carries
 * the scoring breakdown used for ranking.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.0.0
 */
final class SuggestionModel {

	/**
	 * The post being edited (the source of the proposed link).
	 *
	 * @var PostModel
	 */
	public PostModel $source;

	/**
	 * The post or term the link would point to.
	 *
	 * @var PostModel
	 */
	public PostModel $target;

	/**
	 * The anchor text that would be linked.
	 *
	 * @var string
	 */
	public string $anchor;

	/**
	 * The sentence that contains the anchor, with link markup applied.
	 *
	 * @var string
	 */
	public string $sentence_with_anchor;

	/**
	 * The sentence as it currently exists in the source content.
	 *
	 * @var string
	 */
	public string $original_sentence;

	/**
	 * Score component derived from the target post (relatedness, link count, etc.).
	 *
	 * @var float
	 */
	public float $post_score;

	/**
	 * Score component derived from the anchor itself (length, keyword fit).
	 *
	 * @var float
	 */
	public float $anchor_score;

	/**
	 * Combined ranking score. Higher is better.
	 *
	 * @var float
	 */
	public float $total_score;

	/**
	 * Tokenised words from the matched anchor phrase, in order.
	 *
	 * @var array<int, string>
	 */
	public array $words;

	/**
	 * Enhancement label IDs. Empty when no AI enhancement was applied.
	 *
	 * Labels indicate which AI feature affected this suggestion, e.g.
	 * 'ai_ranked' for semantic reranking or 'ai_anchor' for LLM anchor
	 * selection. The badge is only shown when a label is present — AI
	 * being enabled is not enough.
	 *
	 * @since 1.2.0
	 *
	 * @var array<int, string>
	 */
	public array $enhancement_labels;

	/**
	 * Whether the sentence contains one of the target post's focus keywords
	 * in full.
	 *
	 * The default matters for suggestions cached before this property
	 * existed: they unserialize with it unset, and must read as "no match"
	 * rather than fail.
	 *
	 * @since 1.18.2
	 *
	 * @var bool
	 */
	public bool $keyword_match = false;

	/**
	 * @since 1.0.0
	 * @since 1.2.0 Added the $enhancement_labels parameter.
	 * @since 1.18.2 Added the $keyword_match parameter.
	 *
	 * @param PostModel          $source                Source post.
	 * @param PostModel          $target                Target post or term.
	 * @param string             $anchor                Anchor text.
	 * @param string             $sentence_with_anchor  Optional. Sentence with link markup.
	 *                                                  Default empty.
	 * @param string             $original_sentence     Optional. Original sentence text.
	 *                                                  Default empty.
	 * @param float              $post_score            Optional. Post-level score. Default 0.0.
	 * @param float              $anchor_score          Optional. Anchor-level score. Default 0.0.
	 * @param float              $total_score           Optional. Combined score. Default 0.0.
	 * @param array<int, string> $words                 Optional. Tokenised words. Default [].
	 * @param array<int, string> $enhancement_labels    Optional. Enhancement labels. Default [].
	 * @param bool               $keyword_match         Optional. Whether the sentence contains a
	 *                                                  focus keyword of the target. Default false.
	 */
	public function __construct(
		PostModel $source,
		PostModel $target,
		string $anchor,
		string $sentence_with_anchor = '',
		string $original_sentence = '',
		float $post_score = 0.0,
		float $anchor_score = 0.0,
		float $total_score = 0.0,
		array $words = array(),
		array $enhancement_labels = array(),
		bool $keyword_match = false
	) {
		$this->source               = $source;
		$this->target               = $target;
		$this->anchor               = $anchor;
		$this->sentence_with_anchor = $sentence_with_anchor;
		$this->original_sentence    = $original_sentence;
		$this->post_score           = $post_score;
		$this->anchor_score         = $anchor_score;
		$this->total_score          = $total_score;
		$this->words                = $words;
		$this->enhancement_labels   = array_values( array_unique( $enhancement_labels ) );
		$this->keyword_match        = $keyword_match;
	}

	/**
	 * Returns a copy with a different total score.
	 *
	 * Used by the ranker to reweight suggestions without mutating originals.
	 *
	 * @since 1.0.0
	 *
	 * @param float $score The new total score.
	 *
	 * @return self
	 */
	public function with_total_score( float $score ): self {
		return new self(
			$this->source,
			$this->target,
			$this->anchor,
			$this->sentence_with_anchor,
			$this->original_sentence,
			$this->post_score,
			$this->anchor_score,
			$score,
			$this->words,
			$this->enhancement_labels,
			$this->keyword_match
		);
	}

	/**
	 * Returns a copy with a different anchor and sentence.
	 *
	 * Used by the LLM anchor selector when the LLM chooses a different
	 * validated phrase from the same original sentence.
	 *
	 * @since 1.2.0
	 *
	 * @param string $new_anchor              New anchor text.
	 * @param string $new_sentence_with_anchor New marked-up sentence.
	 *
	 * @return self
	 */
	public function with_replaced_anchor( string $new_anchor, string $new_sentence_with_anchor ): self {
		return new self(
			$this->source,
			$this->target,
			$new_anchor,
			$new_sentence_with_anchor,
			$this->original_sentence,
			$this->post_score,
			$this->anchor_score,
			$this->total_score,
			$this->words,
			$this->enhancement_labels,
			$this->keyword_match
		);
	}

	/**
	 * Returns a copy with an additional enhancement label.
	 *
	 * @since 1.2.0
	 *
	 * @param string $label Enhancement label id.
	 *
	 * @return self
	 */
	public function with_enhancement_label( string $label ): self {
		$labels   = $this->enhancement_labels;
		$labels[] = $label;

		return new self(
			$this->source,
			$this->target,
			$this->anchor,
			$this->sentence_with_anchor,
			$this->original_sentence,
			$this->post_score,
			$this->anchor_score,
			$this->total_score,
			$this->words,
			$labels,
			$this->keyword_match
		);
	}

	/**
	 * Returns the enhancement label ids.
	 *
	 * @since 1.2.0
	 *
	 * @return array<int, string>
	 */
	public function get_enhancement_labels(): array {
		return $this->enhancement_labels;
	}
}