Phase 0 of #149: docs and guards, no behaviour change

[grzanka]

Implements Phase 0 — "stop the bleeding" of the plan of action in #149: documentation fixes and defensive guards only, no change to any already-correct code path. Everything below is copied from the Phase 0 checklist in #149.

Changes

• D1 — dedx_get_program_list() / dedx_get_material_list() / dedx_get_ion_list() were documented (@return) as returning a 0-terminated array; they actually return a -1-terminated array (the implementation comments already agreed). Fixed the three doc lines. A consumer following the old docs would run off the end of every one of these arrays.

• B2 — dedx_internal_get_atom_charge() / get_atom_mass() / get_nucleon() in dedx_periodic_table.c only guarded the upper bound (id < 113). A caller-supplied id <= 0 (e.g. an unchecked custom-compound elements_id[] entry, which is never range-checked upstream) indexed dedx_amu[] / dedx_nucl[] out of bounds. Both bounds are now checked directly in the lookup functions.

• B4 — Added DEDX_ERROR_STRING_MAX (64) and documented it as the minimum buffer size dedx_get_error_code() requires; this was previously an undocumented "caller-allocated" buffer with no stated size.

• B5 — NULL-checked the calloc() in load_bethe_2(), the last unchecked allocation left in the library.

• B1 — dedx_internal_validate_config() now rejects a config with elements_id set but no elements_mass_fraction (and nothing to derive it from) with DEDX_ERR_INCONSISTENT_COMPOUND. Previously, a tabulated program (program < 100) with a non-zero target and a caller-supplied elements_id list skipped both branches that populate elements_mass_fraction, and dedx_load_config() reached load_compound()'s Bragg sum with a NULL weight array — a NULL dereference reachable from a plain public-API call.

• C5 — dedx_get_error_code() is now table-driven instead of a switch, so adding a new DEDX_ERR_* code can no longer silently desync from its message. This is exactly how DEDX_ERR_INCONSISTENT_COMPOUND (211) ended up with no message ("No such error code." instead of a real description) despite being defined and documented in dedx_error.h. The table now includes a message for it.

Tests

Regression tests are added for all five guard/behavior fixes:

• tests/test_validate_internal.c: dedx_internal_get_atom_charge/get_atom_mass/get_nucleon reject id <= 0 (B2), and the valid range is unaffected.
• tests/test_error_codes.c: the B1 NULL-deref reproducer now returns DEDX_ERR_INCONSISTENT_COMPOUND instead of crashing; a new test walks every DEDX_ERR_* code defined in dedx_error.h and asserts dedx_get_error_code() resolves it to a real message (C5), plus checks the unknown-code fallback still works.

I verified each new test actually catches the bug it targets by temporarily reverting each individual fix and re-running: B1's reverts to a segfault, B2's reverts to wrong error codes, C5's reverts to a missing message. All tests pass again with the fixes restored.

Full suite is green (32/32) both in a plain Debug build and under -fsanitize=address,undefined, including a standalone build/run of the B1 NULL-deref reproducer from the issue against the fixed library (confirmed no crash, err == DEDX_ERR_INCONSISTENT_COMPOUND).

Scope

Deliberately excludes everything from Phase 1 onward (warning flags/CI sanitizer job, the A1/A2/A5 correctness fixes, API contract changes, etc.) — those are separate, larger changes per the issue's own suggested split.

Closes nothing on its own; #149 stays open for the remaining phases.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.22%. Comparing base (d5bf0cd) to head (621dedc).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #150      +/-   ##
==========================================
+ Coverage   74.51%   78.22%   +3.71%     
==========================================
  Files          12       12              
  Lines        1711     1649      -62     
  Branches      317      320       +3     
==========================================
+ Hits         1275     1290      +15     
+ Misses        436      359      -77     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Phase 0 implementation of issue #149 focused on documentation corrections and defensive guards to prevent API-reachable memory-safety failures, with accompanying regression tests.

Changes:

• Correct public-header documentation for dedx_get_program_list(), dedx_get_material_list(), and dedx_get_ion_list() to reflect -1-terminated arrays.
• Add/strengthen guard rails to prevent out-of-bounds periodic-table lookups, a NULL-deref in compound loading, and an unchecked allocation in the Bethe path.
• Make dedx_get_error_code() table-driven (including a missing message for DEDX_ERR_INCONSISTENT_COMPOUND) and add tests ensuring every defined error code resolves to a real message.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_validate_internal.c	Adds regression coverage for rejecting non-positive periodic-table IDs while keeping valid IDs working.
tests/test_error_codes.c	Adds regression for the former NULL-deref path and verifies all DEDX_ERR_* codes map to real strings.
src/dedx.c	Replaces switch-based error string mapping with a table-driven approach; adds calloc NULL-check in load_bethe_2().
src/dedx_validate.c	Adds validation guard to reject inconsistent configs that would otherwise dereference a NULL weights array.
src/dedx_periodic_table.c	Adds lower-bound checks to prevent out-of-bounds indexing for id <= 0.
include/dedx.h	Documents required buffer size for dedx_get_error_code() and fixes list-terminator docs to -1.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.