Run cabal-docspec in CI

This allows us to include runnable examples in Haddock comments, which are
tested in CI. We will be adding such a runnable example in the next commits.

Author: jorisdral

.github/workflows/ci.yml

@@ -200,6 +200,16 @@ jobs:
       run: |
         cabal test all -j1 --test-show-details=direct
 
+    - name: 🛠️ Setup cabal-docspec (Linux)
+      if: ${{ runner.os == 'Linux' }}
+      uses: jorisdral/actions/setup-cabal-docspec@main
+
+    - name: 🧪 Test with cabal-docspec (Linux)
+      if: ${{ runner.os == 'Linux' }}
+      run: ./scripts/test-cabal-docspec.sh
+      env:
+        SKIP_CABAL_BUILD: true
+
   ################################################################################
   # Lint with cabal-fmt
   ################################################################################
@@ -211,7 +221,7 @@ jobs:
       uses: actions/checkout@v5
 
     - name: 🛠️ Setup cabal-fmt
-      uses: intersectMBO/lsm-tree/.github/actions/setup-cabal-fmt@main
+      uses: jorisdral/actions/setup-cabal-fmt@main
       with:
         cabal-fmt-version: "0.1.12"
         ghc-version: "9.6"
@@ -277,7 +287,7 @@ jobs:
       uses: actions/checkout@v5
 
     - name: 🛠️ Setup stylish-haskell
-      uses: intersectMBO/lsm-tree/.github/actions/setup-stylish-haskell@main
+      uses: jorisdral/actions/setup-stylish-haskell@main
       with:
         stylish-haskell-version: "0.15.1.0"
         ghc-version: "9.10"

scripts/test-cabal-docspec.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+export LC_ALL=C.UTF-8
+
+# POSIX compliant method for 'pipefail':
+warn=$(mktemp)
+
+# Check cabal-docspec version
+cabal_docspec_expect_version="0.0.0.20240703"
+if [ "${cabal_docspec}" = "" ]; then
+    cabal_docspec=$(which "cabal-docspec")
+    if [ "${cabal_docspec}" = "" ]; then
+        echo "Requires cabal-docspec ${cabal_docspec_expect_version}; no version found"
+        exit 1
+    fi
+fi
+cabal_docspec_actual_version="$(${cabal_docspec} --version | head -n 1)"
+if [ ! "${cabal_docspec_actual_version}" = "${cabal_docspec_expect_version}" ]; then
+    echo "Expected cabal-docspec ${cabal_docspec_expect_version}; version ${cabal_docspec_actual_version} found"
+    echo > "$warn"
+fi
+
+# Test Haskell files with cabal-docspec
+echo "Testing Haskell files with cabal-docspec version ${cabal_docspec_actual_version}..."
+# shellcheck disable=SC2016
+if [ "${SKIP_CABAL_BUILD}" = "" ]; then
+    if ! cabal build all; then
+        exit 1
+    fi
+fi
+${cabal_docspec} \
+    -Wno-cpphs \
+    -Wno-missing-module-file \
+    -Wno-skipped-property \
+    -XOverloadedStrings \
+    --extra-package async \
+    || exit 1
+
+# Check whether any warning was issued; on CI, warnings are errors
+if [ "${CI}" = "true" ] && [ -s "$warn" ]; then
+    rm "$warn"
+    exit 1
+else
+    rm "$warn"
+    exit 0
+fi