feat(cli): parameter files, genome version check, and a shell-run readFilesCommand

[BenjaminDEMAILLE]

What this closes

Six of the STAR 2.7.11b names in NOT_YET_ACCEPTED, picked as the ones no open theme PR already owns (so this does not collide with #146, #147, #148, #149, #109, #116, #161, #165). Each is implemented, not merely accepted:

Parameter	Behaviour
--parametersFiles	STAR-format parameter files (name value..., # and // comments). Expanded before clap sees the arguments; a flag the user also passes on the command line is dropped from the file side, so the command line wins even for multi-value parameters, where clap would otherwise append. Unknown name, empty value, unreadable file, or a nested parametersFiles is fatal and names the file and line.
--versionGenome	genomeParameters.txt is checked before the index is read. Versions compare component-wise, so 2.7.10a sorts after 2.7.4a, which a string comparison (STAR's own) gets backwards. A missing version line is accepted with a warning.
--sysShell	Selects the shell for --readFilesCommand.
--readFilesCommand (fix)	Now runs through that shell. It previously spawned the whole string as one program name, so gunzip -c — the example in STAR's own documentation — failed as a missing program. Where no POSIX shell is guaranteed, the command is split into words instead. Paths are quoted.
--outFilterMismatchNoverReadLmax	Mismatch-to-read-length ratio, single-end and paired-end.
--alignTranscriptsPerReadNmax	Caps alignments per read before the score filters; transcripts are already best-first, so the cap keeps the best.
--alignSoftClipAtReferenceEnds	No rejects alignments whose soft clip would hang past a chromosome end. Validated to Yes/No.

Measured, not asserted

star_parameter_coverage_meets_the_floor counts the accepted names from clap and prints the figure: 184/203, 19 still missing. The floor is a test, so a regression that drops a parameter fails here rather than in a pipeline.

Testing

15 new tests: 8 for the parameter-file loader, 4 for the version check (including the lexical-ordering trap), 5 for the shell-run read command, and 3 end-to-end in tests/cli_surface.rs that align real reads and check the SAM. Each end-to-end test carries a control arm (permissive vs strict, uncapped vs capped, Yes vs No) so a filter that rejects everything cannot pass as a filter that works.

Whole suite, cargo clippy --all-targets -- -D warnings, and cargo fmt --check are green on a cold cache. A warm cargo cache does not replay diagnostics, which is how the clippy 1.98 breakage fixed in #236 went unnoticed locally.

One thing deliberately not fixed here

outFilterMismatchNoverLmax is applied to the read length in this codebase, where STAR applies it to the mapped length: issue #238. Changing that denominator moves the yeast benchmark and wants its own before/after measurement, so it is not bundled in. Until it is fixed, the two ratio parameters share a denominator.

What still remains of the port

Measured from the live lists at the time of writing, not from memory: 32 open issues, 28 open non-dependabot PRs, 19 STAR parameters still unaccepted.

The ten themes of #143 (P1 aligner-core faithfulness, P2 STARlong, P3 seed-batch perf, P4 solo barcode chemistry, P5 Transcript3p / CellReads.stats, P6 CLI parity, P7 SuperTranscriptome / RAM-aware SA, P8 chimeric multimapping, P9 parallel output, P10 CellRanger4 clipping) each have a PR open or, for P3, no work started. The remaining 19 parameters map onto those themes: chim* to P8, clip5pAdapter* to P10, genomeType / genomeTransformOutput / genomeSuffixLengthMax / sjdbInsertSave to P7, solo* to P4, alignEndsProtrude / alignInsertionFlush / seedSplitMin / seedNoneLociPerWindow to P1, winReadCoverageBasesMin to P2. Finishing the port is therefore gated on landing those PRs, not on new greenfield work.

🤖 Generated with Claude Code