<?php
/**
 * Per-block recommendations for a parsed Gutenberg block tree.
 *
 * Priority 2 (zvedene-tz 2.1) extracted the actual rule logic out of this
 * class into ABDS_SEO_Rules_Engine, which operates on a source-agnostic
 * ContentUnit sequence rather than a parse_blocks() tree — so a future
 * rendered-HTML source (Priority 3) doesn't need a second, divergent copy
 * of these rules. This class is now a thin compatibility shim: it builds
 * ContentUnits via ABDS_SEO_Block_Content_Adapter, runs the engine, and
 * translates findings back into the block_ref/block_type shape this
 * class's own callers already depend on. No caller of analyze() needs to
 * change (block_ref's value scheme did change once, see translate_finding()).
 *
 * Has zero direct WordPress function calls itself (the adapter and engine
 * it delegates to are equally WP-free) — unit testable without
 * bootstrapping WP, per the same pattern as ABDS_SEO_Keyword_Extractor
 * and ABDS_SEO_Readability_Checker.
 *
 * @package ABDS_SEO
 */

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

/**
 * Produces per-block recommendations from a parsed block tree.
 *
 * Severity uses the same three-level scale as ABDS_SEO_Site_Scanner's
 * technical issues (critical/warning/info), so every part of the plugin's
 * REST output agrees on one shared vocabulary rather than each module
 * inventing its own.
 */
class ABDS_SEO_Block_Recommendations {

	const SEVERITY_CRITICAL = ABDS_SEO_Rules_Engine::SEVERITY_CRITICAL;
	const SEVERITY_WARNING  = ABDS_SEO_Rules_Engine::SEVERITY_WARNING;
	const SEVERITY_INFO     = ABDS_SEO_Rules_Engine::SEVERITY_INFO;

	/**
	 * Gutenberg block types the engine has rules for. Any other block
	 * type still becomes a content unit (kind 'other') but is never
	 * itself flagged.
	 */
	const RELEVANT_BLOCK_TYPES = array( 'core/heading', 'core/paragraph', 'core/image', 'core/list' );

	/**
	 * The source-agnostic rule engine this class now delegates to.
	 *
	 * @var ABDS_SEO_Rules_Engine
	 */
	protected ABDS_SEO_Rules_Engine $engine;

	/**
	 * Constructor.
	 *
	 * @param ABDS_SEO_Keyword_Extractor|null $keywords Optional injected instance (for tests); a fresh one is created otherwise.
	 */
	public function __construct( ?ABDS_SEO_Keyword_Extractor $keywords = null ) {
		$this->engine = new ABDS_SEO_Rules_Engine( $keywords );
	}

	/**
	 * Analyzes a parsed block tree and returns per-block recommendations.
	 *
	 * @param array<int, array{blockName:?string, attrs:array, innerBlocks:array, innerHTML:string, innerContent:array}> $blocks        parse_blocks() output.
	 * @param string                                                                                                     $focus_keyword Focus keyword (or phrase); keyword-dependent checks are skipped when empty.
	 * @return array<int, array{block_ref:string, block_type:string, content_snippet:string, issue:string, severity:string}>
	 */
	public function analyze( array $blocks, string $focus_keyword ): array {
		$units    = ABDS_SEO_Block_Content_Adapter::units_from_blocks( $blocks );
		$findings = $this->engine->evaluate( $units, $focus_keyword );

		return array_map( array( $this, 'translate_finding' ), $findings );
	}

	/**
	 * Translates one of the engine's source-agnostic findings back into
	 * this class's existing, block-specific return shape. `block_ref` was
	 * `block_path` (an int[] position) until Priority 3.3 — renamed
	 * because its value is now ABDS_SEO_Content_Ref::of(), a content hash,
	 * and calling a hash a "path" would be misleading. The one JS consumer
	 * (src/sidebar.js's findMatchingClientId()) was updated in the same
	 * change.
	 *
	 * @param array{ref:string, kind:string, source_type:string, content_snippet:string, issue:string, severity:string} $finding Engine finding.
	 * @return array{block_ref:string, block_type:string, content_snippet:string, issue:string, severity:string}
	 */
	protected function translate_finding( array $finding ): array {
		return array(
			'block_ref'       => $finding['ref'],
			'block_type'      => $finding['source_type'],
			'content_snippet' => $finding['content_snippet'],
			'issue'           => $finding['issue'],
			'severity'        => $finding['severity'],
		);
	}
}