Version at 0.2.0: complete the wishlist, document it, gate the docs

Closes what was left of TODO.md sections 1, 2 and 3, and rewrites that
file to hold outstanding items only.

The API break gets a minor bump, because pre-1.0 the soname carries
MAJOR.MINOR and 0.1 and 0.2 are therefore different ABIs. Five
signatures changed and the ato* contract with them; UPGRADING.md is new
and lists every one, with the before/after for the cases the compiler
cannot warn about.

Section 3.1 is finished: reallocarray with the multiplication checked,
aligned_alloc and posix_memalign, asprintf/vasprintf, scanf/vscanf.
Four functions on that list are deliberately absent rather than missing
-- sprintf, strtok, setbuf and perror -- and TODO.md now says which and
why, so nobody adds them thinking they were forgotten.

Section 1.9, the cross-cutting tests:

  tests/test_pool.c    drives every failure path AKERR_MAX_ARRAY_ERROR
                       + 10 times and checks the pool after each round,
                       because a wrapper that leaks a slot fails a
                       hundred calls later in unrelated code. It also
                       asserts that each error names the function and
                       file it was raised from, which is what catches a
                       FAIL that migrates into a helper during a
                       refactor: status right, message right, origin
                       quietly lying.
  tests/negative/      two sources that must FAIL to compile, built with
                       -Werror and registered WILL_FAIL. AKERR_NOIGNORE
                       and the format attributes are enforced by the
                       compiler and by nothing else; drop either and
                       every ordinary test still passes.

Thread safety is answered rather than tested: the library is not
thread-safe and cannot be made so from here, because libakerror's error
pool is an unlocked process-global array. README.md says so plainly and
TODO.md carries it as the item blocking any future pthread wrappers.

Doxygen is configured and gated. All 147 public functions have @brief,
a @param each, @throws per status and @return; EXTRACT_ALL is off and
WARN_NO_PARAMDOC on, so `cmake --build build --target docs` fails on an
undocumented entity. It ran to 0 warnings. The Doxyfile carries no
version -- cmake/RunDoxygen.cmake feeds PROJECT_NUMBER in from
project(), so that stays the one place a version is written.

CI now builds against the submodule it pins instead of also installing
libakerror@main and never linking it, adds -Werror, and gains a
sanitizer job. The pre-push hook matches, and runs the docs check too.

Coverage: 99.5% of lines (1643/1651), 100% of functions (147/147). The
eight uncovered lines are each uncovered on purpose and TODO.md says
which and why.

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

tests/test_memory.c

@@ -121,6 +121,84 @@ static int test_realloc_grows_and_preserves_the_old_block_on_failure(void)
     return 0;
 }
 
+/*
+ * reallocarray's whole reason for existing: `realloc(p, n * size)` is a heap
+ * overflow waiting for an n large enough to wrap, and the multiplication is the
+ * place a caller does not think to look.
+ */
+static int test_reallocarray_checks_the_multiplication(void)
+{
+    void *ptr = NULL;
+    unsigned char *buf = NULL;
+    size_t i = 0;
+
+    AKSL_CHECK_OK(aksl_malloc(4, &ptr));
+    AKSL_CHECK_OK(aksl_reallocarray(&ptr, 16, 8));
+    buf = (unsigned char *)ptr;
+    for ( i = 0; i < 128; i++ ) {
+	buf[i] = (unsigned char)i;
+    }
+    AKSL_CHECK_OK(aksl_free(ptr));
+
+    ptr = NULL;
+    /* SIZE_MAX/4 members of 8 bytes wraps; without the check this would be a
+     * plausible-looking small allocation followed by a very large write. */
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_reallocarray(&ptr, SIZE_MAX / 4, 8),
+				   AKERR_OUTOFBOUNDS, "overflows size_t");
+    AKSL_CHECK(ptr == NULL);
+
+    AKSL_CHECK_STATUS(aksl_reallocarray(NULL, 1, 1), AKERR_NULLPOINTER);
+    AKSL_CHECK_STATUS(aksl_reallocarray(&ptr, 0, 1), AKERR_VALUE);
+    AKSL_CHECK_STATUS(aksl_reallocarray(&ptr, 1, 0), AKERR_VALUE);
+    return 0;
+}
+
+/*
+ * aligned_alloc(3) requires size to be a multiple of the alignment and the
+ * alignment to be a power of two. Violating either is undefined behaviour that
+ * usually just returns NULL, so both are checked and reported as what they are.
+ */
+static int test_aligned_alloc_checks_its_preconditions(void)
+{
+    void *ptr = (void *)0x1;
+
+    AKSL_CHECK_OK(aksl_aligned_alloc(64, 128, &ptr));
+    AKSL_CHECK(ptr != NULL);
+    AKSL_CHECK(((uintptr_t)ptr % 64) == 0);
+    AKSL_CHECK_OK(aksl_free(ptr));
+
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_aligned_alloc(24, 48, &ptr),
+				   AKERR_VALUE, "not a power of two");
+    AKSL_CHECK(ptr == NULL);
+    AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_aligned_alloc(64, 100, &ptr),
+				   AKERR_VALUE, "not a multiple of alignment");
+    AKSL_CHECK_STATUS(aksl_aligned_alloc(0, 64, &ptr), AKERR_VALUE);
+    AKSL_CHECK_STATUS(aksl_aligned_alloc(64, 0, &ptr), AKERR_VALUE);
+    AKSL_CHECK_STATUS(aksl_aligned_alloc(64, 128, NULL), AKERR_NULLPOINTER);
+    return 0;
+}
+
+/*
+ * posix_memalign(3) breaks the errno convention: it returns the error number and
+ * leaves errno alone. The wrapper reports it as a status like everything else.
+ */
+static int test_posix_memalign(void)
+{
+    void *ptr = (void *)0x1;
+
+    AKSL_CHECK_OK(aksl_posix_memalign(&ptr, sizeof(void *) * 2, 100));
+    AKSL_CHECK(ptr != NULL);
+    AKSL_CHECK(((uintptr_t)ptr % (sizeof(void *) * 2)) == 0);
+    AKSL_CHECK_OK(aksl_free(ptr));
+
+    /* Not a multiple of sizeof(void *), which posix_memalign refuses. */
+    AKSL_CHECK_STATUS(aksl_posix_memalign(&ptr, 3, 100), EINVAL);
+    AKSL_CHECK(ptr == NULL);
+    AKSL_CHECK_STATUS(aksl_posix_memalign(NULL, 16, 100), AKERR_NULLPOINTER);
+    AKSL_CHECK_STATUS(aksl_posix_memalign(&ptr, 16, 0), AKERR_VALUE);
+    return 0;
+}
+
 static int test_free_rejects_null_pointer(void)
 {
     AKSL_CHECK_STATUS_MSG_CONTAINS(aksl_free(NULL),
@@ -324,6 +402,9 @@ int main(void)
     AKSL_RUN(failures, test_malloc_free_round_trip);
 
     AKSL_RUN(failures, test_calloc_zeroes_and_guards);
+    AKSL_RUN(failures, test_reallocarray_checks_the_multiplication);
+    AKSL_RUN(failures, test_aligned_alloc_checks_its_preconditions);
+    AKSL_RUN(failures, test_posix_memalign);
     AKSL_RUN(failures, test_realloc_grows_and_preserves_the_old_block_on_failure);
 
     AKSL_RUN(failures, test_free_rejects_null_pointer);