# Repository Guidelines
Kractor is a Rust CLI for extracting FASTQ/FASTA reads using Kraken2 classifications. Follow the guidance below to keep contributions aligned with the existing codebase.
## Project Structure & Module Organization
- `src/main.rs` wires CLI options into the core extraction logic in `src/kractor.rs`.
- Parsers for Kraken reports and FASTX streams live under `src/parsers/`, with shared helpers in `mod.rs`.
- Streaming and IO helpers for file extraction are in `src/extract.rs`; CLI argument parsing is in `src/cli.rs`.
- Benchmarks and profiling notes reside in `benchmarks/`, alongside reference charts in `benchmarks/img/`.
- Release artifacts land in `target/` (ignored by git) after builds; keep large sample data outside the repo.
## Build, Test, and Development Commands
- `cargo build` compiles the binary; use `cargo build --release` before benchmarking or packaging.
- `cargo run -- --help` prints the CLI usage; add new flags here before documenting them.
- `cargo fmt` applies the enforced rustfmt style; run before opening a PR.
- `cargo clippy --all-targets --all-features` surfaces lint regressions that CI enforces.
- `cargo test` runs unit tests embedded alongside modules; add coverage for new code paths.
## Coding Style & Naming Conventions
Adopt Rust 2021 idioms: prefer explicit `use` paths, `?` for error propagation, and `Result<T>` returns. Files and modules use `snake_case`; exported CLI flags stay kebab-case (e.g., `--output-fasta`). Keep functions focused and document non-obvious invariants with `///` rustdoc comments. Avoid unwraps in production paths; prefer `color_eyre` contexts for diagnostics.
## Testing Guidelines
Place module tests in the same file under `#[cfg(test)]`, mirroring patterns in `src/parsers/fastx.rs`. Name tests after the behaviour under check (`extract_reads_includes_children`). For CLI features, add integration-like tests in `tests/` if behaviour spans modules; create the directory if needed. Run `cargo test -- --nocapture` when debugging streams, and attach benchmark notes to `benchmarks/benchmarks.md` instead of test logs.
## Commit & Pull Request Guidelines
Follow the Conventional Commits style seen in history (`docs(readme): update DOI links`). Each PR should describe motivation, list affected commands, and reference related issues. Include CLI samples, expected output changes, and screenshots when altering docs or UX. Confirm `cargo fmt`, `cargo clippy`, and `cargo test` all pass locally, and mention that verification in the PR checklist.
