feat(task): allow to define a default task

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 * Add support for PHP 8.4
 * Force fetching the last version when guard min is used to display more information for user
+* Add the ability to set a default task when calling `castor` without any arguments
 
 ### Fixes
 

bin/generate-tests.php

@@ -164,6 +164,7 @@
 add_test(['list'], 'LayoutWithOldFolder', '{{ base }}/tests/fixtures/valid/layout-with-old-folder');
 add_test([], 'ImportSamePackageWithDefaultVersion', '{{ base }}/tests/fixtures/valid/import-same-package-with-default-version', needRemote: true, needResetVendor: true);
 add_test(['fs-watch'], 'WatchWithForcedTimeout', '{{ base }}/tests/fixtures/valid/watch-with-forced-timeout');
+add_test([], 'DefaultTask', '{{ base }}/tests/fixtures/valid/default-task');
 
 echo "\nDone.\n";
 

doc/getting-started/basic-usage.md

@@ -103,3 +103,24 @@ function a_very_long_function_name_that_is_very_painful_to_write(): void
 
 > [!TIP]
 > Related example: [foo.php](https://github.com/jolicode/castor/blob/main/examples/foo.php)
+
+## Setting a default task
+
+The `Castor\Attribute\AsTask` attribute allows you to set a default task when
+calling `castor` without any arguments:
+
+```php
+use Castor\Attribute\AsTask;
+
+use function Castor\io;
+
+#[AsTask(description: 'Displays some help and available urls for the current project', default: true)]
+function about(): void
+{
+    io()->title('About this project');
+
+    io()->comment('Run <comment>castor</comment> to display all available commands.');
+    io()->comment('Run <comment>castor about</comment> to display this project help.');
+    io()->comment('Run <comment>castor help [command]</comment> to display Castor help.');
+}
+```

src/Attribute/AsTask.php

@@ -17,6 +17,7 @@ public function __construct(
         public array $onSignals = [],
         public string|bool $enabled = true,
         public bool $ignoreValidationErrors = false,
+        public bool $default = false,
     ) {
     }
 }

src/Function/FunctionLoader.php

@@ -10,6 +10,7 @@
 use Castor\Descriptor\ListenerDescriptor;
 use Castor\Descriptor\SymfonyTaskDescriptor;
 use Castor\Descriptor\TaskDescriptor;
+use Castor\Exception\FunctionConfigurationException;
 use Castor\Factory\TaskCommandFactory;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
@@ -64,8 +65,25 @@ public function loadTasks(
         array $taskDescriptors,
         array $symfonyTaskDescriptors,
     ): void {
+        $previousDefault = null;
+
         foreach ($taskDescriptors as $descriptor) {
             $this->application->add($this->taskCommandFactory->createTask($descriptor));
+
+            if ($descriptor->taskAttribute->default) {
+                $taskName = $descriptor->taskAttribute->name;
+
+                if ($descriptor->taskAttribute->namespace) {
+                    $taskName = $descriptor->taskAttribute->namespace . ':' . $taskName;
+                }
+
+                if ($previousDefault) {
+                    throw new FunctionConfigurationException(\sprintf('The task is marked as default, but task "%s()" was already marked as default.', $previousDefault), $descriptor->function);
+                }
+
+                $previousDefault = $taskName;
+                $this->application->setDefaultCommand($taskName);
+            }
         }
         foreach ($symfonyTaskDescriptors as $descriptor) {
             $this->application->add(SymfonyTaskCommand::createFromDescriptor($descriptor));

tests/Generated/DefaultTaskConflictTest.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Castor\Tests\Generated;
+
+use Castor\Tests\TaskTestCase;
+use Symfony\Component\Process\Exception\ProcessFailedException;
+
+class DefaultTaskConflictTest extends TaskTestCase
+{
+    // no task
+    public function test(): void
+    {
+        $process = $this->runTask([], '{{ base }}/tests/fixtures/broken/default-task-conflict', needRemote: true);
+
+        if (1 !== $process->getExitCode()) {
+            throw new ProcessFailedException($process);
+        }
+
+        $this->assertStringEqualsFile(__FILE__ . '.output.txt', $process->getOutput());
+        $this->assertStringEqualsFile(__FILE__ . '.err.txt', $process->getErrorOutput());
+    }
+}

tests/Generated/DefaultTaskConflictTest.php.err.txt

@@ -0,0 +1,7 @@
+In FunctionLoader.php line XXXX:
+
+  Function "about2()" is not properly configured:
+  The task is marked as default, but task "about()" was already marked as default.
+  Defined in "castor.php" line 11.
+
+

tests/Generated/DefaultTaskTest.php

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

tests/Generated/DefaultTaskTest.php.output.txt

@@ -0,0 +1 @@
+about

tests/fixtures/broken/default-task-conflict/castor.php

@@ -0,0 +1,13 @@
+<?php
+
+use Castor\Attribute\AsTask;
+
+#[AsTask(default: true)]
+function about(): void
+{
+}
+
+#[AsTask(default: true)]
+function about2(): void
+{
+}

tests/fixtures/valid/default-task/castor.php

@@ -0,0 +1,11 @@
+<?php
+
+use Castor\Attribute\AsTask;
+
+use function Castor\io;
+
+#[AsTask(default: true)]
+function about(): void
+{
+    io()->writeln('about');
+}