<?php
/**
 * Detects internal links whose target no longer resolves.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\InternalRot;

use Postlinkly\Database\TableNames;

/**
 * Detects internal links whose target no longer resolves.
 *
 * "Internal-link rot" is the condition where a post or term that was
 * once a valid link target has since been deleted, trashed, or taken
 * private — leaving the source post with a dangling internal link.
 *
 * This class answers the question with a single SQL query against
 * `postlinkly_report_links`. It does not make any outbound HTTP
 * requests, does not schedule cron jobs, and does not maintain any
 * scanner state. The report page calls it on demand.
 *
 * The query strategy:
 *
 *   - Selects rows from `report_links` where `is_internal = 1`.
 *   - LEFT JOINs against `wp_posts` (for post targets) and
 *     `wp_term_taxonomy` (for term targets).
 *   - Returns rows where the join produced no match, or where the
 *     matched post's status is not `publish`.
 *   - Also returns rows with `target_type = 'unresolved'` — internal
 *     links whose target could not be resolved at scan time because it
 *     was already gone (see `Indexing\Stage\LinksStage`).
 *     These need no join condition: they are unconditionally rot.
 *
 * This is Position C from the locked decisions: internal-only, no HTTP
 * probe, derived query. External broken-link checking is a v1.x
 * candidate.
 *
 * @since 1.0.0
 * @since 1.7.0 Includes `target_type = 'unresolved'` rows with `rot_reason = 'unresolved'`.
 */
final class InternalRotDetector {

	/**
	 * Returns all internal-link rot rows.
	 *
	 * Each returned object has the same shape as a `report_links` row
	 * plus a `rot_reason` string (`'deleted'`, `'not_published'`, or
	 * `'unresolved'`) and a `target_status` field carrying the target
	 * post's actual `post_status` (e.g. `'draft'`, `'future'`,
	 * `'private'`) when `rot_reason` is `'not_published'`. `target_status`
	 * is `NULL` for deleted posts, term targets, and unresolved rows.
	 *
	 * @since 1.0.0
	 * @since 1.7.0 Includes rows with `rot_reason = 'unresolved'`.
	 * @since 1.9.0 Includes a `target_status` field.
	 *
	 * @param int $limit Optional. Maximum rows to return. Default 500.
	 *
	 * @return array<int, object>
	 */
	public function detect( int $limit = 500 ): array {
		global $wpdb;

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

		$limit = max( 1, min( $limit, 5000 ) );
		$table = TableNames::report_links();

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- On-demand report query; caching is the caller's responsibility.
		$rows = $wpdb->get_results(
			$wpdb->prepare(
				"SELECT
					rl.*,
					p.post_status AS target_status,
					CASE
						WHEN rl.target_type = 'post' AND p.ID IS NULL THEN 'deleted'
						WHEN rl.target_type = 'post' AND p.post_status != 'publish' THEN 'not_published'
						WHEN rl.target_type = 'term' AND tt.term_id IS NULL THEN 'deleted'
						WHEN rl.target_type = 'unresolved' THEN 'unresolved'
						ELSE 'unknown'
					END AS rot_reason
				FROM %i AS rl
				LEFT JOIN {$wpdb->posts} AS p
					ON rl.target_type = 'post' AND rl.target_id = p.ID
				LEFT JOIN {$wpdb->term_taxonomy} AS tt
					ON rl.target_type = 'term' AND rl.target_id = tt.term_id
				WHERE rl.is_internal = 1
				AND (
					( rl.target_type = 'post'  AND ( p.ID IS NULL OR p.post_status != 'publish' ) )
					OR
					( rl.target_type = 'term'  AND tt.term_id IS NULL )
					OR
					rl.target_type = 'unresolved'
				)
				ORDER BY rl.post_id ASC, rl.id ASC
				LIMIT %d",
				$table,
				$limit
			)
		);

		return is_array( $rows ) ? $rows : array();
	}

	/**
	 * Returns the count of internal-link rot rows without fetching them.
	 *
	 * Useful for dashboard widgets that only need a number.
	 *
	 * @since 1.0.0
	 * @since 1.7.0 Includes `target_type = 'unresolved'` rows in the count.
	 *
	 * @return int
	 */
	public function count(): int {
		global $wpdb;

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

		$table = TableNames::report_links();

		// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Count query; caching is the caller's responsibility.
		$count = $wpdb->get_var(
			$wpdb->prepare(
				"SELECT COUNT(rl.id)
				FROM %i AS rl
				LEFT JOIN {$wpdb->posts} AS p
					ON rl.target_type = 'post' AND rl.target_id = p.ID
				LEFT JOIN {$wpdb->term_taxonomy} AS tt
					ON rl.target_type = 'term' AND rl.target_id = tt.term_id
				WHERE rl.is_internal = 1
				AND (
					( rl.target_type = 'post'  AND ( p.ID IS NULL OR p.post_status != 'publish' ) )
					OR
					( rl.target_type = 'term'  AND tt.term_id IS NULL )
					OR
					rl.target_type = 'unresolved'
				)",
				$table
			)
		);

		return is_numeric( $count ) ? (int) $count : 0;
	}
}