<?php
/**
 * WordPress Coding Standard.
 *
 * @package WPCS\WordPressCodingStandards
 * @link    https://github.com/WordPress/WordPress-Coding-Standards
 * @license https://opensource.org/licenses/MIT MIT
 */

namespace WordPressCS\WordPress\Sniffs\WP;

use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Utils\MessageHelper;
use PHPCSUtils\Utils\PassedParameters;
use PHPCSUtils\Utils\TextStrings;
use WordPressCS\WordPress\AbstractFunctionParameterSniff;
use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;
use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;

/**
 * Check that capabilities are used correctly.
 *
 * User capabilities should be used, not roles or deprecated capabilities.
 *
 * @since 3.0.0
 *
 * @uses \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
 */
final class CapabilitiesSniff extends AbstractFunctionParameterSniff {

	use MinimumWPVersionTrait;

	/**
	 * List of custom capabilities.
	 *
	 * @since 3.0.0
	 *
	 * @var array
	 */
	public $custom_capabilities = array();

	/**
	 * The group name for this group of functions.
	 *
	 * @since 3.0.0
	 *
	 * @var string
	 */
	protected $group_name = 'caps_not_roles';

	/**
	 * List of functions that accept roles and capabilities as an argument.
	 *
	 * The functions are defined in `wp-admin/includes/plugin.php` and
	 * `/wp-includes/capabilities.php`.
	 * The list is sorted alphabetically.
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, array> The key is the name of a function we're targetting,
	 *                           the value is an array containing the 1-based parameter position
	 *                           of the "capability" parameter within the function, as well as
	 *                           the name of the parameter as declared in the function.
	 *                           If the parameter name has been renamed since the release of PHP 8.0,
	 *                           the parameter can be set as an array.
	 */
	protected $target_functions = array(
		'add_comments_page'         => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_dashboard_page'        => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_links_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_management_page'       => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_media_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_menu_page'             => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_object_page'           => array( // Deprecated since WP 4.5.0.
			'position' => 3,
			'name'     => 'capability',
		),
		'add_options_page'          => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_pages_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_plugins_page'          => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_posts_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_submenu_page'          => array(
			'position' => 4,
			'name'     => 'capability',
		),
		'add_theme_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_users_page'            => array(
			'position' => 3,
			'name'     => 'capability',
		),
		'add_utility_page'          => array( // Deprecated since WP 4.5.0.
			'position' => 3,
			'name'     => 'capability',
		),
		'author_can'                => array(
			'position' => 2,
			'name'     => 'capability',
		),
		'current_user_can'          => array(
			'position' => 1,
			'name'     => 'capability',
		),
		'current_user_can_for_blog' => array(
			'position' => 2,
			'name'     => 'capability',
		),
		'map_meta_cap'              => array(
			'position' => 1,
			'name'     => 'cap',
		),
		'user_can'                  => array(
			'position' => 2,
			'name'     => 'capability',
		),
	);

	/**
	 * List of core roles which should not to be used directly.
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, true> Key is role available in WP Core, value irrelevant.
	 */
	private $core_roles = array(
		'super_admin'   => true,
		'administrator' => true,
		'editor'        => true,
		'author'        => true,
		'contributor'   => true,
		'subscriber'    => true,
	);

