<?php
/**
 * Centralized read-access / disclosure policy for the v1 command grammar.
 *
 * @package ActionPanelAI
 */

namespace ActionPanelAI\Grammar;

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

/**
 * Single place that decides which read data the assistant may receive.
 *
 * This is the security/privacy boundary for reads. It is deliberately pure
 * (no WordPress calls, no command-execution coupling) so the allowlists and
 * redaction rules can be tuned in one file. Capabilities consult it; they do
 * not embed their own allowlists.
 *
	 * Dev mode (internal builds only) bypasses name-based read filtering for
	 * diagnosis. Projection code may still apply value-level redaction before data
	 * leaves the plugin process.
 */
class ReadAccessPolicy {
	/**
	 * Option names the assistant may read on a public (non-dev) build.
	 *
	 * Keep this aligned with
	 * `src/backend/app/assistant/skill_files/reference/site_settings.md`.
	 */
	private const READABLE_OPTION_EXACT = array(
		'blogname',
		'blogdescription',
		'siteurl',
		'home',
		'admin_email',
		'locale',
		'date_format',
		'time_format',
		'start_of_week',
		'gmt_offset',
		'show_on_front',
		'page_on_front',
		'page_for_posts',
		'timezone_string',
		'default_category',
		'default_post_format',
		'users_can_register',
		'permalink_structure',
		'posts_per_page',
		'posts_per_rss',
		'rss_use_excerpt',
		'default_comment_status',
		'default_ping_status',
		'comment_moderation',
		'comment_registration',
		'comments_per_page',
		'thread_comments',
		'thread_comments_depth',
		'require_name_email',
		'close_comments_for_old_posts',
		'close_comments_days_old',
		'show_avatars',
		'avatar_rating',
		'avatar_default',
		'thumbnail_size_w',
		'thumbnail_size_h',
		'thumbnail_crop',
		'medium_size_w',
		'medium_size_h',
		'large_size_w',
		'large_size_h',
		'uploads_use_yearmonth_folders',
		'category_base',
		'tag_base',
		'blog_charset',
		'blog_public',
		'template',
		'stylesheet',
		'active_plugins',
		'sidebars_widgets',
		'custom_logo',
		'site_icon',
		'woocommerce_cart_page_id',
		'woocommerce_checkout_page_id',
		'woocommerce_myaccount_page_id',
		'woocommerce_shop_page_id',
		'woocommerce_terms_page_id',
		'woocommerce_default_country',
		'woocommerce_weight_unit',
		'woocommerce_dimension_unit',
		'woocommerce_currency',
		'woocommerce_currency_pos',
		'woocommerce_price_thousand_sep',
		'woocommerce_price_decimal_sep',
		'woocommerce_price_num_decimals',
		'woocommerce_calc_taxes',
		'rewrite_rules',
	);

	/**
	 * Option-name prefixes the assistant may read on a public build.
	 */
	private const READABLE_OPTION_PREFIXES = array(
		'woocommerce_store_',
		'theme_mods_',
		'wpseo_',
		'rank_math_',
	);

	/**
	 * Return exact public option names for storage-level filtering.
	 *
	 * @return array<int, string>
	 */
	public function readable_option_exact_names(): array {
		return self::READABLE_OPTION_EXACT;
	}

	/**
	 * Return public option-name prefixes for storage-level filtering.
	 *
	 * @return array<int, string>
	 */
	public function readable_option_prefixes(): array {
		return self::READABLE_OPTION_PREFIXES;
	}

	/**
	 * Return whether a single option name is readable.
	 *
	 * @param string $name     Option name.
	 * @param bool   $dev_mode Whether the internal dev module is active.
	 */
	public function is_option_readable( string $name, bool $dev_mode = false ): bool {
		if ( $dev_mode ) {
			return true;
		}
		if ( in_array( $name, self::READABLE_OPTION_EXACT, true ) ) {
			return true;
		}
		foreach ( self::READABLE_OPTION_PREFIXES as $prefix ) {
			if ( '' !== $prefix && str_starts_with( $name, $prefix ) ) {
				return true;
			}
		}
		return false;
	}

	/**
	 * Filter a list of option documents down to the readable allowlist.
	 *
	 * Filtering happens before pagination so a page is never silently shrunk
	 * by a later redaction pass.
	 *
	 * @param array<int, array> $documents Option documents shaped `{identity:{name},...}`.
	 * @param bool              $dev_mode  Whether the internal dev module is active.
	 * @return array<int, array>
	 */
	public function filter_readable_options( array $documents, bool $dev_mode = false ): array {
		if ( $dev_mode ) {
			return $documents;
		}
		return array_values(
			array_filter(
				$documents,
				function ( $document ): bool {
					$name = is_array( $document ) && isset( $document['identity']['name'] )
						? (string) $document['identity']['name']
						: '';
					return '' !== $name && $this->is_option_readable( $name, false );
				}
			)
		);
	}
}