Refactor scan grouping

[tsalo]

Keeping as a draft for now.

Open issues

• DRBUDDI RPE.

Summary

Reorganizes QSIPrep's scan-grouping and field-map-selection code into SDCFlows-style value objects, without changing behavior. The previously monolithic qsiprep/utils/grouping.py is split into a clear pipeline and shrinks from 1725 → 1055 lines.

• New qsiprep/utils/fieldmaps.py (+217) mirroring sdcflows.fieldmaps: EstimatorType, MODALITIES, FieldmapFile (sibling discovery), and FieldmapEstimation (method inference, bids_id, and to_fieldmap_info() — the single place per-suffix field-map knowledge now lives).
• Slimmed grouping.py: DwiSeries → _final_distortion_groups → find_estimators (B0FieldIdentifier → IntendedFor →
  PE-heuristic) → _serialize_estimation_groups + build_fmap_application_groups, with group_dwi_scans reduced to a thin orchestrator.
• base.py adapter builds fieldmap_info via FieldmapEstimation.to_fieldmap_info() instead of re-deriving suffix typing.
• Deleted the post-hoc refine/remap dance (refine_distortion_groups, remap*) and the duplicated per-suffix helpers (classify_fmap_files, get_highest_priority_fieldmap, FMAP_PRIORITY, the legacy build_distortion_groups/build_fmap_estimation_groups and their helpers) — ~670 lines net removed.

Why it's safe (behavior preservation)

• Adds a golden/characterization suite (test_grouping_golden.py, 240 snapshots) frozen from the pre-refactor
  group-dwi-scans baseline, covering every fixture × combine_scans/ignore_fieldmaps/estimate_per_axis combo, including error cases. The new code reproduces it exactly and deterministically.
• For the trickiest edge cases (same-physical-signature multi-run DWIs with per-run field-map links via
  B0FieldSource/IntendedFor), the four-dict output was verified byte-identical to the pre-refactor baseline across all 8
  flag combos, locked by two dedicated fixtures.
• Also fixed pre-existing nondeterminism in three grouping error messages (Python set reprs reordered between runs), so the suite is stable.

Test plan

• pytest qsiprep/tests/test_grouping_golden.py qsiprep/tests/test_utils_grouping.py qsiprep/tests/test_utils_fieldmaps.py — all green.
• Full non-integration suite: 310 passed, 8 xfailed (the 4 test_interfaces_{dipy,freesurfer,mrtrix3} errors are
  pre-existing/unrelated).
• CircleCI integration jobs (forrest_gump, maternal_brain_project, drbuddi_*) — the end-to-end check that the
  preserved fieldmap_info drives the same workflows.

Notes

• One test is marked xfail: test_drbuddi_rpe_pair_collapses_to_single_output asserts an unimplemented DRBUDDI behavior (collapsing an opposite-PE DWI into its partner as an rpe_series field map). It fails identically on the pre-refactor baseline — not a regression, but a real feature gap worth a separate issue.
• fieldmaps.py intentionally mirrors sdcflows so a future offload of distortion correction becomes "add the dependency, delete our copy, delegate" rather than a rewrite.