openapi_clap/

builder.rs

//! IR → clap Command tree builder
//!
//! Converts `ApiOperation`s into a clap `Command` tree grouped by tags.

use std::collections::{BTreeMap, HashMap};

use clap::{Arg, ArgAction, Command};

use crate::spec::{is_bool_schema, ApiOperation};

/// Configuration for building a CLI from an OpenAPI spec.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct CliConfig {
    /// Root command name (e.g. "runpod", "myapi")
    pub name: String,
    /// Root command about/description
    pub about: String,
    /// Default base URL for the API
    pub default_base_url: String,
}

impl CliConfig {
    pub fn new(
        name: impl Into<String>,
        about: impl Into<String>,
        default_base_url: impl Into<String>,
    ) -> Self {
        Self {
            name: name.into(),
            about: about.into(),
            default_base_url: default_base_url.into(),
        }
    }
}

/// Build a clap `Command` tree from a list of API operations.
///
/// Structure: `<name> <group> <operation> [args] [--options]`
/// Groups are derived from OpenAPI tags (e.g. "pods", "endpoints").
pub fn build_commands(config: &CliConfig, ops: &[ApiOperation]) -> Command {
    let root = Command::new(config.name.clone())
        .about(config.about.clone())
        .subcommand_required(true)
        .arg_required_else_help(true)
        .arg(
            Arg::new("base-url")
                .long("base-url")
                .global(true)
                .default_value(config.default_base_url.clone())
                .help("API base URL"),
        )
        .arg(
            Arg::new("output")
                .long("output")
                .short('o')
                .global(true)
                .default_value("json")
                .help("Output format: json, compact"),
        );

    // Group operations by tag
    let mut groups: BTreeMap<String, Vec<&ApiOperation>> = BTreeMap::new();
    for op in ops {
        groups.entry(op.group.clone()).or_default().push(op);
    }

    let mut root = root;
    for (group_name, group_ops) in &groups {
        let mut group_cmd = Command::new(normalize_group(group_name))
            .about(format!("Manage {group_name}"))
            .subcommand_required(true)
            .arg_required_else_help(true);

        // Detect duplicate normalized names within this group
        let mut name_count: HashMap<String, usize> = HashMap::new();
        for op in group_ops {
            *name_count
                .entry(normalize_operation_id(&op.operation_id))
                .or_default() += 1;
        }

        for op in group_ops {
            let base_name = normalize_operation_id(&op.operation_id);
            let cmd_name = if name_count.get(&base_name).copied().unwrap_or(0) > 1 {
                format!("{}-{}", base_name, op.method.to_lowercase())
            } else {
                base_name
            };
            group_cmd = group_cmd.subcommand(build_operation_command(op, &cmd_name));
        }

        root = root.subcommand(group_cmd);
    }

    root
}

/// Find the matching `ApiOperation` for a resolved group + operation name.
pub fn find_operation<'a>(
    ops: &'a [ApiOperation],
    group_name: &str,
    op_name: &str,
) -> Option<&'a ApiOperation> {
    ops.iter().find(|o| {
        let base = normalize_operation_id(&o.operation_id);
        let with_method = format!("{}-{}", base, o.method.to_lowercase());
        (base == op_name || with_method == op_name) && normalize_group(&o.group) == group_name
    })
}

fn build_operation_command(op: &ApiOperation, cmd_name: &str) -> Command {
    let mut cmd = Command::new(cmd_name.to_owned()).about(op.summary.clone());

    // Path parameters → positional args
    for param in &op.path_params {
        cmd = cmd.arg(
            Arg::new(param.name.clone())
                .help(param.description.clone())
                .required(true),
        );
    }

    // Query parameters → --flag options
    for param in &op.query_params {
        let arg = Arg::new(param.name.clone())
            .long(param.name.clone())
            .help(param.description.clone())
            .required(param.required);

        let arg = if is_bool_schema(&param.schema) {
            arg.action(ArgAction::SetTrue)
        } else {
            arg.action(ArgAction::Set)
        };

        cmd = cmd.arg(arg);
    }

    // Header parameters → --header-name options
    for param in &op.header_params {
        cmd = cmd.arg(
            Arg::new(param.name.clone())
                .long(param.name.clone())
                .help(param.description.clone())
                .required(param.required)
                .action(ArgAction::Set),
        );
    }

    // Request body → --json or --field options
    if op.body_schema.is_some() {
        cmd = cmd
            .arg(
                Arg::new("json-body")
                    .long("json")
                    .short('j')
                    .help("Request body as JSON string")
                    .action(ArgAction::Set),
            )
            .arg(
                Arg::new("field")
                    .long("field")
                    .short('f')
                    .help("Set body field: key=value (repeatable)")
                    .action(ArgAction::Append),
            );
    }

    cmd
}

