Add local pre-push validation gates

Co-authored-by: Andrew Kesterson <andrew@starfort.tech>

.gitea/workflows/ci.yaml

@@ -64,6 +64,7 @@ jobs:
               -I tests \
               tests/freestanding_fixture.c -o /tmp/freestanding_fixture.o
       - run: echo "🍏 This job's status is ${{ job.status }}."
+
   sanitizer:
     runs-on: ubuntu-latest
     steps:

.githooks/pre-push

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+#
+# Run the repository's cheap gates before a push reaches the forge.  CI remains
+# the hard gate; this hook makes the common failure modes cheap to find.
+#
+# Install once per clone:
+#
+#     git config core.hooksPath .githooks
+#
+# The mutation harness is deliberately opt-in because it is slow:
+#
+#     AKERR_HOOK_MUTATION=1 git push
+#
+# Git's normal escape hatch remains available:
+#
+#     git push --no-verify
+#
+# Builds go under .git/akerr-prepush so the hook does not disturb build/.
+# Override that location with AKERR_HOOK_BUILD_DIR when needed.
+
+set -u
+
+ZERO_SHA=0000000000000000000000000000000000000000
+
+root=$(git rev-parse --show-toplevel) || exit 1
+cd "$root" || exit 1
+
+# A delete-only push, or an invocation with no refs on stdin, has no new code
+# to validate.
+has_updates=0
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+    if [ "$local_sha" != "$ZERO_SHA" ]; then
+	has_updates=1
+    fi
+done
+if [ "$has_updates" -eq 0 ]; then
+    exit 0
+fi
+
+builddir="${AKERR_HOOK_BUILD_DIR:-$(git rev-parse --git-dir)/akerr-prepush}"
+mkdir -p "$builddir" || exit 1
+logfile="$builddir/last.log"
+
+# Keep normal output short, but preserve the complete failing command output.
+run() {
+    if ! "$@" > "$logfile" 2>&1; then
+	echo >&2
+	echo "pre-push: FAILED: $*" >&2
+	echo "---------------------------------------------------------------" >&2
+	cat "$logfile" >&2
+	echo "---------------------------------------------------------------" >&2
+	echo "pre-push: push aborted. Use 'git push --no-verify' to override." >&2
+	exit 1
+    fi
+}
+
+if [ -f scripts/cppcheck.sh ] && command -v cppcheck > /dev/null 2>&1; then
+    echo "pre-push: cppcheck"
+    run bash scripts/cppcheck.sh
+elif [ ! -f scripts/cppcheck.sh ]; then
+    echo "pre-push: scripts/cppcheck.sh not present, skipping cppcheck"
+else
+    echo "pre-push: cppcheck not installed, skipping cppcheck"
+fi
+
+echo "pre-push: default build + ctest"
+run cmake -S . -B "$builddir/default"
+run cmake --build "$builddir/default"
+run ctest --test-dir "$builddir/default" --output-on-failure
+
+echo "pre-push: AKERR_USE_STDLIB=OFF build + ctest"
+run cmake -S . -B "$builddir/stdlib-off" \
+    -DAKERR_USE_STDLIB=OFF -DAKERR_THREADS=none
+run cmake --build "$builddir/stdlib-off"
+run ctest --test-dir "$builddir/stdlib-off" --output-on-failure
+
+if [ "${AKERR_HOOK_MUTATION:-0}" = "1" ]; then
+    if command -v python3 > /dev/null 2>&1; then
+	echo "pre-push: mutation testing (this takes a while)"
+	if ! python3 scripts/mutation_test.py \
+		--target src/error.c \
+		--threshold "${AKERR_MUTATION_THRESHOLD:-65}"; then
+	    echo >&2
+	    echo "pre-push: mutation score below threshold. Push aborted." >&2
+	    echo "pre-push: use 'git push --no-verify' to override." >&2
+	    exit 1
+	fi
+    else
+	echo "pre-push: python3 not installed, skipping mutation testing"
+    fi
+fi
+
+echo "pre-push: OK"
+exit 0

README.md

