help_probe/

parser.rs

use crate::model::{
    ArgumentSpec, ArgumentType, EnvVarSpec, OptionSpec, OptionType, SubcommandSpec, ValidationRule,
    ValidationType,
};

/// Detect whether the user-supplied args contain a likely "help" flag.
///
/// We look for:
///   - -h
///   - --help
///   - help
///   - /?
///   - -?
///   - --usage
pub fn detect_help_flag(args: &[String]) -> bool {
    args.iter().any(|arg| {
        let lower = arg.to_lowercase();
        matches!(
            lower.as_str(),
            "-h" | "--help" | "help" | "/?" | "-?" | "--usage"
        )
    })
}

/// Parse "usage" blocks from stdout/stderr.
///
/// Strategy:
/// - Combine stdout and stderr lines.
/// - Find all lines where "usage" appears (case-insensitive),
///   or line starts with "usage".
/// - For each such line, capture N lines before and after.
///
/// This is intentionally simple and heuristic.
pub fn parse_usages(stdout: &[u8], stderr: &[u8]) -> Vec<String> {
    let stdout_s = String::from_utf8_lossy(stdout);
    let stderr_s = String::from_utf8_lossy(stderr);

    let lines: Vec<String> = stdout_s
        .lines()
        .map(|s| s.to_string())
        .chain(stderr_s.lines().map(|s| s.to_string()))
        .collect();

    if lines.is_empty() {
        return Vec::new();
    }

    let mut usage_indices = Vec::new();

    for (idx, line) in lines.iter().enumerate() {
        let l = line.to_lowercase();
        if l.contains("usage:") || l.starts_with("usage ") || l.starts_with("usage:") {
            usage_indices.push(idx);
        }
    }

    if usage_indices.is_empty() {
        return Vec::new();
    }

    // Sort and dedup indices
    usage_indices.sort_unstable();
    usage_indices.dedup();

    let mut results = Vec::new();
    let context_before = 1usize;
    let context_after = 10usize; // Increased to capture more options

    for idx in usage_indices {
        let start = idx.saturating_sub(context_before);
        let end = std::cmp::min(idx + 1 + context_after, lines.len());
        let block = lines[start..end].join("\n");
        results.push(block);
    }

    results
}

/// Attempt to parse option/flag lines from the usage blocks and OPTIONS sections.
///
/// Heuristic:
/// - For each line in each block:
///   - Trim leading whitespace.
///   - If line starts with '-' or '--', assume it's an option line.
///   - Split into "flag part" and "description part".
///   - Parse flags like "-h", "--help", "-v, --verbose", "-p | --paginate".
pub fn parse_options_from_usage_blocks(blocks: &[String]) -> Vec<OptionSpec> {
    let mut options = Vec::new();

    for block in blocks {
        for raw_line in block.lines() {
            let line = raw_line.trim_start();
            if line.is_empty() {
                continue;
            }

            // Heuristic: option lines often start with '-' or '--'
            if !line.starts_with('-') {
                continue;
            }

            // Split into flag part and description part.
            let (flag_part, desc_part) = split_flag_and_description(line);

            let mut short_flags = Vec::new();
            let mut long_flags = Vec::new();

            // Handle pipe-separated flags like "-p | --paginate"
            let flag_part_normalized = flag_part.replace(" | ", ", ");

            // Split on commas or whitespace, but be smarter about it
            for token in flag_part_normalized.split(|c: char| c.is_whitespace() || c == ',') {
                let t = token.trim();
                if t.is_empty() {
                    continue;
                }

                // Remove common placeholders/values like <FILE>, [PATH], =FILE, etc.
                let cleaned = t
                    .split(|c: char| c == '<' || c == '>' || c == '[' || c == ']' || c == '=')
                    .next()
                    .unwrap_or(t)
                    .trim();

                if cleaned.is_empty() {
                    continue;
                }

                if cleaned.starts_with("--") {
                    long_flags.push(cleaned.to_string());
                } else if cleaned.starts_with('-') {
                    short_flags.push(cleaned.to_string());
                }
            }

            if short_flags.is_empty() && long_flags.is_empty() {
                continue;
            }

            let description = desc_part
                .map(|s| s.trim().to_string())
                .filter(|s| !s.is_empty());

            // Extract enhanced metadata from flag_part and description
            let (takes_argument, argument_name, option_type, choices) =
                extract_option_metadata(&flag_part, description.as_deref());

            // Determine if required (typically options are optional, but check description)
            let required = description
                .as_ref()
                .map(|d| d.to_lowercase().contains("required"))
                .unwrap_or(false);

            options.push(OptionSpec {
                short_flags,
                long_flags,
                description: description.clone(),
                option_type,
                required,
                default_value: extract_default_value(description.as_deref()),
                takes_argument,
                argument_name,
                choices,
            });
        }
    }

    options
}

