aria2-rust-pro/xtask/src/cli.rs

#![expect(
    clippy::redundant_pub_crate,
    reason = "the cli module stays private while sibling xtask modules need crate-visible CLI types"
)]

use std::path::PathBuf;

use clap::{ArgAction, Args, Parser, Subcommand};

/// Top-level xtask CLI entrypoint.
#[derive(Debug, Parser)]
#[command(
    author,
    version,
    about = "Cargo-native workflow entrypoints for aria2-rust-pro"
)]
pub(crate) struct Cli {
    /// Selected top-level subcommand.
    #[command(subcommand)]
    pub(crate) command: TopLevelCommand,
}

/// Supported top-level xtask command groups.
#[derive(Debug, Subcommand)]
pub(crate) enum TopLevelCommand {
    /// Compatibility and golden-output workflows.
    Compat(CompatCommand),
    /// Docker packaging and smoke-test workflows.
    Docker(DockerCommand),
    /// Performance collection workflows.
    Perf(PerfCommand),
    /// Release packaging and validation workflows.
    Release(ReleaseCommand),
    /// Aggregated testing and lint-style sweeps.
    Testing(TestingCommand),
}

/// Compatibility command group.
#[derive(Debug, Args)]
pub(crate) struct CompatCommand {
    /// Selected compatibility subcommand.
    #[command(subcommand)]
    pub(crate) command: CompatSubcommand,
}

/// Compatibility-focused subcommands.
#[derive(Debug, Subcommand)]
pub(crate) enum CompatSubcommand {
    /// Capture CLI output goldens from upstream and Rust binaries.
    CaptureCliGoldens(CaptureCliGoldensArgs),
}

/// Arguments for capturing CLI golden outputs.
#[derive(Debug, Args)]
pub(crate) struct CaptureCliGoldensArgs {
    /// Optional path to the upstream reference binary.
    #[arg(long)]
    pub(crate) upstream_binary: Option<PathBuf>,
    /// Optional path to the Rust implementation binary.
    #[arg(long)]
    pub(crate) rust_binary: Option<PathBuf>,
    /// Optional root directory where captured goldens are written.
    #[arg(long)]
    pub(crate) output_root: Option<PathBuf>,
}

/// Release command group.
#[derive(Debug, Args)]
pub(crate) struct ReleaseCommand {
    /// Selected release subcommand.
    #[command(subcommand)]
    pub(crate) command: ReleaseSubcommand,
}

/// Release-oriented subcommands.
#[derive(Debug, Subcommand)]
pub(crate) enum ReleaseSubcommand {
    /// Validate the release binary reports the expected version string.
    SmokeVersion(ReleaseSmokeVersionArgs),
    /// Package a local release artifact layout.
    PackageLocal(PackageLocalArgs),
}

/// Arguments for the release version smoke test.
#[derive(Debug, Args)]
pub(crate) struct ReleaseSmokeVersionArgs {
    /// Build the binary before running the smoke test.
    #[arg(long)]
    pub(crate) build: bool,
    /// Optional target triple used when locating or building the binary.
    #[arg(long)]
    pub(crate) target_triple: Option<String>,
    /// Optional explicit path to the binary under test.
    #[arg(long)]
    pub(crate) binary_path: Option<PathBuf>,
}

/// Arguments for packaging a local release bundle.
#[derive(Debug, Args)]
pub(crate) struct PackageLocalArgs {
    /// Build the binary before packaging it.
    #[arg(long)]
    pub(crate) build: bool,
    /// Optional target triple used when locating or building the binary.
    #[arg(long)]
    pub(crate) target_triple: Option<String>,
    /// Optional explicit path to the binary that should be packaged.
    #[arg(long)]
    pub(crate) source_binary: Option<PathBuf>,
    /// Optional root directory where packaged artifacts are written.
    #[arg(long)]
    pub(crate) output_root: Option<PathBuf>,
    /// Skip the version smoke test that normally runs before packaging.
    #[arg(long)]
    pub(crate) skip_version_smoke: bool,
}

/// Testing command group.
#[derive(Debug, Args)]
pub(crate) struct TestingCommand {
    /// Selected testing subcommand.
    #[command(subcommand)]
    pub(crate) command: TestingSubcommand,
}

