feat(bam): populate @pg header with PN/VN/CL fields

Per SAM spec §1.3, the @pg line conventionally carries PN (program name),
VN (version), and CL (command line) alongside ID. rustar was emitting
only ID:rustar-aligner, leaving downstream provenance tools (MultiQC's
program-version table, dx-toolkit lineage tracking) with a blank entry.

Expand the header writer to emit:
  @pg\tID:rustar-aligner\tPN:rustar-aligner\tVN:<cargo pkg version>\tCL:<args>

The full command line is captured in main() before clap parses it, then
threaded into Parameters via a new (skip) field so it reaches the SAM
header builder. Version comes from CARGO_PKG_VERSION at compile time.

This matches STAR's @pg format and gives downstream tools the provenance
they need.

Fixes #33 (the @pg header gap; AS divergence is a separate item).

Author: pinin4fjords

src/io/sam.rs

@@ -17,7 +17,7 @@ use noodles::sam::alignment::record_buf::data::field::value::Array;
 use noodles::sam::alignment::record_buf::{QualityScores, RecordBuf, Sequence};
 use noodles::sam::header::record::value::{
     Map,
-    map::{Program, ReadGroup, tag::Other as HeaderOtherTag},
+    map::{Program, ReadGroup, program::tag as program_tag, tag::Other as HeaderOtherTag},
 };
 use std::collections::HashSet;
 use std::fmt::Write as FmtWrite;
@@ -843,8 +843,23 @@ where
         builder = builder.add_read_group(id, map);
     }
 
-    // @PG line
-    builder = builder.add_program("rustar-aligner", Map::<Program>::default());
+    // @PG line. Per SAM spec §1.3, populate PN/VN/CL alongside ID so downstream
+    // provenance tools (MultiQC program-version table, etc.) see a fully
+    // populated record matching STAR's @PG format.
+    let mut pg = Map::<Program>::default();
+    pg.other_fields_mut()
+        .insert(program_tag::NAME, BString::from("rustar-aligner"));
+    pg.other_fields_mut().insert(
+        program_tag::VERSION,
+        BString::from(env!("CARGO_PKG_VERSION")),
+    );
+    let cl = params
+        .command_line
+        .clone()
+        .unwrap_or_else(|| "rustar-aligner".to_string());
+    pg.other_fields_mut()
+        .insert(program_tag::COMMAND_LINE, BString::from(cl));
+    builder = builder.add_program("rustar-aligner", pg);
 
     Ok(builder.build())
 }
@@ -1373,6 +1388,63 @@ mod tests {
         assert_eq!(header.reference_sequences().len(), 1);
     }
 
+    #[test]
+    fn test_build_sam_header_pg_line_populated() {
+        // The @PG line must carry PN, VN and CL alongside ID per SAM spec §1.3,
+        // so downstream provenance tools (MultiQC etc.) get a non-blank entry.
+        let genome = make_test_genome();
+        let mut params = Parameters::parse_from(vec!["rustar-aligner", "--readFilesIn", "test.fq"]);
+        params.command_line =
+            Some("rustar-aligner --readFilesIn test.fq --runThreadN 4".to_string());
+
+        let header = build_sam_header(&genome, &params).unwrap();
+        let programs = header.programs().as_ref();
+        let pg = programs
+            .get(&b"rustar-aligner"[..])
+            .expect("@PG line with ID:rustar-aligner must be present");
+
+        let pn: &[u8] = pg
+            .other_fields()
+            .get(&program_tag::NAME)
+            .expect("PN field must be present")
+            .as_ref();
+        assert_eq!(pn, b"rustar-aligner");
+
+        let vn: &[u8] = pg
+            .other_fields()
+            .get(&program_tag::VERSION)
+            .expect("VN field must be present")
+            .as_ref();
+        assert_eq!(vn, env!("CARGO_PKG_VERSION").as_bytes());
+
+        let cl: &[u8] = pg
+            .other_fields()
+            .get(&program_tag::COMMAND_LINE)
+            .expect("CL field must be present")
+            .as_ref();
+        assert!(!cl.is_empty(), "CL field must be non-empty");
+        assert_eq!(cl, b"rustar-aligner --readFilesIn test.fq --runThreadN 4");
+    }
+
+    #[test]
+    fn test_build_sam_header_pg_line_default_cl_when_unset() {
+        // When command_line is None (e.g. tests, library use), fall back to
+        // the program name so CL is still non-empty.
+        let genome = make_test_genome();
+        let params = Parameters::parse_from(vec!["rustar-aligner", "--readFilesIn", "test.fq"]);
+        assert!(params.command_line.is_none());
+
+        let header = build_sam_header(&genome, &params).unwrap();
+        let programs = header.programs().as_ref();
+        let pg = programs.get(&b"rustar-aligner"[..]).unwrap();
+        let cl: &[u8] = pg
+            .other_fields()
+            .get(&program_tag::COMMAND_LINE)
+            .expect("CL field must be present even when command_line is None")
+            .as_ref();
+        assert!(!cl.is_empty());
+    }
+
     #[test]
     fn test_build_sam_header_with_rg() {
         let genome = make_test_genome();

src/main.rs

@@ -8,6 +8,8 @@ fn main() -> anyhow::Result<()> {
 
     cpu::check_cpu_compat()?;
 
-    let params = Parameters::parse();
+    let command_line = std::env::args().collect::<Vec<_>>().join(" ");
+    let mut params = Parameters::parse();
+    params.command_line = Some(command_line);
     rustar_aligner::run(&params)
 }

src/params.rs

@@ -701,6 +701,13 @@ pub struct Parameters {
     /// Chimeric output type
     #[arg(long = "chimOutType", num_args = 1..=2, default_values_t = vec!["Junctions".to_string()])]
     pub chim_out_type: Vec<String>,
+
+    /// Full command line as invoked (captured in `main` before clap parsing).
+    /// Not a CLI argument; populated programmatically and embedded in the
+    /// BAM `@PG` `CL:` field for provenance. STAR captures the same string
+    /// in `P.commandLineFull`.
+    #[arg(skip)]
+    pub command_line: Option<String>,
 }
 
 impl Parameters {