/// Parse options from separate OPTIONS sections in the help text.
/// This complements parse_options_from_usage_blocks by finding options
/// that appear in dedicated OPTIONS sections.
pub fn parse_options_from_sections(full_stdout: &str, full_stderr: &str) -> Vec<OptionSpec> {
    let lines: Vec<String> = full_stdout
        .lines()
        .map(|s| s.to_string())
        .chain(full_stderr.lines().map(|s| s.to_string()))
        .collect();

    if lines.is_empty() {
        return Vec::new();
    }

    let mut options = Vec::new();
    let mut in_options_section = false;
    let mut options_start_idx = 0;

    // Find OPTIONS sections
    for (idx, line) in lines.iter().enumerate() {
        let trimmed = line.trim().to_lowercase();

        // Check if this is an OPTIONS section header
        if trimmed == "options:" || trimmed == "options" {
            in_options_section = true;
            options_start_idx = idx + 1;
            continue;
        }

        // If we're in an options section, parse lines until we hit a non-option line
        if in_options_section {
            let trimmed_line = line.trim_start();

            // Stop if we hit a blank line or a section header (non-indented, uppercase-ish)
            if trimmed_line.is_empty() {
                // Blank line might be separator, continue for a bit
                if idx > options_start_idx + 2 {
                    in_options_section = false;
                }
                continue;
            }

            // Stop if we hit another section header (like "COMMANDS:", "SUBCOMMANDS:")
            let lower = trimmed_line.to_lowercase();
            if (lower.ends_with(':')
                || lower.ends_with("commands")
                || lower.ends_with("subcommands"))
                && !trimmed_line.starts_with(' ')
                && !trimmed_line.starts_with('\t')
            {
                in_options_section = false;
                continue;
            }

            // Parse option lines (start with -)
            if trimmed_line.starts_with('-') {
                let (flag_part, desc_part) = split_flag_and_description(trimmed_line);

                let mut short_flags = Vec::new();
                let mut long_flags = Vec::new();

                let flag_part_normalized = flag_part.replace(" | ", ", ");

                for token in flag_part_normalized.split(|c: char| c.is_whitespace() || c == ',') {
                    let t = token.trim();
                    if t.is_empty() {
                        continue;
                    }

                    // Remove placeholders
                    let cleaned = t
                        .split(|c: char| c == '<' || c == '>' || c == '[' || c == ']' || c == '=')
                        .next()
                        .unwrap_or(t)
                        .trim();

                    if cleaned.is_empty() {
                        continue;
                    }

                    if cleaned.starts_with("--") {
                        long_flags.push(cleaned.to_string());
                    } else if cleaned.starts_with('-') {
                        short_flags.push(cleaned.to_string());
                    }
                }

                if !short_flags.is_empty() || !long_flags.is_empty() {
                    let description = desc_part
                        .map(|s| s.trim().to_string())
                        .filter(|s| !s.is_empty());

                    // Extract enhanced metadata
                    let (takes_argument, argument_name, option_type, choices) =
                        extract_option_metadata(&flag_part, description.as_deref());

                    let required = description
                        .as_ref()
                        .map(|d| d.to_lowercase().contains("required"))
                        .unwrap_or(false);

                    options.push(OptionSpec {
                        short_flags,
                        long_flags,
                        description: description.clone(),
                        option_type,
                        required,
                        default_value: extract_default_value(description.as_deref()),
                        takes_argument,
                        argument_name,
                        choices,
                    });
                }
            } else if !trimmed_line.starts_with(' ') && !trimmed_line.starts_with('\t') {
                // Non-indented, non-option line - probably end of section
                in_options_section = false;
            }
        }
    }

    options
}

/// Attempt to parse arguments/parameters from usage blocks and Arguments sections.
///
/// Strategy:
/// - Parse usage lines for argument patterns: `<ARG>`, `[ARG]`, `<ARG>...`
/// - Extract from "Arguments:" sections in help text
/// - Infer types from placeholders (`<FILE>`, `<PORT>`, `<URL>`)
/// - Extract descriptions from help text
pub fn parse_arguments(
    full_stdout: &str,
    full_stderr: &str,
    usage_blocks: &[String],
) -> Vec<ArgumentSpec> {
    let mut arguments = Vec::new();

    // First, extract from usage blocks (usage lines)
    for block in usage_blocks {
        arguments.extend(parse_arguments_from_usage_line(block));
    }

    // Then, extract from "Arguments:" sections
    let lines: Vec<String> = full_stdout
        .lines()
        .map(|s| s.to_string())
        .chain(full_stderr.lines().map(|s| s.to_string()))
        .collect();

    arguments.extend(parse_arguments_from_section(&lines));

    // Deduplicate arguments (same name)
    arguments.sort_by(|a, b| a.name.cmp(&b.name));
    arguments.dedup_by(|a, b| a.name == b.name && a.placeholder == b.placeholder);

    arguments
}

/// Parse arguments from a usage line.
/// Extracts patterns like: `<FILE>`, `[OPTIONAL]`, `<PATTERN>...`, `[ARGS]...`
fn parse_arguments_from_usage_line(usage_block: &str) -> Vec<ArgumentSpec> {
    let mut arguments = Vec::new();

    // Look for usage lines
    for line in usage_block.lines() {
        let line_lower = line.to_lowercase();
        if !line_lower.contains("usage:") && !line_lower.starts_with("usage ") {
            continue;
        }

        // Extract argument patterns from the usage line
        // Patterns: <ARG>, [ARG], <ARG>..., [ARG]...
        let re = regex::Regex::new(r"(<([^>]+)>|\[([^\]]+)\])(\.\.\.)?").unwrap();

        for cap in re.captures_iter(line) {
            if let Some(full_match) = cap.get(1) {
                let is_required = full_match.as_str().starts_with('<');
                let name = if let Some(m) = cap.get(2) {
                    m.as_str().to_string()
                } else if let Some(m) = cap.get(3) {
                    m.as_str().to_string()
                } else {
                    continue;
                };
                let is_variadic = cap.get(4).is_some();
                let placeholder = Some({
                    let mut p = full_match.as_str().to_string();
                    if is_variadic {
                        p.push_str("...");
                    }
                    p
                });

                let arg_type = infer_argument_type(&name, placeholder.as_deref());

                arguments.push(ArgumentSpec {
                    name: name.clone(),
                    description: None,
                    required: is_required,
                    variadic: is_variadic,
                    arg_type,
                    placeholder,
                });
            }
        }
    }

    arguments
}

