reserve 0.2.0

use clap::{Args, Parser, Subcommand, ValueEnum, ValueHint};

/// The command tree, defined once and shared by the parser, the completions,
/// and the man page so the three can never drift apart.
#[derive(Debug, Parser)]
#[command(
    name = "reserve",
    version,
    about = "Find a domain name you can actually buy",
    long_about = "Check one or more names across grouped domain extensions.\n\n\
                  Pick extensions by industry, region, or popularity, filter and sort\n\
                  the list, and sweep it. Every answer comes from the registry itself, and a\n\
                  lookup that cannot be answered is reported as unknown rather than guessed.",
    after_help = "EXAMPLES:\n  \
        reserve example                        open the picker and choose extensions\n  \
        reserve example --group tech           sweep the technology extensions\n  \
        reserve example -g shop -g finance     extensions marketed for selling\n  \
        reserve example -g top-50 --sort popularity  the fifty most used\n  \
        reserve groups                         list every group you can pick\n\n\
        Full documentation: https://reserve.devops.bd",
    disable_help_subcommand = true,
    infer_subcommands = false,
    propagate_version = true,
    max_term_width = 100
)]
pub(crate) struct Cli {
    /// Names to check. A name carrying a dot is checked exactly as typed.
    #[arg(value_name = "NAME", value_hint = ValueHint::Other)]
    pub names: Vec<String>,

    /// Read names from a file, one per line. Commas also separate, `#` starts
    /// a comment, and blank lines are skipped.
    #[arg(long, value_name = "PATH", value_hint = ValueHint::FilePath)]
    pub names_from: Option<String>,

    #[command(flatten)]
    pub select: SelectArgs,

    #[command(flatten)]
    pub view: ListingArgs,

    #[command(flatten)]
    pub pacing: PacingArgs,

    #[command(flatten)]
    pub output: OutputArgs,

    #[command(flatten)]
    pub global: GlobalArgs,

    #[command(subcommand)]
    pub command: Option<Command>,
}

#[derive(Debug, Subcommand)]
#[allow(
    clippy::large_enum_variant,
    reason = "clap derive requires argument structs by value on each variant"
)]
pub(crate) enum Command {
    /// List the extension groups you can pick from.
    Groups {
        /// Show only one family of groups.
        #[arg(short, long, value_enum, value_name = "FAMILY")]
        family: Option<FamilyArg>,

        /// Print as JSON.
        #[arg(long)]
        json: bool,
    },

    /// Browse and search the extension catalog without checking anything.
    Extensions {
        #[command(flatten)]
        select: SelectArgs,

        #[command(flatten)]
        view: ListingArgs,

        /// Print as JSON.
        #[arg(long)]
        json: bool,
    },

    /// Show where settings come from and what they resolved to.
    Config {
        #[command(subcommand)]
        action: ConfigAction,
    },

    /// Print what the tool sees: version, paths, terminal, and network.
    Doctor {
        /// Print as JSON.
        #[arg(long)]
        json: bool,
    },

    /// Write a shell completion script to stdout.
    Completions {
        /// The shell to generate for.
        #[arg(value_enum)]
        shell: ShellArg,
    },
}

#[derive(Debug, Subcommand)]
pub(crate) enum ConfigAction {
    /// Print every resolved setting and where each value came from.
    Show {
        /// Print as JSON.
        #[arg(long)]
        json: bool,
    },
    /// Print the config, cache, and data paths this machine uses.
    Path,
}

