Feature/fix plugin interface

.github/workflows/diagnostics.yml

@@ -17,12 +17,6 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - php: '7.4'
-            phpcq_install: 'update'
-            phpcq_flags: ''
-          - php: '8.0'
-            phpcq_install: 'update'
-            phpcq_flags: ''
           - php: '8.1'
             phpcq_install: 'update'
             phpcq_flags: ''

composer.json

@@ -17,7 +17,7 @@
     }
   ],
   "require": {
-    "php": "^7.3 || ^8.0",
+    "php": "^8.1",
     "ext-dom": "*"
   },
   "require-dev": {
@@ -35,7 +35,8 @@
   },
   "extra": {
     "branch-alias": {
-      "dev-master": "1.x-dev"
+      "dev-master": "1.x-dev",
+      "dev-feature/fix-plugin-interface": "1.1.x-dev"
     }
   }
 }

src/Version10/FixPluginInterface.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpcq\PluginApi\Version10;
+
+use Phpcq\PluginApi\Version10\Configuration\PluginConfigurationInterface;
+use Phpcq\PluginApi\Version10\Task\TaskInterface;
+
+/**
+ * A plugin which is able to fix issues automatically.
+ *
+ * The fix tasks are executed sequentially in "phpcq fix" before the diagnostics are run.
+ */
+interface FixPluginInterface extends ConfigurationPluginInterface
+{
+    /**
+     * The stage in which the fix tasks are executed. The project configuration may override it.
+     */
+    public function getFixStage(): FixStage;
+
+    /**
+     * Process plugin configuration and create fix tasks.
+     *
+     * @param PluginConfigurationInterface $config      The plugin configuration.
+     * @param EnvironmentInterface         $environment The build configuration.
+     *
+     * @return TaskInterface[]
+     *
+     * @psalm-return \Generator<int, TaskInterface>
+     */
+    public function createFixTasks(
+        PluginConfigurationInterface $config,
+        EnvironmentInterface $environment
+    ): iterable;
+}

src/Version10/FixStage.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpcq\PluginApi\Version10;
+
+/**
+ * The stage in which the fix tasks of a plugin are executed.
+ */
+enum FixStage: string
+{
+    /** Normalization of project metadata, e.g. composer.json. */
+    case Normalize = 'normalize';
+
+    /** Structural changes of the code, e.g. rector. */
+    case Refactor = 'refactor';
+
+    /** Pure formatting, always executed last, e.g. phpcbf. */
+    case Format = 'format';
+
+    /**
+     * The execution order. Lower values are executed first.
+     */
+    public function order(): int
+    {
+        return match ($this) {
+            self::Normalize => 0,
+            self::Refactor  => 1,
+            self::Format    => 2,
+        };
+    }
+}

tests/Version10/FixStageTest.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpcq\PluginApi\Test\Version10;
+
+use Phpcq\PluginApi\Version10\FixStage;
+use PHPUnit\Framework\TestCase;
+
+use function array_map;
+use function usort;
+
+/** @covers \Phpcq\PluginApi\Version10\FixStage */
+final class FixStageTest extends TestCase
+{
+    public function testBackingValues(): void
+    {
+        self::assertSame(FixStage::Normalize, FixStage::from('normalize'));
+        self::assertSame(FixStage::Refactor, FixStage::from('refactor'));
+        self::assertSame(FixStage::Format, FixStage::from('format'));
+        self::assertNull(FixStage::tryFrom('unknown'));
+    }
+
+    public function testOrderSortsNormalizeRefactorFormat(): void
+    {
+        $stages = [FixStage::Format, FixStage::Normalize, FixStage::Refactor];
+        usort($stages, static fn (FixStage $first, FixStage $second): int => $first->order() <=> $second->order());
+
+        self::assertSame(
+            ['normalize', 'refactor', 'format'],
+            array_map(static fn (FixStage $stage): string => $stage->value, $stages)
+        );
+    }
+}