	/**
	 * List of known primitive and meta core capabilities.
	 *
	 * Sources:
	 * - {@link https://wordpress.org/support/article/roles-and-capabilities/ Roles and Capabilities handbook page}
	 * - The `map_meta_cap()` function in the `src/wp-includes/capabilities.php` file.
	 * - The tests in the `tests/phpunit/tests/user/capabilities.php` file.
	 *
	 * List is sorted alphabetically.
	 *
	 * {@internal To be updated after every major release. Last updated for WordPress 6.1.0.}
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, true> All capabilities available in core.
	 */
	private $core_capabilities = array(
		'activate_plugin'             => true,
		'activate_plugins'            => true,
		'add_comment_meta'            => true,
		'add_post_meta'               => true,
		'add_term_meta'               => true,
		'add_user_meta'               => true,
		'add_users'                   => true,
		'assign_categories'           => true,
		'assign_post_tags'            => true,
		'assign_term'                 => true,
		'create_app_password'         => true,
		'create_sites'                => true,
		'create_users'                => true,
		'customize'                   => true,
		'deactivate_plugin'           => true,
		'deactivate_plugins'          => true,
		'delete_app_password'         => true,
		'delete_app_passwords'        => true,
		'delete_block'                => true, // Only seen in tests.
		'delete_blocks'               => true, // Alias for 'delete_posts', but supported.
		'delete_categories'           => true,
		'delete_comment_meta'         => true,
		'delete_others_blocks'        => true, // Alias for 'delete_others_posts', but supported.
		'delete_others_pages'         => true,
		'delete_others_posts'         => true,
		'delete_page'                 => true, // Alias, but supported.
		'delete_pages'                => true,
		'delete_plugins'              => true,
		'delete_post_tags'            => true,
		'delete_post'                 => true, // Alias, but supported.
		'delete_post_meta'            => true,
		'delete_posts'                => true,
		'delete_private_blocks'       => true, // Alias for 'delete_private_posts', but supported.
		'delete_private_pages'        => true,
		'delete_private_posts'        => true,
		'delete_published_blocks'     => true, // Alias for 'delete_published_posts', but supported.
		'delete_published_pages'      => true,
		'delete_published_posts'      => true,
		'delete_site'                 => true,
		'delete_sites'                => true,
		'delete_term'                 => true,
		'delete_term_meta'            => true,
		'delete_themes'               => true,
		'delete_user'                 => true, // Alias for 'delete_users', but supported.
		'delete_user_meta'            => true,
		'delete_users'                => true,
		'edit_app_password'           => true,
		'edit_categories'             => true,
		'edit_block'                  => true, // Only seen in tests.
		'edit_blocks'                 => true, // Alias for 'edit_posts', but supported.
		'edit_comment'                => true, // Alias, but supported.
		'edit_comment_meta'           => true,
		'edit_css'                    => true,
		'edit_dashboard'              => true,
		'edit_files'                  => true,
		'edit_others_blocks'          => true, // Alias for 'edit_others_posts', but supported.
		'edit_others_pages'           => true,
		'edit_others_posts'           => true,
		'edit_page'                   => true, // Alias, but supported.
		'edit_pages'                  => true,
		'edit_plugins'                => true,
		'edit_post_tags'              => true,
		'edit_post'                   => true, // Alias, but supported.
		'edit_post_meta'              => true,
		'edit_posts'                  => true,
		'edit_private_blocks'         => true, // Alias for 'edit_private_posts', but supported.
		'edit_private_pages'          => true,
		'edit_private_posts'          => true,
		'edit_published_blocks'       => true, // Alias for 'edit_published_posts', but supported.
		'edit_published_pages'        => true,
		'edit_published_posts'        => true,
		'edit_term'                   => true,
		'edit_term_meta'              => true,
		'edit_theme_options'          => true,
		'edit_themes'                 => true,
		'edit_user'                   => true, // Alias for 'edit_users', but supported.
		'edit_user_meta'              => true,
		'edit_users'                  => true,
		'erase_others_personal_data'  => true,
		'export'                      => true,
		'export_others_personal_data' => true,
		'import'                      => true,
		'install_languages'           => true,
		'install_plugins'             => true,
		'install_themes'              => true,
		'list_app_passwords'          => true,
		'list_users'                  => true,
		'manage_categories'           => true,
		'manage_links'                => true,
		'manage_network'              => true,
		'manage_network_options'      => true,
		'manage_network_plugins'      => true,
		'manage_network_themes'       => true,
		'manage_network_users'        => true,
		'manage_options'              => true,
		'manage_post_tags'            => true,
		'manage_privacy_options'      => true,
		'manage_sites'                => true,
		'moderate_comments'           => true,
		'publish_blocks'              => true, // Alias for 'publish_posts', but supported.
		'publish_pages'               => true,
		'publish_post'                => true, // Alias, but supported.
		'publish_posts'               => true,
		'promote_user'                => true,
		'promote_users'               => true,
		'read'                        => true,
		'read_block'                  => true, // Only seen in tests.
		'read_post'                   => true, // Alias, but supported.
		'read_page'                   => true, // Alias, but supported.
		'read_app_password'           => true,
		'read_private_blocks'         => true, // Alias for 'read_private_posts', but supported.
		'read_private_pages'          => true,
		'read_private_posts'          => true,
		'remove_user'                 => true, // Alias for 'remove_users', but supported.
		'remove_users'                => true,
		'resume_plugin'               => true, // Alias for 'resume_plugins', but supported.
		'resume_plugins'              => true,
		'resume_theme'                => true, // Alias for 'resume_themes', but supported.
		'resume_themes'               => true,
		'setup_network'               => true,
		'switch_themes'               => true,
		'unfiltered_html'             => true,
		'unfiltered_upload'           => true,
		'update_core'                 => true,
		'update_https'                => true,
		'update_languages'            => true,
		'update_plugins'              => true,
		'update_php'                  => true,
		'update_themes'               => true,
		'upgrade_network'             => true,
		'upload_files'                => true,
		'upload_plugins'              => true,
		'upload_themes'               => true,
		'view_site_health_checks'     => true,
	);

