refactor: comments

bin/pest

@@ -1,12 +1,10 @@
 #!/usr/bin/env php
 <?php declare(strict_types=1);
 
-use NunoMaduro\Collision\Provider;
 use Pest\Actions\ValidatesEnvironment;
 use Pest\Support\Container;
-use Pest\Console\Kernel;
+use Pest\Kernel;
 use Pest\TestSuite;
-use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\ArgvInput;
 use Symfony\Component\Console\Output\ConsoleOutput;
 use Symfony\Component\Console\Output\OutputInterface;

src/Actions/InteractsWithPlugins.php

@@ -1,50 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Pest\Actions;
-
-use Pest\Contracts\Plugins\AddsOutput;
-use Pest\Contracts\Plugins\HandlesArguments;
-use Pest\Plugin\Loader;
-
-/**
- * @internal
- */
-final class InteractsWithPlugins
-{
-    /**
-     * Transform the input arguments by passing it to the relevant plugins.
-     *
-     * @param array<int, string> $argv
-     *
-     * @return array<int, string>
-     */
-    public static function handleArguments(array $argv): array
-    {
-        $plugins = Loader::getPlugins(HandlesArguments::class);
-
-        /** @var HandlesArguments $plugin */
-        foreach ($plugins as $plugin) {
-            $argv = $plugin->handleArguments($argv);
-        }
-
-        return $argv;
-    }
-
-    /**
-     * Provides an opportunity for any plugins that want
-     * to provide additional output after test execution.
-     */
-    public static function addOutput(int $result): int
-    {
-        $plugins = Loader::getPlugins(AddsOutput::class);
-
-        /** @var AddsOutput $plugin */
-        foreach ($plugins as $plugin) {
-            $result = $plugin->addOutput($result);
-        }
-
-        return $result;
-    }
-}

src/Concerns/Expectable.php

@@ -14,13 +14,13 @@ trait Expectable
     /**
      * @template TValue
      *
-     * Creates a new expectation.
+     * Creates a new Expectation.
      *
      * @param TValue $value
      *
      * @return Expectation<TValue>
      */
-    public function expect($value): Expectation
+    public function expect(mixed $value): Expectation
     {
         return new Expectation($value);
     }

src/Concerns/Extendable.php

