<?php
/**
 * Records which revision of a post was last indexed.
 *
 * @package Postlinkly
 * @since   1.14.0
 */

declare(strict_types=1);

namespace Postlinkly\Indexing;

/**
 * Lets a re-index skip posts that have not changed.
 *
 * Without this, every rebuild costs as much as the first — on a large site
 * that is the difference between routine maintenance and something nobody
 * dares run. With it, the expensive full walk happens once and the ongoing
 * cost is proportional to how much was edited.
 *
 * The comparison is against `post_modified` rather than a content hash
 * because WordPress already maintains that value: hashing every post to
 * discover that nothing changed would cost exactly the walk this avoids.
 *
 * Applies to per-post indexing only. It deliberately must NOT be used by
 * {@see Stage\StemFrequencyStage}, whose output is a corpus-wide aggregate —
 * skipping a post there would omit it from the document count that every IDF
 * value is divided by, quietly corrupting scoring rather than saving work.
 *
 * @since 1.14.0
 */
final class IndexedMarker {

	/**
	 * Post meta holding the `post_modified` value last indexed.
	 *
	 * The leading underscore keeps it out of the custom-fields UI; the
	 * `postlinkly_` prefix is what {@see \Postlinkly\Bootstrap\Uninstaller}
	 * sweeps, so this needs no cleanup of its own.
	 */
	public const META_KEY = '_postlinkly_indexed_modified';

	/**
	 * Whether this post has changed since it was last indexed.
	 *
	 * @since 1.14.0
	 *
	 * @param int    $post_id       Post to check.
	 * @param string $post_modified The post's current `post_modified` value.
	 *
	 * @return bool
	 */
	public static function needs_indexing( int $post_id, string $post_modified ): bool {
		if ( $post_id <= 0 || '' === $post_modified ) {
			// Nothing to compare against, so never assume it is current.
			return true;
		}

		$stored = get_post_meta( $post_id, self::META_KEY, true );

		return ! is_string( $stored ) || $stored !== $post_modified;
	}

	/**
	 * Whether this post has been indexed at all.
	 *
	 * Tells "scanned, and has no links" apart from "never scanned": both
	 * have no rows in the link report, so the report alone cannot say which.
	 *
	 * @since 1.18.4
	 *
	 * @param int $post_id Post to check.
	 *
	 * @return bool
	 */
	public static function is_indexed( int $post_id ): bool {
		if ( $post_id <= 0 ) {
			return false;
		}

		$stored = get_post_meta( $post_id, self::META_KEY, true );

		return is_string( $stored ) && '' !== $stored;
	}

	/**
	 * Records that this post has been indexed at its current revision.
	 *
	 * @since 1.14.0
	 *
	 * @param int    $post_id       Post that was indexed.
	 * @param string $post_modified The `post_modified` value that was indexed.
	 *
	 * @return void
	 */
	public static function mark( int $post_id, string $post_modified ): void {
		if ( $post_id <= 0 || '' === $post_modified ) {
			return;
		}

		update_post_meta( $post_id, self::META_KEY, $post_modified );
	}

	/**
	 * Makes one post eligible for indexing again.
	 *
	 * @since 1.14.0
	 *
	 * @param int $post_id Post to unmark.
	 *
	 * @return void
	 */
	public static function clear( int $post_id ): void {
		if ( $post_id <= 0 ) {
			return;
		}

		delete_post_meta( $post_id, self::META_KEY );
	}

	/**
	 * Makes every post eligible again, for a forced rebuild.
	 *
	 * One query rather than one per post: clearing a 9,000-post site row by
	 * row would reintroduce exactly the per-item cost this class removes.
	 *
	 * @since 1.14.0
	 *
	 * @return void
	 */
	public static function clear_all(): void {
		global $wpdb;

		if ( ! isset( $wpdb ) ) {
			return;
		}

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Bulk clearing this marker is the operation; doing it through the meta API would be one query per post.
		$wpdb->query(
			$wpdb->prepare( "DELETE FROM {$wpdb->postmeta} WHERE meta_key = %s", self::META_KEY )
		);
	}
}