[TEST] #61: BAM/CRAM parsing

[crashfrog]

Summary

Comprehensive acceptance test suite for BAM/CRAM parsing functionality (issue #61). Tests define the complete specification for parsing BAM and CRAM files using rust-htslib, extracting sequences with quality scores and metadata.

• 45 tests covering all acceptance criteria
• Tests organized by category: happy path, streaming, mapped/unmapped reads, indexed files, errors, edge cases
• Includes performance tests for large files and correctness tests matching samtools output
• All tests currently failing (RED phase) - implementation blocked by Core types and error handling #59 (Sequence type)

Test Coverage

Core Functionality

• Parse BAM/CRAM files and return Sequence iterator
• Extract read ID, bases, and Phred quality scores
• Handle descriptions from auxiliary tags

Streaming & Performance

• Lazy iterator (memory-efficient, not bulk loading)
• Partial consumption (can stop early)
• Empty file handling
• Large file performance (1M+ reads)

Mapped vs Unmapped Reads

• Extract original query sequence from mapped reads (ignore alignments)
• Ignore CIGAR strings during extraction
• Handle reverse-complemented reads correctly
• Support supplementary and secondary alignments
• Extract unmapped read sequences
• Handle mixed mapped/unmapped files

Indexed Files

• Detect and use .bai index for BAM files
• Detect and use .crai index for CRAM files
• Support non-indexed files (sequential fallback)
• Region queries (deferred to Phase 2, but index support tested)

Error Handling

• Reject nonexistent files with ParseError
• Reject non-BAM/CRAM files with clear error
• Handle truncated/corrupted files
• Validate headers
• CRAM: handle missing reference genome

Edge Cases

• Zero-length sequences
• Very long reads (50kb PacBio/Nanopore)
• Missing quality scores (reads with "*")
• Sequences with N bases
• Quality score validation (length matches sequence, valid Phred range)

Integration & Correctness

• Match samtools view output for BAM files
• Match samtools view output for CRAM files
• Illumina paired-end reads
• Nanopore long reads
• PacBio HiFi reads

Test Status

All 45 tests failing as expected:

cargo test --package phraya-io
test result: FAILED. 0 passed; 45 failed; 0 ignored

Each test uses todo!() with clear description of what needs implementation.

Blocked By

• Core types and error handling #59 (Core types and error handling) - needs Sequence type with id, bases, quality scores

Implementation Notes

Tests assume the following API design:

• parse_bam(path: &Path) -> Result<impl Iterator<Item = Result<Sequence>>, IoError>
• parse_cram(path: &Path, reference: Option<&Path>) -> Result<impl Iterator<Item = Result<Sequence>>, IoError>

Iterator returns Results per-record to allow graceful handling of individual bad records while continuing parsing.

Generated with Claude Code

[crashfrog]

Closing stale PR. Work has been superseded or merged via alternative approach.