<?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\Helpers;

use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Utils\Namespaces;
use PHPCSUtils\Utils\ObjectDeclarations;
use WordPressCS\WordPress\Helpers\RulesetPropertyHelper;

/**
 * Helper utilities for sniffs which need to take into account whether the
 * code under examination is unit test code or not.
 *
 * Usage instructions:
 * - Add appropriate `use` statement(s) to the file/class which intends to use this functionality.
 * - Now the sniff will automatically support the public `custom_test_classes` property which
 *   users can set in their custom ruleset. Do not add the property to the sniff!
 * - The sniff can call the `is_test_class()` method in this trait to verify if a class is
 *   a test class. The `is_test_class()` method will take the custom property into account.
 *
 * @since 3.0.0 The properties and method in this trait were previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and have been moved here.
 */
trait IsUnitTestTrait {

	/**
	 * Custom list of classes which test classes can extend.
	 *
	 * This property allows end-users to add to the build-in `$known_test_classes`
	 * via their custom PHPCS ruleset.
	 * This property will need to be set for each sniff which uses this trait.
	 *
	 * Currently this property is used by the `WordPress.WP.GlobalVariablesOverride`,
	 * `WordPress.NamingConventions.PrefixAllGlobals` and the `WordPress.Files.Filename` sniffs.
	 *
	 * Example usage:
	 * ```xml
	 * <rule ref="WordPress.[Subset].[Sniffname]">
	 *  <properties>
	 *   <property name="custom_test_classes" type="array">
	 *     <element value="My_Plugin_First_Test_Class"/>
	 *     <element value="My_Plugin_Second_Test_Class"/>
	 *   </property>
	 *  </properties>
	 * </rule>
	 * ```
	 *
	 * Note: it is strongly _recommended_ to exclude your test directories for
	 * select error codes of those particular sniffs instead of relying on this
	 * property/trait.
	 *
	 * @since 0.11.0
	 * @since 3.0.0  Moved from the Sniff class to this dedicated Trait.
	 *               Renamed from `$custom_test_class_whitelist` to `$custom_test_classes`.
	 *
	 * @var string[]
	 */
	public $custom_test_classes = array();

	/**
	 * List of PHPUnit and WP native classes which test classes can extend.
	 *
	 * {internal These are the test cases provided in the `/tests/phpunit/includes/`
	 *           directory of WP Core.}
	 *
	 * @since 0.11.0
	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
	 *               - Renamed from `$test_class_whitelist` to `$known_test_classes`.
	 *               - Visibility changed from protected to private.
	 *
	 * @var array<string, true> Key is class name, value irrelevant.
	 */
	private $known_test_classes = array(
		// Base test cases.
		'WP_UnitTestCase'                            => true,
		'WP_UnitTestCase_Base'                       => true,
		'PHPUnit_Adapter_TestCase'                   => true,

		// Domain specific base test cases.
		'WP_Ajax_UnitTestCase'                       => true,
		'WP_Canonical_UnitTestCase'                  => true,
		'WP_Font_Face_UnitTestCase'                  => true,
		'WP_Test_REST_Controller_Testcase'           => true,
		'WP_Test_REST_Post_Type_Controller_Testcase' => true,
		'WP_Test_REST_TestCase'                      => true,
		'WP_Test_XML_TestCase'                       => true,
		'WP_XMLRPC_UnitTestCase'                     => true,

		// PHPUnit native test cases.
		'PHPUnit_Framework_TestCase'                 => true,
		'PHPUnit\\Framework\\TestCase'               => true,
		// PHPUnit native TestCase class when imported via use statement.
		'TestCase'                                   => true,
	);

	/**
	 * Cache of previously added custom test classes.
	 *
	 * Prevents having to do the same merges over and over again.
	 *
	 * @since 3.0.0
	 *
	 * @var string[]
	 */
	private $added_custom_test_classes = array();

	/**
	 * Combined list of WP/PHPUnit native and custom test classes.
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, bool>
	 */
	private $all_test_classes = array();

