test(clip): port missing fgbio SamRecordClipper and ClipBam tests

[nh13]

Follows #1015 (merged).

#1015's bugs got through because none of fgbio's SamRecordClipperTest / ClipBamTest cases cover overlap clipping with a far-end soft clip, soft-with-mask overlap clipping, or empty SEQ. That prompted an audit of how completely those two suites were ported. Every fgbio case was re-run against fgumi with fgbio's exact inputs and expectations, and fgumi met all of them, so this PR is test coverage plus cleanup with no change in output.

fgbio suite	cases	already equivalent	weaker in fgumi	missing
SamRecordClipperTest	82	44	8	30
ClipBamTest	24	3	11	10

Changes

• Port the weaker/missing cases into fgbio_sam_record_clipper_tests (clipper.rs, 69 tests) and fgbio_clip_bam_tests (clip.rs, 31 tests). Each cites its fgbio source line, with fgbio's expected values copied unchanged. Notable gaps closed:
  • all 12 clipExtendingPastMateEnds cases;
  • hard-mode overlap clipping with soft clips and deletions;
  • clip{Start,End}OfRead and clip{5,3}PrimeEndOfRead;
  • ClipBam's end-to-end metric values, mate info and NM/UQ/MD;
  • --upgrade-clipping across mode pairs.
• Fixture-only deviations are documented on the affected tests:
  • ClipBamTest.scala:182's SEQ is resized to match its hard-clipped CIGAR, because fgbio's fixture is malformed.
  • numBasesExtendingPastMate is exercised through the MC-based num_bases_extending_past_mate_raw.
• Stricter tag assertions: 28 existing clipper tests asserted tag values inside if let Some(Value::...), so a missing tag silently passed. They now panic instead.
• Cleanup:
  • clip_{start,end}_of_read_raw share the clipping_at_end_raw helper added in fix(clip): upgrade soft clips only at the mate-facing end when clipping overlaps #1015.
  • Comments that pointed at the removed typed SamRecordClipper now cite fgbio.
  • The clip_template_records comment no longer claims the per-read helpers never upgrade clipping.
  • The strand-normalization overlap tests also run in soft-with-mask mode.

Not addressed

• clip_start_of_alignment / clip_end_of_alignment still leave an empty-SEQ (*) record's alignment unclipped, whereas fgbio clips the CIGAR. Since fix(clip): upgrade soft clips only at the mate-facing end when clipping overlaps #1015 the read-end helpers at least upgrade the existing soft clip at that end. No fgbio test reaches this.
• Some pre-existing fgumi overlap tests still assert only > 0 (_with_multiple_insertions, _insertion_at_overlap_boundary, _complex_cigar, _soft_with_mask). The ported fgbio table now pins the same behavior exactly.

Mutation check

Corrupting one expected value in each of three new tests fails exactly those three.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: fulcrumgenomics/fgumi/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Essentials
• Run ID: dd57c585-1dc7-40e7-b893-49b5217e9d3d

📥 Commits

Reviewing files that changed from the base of the PR and between 7b02a4c and 5c14575.

📒 Files selected for processing (2)

• crates/fgumi-sam/src/clipper.rs
• src/lib/commands/clip.rs

Included review availability: This review used your included allowance. 2 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

⚠️ A high-level summary could not be generated for this review. CodeRabbit will regenerate it on the next update, or you can request a refresh with @coderabbitai summary.

Walkthrough

The pull request reuses a shared helper to count existing raw end clips and adds fgbio-derived tests for raw and command-level clipping. Tests also require clipping-related tags to exist with expected types and cover clipping outputs, mate fields, regenerated tags, metrics, and unmapped reads.

Changes

Read clipping

Layer / File(s)	Summary
Raw clipper helpers and coverage crates/fgumi-sam/src/clipper.rs	Raw start and end clipping use a shared helper to count existing clips. Test adapters and fgbio-derived cases cover read-end, alignment, overlap, and past-mate clipping. Strand-normalization tests now include SoftWithMask.
Clipping attribute assertions crates/fgumi-sam/src/clipper.rs	Clipping tests now fail when expected tags are missing or have the wrong type, rather than skipping value checks.
Pair and fragment clipping src/lib/commands/clip.rs	Command tests cover overlap and fixed clipping, clipping metrics, paired-read output and mate fields, regenerated tags, and fragment output.
Clipping upgrades and mate extension src/lib/commands/clip.rs	Command tests cover clipping-mode upgrades, reads extending past their mates, and clipping requests that leave reads unmapped. A comment clarifies the scope of the template-wide upgrade pass.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~30 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 5c145

The clipping changes add tests and clarify a comment; no issue requiring correction before merge was identified.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses the required conventional-commit format, names the affected clipping scope, and describes the test-porting change with a lowercase imperative description.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[nh13]

@coderabbitai pause

[coderabbitai]

✅ Action performed

Reviews paused.

[codecov]

Codecov Report

❌ Patch coverage is 95.20807% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.44%. Comparing base (1b203b1) to head (5c14575).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/fgumi-sam/src/clipper.rs	88.47%	31 Missing ⚠️
src/lib/commands/clip.rs	98.66%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1018      +/-   ##
==========================================
+ Coverage   96.43%   96.44%   +0.01%     
==========================================
  Files         299      299              
  Lines      151289   152039     +750     
==========================================
+ Hits       145894   146634     +740     
- Misses       5395     5405      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nh13]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Head commit changed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.