Add check() function to ensure requirements are met

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Features
 
 * Better rendering of run errors
+* Add `check()` function to ensure requirements are met
+* Add `ProblemException` to handle problems in a more structured way
 
 ### Internal
 

doc/_nav.md

@@ -1,6 +1,6 @@
 - [Home](index.md)
+- [Installation](installation.md)
 - [Getting started](getting-started/index.md)
-    - [Installation and Autocomplete](getting-started/installation.md)
     - [Basic Usage](getting-started/basic-usage.md)
     - [Executing Processes with `run()`](getting-started/run.md)
     - [Task Arguments](getting-started/arguments.md)

doc/going-further/helpers/assertion.md

@@ -0,0 +1,46 @@
+# Assertion
+
+## The `check()` function
+
+Castor provides a `check()` function to ensure some requirements are met:
+
+```php
+use Castor\Attribute\AsTask;
+use Symfony\Component\Process\ExecutableFinder;
+
+use function Castor\check;
+
+#[AsTask()]
+function git()
+{
+    check(
+        'Check if Git is installed',
+        'Git is not installed. Please install it before.',
+        fn () => (new ExecutableFinder())->find('git'),
+    );
+}
+```
+
+## The `ProblemException` exception
+
+If you must stop a task execution because of a problem, you can throw a
+`ProblemException` exception:
+
+```php
+use Castor\Attribute\AsTask;
+use Castor\Exception\ProblemException;
+
+use function Castor\capture;
+
+#[AsTask()]
+function git()
+{
+    if (capture('git status --porcelain')) {
+        throw new ProblemException('There are uncommitted changes.');
+    }
+}
+```
+
+It will stop the execution of the task and display the message in the console.
+And it will also return a non-zero exit code (default to 1) to indicate that the
+task failed.

doc/index.md

@@ -54,7 +54,7 @@ function hello(): void
 
 Will expose a `greetings:hello` task that you can run with `castor greetings:hello`:
 
-```bash
+```shell
 $ castor greetings:hello
 Hello from castor
 ```
@@ -86,6 +86,7 @@ function destroy(bool $force = false)
 
 Discover more by reading the docs:
 
+* [Installation](installation.md)
 * [Getting started with Castor](getting-started/index.md)
 * [Going further with Castor](going-further/index.md)
 * [Castor reference](reference.md)

doc/getting-started/installation.md → doc/installation.md

@@ -198,7 +198,7 @@ ln -s $PWD/bin/castor $HOME/.local/bin/castor
 
 #### Using setup-castor action
 
-Castor provide a [Github Action to install Castor in your workflow](https://github.com/marketplace/actions/setup-castor). 
+Castor provide a [Github Action to install Castor in your workflow](https://github.com/marketplace/actions/setup-castor).
 Here is an example:
 
 ```yaml

examples/assertion.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace assertion;
+
+use Castor\Attribute\AsTask;
+use Castor\Exception\ProblemException;
+
+use function Castor\check;
+
+#[AsTask(description: 'Ensure we are in the future')]
+function ensure_we_are_in_the_future(): void
+{
+    check(
+        'Check if we are in the future',
+        'We are not in the future 😱',
+        fn () => (!usleep(500_000) && new \DateTime() > new \DateTime('2015-10-21'))
+    );
+}
+
+#[AsTask(description: 'Throws a Problem exception')]
+function throw_an_exception(): never
+{
+    throw new ProblemException('Houston, we have a problem');
+}

phpstan-baseline.neon

@@ -5,6 +5,16 @@ parameters:
 			count: 1
 			path: examples/args.php
 
+		-
+			message: "#^Negated boolean expression is always true\\.$#"
+			count: 1
+			path: examples/assertion.php
+
+		-
+			message: "#^Result of function usleep \\(void\\) is used\\.$#"
+			count: 1
+			path: examples/assertion.php
+
 		-
 			message: "#^Class RepackedApplication not found\\.$#"
 			count: 1

src/Console/Application.php

@@ -78,7 +78,7 @@ public function renderThrowable(\Throwable $e, OutputInterface $output): void
                 $process = $e->getProcess();
                 $runnable = $this->processRunner->buildRunnableCommand($process);
 
-                $this->io->writeln(sprintf('<comment>%s</comment>', OutputFormatter::escape(sprintf('In %s line %s:', basename($e->getFile()) ?: 'n/a', $e->getLine() ?: 'n/a'))));
+                $this->io->writeln(\sprintf('<comment>%s</comment>', OutputFormatter::escape(\sprintf('In %s line %s:', basename($e->getFile()) ?: 'n/a', $e->getLine() ?: 'n/a'))));
                 $this->io->error('The following process did not finish successfully (exit code ' . $process->getExitCode() . '):');
                 $this->io->writeln("<fg=yellow>{$runnable}</>");
                 $this->io->newLine();

