Add action and condition shorthands to simplify the configuration

src/Hook/Branch/Action/BlockFixupAndSquashCommits.php

@@ -27,17 +27,17 @@
  * This action blocks pushes that contain fixup! or squash! commits.
  * Just as a security layer, so you are not pushing stuff you wanted to autosquash.
  *
- * Configure like this:
- *
+ * Example configuration:
+ * <code>
  * {
- *    "action": "\\CaptainHook\\App\\Hook\\Branch\\Action\\BlockFixupAndSquashCommits",
- *    "options": {
- *      "blockSquashCommits": true,
- *      "blockFixupCommits": true,
- *      "protectedBranches": ["main", "master", "integration"]
- *    },
- *    "conditions": []
- *  }
+ *   "action": "CaptainHook.Branch.PreventPushOfFixupAndSquashCommits",
+ *   "options": {
+ *     "blockSquashCommits": true,
+ *     "blockFixupCommits": true,
+ *     "protectedBranches": ["main", "master", "integration"]
+ *   }
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Branch/Action/EnsureNaming.php

@@ -22,6 +22,20 @@
 /**
  * Class EnsureNaming
  *
+ * This Action makes sure you are on a branch that follows your naming conventions.
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "CaptainHook.Branch.EnsureNaming",
+ *   "options": {
+ *     "regex": "#feature/issue[0-9]+-.*#i",
+ *     "error": "Arr matey! Ye be on the wrong branch!",
+ *     "success": "All clear, Captain! Full speed ahead!",
+ *   }
+ * }
+ * </code>
+ *
  * @package CaptainHook
  * @author  Felix Edelmann <[email protected]>
  * @link    https://github.com/captainhook-git/captainhook

src/Hook/Condition/Branch/NotOn.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * NotOn condition
+ * NotOn Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.NotOnBranch",
+ *       "args": ["not-on-this-branch"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/NotOnMatching.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * NotOnMatching condition
+ * NotOnMatching Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.NotOnMatchingBranch",
+ *       "args": ["#^branches-names/not-matching[0-9]+-this-regex$#i"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/On.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * On condition
+ * On Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.OnBranch",
+ *       "args": ["only-on-this-branch"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Branch/OnMatching.php

@@ -18,7 +18,20 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * OnMatching condition
+ * OnMatching Branch condition
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "some-action",
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Status.OnMatchingBranch",
+ *       "args": ["#^branches-names/matching[0-9]+-this-regex$#i"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Condition/Config/CustomValueIsFalsy.php

@@ -17,22 +17,31 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * Class CustomValueIsFalsy
+ * Condition CustomValueIsFalsy
+ *
+ * With this condition, you can check if a given custom value is falsy.
+ * The Action only is executed if the custom value is falsy.
+ * Values considered falsy are, 0, null, empty string, empty array and false.
  *
  * Example configuration:
  *
- * "action": "some-action"
- * "conditions": [
- *   {"exec": "\\CaptainHook\\App\\Hook\\Condition\\Config\\CustomValueIsFalsy",
- *    "args": [
- *      "NAME_OF_CUSTOM_VALUE"
- *    ]}
- * ]
+ * <code>
+ * {
+ *   "action": "some-action"
+ *   "conditions": [
+ *     {
+ *       "exec": "CaptainHook.Config.CustomValueIsFalsy",
+ *       "args": ["NAME_OF_CUSTOM_VALUE"]
+ *     }
+ *   ]
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>
  * @link    https://github.com/captainhook-git/captainhook
  * @since   Class available since Release 5.17.2
+ * @short   CaptainHook.Config.CustomValueIsFalsy
  */
 class CustomValueIsFalsy extends Condition\Config
 {

src/Hook/Debug/Failure.php

@@ -18,7 +18,17 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * Debug hook to test hook triggering that fails the hook execution
+ * Debug Failure
+ *
+ * Debug hook to test hook triggering, arguments, stdIn ect.
+ * Fails the hook execution and stops current the git operation.
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "CaptainHook.Debug.Fail"
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Hook/Debug/Success.php

@@ -17,7 +17,17 @@
 use SebastianFeldmann\Git\Repository;
 
 /**
- * Debug hook to test hook triggering that allows the hook to pass
+ * Debug Success
+ *
+ * Debug hook action to test hook triggering, arguments, stdIn etc.
+ * Does not crash the hook execution. The git operation will succeed.
+ *
+ * Example configuration:
+ * <code>
+ * {
+ *   "action": "CaptainHook.Debug.Ok"
+ * }
+ * </code>
  *
  * @package CaptainHook
  * @author  Sebastian Feldmann <[email protected]>

src/Runner/Action/PHP.php

@@ -19,6 +19,7 @@
 use CaptainHook\App\Hook\Constrained;
 use CaptainHook\App\Hook\EventSubscriber;
 use CaptainHook\App\Runner\Action as ActionRunner;
+use CaptainHook\App\Runner\Shorthand;
 use Error;
 use Exception;
 use RuntimeException;
@@ -40,13 +41,13 @@ class PHP implements ActionRunner
      *
      * @var string
      */
-    private $hook;
+    private string $hook;
 
     /**
      *
      * @var \CaptainHook\App\Event\Dispatcher
      */
-    private $dispatcher;
+    private Dispatcher $dispatcher;
 
     /**
      * PHP constructor.
@@ -71,7 +72,7 @@ public function __construct(string $hook, Dispatcher $dispatcher)
      */
     public function execute(Config $config, IO $io, Repository $repository, Config\Action $action): void
     {
-        $class = $action->getAction();
+        $class = $this->getActionClass($action->getAction());
 
         try {
             // if the configured action is a static php method display the captured output and exit
@@ -80,7 +81,7 @@ public function execute(Config $config, IO $io, Repository $repository, Config\A
                 return;
             }
 
-            // if not static it has to be an 'Action' so let's instantiate
+            // if not static, it has to be an 'Action' so let's instantiate
             $exe = $this->createAction($class);
             // check for any given restrictions
             if (!$this->isApplicable($exe)) {
@@ -170,4 +171,15 @@ private function isApplicable(Action $action)
         }
         return true;
     }
+
+    /**
+     * Make sure action shorthands are translated before instantiating
+     *
+     * @param  string $action
+     * @return string
+     */
+    private function getActionClass(string $action): string
+    {
+        return Shorthand::isShorthand($action) ? Shorthand::getActionClass($action) : $action;
+    }
 }

src/Runner/Condition.php

@@ -109,7 +109,7 @@ private function createCondition(Config\Condition $config): ConditionInterface
         }
 
         /** @var class-string<\CaptainHook\App\Hook\Condition> $class */
-        $class = $config->getExec();
+        $class = $this->getConditionClass($config->getExec());
         if (!class_exists($class)) {
             throw new RuntimeException('could not find condition class: ' . $class);
         }
@@ -165,4 +165,15 @@ private function isLogicCondition(Config\Condition $config): bool
     {
         return in_array(strtolower($config->getExec()), ['and', 'or']);
     }
+
+    /**
+     * Returns the condition class
+     *
+     * @param string $exec
+     * @return string
+     */
+    private function getConditionClass(string $exec): string
+    {
+        return Shorthand::isShorthand($exec) ? Shorthand::getConditionClass($exec) : $exec;
+    }
 }