/// Which extensions a run covers.
#[derive(Debug, Clone, Default, Args)]
#[command(next_help_heading = "Choosing extensions")]
pub(crate) struct SelectArgs {
    /// Group to pull extensions from. Repeat or comma-separate for several.
    #[arg(
        short,
        long,
        value_name = "GROUP",
        value_delimiter = ',',
        num_args = 1..
    )]
    pub group: Vec<String>,

    /// Extension to check, named directly, such as `com` or `co.uk`.
    #[arg(
        short = 't',
        long = "tld",
        value_name = "EXT",
        value_delimiter = ',',
        num_args = 1..
    )]
    pub tld: Vec<String>,

    /// Extension to leave out of whatever else was chosen.
    #[arg(
        short = 'x',
        long,
        value_name = "EXT",
        value_delimiter = ',',
        num_args = 1..
    )]
    pub exclude: Vec<String>,

    /// Keep only extensions matching this text, by name, country, or industry.
    #[arg(short, long, value_name = "TEXT")]
    pub search: Option<String>,

    /// Keep only extensions marketed for this industry.
    #[arg(long, value_name = "KEY", value_delimiter = ',', num_args = 1..)]
    pub industry: Vec<String>,

    /// Keep only country extensions from this region.
    #[arg(long, value_name = "KEY", value_delimiter = ',', num_args = 1..)]
    pub region: Vec<String>,

    /// Keep only two-letter country extensions.
    #[arg(long)]
    pub cctld: bool,

    /// Keep plain extensions, multi-label ones, or both.
    #[arg(long, value_enum, value_name = "DEPTH", default_value_t = DepthArg::Any)]
    pub depth: DepthArg,

    /// Keep extensions by length: `2`, `-3`, `4-`, or `2-4`.
    #[arg(long, value_name = "SPEC")]
    pub length: Option<String>,

    /// Read extensions from a file, in the same shape as a name list.
    #[arg(long, value_name = "PATH", value_hint = ValueHint::FilePath)]
    pub tlds_from: Option<String>,

    /// Include zones the public cannot register under.
    #[arg(long)]
    pub include_restricted: bool,
}

/// How the result list is ordered and paged.
#[derive(Debug, Clone, Args)]
#[command(next_help_heading = "Ordering and paging")]
pub(crate) struct ListingArgs {
    /// What to order the list by.
    #[arg(long, value_enum, value_name = "FIELD", default_value_t = SortFieldArg::Popularity)]
    pub sort: SortFieldArg,

    /// Which way to order. Defaults to what reads best for the chosen field.
    #[arg(long, value_enum, value_name = "ORDER")]
    pub order: Option<SortOrderArg>,

    /// Which page to show.
    #[arg(long, value_name = "N", default_value_t = 1)]
    pub page: usize,

    /// How many rows a page holds. Defaults to what the terminal fits.
    #[arg(long, value_name = "N")]
    pub page_size: Option<usize>,

    /// Print every page at once instead of stopping at the first.
    #[arg(long, conflicts_with = "page")]
    pub all_pages: bool,
}

impl Default for ListingArgs {
    fn default() -> Self {
        Self {
            sort: SortFieldArg::Popularity,
            order: None,
            page: 1,
            page_size: None,
            all_pages: false,
        }
    }
}

/// How hard the run pushes the registries.
#[derive(Debug, Clone, Args)]
#[command(next_help_heading = "Pacing")]
pub(crate) struct PacingArgs {
    /// Lookups in flight across the whole run.
    #[arg(short = 'c', long, value_name = "N", env = "RESERVE_CONCURRENCY")]
    pub concurrency: Option<usize>,

    /// Lookups in flight against any one registry.
    #[arg(long, value_name = "N")]
    pub per_registry: Option<usize>,

    /// Sustained requests per second against any one registry.
    #[arg(long, value_name = "N")]
    pub rate: Option<u32>,

    /// Seconds to wait on any single request.
    #[arg(long, value_name = "SECS", env = "RESERVE_TIMEOUT")]
    pub timeout: Option<u64>,

    /// Go slowly, for a very large sweep or a strict registry. This is a
    /// ceiling: --rate and --per-registry can lower it, never raise it.
    #[arg(long)]
    pub cautious: bool,

    /// Where answers come from.
    #[arg(long, value_enum, value_name = "SOURCE", default_value_t = SourceArg::Auto)]
    pub source: SourceArg,

    /// Re-download the registry server list instead of using the cached copy.
    #[arg(long)]
    pub refresh: bool,

    /// Use your own structured-service list, in the published bootstrap shape.
    #[arg(long, value_name = "PATH", value_hint = ValueHint::FilePath)]
    pub registry_servers: Option<String>,

    /// Use your own text-service table, in the same shape as the built-in one.
    #[arg(long, value_name = "PATH", value_hint = ValueHint::FilePath)]
    pub text_servers: Option<String>,

