<?php
/**
 * Immutable value object describing one anchor candidate.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

/**
 * Immutable value object describing one anchor candidate.
 *
 * Returned by {@see AnchorCandidateBuilder::build()}. Carries the anchor
 * text, the words in the matched span, and an internal anchor score the
 * ranker can fold into the final ordering.
 *
 * Properties are public for compactness; do not modify them after
 * construction.
 *
 * @since 1.0.0
 */
final class AnchorCandidate {

	/**
	 * The anchor text, taken verbatim from the source phrase.
	 *
	 * @var string
	 */
	public string $anchor;

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

	/**
	 * Anchor-level score in `[0.0, 1.0]`.
	 *
	 * Reflects how confidently this span is an anchor (length, contiguity).
	 * Independent of the candidate post's quality.
	 *
	 * @var float
	 */
	public float $score;

	/**
	 * @since 1.0.0
	 *
	 * @param string             $anchor Anchor text.
	 * @param array<int, string> $words  Matched words in order.
	 * @param float              $score  Anchor-level score in `[0.0, 1.0]`.
	 */
	public function __construct( string $anchor, array $words, float $score ) {
		$this->anchor = $anchor;
		$this->words  = $words;
		$this->score  = $score;
	}
}