<?php
/**
 * Single source of truth for database table names.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Database;

/**
 * Constants and getters for every plugin-managed database table.
 *
 * The bare-name constants hold the unprefixed table name. The static
 * getter methods prepend `$wpdb->prefix` to produce the runtime table
 * name. Always call the getter — never concatenate the prefix yourself.
 *
 * Adding a new table is a two-step change: declare the constant + getter
 * here, then create a `Migration_NNN_*` class that materialises it.
 *
 * The schema is deliberately minimal — three tables. Internal-link rot
 * detection is a derived query against `report_links`, not a separate
 * table.
 *
 * Only tables this plugin owns are listed. The Pro add-on's tables
 * (`postlinkly_keywords`, `postlinkly_urls`, `postlinkly_embeddings`) are
 * named by Pro, so deleting this plugin never drops them.
 *
 * @since 1.0.0
 * @since 1.18.0 The auto-link, URL-changer, and embeddings tables moved to
 *        the Pro add-on.
 */
final class TableNames {

	/**
	 * Link relationships discovered by the scanner. One row per link
	 * found in post or term content. Acts as both data store and audit
	 * log: when a link was inserted by an auto-link rule, `keyword_id`
	 * points to the rule; when modified by a URL-changer rule,
	 * `url_rule_id` points to the rule and `original_url` preserves the
	 * pre-change value.
	 *
	 * Internal-link rot is a derived query on this table — rows where
	 * `is_internal = 1` and `target_id` no longer resolves to a published
	 * post or term.
	 */
	public const REPORT_LINKS = 'postlinkly_report_links';

	/**
	 * Target keyword (focus keyword) data per post, sourced from SEO
	 * plugins or entered manually.
	 */
	public const TARGET_KEYWORDS = 'postlinkly_target_keywords';

	/**
	 * Corpus-wide stem document-frequency map. One row per stem that
	 * appears in at least one indexed candidate post, with a running
	 * count of how many candidates contain it. Backs the suggestion
	 * engine's IDF calculation so it no longer has to derive the map by
	 * scanning every candidate's content on each request.
	 *
	 * @since 1.10.0
	 */
	public const STEM_FREQUENCY = 'postlinkly_stem_frequency';

	/**
	 * Returns the report-links table name with the WP prefix applied.
	 *
	 * @since 1.0.0
	 */
	public static function report_links(): string {
		global $wpdb;
		return $wpdb->prefix . self::REPORT_LINKS;
	}

	/**
	 * Returns the target-keywords table name with the WP prefix applied.
	 *
	 * @since 1.0.0
	 */
	public static function target_keywords(): string {
		global $wpdb;
		return $wpdb->prefix . self::TARGET_KEYWORDS;
	}

	/**
	 * Returns the stem-frequency table name with the WP prefix.
	 *
	 * @since 1.10.0
	 */
	public static function stem_frequency(): string {
		global $wpdb;
		return $wpdb->prefix . self::STEM_FREQUENCY;
	}

	/**
	 * Returns every plugin-managed table name with the WP prefix applied.
	 *
	 * Used by the uninstaller to drop every table the plugin owns.
	 *
	 * @since 1.0.0
	 * @since 1.10.0 Includes the stem-frequency table.
	 * @since 1.18.0 Lists only the tables this plugin owns.
	 *
	 * @return array<int, string>
	 */
	public static function all(): array {
		return array(
			self::report_links(),
			self::target_keywords(),
			self::stem_frequency(),
		);
	}
}