feat: expose nucleon number, atom mass, density and is-gas accessors (#119)

[grzanka]

Closes #119 · Phase A of the dedx_extra.c migration epic #118.

What

Promotes four previously-internal helpers to the public API in dedx.h, so frontends/bindings (notably the WASM web app) no longer need their own shims:

int   dedx_get_nucleon_number(int ion, int *err);      /* mass number A */
float dedx_get_atom_mass(int ion, int *err);           /* atomic mass, u */
float dedx_get_density(int material, int *err);        /* g/cm³ */
int   dedx_is_gas(int target, int *err);               /* 1 = gas, 0 = condensed/unknown */

The implementations already existed inside libdedx (dedx_internal_get_nucleon/_atom_mass in dedx_periodic_table.c, dedx_internal_read_density/_target_is_gas in dedx_data_access.c) — they just lacked a public header entry.

Why

dedx_web/wasm/dedx_extra.c re-exports exactly these four functions because they had no public declaration. This is the smallest, lowest-risk slice of the migration plan and lets the web side delete its shims. It also unblocks dedx_web #175 (display selected-material density) and #176 (custom density).

Notable detail — a latent out-of-bounds guard

dedx_internal_get_nucleon() / dedx_internal_get_atom_mass() only guard the upper bound (id < 113); for ion <= 0 they would index dedx_nucl[id-1] / dedx_amu[id-1] at a negative offset. The new public element accessors add the missing lower-bound check and return -1 with DEDX_ERR_NOT_AN_ELEMENT for out-of-range elements. dedx_get_density propagates DEDX_ERR_TARGET_NOT_FOUND for unknown materials; dedx_is_gas normalises the internal size_t to 0/1 and reports unknown targets as non-gas (documented).

This partially addresses the "bounds-check name/lookup accessors" item in the health-review epic #108.

Tests & docs

• tests/test_accessors.c (new, auto-registered by the test_*.c glob): valid values (H/He/C nucleon numbers and masses, water/air density, liquid-vs-gas), out-of-range guards (0, negative, 113, 200), and the unknown-material error path. Verified against the real embedded data: Carbon A=12 / 12.0107 u, water 1.0 g/cm³ (non-gas), air 1.205e-3 g/cm³ (gas).
• Short usage demo added to examples/dedx_list.c.

Verification

• ctest: 28/28 pass (27 existing + the new test).
• clang-format --Werror: clean on all changed files.
• clang-tidy (the CI config, WarningsAsErrors: '*'): no findings in the added code.

Open question for maintainers

Final function names — I followed the names proposed in #119 and the dedx_get_* convention. Happy to rename (e.g. dedx_get_ion_nucleon_number to match the web shim, or drop get_ for the predicate) if you prefer.

---

Authored via Claude Code as Phase A of the dedx_extra.c → libdedx migration.

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 88.09524% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.66%. Comparing base (335be0b) to head (7d2e906).

Files with missing lines	Patch %	Lines
tests/test_accessors.c	85.71%	6 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #124      +/-   ##
==========================================
+ Coverage   77.27%   77.66%   +0.38%     
==========================================
  Files          30       31       +1     
  Lines        3019     3103      +84     
  Branches      403      409       +6     
==========================================
+ Hits         2333     2410      +77     
- Misses        597      600       +3     
- Partials       89       93       +4     

☔ 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

This PR exposes four previously-internal material/ion property helpers as part of the public C API (include/dedx.h), to support downstream frontends/bindings (notably the WASM app) without local shims. It adds bounds-checking for element-table access and introduces a new test covering the new accessors, plus a short usage demo in an example.

Changes:

• Add public API declarations for nucleon number, atomic mass, density, and gas/condensed flag accessors.
• Implement the new public accessors in src/dedx.c, including lower-bound guards for element lookups.
• Add a new dedicated test (tests/test_accessors.c) and update examples/dedx_list.c with a usage snippet.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
include/dedx.h	Adds public declarations + Doxygen docs for the four new accessors.
src/dedx.c	Implements public wrappers and adds element-range guarding for mass/nucleon lookups.
tests/test_accessors.c	New test file validating correct values and error/sentinel behavior.
examples/dedx_list.c	Adds a short demo showing how to call the new accessors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[grzanka]

Addressed the review feedback in c70e206:

• Unsequenced *err writes in the example (3 comments). examples/dedx_list.c now reads each accessor result into a temporary before printing, so no single printf passes one &err to multiple calls.
• dedx_is_gas doc contract. Clarified in dedx.h that *err is always set to DEDX_OK — an unknown target is reported as non-gas, not as an error.
• Test contract. test_accessors.c now also asserts *err == DEDX_OK for the unknown-target is_gas case.

clang-format --Werror clean, ctest 28/28 pass, example output unchanged.

---

Generated by Claude Code