    /// Let a supplied server list replace the built-in one instead of
    /// overlaying it.
    #[arg(long)]
    pub servers_replace: bool,

    /// Never ask IANA who serves an extension, so a stale built-in host is
    /// not repaired and no extra lookup is made.
    #[arg(long)]
    pub no_referral: bool,
}

/// What the run prints and writes.
#[derive(Debug, Clone, Default, Args)]
#[command(next_help_heading = "Output")]
pub(crate) struct OutputArgs {
    /// Print machine-readable JSON instead of the table.
    #[arg(long)]
    pub json: bool,

    /// Show only the names nobody holds.
    #[arg(short = 'a', long)]
    pub available_only: bool,

    /// Show registrar, dates, status, nameservers, and abuse contact.
    #[arg(long)]
    pub details: bool,

    /// Show which registry server answered.
    #[arg(long)]
    pub responder: bool,

    /// Show the DNS records for a name that is taken.
    #[arg(long)]
    pub dns: bool,

    /// For an available name, show the registry and where to buy it.
    #[arg(long)]
    pub where_to_buy: bool,

    /// Turn on every extra section at once.
    #[arg(long, conflicts_with_all = ["details", "responder", "dns", "where_to_buy"])]
    pub full: bool,

    /// Write the results into this directory.
    #[arg(short, long, value_name = "DIR", value_hint = ValueHint::DirPath, group = "save_target")]
    pub out: Option<String>,

    /// Write result files into the current directory.
    #[arg(long, group = "save_target")]
    pub save: bool,

    /// Merge into the files already there instead of replacing them.
    #[arg(long, requires = "save_target")]
    pub append: bool,
}

/// Settings that apply to every subcommand.
#[derive(Debug, Args)]
pub(crate) struct GlobalArgs {
    #[command(flatten)]
    pub verbosity: clap_verbosity_flag::Verbosity<clap_verbosity_flag::WarnLevel>,

    /// When to use color.
    #[arg(long, value_enum, value_name = "WHEN", default_value_t = ColorArg::Auto, global = true)]
    pub color: ColorArg,

    /// Lay the table out for this many columns instead of the terminal's width.
    #[arg(long, value_name = "N", global = true, env = "RESERVE_WIDTH")]
    pub width: Option<u16>,

    /// Never prompt and never open the picker.
    #[arg(
        long,
        global = true,
        env = "RESERVE_NO_INPUT",
        value_parser = clap::builder::FalseyValueParser::new()
    )]
    pub no_input: bool,

    /// Open the picker even when extensions were given on the command line.
    #[arg(long, conflicts_with = "no_input", global = true)]
    pub interactive: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum ColorArg {
    /// Color when the output is a terminal.
    Auto,
    /// Always color, even through a pipe.
    Always,
    /// Never color.
    Never,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, ValueEnum)]
pub(crate) enum DepthArg {
    /// Both plain and multi-label extensions.
    #[default]
    Any,
    /// Plain extensions only, such as `com`.
    Second,
    /// Multi-label extensions only, such as `co.uk`.
    Third,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum SortFieldArg {
    /// Alphabetical by extension.
    Name,
    /// By how widely the extension is used.
    Popularity,
    /// By how many characters the extension has.
    Length,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum SortOrderArg {
    /// Lowest or earliest first.
    Asc,
    /// Highest or latest first.
    Desc,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum SourceArg {
    /// Ask the registry, then fall back to DNS.
    Auto,
    /// Ask the registry only. An extension with no service reports unknown.
    Registry,
    /// Use the older text protocol only.
    Text,
    /// Use DNS only. Can prove a name is taken, never that one is free.
    Dns,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum FamilyArg {
    Industry,
    Region,
    Popularity,
    Curated,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub(crate) enum ShellArg {
    Bash,
    Elvish,
    Fish,
    /// @docgen Left to the derive this becomes `power-shell`, which is not a name any user would type.
    #[value(name = "powershell")]
    PowerShell,
    Zsh,
}

#[cfg(test)]
mod tests {
    use clap::CommandFactory as _;

    use super::*;

    #[test]
    fn the_command_tree_carries_no_conflicting_definition() {
        Cli::command().debug_assert();
    }
}