<?php
/**
 * Link Architect Module.
 *
 * Bulk-builds internal links pointing TO orphan URLs FROM existing published
 * content. Companion to the Link Suggester — the suggester proposes links
 * inline as you write; the architect builds them across the whole library in
 * safe, backed-up batches.
 *
 *   - Tab 1 (Scan & Suggest): paste orphan URLs, generate per-orphan phrase
 *     candidates and matching source posts.
 *   - Tab 2 (Execute): batch-process approved suggestions; wrap the first
 *     contextually-valid occurrence of the phrase in an anchor.
 *   - Tab 3 (Restore): one-click rollback per modified source post.
 *
 * Safety baked in: already-linked detection, self-reference skip, anchor-context
 * awareness (skips headings/anchors/scripts), per-source link cap (default 3,
 * filterable), and backup-before-modify on every touched post.
 *
 * Optional Elementor support: if a post stores `_elementor_data`, insertion and
 * restore handle it too — but it's a graceful adapter, never a dependency.
 *
 * @package Platform\Helm\Modules\Link_Architect
 */

declare( strict_types = 1 );

namespace Platform\Helm\Modules\Link_Architect;

use Platform\Helm\Contracts\ModuleInterface;
use Platform\Helm\Core\Assets;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

final class LinkArchitectModule implements ModuleInterface {

	public const BATCH_SIZE         = 25;
	public const JOB_TRANSIENT      = 'platform_helm_lk_job_';
	public const JOB_TTL_SECONDS    = 3600; // 1 hour.
	public const BACKUP_META_PREFIX = '_platform_helm_lk_backup_';
	public const APPROVAL_TRANSIENT = 'platform_helm_lk_approvals_';
	public const APPROVAL_TTL       = 7200; // 2 hours — survive page refreshes between tabs.

	/** Default cap on new outbound internal links injected per source post per execution. */
	public const DEFAULT_MAX_LINKS_PER_POST = 3;

	private KeywordExtractor $extractor;
	private PostScanner $scanner;
	private BackupManager $backups;
	private LinkInserter $inserter;
	private BatchProcessor $batch_processor;
	private JobStore $jobs;
	private AjaxController $ajax;
	private AdminUI $ui;

	public function __construct( Assets $assets ) {
		$this->extractor       = new KeywordExtractor();
		$this->scanner         = new PostScanner();
		$this->backups         = new BackupManager();
		$this->inserter        = new LinkInserter();
		$this->jobs            = new JobStore();
		$this->batch_processor = new BatchProcessor( $this->backups, $this->inserter );
		$this->ajax            = new AjaxController(
			$this->extractor,
			$this->scanner,
			$this->batch_processor,
			$this->backups,
			$this->jobs
		);
		$this->ui = new AdminUI( $assets, $this->backups );
	}

	public function id(): string {
		return 'link_architect';
	}

	public function name(): string {
		return __( 'Link Architect', 'platform-helm' );
	}

	public function description(): string {
		return __( 'Bulk-builds internal links to orphan pages. Paste orphan URLs, get keyword-matched source-post suggestions, approve in batch, and inject links with context-aware placement. Every modified post is backed up first, with one-click restore. Find it under Helm → Link Architect.', 'platform-helm' );
	}

	public function default_enabled(): bool {
		return false; // Heavier, write-capable tool — opt-in.
	}

	public function boot(): void {
		Diagnostics::register_shutdown();
		Diagnostics::checkpoint( 'LinkArchitectModule::boot() called' );
		$this->ui->register_hooks();
		$this->ajax->register_hooks();
		Diagnostics::checkpoint( 'hooks registered' );
	}
}