/// Parse arguments from "Arguments:" sections in help text.
fn parse_arguments_from_section(lines: &[String]) -> Vec<ArgumentSpec> {
    let mut arguments = Vec::new();
    let mut in_arguments_section = false;
    let mut section_start_idx = 0;

    for (idx, line) in lines.iter().enumerate() {
        let trimmed = line.trim().to_lowercase();

        // Check if this is an "Arguments:" section header
        if trimmed == "arguments:" || trimmed == "arguments" {
            in_arguments_section = true;
            section_start_idx = idx + 1;
            continue;
        }

        // If we're in an arguments section, parse lines until we hit a non-argument line
        if in_arguments_section {
            let trimmed_line = line.trim_start();

            // Stop if we hit a blank line or a section header (non-indented, uppercase-ish)
            if trimmed_line.is_empty() {
                if idx > section_start_idx + 2 {
                    in_arguments_section = false;
                }
                continue;
            }

            // Stop if we hit another section header
            let lower = trimmed_line.to_lowercase();
            if (lower.ends_with(':') || lower.contains("options") || lower.contains("commands"))
                && !trimmed_line.starts_with(' ')
                && !trimmed_line.starts_with('\t')
            {
                in_arguments_section = false;
                continue;
            }

            // Parse argument lines (typically start with <ARG> or [ARG])
            if trimmed_line.starts_with('<') || trimmed_line.starts_with('[') {
                if let Some(arg) = parse_argument_line(trimmed_line) {
                    arguments.push(arg);
                }
            } else if !trimmed_line.starts_with(' ') && !trimmed_line.starts_with('\t') {
                // Non-indented, non-argument line - probably end of section
                in_arguments_section = false;
            }
        }
    }

    arguments
}

/// Parse a single argument line from an Arguments section.
/// Format: "  <FILE>        Description of the file"
/// or:     "  [OUTPUT]      Optional output path"
fn parse_argument_line(line: &str) -> Option<ArgumentSpec> {
    let trimmed = line.trim();

    // Extract placeholder pattern
    let re = regex::Regex::new(r"^(<([^>]+)>|\[([^\]]+)\])(\.\.\.)?").unwrap();
    let cap = re.captures(trimmed)?;

    let full_match = cap.get(1)?;
    let is_required = full_match.as_str().starts_with('<');
    let name = if let Some(m) = cap.get(2) {
        m.as_str().to_string()
    } else if let Some(m) = cap.get(3) {
        m.as_str().to_string()
    } else {
        return None;
    };
    let is_variadic = cap.get(4).is_some();
    let placeholder = Some({
        let mut p = full_match.as_str().to_string();
        if is_variadic {
            p.push_str("...");
        }
        p
    });

    // Extract description (everything after the placeholder, separated by 2+ spaces or tab)
    let full_cap = cap.get(0)?;
    let desc_start = full_cap.end();
    let rest = &trimmed[desc_start..].trim();
    let description = if rest.is_empty() {
        None
    } else {
        // Try to split on 2+ spaces or tab
        let desc = if let Some(idx) = rest.find("  ") {
            rest[..idx].trim().to_string()
        } else if let Some(idx) = rest.find('\t') {
            rest[..idx].trim().to_string()
        } else {
            rest.to_string()
        };
        if desc.is_empty() { None } else { Some(desc) }
    };

    let arg_type = infer_argument_type(&name, placeholder.as_deref());

    Some(ArgumentSpec {
        name,
        description,
        required: is_required,
        variadic: is_variadic,
        arg_type,
        placeholder,
    })
}

/// Infer argument type from name and placeholder.
fn infer_argument_type(name: &str, placeholder: Option<&str>) -> Option<ArgumentType> {
    let name_upper = name.to_uppercase();

    // Check name patterns
    if name_upper.contains("FILE") || name_upper.contains("PATH") || name_upper.contains("DIR") {
        return Some(ArgumentType::Path);
    }
    if name_upper.contains("URL") {
        return Some(ArgumentType::Url);
    }
    if name_upper.contains("EMAIL") {
        return Some(ArgumentType::Email);
    }
    if name_upper.contains("PORT") || name_upper.contains("NUM") || name_upper.contains("COUNT") {
        return Some(ArgumentType::Number);
    }

    // Check placeholder patterns
    if let Some(ph) = placeholder {
        let ph_lower = ph.to_lowercase();
        if ph_lower.contains("file") || ph_lower.contains("path") || ph_lower.contains("dir") {
            return Some(ArgumentType::Path);
        }
        if ph_lower.contains("url") {
            return Some(ArgumentType::Url);
        }
        if ph_lower.contains("email") {
            return Some(ArgumentType::Email);
        }
        if ph_lower.contains("port") || ph_lower.contains("num") {
            return Some(ArgumentType::Number);
        }
    }

    // Default to String if we can't infer
    Some(ArgumentType::String)
}

