seqair: Instructions file for Claude Code

seqair

Pure-Rust BAM/SAM/CRAM/FASTA reader + pileup engine. I/O backend for rastair.

Workspace: crates/seqair (readers, pileup, BGZF, CRAM) and crates/seqair-types (Base, BaseQuality, MappingQuality, ModProbability, Strand, Phred, Probability, RmsAccumulator, RegionString, Pos/QPos).

Tracey specs

Specs in docs/spec/*.md with r[rule.id]. Code: // r[impl rule.id], tests: // r[verify rule.id]. Use the tracey skill. Add spec rules before implementing; update specs when changing behavior.

Coding style

Expert Rust. Modern idioms. Types are the primary abstraction.

• Correctness and clarity first. Comments explain "why" only.
• No mod.rs — use src/some_module.rs.
• No unwrap() — propagate with ?.
• No indexing — use .get(). If indexing is unavoidable, #[allow(clippy::indexing_slicing)] + debug_assert!.
• No let _ = on fallible ops — propagate, log with warn!, or handle.
• No from_utf8_lossy — use from_utf8()? with typed errors.
• Error enums: one per module, typed fields only (never String), #[from] for wrapping. Never use io::Error::other("message") — add a typed variant instead. Hierarchy: BgzfError → BamHeaderError/BaiError → BamError; BamWriteError (parallel to BamError for the write path); FaiError/GziError → FastaError; FormatDetectionError → ReaderError; VcfHeaderError/VcfEncodeError/AllelesError → VcfError.
• color_eyre for errors, tracing for logging.
• Sequence names are SmolStr.
• Tests: prefer cargo nextest run (parallel test-binary execution; ~8× faster than cargo test on this repo, config in .config/nextest.toml). Doctests aren't run by nextest — append cargo test --doc --quiet when you need to cover them. Prefer property-based tests with hegel (hegeltest) where applicable: #[hegel::test] fn f(tc: TestCase) with tc.draw(gs::..), #[hegel::composite] for custom generators, plain assert!/assert_eq!, tc.assume(..) to reject a case. Case counts live in hegel.toml; pin an expensive test with #[hegel::test(test_cases = crate::pinned::cases(N))] (integration tests add #[path = "../src/pinned.rs"] mod pinned;) so SEQAIR_PINNED_CASES=N can still override it — a bare test_cases = N beats HEGEL_TEST_CASES. Prefer constructing inputs in the shape you need over rejecting them — a rejection loop makes hegel's smallest generated input large and its shrinking useless. Round-trip tests against noodles and bcftools are the strongest validation — always add them for new output formats. Avoid tautological tests — don't verify code using a copy of the same logic (e.g., compute expected bin with the same reg2bin). Use independent oracles. For tests that write temp files (e.g., bcftools round-trips), use the tempfile crate (tempfile::NamedTempFile) rather than std::env::temp_dir().join(...) to avoid filename collisions under parallel test execution.
• SmallVec in this project uses 2-arg form SmallVec<T, N> (not SmallVec<[T; N]>).
• No silent as i32/as u32 truncation at serialization boundaries — use i32::try_from() or equivalent with typed errors. At allocation boundaries (parsing untrusted counts), apply practical upper bounds matching real-world data, not format maximums (i32::MAX is not a limit). See r[io.writer_limits] and r[io.fuzz.alloc_limits] in the general spec.