ci: add GitHub Actions workflow with test matrix, lint, and coverage

Three jobs:

- test: matrix across Emacs 28.2 / 29.4 / snapshot.  Sets up Emacs
  via jcs090218/setup-emacs and Cask via cask/setup-cask, then
  runs make setup (with 3 retries to absorb MELPA flakes) and
  make test-unit.  Org 9.6 ships built-in with Emacs 29; on 28
  Cask pulls it from MELPA per our depends-on declaration.
- lint: Emacs 29.4 only, runs make lint (informational), then
  make compile and make validate-parens.
- coverage: same Emacs version, runs make coverage, prints a
  per-file summary via scripts/coverage-summary.py (copied from
  emacs-wttrin), uploads .coverage/simplecov.json as a workflow
  artifact, and sends results to Coveralls via continue-on-error
  so CI doesn't fail when COVERALLS_REPO_TOKEN isn't set yet.

The README badge URL points at this workflow file (ci.yml) so it
auto-populates on the next push to main.

Closes the [#B] GitHub Actions TODO.  After this lands, the
remaining setup is enabling the org-drill repo on coveralls.io
and adding COVERALLS_REPO_TOKEN as a GitHub secret so the
upload step actually publishes.

2 files changed, 194 insertions, 0 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..6491867
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Emacs ${{ matrix.emacs-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        emacs-version:
+          # Org 9.6 (our floor) ships built-in with Emacs 29; on Emacs
+          # 28 Cask pulls it from MELPA, so 28 still works as a target.
+          - '28.2'
+          - '29.4'
+          - 'snapshot'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Emacs
+        uses: jcs090218/setup-emacs@master
+        with:
+          version: ${{ matrix.emacs-version }}
+
+      - name: Set up Cask
+        uses: cask/setup-cask@master
+
+      - name: Install dependencies
+        run: |
+          for attempt in 1 2 3; do
+            if make setup; then
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "::warning::setup attempt $attempt failed, retrying in 15s"
+              sleep 15
+            fi
+          done
+          echo "::error::setup failed after 3 attempts"
+          exit 1
+
+      - name: Run unit tests
+        run: make test-unit
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Emacs
+        uses: jcs090218/setup-emacs@master
+        with:
+          version: '29.4'
+
+      - name: Set up Cask
+        uses: cask/setup-cask@master
+
+      - name: Install dependencies
+        run: |
+          for attempt in 1 2 3; do
+            if make setup; then
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "::warning::setup attempt $attempt failed, retrying in 15s"
+              sleep 15
+            fi
+          done
+          echo "::error::setup failed after 3 attempts"
+          exit 1
+
+      # `make lint' is informational right now (the source has known
+      # docstring/style debt); kept here so warnings show up in PRs.
+      - name: Run linters
+        run: make lint
+
+      - name: Byte-compile
+        run: make compile
+
+      - name: Validate parens
+        run: make validate-parens
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Emacs
+        uses: jcs090218/setup-emacs@master
+        with:
+          version: '29.4'
+
+      - name: Set up Cask
+        uses: cask/setup-cask@master
+
+      - name: Install dependencies
+        run: |
+          for attempt in 1 2 3; do
+            if make setup; then
+              exit 0
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "::warning::setup attempt $attempt failed, retrying in 15s"
+              sleep 15
+            fi
+          done
+          echo "::error::setup failed after 3 attempts"
+          exit 1
+
+      - name: Run coverage
+        run: make coverage
+
+      - name: Print coverage summary
+        run: python3 scripts/coverage-summary.py
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-simplecov
+          path: .coverage/simplecov.json
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: Send coverage to Coveralls
+        uses: coverallsapp/github-action@v2
+        continue-on-error: true
+        with:
+          file: .coverage/simplecov.json
+          format: simplecov
+        env:
+          COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
diff --git a/scripts/coverage-summary.py b/scripts/coverage-summary.py
new file mode 100755
index 0000000..9b7bc99
--- /dev/null
+++ b/scripts/coverage-summary.py
@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Print a per-file and overall coverage summary from undercover's simplecov JSON.
+
+Usage:
+    python3 scripts/coverage-summary.py [path]
+
+If `path` is omitted, defaults to `.coverage/simplecov.json`.
+Exit code is 0 on success, 1 if the JSON is missing or malformed.
+"""
+
+import json
+import os
+import sys
+
+
+def main(path: str) -> int:
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        print(f"error: {path} not found; run `make coverage` first", file=sys.stderr)
+        return 1
+    except json.JSONDecodeError as exc:
+        print(f"error: {path} is not valid JSON: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        suite = data["undercover.el"]["coverage"]
+    except (KeyError, TypeError):
+        print(f"error: {path} does not look like an undercover simplecov report",
+              file=sys.stderr)
+        return 1
+
+    print(f'{"File":<30} {"Lines":>7} {"Covered":>8} {"Coverage":>10}')
+    print("-" * 60)
+
+    total_lines = 0
+    total_covered = 0
+    for fname, lines in suite.items():
+        relevant = [l for l in lines if l is not None]
+        covered = sum(1 for l in relevant if l > 0)
+        pct = 100.0 * covered / len(relevant) if relevant else 0.0
+        total_lines += len(relevant)
+        total_covered += covered
+        short = os.path.basename(fname)
+        print(f"{short:<30} {len(relevant):>7} {covered:>8} {pct:>9.2f}%")
+
+    print("-" * 60)
+    overall = 100.0 * total_covered / total_lines if total_lines else 0.0
+    print(f'{"TOTAL":<30} {total_lines:>7} {total_covered:>8} {overall:>9.2f}%')
+    return 0
+
+
+if __name__ == "__main__":
+    target = sys.argv[1] if len(sys.argv) > 1 else ".coverage/simplecov.json"
+    sys.exit(main(target))