<?php
/**
 * Pre-tokenised candidate description for the suggestion engine.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

use Postlinkly\Post\PostModel;

/**
 * Pre-tokenised candidate description for the suggestion engine.
 *
 * A `Candidate` describes one potential target post or term, complete
 * with everything the scoring strategies need: the stemmed word counts,
 * the total word count, and the pre-stemmed target-keyword list.
 * Providing this structure means the engine does no further tokenisation
 * during scoring — the heavy lifting is amortised across every phrase
 * the source post offers.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.0.0
 */
final class Candidate {

	/**
	 * The candidate post or term.
	 *
	 * @var PostModel
	 */
	public PostModel $post;

	/**
	 * Stem -> count map for the candidate's content.
	 *
	 * @var array<string, int>
	 */
	public array $word_counts;

	/**
	 * Total stemmed-word count (sum of $word_counts values).
	 *
	 * Stored separately so the TF-IDF scorer doesn't recompute it for
	 * every phrase it scores.
	 *
	 * @var int
	 */
	public int $word_total;

	/**
	 * Pre-stemmed, space-joined target keywords.
	 *
	 * @var array<int, string>
	 */
	public array $target_keywords;

	/**
	 * @since 1.0.0
	 *
	 * @param PostModel          $post            The candidate post or term.
	 * @param array<string, int> $word_counts     Stem counts. Default [].
	 * @param int                $word_total      Optional. Total word count.
	 *                                            Defaults to `array_sum($word_counts)`.
	 * @param array<int, string> $target_keywords Optional. Stemmed target keywords.
	 *                                            Default [].
	 */
	public function __construct(
		PostModel $post,
		array $word_counts = array(),
		int $word_total = -1,
		array $target_keywords = array()
	) {
		$this->post            = $post;
		$this->word_counts     = $word_counts;
		$this->word_total      = $word_total >= 0 ? $word_total : (int) array_sum( $word_counts );
		$this->target_keywords = $target_keywords;
	}
}