help_probe/
model.rs

1use serde::{Deserialize, Serialize};
2
3/// Type of an argument, inferred from placeholder or description.
4#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
5pub enum ArgumentType {
6    /// String argument
7    String,
8    /// Numeric argument
9    Number,
10    /// File or directory path
11    Path,
12    /// URL argument
13    Url,
14    /// Email address argument
15    Email,
16    // Could be extended with more types
17}
18
19/// Structured description of a command argument/parameter.
20#[derive(Debug, Serialize, Deserialize, Clone)]
21pub struct ArgumentSpec {
22    /// Argument name/placeholder, e.g. "FILE", "PATTERN", "PORT"
23    pub name: String,
24    /// Description of the argument, if available.
25    pub description: Option<String>,
26    /// Whether the argument is required (true for `ARG`, false for `[ARG]`).
27    pub required: bool,
28    /// Whether the argument is variadic (true for `ARG...`).
29    pub variadic: bool,
30    /// Inferred type of the argument.
31    pub arg_type: Option<ArgumentType>,
32    /// Original placeholder text, e.g. `"<FILE>"`, `"[PATH]"`, `"<PATTERN>..."`
33    pub placeholder: Option<String>,
34}
35
36/// Type of an option's value.
37#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
38pub enum OptionType {
39    /// Boolean flag (e.g., `--verbose`, `--no-color`, no argument)
40    Boolean,
41    /// String option (e.g., `--file <FILE>`, takes string argument)
42    String,
43    /// Numeric option (e.g., `--port <PORT>`, takes numeric argument)
44    Number,
45    /// Choice/enum option (e.g., `--level {debug|info|warn}`)
46    Choice,
47    /// Path option (e.g., `--config <PATH>`, file/directory path)
48    Path,
49}
50
51/// Structured description of a single CLI option/flag.
52#[derive(Debug, Serialize, Deserialize, Clone)]
53pub struct OptionSpec {
54    /// Short flags, e.g. ["-h", "-v"]
55    pub short_flags: Vec<String>,
56    /// Long flags, e.g. ["--help", "--verbose"]
57    pub long_flags: Vec<String>,
58    /// A brief description, if we could extract one.
59    pub description: Option<String>,
60
61    /// Type of the option (boolean, string, number, choice, path).
62    pub option_type: OptionType,
63    /// Whether the option is required.
64    pub required: bool,
65    /// Default value, if any.
66    pub default_value: Option<String>,
67    /// Whether the option takes an argument (true for `--file <FILE>`, false for `--verbose`).
68    pub takes_argument: bool,
69    /// Name of the argument, if takes_argument is true (e.g. `"FILE"`, `"PATH"`).
70    pub argument_name: Option<String>,
71    /// For choice/enum options, the available choices.
72    pub choices: Vec<String>,
73}
74
75/// Types of validation rules.
76#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
77pub enum ValidationType {
78    /// Regex pattern validation.
79    Pattern,
80    /// Numeric range validation (min/max).
81    Range,
82    /// Enum/choice validation.
83    Choice,
84    /// Required field validation.
85    Required,
86    /// Format validation (email, URL, etc.).
87    Format,
88}
89
90/// A validation rule for an option or argument.
91#[derive(Debug, Serialize, Deserialize, Clone)]
92pub struct ValidationRule {
93    /// The target option or argument name this rule applies to.
94    pub target: String,
95    /// Type of validation rule.
96    pub rule_type: ValidationType,
97    /// Regex pattern (for Pattern type).
98    pub pattern: Option<String>,
99    /// Minimum value (for Range type).
100    pub min: Option<f64>,
101    /// Maximum value (for Range type).
102    pub max: Option<f64>,
103    /// Validation error message.
104    pub message: Option<String>,
105}
106
107/// An environment variable that can be used to configure the command.
108#[derive(Debug, Serialize, Deserialize, Clone)]
109pub struct EnvVarSpec {
110    /// The environment variable name, e.g. "CONFIG_FILE", "DEBUG".
111    pub name: String,
112    /// Description of what this environment variable does.
113    pub description: Option<String>,
114    /// The option this environment variable maps to (if any), e.g. "--config".
115    pub option_mapped: Option<String>,
116    /// Default value for this environment variable, if mentioned.
117    pub default_value: Option<String>,
118}
119
120/// An example command usage extracted from help text.
121#[derive(Debug, Serialize, Deserialize, Clone)]
122pub struct Example {
123    /// The example command line.
124    pub command: String,
125    /// Description of what this example demonstrates, if available.
126    pub description: Option<String>,
127    /// Tags categorizing the example (e.g., "basic", "advanced", "common").
128    pub tags: Vec<String>,
129}
130
131/// Structured description of a subcommand (very heuristic).
132#[derive(Debug, Serialize, Deserialize, Clone)]
133pub struct SubcommandSpec {
134    /// The subcommand name, e.g. "build", "run".
135    pub name: String,
136    /// A brief description, if available.
137    pub description: Option<String>,
138    /// Full path to this subcommand, e.g. "docker container run".
139    pub full_path: String,
140    /// Parent subcommand name, if this is nested (e.g. "container" for "run").
141    pub parent: Option<String>,
142    /// Subcommand-specific options.
143    pub options: Vec<OptionSpec>,
144    /// Subcommand-specific arguments.
145    pub arguments: Vec<ArgumentSpec>,
146    /// Nested subcommands (recursive structure).
147    pub subcommands: Vec<SubcommandSpec>,
148}
149
150/// Complete command tree discovered through recursive probing.
151#[derive(Debug, Serialize)]
152pub struct CommandTree {
153    /// The root command name.
154    pub command: String,
155    /// Root-level options.
156    pub options: Vec<OptionSpec>,
157    /// Root-level arguments.
158    pub arguments: Vec<ArgumentSpec>,
159    /// All subcommands (hierarchical structure).
160    pub subcommands: Vec<SubcommandSpec>,
161    /// Total number of commands discovered (including nested).
162    pub total_commands: usize,
163}
164
165/// Structured result of probing a command.
166#[derive(Debug, Serialize, Deserialize, Clone)]
167pub struct ProbeResult {
168    /// The command that was probed.
169    pub command: String,
170    /// The arguments that were used (may include automatically added help flags).
171    pub args: Vec<String>,
172    /// Exit code of the command, if it completed.
173    pub exit_code: Option<i32>,
174    /// Whether the command timed out.
175    pub timed_out: bool,
176    /// Whether a help flag was detected or automatically added.
177    pub help_flag_detected: bool,
178    /// Extracted usage blocks from help text.
179    pub usage_blocks: Vec<String>,
180
181    /// Parsed option specs (heuristic, may be incomplete).
182    pub options: Vec<OptionSpec>,
183
184    /// Parsed subcommands (heuristic).
185    pub subcommands: Vec<SubcommandSpec>,
186
187    /// Parsed arguments/parameters (heuristic, may be incomplete).
188    pub arguments: Vec<ArgumentSpec>,
189
190    /// Extracted examples from help text.
191    pub examples: Vec<Example>,
192
193    /// Discovered environment variables.
194    pub environment_variables: Vec<EnvVarSpec>,
195
196    /// Extracted validation rules.
197    pub validation_rules: Vec<ValidationRule>,
198
199    /// Raw stdout as UTF-8 (lossy).
200    pub raw_stdout: String,
201
202    /// Raw stderr as UTF-8 (lossy).
203    pub raw_stderr: String,
204}
help_probe/model.rs

help_probe/
model.rs
