test: add diff_star_transcriptome.sh — byte-for-byte parity script

Generates a deterministic 2-chr / 4-transcript / 4-gene synthetic test
case, runs both STAR and ruSTAR genomeGenerate, then diffs each of the
9 files byte-for-byte.

Current result on STAR 2.7.11b: 9/9 files identical
  * chrName.txt, chrLength.txt, chrStart.txt, chrNameLength.txt
  * transcriptInfo.tab, exonInfo.tab, geneInfo.tab,
    exonGeTrInfo.tab, sjdbList.fromGTF.out.tab

Runnable via:
  RUSTAR_BIN=/path/to/target/release/ruSTAR \\
    test/diff_star_transcriptome.sh /tmp/workdir

Reports with ✓/✗ per file and exits non-zero if any file differs.

Requires STAR on PATH (`brew install rna-star` or bioconda star).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ewels

test/diff_star_transcriptome.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Byte-for-byte diff of ruSTAR vs STAR for the transcriptome index files
+# written at genomeGenerate time.
+#
+# Usage: ./diff_star_transcriptome.sh [WORKDIR]
+#
+# Generates a synthetic 2-chr / 4-transcript / 4-gene test case, runs both
+# ruSTAR and STAR genomeGenerate, then diffs each output file byte-for-byte.
+#
+# Requires STAR on PATH (`brew install rna-star`, bioconda star, etc.).
+# ruSTAR must already be built — the script expects `target/debug/ruSTAR`
+# in the repo root (or $RUSTAR_BIN set to a compiled binary).
+
+set -euo pipefail
+
+WORKDIR="${1:-/tmp/rustar_diff}"
+RUSTAR_BIN="${RUSTAR_BIN:-$(pwd)/target/debug/ruSTAR}"
+
+if [[ ! -x "$RUSTAR_BIN" ]]; then
+    echo "ERROR: ruSTAR binary not found at $RUSTAR_BIN"
+    echo "Build with: cargo build (or set RUSTAR_BIN=/path/to/ruSTAR)"
+    exit 1
+fi
+
+if ! command -v STAR >/dev/null 2>&1; then
+    echo "ERROR: STAR not on PATH. Install via 'brew install rna-star' or bioconda."
+    exit 1
+fi
+
+mkdir -p "$WORKDIR"
+cd "$WORKDIR"
+
+# Deterministic test case.
+python3 - <<'PYEOF'
+BASES = "ACGT"
+def lcg(seed, length):
+    state = seed & 0xFFFFFFFF
+    out = []
+    for _ in range(length):
+        state = (state * 1103515245 + 12345) & 0xFFFFFFFF
+        out.append(BASES[(state >> 16) & 3])
+    return "".join(out)
+
+CHR1 = lcg(11111, 3000)
+CHR2 = lcg(22222, 3000)
+
+with open("genome.fa", "w") as f:
+    f.write(">chr1\n")
+    for i in range(0, len(CHR1), 60): f.write(CHR1[i:i+60] + "\n")
+    f.write(">chr2\n")
+    for i in range(0, len(CHR2), 60): f.write(CHR2[i:i+60] + "\n")
+
+with open("annotations.gtf", "w") as f:
+    f.write('chr1\ttest\texon\t101\t400\t.\t+\t.\tgene_id "G1"; transcript_id "T1";\n')
+    f.write('chr1\ttest\texon\t501\t600\t.\t+\t.\tgene_id "G2"; transcript_id "T2"; gene_name "GENE2";\n')
+    f.write('chr1\ttest\texon\t701\t800\t.\t+\t.\tgene_id "G2"; transcript_id "T2"; gene_name "GENE2";\n')
+    f.write('chr1\ttest\texon\t901\t1000\t.\t+\t.\tgene_id "G2"; transcript_id "T2"; gene_name "GENE2";\n')
+    f.write('chr2\ttest\texon\t301\t600\t.\t-\t.\tgene_id "G3"; transcript_id "T3"; gene_biotype "protein_coding";\n')
+    f.write('chr2\ttest\texon\t1001\t1100\t.\t+\t.\tgene_id "G4"; transcript_id "T4";\n')
+    f.write('chr2\ttest\texon\t1301\t1400\t.\t+\t.\tgene_id "G4"; transcript_id "T4";\n')
+PYEOF
+
+# STAR genomeGenerate.
+rm -rf star_index
+mkdir star_index
+STAR --runMode genomeGenerate --genomeDir star_index \
+     --genomeFastaFiles genome.fa --sjdbGTFfile annotations.gtf \
+     --genomeSAindexNbases 5 --sjdbOverhang 49 --runThreadN 1 >/dev/null 2>&1
+
+# ruSTAR genomeGenerate.
+rm -rf rustar_index
+"$RUSTAR_BIN" --runMode genomeGenerate --genomeDir rustar_index \
+     --genomeFastaFiles genome.fa --sjdbGTFfile annotations.gtf \
+     --genomeSAindexNbases 5 --sjdbOverhang 49 --runThreadN 1 >/dev/null 2>&1
+
+# Diff each file.
+pass=0
+fail=0
+for f in chrName.txt chrLength.txt chrStart.txt chrNameLength.txt \
+         transcriptInfo.tab exonInfo.tab geneInfo.tab exonGeTrInfo.tab \
+         sjdbList.fromGTF.out.tab; do
+    if diff -q "star_index/$f" "rustar_index/$f" >/dev/null 2>&1; then
+        echo "✓ $f"
+        pass=$((pass+1))
+    else
+        echo "✗ $f DIFFERS"
+        diff "star_index/$f" "rustar_index/$f" | head -20
+        fail=$((fail+1))
+    fi
+done
+
+echo
+echo "RESULT: $pass/$((pass+fail)) files identical to STAR's output"
+if [[ $fail -gt 0 ]]; then
+    exit 1
+fi