saccade 0.1.0

Visual-regression CLI for renderers and graphics code, built on NVIDIA FLIP
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

//! Analyze divergence among existing captures.
use clap::Args;
#[cfg(feature = "graphics")]
use saccade_core::bisect::{self, BisectOptions};
use std::path::PathBuf;

use crate::agent::CliError;

#[derive(Args)]
#[cfg(feature = "graphics")]
pub(crate) struct BisectArgs {
    /// Ordered run directories, oldest first (repeatable).
    #[arg(long, num_args = 1..)]
    pub runs: Vec<PathBuf>,
    /// One ordered run path per line.
    #[arg(long)]
    pub runs_from: Option<PathBuf>,
    /// Reference for existing runs (default: first run).
    #[arg(long)]
    pub good: Option<PathBuf>,
    /// Explicit FLIP threshold relaxes native sample identity.
    #[arg(long)]
    pub threshold: Option<f64>,
    /// mean, p95, p99 or max (default max).
    #[arg(long)]
    pub metric: Option<String>,
    /// Select image names by glob.
    #[arg(long)]
    pub entries: Option<String>,
    /// Report directory, separate from inputs.
    #[arg(long, default_value = "bisect-report")]
    pub out: PathBuf,
    /// Print saccade-bisect.v1 JSON.
    #[arg(long)]
    pub json: bool,
}

#[cfg(feature = "graphics")]
pub(crate) fn options(
    threshold: Option<f64>,
    metric: Option<&str>,
    entries: Option<String>,
) -> Result<BisectOptions, CliError> {
    let metric = metric
        .map(|m| match m {
            "mean" => Ok(saccade_core::Metric::Mean),
            "p95" => Ok(saccade_core::Metric::P95),
            "p99" => Ok(saccade_core::Metric::P99),
            "max" => Ok(saccade_core::Metric::Max),
            _ => Err(CliError::usage("metric must be mean, p95, p99 or max")),
        })
        .transpose()?;
    if threshold.is_some_and(|t| !t.is_finite() || !(0.0..=1.0).contains(&t)) {
        return Err(CliError::usage(
            "threshold must be finite and between 0 and 1",
        ));
    }
    Ok(BisectOptions {
        threshold,
        metric,
        entries,
    })
}

#[cfg(feature = "graphics")]
pub(crate) fn bisect(args: BisectArgs) -> Result<u8, CliError> {
    let opts = options(args.threshold, args.metric.as_deref(), args.entries)?;
    let result = {
        let mut runs = args.runs;
        if let Some(file) = args.runs_from {
            if !runs.is_empty() {
                return Err(CliError::usage("use --runs or --runs-from"));
            }
            runs = std::fs::read_to_string(file)
                .map_err(|e| CliError::io(format!("reading runs file: {e}")))?
                .lines()
                .filter(|s| !s.trim().is_empty())
                .map(PathBuf::from)
                .collect();
        }
        bisect::runs(&runs, args.good.as_deref(), &args.out, &opts)?
    };
    if args.json {
        crate::emit(&format!(
            "{}\n",
            serde_json::to_string(&crate::local_cmd::analysis_result(
                &serde_json::to_value(&result)?,
                &args.out
            )?)?
        ))?;
    } else {
        crate::emit(&result.text())?;
    }
    Ok(result.exit_code())
}