@@ -13,12 +13,14 @@ use Closure;
 trait Extendable
 {
     /**
+     * The list of extends.
+     *
      * @var array<string, Closure>
      */
     private static array $extends = [];
 
     /**
-     * Register a custom extend.
+     * Register a new extend.
      */
     public static function extend(string $name, Closure $extend): void
     {
@@ -26,7 +28,7 @@ trait Extendable
     }
 
     /**
-     * Checks if extend is registered.
+     * Checks if given extend name is registered.
      */
     public static function hasExtend(string $name): bool
     {
@@ -37,10 +39,8 @@ trait Extendable
      * Dynamically handle calls to the class.
      *
      * @param array<int, mixed> $parameters
-     *
-     * @return mixed
      */
-    public function __call(string $method, array $parameters)
+    public function __call(string $method, array $parameters): mixed
     {
         if (!static::hasExtend($method)) {
             throw new BadMethodCallException("$method is not a callable method name.");

src/Concerns/Logging/WritesToConsole.php

@@ -9,21 +9,33 @@ namespace Pest\Concerns\Logging;
  */
 trait WritesToConsole
 {
+    /**
+     * Writes the given success message to the console.
+     */
     private function writeSuccess(string $message): void
     {
         $this->writePestTestOutput($message, 'fg-green, bold', '✓');
     }
 
+    /**
+     * Writes the given error message to the console.
+     */
     private function writeError(string $message): void
     {
         $this->writePestTestOutput($message, 'fg-red, bold', '⨯');
     }
 
+    /**
+     * Writes the given warning message to the console.
+     */
     private function writeWarning(string $message): void
     {
         $this->writePestTestOutput($message, 'fg-yellow, bold', '-');
     }
 
+    /**
+     * Writes the give message to the console.
+     */
     private function writePestTestOutput(string $message, string $color, string $symbol): void
     {
         $this->writeWithColor($color, "$symbol ", false);

src/Concerns/RetrievesValues.php

@@ -19,7 +19,7 @@ trait RetrievesValues
      *
      * @return TRetrievableValue|null
      */
-    private function retrieve(string $key, $value, $default = null)
+    private function retrieve(string $key, mixed $value, mixed $default = null): mixed
     {
         if (is_array($value)) {
             return $value[$key] ?? $default;

src/Console/Help.php

@@ -11,7 +11,11 @@ use Symfony\Component\Console\Output\OutputInterface;
  */
 final class Help
 {
-    /** @var array<int, string> */
+    /**
+     * The Command messages.
+     *
+     * @var array<int, string>
+     */
     private const HELP_MESSAGES = [
         '<comment>Pest Options:</comment>',
         '  <info>--init</info>                      Initialise a standard Pest configuration',
@@ -20,11 +24,17 @@ final class Help
         '  <info>--group=<fg=cyan><name></></info>              Only runs tests from the specified group(s)',
     ];
 
+    /**
+     * Creates a new Console Command instance.
+     */
     public function __construct(private OutputInterface $output)
     {
         // ..
     }
 
+    /**
+     * Executes the Console Command.
+     */
     public function __invoke(): void
     {
         foreach (self::HELP_MESSAGES as $message) {

src/Console/Thanks.php

@@ -14,7 +14,11 @@ use Symfony\Component\Console\Question\ConfirmationQuestion;
  */
 final class Thanks
 {
-    /** @var array<int, string> */
+    /**
+     * The Command messages.
+     *
+     * @var array<int, string>
+     */
     private const FUNDING_MESSAGES = [
         '',
         '  - Star or contribute to Pest:',
@@ -25,13 +29,16 @@ final class Thanks
         '    <options=bold>https://github.com/sponsors/nunomaduro</>',
     ];
 
+    /**
+     * Creates a new Console Command instance.
+     */
     public function __construct(private OutputInterface $output)
     {
         // ..
     }
 
     /**
-     * Asks the user to support Pest.
+     * Executes the Console Command.
      */
     public function __invoke(): void
     {

src/Contracts/HasPrintableTestCaseName.php

@@ -4,18 +4,12 @@ declare(strict_types=1);
 
 namespace Pest\Contracts;
 
-if (interface_exists(\NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName::class)) {
+use NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName as BaseHasPrintableTestCaseName;
+
 /**
  * @internal
  */
-    interface HasPrintableTestCaseName extends \NunoMaduro\Collision\Contracts\Adapters\Phpunit\HasPrintableTestCaseName
+interface HasPrintableTestCaseName extends BaseHasPrintableTestCaseName
 {
-    }
-} else {
-    /**
-     * @internal
-     */
-    interface HasPrintableTestCaseName
-    {
-    }
+    // ..
 }

src/Contracts/Plugins/AddsOutput.php

@@ -10,7 +10,7 @@ namespace Pest\Contracts\Plugins;
 interface AddsOutput
 {
     /**
-     * Allows to add custom output after the test suite was executed.
+     * Adds output after the Test Suite execution.
      */
-    public function addOutput(int $testReturnCode): int;
+    public function addOutput(int $exitCode): int;
 }

src/Contracts/Plugins/HandlesArguments.php

@@ -10,11 +10,11 @@ namespace Pest\Contracts\Plugins;
 interface HandlesArguments
 {
     /**
-     * Allows to handle custom command line arguments.
+     * Adds arguments before of the Test Suite execution.
      *
-     * @param array<int, string> $arguments
+     * @param array<int, string> $argv
      *
-     * @return array<int, string> the updated list of arguments
+     * @return array<int, string>
      */
-    public function handleArguments(array $arguments): array;
+    public function handleArguments(array $argv): array;
 }

src/Emitters/DispatchingEmitter.php

@@ -19,6 +19,9 @@ use SebastianBergmann\GlobalState\Snapshot;
  */
 final class DispatchingEmitter implements Emitter
 {
+    /**
+     * Creates a new Emitter instance.
+     */
     public function __construct(private Emitter $baseEmitter)
     {
         // ..

src/Exceptions/AfterAllAlreadyExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class AfterAllAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of after all already exist exception.
+     * Creates a new Exception instance.
      */
     public function __construct(string $filename)
     {

src/Exceptions/AfterEachAlreadyExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class AfterEachAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of after each already exist exception.
+     * Creates a new Exception instance.
      */
     public function __construct(string $filename)
     {

src/Exceptions/AttributeNotSupportedYet.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class AttributeNotSupportedYet extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of attribute not supported yet.
+     * Creates a new Exception instance.
      */
     public function __construct(string $attribute, string $value)
     {

src/Exceptions/BeforeEachAlreadyExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class BeforeEachAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of before each already exist exception.
+     * Creates a new Exception instance.
      */
     public function __construct(string $filename)
     {

src/Exceptions/DatasetAlreadyExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class DatasetAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of dataset already exist.
+     * Creates a new Exception instance.
      */
     public function __construct(string $name)
     {

src/Exceptions/DatasetDoesNotExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class DatasetDoesNotExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of dataset does not exist.
+     * Creates a new Exception instance.
      */
     public function __construct(string $name)
     {

src/Exceptions/DatasetMissing.php

@@ -10,24 +10,22 @@ use NunoMaduro\Collision\Contracts\RenderlessTrace;
 use Symfony\Component\Console\Exception\ExceptionInterface;
 
 /**
- * Creates a new instance of dataset is not present for test that has arguments.
- *
  * @internal
  */
 final class DatasetMissing extends BadFunctionCallException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Create new exception instance.
+     * Creates a new Exception instance.
      *
-     * @param array<string, string> $args A map of argument names to their typee
+     * @param array<string, string> $arguments
      */
-    public function __construct(string $file, string $name, array $args)
+    public function __construct(string $file, string $name, array $arguments)
     {
         parent::__construct(sprintf(
             "A test with the description '%s' has %d argument(s) ([%s]) and no dataset(s) provided in %s",
             $name,
-            count($args),
-            implode(', ', array_map(static fn (string $arg, string $type): string => sprintf('%s $%s', $type, $arg), array_keys($args), $args)),
+            count($arguments),
+            implode(', ', array_map(static fn (string $arg, string $type): string => sprintf('%s $%s', $type, $arg), array_keys($arguments), $arguments)),
             $file,
         ));
     }

src/Exceptions/FileOrFolderNotFound.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class FileOrFolderNotFound extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of file not found.
+     * Creates a new Exception instance.
      */
     public function __construct(string $filename)
     {

src/Exceptions/InvalidConsoleArgument.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class InvalidConsoleArgument extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of should not happen.
+     * Creates a new Exception instance.
      */
     public function __construct(string $message)
     {

src/Exceptions/InvalidPestCommand.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class InvalidPestCommand extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of invalid pest command exception.
+     * Creates a new Exception instance.
      */
     public function __construct()
     {

src/Exceptions/MissingDependency.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class MissingDependency extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of missing dependency.
+     * Creates a new Exception instance.
      */
     public function __construct(string $feature, string $dependency)
     {

src/Exceptions/ShouldNotHappen.php

@@ -13,7 +13,7 @@ use RuntimeException;
 final class ShouldNotHappen extends RuntimeException
 {
     /**
-     * Creates a new instance of should not happen.
+     * Creates a new Exception instance.
      */
     public function __construct(Exception $exception)
     {

src/Exceptions/TestAlreadyExist.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class TestAlreadyExist extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of test already exist.
+     * Creates a new Exception instance.
      */
     public function __construct(string $fileName, string $description)
     {

src/Exceptions/TestCaseAlreadyInUse.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class TestCaseAlreadyInUse extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of test case already in use.
+     * Creates a new Exception instance.
      */
     public function __construct(string $inUse, string $newOne, string $folder)
     {

src/Exceptions/TestCaseClassOrTraitNotFound.php

@@ -15,7 +15,7 @@ use Symfony\Component\Console\Exception\ExceptionInterface;
 final class TestCaseClassOrTraitNotFound extends InvalidArgumentException implements ExceptionInterface, RenderlessEditor, RenderlessTrace
 {
     /**
-     * Creates a new instance of after each already exist exception.
+     * Creates a new Exception instance.
      */
     public function __construct(string $testCaseClass)
     {

src/Factories/TestCaseFactory.php

@@ -24,15 +24,11 @@ final class TestCaseFactory
 {
     /**
      * Marks this test case as only.
-     *
-     * @readonly
      */
     public bool $only = false;
 
     /**
      * Holds the test closure.
-     *
-     * @readonly
      */
     public Closure $test;
 
@@ -53,7 +49,7 @@ final class TestCaseFactory
     /**
      * An array of FQN of the class traits.
      *
-     * @var array <int, string>
+     * @var array <int, class-string>
      */
     public array $traits = [
         Concerns\Testable::class,
@@ -61,12 +57,12 @@ final class TestCaseFactory
     ];
 
     /**
-     * Holds the higher order messages for the factory that are proxyble.
+     * Holds the higher order messages for the factory that are proxyable.
      */
     public HigherOrderMessageCollection $factoryProxies;
 
     /**
-     * Holds the higher order messages that are proxyble.
+     * Holds the higher order messages that are proxyable.
      */
     public HigherOrderMessageCollection $proxies;
 
@@ -80,14 +76,10 @@ final class TestCaseFactory
      */
     public function __construct(
         public string $filename,
-        public ?string $description = null,
+        public ?string $description,
         Closure $closure = null)
     {
-        $this->test = $closure ?? function (): void {
-            if (Assert::getCount() === 0) {
-                self::markTestIncomplete(); // @phpstan-ignore-line
-            }
-        };
+        $this->test = $closure ?? fn () => Assert::getCount() > 0 ?: self::markTestIncomplete();
 
         $this->factoryProxies = new HigherOrderMessageCollection();
         $this->proxies        = new HigherOrderMessageCollection();

src/Kernel.php

@@ -2,10 +2,8 @@
 
 declare(strict_types=1);
 
-namespace Pest\Console;
+namespace Pest;
 
-use Pest\Actions\InteractsWithPlugins;
-use Pest\Bootstrappers;
 use PHPUnit\TextUI\Application;
 
 /**
@@ -53,13 +51,13 @@ final class Kernel
      */
     public function handle(array $argv): int
     {
-        $argv = InteractsWithPlugins::handleArguments($argv);
+        $argv = (new Plugins\Actions\HandleArguments())->__invoke($argv);
 
         $result = $this->application->run(
             $argv, false,
         );
 
-        return InteractsWithPlugins::addOutput($result);
+        return (new Plugins\Actions\AddsOutput())->__invoke($result);
     }
 
     /**

src/Plugins/Actions/AddsOutput.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Pest\Plugins\Actions;
+
+use Pest\Contracts\Plugins;
+use Pest\Plugin\Loader;
+
+/**
+ * @internal
+ */
+final class AddsOutput
+{
+    /**
+     * Executes the Plugin action.
+     *
+     * Provides an opportunity for any plugins that want
+     * to provide additional output after test execution.
+     */
+    public function __invoke(int $exitCode): int
+    {
+        $plugins = Loader::getPlugins(Plugins\AddsOutput::class);
+
+        /** @var Plugins\AddsOutpu $plugin */
+        foreach ($plugins as $plugin) {
+            $exitCode = $plugin->addOutput($exitCode);
+        }
+
+        return $exitCode;
+    }
+}

src/Plugins/Actions/HandleArguments.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Pest\Plugins\Actions;
+
+use Pest\Contracts\Plugins;
+use Pest\Plugin\Loader;
+
+/**
+ * @internal
+ */
+final class HandleArguments
+{
+    /**
+     * Executes the Plugin action.
+     *
+     * Transform the input arguments by passing it to the relevant plugins.
+     *
+     * @param array<int, string> $argv
+     *
+     * @return array<int, string>
+     */
+    public function __invoke(array $argv): array
+    {
+        $plugins = Loader::getPlugins(Plugins\HandlesArguments::class);
+
+        /** @var Plugins\HandlesArguments $plugin */
+        foreach ($plugins as $plugin) {
+            $argv = $plugin->handleArguments($argv);
+        }
+
+        return $argv;
+    }
+}

src/Support/Arr.php

@@ -5,16 +5,12 @@ declare(strict_types=1);
 namespace Pest\Support;
 
 /**
- * Credits: most of this class methods and implementations
- * belongs to the Arr helper of laravel/framework project
- * (https://github.com/laravel/framework).
- *
  * @internal
  */
 final class Arr
 {
     /**
-     * @param array<mixed> $array
+     * Checks if the given array has the given key.
      */
     public static function has(array $array, string|int $key): bool
     {
@@ -36,12 +32,9 @@ final class Arr
     }
 
     /**
-     * @param array<mixed> $array
-     * @param null         $default
-     *
-     * @return array|mixed|null
+     * Gets the given key value.
      */
-    public static function get(array $array, string|int $key, $default = null)
+    public static function get(array $array, string|int $key, mixed $default = null): mixed
     {
         $key = (string) $key;