<?php
/**
 * Combines and orders suggestion candidates produced by the engine.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Suggestion;

/**
 * Combines and orders suggestion candidates produced by the engine.
 *
 * Each suggestion handed to the ranker carries a `post_score` (the
 * weighted sum of every scoring strategy applied to the candidate) and
 * an `anchor_score` (from the anchor builder). The ranker:
 *
 *   1. Sets `total_score = post_score + anchor_score` for every entry.
 *   2. Drops entries whose `total_score` is `<= 0.0` — they would be
 *      noise in the result list.
 *   3. Deduplicates by target identity. When several phrases produce
 *      suggestions to the same target, only the highest-scoring one
 *      survives. Ties are broken by the longer anchor; further ties
 *      preserve the input order.
 *   4. Sorts the survivors by `total_score` descending. Stable order
 *      under ties (input order preserved).
 *   5. Caps the result list at `$limit`.
 *
 * The ranker is a pure function: same input, same output. It does not
 * touch the database, the cache, or any global state.
 *
 * @since 1.0.0
 */
final class SuggestionRanker {

	/**
	 * Default cap applied when the engine doesn't pass an explicit one.
	 */
	public const DEFAULT_LIMIT = 10;

	/**
	 * Combines, sorts, dedupes, and caps a list of suggestions.
	 *
	 * @since 1.0.0
	 * @since 1.6.0 The anchor-length tie-break compares character count
	 *              instead of byte count, so multibyte anchors are no
	 *              longer favored purely by UTF-8 encoding overhead.
	 *
	 * @param array<int, SuggestionModel> $suggestions Pre-scored candidates.
	 * @param int                         $limit       Optional. Maximum number of
	 *                                                  results to return. Default
	 *                                                  {@see DEFAULT_LIMIT}.
	 *
	 * @return array<int, SuggestionModel> Re-keyed, ranked suggestions.
	 */
	public function rank( array $suggestions, int $limit = self::DEFAULT_LIMIT ): array {
		if ( $limit <= 0 || array() === $suggestions ) {
			return array();
		}

		// Step 1: compute totals and drop entries that scored zero or
		// below. Index entries by their original position so we can
		// preserve input order across stable sorts.
		$indexed = array();
		$index   = 0;
		foreach ( $suggestions as $entry ) {
			if ( ! $entry instanceof SuggestionModel ) {
				++$index;
				continue;
			}
			$total = $entry->post_score + $entry->anchor_score;
			if ( $total <= 0.0 ) {
				++$index;
				continue;
			}
			$updated   = $entry->with_total_score( $total );
			$indexed[] = array(
				'order'      => $index,
				'suggestion' => $updated,
			);
			++$index;
		}

		if ( array() === $indexed ) {
			return array();
		}

		// Step 2: dedupe by target identity. Iterate the list; for each
		// target keep the entry with the highest total_score, breaking
		// ties by anchor length, and finally by input order.
		$best_for_target = array();
		foreach ( $indexed as $row ) {
			$target_key = $row['suggestion']->target->get_key();

			if ( ! isset( $best_for_target[ $target_key ] ) ) {
				$best_for_target[ $target_key ] = $row;
				continue;
			}

			$current  = $best_for_target[ $target_key ]['suggestion'];
			$incoming = $row['suggestion'];

			if ( $incoming->total_score > $current->total_score ) {
				$best_for_target[ $target_key ] = $row;
				continue;
			}
			if ( $incoming->total_score < $current->total_score ) {
				continue;
			}
			// Equal totals: prefer the longer anchor. The engine usually
			// produces longer anchors when the source paragraph more
			// strongly aligns with the candidate's topic.
			if ( mb_strlen( $incoming->anchor ) > mb_strlen( $current->anchor ) ) {
				$best_for_target[ $target_key ] = $row;
				continue;
			}
			// Equal totals and equal anchor length: keep the earlier
			// input position (already in $current; nothing to do).
		}

		// Step 3: sort the surviving entries by total_score desc, with
		// stable input-order tie breaking via the recorded order index.
		$rows = array_values( $best_for_target );
		usort(
			$rows,
			static function ( array $left, array $right ): int {
				$score_diff = $right['suggestion']->total_score <=> $left['suggestion']->total_score;
				if ( 0 !== $score_diff ) {
					return $score_diff;
				}
				return $left['order'] <=> $right['order'];
			}
		);

		// Step 4: cap at limit and project back to a SuggestionModel list.
		if ( count( $rows ) > $limit ) {
			$rows = array_slice( $rows, 0, $limit );
		}

		$out = array();
		foreach ( $rows as $row ) {
			$out[] = $row['suggestion'];
		}
		return $out;
	}
}