Andrew Kesterson
437da2960b
Every wrapper outside the list and tree code was untested. Six new test
files close that, following the plan already written in TODO.md 1.2-1.6:
test_stream.c fopen/fread/fwrite/fclose -- happy paths, the round
trip, AKERR_EOF on a short read, AKERR_IO on a stream
opened in the wrong mode, ENOENT, and the NULL guards
test_format.c printf/fprintf/sprintf -- text *and* count asserted
(stdout is pointed at a temp file to check aksl_printf),
all eight NULL guards, EBADF on a read-only stream, and
512 variadic calls in a loop as sanitizer cover for the
missing va_end
test_convert.c ato{i,l,ll,f} happy paths, negatives, leading
whitespace, NULL guards
test_path.c realpath on a file and on a symlink, both compared
against realpath(3) since TMPDIR may itself be a link;
ENOENT, ENOTDIR, NULL path
test_strhash.c djb2 known-answer vectors, len == 0, embedded NUL,
stability, NULL guards
test_convert_strict.c
known-failing (2.1.5): the AKERR_VALUE / ERANGE
contract the ato* family cannot express today
test_tree.c gains the BFS AKERR_NOT_IMPLEMENTED contract, NULL arguments,
and a callback error that is not AKERR_ITERATOR_BREAK propagating out.
Tests deliberately say nothing about behaviour TODO.md records as
defective -- unchecked ptr/mode/resolved_path, short transfers reported as
success, *count left at -1, the djb2 sign extension -- so the eventual fix
does not have to come with a test rewrite. Each failure case in
test_path.c passes a zeroed buffer, because the wrapper's own error path
formats resolved_path with %s (2.1.6).
aksl_capture.h gains aksl_temp_file() with an atexit unlink backstop.
Without it every test that fails before its own unlink leaves temp files
behind -- which is the normal case for a known-failing test, and happens
173 times over in a mutation run.
Coverage on src/stdlib.c: 52.0% -> 99.0% of lines (200/202), 23.6% ->
51.0% of branches, 8/21 -> 21/21 functions. The two uncovered lines are
both `} HANDLE(e, AKERR_ITERATOR_BREAK) {`, where the macro starts with
the `break;` of PROCESS's `case 0:` arm -- reachable only via a non-NULL
error context whose status is zero, the pathology 2.2.1 exists to remove.
Mutation score on src/stdlib.c: 46.8% -> 89.6% (155/173 killed). CI, the
pre-push hook and the docs ratchet from 40 to 80 accordingly, and the 18
survivors are grouped by cause in TODO.md and README.md. A new CI
coverage job gates at 90% lines / 45% branches.
Verified:
ctest --test-dir build # 12/12
ctest --test-dir build-asan # 12/12 under ASan + UBSan
ctest --test-dir build-coverage # 14/14, report attached
ctest --test-dir build -j8 --repeat until-fail:3
gcc -Wall -Wextra -c on all nine test files # no warnings
python3 scripts/mutation_test.py --target src/stdlib.c # 89.6%
No temp files left in /tmp after any of the above.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.5 KiB
Repository Guidelines
Project Structure & Module Organization
libakstdlib is a C shared library that wraps libc calls and small data
structures in libakerror error contexts. Public API declarations live in
include/akstdlib.h; implementation lives in src/stdlib.c. Tests are
one-file CTest executables under tests/test_<name>.c, with shared test helpers
in tests/aksl_capture.h. CMake package templates are in cmake/ and
akstdlib.pc.in. The vendored dependency is deps/libakerror; update it as a
submodule rather than editing generated files under build/, build-asan/ or
build-coverage/.
Build, Test, and Development Commands
Initialize dependencies before a fresh build:
git submodule update --init --recursive
cmake -S . -B build
cmake --build build
Run the normal suite with ctest --test-dir build --output-on-failure. Use the
instrumented build for memory and undefined-behavior checks:
cmake -S . -B build-asan -DAKSL_SANITIZE=ON
cmake --build build-asan
ctest --test-dir build-asan --output-on-failure
For coverage, configure a third tree; the report is part of that suite (the
coverage_reset / coverage_report CTest entries) and also lands in
build-coverage/coverage-summary.txt:
cmake -S . -B build-coverage -DAKSL_COVERAGE=ON
cmake --build build-coverage --target coverage
Run cmake --build build --target mutation only when you need the slower
mutation harness. rebuild.sh installs to /home/andrew/local and removes the
local build directory, so treat it as a local convenience script.
Coding Style & Naming Conventions
Use C with 4-space indentation; existing files sometimes use tabs for continued
statements, so match the surrounding block. Public symbols use the aksl_
prefix, structs use aksl_<Name>, and tests use test_<feature>.c plus static
test_<case> functions. Preserve the akerr_ErrorContext AKERR_NOIGNORE *
return convention and the PREPARE_ERROR / FAIL_* / SUCCEED_RETURN pattern.
Testing Guidelines
Add a new test by creating tests/test_mything.c and adding mything to the
right list in CMakeLists.txt. AKSL_TESTS must exit zero.
AKSL_WILL_FAIL_TESTS are deliberate abort/contract tests.
AKSL_KNOWN_FAILING_TESTS assert documented defects from TODO.md; when one
starts unexpectedly passing, move it into AKSL_TESTS with the fix.
src/stdlib.c is at 99.0% line coverage and CI gates it at 90 (line) / 45
(branch), so new code needs tests in the same commit. Run
cmake --build build-coverage --target coverage and check the uncovered-line
listing before proposing a change. Tests for behaviour that TODO.md records as
defective belong in AKSL_KNOWN_FAILING_TESTS asserting the correct contract —
do not pin current-but-wrong behaviour in AKSL_TESTS, since that turns the
eventual fix into a test failure.
Commit & Pull Request Guidelines
Recent commits use short imperative summaries, for example Add memory wrapper tests and Make error-status assertions authoritative. Keep commits focused
and include tests with behavior changes. Pull requests should describe the
changed API or behavior, list the CTest/sanitizer/mutation commands run, and
link the relevant TODO.md item or issue when fixing a known defect.
Agent-Specific Instructions
Do not modify generated build trees, profiling artifacts, or untracked scratch
files unless explicitly asked. Prefer small, test-backed changes and update
README.md or TODO.md when changing documented workflows or known failures.