Level 6

Author: swissspidy

lib/cli/Arguments.php

@@ -19,14 +19,23 @@
 
 /**
  * Parses command line arguments.
+ *
+ * @implements \ArrayAccess<string, mixed>
  */
 class Arguments implements \ArrayAccess {
+	/** @var array<string, array<string, mixed>> */
 	protected $_flags = array();
+	/** @var array<string, array<string, mixed>> */
 	protected $_options = array();
+	/** @var bool */
 	protected $_strict = false;
+	/** @var array<int, string> */
 	protected $_input = array();
+	/** @var array<int, string> */
 	protected $_invalid = array();
+	/** @var array<string, mixed>|null */
 	protected $_parsed;
+	/** @var Lexer|null */
 	protected $_lexer;
 
 	/**
@@ -36,7 +45,7 @@ class Arguments implements \ArrayAccess {
 	 *
 	 * `'help'` is `true` by default, `'strict'` is false by default.
 	 *
-	 * @param  array  $options  An array of options for this parser.
+	 * @param  array<string, mixed>  $options  An array of options for this parser.
 	 */
 	public function __construct($options = array()) {
 		$options += array(
@@ -58,7 +67,7 @@ public function __construct($options = array()) {
 	/**
 	 * Get the list of arguments found by the defined definitions.
 	 *
-	 * @return array
+	 * @return array<string, mixed>
 	 */
 	public function getArguments() {
 		if (!isset($this->_parsed)) {
@@ -67,6 +76,11 @@ public function getArguments() {
 		return $this->_parsed;
 	}
 
+	/**
+	 * Get the help screen.
+	 *
+	 * @return HelpScreen
+	 */
 	public function getHelpScreen() {
 		return new HelpScreen($this);
 	}
@@ -147,7 +161,7 @@ public function offsetUnset($offset) {
 	 * Adds a flag (boolean argument) to the argument list.
 	 *
 	 * @param mixed  $flag  A string representing the flag, or an array of strings.
-	 * @param array  $settings  An array of settings for this flag.
+	 * @param array<string, mixed>|string  $settings  An array of settings for this flag.
 	 * @setting string  description  A description to be shown in --help.
 	 * @setting bool    default  The default value for this flag.
 	 * @setting bool    stackable  Whether the flag is repeatable to increase the value.
@@ -183,7 +197,7 @@ public function addFlag($flag, $settings = array()) {
 	 * primary flag character, and the values should be the settings array
 	 * used by {addFlag}.
 	 *
-	 * @param array  $flags  An array of flags to add
+	 * @param array<string, array<string, mixed>|string>  $flags  An array of flags to add
 	 * @return $this
 	 */
 	public function addFlags($flags) {
@@ -203,7 +217,7 @@ public function addFlags($flags) {
 	 * Adds an option (string argument) to the argument list.
 	 *
 	 * @param mixed  $option  A string representing the option, or an array of strings.
-	 * @param array  $settings  An array of settings for this option.
+	 * @param array<string, mixed>|string  $settings  An array of settings for this option.
 	 * @setting string  description  A description to be shown in --help.
 	 * @setting bool    default  The default value for this option.
 	 * @setting array   aliases  Other ways to trigger this option.
@@ -237,7 +251,7 @@ public function addOption($option, $settings = array()) {
 	 * primary option string, and the values should be the settings array
 	 * used by {addOption}.
 	 *
-	 * @param array  $options  An array of options to add
+	 * @param array<string, array<string, mixed>|string>  $options  An array of options to add
 	 * @return $this
 	 */
 	public function addOptions($options) {
@@ -271,7 +285,7 @@ public function setStrict($strict) {
 	/**
 	 * Get the list of invalid arguments the parser found.
 	 *
-	 * @return array
+	 * @return array<int, string>
 	 */
 	public function getInvalidArguments() {
 		return $this->_invalid;
@@ -282,7 +296,7 @@ public function getInvalidArguments() {
 	 *
 	 * @param mixed  $flag  Either a string representing the flag or an
 	 *                      cli\arguments\Argument object.
-	 * @return array|null
+	 * @return array<string, mixed>|null
 	 */
 	public function getFlag($flag) {
 		if ($flag instanceOf Argument) {
@@ -308,10 +322,20 @@ public function getFlag($flag) {
 		return null;
 	}
 
+	/**
+	 * Get all flags.
+	 *
+	 * @return array<string, array<string, mixed>>
+	 */
 	public function getFlags() {
 		return $this->_flags;
 	}
 
+	/**
+	 * Check if there are any flags defined.
+	 *
+	 * @return bool
+	 */
 	public function hasFlags() {
 		return !empty($this->_flags);
 	}
@@ -345,7 +369,7 @@ public function isStackable($flag) {
 	 *
 	 * @param mixed  $option Either a string representing the option or an
 	 *                       cli\arguments\Argument object.
-	 * @return array|null
+	 * @return array<string, mixed>|null
 	 */
 	public function getOption($option) {
 		if ($option instanceOf Argument) {
@@ -370,10 +394,20 @@ public function getOption($option) {
 		return null;
 	}
 
+	/**
+	 * Get all options.
+	 *
+	 * @return array<string, array<string, mixed>>
+	 */
 	public function getOptions() {
 		return $this->_options;
 	}
 
+	/**
+	 * Check if there are any options defined.
+	 *
+	 * @return bool
+	 */
 	public function hasOptions() {
 		return !empty($this->_options);
 	}
@@ -424,6 +458,8 @@ public function parse() {
 	 * This applies the default values, if any, of all of the
 	 * flags and options, so that if there is a default value
 	 * it will be available.
+	 *
+	 * @return void
 	 */
 	private function _applyDefaults() {
 		foreach($this->_flags as $flag => $settings) {
@@ -438,10 +474,22 @@ private function _applyDefaults() {
 		}
 	}
 
+	/**
+	 * Warn about something.
+	 *
+	 * @param string $message
+	 * @return void
+	 */
 	private function _warn($message) {
 		trigger_error('[' . __CLASS__ .'] ' . $message, E_USER_WARNING);
 	}
 
+	/**
+	 * Parse a flag.
+	 *
+	 * @param Argument $argument
+	 * @return bool
+	 */
 	private function _parseFlag($argument) {
 		if (!$this->isFlag($argument)) {
 			return false;
@@ -460,6 +508,12 @@ private function _parseFlag($argument) {
 		return true;
 	}
 
+	/**
+	 * Parse an option.
+	 *
+	 * @param Argument $option
+	 * @return bool
+	 */
 	private function _parseOption($option) {
 		if (!$this->isOption($option)) {
 			return false;
@@ -490,7 +544,6 @@ private function _parseOption($option) {
 			$value = $this->_lexer->current();
 			array_push( $values, $value->raw );
 
-			// @phpstan-ignore-next-line
 			if ( ! $this->_lexer->end() && ! $this->_lexer->peek->isValue ) {
 				break;
 			}

lib/cli/Colors.php

@@ -18,6 +18,7 @@
  * Reference: http://graphcomp.com/info/specs/ansi_col.html#colors
  */
 class Colors {
+	/** @var array<string, array<string, int>> */
 	static protected $_colors = array(
 		'color' => array(
 			'black'   => 30,
@@ -48,14 +49,28 @@ class Colors {
 			'white'   => 47
 		)
 	);
+	/** @var bool|null */
 	static protected $_enabled = null;
 
+	/** @var array<string, array<string, string>> */
 	static protected $_string_cache = array();
 
+	/**
+	 * Enable colorized output.
+	 *
+	 * @param bool $force Force enable.
+	 * @return void
+	 */
 	static public function enable($force = true) {
 		self::$_enabled = $force === true ? true : null;
 	}
 
+	/**
+	 * Disable colorized output.
+	 *
+	 * @param bool $force Force disable.
+	 * @return void
+	 */
 	static public function disable($force = true) {
 		self::$_enabled = $force === true ? false : null;
 	}
@@ -64,6 +79,9 @@ static public function disable($force = true) {
 	 * Check if we should colorize output based on local flags and shell type.
 	 *
 	 * Only check the shell type if `Colors::$_enabled` is null and `$colored` is null.
+	 *
+	 * @param bool|null $colored Force enable or disable the colorized output.
+	 * @return bool
 	 */
 	static public function shouldColorize($colored = null) {
 		return self::$_enabled === true ||
@@ -75,8 +93,8 @@ static public function shouldColorize($colored = null) {
 	/**
 	 * Set the color.
 	 *
-	 * @param string  $color  The name of the color or style to set.
-     * @return string
+	 * @param string|array<string, string|int>  $color  The name of the color or style to set, or an array of options.
+	 * @return string
 	 */
 	static public function color($color) {
 		if (!is_array($color)) {
@@ -171,6 +189,7 @@ static public function decolorize( $string, $keep = 0 ) {
 	 * @param string $passed The original string before colorization.
 	 * @param string $colorized The string after running through self::colorize.
 	 * @param string $deprecated Optional. Not used. Default null.
+	 * @return void
 	 */
 	static public function cacheString( $passed, $colorized, $deprecated = null ) {
 		self::$_string_cache[md5($passed)] = array(
@@ -225,7 +244,7 @@ static public function pad( $string, $length, $pre_colorized = false, $encoding
 	/**
 	 * Get the color mapping array.
 	 *
-	 * @return array Array of color tokens mapped to colors and styles.
+	 * @return array<string, array<string, string|int>> Array of color tokens mapped to colors and styles.
 	 */
 	static public function getColors() {
 		return array(
@@ -268,14 +287,16 @@ static public function getColors() {
 	/**
 	 * Get the cached string values.
 	 *
-	 * @return array The cached string values.
+	 * @return array<string, array<string, string>> The cached string values.
 	 */
 	static public function getStringCache() {
 		return self::$_string_cache;
 	}
 
 	/**
 	 * Clear the string cache.
+	 *
+	 * @return void
 	 */
 	static public function clearStringCache() {
 		self::$_string_cache = array();
@@ -305,7 +326,7 @@ static public function getResetCode() {
 	 * @param string      $string   The string to wrap (with ANSI codes).
 	 * @param int         $width    The maximum display width per line.
 	 * @param string|bool $encoding Optional. The encoding of the string. Default false.
-	 * @return array Array of wrapped string segments.
+	 * @return array<int, string> Array of wrapped string segments.
 	 */
 	static public function wrapPreColorized( $string, $width, $encoding = false ) {
 		$wrapped = array();

lib/cli/Memoize.php

@@ -13,8 +13,15 @@
 namespace cli;
 
 abstract class Memoize {
+	/** @var array<string, mixed> */
 	protected $_memoCache = array();
 
+	/**
+	 * Magic getter to retrieve memoized properties.
+	 *
+	 * @param string $name Property name.
+	 * @return mixed
+	 */
 	public function __get($name) {
 		if (isset($this->_memoCache[$name])) {
 			return $this->_memoCache[$name];
@@ -34,6 +41,12 @@ public function __get($name) {
 		return $this->_memoCache[$name];
 	}
 
+	/**
+	 * Unmemoize a property or all properties.
+	 *
+	 * @param string|bool $name Property name to unmemoize, or true to unmemoize all.
+	 * @return void
+	 */
 	protected function _unmemo($name) {
 		if ($name === true) {
 			$this->_memoCache = array();