Add sam-stats command (port of ngsutils bam-stats)

[mbreese]

Summary

Adds a sam-stats command that prints summary statistics for SAM/BAM/CRAM files, porting the per-read logic from ngsutils bam-stats. Phase 1 — the --gtf gene-model and --bed on-target stats are intentionally deferred (they need an interval/region model that doesn't exist in cgkit yet).

Statistics reported

• Core counts: total / mapped / unmapped / multiple-mapped / uniquely-mapped
• Q30 pct, total bases, reference length, total depth (suppressed when gapped N alignments are present, matching the RNA-seq guard)
• [Flags] breakdown (non-zero bits only) and [References] per-chrom counts
• --tags NH:i,RG:Z,MAPQ value distributions with a missing bucket
• --calc-insert median, --rgid filter, --unique, --show-unmapped-ref, --cram-ref

Faithful to the Java semantics: unique detection is NH→IH→MAPQ, and only the first read of each pair is profiled (so total is intentionally lower than samtools flagstat's raw record count).

Also: usage-on-error fix (root)

SilenceUsage was set globally, so a missing argument printed only the bare error with no usage. Moved it into PersistentPreRun (which runs after Cobra validates args/flags but before RunE), so:

• Argument/flag errors → error + usage shown
• Execution errors (e.g. file not found) → error only

Also stopped double-printing the error in Execute() (Cobra already prints it). This applies uniformly to all commands.

Test plan

• go test ./... passes; go vet and gofmt clean
• New sam_stats_test.go covers counts, second-of-pair/unmapped handling, Q30, a --tags tally, --rgid filtering, and tag-spec parsing
• Cross-checked counts against samtools flagstat
• Manually verified missing-arg shows usage while runtime errors do not

🤖 Generated with Claude Code