/// Extract enhanced metadata from an option flag part and description.
/// Returns: (takes_argument, argument_name, option_type, choices)
fn extract_option_metadata(
    flag_part: &str,
    description: Option<&str>,
) -> (bool, Option<String>, OptionType, Vec<String>) {
    // Check if option takes an argument by looking for patterns in flag_part
    // Patterns: --file <FILE>, --output=<PATH>, --level {debug|info|warn}

    // Check for argument patterns: <ARG>, [ARG], =ARG, {choice1|choice2|choice3}
    // Note: =ARG pattern - match = followed by non-whitespace, non-comma characters
    // Use separate patterns to avoid regex issues
    // Escape braces: { and } are special in regex
    let choice_pattern = regex::Regex::new(r"\{([^}]+)\}").unwrap();
    let arg_pattern = regex::Regex::new(r"(<([^>]+)>|\[([^\]]+)\]|=\s*([^,\s]+))").unwrap();

    let mut takes_argument = false;
    let mut argument_name = None;
    let choices = Vec::new();

    // First check for choice/enum pattern: {choice1|choice2|choice3}
    // Check both flag_part and description
    let check_choice = |text: &str| -> Option<Vec<String>> {
        if let Some(cap) = choice_pattern.captures(text) {
            if let Some(choices_str) = cap.get(1) {
                let choices_text = choices_str.as_str();
                let ch: Vec<String> = choices_text
                    .split('|')
                    .map(|c| c.trim().to_string())
                    .filter(|c| !c.is_empty())
                    .collect();
                if !ch.is_empty() {
                    return Some(ch);
                }
            }
        }
        None
    };

    if let Some(ch) = check_choice(flag_part) {
        return (true, None, OptionType::Choice, ch);
    }

    if let Some(desc) = description {
        if let Some(ch) = check_choice(desc) {
            return (true, None, OptionType::Choice, ch);
        }
    }

    for cap in arg_pattern.captures_iter(flag_part) {
        takes_argument = true;

        // Extract argument name from <ARG>, [ARG], or =ARG
        if let Some(m) = cap.get(2) {
            argument_name = Some(m.as_str().to_string());
        } else if let Some(m) = cap.get(3) {
            argument_name = Some(m.as_str().to_string());
        } else if let Some(m) = cap.get(4) {
            argument_name = Some(m.as_str().to_string());
        }
    }

    // If no argument pattern found, check description for hints
    if !takes_argument {
        if let Some(desc) = description {
            let desc_lower = desc.to_lowercase();
            // Look for patterns like "takes <FILE>", "requires <PATH>", etc.
            if desc_lower.contains("takes")
                || desc_lower.contains("requires")
                || desc_lower.contains("specify")
            {
                // Try to extract from description
                let desc_arg_pattern = regex::Regex::new(r"<([^>]+)>|\[([^\]]+)\]").unwrap();
                if let Some(cap) = desc_arg_pattern.captures(desc) {
                    takes_argument = true;
                    if let Some(m) = cap.get(1) {
                        argument_name = Some(m.as_str().to_string());
                    } else if let Some(m) = cap.get(2) {
                        argument_name = Some(m.as_str().to_string());
                    }
                }
            }
        }
    }

    // Infer option type
    let option_type = if !choices.is_empty() {
        OptionType::Choice
    } else if takes_argument {
        infer_option_type(argument_name.as_deref(), description)
    } else {
        OptionType::Boolean
    };

    (takes_argument, argument_name, option_type, choices)
}

/// Infer option type from argument name and description.
fn infer_option_type(argument_name: Option<&str>, description: Option<&str>) -> OptionType {
    if let Some(name) = argument_name {
        let name_upper = name.to_uppercase();
        if name_upper.contains("FILE") || name_upper.contains("PATH") || name_upper.contains("DIR")
        {
            return OptionType::Path;
        }
        if name_upper.contains("PORT")
            || name_upper.contains("NUM")
            || name_upper.contains("COUNT")
            || name_upper.contains("SIZE")
        {
            return OptionType::Number;
        }
    }

    if let Some(desc) = description {
        let desc_lower = desc.to_lowercase();
        if desc_lower.contains("file")
            || desc_lower.contains("path")
            || desc_lower.contains("directory")
        {
            return OptionType::Path;
        }
        if desc_lower.contains("port")
            || desc_lower.contains("number")
            || desc_lower.contains("count")
            || desc_lower.contains("numeric")
        {
            return OptionType::Number;
        }
    }

    OptionType::String
}

/// Extract default value from description.
/// Looks for patterns like "default: value", "defaults to value", "(default: value)"
fn extract_default_value(description: Option<&str>) -> Option<String> {
    if let Some(desc) = description {
        // Try various patterns
        let patterns = [
            r"default:\s*([^\s,;)]+)",
            r"defaults?\s+to\s+([^\s,;)]+)",
            r"\(default:\s*([^)]+)\)",
            r"\[default:\s*([^\]]+)\]",
        ];

        for pattern in &patterns {
            let re = regex::Regex::new(pattern).unwrap();
            if let Some(cap) = re.captures(desc) {
                if let Some(m) = cap.get(1) {
                    return Some(m.as_str().trim().to_string());
                }
            }
        }
    }

    None
}

/// Simple heuristic to split an option line into "flags" and "description".
///
/// Examples:
///   "-h, --help    Show help message"
///   "  -v, --verbose   Verbose mode"
///   "--version Print version"
fn split_flag_and_description(line: &str) -> (String, Option<String>) {
    // First try to split on two or more spaces
    let mut best_split: Option<(String, String)> = None;

    // Find first occurrence of "  " (two spaces) or a tab as a separator.
    if let Some(idx) = line.find("  ") {
        let (left, right) = line.split_at(idx);
        let flag_part = left.trim_end().to_string();
        let desc_part = right.trim_start().to_string();
        if !flag_part.is_empty() && !desc_part.is_empty() {
            best_split = Some((flag_part, desc_part));
        }
    } else if let Some(idx) = line.find('\t') {
        let (left, right) = line.split_at(idx);
        let flag_part = left.trim_end().to_string();
        let desc_part = right.trim_start().to_string();
        if !flag_part.is_empty() && !desc_part.is_empty() {
            best_split = Some((flag_part, desc_part));
        }
    }

    if let Some((flags, desc)) = best_split {
        (flags, Some(desc))
    } else {
        // Fallback: no clear separator; treat entire line as flags only
        (line.to_string(), None)
    }
}

