CI: add PR size and commit message quality checks

Add pr-hygiene workflow with two checks:
- PR size: warns at 300 lines, fails at 500 (configurable via
  PR_SIZE_WARN/PR_SIZE_FAIL env vars), excludes lock files
- Commit messages: enforces title <= 80 chars, rejects fixup/WIP
  commits, requires body for commits with 20+ lines changed

Update Makefile lint-shell target to include new scripts.

Closes #77

Author: dannywillems

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Validate commit message quality for all commits in a PR.
+#
+# Checks:
+# 1. Title (first line) must be <= 80 characters
+# 2. No fixup!/squash!/WIP commits in the final PR
+# 3. Commits with 20+ lines changed must have a non-empty body
+#
+# Usage: check-commit-messages.sh <base-sha>
+set -euo pipefail
+
+base="${1:?Usage: check-commit-messages.sh <base-sha>}"
+errors=0
+
+for commit in $(git log --format=%H "${base}..HEAD"); do
+    # Get the full commit message.
+    subject=$(git log -1 --format=%s "$commit")
+    body=$(git log -1 --format=%b "$commit")
+    short=$(git log -1 --format=%h "$commit")
+
+    # --- Check 1: Title length ---
+    title_len=${#subject}
+    if [ "$title_len" -gt 80 ]; then
+        echo "::error::Commit $short: title is $title_len chars (max 80)."
+        echo "  Title: $subject"
+        errors=$((errors + 1))
+    fi
+
+    # --- Check 2: No fixup/squash/WIP commits ---
+    case "$subject" in
+        fixup!*|squash!*|WIP:*|WIP\ *|wip:*|wip\ *)
+            echo "::error::Commit $short: fixup/squash/WIP commits must be cleaned up before merge."
+            echo "  Title: $subject"
+            errors=$((errors + 1))
+            ;;
+    esac
+
+    # --- Check 3: Large commits need a body ---
+    lines_changed=$(git diff-tree --no-commit-id --numstat -r "$commit" \
+        | awk '{ s += $1 + $2 } END { print s+0 }')
+    body_trimmed=$(echo "$body" | sed '/^$/d' | head -1)
+    if [ "$lines_changed" -ge 20 ] && [ -z "$body_trimmed" ]; then
+        echo "::error::Commit $short: $lines_changed lines changed but no commit body."
+        echo "  Commits with 20+ lines changed should include a description."
+        errors=$((errors + 1))
+    fi
+done
+
+# --- Summary ---
+
+if [ "$errors" -gt 0 ]; then
+    echo "Found $errors commit message error(s)."
+    exit 1
+fi
+
+echo "All commit message checks passed."

.github/scripts/pr-hygiene/check-pr-size.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Check that a PR does not exceed a configurable line-change threshold.
+#
+# Excludes generated files (lock files, etc.) from the count.
+# Exits 0 on success, 1 on failure, and prints a warning when the
+# soft threshold is exceeded but the hard threshold is not.
+#
+# Environment variables (optional):
+#   PR_SIZE_WARN   - soft threshold (default: 300)
+#   PR_SIZE_FAIL   - hard threshold (default: 500)
+#
+# Usage: check-pr-size.sh <base-sha>
+set -euo pipefail
+
+base="${1:?Usage: check-pr-size.sh <base-sha>}"
+warn_threshold="${PR_SIZE_WARN:-300}"
+fail_threshold="${PR_SIZE_FAIL:-500}"
+
+# Patterns for generated/vendored files to exclude from the count.
+exclude_patterns=(
+    "*.lock"
+    "uv.lock"
+    "poetry.lock"
+    "package-lock.json"
+    "yarn.lock"
+    "pnpm-lock.yaml"
+    "Cargo.lock"
+)
+
+# Build the pathspec exclusion arguments.
+pathspec_args=()
+for pattern in "${exclude_patterns[@]}"; do
+    pathspec_args+=(":(exclude)${pattern}")
+done
+
+# Count added + removed lines, excluding generated files.
+diff_stat=$(git diff --numstat "${base}...HEAD" -- . "${pathspec_args[@]}")
+
+total=0
+while IFS=$'\t' read -r added removed _path; do
+    # Binary files show "-" for added/removed; skip them.
+    if [ "$added" = "-" ] || [ "$removed" = "-" ]; then
+        continue
+    fi
+    total=$((total + added + removed))
+done <<< "$diff_stat"
+
+echo "Total lines changed (excluding generated files): $total"
+
+if [ "$total" -gt "$fail_threshold" ]; then
+    echo "::error::PR is too large ($total lines changed, threshold: $fail_threshold)."
+    echo "Consider splitting into smaller, focused PRs."
+    exit 1
+fi
+
+if [ "$total" -gt "$warn_threshold" ]; then
+    echo "::warning::PR is getting large ($total lines changed, warn threshold: $warn_threshold)."
+    echo "Consider whether this can be split into smaller PRs."
+fi
+
+echo "PR size check passed."

.github/workflows/pr-hygiene.yaml

@@ -0,0 +1,33 @@
+name: PR hygiene checks
+on:
+  pull_request:
+    types: [assigned, opened, synchronize, reopened]
+    branches:
+      - main
+  merge_group:
+    types: [checks_requested]
+
+jobs:
+  check-pr-size:
+    name: Check PR size
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Verify PR is not too large
+        run: >
+          .github/scripts/pr-hygiene/check-pr-size.sh
+          "${{ github.event.pull_request.base.sha }}"
+
+  check-commit-messages:
+    name: Check commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Verify commit message quality
+        run: >
+          .github/scripts/pr-hygiene/check-commit-messages.sh
+          "${{ github.event.pull_request.base.sha }}"

Makefile

@@ -52,7 +52,8 @@ lint-fix: ## Lint and fix code using ruff
 
 .PHONY: lint-shell
 lint-shell: ## Lint shell scripts using shellcheck
-	shellcheck .github/scripts/*.sh
+	shellcheck .github/scripts/*.sh \
+		.github/scripts/pr-hygiene/*.sh
 
 .PHONY: typecheck
 typecheck: ## Run mypy type checker