Merge pull request 'Test ignored-error storage across translation units' (#40) from 37 into main

Reviewed-on: #40
Reviewed-by: andrew <andrew@aklabs.net>

.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

CMakeLists.txt

@@ -18,7 +18,7 @@ cmake_minimum_required(VERSION 3.10)
 # 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)
+project(akerror VERSION 2.0.3 LANGUAGES C)
 
 include(GNUInstallDirs)
 include(CMakePackageConfigHelpers)
@@ -402,6 +402,22 @@ foreach(_test IN LISTS AKERR_TESTS)
     endif()
 endforeach()
 
+# The ignored-error slot is declared in the public header but must have one
+# library definition. Compare its address from two translation units, and
+# compile the consumer-facing test with all ordinary warnings enabled: a
+# header-local TLS definition would both duplicate storage and warn when unused.
+add_executable(test_err_ignore_multitu
+               tests/err_ignore_multitu.c
+               tests/err_ignore_multitu_helper.c)
+target_include_directories(test_err_ignore_multitu
+                           PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+target_link_libraries(test_err_ignore_multitu PRIVATE akerror)
+target_compile_options(test_err_ignore_multitu PRIVATE -Wall -Wextra -Werror)
+if(AKERR_THREAD_SAFE)
+    target_link_libraries(test_err_ignore_multitu PRIVATE Threads::Threads)
+endif()
+add_test(NAME err_ignore_multitu COMMAND test_err_ignore_multitu)
+
 # HANDLE_GROUP deliberately enters the next case label. Keep that public macro
 # compiling with the warning enabled, so a future macro edit cannot restore the
 # warning for consumers which adopt -Wextra.

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

UPGRADING.md

@@ -1,3 +1,13 @@
+# Release 2.0.3
+
+2.0.3 is a maintenance release with no public API or ABI changes. Compared
+with 2.0.2, the project now has:
+
+* AddressSanitizer and UndefinedBehaviorSanitizer coverage in CI, so the
+  regular test suite is exercised under both sanitizers.
+* A repeatable `--cmake-arg` option for `scripts/mutation_test.py`, allowing
+  mutation runs to cover alternate CMake configurations such as ThreadSanitizer.
+
 # Bug fix: the AKERR_USE_STDLIB=OFF build, and a pool-exhaustion exit code (2.0.2)
 
 `-DAKERR_USE_STDLIB=OFF` did not compile at all ([issue #12](https://source.starfort.tech/andrew/libakerror/issues/12)):

include/akerror.tmpl.h

@@ -216,7 +216,7 @@ extern akerr_ErrorLogFunction akerr_log_method;
  * after the pool slot is reused. The snapshot is read-only and is replaced by
  * the next ignored error. Thread local only when AKERR_THREAD_SAFE is 1.
  */
-static AKERR_THREAD_LOCAL akerr_ErrorContext akerr_last_ignored;
+extern AKERR_THREAD_LOCAL akerr_ErrorContext akerr_last_ignored;
 
 /*
  * Drop one reference, returning NULL once the last one is gone so the caller can

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()

src/error.c

@@ -28,6 +28,7 @@
  * template header because the macro copies into it at the call site.
  */
 static AKERR_THREAD_LOCAL akerr_ErrorContext __akerr_last_ditch;
+AKERR_THREAD_LOCAL akerr_ErrorContext akerr_last_ignored;
 akerr_ErrorUnhandledErrorHandler akerr_handler_unhandled_error;
 akerr_ErrorLogFunction akerr_log_method = NULL;
 

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
+Useful flags: `--cmake-arg ARG` (pass a CMake configure argument to every
-hangs is counted as killed), `--keep` (retain the scratch copy for debugging),
+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).
 

tests/err_ignore_multitu.c

@@ -0,0 +1,18 @@
+#include "akerror.h"
+#include "err_ignore_multitu.h"
+#include <stdio.h>
+
+int main(void)
+{
+    akerr_ErrorContext *main_address = &akerr_last_ignored;
+    akerr_ErrorContext *helper_address = akerr_multitu_snapshot_address();
+
+    if ( main_address != helper_address ) {
+	fprintf(stderr,
+		"CHECK FAILED: ignored-error storage differs between translation units\n");
+	return 1;
+    }
+
+    fprintf(stderr, "err_ignore_multitu ok\n");
+    return 0;
+}

tests/err_ignore_multitu.h

@@ -0,0 +1,8 @@
+#ifndef AKERR_TEST_IGNORE_MULTITU_H
+#define AKERR_TEST_IGNORE_MULTITU_H
+
+#include "akerror.h"
+
+akerr_ErrorContext *akerr_multitu_snapshot_address(void);
+
+#endif

tests/err_ignore_multitu_helper.c

@@ -0,0 +1,6 @@
+#include "err_ignore_multitu.h"
+
+akerr_ErrorContext *akerr_multitu_snapshot_address(void)
+{
+    return &akerr_last_ignored;
+}