<?php
/**
 * Plugin activation handler.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Bootstrap;

use Postlinkly\Bootstrap\Migrations\MigrationInterface;
use Postlinkly\Bootstrap\Migrations\MigrationRunner;
use Postlinkly\Bootstrap\Migrations\Migration_001_InitialSchema;
use Postlinkly\Bootstrap\Migrations\Migration_005_AddStemFrequencyTable;
use Postlinkly\Bootstrap\Migrations\Migration_006_DropUnusedTrackingColumn;

/**
 * Plugin activation handler.
 *
 * Runs once when the user activates the plugin. Idempotent: subsequent
 * activations (e.g. via "Reactivate" after deactivation) only run the
 * migrations that have not yet been applied.
 *
 * @since 1.0.0
 */
final class Activator {

	/**
	 * Runs the activation routine.
	 *
	 * @since 1.0.0
	 * @hook  register_activation_hook
	 *
	 * @return void
	 */
	public static function run(): void {
		( new MigrationRunner( self::known_migrations() ) )->run_pending();
	}

	/**
	 * Returns every migration class shipped with the plugin.
	 *
	 * Order does not matter — MigrationRunner sorts by version. Each new
	 * migration must be appended here.
	 *
	 * Versions 2 to 4 are missing on purpose: they created the embeddings
	 * table, which belongs to the Pro add-on and is migrated there. The gap
	 * is safe because MigrationRunner runs every migration whose version is
	 * above the stored one; it never expects consecutive numbers. Do not
	 * reuse 2 to 4 — a site that already ran them has a schema version past
	 * them and would never run a new migration given one of those numbers.
	 *
	 * @since 1.0.0
	 * @since 1.10.0 Registers Migration_005_AddStemFrequencyTable.
	 * @since 1.17.2 Registers Migration_006_DropUnusedTrackingColumn.
	 * @since 1.18.0 The embeddings migrations (2 to 4) moved to the Pro add-on.
	 *
	 * @return array<int, MigrationInterface>
	 */
	public static function known_migrations(): array {
		return array(
			new Migration_001_InitialSchema(),
			new Migration_005_AddStemFrequencyTable(),
			new Migration_006_DropUnusedTrackingColumn(),
		);
	}
}