	/**
	 * Retrieve a list of all registered test classes, both WP/PHPUnit native as well as custom.
	 *
	 * @since 3.0.0
	 *
	 * @return array<string, bool>
	 */
	final protected function get_all_test_classes() {
		if ( array() === $this->all_test_classes
			|| $this->custom_test_classes !== $this->added_custom_test_classes
		) {
			/*
			 * Show some tolerance for user input.
			 * The custom test class names should be passed as FQN without a prefixing `\`.
			 */
			$custom_test_classes = array();
			if ( ! empty( $this->custom_test_classes ) ) {
				foreach ( $this->custom_test_classes as $v ) {
					$custom_test_classes[] = ltrim( $v, '\\' );
				}
			}

			/*
			 * Lowercase all names, both custom as well as "known", as PHP treats namespaced names case-insensitively.
			 */
			$custom_test_classes = array_map( 'strtolower', $custom_test_classes );
			$known_test_classes  = array_change_key_case( $this->known_test_classes, \CASE_LOWER );

			$this->all_test_classes = RulesetPropertyHelper::merge_custom_array(
				$custom_test_classes,
				$known_test_classes
			);

			// Store the original value so the comparison can succeed.
			$this->added_custom_test_classes = $this->custom_test_classes;
		}

		return $this->all_test_classes;
	}

	/**
	 * Check if a class token is part of a unit test suite.
	 *
	 * Unit test classes are identified as such:
	 * - Class which either extends one of the known test cases, such as `WP_UnitTestCase`
	 *   or `PHPUnit_Framework_TestCase` or extends a custom unit test class as listed in the
	 *   `custom_test_classes` property.
	 *
	 * @since 0.12.0 Split off from the `is_token_in_test_method()` method.
	 * @since 1.0.0  Improved recognition of namespaced class names.
	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
	 *               - The `$phpcsFile` parameter was added.
	 *
	 * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
	 * @param int                         $stackPtr  The position of the token to be examined.
	 *                                               This should be a class, anonymous class or trait token.
	 *
	 * @return bool True if the class is a unit test class, false otherwise.
	 */
	final protected function is_test_class( File $phpcsFile, $stackPtr ) {

		$tokens = $phpcsFile->getTokens();

		if ( isset( $tokens[ $stackPtr ], Tokens::$ooScopeTokens[ $tokens[ $stackPtr ]['code'] ] ) === false ) {
			return false;
		}

		// Add any potentially extra custom test classes to the known test classes list.
		$known_test_classes = $this->get_all_test_classes();

		$namespace = strtolower( Namespaces::determineNamespace( $phpcsFile, $stackPtr ) );

		// Is the class/trait one of the known test classes ?
		$className = ObjectDeclarations::getName( $phpcsFile, $stackPtr );
		if ( empty( $className ) === false ) {
			$className = strtolower( $className );
			if ( '' !== $namespace ) {
				if ( isset( $known_test_classes[ $namespace . '\\' . $className ] ) ) {
					return true;
				}
			} elseif ( isset( $known_test_classes[ $className ] ) ) {
				return true;
			}
		}

		// Does the class/trait extend one of the known test classes ?
		$extendedClassName = ObjectDeclarations::findExtendedClassName( $phpcsFile, $stackPtr );
		if ( false === $extendedClassName ) {
			return false;
		}

		$extendedClassName = strtolower( $extendedClassName );

		if ( '\\' === $extendedClassName[0] ) {
			if ( isset( $known_test_classes[ substr( $extendedClassName, 1 ) ] ) ) {
				return true;
			}
		} elseif ( '' !== $namespace ) {
			if ( isset( $known_test_classes[ $namespace . '\\' . $extendedClassName ] ) ) {
				return true;
			}
		} elseif ( isset( $known_test_classes[ $extendedClassName ] ) ) {
			return true;
		}

		/*
		 * Not examining imported classes via `use` statements as with the variety of syntaxes,
		 * this would get very complicated.
		 * After all, users can add an `<exclude-pattern>` for a particular sniff to their
		 * custom ruleset to selectively exclude the test directory.
		 */

		return false;
	}
}