src/functions.php

@@ -7,6 +7,7 @@
 use Castor\Console\Application;
 use Castor\Exception\ExecutableNotFoundException;
 use Castor\Exception\MinimumVersionRequirementNotMetException;
+use Castor\Exception\ProblemException;
 use Castor\Exception\WaitFor\ExitedBeforeTimeoutException;
 use Castor\Exception\WaitFor\TimeoutReachedException;
 use Castor\Helper\HasherHelper;
@@ -160,6 +161,22 @@ function exit_code(
     ;
 }
 
+/**
+ * @param callable():bool $check
+ */
+function check(string $title, string $failureMessage, callable $check): void
+{
+    io()->write($title);
+
+    if (!$check()) {
+        io()->writeln(' ❌');
+
+        throw new ProblemException($failureMessage);
+    }
+
+    io()->writeln(' ✅');
+}
+
 /**
  * @deprecated Since castor/castor 0.8. Use Castor\exit_code() instead
  */

tests/Generated/AssertionEnsureWeAreInTheFutureTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Castor\Tests\Generated;
+
+use Castor\Tests\TaskTestCase;
+use Symfony\Component\Process\Exception\ProcessFailedException;
+
+class AssertionEnsureWeAreInTheFutureTest extends TaskTestCase
+{
+    // assertion:ensure-we-are-in-the-future
+    public function test(): void
+    {
+        $process = $this->runTask(['assertion:ensure-we-are-in-the-future']);
+
+        if (0 !== $process->getExitCode()) {
+            throw new ProcessFailedException($process);
+        }
+
+        $this->assertStringEqualsFile(__FILE__ . '.output.txt', $process->getOutput());
+        $this->assertSame('', $process->getErrorOutput());
+    }
+}

tests/Generated/AssertionEnsureWeAreInTheFutureTest.php.output.txt

@@ -0,0 +1 @@
+Check if we are in the future ✅

tests/Generated/AssertionThrowAnExceptionTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Castor\Tests\Generated;
+
+use Castor\Tests\TaskTestCase;
+use Symfony\Component\Process\Exception\ProcessFailedException;
+
+class AssertionThrowAnExceptionTest extends TaskTestCase
+{
+    // assertion:throw-an-exception
+    public function test(): void
+    {
+        $process = $this->runTask(['assertion:throw-an-exception']);
+
+        if (1 !== $process->getExitCode()) {
+            throw new ProcessFailedException($process);
+        }
+
+        $this->assertStringEqualsFile(__FILE__ . '.output.txt', $process->getOutput());
+        $this->assertSame('', $process->getErrorOutput());
+    }
+}

tests/Generated/AssertionThrowAnExceptionTest.php.output.txt

@@ -0,0 +1,2 @@
+ [ERROR] Houston, we have a problem
+

tests/Generated/FilesystemFindTest.php.output.txt

@@ -1 +1 @@
-Number of PHP files: 34
+Number of PHP files: 35

tests/Generated/ListTest.php.output.txt

@@ -8,6 +8,8 @@ args:another-args                                                 Dumps all argu
 args:args                                                         Dumps all arguments and options, with custom configuration
 args:autocomplete-argument                                        Provides autocomplete for an argument
 args:passthru                                                     Dumps all arguments and options, without configuration nor validation
+assertion:ensure-we-are-in-the-future                             Ensure we are in the future
+assertion:throw-an-exception                                      Throws a Problem exception
 bar:bar                                                           Prints bar, but also executes foo
 cache:complex                                                     Cache with usage of CacheItemInterface
 cache:simple                                                      Cache a simple call

tests/Monolog/Processor/ProcessProcessorTest.php

@@ -28,7 +28,8 @@ public function test(): void
         $mock = $this->getMockBuilder(ProcessRunner::class)
             ->onlyMethods(['buildRunnableCommand'])
             ->disableOriginalConstructor()
-            ->getMock();
+            ->getMock()
+        ;
 
         $processor = new ProcessProcessor($mock);
 

tools/release/castor.php

@@ -7,6 +7,7 @@
 use Symfony\Component\Process\ExecutableFinder;
 
 use function Castor\capture;
+use function Castor\check;
 use function Castor\context;
 use function Castor\finder;
 use function Castor\fs;
@@ -137,19 +138,6 @@ function release(): int
     return 0;
 }
 
-function check(string $title, string $failureMessage, callable $check): void
-{
-    io()->write($title);
-
-    if (!$check()) {
-        io()->writeln(' ❌');
-
-        throw new ProblemException($failureMessage);
-    }
-
-    io()->writeln(' ✅');
-}
-
 function checkCi(array $run): void
 {
     io()->comment("{$run['name']}'s run id <comment>{$run['databaseId']}</comment>");