	/**
	 * List of deprecated core capabilities.
	 *
	 * User Levels were deprecated in version 3.0.
	 *
	 * {@internal To be updated after every major release. Last updated for WordPress 6.1.0.}
	 *
	 * @link https://github.com/WordPress/wordpress-develop/blob/master/tests/phpunit/tests/user/capabilities.php
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, string> All deprecated capabilities in core.
	 */
	private $deprecated_capabilities = array(
		'level_10' => '3.0.0',
		'level_9'  => '3.0.0',
		'level_8'  => '3.0.0',
		'level_7'  => '3.0.0',
		'level_6'  => '3.0.0',
		'level_5'  => '3.0.0',
		'level_4'  => '3.0.0',
		'level_3'  => '3.0.0',
		'level_2'  => '3.0.0',
		'level_1'  => '3.0.0',
		'level_0'  => '3.0.0',
	);

	/**
	 * Process the parameters of a matched function.
	 *
	 * @since 3.0.0
	 *
	 * @param int    $stackPtr        The position of the current token in the stack.
	 * @param string $group_name      The name of the group which was matched.
	 * @param string $matched_content The token content (function name) which was matched
	 *                                in lowercase.
	 * @param array  $parameters      Array with information about the parameters.
	 *
	 * @return void
	 */
	public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
		$function_details = $this->target_functions[ $matched_content ];

		$parameter = PassedParameters::getParameterFromStack(
			$parameters,
			$function_details['position'],
			$function_details['name']
		);

		if ( false === $parameter ) {
			return;
		}

		// If the parameter is anything other than T_CONSTANT_ENCAPSED_STRING throw a warning and bow out.
		$first_non_empty = null;
		for ( $i = $parameter['start']; $i <= $parameter['end']; $i++ ) {
			if ( isset( Tokens::$emptyTokens[ $this->tokens[ $i ]['code'] ] ) ) {
				continue;
			}

			if ( \T_CONSTANT_ENCAPSED_STRING !== $this->tokens[ $i ]['code']
				|| null !== $first_non_empty
			) {
				// Throw warning at low severity.
				$this->phpcsFile->addWarning(
					'Couldn\'t determine the value passed to the $%s parameter in function call to %s(). Please check if it matches a valid capability. Found: %s',
					$i,
					'Undetermined',
					array(
						$function_details['name'],
						$matched_content,
						$parameter['clean'],
					),
					3 // Message severity set to below default.
				);
				return;
			}

			$first_non_empty = $i;
		}

		if ( null === $first_non_empty ) {
			// Parse error. Bow out.
			return;
		}

		/*
		 * As of this point we know that the `$capabilities` parameter only contains the one token
		 * and that that token is a `T_CONSTANT_ENCAPSED_STRING`.
		 */
		$matched_parameter = TextStrings::stripQuotes( $this->tokens[ $first_non_empty ]['content'] );

		if ( isset( $this->core_capabilities[ $matched_parameter ] ) ) {
			return;
		}

		if ( empty( $matched_parameter ) ) {
			$this->phpcsFile->addError(
				'An empty string is not a valid capability. Empty string found as the $%s parameter in a function call to %s()"',
				$first_non_empty,
				'Invalid',
				array(
					$function_details['name'],
					$matched_content,
				)
			);
			return;
		}

		// Check if additional capabilities were registered via the ruleset and if the found capability matches any of those.
		$custom_capabilities = RulesetPropertyHelper::merge_custom_array( $this->custom_capabilities, array() );
		if ( isset( $custom_capabilities[ $matched_parameter ] ) ) {
			return;
		}

		if ( isset( $this->deprecated_capabilities[ $matched_parameter ] ) ) {
			$this->set_minimum_wp_version();
			$is_error = $this->wp_version_compare( $this->deprecated_capabilities[ $matched_parameter ], $this->minimum_wp_version, '<' );

			$data = array(
				$matched_parameter,
				$matched_content,
				$this->deprecated_capabilities[ $matched_parameter ],
			);

			MessageHelper::addMessage(
				$this->phpcsFile,
				'The capability "%s", found in the function call to %s(), has been deprecated since WordPress version %s.',
				$first_non_empty,
				$is_error,
				'Deprecated',
				$data
			);
			return;
		}

		if ( isset( $this->core_roles[ $matched_parameter ] ) ) {
			$this->phpcsFile->addError(
				'Capabilities should be used instead of roles. Found "%s" in function call to %s()',
				$first_non_empty,
				'RoleFound',
				array(
					$matched_parameter,
					$matched_content,
				)
			);
			return;
		}

		$this->phpcsFile->addWarning(
			'Found unknown capability "%s" in function call to %s(). Please check the spelling of the capability. If this is a custom capability, please verify the capability is registered with WordPress via a call to WP_Role(s)->add_cap().' . \PHP_EOL . 'Custom capabilities can be made known to this sniff by setting the "custom_capabilities" property in the PHPCS ruleset.',
			$first_non_empty,
			'Unknown',
			array(
				$matched_parameter,
				$matched_content,
			)
		);
	}
}