/// Attempt to parse subcommands from the full help text (stdout+stderr, as strings).
///
/// Heuristic:
/// - Look for a section header like "SUBCOMMANDS", "Subcommands", "Commands".
/// - Then look at following indented lines of form:
///      subcmd   Description...
///   or:
///      subcmd
///        Longer description...
pub fn parse_subcommands(full_stdout: &str, full_stderr: &str) -> Vec<SubcommandSpec> {
    let lines: Vec<String> = full_stdout
        .lines()
        .map(|s| s.to_string())
        .chain(full_stderr.lines().map(|s| s.to_string()))
        .collect();

    if lines.is_empty() {
        return Vec::new();
    }

    let mut subcommands = Vec::new();

    // Find indices of possible "subcommands" headers.
    // Support various formats: "SUBCOMMANDS:", "Commands:", "Management Commands:", etc.
    let mut header_indices = Vec::new();
    for (idx, line) in lines.iter().enumerate() {
        let l = line.trim().to_lowercase();
        // Exact matches
        if l == "subcommands:" || l == "subcommands" || l == "commands:" || l == "commands" {
            header_indices.push(idx);
        }
        // Pattern matches for variations like "Management Commands:", "Basic Commands (Beginner):"
        else if l.ends_with("commands:") || l.ends_with("commands") {
            // Check if it's actually a commands section (not something like "options")
            if !l.contains("option") {
                header_indices.push(idx);
            }
        }
    }

    // Also try to find subcommands in lists without explicit headers
    // (e.g., "Some common cargo commands are:" followed by indented command names)
    let list_subcommands = find_subcommands_in_lists(&lines);

    if header_indices.is_empty() {
        // If no explicit headers found, return list-based subcommands if any
        return list_subcommands;
    }

    // For each header, inspect following lines until blank line or non-indented.
    for header_idx in header_indices {
        let mut i = header_idx + 1;
        while i < lines.len() {
            let raw = &lines[i];
            let line = raw.trim_end();

            if line.trim().is_empty() {
                break;
            }

            // We expect some indentation before subcommand name
            // e.g. "  build   Compile the current package"
            let trimmed_start = line.trim_start();
            // If there's no leading indent at all and no spaces, likely not a subcommand block.
            if raw == trimmed_start {
                // No indentation; this probably means the section ended.
                break;
            }

            // Attempt: split into "name" and "description"
            let mut parts = trimmed_start.splitn(2, char::is_whitespace);
            let mut name = parts.next().unwrap_or("").trim().to_string();
            let rest = parts.next().unwrap_or("").trim().to_string();

            if name.is_empty() {
                i += 1;
                continue;
            }

            // Clean up name: remove trailing commas and other punctuation
            // Cargo format: "build, b    Description" -> "build"
            name = name.trim_end_matches(',').trim().to_string();

            // Stop if the "name" looks like an option (starts with '-')
            if name.starts_with('-') {
                i += 1;
                continue;
            }

            // Skip invalid names like "..." or empty after cleaning
            if name == "..." || name.is_empty() {
                i += 1;
                continue;
            }

            let mut description = if rest.is_empty() { None } else { Some(rest) };

            // Optional: capture one more indented description line if present.
            // A continuation line should be MORE indented than the current line's content.
            let current_indent = raw.len() - trimmed_start.len();
            let j = i + 1;
            if j < lines.len() {
                let next_raw = &lines[j];
                let next_trimmed = next_raw.trim_start();
                let next_indent = next_raw.len() - next_trimmed.len();

                // Only treat as continuation if:
                // 1. It's not empty
                // 2. It's indented (more than the current line's content)
                // 3. It doesn't start with '-' (not an option)
                // 4. It's more indented than the current line (actual continuation)
                if !next_trimmed.is_empty()
                    && next_raw != next_trimmed
                    && !next_trimmed.starts_with('-')
                    && next_indent > current_indent
                {
                    // Consider this a continuation of the description.
                    let extra = next_trimmed.to_string();
                    description = Some(match description {
                        Some(existing) => format!("{existing} {extra}"),
                        None => extra,
                    });
                    i = j; // skip the continuation line as well
                }
            }

            // Use cleaned name for the subcommand
            let sc_name = name.clone();
            subcommands.push(SubcommandSpec {
                name: sc_name.clone(),
                description,
                full_path: sc_name,
                parent: None,
                options: Vec::new(),
                arguments: Vec::new(),
                subcommands: Vec::new(),
            });

            i += 1;
        }
    }

    // Merge with list-based subcommands, avoiding duplicates
    for list_sub in list_subcommands {
        if !subcommands.iter().any(|s| s.name == list_sub.name) {
            subcommands.push(list_sub);
        }
    }

    subcommands
}

