Add CI for formatting and linting checks

.github/workflows/format-lint-comment.yml

@@ -0,0 +1,105 @@
+# This takes the results of "format-lint.yaml" and creates a comment on the PR to explain 
+# them.
+#
+# See "format-lint.yaml" for more details on why this workflow split is needed.
+
+name: PR comment
+
+on:
+  workflow_run:
+    workflows: [Format and lint]
+    types: [completed]
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request'
+    permissions:
+      pull-requests: write
+      actions: read
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Download panache results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        continue-on-error: true
+        with:
+          name: panache-results
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: /tmp/panache
+
+      - name: Download jarl results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        continue-on-error: true
+        with:
+          name: jarl-results
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: /tmp/jarl
+
+      - name: Read results
+        id: results
+        run: |
+          echo "pr_number=$(cat /tmp/panache/pr-number.txt 2>/dev/null)" >> "$GITHUB_OUTPUT"
+          echo "panache_result=$(cat /tmp/panache/panache-result.txt 2>/dev/null)" >> "$GITHUB_OUTPUT"
+          echo "jarl_result=$(cat /tmp/jarl/jarl-result.txt 2>/dev/null)" >> "$GITHUB_OUTPUT"
+
+      # After reading the results of Panache and Jarl, we have several possible outcomes:
+      #   - both pass: if we had created a comment before because at least one of them was
+      #       failing, then we update this comment. Otherwise, we don't open a comment just to
+      #       say that this is passing.
+      #   - Jarl, Panache, or both fail: we create a comment with a custom template to explain 
+      #       what failed and how to fix it locally. This should help new contributors when 
+      #       they see that CI for linting and formatting fails. 
+
+      # This is needed to know if we need to create or update a comment.
+      - name: Find existing comment
+        if: steps.results.outputs.pr_number != ''
+        uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
+        id: find-comment
+        with:
+          issue-number: ${{ steps.results.outputs.pr_number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '<!-- format-lint-check -->'
+
+      # Build the comment body depending on Panache and Jarl results. For the case where both
+      # fail, we concatenate the two single-failure templates. 
+      #
+      # Note that the case with both succeeding produces a template only if we have                  
+      # "$COMMENT_ID", i.e. if we already created a comment before. If we didn't, then               
+      # `steps.build.outputs.ready` is false and the last step isn't triggered.            
+      - name: Build comment
+        id: build
+        if: steps.results.outputs.pr_number != ''
+        env:
+          PANACHE_RESULT: ${{ steps.results.outputs.panache_result }}
+          JARL_RESULT: ${{ steps.results.outputs.jarl_result }}
+          COMMENT_ID: ${{ steps.find-comment.outputs.comment-id }}
+        # The "echo" between the two "cat" ensures a new line between the two templates.
+        run: |
+          if [[ "$PANACHE_RESULT" == "failure" && "$JARL_RESULT" == "failure" ]]; then
+            {
+              cat .github/workflows/templates/panache-only.md
+              echo
+              echo "---"
+              echo
+              cat .github/workflows/templates/jarl-only.md
+            } > /tmp/comment.md
+          elif [[ "$PANACHE_RESULT" == "failure" ]]; then
+            cp .github/workflows/templates/panache-only.md /tmp/comment.md
+          elif [[ "$JARL_RESULT" == "failure" ]]; then
+            cp .github/workflows/templates/jarl-only.md /tmp/comment.md
+          elif [[ -n "$COMMENT_ID" ]]; then
+            cp .github/workflows/templates/all-pass.md /tmp/comment.md
+          fi
+          [[ -f /tmp/comment.md ]] && echo "ready=true" >> "$GITHUB_OUTPUT" || echo "ready=false" >> "$GITHUB_OUTPUT"
+
+      - name: Create or update comment
+        if: steps.build.outputs.ready == 'true' && steps.results.outputs.pr_number != ''
+        uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ steps.results.outputs.pr_number }}
+          body-path: /tmp/comment.md
+          edit-mode: replace

.github/workflows/format-lint.yml

@@ -0,0 +1,68 @@
+# This workflow runs Panache for formatting and Jarl for linting. It stores artifacts about the
+# outcome of each tool and the PR number. Those artifacts are then used in the workflow 
+# "format-lint-pr-comment.yaml" to post a comment so that it's clearer for external
+# contributors.
+#
+# This could have been done in a single workflow with a "pull_request_target" trigger but
+# this might have some security issues (this is unlikely in practice but still better to
+# be ahead of it):
+# https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
+
+name: Format and lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  format-panache:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Run Panache
+        id: check
+        uses: jolars/panache-action@a1e4e68c74a41e6b9dade9c93095a262a23aa48c # v1
+        with:
+          lint: "false"
+        continue-on-error: true
+      - name: Save results
+        if: github.event_name == 'pull_request'
+        run: |
+          echo "${{ steps.check.outcome }}" > /tmp/panache-result.txt
+          echo "${{ github.event.pull_request.number }}" > /tmp/pr-number.txt
+      - name: Upload artifacts
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: panache-results
+          path: |
+            /tmp/panache-result.txt
+            /tmp/pr-number.txt
+      - if: steps.check.outcome == 'failure'
+        run: exit 1
+
+  lint-jarl:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Check
+        id: check
+        uses: etiennebacher/setup-jarl@eabf7e572f2991d165059007531b9bbe2987e39c # v0.1.1
+        continue-on-error: true
+      - name: Save result
+        if: github.event_name == 'pull_request'
+        run: echo "${{ steps.check.outcome }}" > /tmp/jarl-result.txt
+      - name: Upload artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: jarl-results
+          path: /tmp/jarl-result.txt
+      - if: steps.check.outcome == 'failure'
+        run: exit 1

.github/workflows/templates/all-pass.md

@@ -0,0 +1,2 @@
+<!-- format-lint-check -->
+:white_check_mark: All formatting and linting checks passed!

.github/workflows/templates/jarl-only.md

@@ -0,0 +1,14 @@
+<!-- format-lint-check -->
+:x: This Pull Request failed our automated **linting checks**. Please resolve these prior to requesting review. We use Jarl to automatically lint R code. Please [install it](https://jarl.etiennebacher.com/#installation) (you may need to close and reopen your IDE, e.g. RStudio or Positron, after that) and run the following command in the terminal (not the R console) to find linting issues:
+
+```sh
+jarl check .
+```
+
+Some of these issues might be automatically fixed with the following command:
+
+```sh
+jarl check . --fix
+```
+
+<sub>This comment will be automatically updated once linting checks pass.</sub>

.github/workflows/templates/panache-only.md

@@ -0,0 +1,8 @@
+<!-- format-lint-check -->
+:x: This Pull Request failed our automated **formatting checks**. Please resolve these prior to requesting review. We use Panache to automatically format R code chunks in Quarto files. Please [install it](https://panache.bz/getting-started.html#installation) (you may need to close and reopen your IDE, e.g. RStudio or Positron, after that) and run the following command in the terminal (not the R console) to reformat the code:
+
+```sh
+panache format **/*.qmd
+```
+
+<sub>This comment will be automatically updated once formatting checks pass.</sub>