Merge pull request 'Add local pre-push validation gates' (#34) from 32 into main

Reviewed-on: #34

.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

CMakeLists.txt

@@ -1,6 +1,24 @@
 cmake_minimum_required(VERSION 3.10)
-# Version changelog notices DO NOT GO HERE. Put them in UPGRADING.md instead.
-project(akerror VERSION 2.0.3 LANGUAGES C)
+# 1.0.0 replaced the consumer-sized __AKERR_ERROR_NAMES array with private
+# storage. 2.0.0 makes the library thread safe, which is a second ABI break in
+# the same places: akerr_last_ignored became thread-local storage, and
+# ENSURE_ERROR_READY no longer takes the pool reference that akerr_next_error()
+# now takes for it. Consumer code compiled against a 1.x header would
+# double-count every reference. Hence the major bump and the SOVERSION, so a
+# stale installed libakerror.so cannot be silently paired with new headers.
+# 2.0.1 fixes the unhandled-error exit code, which reported success for any
+# status whose low byte was zero. It adds akerr_exit() but breaks nothing: the
+# soname is unchanged and no existing entry point changed shape.
+# 2.0.2 fixes the AKERR_USE_STDLIB=OFF build, which did not compile at all
+# (issue #12): untangles the header's includes, defines the AKERR_RUNTIME_HEADER
+# freestanding contract, retires PATH_MAX in favor of the AKERR_MAX_ERROR_FNAME_LENGTH
+# build option (default unchanged, so this is not an ABI break), and fails the
+# configure instead of the build when AKERR_THREADS would resolve to pthread
+# under AKERR_USE_STDLIB=OFF. ENSURE_ERROR_READY's pool-exhaustion path now
+# calls akerr_exit() instead of exit(1) directly, which changes that exit code
+# from 1 to AKERR_EXIT_STATUS_UNREPRESENTABLE (125) -- a deliberate behavior
+# change, not an ABI break: no soname move, no entry point changed shape.
+project(akerror VERSION 2.0.2 LANGUAGES C)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)

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