/// Find subcommands in lists without explicit "SUBCOMMANDS:" headers.
/// This handles formats like:
///   "Some common cargo commands are:"
///   "    build       Compile the current package"
///   "    run         Run a binary"
fn find_subcommands_in_lists(lines: &[String]) -> Vec<SubcommandSpec> {
    let mut subcommands = Vec::new();

    // Look for patterns like "commands are:", "available commands:", etc.
    for (idx, line) in lines.iter().enumerate() {
        let lower = line.trim().to_lowercase();

        // Check if this line suggests a command list
        if (lower.contains("commands") && (lower.contains("are") || lower.contains("available")))
            || (lower.contains("common") && lower.contains("commands"))
        {
            // Look at following lines for indented command names
            let mut i = idx + 1;
            while i < lines.len() && i < idx + 50 {
                // Limit search range
                let raw = &lines[i];
                let trimmed = raw.trim_start();

                // Stop on blank line or non-indented line that looks like a section
                if trimmed.is_empty() {
                    if i > idx + 3 {
                        break;
                    }
                    i += 1;
                    continue;
                }

                // Stop if we hit a section header
                let lower_next = trimmed.to_lowercase();
                if (lower_next.ends_with(':') && !trimmed.starts_with(' '))
                    || (lower_next.contains("options") && !trimmed.starts_with(' '))
                {
                    break;
                }

                // Check if line is indented and looks like a command
                if raw != trimmed && !trimmed.starts_with('-') {
                    // Split into name and description
                    let parts: Vec<&str> = trimmed.splitn(2, char::is_whitespace).collect();
                    if let Some(raw_name) = parts.first() {
                        // Clean up name: remove trailing commas and trim
                        let name = raw_name.trim().trim_end_matches(',').trim();
                        // Valid command name: not empty, doesn't start with special chars
                        if !name.is_empty()
                            && name != "..."
                            && !name.starts_with('-')
                            && !name.starts_with('[')
                            && name
                                .chars()
                                .all(|c| c.is_alphanumeric() || c == '-' || c == '_')
                        {
                            let description = parts
                                .get(1)
                                .map(|s| s.trim().to_string())
                                .filter(|s| !s.is_empty());

                            let sc_name = name.to_string();
                            subcommands.push(SubcommandSpec {
                                name: sc_name.clone(),
                                description,
                                full_path: sc_name,
                                parent: None,
                                options: Vec::new(),
                                arguments: Vec::new(),
                                subcommands: Vec::new(),
                            });
                        }
                    }
                } else if raw == trimmed {
                    // Non-indented line, probably end of list
                    break;
                }

                i += 1;
            }
        }
    }

    subcommands
}
/// Parse examples from help text.
///
/// Looks for "Examples:" or "EXAMPLES:" sections and extracts:
/// - Command lines (typically starting with $, >, or the command name)
/// - Descriptions (lines before or after command lines)
/// - Tags (inferred from context or explicit tags)
pub fn parse_examples(stdout: &str, stderr: &str) -> Vec<crate::model::Example> {
    let mut examples = Vec::new();
    let combined = format!("{}\n{}", stdout, stderr);
    let lines: Vec<String> = combined.lines().map(|s| s.to_string()).collect();

    let mut in_examples_section = false;
    let mut section_start_idx = 0;

    for (idx, line) in lines.iter().enumerate() {
        let trimmed = line.trim().to_lowercase();

        // Check if this is an "Examples:" section header
        if trimmed == "examples:"
            || trimmed == "example:"
            || trimmed.starts_with("examples:")
            || trimmed.starts_with("example:")
        {
            in_examples_section = true;
            section_start_idx = idx + 1;
            continue;
        }

        if in_examples_section {
            let trimmed_line = line.trim_start();

            // Stop if we hit a blank line followed by another section header
            if trimmed_line.is_empty() {
                if idx > section_start_idx + 3 {
                    // Check if next non-empty line is a section header
                    let mut found_header = false;
                    for j in (idx + 1)..lines.len().min(idx + 5) {
                        let next_trimmed = lines[j].trim().to_lowercase();
                        if next_trimmed.ends_with(':')
                            && !next_trimmed.starts_with(' ')
                            && !next_trimmed.starts_with('\t')
                        {
                            found_header = true;
                            break;
                        }
                    }
                    if found_header {
                        in_examples_section = false;
                    }
                }
                continue;
            }

            // Stop if we hit another section header
            let lower = trimmed_line.to_lowercase();
            if (lower.ends_with(':')
                || lower.contains("options")
                || lower.contains("commands")
                || lower.contains("arguments"))
                && !trimmed_line.starts_with(' ')
                && !trimmed_line.starts_with('\t')
            {
                in_examples_section = false;
                continue;
            }

            // Look for example command lines
            // Patterns: $ command, > command, command (without leading $/>), or indented command
            let is_command_line = trimmed_line.starts_with('$')
                || trimmed_line.starts_with('>')
                || trimmed_line.starts_with('#')
                || (trimmed_line.len() > 0
                    && !trimmed_line.starts_with('-')
                    && !trimmed_line.starts_with('[')
                    && (trimmed_line.contains(' ') || trimmed_line.len() > 10));

            if is_command_line {
                // Extract command (remove $, >, # prefix and trim)
                let command = trimmed_line
                    .trim_start_matches('$')
                    .trim_start_matches('>')
                    .trim_start_matches('#')
                    .trim()
                    .to_string();

                // Look for description on previous or next lines
                let mut description = None;

                // Check previous line (if it's not a command line)
                if idx > 0 {
                    let prev_line = lines[idx - 1].trim();
                    if !prev_line.is_empty()
                        && !prev_line.starts_with('$')
                        && !prev_line.starts_with('>')
                        && !prev_line.starts_with('#')
                        && prev_line.len() > 10
                    {
                        description = Some(prev_line.to_string());
                    }
                }

                // Check next line (if it's not a command line)
                if description.is_none() && idx + 1 < lines.len() {
                    let next_line = lines[idx + 1].trim();
                    if !next_line.is_empty()
                        && !next_line.starts_with('$')
                        && !next_line.starts_with('>')
                        && !next_line.starts_with('#')
                        && !next_line.starts_with('-')
                        && next_line.len() > 10
                    {
                        description = Some(next_line.to_string());
                    }
                }

                // Infer tags from context
                let mut tags = Vec::new();
                if let Some(desc) = &description {
                    let desc_lower = desc.to_lowercase();
                    if desc_lower.contains("basic") || desc_lower.contains("simple") {
                        tags.push("basic".to_string());
                    }
                    if desc_lower.contains("advanced") || desc_lower.contains("complex") {
                        tags.push("advanced".to_string());
                    }
                    if desc_lower.contains("common") || desc_lower.contains("typical") {
                        tags.push("common".to_string());
                    }
                }

                // If no tags inferred, add "example" as default
                if tags.is_empty() {
                    tags.push("example".to_string());
                }

                examples.push(crate::model::Example {
                    command,
                    description,
                    tags,
                });
            } else if !trimmed_line.starts_with(' ') && !trimmed_line.starts_with('\t') {
                // Non-indented, non-command line - probably end of section
                if idx > section_start_idx + 2 {
                    in_examples_section = false;
                }
            }
        }
    }

    examples
}