@@ -43,6 +43,26 @@ cmake --build build
 cmake --install build
 ```
 
+## Local pre-push checks
+
+Enable the repository's local pre-push checks once in each clone:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+The hook runs cppcheck when `scripts/cppcheck.sh` and cppcheck are available,
+then the default build and tests, followed by the `AKERR_USE_STDLIB=OFF`
+build and tests. Builds are kept under `.git/akerr-prepush` and do not disturb
+the normal `build/` directory. Mutation testing is opt-in because it is slow:
+
+```bash
+AKERR_HOOK_MUTATION=1 git push
+```
+
+CI remains the hard gate. For an intentional local escape, use Git's standard
+`git push --no-verify` option.
+
 The library depends on `stdlib` and on POSIX threads. Both are optional at the
 cost of some functionality — see [docs/building.md](docs/building.md) for
 `-DAKERR_USE_STDLIB=OFF` and

scripts/mutation_test.py

@@ -25,6 +25,8 @@ Usage:
     --work DIR          scratch dir for the mutated copy (default: a temp dir)
     --timeout SECONDS   per-suite ctest timeout (default: 120)
     --threshold PCT     exit non-zero if mutation score < PCT (default: 0 = off)
+    --cmake-arg ARG     pass an additional argument to the mutant CMake configure;
+                        repeat for multiple arguments (e.g. -DAKERR_SANITIZE=thread)
     --list              only list the mutants that would be run, then exit
     --keep              keep the scratch working copy on exit (for debugging)
     -j N                (reserved) currently runs sequentially
@@ -199,10 +201,11 @@ def generate_mutants(root, rel_target):
 # --------------------------------------------------------------------------- #
 
 class Runner:
-    def __init__(self, work, timeout):
+    def __init__(self, work, timeout, cmake_args):
         self.work = work
         self.build = os.path.join(work, "build")
         self.timeout = timeout
+        self.cmake_args = cmake_args
 
     def _run(self, cmd, timeout=None):
         return subprocess.run(
@@ -211,7 +214,8 @@ class Runner:
         )
 
     def configure(self):
-        r = self._run(["cmake", "-S", ".", "-B", "build"], timeout=self.timeout)
+        r = self._run(["cmake", "-S", ".", "-B", "build", *self.cmake_args],
+                      timeout=self.timeout)
         return r.returncode == 0, r.stdout
 
     def build_and_test(self):
@@ -307,6 +311,8 @@ def main():
     ap.add_argument("--work", default=None)
     ap.add_argument("--timeout", type=int, default=120)
     ap.add_argument("--threshold", type=float, default=0.0)
+    ap.add_argument("--cmake-arg", action="append", default=[],
+                    help="pass an argument to the mutant CMake configure; repeatable")
     ap.add_argument("--junit", default=None,
                     help="write a JUnit XML report to this path")
     ap.add_argument("--max-mutants", type=int, default=0,
@@ -354,7 +360,7 @@ def main():
     print(f"\nCopying sources to scratch dir: {work}")
     copy_tree(root, work)
 
-    runner = Runner(work, args.timeout)
+    runner = Runner(work, args.timeout, args.cmake_arg)
 
     print("Configuring baseline ...")
     ok, out = runner.configure()

tests/MUTATION.md

@@ -32,6 +32,9 @@ scripts/mutation_test.py --target src/error.c --list
 
 # Gate CI: exit non-zero if the score drops below 90%
 scripts/mutation_test.py --threshold 90
+
+# Check concurrency mutants under ThreadSanitizer
+scripts/mutation_test.py --cmake-arg=-DAKERR_SANITIZE=thread
 ```
 
 Via CMake (configures a build first if needed):
@@ -40,8 +43,10 @@ Via CMake (configures a build first if needed):
 cmake --build build --target mutation
 ```
 
-Useful flags: `--timeout SECONDS` (per-suite build+test cap; a mutant that
-hangs is counted as killed), `--keep` (retain the scratch copy for debugging),
+Useful flags: `--cmake-arg ARG` (pass a CMake configure argument to every
+mutant build; repeat it for multiple arguments), `--timeout SECONDS` (per-suite
+build+test cap; a mutant that hangs is counted as killed), `--keep` (retain the
+scratch copy for debugging),
 `--work DIR` (use a specific scratch directory), `--junit FILE` (write a JUnit
 XML report — surviving mutants appear as failing test cases).