[feature] add a custom hint for failing actions

[CircleCode]

In some companies, or communities, code rules are detailed in custom documentation. For example, in my compani, we have a comprehensive code style redacted and hosted in our internal wiki.
When lint action fails, I'd like to add a message like this:

Your code does not pass the code style.
Go ahead and read it carefully at https://example.net/.
Note: you can automatically fix modified files by running make beautify-php

I'd suggest to add a hint section in actions, accepting:

• a single string to be printed
• an array of strings to be printed

Note: I was wondering if accepting a custom callable would be useful, and I am not against it, but if you are about to write custom code, why not writing the full action in custom code, and thus you do not need the hint section.

If this sounds a reasonable feature to you, I am willing to contribute with a PR.

[sebastianfeldmann]

I would suggest something like this.

"actions": [
    {
        "action": "tools/phpcs,
        "options": {
            "hint": ["my custom error message"],
        },
   }
]

What do you think?

[CircleCode]

I thought about adding it into options too, but it was counterintuitive to me:
Here, the hint would not be consumed by the action itself, as it is common for all actions, and would rather be consumed by captainhook itself. So I felt like mixing action-specific options, and generic options.

Maybe I am wrong and there already exists generic options; in this case, your suggestion would be the way to go.

[sebastianfeldmann]

I thought a little bit about it and I think creating a dedicated CLI-Action is the way to go.
Something like this

"actions": {
  {
    "action": "\\CaptainHook\\App\\Hook\\Cli\\Action\\Advanced",
    "options": {
      "command": "ls -lisa",
      "hint": "some hint",
      "acceptableErrorCodes": [0, 14, 773]
    }
  }
}

[CircleCode]

I like the idea of a dedicated and explicit CLI-Action. It would allow very specific customization. For exapmple, we could even imagine something like

"actions": {
  {
    "action": "\\CaptainHook\\App\\Hook\\Cli\\Action\\Advanced",
    "options": {
      "command": "ls -lisa",
      "hints": [
        "-1": "default hint",
        "1-13": "some hint for error codes betweek 1 and 13"
      ],
      "acceptableErrorCodes": [0, 14, 773]
    }
  }
}

Note: this is an advanced usage, and I would go for it ina firts run, but it was just an example of how CLI-Action would allow more things in the future.

[sebastianfeldmann]

Yes that would be the point, we could allow more features over time without messing with the Cap'ns core settings.