chore: add GH commit conventions check

Signed-off-by: Ronan Abhamon <ronan.abhamon@vates.tech>

Author: Wescoeur

.github/commit-scopes.txt

@@ -0,0 +1,4 @@
+# Allowed commit scopes, one per line (blank lines and lines starting with `#` are ignored).
+# Used by `.github/scripts/check-commit-messages.sh`.
+core
+tests/core

.github/scripts/check-commit-messages.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Check the commit message conventions of a pull request.
+#
+# Usage: check-commit-messages.sh <base-sha> <head-sha> <pr-number>
+#
+# Rules:
+# - Format: `<type>(<scope>): <subject>`, with type in `feat`, `fix`, `docs` or `chore`.
+# - `feat`, `fix` and `docs` require a scope. `chore` accepts an optional one.
+# - A scope must be in the allowed list of `.github/commit-scopes.txt`.
+# - A commit that only touches files in `tests/` must have a scope starting with `tests/`
+#   (even for `chore`), and a scope starting with `tests/` is only allowed for such commits.
+# - A `chore` commit touching files in `src/` or `tests/` only triggers a warning (never a failure).
+# - If the pull request has several commits, each one must end with ` (#<pr-number>)`.
+#   With a single commit nothing is checked: the ID is added when the pull request is merged.
+
+set -euo pipefail
+
+readonly SCOPES_FILE="$(dirname "$0")/../commit-scopes.txt"
+
+# ==============================================================================
+
+if [ "$#" -ne 3 ]; then
+    echo "Usage: $0 <base-sha> <head-sha> <pr-number>" >&2
+    exit 2
+fi
+
+readonly BASE_SHA=$1
+readonly HEAD_SHA=$2
+readonly PR_NUMBER=$3
+
+# ------------------------------------------------------------------------------
+
+# Read the allowed scopes, one per line, ignoring comments and blank lines.
+mapfile -t scopes < <(grep -vE '^[[:space:]]*(#|$)' "$SCOPES_FILE" | sed -E 's/^[[:space:]]+|[[:space:]]+$//g')
+if [ "${#scopes[@]}" -eq 0 ]; then
+    echo "::error::No allowed scope found in `${SCOPES_FILE}`."
+    exit 2
+fi
+
+# Escape the regex special characters of each scope, then join them with `|`.
+ALLOWED_SCOPES=$(printf '%s\n' "${scopes[@]}" | sed -E 's/[][\\.^$*+?(){}|]/\\&/g' | paste -sd'|')
+readonly ALLOWED_SCOPES
+
+DISPLAYED_SCOPES=$(printf '`%s`, ' "${scopes[@]}")
+readonly DISPLAYED_SCOPES
+
+readonly SUBJECT_REGEX='.*[^ ]'
+readonly SCOPE_REGEX="\\((${ALLOWED_SCOPES})\\)"
+readonly COMMIT_REGEX="^((feat|fix|docs)${SCOPE_REGEX}|chore(${SCOPE_REGEX})?): ${SUBJECT_REGEX}$"
+
+# ------------------------------------------------------------------------------
+
+mapfile -t hashes < <(git log --no-merges --format=%H "${BASE_SHA}..${HEAD_SHA}")
+
+# ------------------------------------------------------------------------------
+
+get_changed_files() {
+    git diff-tree --root --no-commit-id --name-only -r "$1"
+}
+
+is_touching_only_tests() {
+    local files
+    files=$(get_changed_files "$1")
+    [ -n "$files" ] && ! grep -qv '^tests/' <<< "$files"
+}
+
+is_touching_src_or_tests() {
+    local files
+    files=$(get_changed_files "$1")
+    grep -qE '^(src|tests)/' <<< "$files"
+}
+
+# ------------------------------------------------------------------------------
+
+errors=0
+for hash in "${hashes[@]}"; do
+    subject=$(git log -1 --format=%s "$hash")
+    # The ID is optional here: the format is checked without it.
+    message=${subject% (#[0-9]*)}
+
+    if ! [[ $message =~ $COMMIT_REGEX ]]; then
+        echo "::error::Invalid commit message. Expected \`feat|fix|docs(<scope>): ...\` or \`chore[(<scope>)]: ...\`, with scope in [${DISPLAYED_SCOPES%, }]: \"${subject}\""
+        errors=$((errors + 1))
+        continue
+    fi
+
+    scope=""
+    if [[ $message =~ ^[a-z]+\(([^\)]+)\) ]]; then
+        scope=${BASH_REMATCH[1]}
+    fi
+    if is_touching_only_tests "$hash"; then
+        if [[ $scope != tests/* ]]; then
+            echo "::error::Commit only touches \`tests/\`, its scope must start with \`tests/\`: \"${subject}\"."
+            errors=$((errors + 1))
+        fi
+    elif [[ $scope == tests/* ]]; then
+        echo "::error::Scope \`${scope}\` is only allowed for commits that only touch \`tests/\`: \"${subject}\"."
+        errors=$((errors + 1))
+    fi
+
+    if [[ $message == chore* ]] && is_touching_src_or_tests "$hash"; then
+        echo "::warning::Commit \`chore\` touches files in \`src/\` or \`tests/\`, consider \`feat\`, \`fix\` or \`docs\`: \"${subject}\"."
+    fi
+
+    if [ "${#hashes[@]}" -gt 1 ] && [[ $subject != *" (#${PR_NUMBER})" ]]; then
+        echo "::error::Commit message must end with \" (#${PR_NUMBER})\": \"${subject}\"."
+        errors=$((errors + 1))
+    fi
+done
+
+if [ "$errors" -ne 0 ]; then
+    exit 1
+fi
+echo "${#hashes[@]} commit message(s) checked: OK."

.github/workflows/commit-conventions.yml

@@ -0,0 +1,25 @@
+name: Commit conventions
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  commit-messages:
+    name: Commit messages
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check commit messages
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: .github/scripts/check-commit-messages.sh "$BASE_SHA" "$HEAD_SHA" "$PR_NUMBER"