ref-solver 0.3.0

Solve reference genome identification from BAM/SAM headers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Command-line interface for ref-solver.
//!
//! This module implements the CLI using clap. Available commands:
//!
//! - **identify**: Identify the reference genome from a BAM/SAM/CRAM file
//! - **compare**: Compare two headers or a header against a known reference
//! - **catalog**: List, show, or export references from the catalog
//! - **serve**: Start the interactive web interface
//!
//! ## Usage
//!
//! ```text
//! # Identify reference from a BAM file
//! ref-solver identify sample.bam
//!
//! # Pipe from samtools
//! samtools view -H sample.bam | ref-solver identify -
//!
//! # JSON output for scripting
//! ref-solver identify sample.bam --format json
//!
//! # Compare against a known reference
//! ref-solver compare sample.bam hg38_ucsc --reference
//!
//! # Start web UI
//! ref-solver serve --port 8080 --open
//! ```

use clap::{Parser, Subcommand};

pub mod catalog;
pub mod compare;
pub mod identify;
pub mod score;

#[derive(Parser)]
#[command(name = "ref-solver")]
#[command(author = "Fulcrum Genomics")]
#[command(version)]
#[command(about = "Identify and match reference genomes from BAM/SAM headers")]
#[command(
    long_about = "ref-solver helps you identify which reference genome was used to align a BAM/SAM/CRAM file.\n\nIt matches the sequence dictionary from your file against a catalog of known human reference genomes and provides:\n- Exact matches when possible\n- Detailed diagnostics when differences exist\n- Actionable suggestions for fixing mismatches (renaming, reordering)"
)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,

    /// Enable verbose output
    #[arg(short, long, global = true)]
    pub verbose: bool,

    /// Output format
    #[arg(short, long, global = true, default_value = "text")]
    pub format: OutputFormat,
}

#[derive(Subcommand)]
#[allow(clippy::large_enum_variant)]
pub enum Commands {
    /// Identify the reference genome used in a BAM/SAM file
    Identify(identify::IdentifyArgs),

    /// Compare two headers or references
    Compare(compare::CompareArgs),

    /// Score a query file against a reference file directly (no catalog).
    /// By default, scoring is asymmetric: it measures how well the query
    /// matches the reference. Use --symmetric to compute both directions.
    Score(score::ScoreArgs),

    /// Manage the reference catalog
    Catalog(catalog::CatalogArgs),

    /// Start the web server
    Serve(ServeArgs),
}

#[derive(clap::Args)]
pub struct ServeArgs {
    /// Port to listen on
    #[arg(short, long, default_value = "8080")]
    pub port: u16,

    /// Address to bind to
    #[arg(short, long, default_value = "127.0.0.1")]
    pub address: String,

    /// Open browser automatically
    #[arg(long)]
    pub open: bool,

    /// Refget server URL for looking up unknown contigs.
    /// Defaults to EBI's ENA CRAM endpoint. Use --no-refget to disable.
    #[arg(long, default_value = crate::refget::DEFAULT_REFGET_SERVER)]
    pub refget_server: String,

    /// Disable refget lookups for unmatched contigs
    #[arg(long)]
    pub no_refget: bool,
}

#[derive(Clone, Copy, Debug, clap::ValueEnum)]
pub enum OutputFormat {
    Text,
    Json,
    Tsv,
}