/// Parse environment variables from help text.
///
/// Looks for patterns like:
/// - "Can be set via $VAR"
/// - "Uses VAR environment variable"
/// - "VAR (default: value)"
/// - "Set VAR to ..."
/// - Option descriptions mentioning environment variables
pub fn parse_environment_variables(
    stdout: &str,
    stderr: &str,
    options: &[OptionSpec],
) -> Vec<EnvVarSpec> {
    let mut env_vars = Vec::new();
    let combined = format!("{}\n{}", stdout, stderr);
    let lines: Vec<String> = combined.lines().map(|s| s.to_string()).collect();

    // Patterns to detect environment variable mentions
    let env_var_patterns = [
        // $VAR or ${VAR}
        (r"\$([A-Z_][A-Z0-9_]*)", "dollar_sign"),
        (r"\$\{([A-Z_][A-Z0-9_]*)\}", "dollar_brace"),
        // "VAR environment variable" or "VAR env var"
        (
            r"\b([A-Z_][A-Z0-9_]*)\s+(?:environment\s+)?variable",
            "explicit_var",
        ),
        // "Set VAR to" or "VAR can be set"
        (r"(?:set|use|via)\s+([A-Z_][A-Z0-9_]*)", "set_pattern"),
    ];

    // Build a map of option names to flags for mapping
    let mut option_map = std::collections::HashMap::new();
    for opt in options {
        for long_flag in &opt.long_flags {
            let opt_name = long_flag
                .trim_start_matches("--")
                .replace('-', "_")
                .to_uppercase();
            option_map.insert(opt_name.clone(), long_flag.clone());
        }
        for short_flag in &opt.short_flags {
            let opt_name = short_flag.trim_start_matches("-").to_uppercase();
            option_map.insert(opt_name, short_flag.clone());
        }
    }

    // Track found env vars to avoid duplicates
    let mut found_vars = std::collections::HashSet::new();

    for line in &lines {
        let line_lower = line.to_lowercase();

        // Skip if line doesn't seem to mention environment variables
        if !line_lower.contains("environment")
            && !line_lower.contains("env")
            && !line_lower.contains("$")
            && !line_lower.contains("variable")
        {
            continue;
        }

        // Try each pattern
        for (pattern, _pattern_type) in &env_var_patterns {
            let re = regex::Regex::new(pattern).unwrap();
            for cap in re.captures_iter(line) {
                if let Some(var_name) = cap.get(1) {
                    let var_name = var_name.as_str().to_uppercase();

                    // Skip common false positives
                    if var_name.len() < 2
                        || var_name == "THE"
                        || var_name == "CAN"
                        || var_name == "SET"
                    {
                        continue;
                    }

                    if found_vars.contains(&var_name) {
                        continue;
                    }

                    found_vars.insert(var_name.clone());

                    // Try to map to an option
                    let option_mapped = option_map.get(&var_name).cloned();

                    // Extract description (the line itself, or nearby context)
                    let description = if line.len() > var_name.len() + 10 {
                        Some(line.trim().to_string())
                    } else {
                        None
                    };

                    // Try to extract default value
                    let default_value = extract_env_default_value(line);

                    env_vars.push(EnvVarSpec {
                        name: var_name,
                        description,
                        option_mapped,
                        default_value,
                    });
                }
            }
        }

        // Also check for explicit mappings in option descriptions
        for opt in options {
            if let Some(desc) = &opt.description {
                let desc_lower = desc.to_lowercase();
                if desc_lower.contains("environment") || desc_lower.contains("env var") {
                    // Look for VAR pattern in description
                    let var_re = regex::Regex::new(r"\b([A-Z_][A-Z0-9_]{2,})\b").unwrap();
                    for cap in var_re.captures_iter(desc) {
                        let var_name = cap.get(1).unwrap().as_str().to_uppercase();

                        // Skip if it's the option name itself
                        if var_name
                            == opt
                                .long_flags
                                .first()
                                .unwrap_or(&String::new())
                                .trim_start_matches("--")
                                .replace('-', "_")
                                .to_uppercase()
                        {
                            continue;
                        }

                        if !found_vars.contains(&var_name) && var_name.len() >= 3 {
                            found_vars.insert(var_name.clone());

                            let option_mapped = opt.long_flags.first().cloned();

                            env_vars.push(EnvVarSpec {
                                name: var_name,
                                description: Some(desc.clone()),
                                option_mapped,
                                default_value: extract_env_default_value(desc),
                            });
                        }
                    }
                }
            }
        }
    }

    env_vars
}

/// Extract default value from environment variable description.
fn extract_env_default_value(text: &str) -> Option<String> {
    let text_lower = text.to_lowercase();

    // Patterns for default values
    let patterns = [
        r"default[:\s]+([^\s,;)]+)",
        r"defaults?\s+to\s+([^\s,;)]+)",
        r"\(default[:\s]+([^)]+)\)",
    ];

    for pattern in &patterns {
        let re = regex::Regex::new(pattern).unwrap();
        if let Some(cap) = re.captures(&text_lower) {
            if let Some(m) = cap.get(1) {
                return Some(m.as_str().trim().to_string());
            }
        }
    }

    None
}