/// Testing-oriented subcommands.
#[derive(Debug, Subcommand)]
pub(crate) enum TestingSubcommand {
    /// Run the strict sweep across the xtask quality gates.
    StrictSweep(StrictSweepArgs),
}

/// Arguments for the strict sweep workflow.
#[derive(Debug, Args)]
pub(crate) struct StrictSweepArgs {
    /// Include release smoke checks as part of the sweep.
    #[arg(long)]
    pub(crate) include_release_smoke: bool,
}

/// Docker command group.
#[derive(Debug, Args)]
pub(crate) struct DockerCommand {
    /// Selected Docker subcommand.
    #[command(subcommand)]
    pub(crate) command: DockerSubcommand,
}

/// Docker-oriented subcommands.
#[derive(Debug, Subcommand)]
pub(crate) enum DockerSubcommand {
    /// Export a locally built Docker image as a tarball.
    ExportLocal(ExportLocalArgs),
    /// Run the Docker smoke test against a tagged image.
    Smoke(DockerSmokeArgs),
    /// Run the Docker smoke test using the local defaults.
    SmokeLocal(DockerSmokeLocalArgs),
}

/// Arguments for exporting a local Docker image.
#[derive(Debug, Args)]
pub(crate) struct ExportLocalArgs {
    /// Docker image tag to build or export.
    #[arg(long, default_value = "aria2-rust-pro:local")]
    pub(crate) tag: String,
    /// Optional root directory where exported artifacts are written.
    #[arg(long)]
    pub(crate) output_root: Option<PathBuf>,
    /// Build the Docker image before exporting it.
    #[arg(long)]
    pub(crate) build: bool,
}

/// Arguments for running the Docker smoke test.
#[derive(Debug, Args)]
pub(crate) struct DockerSmokeArgs {
    /// Docker image tag to build or run during the smoke test.
    #[arg(long, default_value = "aria2-rust-pro:smoke")]
    pub(crate) tag: String,
    /// Build the Docker image before running the smoke test.
    #[arg(long, default_value_t = true, action = ArgAction::Set)]
    pub(crate) build: bool,
    /// Host RPC port mapped into the smoke-test container.
    #[arg(long, default_value_t = 26_800)]
    pub(crate) host_rpc_port: u16,
    /// RPC secret used by the smoke-test container.
    #[arg(long, default_value = "smoke-secret")]
    pub(crate) rpc_secret: String,
    /// Special mode passed into the smoke-test scenario.
    #[arg(long, default_value = "move")]
    pub(crate) special_mode: String,
}

/// Arguments for the local Docker smoke shortcut.
#[derive(Debug, Args)]
pub(crate) struct DockerSmokeLocalArgs {}

/// Performance command group.
#[derive(Debug, Args)]
pub(crate) struct PerfCommand {
    /// Selected performance subcommand.
    #[command(subcommand)]
    pub(crate) command: PerfSubcommand,
}

/// Performance-oriented subcommands.
#[derive(Debug, Subcommand)]
pub(crate) enum PerfSubcommand {
    /// Collect local upstream-vs-Rust comparison data.
    CollectLocalComparison(CollectLocalComparisonArgs),
}

/// Arguments for local comparison data collection.
#[derive(Debug, Args)]
pub(crate) struct CollectLocalComparisonArgs {
    /// Optional output file for the comparison report.
    #[arg(long)]
    pub(crate) output_path: Option<PathBuf>,
    /// Number of samples collected per benchmark case.
    #[arg(long, default_value_t = 10.0)]
    pub(crate) sample_size: f64,
    /// Measurement duration, in seconds, for each sample.
    #[arg(long, default_value_t = 0.05)]
    pub(crate) measurement_seconds: f64,
    /// Warmup duration, in seconds, before measurements begin.
    #[arg(long, default_value_t = 0.05)]
    pub(crate) warmup_seconds: f64,
    /// Transfer size, in bytes, used by the benchmark.
    #[arg(long, default_value_t = 8 * 1024 * 1024)]
    pub(crate) transfer_bytes: usize,
    /// Timed same-host transfer samples collected per binary and scenario after warmup.
    #[arg(long, default_value_t = 5)]
    pub(crate) same_host_runs: usize,
    /// Skip bench execution and only reuse existing output data.
    #[arg(long)]
    pub(crate) skip_bench_execution: bool,
}