Files

Add gcov code coverage to the test suite

scripts/coverage.py configures an instrumented build tree
(-DAKERR_COVERAGE=ON), runs the CTest suite in it, and reports merged
gcov line/branch/function coverage per library source. Like the mutation
harness it has no third-party dependencies and supports --threshold and
--junit; thresholds gate each file as well as the total so the generated
status-name table cannot mask a regression in src/error.c.

Only the library is instrumented. The public header's macros cannot be
measured this way -- GCC attributes an expanded macro to its call site,
so header logic would report as lines of the test that used it -- which
is what mutation testing against include/akerror.tmpl.h is for.

Coverage flags are applied per target rather than globally, so they do
not leak into the exported/installed target interface.

Current numbers for src/error.c are 94.0% line and 59.5% branch; the CI
gate is set to 90/50 to keep headroom, matching the convention used for
the mutation score threshold.

Tests run: ctest (23/23), cmake --build build --target coverage,
threshold gate verified failing at --threshold 99, cmake --install
checked for flag leakage, out-of-tree --build-dir checked.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-30 02:05:30 -04:00

3.1 KiB

Raw Blame History

Repository Guidelines

Project Structure & Module Organization

This is a small C library built with CMake. Core implementation lives in src/error.c. The public header is generated at build time from include/akerror.tmpl.h by scripts/generrno.sh, which also generates src/errno.c under the build directory. CMake package and pkg-config templates are in cmake/ and akerror.pc.in. Tests are one-file C programs in tests/; shared test helpers live beside them, such as tests/err_capture.h.

Build, Test, and Development Commands

Use an out-of-tree build:

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

cmake -S . -B build configures the build and generates akerror.h. cmake --build build compiles libakerror and test executables. ctest runs the registered unit tests. To emit CI-style results, use:

ctest --test-dir build --output-on-failure --output-junit "$(pwd)/ctest-junit.xml"

Mutation testing is available through:

cmake --build build --target mutation
scripts/mutation_test.py --target src/error.c --threshold 65

Code coverage is available through:

cmake --build build --target coverage
scripts/coverage.py --threshold 90 --branch-threshold 50

scripts/coverage.py configures its own instrumented build tree (default build/coverage, -DAKERR_COVERAGE=ON), runs the CTest suite there, and reports gcov line/branch coverage per library source. Thresholds gate each file as well as the total. Coverage measures src/error.c and the generated src/errno.c only; the public header's macros expand at their call sites, so mutation testing is what checks those.

Coding Style & Naming Conventions

Use C99-compatible C and follow the surrounding style. Functions and types use the akerr_ prefix; macros and constants use AKERR_ or all-caps macro names such as PREPARE_ERROR. Keep generated-code changes in templates or generator scripts, not in build outputs. Preserve concise comments for invariants, macro constraints, and non-obvious error lifecycle behavior.

Testing Guidelines

Add tests as tests/err_<behavior>.c. Register each new test in the AKERR_TESTS list in CMakeLists.txt; tests that intentionally abort must also be listed in AKERR_WILL_FAIL_TESTS. Prefer focused executable tests that return zero on success and use existing helpers such as AKERR_CHECK. Run the CTest suite before submitting changes, and run mutation testing and coverage when changing core control-flow, reference counting, stack-trace, or handler behavior.

Commit & Pull Request Guidelines

Recent commits use short, imperative, sentence-case subjects, for example Fix refcount leak and stack-trace buffer overflow. Keep commits focused and describe the observable behavior changed. Pull requests should include a brief summary, tests run, and any compatibility impact for public macros, generated headers, installation paths, or CMake/pkg-config consumers.

Agent-Specific Instructions

Do not overwrite uncommitted user changes. Avoid editing generated files in build/; update include/akerror.tmpl.h, src/error.c, CMake files, tests, or scripts instead.

3.1 KiB Raw Blame History