/// Parse validation rules from help text.
///
/// Extracts validation rules from descriptions, looking for patterns like:
/// - "must be between 1-100" (Range)
/// - "valid email" (Format)
/// - "must match pattern X" (Pattern)
/// - "one of: a, b, c" (Choice)
pub fn parse_validation_rules(
    _stdout: &str,
    _stderr: &str,
    options: &[OptionSpec],
    arguments: &[ArgumentSpec],
) -> Vec<ValidationRule> {
    let mut rules = Vec::new();

    // Extract rules from option descriptions
    for opt in options {
        if let Some(desc) = &opt.description {
            if let Some(rule) = extract_validation_rule_from_description(
                desc,
                &opt.long_flags.first().unwrap_or(&String::new()).clone(),
            ) {
                rules.push(rule);
            }
        }
    }

    // Extract rules from argument descriptions
    for arg in arguments {
        if let Some(desc) = &arg.description {
            if let Some(rule) = extract_validation_rule_from_description(desc, &arg.name) {
                rules.push(rule);
            }
        }

        // Add required rule if argument is required
        if arg.required {
            rules.push(ValidationRule {
                target: arg.name.clone(),
                rule_type: ValidationType::Required,
                pattern: None,
                min: None,
                max: None,
                message: Some(format!("{} is required", arg.name)),
            });
        }

        // Infer format rules from argument types
        if let Some(arg_type) = &arg.arg_type {
            match arg_type {
                ArgumentType::Email => {
                    rules.push(ValidationRule {
                        target: arg.name.clone(),
                        rule_type: ValidationType::Format,
                        pattern: Some(
                            r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$".to_string(),
                        ),
                        min: None,
                        max: None,
                        message: Some("Must be a valid email address".to_string()),
                    });
                }
                ArgumentType::Url => {
                    rules.push(ValidationRule {
                        target: arg.name.clone(),
                        rule_type: ValidationType::Format,
                        pattern: Some(r"^https?://.+".to_string()),
                        min: None,
                        max: None,
                        message: Some("Must be a valid URL".to_string()),
                    });
                }
                ArgumentType::Number => {
                    rules.push(ValidationRule {
                        target: arg.name.clone(),
                        rule_type: ValidationType::Pattern,
                        pattern: Some(r"^\d+(\.\d+)?$".to_string()),
                        min: None,
                        max: None,
                        message: Some("Must be a number".to_string()),
                    });
                }
                _ => {}
            }
        }
    }

    // Extract choice rules from options with choices
    for opt in options {
        if !opt.choices.is_empty() {
            let target = opt.long_flags.first().unwrap_or(&String::new()).clone();
            rules.push(ValidationRule {
                target: target.clone(),
                rule_type: ValidationType::Choice,
                pattern: None,
                min: None,
                max: None,
                message: Some(format!("Must be one of: {}", opt.choices.join(", "))),
            });
        }
    }

    rules
}

/// Extract validation rule from a description string.
fn extract_validation_rule_from_description(desc: &str, target: &str) -> Option<ValidationRule> {
    let desc_lower = desc.to_lowercase();

    // Check for range patterns: "between 1-100", "1 to 100", "must be 1-100"
    let range_pattern = regex::Regex::new(
        r"(?:between|from|range|must be)\s+(\d+(?:\.\d+)?)\s*(?:-|to)\s*(\d+(?:\.\d+)?)",
    )
    .unwrap();
    if let Some(cap) = range_pattern.captures(&desc_lower) {
        if let (Some(min_str), Some(max_str)) = (cap.get(1), cap.get(2)) {
            if let (Ok(min), Ok(max)) = (
                min_str.as_str().parse::<f64>(),
                max_str.as_str().parse::<f64>(),
            ) {
                return Some(ValidationRule {
                    target: target.to_string(),
                    rule_type: ValidationType::Range,
                    pattern: None,
                    min: Some(min),
                    max: Some(max),
                    message: Some(format!("Must be between {} and {}", min, max)),
                });
            }
        }
    }

    // Check for min/max separately: "minimum 1", "max 100"
    let min_pattern = regex::Regex::new(r"(?:minimum|min|at least|>=)\s+(\d+(?:\.\d+)?)").unwrap();
    let max_pattern = regex::Regex::new(r"(?:maximum|max|at most|<=)\s+(\d+(?:\.\d+)?)").unwrap();

    let min = min_pattern
        .captures(&desc_lower)
        .and_then(|c| c.get(1))
        .and_then(|m| m.as_str().parse::<f64>().ok());
    let max = max_pattern
        .captures(&desc_lower)
        .and_then(|c| c.get(1))
        .and_then(|m| m.as_str().parse::<f64>().ok());

    if min.is_some() || max.is_some() {
        return Some(ValidationRule {
            target: target.to_string(),
            rule_type: ValidationType::Range,
            pattern: None,
            min,
            max,
            message: Some(desc.to_string()),
        });
    }

    // Check for format patterns: "valid email", "valid URL", "valid path"
    if desc_lower.contains("valid email") || desc_lower.contains("email address") {
        return Some(ValidationRule {
            target: target.to_string(),
            rule_type: ValidationType::Format,
            pattern: Some(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$".to_string()),
            min: None,
            max: None,
            message: Some("Must be a valid email address".to_string()),
        });
    }

    if desc_lower.contains("valid url") || desc_lower.contains("url") {
        return Some(ValidationRule {
            target: target.to_string(),
            rule_type: ValidationType::Format,
            pattern: Some(r"^https?://.+".to_string()),
            min: None,
            max: None,
            message: Some("Must be a valid URL".to_string()),
        });
    }

    // Check for pattern mentions: "must match pattern", "regex", etc.
    let pattern_mention =
        regex::Regex::new(r"(?:pattern|regex|match|format)\s*[:=]\s*([^\s,;)]+)").unwrap();
    if let Some(cap) = pattern_mention.captures(desc) {
        if let Some(pattern) = cap.get(1) {
            return Some(ValidationRule {
                target: target.to_string(),
                rule_type: ValidationType::Pattern,
                pattern: Some(pattern.as_str().to_string()),
                min: None,
                max: None,
                message: Some(desc.to_string()),
            });
        }
    }

    None
}