CI(clang-format): Run faster and post fixes as code suggestions if possible when running on a PR

[echoix]

Replaces #3284
Closes #3284

This PR replaces #3284.
It is an adaptation of OSGeo/grass-addons#1038.

This integrates the ideas of #3284, which is to run clang-format way faster, in the 30-second range. It also sets the infrastructure needed to post code suggestions to the PRs of linter fixes. Clang-format is now the first here to have it. It is designed, and planned, to have some of our other tools add code suggestions as fixes to PRs to facilitate completing them and applying small fixes without a full round of feedback from the author.

Here is what I wrote for OSGeo/grass-addons#1038:

After a hundred iterations or so, I've got a solution that I'm satisfied with. This allows linter formatting in a PR from a forked pull request to do so without any special secret access, and also be able to add PR review comments, that need pull-request: write permissions. These permissions cannot be granted for PRs coming from forks. Since all the PRs come from forks, we could never use any write permissions from our forks. It also avoids using pull_request_target with a checkout of the external code, which is something that should never be done.

Instead, it runs another workflow triggered by the completion of another workflow, through the workflow_run trigger. That second workflow takes 3 seconds, max 10 including startup. It won't appear as a check for a PR, but still manages to use the event's payload information available to apply to the PR. The fixes that need to be added as code suggestion comments are fed through the upload of a diff artifact. It is then easily downloaded in the second workflow.

Note that PR review comments can only be added to lines in the diff context, that is 3 lines above or below the changed lines of a PR, just like the web interface: the API isn't different. The code suggestion comments are added on a best-effort basis to facilitate contributors to finish a PR. So only upgrading the clang-format version in a PR won't be able to post suggestions on all changes in the repo, since the affected lines aren't changed in that PR.

I designed this solution to be able to accept and post code suggestions for other tools in the near future. Other workflows could upload diffs from multiple tools in the same artifact, and only the tool name and the file name needs to be handled by conditional expressions (if: ...) or a bash loop (careful to not inject the file names from the artifact, as it is untrusted inputs; prefer whitelisting the expected file names to match to). For now, it is implemented for clang-format.

This time, I created a new organization, so I could develop with the forked-repo situation from the start. Once this PR is merged, the "callback" workflow that post code suggestions will be enabled, and will work right away.

Examples (when intentionally creating formatting errors):

They can be batch committed as always by going to the files changed tab and adding the suggestions to a batch, and creating one commit.

[echoix]

@wenzeslaus can you take a look at this on your next time on the repo? I'd love to see this functionality finally integrated and used by all ;)

[wenzeslaus]

Well, this looks like a great accomplishment. I'm curious about balance of clear usefulness for small changes and of how this will work for places where change triggers a large reformatting. That needs testing in practice, though. However, the suggestion-based workflow with reviewdog seems to address all my previous concerns (and bad experience) with automation for fixes. This may save us some review time in the PRs to come, thanks!

[echoix]

If ever we happen to have a really large code change, that on top of that is really badly formatted, and that there was no other limits preventing from having that much of comments added (like the 10 annotations per step limit: annotations is when a log output uses the special formatting codes or is matched by a problem matcher, making yellow or red boxes throughout the code or in the summary), then I would look into it at a later time. If it happens, the PR would already be big itself and in bad shape.