<?php
/**
 * Single source of truth for plugin capability requirements.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Capabilities;

/**
 * Maps internal action keywords to WordPress capability strings.
 *
 * Every capability check across the plugin reads from this class. Menu
 * pages, AJAX handlers, REST permission callbacks, and template-level
 * checks all call `for($action)` — never `current_user_can('foo')` with
 * a literal capability.
 *
 * Site owners can override mappings via the `postlinkly_capability_for`
 * filter, which keeps the customisation surface narrow and discoverable.
 *
 * @since 1.0.0
 */
final class CapabilityMap {

	/**
	 * Returns the capability required for the given action.
	 *
	 * Unknown actions fall back to `manage_options` (the safest default).
	 * The `postlinkly_capability_for` filter lets sites adjust the mapping.
	 *
	 * `edit_target_post` is a WordPress **meta** capability, unlike every
	 * other entry here — it must always be checked with a post id, e.g.
	 * `current_user_can( CapabilityMap::for( 'edit_target_post' ), $post_id )`,
	 * so WordPress can resolve ownership/status/post-type per post instead
	 * of granting access to any post to anyone holding the primitive cap.
	 *
	 * @since 1.0.0
	 * @since 1.5.0 Added the `edit_target_post` meta capability.
	 *
	 * @param string $action Internal action keyword (see class constants).
	 *
	 * @return string A WordPress capability string.
	 */
	public static function for( string $action ): string {
		$map = array(
			'view_dashboard'   => 'edit_posts',
			'view_report'      => 'edit_posts',
			'manage_links'     => 'edit_posts',
			// META capability (see docblock above) — every other entry here is
			// a primitive capability WordPress checks without the post id.
			'edit_target_post' => 'edit_post',
			'manage_settings'  => 'manage_options',
			'manage_broken'    => 'manage_options',
			'run_tools'        => 'manage_options',
			'export'           => 'manage_options',
		);

		$capability = $map[ $action ] ?? 'manage_options';

		/**
		 * Filters the capability required for a Postlinkly action.
		 *
		 * @since 1.0.0
		 *
		 * @param string $capability Default capability for the action.
		 * @param string $action     The action keyword being mapped.
		 */
		return (string) apply_filters( 'postlinkly_capability_for', $capability, $action );
	}
}