# Repository Guidelines

## Project Structure & Module Organization
- Core library lives in `src/`, organized by domain: `collection` (sample discovery), `pipes` and `runners` (pipeline orchestration), `callers` (tool interfaces), `annotation` and `variant` (VEP parsing, variant models), `commands` (external tool wrappers), `io`/`helpers`/`functions` (utilities), `modkit`, and `math`.
- `jq_filters/` holds jq modules used by the JSON post-processing examples in `README.md`.
- `pandora-config.example.toml` documents runtime settings; copy and adapt for local runs. Build outputs land in `target/`.

## Build, Test, and Development Commands
- `cargo build` — compile the library; ensure system deps like minimap2, samtools, dorado, bcftools, modkit, and VEP are available for runtime pipelines.
- `cargo test -- --nocapture` — run tests with stdout; set `RUST_LOG=debug` when debugging pipelines.
- `cargo fmt` and `cargo clippy -- -D warnings` — format and lint; run before sending a PR.
- `cargo doc --open` — generate local docs to understand module APIs.

## Coding Style & Naming Conventions
- Rust 2021 edition; use 4-space indentation and `snake_case` for functions/vars, `PascalCase` for types, `SCREAMING_SNAKE_CASE` for consts.
- Prefer `anyhow::Result` with the `?` operator; avoid `unwrap()` in pipeline code—propagate errors with context.
- Keep modules focused (e.g., orchestration in `runners`, IO logic in `io`, stats in `math`/`variant`). Add small comments when wiring external tools or Docker/Slurm behaviors.

## Testing Guidelines
- Existing integration tests expect access to shared test data at the path in `TEST_DIR` (see `src/lib.rs`). If unavailable, skip or point to local fixtures when adding new tests.
- Co-locate unit tests with their modules using Rust’s `#[cfg(test)]` blocks; name tests after the behavior under check (e.g., `loads_bam_metadata`, `filters_low_quality_variants`).
- Before proposing changes, run `cargo test` and note any environment-specific assumptions (e.g., tool availability, data paths).

## Commit & Pull Request Guidelines
- Commit messages are short and imperative (e.g., `add somatic stats export`, `fix dorado pod5 paths`).
- PRs should include: purpose, key changes, commands run (build/test), and any pipeline outputs or log snippets that validate tool integration.
- Document new external tool requirements or config keys in `README.md` and update `pandora-config.example.toml` when adding settings.
- Keep changes atomic: separate refactors from functional changes, and prefer small, reviewable diffs.