help-probe 0.1.0

use serde::{Deserialize, Serialize};

/// Type of an argument, inferred from placeholder or description.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ArgumentType {
    /// String argument
    String,
    /// Numeric argument
    Number,
    /// File or directory path
    Path,
    /// URL argument
    Url,
    /// Email address argument
    Email,
    // Could be extended with more types
}

/// Structured description of a command argument/parameter.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ArgumentSpec {
    /// Argument name/placeholder, e.g. "FILE", "PATTERN", "PORT"
    pub name: String,
    /// Description of the argument, if available.
    pub description: Option<String>,
    /// Whether the argument is required (true for `ARG`, false for `[ARG]`).
    pub required: bool,
    /// Whether the argument is variadic (true for `ARG...`).
    pub variadic: bool,
    /// Inferred type of the argument.
    pub arg_type: Option<ArgumentType>,
    /// Original placeholder text, e.g. `"<FILE>"`, `"[PATH]"`, `"<PATTERN>..."`
    pub placeholder: Option<String>,
}

/// Type of an option's value.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum OptionType {
    /// Boolean flag (e.g., `--verbose`, `--no-color`, no argument)
    Boolean,
    /// String option (e.g., `--file <FILE>`, takes string argument)
    String,
    /// Numeric option (e.g., `--port <PORT>`, takes numeric argument)
    Number,
    /// Choice/enum option (e.g., `--level {debug|info|warn}`)
    Choice,
    /// Path option (e.g., `--config <PATH>`, file/directory path)
    Path,
}

/// Structured description of a single CLI option/flag.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct OptionSpec {
    /// Short flags, e.g. ["-h", "-v"]
    pub short_flags: Vec<String>,
    /// Long flags, e.g. ["--help", "--verbose"]
    pub long_flags: Vec<String>,
    /// A brief description, if we could extract one.
    pub description: Option<String>,

    /// Type of the option (boolean, string, number, choice, path).
    pub option_type: OptionType,
    /// Whether the option is required.
    pub required: bool,
    /// Default value, if any.
    pub default_value: Option<String>,
    /// Whether the option takes an argument (true for `--file <FILE>`, false for `--verbose`).
    pub takes_argument: bool,
    /// Name of the argument, if takes_argument is true (e.g. `"FILE"`, `"PATH"`).
    pub argument_name: Option<String>,
    /// For choice/enum options, the available choices.
    pub choices: Vec<String>,
}

/// Types of validation rules.
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
pub enum ValidationType {
    /// Regex pattern validation.
    Pattern,
    /// Numeric range validation (min/max).
    Range,
    /// Enum/choice validation.
    Choice,
    /// Required field validation.
    Required,
    /// Format validation (email, URL, etc.).
    Format,
}

/// A validation rule for an option or argument.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ValidationRule {
    /// The target option or argument name this rule applies to.
    pub target: String,
    /// Type of validation rule.
    pub rule_type: ValidationType,
    /// Regex pattern (for Pattern type).
    pub pattern: Option<String>,
    /// Minimum value (for Range type).
    pub min: Option<f64>,
    /// Maximum value (for Range type).
    pub max: Option<f64>,
    /// Validation error message.
    pub message: Option<String>,
}

/// An environment variable that can be used to configure the command.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct EnvVarSpec {
    /// The environment variable name, e.g. "CONFIG_FILE", "DEBUG".
    pub name: String,
    /// Description of what this environment variable does.
    pub description: Option<String>,
    /// The option this environment variable maps to (if any), e.g. "--config".
    pub option_mapped: Option<String>,
    /// Default value for this environment variable, if mentioned.
    pub default_value: Option<String>,
}

/// An example command usage extracted from help text.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Example {
    /// The example command line.
    pub command: String,
    /// Description of what this example demonstrates, if available.
    pub description: Option<String>,
    /// Tags categorizing the example (e.g., "basic", "advanced", "common").
    pub tags: Vec<String>,
}

/// Structured description of a subcommand (very heuristic).
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct SubcommandSpec {
    /// The subcommand name, e.g. "build", "run".
    pub name: String,
    /// A brief description, if available.
    pub description: Option<String>,
    /// Full path to this subcommand, e.g. "docker container run".
    pub full_path: String,
    /// Parent subcommand name, if this is nested (e.g. "container" for "run").
    pub parent: Option<String>,
    /// Subcommand-specific options.
    pub options: Vec<OptionSpec>,
    /// Subcommand-specific arguments.
    pub arguments: Vec<ArgumentSpec>,
    /// Nested subcommands (recursive structure).
    pub subcommands: Vec<SubcommandSpec>,
}

/// Complete command tree discovered through recursive probing.
#[derive(Debug, Serialize)]
pub struct CommandTree {
    /// The root command name.
    pub command: String,
    /// Root-level options.
    pub options: Vec<OptionSpec>,
    /// Root-level arguments.
    pub arguments: Vec<ArgumentSpec>,
    /// All subcommands (hierarchical structure).
    pub subcommands: Vec<SubcommandSpec>,
    /// Total number of commands discovered (including nested).
    pub total_commands: usize,
}

/// Structured result of probing a command.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ProbeResult {
    /// The command that was probed.
    pub command: String,
    /// The arguments that were used (may include automatically added help flags).
    pub args: Vec<String>,
    /// Exit code of the command, if it completed.
    pub exit_code: Option<i32>,
    /// Whether the command timed out.
    pub timed_out: bool,
    /// Whether a help flag was detected or automatically added.
    pub help_flag_detected: bool,
    /// Extracted usage blocks from help text.
    pub usage_blocks: Vec<String>,

    /// Parsed option specs (heuristic, may be incomplete).
    pub options: Vec<OptionSpec>,

    /// Parsed subcommands (heuristic).
    pub subcommands: Vec<SubcommandSpec>,

    /// Parsed arguments/parameters (heuristic, may be incomplete).
    pub arguments: Vec<ArgumentSpec>,

    /// Extracted examples from help text.
    pub examples: Vec<Example>,

    /// Discovered environment variables.
    pub environment_variables: Vec<EnvVarSpec>,

    /// Extracted validation rules.
    pub validation_rules: Vec<ValidationRule>,

    /// Raw stdout as UTF-8 (lossy).
    pub raw_stdout: String,

    /// Raw stderr as UTF-8 (lossy).
    pub raw_stderr: String,
}