medicallib_rust/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/ contains the crate root (src/lib.rs) and organ modules under src/organs/.
• Shared data types live in src/types.rs; domain errors in src/error.rs.
• FFI layer is src/ffi.rs with matching C header in ffi/medicallib.h; keep them aligned.
• Integration tests sit in tests/ (run cargo test --test patient to target a file).
• Usage and tracing demos live in examples/; the C example is in examples/c/.
• Performance benchmarks use Criterion in benches/ (see benches/heart.rs).
• Architectural and setup docs are at the repo root (README.md, ARCHITECTURE.md, INSTALL.md, MIGRATION.md).

Build, Test, and Development Commands

• cargo build compiles the library in debug mode for fast iteration.
• cargo build --release --features ffi produces the shared library for FFI consumers.
• cargo test runs the full test suite; append --test <name> for a single integration test.
• cargo run --example usage or cargo run --example tracing_demo exercises examples.
• cargo bench executes Criterion benchmarks; compare results across runs in target/criterion/.
• cargo clippy --all-targets -- -D warnings enforces lint hygiene before committing.

Coding Style & Naming Conventions

• Use cargo fmt --all (4-space indent, ~100-char lines) before sending patches.
• Modules and files use snake_case; types and traits use CamelCase; constants are SCREAMING_SNAKE_CASE.
• Favor standard library and existing crates; document any unsafe with clear safety notes.
• Keep public APIs cohesive within src/organs/; update examples/docs when the FFI surface changes.

Testing Guidelines

• Prefer integration coverage in tests/; create files named after features (e.g., tests/ffi.rs).
• Add focused unit tests near code under #[cfg(test)] for invariants.
• Ensure tests are deterministic; avoid sleeps or external I/O without guards.
• Run cargo test and cargo clippy locally before opening a PR.

Commit & Pull Request Guidelines

• Write imperative commit subjects (e.g., “Add heart rate update clamp”); Conventional Commits are welcome.
• PRs should link related issues, call out breaking changes, and mention new tests or examples.
• Include reproduction steps or screenshots only when they clarify user-facing changes.

Security & FFI Notes

• Any change to src/ffi.rs must be mirrored in ffi/medicallib.h and validated against examples/c/ffi_example.c.
• Avoid introducing new runtime dependencies; discuss first if unavoidable.