pub fn normalize_group(name: &str) -> String {
    let mut result = String::with_capacity(name.len());
    for c in name.chars() {
        if c.is_alphanumeric() {
            result.push(c.to_ascii_lowercase());
        } else if !result.is_empty() && !result.ends_with('-') {
            result.push('-');
        }
    }
    while result.ends_with('-') {
        result.pop();
    }
    result
}

pub fn normalize_operation_id(s: &str) -> String {
    let chars: Vec<char> = s.chars().collect();
    let mut result = String::with_capacity(s.len() + 4);
    for i in 0..chars.len() {
        let c = chars[i];
        if c.is_uppercase() {
            if i > 0 {
                let prev = chars[i - 1];
                let next_is_lower = chars.get(i + 1).is_some_and(|n| n.is_lowercase());
                if prev.is_lowercase() || (prev.is_uppercase() && next_is_lower) {
                    result.push('-');
                }
            }
            result.push(c.to_ascii_lowercase());
        } else {
            result.push(c);
        }
    }
    result
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::spec::{ApiOperation, Param};
    use serde_json::json;

    fn make_operation(operation_id: &str, method: &str, path: &str, group: &str) -> ApiOperation {
        ApiOperation {
            operation_id: operation_id.to_string(),
            method: method.to_string(),
            path: path.to_string(),
            group: group.to_string(),
            summary: String::new(),
            path_params: Vec::new(),
            query_params: Vec::new(),
            header_params: Vec::new(),
            body_schema: None,
            body_required: false,
        }
    }

    // -- normalize_operation_id --

    #[test]
    fn normalize_operation_id_pascal_case() {
        assert_eq!(normalize_operation_id("CreatePod"), "create-pod");
    }

    #[test]
    fn normalize_operation_id_camel_case() {
        assert_eq!(normalize_operation_id("getPods"), "get-pods");
    }

    #[test]
    fn normalize_operation_id_already_lowercase() {
        assert_eq!(normalize_operation_id("list"), "list");
    }

    #[test]
    fn normalize_operation_id_consecutive_uppercase() {
        assert_eq!(normalize_operation_id("getHTTPStatus"), "get-http-status");
    }

    #[test]
    fn normalize_operation_id_acronym_at_start() {
        assert_eq!(normalize_operation_id("HTMLParser"), "html-parser");
    }

    #[test]
    fn normalize_operation_id_acronym_at_end() {
        assert_eq!(normalize_operation_id("getAPI"), "get-api");
    }

    #[test]
    fn normalize_operation_id_empty() {
        assert_eq!(normalize_operation_id(""), "");
    }

    // -- normalize_group --

    #[test]
    fn normalize_group_with_spaces() {
        assert_eq!(normalize_group("My Group"), "my-group");
    }

    #[test]
    fn normalize_group_already_lowercase() {
        assert_eq!(normalize_group("pods"), "pods");
    }

    #[test]
    fn normalize_group_uppercase() {
        assert_eq!(normalize_group("PODS"), "pods");
    }

    #[test]
    fn normalize_group_multiple_spaces() {
        assert_eq!(normalize_group("My Cool Group"), "my-cool-group");
    }

    #[test]
    fn normalize_group_special_characters() {
        assert_eq!(normalize_group("My/Group"), "my-group");
        assert_eq!(normalize_group("My_Group"), "my-group");
        assert_eq!(normalize_group("My..Group"), "my-group");
    }

    // -- build_commands --

    #[test]
    fn build_commands_creates_correct_tree_structure() {
        let ops = vec![
            make_operation("ListPods", "GET", "/pods", "Pods"),
            make_operation("CreatePod", "POST", "/pods", "Pods"),
            make_operation("ListEndpoints", "GET", "/endpoints", "Endpoints"),
        ];

        let config = CliConfig {
            name: "testcli".into(),
            about: "Test CLI".into(),
            default_base_url: "https://api.example.com".into(),
        };

        let cmd = build_commands(&config, &ops);

        assert_eq!(cmd.get_name(), "testcli");

        let subcommands: Vec<&str> = cmd.get_subcommands().map(|c| c.get_name()).collect();
        assert!(subcommands.contains(&"pods"), "should have 'pods' group");
        assert!(
            subcommands.contains(&"endpoints"),
            "should have 'endpoints' group"
        );

        let pods_cmd = cmd
            .get_subcommands()
            .find(|c| c.get_name() == "pods")
            .unwrap();
        let pod_subs: Vec<&str> = pods_cmd.get_subcommands().map(|c| c.get_name()).collect();
        assert!(pod_subs.contains(&"list-pods"), "should have 'list-pods'");
        assert!(pod_subs.contains(&"create-pod"), "should have 'create-pod'");

        let endpoints_cmd = cmd
            .get_subcommands()
            .find(|c| c.get_name() == "endpoints")
            .unwrap();
        let ep_subs: Vec<&str> = endpoints_cmd
            .get_subcommands()
            .map(|c| c.get_name())
            .collect();
        assert!(
            ep_subs.contains(&"list-endpoints"),
            "should have 'list-endpoints'"
        );
    }

    #[test]
    fn build_commands_includes_path_params_as_positional_args() {
        let ops = vec![ApiOperation {
            operation_id: "GetPod".to_string(),
            method: "GET".to_string(),
            path: "/pods/{podId}".to_string(),
            group: "Pods".to_string(),
            summary: "Get a pod".to_string(),
            path_params: vec![Param {
                name: "podId".to_string(),
                description: "Pod ID".to_string(),
                required: true,
                schema: json!({"type": "string"}),
            }],
            query_params: Vec::new(),
            header_params: Vec::new(),
            body_schema: None,
            body_required: false,
        }];

        let config = CliConfig {
            name: "testcli".into(),
            about: "Test".into(),
            default_base_url: "https://example.com".into(),
        };

        let cmd = build_commands(&config, &ops);
        let pods = cmd
            .get_subcommands()
            .find(|c| c.get_name() == "pods")
            .unwrap();
        let get_pod = pods
            .get_subcommands()
            .find(|c| c.get_name() == "get-pod")
            .unwrap();

        let arg = get_pod.get_arguments().find(|a| a.get_id() == "podId");
        assert!(arg.is_some(), "should have podId positional arg");
        assert!(arg.unwrap().is_required_set());
    }

    #[test]
    fn build_commands_includes_body_args_when_body_schema_present() {
        let ops = vec![ApiOperation {
            operation_id: "CreatePod".to_string(),
            method: "POST".to_string(),
            path: "/pods".to_string(),
            group: "Pods".to_string(),
            summary: "Create a pod".to_string(),
            path_params: Vec::new(),
            query_params: Vec::new(),
            header_params: Vec::new(),
            body_schema: Some(json!({"type": "object"})),
            body_required: true,
        }];

        let config = CliConfig {
            name: "testcli".into(),
            about: "Test".into(),
            default_base_url: "https://example.com".into(),
        };

        let cmd = build_commands(&config, &ops);
        let pods = cmd
            .get_subcommands()
            .find(|c| c.get_name() == "pods")
            .unwrap();
        let create_pod = pods
            .get_subcommands()
            .find(|c| c.get_name() == "create-pod")
            .unwrap();

        assert!(
            create_pod
                .get_arguments()
                .any(|a| a.get_id() == "json-body"),
            "should have --json arg"
        );
        assert!(
            create_pod.get_arguments().any(|a| a.get_id() == "field"),
            "should have --field arg"
        );
    }

    #[test]
    fn build_commands_global_base_url_arg() {
        let config = CliConfig {
            name: "testcli".into(),
            about: "Test".into(),
            default_base_url: "https://api.example.com".into(),
        };

        let cmd = build_commands(&config, &[]);
        let base_url_arg = cmd.get_arguments().find(|a| a.get_id() == "base-url");
        assert!(base_url_arg.is_some(), "should have global base-url arg");
    }

    // -- find_operation --

    #[test]
    fn find_operation_returns_matching_operation() {
        let ops = vec![
            make_operation("ListPods", "GET", "/pods", "Pods"),
            make_operation("CreatePod", "POST", "/pods", "Pods"),
        ];

        let found = find_operation(&ops, "pods", "create-pod");
        assert!(found.is_some());
        assert_eq!(found.unwrap().operation_id, "CreatePod");
    }

    #[test]
    fn find_operation_returns_none_for_nonexistent() {
        let ops = vec![make_operation("ListPods", "GET", "/pods", "Pods")];

        let found = find_operation(&ops, "pods", "delete-pod");
        assert!(found.is_none());
    }

    #[test]
    fn find_operation_returns_none_for_wrong_group() {
        let ops = vec![make_operation("ListPods", "GET", "/pods", "Pods")];

        let found = find_operation(&ops, "endpoints", "list-pods");
        assert!(found.is_none());
    }

    #[test]
    fn find_operation_matches_with_method_suffix() {
        let ops = vec![
            make_operation("UpdatePod", "PUT", "/pods/{id}", "Pods"),
            make_operation("UpdatePod", "PATCH", "/pods/{id}", "Pods"),
        ];

        let found = find_operation(&ops, "pods", "update-pod-patch");
        assert!(found.is_some());
        assert_eq!(found.unwrap().method, "PATCH");
    }
}