clap_sort/

lib.rs

//! # clap-sort
//!
//! A library to validate that clap subcommands and arguments are sorted.
//!
//! This crate provides functionality to validate that:
//! - Subcommands are sorted alphabetically
//! - Arguments are grouped and sorted by type:
//!   1. Positional arguments (order not enforced - parsing order matters)
//!   2. Flags with short options (alphabetically by short option)
//!   3. Long-only flags (alphabetically)

/// Validates that subcommands and arguments are sorted correctly.
///
/// This checks:
/// - Subcommands are sorted alphabetically
/// - Arguments are grouped and sorted by type:
///   1. Positional arguments (order not enforced)
///   2. Flags with short options (alphabetically by short option)
///   3. Long-only flags (alphabetically)
///
/// Recursively validates all subcommands.
///
/// # Panics
/// Panics if subcommands or arguments are not properly sorted.
///
/// # Example
///
/// ```rust
/// use clap::{Command, Arg};
///
/// let cmd = Command::new("mycli")
///     .arg(Arg::new("file"))  // Positional
///     .arg(Arg::new("output").short('o').long("output"))  // Short flag
///     .arg(Arg::new("config").long("config"));  // Long-only flag
///
/// clap_sort::assert_sorted(&cmd);
/// ```
pub fn assert_sorted(cmd: &clap::Command) {
    assert_sorted_with_path(cmd, vec![]);
}

fn assert_sorted_with_path(cmd: &clap::Command, parent_path: Vec<&str>) {
    let mut current_path = parent_path.clone();
    current_path.push(cmd.get_name());

    // Check subcommands
    let subcommands: Vec<_> = cmd.get_subcommands().map(|s| s.get_name()).collect();

    if !subcommands.is_empty() {
        let mut sorted = subcommands.clone();
        sorted.sort();

        if subcommands != sorted {
            panic!(
                "Subcommands in '{}' are not sorted alphabetically!\nActual order: {:?}\nExpected order: {:?}",
                current_path.join(" "),
                subcommands,
                sorted
            );
        }
    }

    // Check arguments
    assert_arguments_sorted_with_path(cmd, &current_path);

    // Recursively check subcommands
    for subcmd in cmd.get_subcommands() {
        assert_sorted_with_path(subcmd, current_path.clone());
    }
}

/// Checks if subcommands and arguments are sorted, returning a Result instead of panicking.
///
/// This checks:
/// - Subcommands are sorted alphabetically
/// - Arguments are grouped and sorted by type
///
/// Recursively validates all subcommands.
///
/// # Example
///
/// ```rust
/// use clap::Command;
///
/// let cmd = Command::new("mycli");
/// match clap_sort::is_sorted(&cmd) {
///     Ok(()) => println!("Everything is sorted!"),
///     Err(msg) => eprintln!("Error: {}", msg),
/// }
/// ```
pub fn is_sorted(cmd: &clap::Command) -> Result<(), String> {
    is_sorted_with_path(cmd, vec![])
}

fn is_sorted_with_path(cmd: &clap::Command, parent_path: Vec<&str>) -> Result<(), String> {
    let mut current_path = parent_path.clone();
    current_path.push(cmd.get_name());

    // Check subcommands
    let subcommands: Vec<_> = cmd.get_subcommands().map(|s| s.get_name()).collect();

    if !subcommands.is_empty() {
        let mut sorted = subcommands.clone();
        sorted.sort();

        if subcommands != sorted {
            return Err(format!(
                "Subcommands in '{}' are not sorted alphabetically!\nActual order: {:?}\nExpected order: {:?}",
                current_path.join(" "),
                subcommands,
                sorted
            ));
        }
    }

    // Check arguments
    is_arguments_sorted_with_path(cmd, &current_path)?;

    // Recursively check subcommands
    for subcmd in cmd.get_subcommands() {
        is_sorted_with_path(subcmd, current_path.clone())?;
    }

    Ok(())
}

/// Internal function to assert arguments are sorted.
fn assert_arguments_sorted_with_path(cmd: &clap::Command, path: &[&str]) {
    if let Err(msg) = is_arguments_sorted_with_path(cmd, path) {
        panic!("{}", msg);
    }
}

/// Checks if arguments are sorted correctly, returning a Result.
fn is_arguments_sorted_with_path(cmd: &clap::Command, path: &[&str]) -> Result<(), String> {
    let args: Vec<_> = cmd.get_arguments().collect();

    let mut positional = Vec::new();
    let mut with_short = Vec::new();
    let mut long_only = Vec::new();

    for arg in &args {
        if arg.is_positional() {
            positional.push(*arg);
        } else if arg.get_short().is_some() {
            with_short.push(*arg);
        } else if arg.get_long().is_some() {
            long_only.push(*arg);
        }
    }

    // Note: We don't check if positional args are sorted - their order matters for parsing

    // Check short flags are sorted by short option
    let with_short_shorts: Vec<char> = with_short.iter().filter_map(|a| a.get_short()).collect();
    let mut sorted_shorts = with_short_shorts.clone();
    sorted_shorts.sort_by(|a, b| {
        let a_lower = a.to_ascii_lowercase();
        let b_lower = b.to_ascii_lowercase();
        match a_lower.cmp(&b_lower) {
            std::cmp::Ordering::Equal => {
                // Lowercase before uppercase for same letter
                if a.is_lowercase() && b.is_uppercase() {
                    std::cmp::Ordering::Less
                } else if a.is_uppercase() && b.is_lowercase() {
                    std::cmp::Ordering::Greater
                } else {
                    std::cmp::Ordering::Equal
                }
            }
            other => other,
        }
    });

    if with_short_shorts != sorted_shorts {
        let current: Vec<String> = with_short
            .iter()
            .map(|a| format!("-{}", a.get_short().unwrap()))
            .collect();
        let mut sorted_args = with_short.clone();
        sorted_args.sort_by(|a, b| {
            let a_char = a.get_short().unwrap();
            let b_char = b.get_short().unwrap();
            let a_lower = a_char.to_ascii_lowercase();
            let b_lower = b_char.to_ascii_lowercase();
            match a_lower.cmp(&b_lower) {
                std::cmp::Ordering::Equal => {
                    if a_char.is_lowercase() && b_char.is_uppercase() {
                        std::cmp::Ordering::Less
                    } else if a_char.is_uppercase() && b_char.is_lowercase() {
                        std::cmp::Ordering::Greater
                    } else {
                        std::cmp::Ordering::Equal
                    }
                }
                other => other,
            }
        });
        let expected: Vec<String> = sorted_args
            .iter()
            .map(|a| format!("-{}", a.get_short().unwrap()))
            .collect();

        return Err(format!(
            "Flags with short options in '{}' are not sorted!\nActual: {:?}\nExpected: {:?}",
            path.join(" "),
            current,
            expected
        ));
    }

    // Check long-only flags are sorted
    let long_only_longs: Vec<&str> = long_only.iter().filter_map(|a| a.get_long()).collect();
    let mut sorted_longs = long_only_longs.clone();
    sorted_longs.sort_unstable();

    if long_only_longs != sorted_longs {
        let current: Vec<String> = long_only_longs.iter().map(|l| format!("--{}", l)).collect();
        let expected: Vec<String> = sorted_longs.iter().map(|l| format!("--{}", l)).collect();

        return Err(format!(
            "Long-only flags in '{}' are not sorted!\nActual: {:?}\nExpected: {:?}",
            path.join(" "),
            current,
            expected
        ));
    }

    // Skip group order checking when flattened structs are involved
    // Flattened structs can cause positionals and flags to be interspersed,
    // which is valid for clap but would fail a strict group order check.
    // We only care that within each group (positionals, short flags, long-only flags),
    // the items are sorted correctly.

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use clap::{Command, CommandFactory, Parser, Subcommand};

    #[test]
    fn test_sorted_subcommands() {
        let cmd = Command::new("test")
            .subcommand(Command::new("add"))
            .subcommand(Command::new("delete"))
            .subcommand(Command::new("list"));

        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "are not sorted alphabetically")]
    fn test_unsorted_subcommands() {
        let cmd = Command::new("test")
            .subcommand(Command::new("list"))
            .subcommand(Command::new("add"))
            .subcommand(Command::new("delete"));

        assert_sorted(&cmd);
    }

    #[test]
    fn test_is_sorted_ok() {
        let cmd = Command::new("test")
            .subcommand(Command::new("add"))
            .subcommand(Command::new("delete"))
            .subcommand(Command::new("list"));

        assert!(is_sorted(&cmd).is_ok());
    }

    #[test]
    fn test_is_sorted_err() {
        let cmd = Command::new("test")
            .subcommand(Command::new("list"))
            .subcommand(Command::new("add"));

        assert!(is_sorted(&cmd).is_err());
    }

    #[test]
    fn test_no_subcommands() {
        let cmd = Command::new("test");
        assert_sorted(&cmd);
        assert!(is_sorted(&cmd).is_ok());
    }

    #[test]
    fn test_with_derive_sorted() {
        #[derive(Parser)]
        struct Cli {
            #[command(subcommand)]
            command: Commands,
        }

        #[derive(Subcommand)]
        enum Commands {
            Add,
            Delete,
            List,
        }

        let cmd = Cli::command();
        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "are not sorted alphabetically")]
    fn test_with_derive_unsorted() {
        #[derive(Parser)]
        struct Cli {
            #[command(subcommand)]
            command: Commands,
        }

        #[derive(Subcommand)]
        enum Commands {
            List,
            Add,
            Delete,
        }

        let cmd = Cli::command();
        assert_sorted(&cmd);
    }

    // Tests for argument sorting

    #[test]
    fn test_arguments_correctly_sorted() {
        use clap::{Arg, ArgAction};

        let cmd = Command::new("test")
            .arg(Arg::new("file")) // Positional
            .arg(
                Arg::new("debug")
                    .short('d')
                    .long("debug")
                    .action(ArgAction::SetTrue),
            )
            .arg(Arg::new("output").short('o').long("output"))
            .arg(
                Arg::new("verbose")
                    .short('v')
                    .long("verbose")
                    .action(ArgAction::SetTrue),
            )
            .arg(Arg::new("config").long("config"))
            .arg(
                Arg::new("no-color")
                    .long("no-color")
                    .action(ArgAction::SetTrue),
            );

        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "Flags with short options")]
    fn test_short_flags_unsorted() {
        use clap::Arg;

        let cmd = Command::new("test")
            .arg(Arg::new("verbose").short('v').long("verbose"))
            .arg(Arg::new("debug").short('d').long("debug"));

        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "Long-only flags")]
    fn test_long_only_unsorted() {
        use clap::{Arg, ArgAction};

        let cmd = Command::new("test")
            .arg(Arg::new("zebra").long("zebra").action(ArgAction::SetTrue))
            .arg(Arg::new("alpha").long("alpha").action(ArgAction::SetTrue));

        assert_sorted(&cmd);
    }

    #[test]
    fn test_positional_order_not_enforced() {
        // Positional arguments can be in any order since their order matters for parsing
        let cmd = Command::new("test")
            .arg(clap::Arg::new("second"))
            .arg(clap::Arg::new("first"));

        assert_sorted(&cmd);
    }

    #[test]
    fn test_is_sorted_ok_with_args() {
        use clap::Arg;

        let cmd = Command::new("test")
            .arg(Arg::new("file"))
            .arg(Arg::new("output").short('o').long("output"))
            .arg(Arg::new("config").long("config"))
            .subcommand(Command::new("add"))
            .subcommand(Command::new("delete"));

        assert!(is_sorted(&cmd).is_ok());
    }

    #[test]
    fn test_is_sorted_err_args() {
        use clap::Arg;

        let cmd = Command::new("test")
            .arg(Arg::new("zebra").short('z').long("zebra"))
            .arg(Arg::new("alpha").short('a').long("alpha"));

        assert!(is_sorted(&cmd).is_err());
    }

    #[test]
    fn test_recursive_subcommand_args() {
        use clap::{Arg, ArgAction};

        let cmd = Command::new("test")
            .arg(
                Arg::new("verbose")
                    .short('v')
                    .long("verbose")
                    .action(ArgAction::SetTrue),
            )
            .subcommand(
                Command::new("sub")
                    .arg(
                        Arg::new("debug")
                            .short('d')
                            .long("debug")
                            .action(ArgAction::SetTrue),
                    )
                    .arg(Arg::new("output").short('o').long("output")),
            );

        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "Flags with short options")]
    fn test_recursive_subcommand_args_fails() {
        use clap::Arg;

        let cmd = Command::new("test").subcommand(
            Command::new("sub")
                .arg(Arg::new("output").short('o').long("output"))
                .arg(Arg::new("debug").short('d').long("debug")),
        );

        assert_sorted(&cmd);
    }

    #[test]
    fn test_global_flags_not_checked_in_subcommands() {
        use clap::{Arg, ArgAction};

        // Global flag 'v' should not interfere with subcommand's 'd' flag ordering
        let cmd = Command::new("test")
            .arg(
                Arg::new("verbose")
                    .short('v')
                    .long("verbose")
                    .global(true)
                    .action(ArgAction::SetTrue),
            )
            .subcommand(
                Command::new("sub")
                    .arg(
                        Arg::new("debug")
                            .short('d')
                            .long("debug")
                            .action(ArgAction::SetTrue),
                    )
                    .arg(Arg::new("output").short('o').long("output")),
            );

        // Should not panic - we only check non-global args in subcommands
        assert_sorted(&cmd);
    }

    #[test]
    fn test_global_flags_dont_appear_in_subcommand_args() {
        use clap::{Arg, ArgAction};

        // Verify that global flags don't appear in subcommand's get_arguments()
        // This confirms there's no bug with global flags interfering with sorting
        let cmd = Command::new("test")
            .arg(
                Arg::new("verbose")
                    .short('v')
                    .long("verbose")
                    .global(true)
                    .action(ArgAction::SetTrue),
            )
            .subcommand(
                Command::new("sub")
                    .arg(
                        Arg::new("debug")
                            .short('d')
                            .long("debug")
                            .action(ArgAction::SetTrue),
                    )
                    .arg(Arg::new("output").short('o').long("output")),
            );

        let subcmd = cmd.find_subcommand("sub").unwrap();
        let args: Vec<_> = subcmd.get_arguments().collect();

        // Subcommand should only see its own 2 args, not the global flag
        assert_eq!(args.len(), 2);

        // Verify neither arg is global
        for arg in &args {
            assert!(
                !arg.is_global_set(),
                "Subcommand arg {} should not be global",
                arg.get_id()
            );
        }

        // Should pass - subcommand args are sorted and global flag doesn't interfere
        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "Flags with short options")]
    fn test_uppercase_before_lowercase_same_letter() {
        use clap::Arg;

        // Uppercase I before lowercase i - should fail
        let cmd = Command::new("test")
            .arg(Arg::new("index").short('I').long("index"))
            .arg(Arg::new("inject").short('i').long("inject"));

        assert_sorted(&cmd);
    }

    #[test]
    fn test_lowercase_before_uppercase_same_letter() {
        use clap::Arg;

        // Lowercase i before uppercase I - should pass
        let cmd = Command::new("test")
            .arg(Arg::new("inject").short('i').long("inject"))
            .arg(Arg::new("index").short('I').long("index"));

        assert_sorted(&cmd);
    }

    #[test]
    #[should_panic(expected = "Flags with short options")]
    fn test_task_docs_flags_unsorted() {
        use clap::Arg;

        // Reproduces the task_docs issue: -I before -i
        let cmd = Command::new("generate").subcommand(
            Command::new("task-docs")
                .arg(Arg::new("index").short('I').long("index"))
                .arg(Arg::new("inject").short('i').long("inject"))
                .arg(Arg::new("multi").short('m').long("multi"))
                .arg(Arg::new("output").short('o').long("output"))
                .arg(Arg::new("root").short('r').long("root"))
                .arg(Arg::new("style").short('s').long("style")),
        );

        assert_sorted(&cmd);
    }

    #[test]
    fn test_error_message_shows_full_command_path() {
        use clap::Arg;

        // Test that error message shows the full command path
        let cmd = Command::new("parent-has-no-flags").subcommand(
            Command::new("child-has-unsorted-flags")
                .arg(Arg::new("zebra").short('z').long("zebra"))
                .arg(Arg::new("alpha").short('a').long("alpha")),
        );

        let result = is_sorted(&cmd);
        assert!(result.is_err());
        let err = result.unwrap_err();

        // Should show full path: 'parent-has-no-flags child-has-unsorted-flags'
        assert!(
            err.contains("parent-has-no-flags child-has-unsorted-flags"),
            "Error message should contain full path, got: {}",
            err
        );
    }

    #[test]
    fn test_error_with_derive_api_nested_subcommands() {
        use clap::{Args, Parser, Subcommand};

        #[derive(Parser)]
        struct Cli {
            #[command(subcommand)]
            command: Commands,
        }

        #[derive(Subcommand)]
        enum Commands {
            /// Generate command
            Generate(GenerateArgs),
        }

        #[derive(Args)]
        struct GenerateArgs {
            #[command(subcommand)]
            command: GenerateCommands,
        }

        #[derive(Subcommand)]
        enum GenerateCommands {
            /// Task docs subcommand
            TaskDocs(TaskDocsArgs),
        }

        #[derive(Args)]
        struct TaskDocsArgs {
            /// task flag
            #[arg(short, long)]
            task: Option<String>,

            /// output flag
            #[arg(short, long)]
            output: Option<String>,
        }

        let cmd = Cli::command();
        let result = is_sorted(&cmd);

        if let Err(e) = result {
            // The error should show the full path
            eprintln!("Error message: {}", e);
            // Since the root command is the Cli, and we have Generate, then TaskDocs,
            // the full path would be something like "Cli Generate TaskDocs" but clap
            // converts names to kebab-case, so it would be "cli generate task-docs"
            // Actually, let me just check it contains both generate and task-docs
            assert!(
                e.contains("task-docs"),
                "Error should mention 'task-docs'. Got: {}",
                e
            );
            assert!(
                e.contains("[\"-t\", \"-o\"]"),
                "Error should show the actual unsorted flags. Got: {}",
                e
            );
        } else {
            panic!("Expected error for unsorted flags");
        }
    }
}