mecha10-core 0.6.2

// Mecha10 Configuration System
//
// This module provides configuration loading, validation, and environment variable support.

use crate::{Mecha10Error, Result};
use anyhow::Context as _;
use serde::de::DeserializeOwned;
use std::env;
use std::fs;
use std::path::Path;

// ============================================================================
// Shared Config Field Defaults
// ============================================================================

/// Shared `#[serde(default = "...")]` helpers for config fields that are
/// duplicated byte-for-byte across multiple crates.
///
/// Only fields with genuinely identical defaults across crates belong here -
/// don't add a helper just because two fields happen to share a name.
pub mod defaults {
    /// Default odometry update rate in Hz.
    pub fn default_odom_rate_hz() -> f32 {
        50.0
    }

    /// Default maximum linear velocity in m/s.
    pub fn default_max_linear_vel() -> f32 {
        0.5
    }

    /// Default maximum angular velocity in rad/s.
    pub fn default_max_angular_vel() -> f32 {
        1.0
    }
}

// ============================================================================
// Environment Variable Helpers
// ============================================================================

/// Read an environment variable, falling back to `default` if it's unset (or
/// not valid unicode).
///
/// # Example
///
/// ```
/// use mecha10_core::config::env_or_default;
///
/// std::env::remove_var("MECHA10_EXAMPLE_ENV_VAR");
/// assert_eq!(env_or_default("MECHA10_EXAMPLE_ENV_VAR", "fallback"), "fallback");
/// ```
pub fn env_or_default(key: &str, default: &str) -> String {
    env::var(key).unwrap_or_else(|_| default.to_string())
}

/// Convert an `http(s)://` URL into its `ws(s)://` equivalent.
///
/// - `https://` is replaced with `wss://`
/// - `http://` is replaced with `ws://`
/// - if the input has no recognized scheme prefix at all, `wss://` is
///   prepended rather than leaving the URL scheme-less. A schemeless URL
///   (e.g. a `control_plane` value copied from config without a protocol)
///   would otherwise silently produce a malformed relay URL that fails to
///   connect.
///
/// # Example
///
/// ```
/// use mecha10_core::config::to_websocket_url;
///
/// assert_eq!(to_websocket_url("https://example.com"), "wss://example.com");
/// assert_eq!(to_websocket_url("http://example.com"), "ws://example.com");
/// assert_eq!(to_websocket_url("example.com"), "wss://example.com");
/// ```
pub fn to_websocket_url(url: &str) -> String {
    if let Some(rest) = url.strip_prefix("https://") {
        format!("wss://{}", rest)
    } else if let Some(rest) = url.strip_prefix("http://") {
        format!("ws://{}", rest)
    } else {
        format!("wss://{}", url)
    }
}

// ============================================================================
// Configuration Loading
// ============================================================================

/// Load configuration from a file with environment variable substitution.
///
/// Supports:
/// - JSON, YAML, TOML files (based on extension)
/// - Environment variable substitution with `${VAR_NAME}` syntax
/// - Environment-specific config sections (dev, production, staging)
/// - Validation via serde
/// - Semantic validation via [`Validate`]: if `T` implements `Validate`, its
///   `validate()` is called automatically after deserializing and any error
///   it returns is propagated. Types that don't implement `Validate` are
///   unaffected (no-op) -- this hook is purely additive/opt-in.
///
/// # Environment Selection
///
/// If the config file has top-level keys matching environment names (dev, development,
/// prod, production, staging), the function will select the appropriate section based
/// on the `MECHA10_ENV` environment variable (defaults to "development").
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Debug, Deserialize)]
/// struct MyConfig {
///     rate: f32,
///     endpoint: String,
/// }
///
/// // Load from file
/// let config: MyConfig = load_config("config.yaml")?;
///
/// // If config.json contains:
/// // {
/// //   "dev": { "rate": 10.0, "endpoint": "http://localhost" },
/// //   "production": { "rate": 1.0, "endpoint": "https://api.example.com" }
/// // }
/// // And MECHA10_ENV=development, then config will use the "dev" section
/// ```
pub fn load_config<T, P>(path: P) -> Result<T>
where
    T: DeserializeOwned,
    P: AsRef<Path>,
{
    let path = path.as_ref();

    // Read file
    let content = fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file at '{}'", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Substitute environment variables
    let content = substitute_env_vars(&content)
        .with_context(|| format!("Failed to substitute environment variables in '{}'", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Parse to generic JSON value first to check for environment sections
    let value: serde_json::Value = match path.extension().and_then(|s| s.to_str()) {
        Some("json") => serde_json::from_str(&content)
            .with_context(|| format!("Failed to parse JSON config from '{}'", path.display()))
            .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?,
        Some("yaml") | Some("yml") => serde_yaml::from_str(&content)
            .with_context(|| format!("Failed to parse YAML config from '{}'", path.display()))
            .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?,
        Some("toml") => {
            let toml_value: toml::Value = toml::from_str(&content)
                .with_context(|| format!("Failed to parse TOML config from '{}'", path.display()))
                .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;
            // Convert TOML to JSON for uniform handling
            serde_json::to_value(toml_value)
                .map_err(|e| Mecha10Error::Configuration(format!("Failed to convert TOML: {}", e)))?
        }
        Some(ext) => {
            return Err(Mecha10Error::Configuration(format!(
                "Unsupported config file extension: {}",
                ext
            )));
        }
        None => {
            return Err(Mecha10Error::Configuration("Config file has no extension".to_string()));
        }
    };

    // Check if this is an environment-sectioned config
    let final_value = extract_env_config(value);

    // Parse to target type
    let config: T = serde_json::from_value(final_value)
        .with_context(|| format!("Failed to parse config from '{}'", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Run semantic validation if `T` implements `Validate` (no-op otherwise).
    maybe_validate(&config)?;

    Ok(config)
}

/// Extract environment-specific config section.
///
/// Node configs MUST have environment keys (dev, development, prod, production, staging, test).
/// Returns the appropriate section based on MECHA10_ENV (defaults to "development").
///
/// Flat configs are not supported - all node configs must be nested by environment.
fn extract_env_config(value: serde_json::Value) -> serde_json::Value {
    // Environment key mappings
    let env_keys = ["dev", "development", "prod", "production", "staging", "test"];

    if let serde_json::Value::Object(ref map) = value {
        // Get current environment
        let current_env = env::var("MECHA10_ENV").unwrap_or_else(|_| "development".to_string());

        // Map environment name to config key
        let env_key = match current_env.as_str() {
            "development" | "dev" => {
                if map.contains_key("dev") {
                    "dev"
                } else {
                    "development"
                }
            }
            "production" | "prod" => {
                if map.contains_key("production") {
                    "production"
                } else {
                    "prod"
                }
            }
            other => other,
        };

        // Return the environment section if it exists
        if let Some(env_config) = map.get(env_key) {
            return env_config.clone();
        }

        // No matching env section found - check if config has ANY env keys
        let has_any_env_keys = map.keys().any(|k| env_keys.contains(&k.as_str()));
        if has_any_env_keys {
            // Config has env sections but not the one we need
            // Return empty object to trigger parse error
            return serde_json::Value::Object(serde_json::Map::new());
        }

        // Flat config detected (no env keys) - return empty to force nested format
        // This ensures all configs must use the nested environment format
        return serde_json::Value::Object(serde_json::Map::new());
    }

    // Non-object configs return empty to trigger error
    serde_json::Value::Object(serde_json::Map::new())
}

/// Load configuration from environment variables with a prefix.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Debug, Deserialize)]
/// struct MyConfig {
///     rate: f32,
///     endpoint: String,
/// }
///
/// // Load from environment variables:
/// // MYAPP_RATE=10.5
/// // MYAPP_ENDPOINT=http://localhost:8080
/// let config: MyConfig = load_config_from_env("MYAPP")?;
/// ```
pub fn load_config_from_env<T>(prefix: &str) -> Result<T>
where
    T: DeserializeOwned,
{
    // Collect all environment variables with the prefix
    let mut config_map = serde_json::Map::new();

    for (key, value) in env::vars() {
        if let Some(suffix) = key.strip_prefix(&format!("{}_", prefix)) {
            // Convert UPPER_SNAKE_CASE to lower_snake_case
            let json_key = suffix.to_lowercase();

            // Try to parse value as JSON first (for nested objects, arrays, etc.)
            let json_value = serde_json::from_str(&value).unwrap_or(serde_json::Value::String(value));

            config_map.insert(json_key, json_value);
        }
    }

    // Convert to target type
    let config: T = serde_json::from_value(serde_json::Value::Object(config_map))
        .map_err(|e| Mecha10Error::Configuration(format!("Failed to parse config from environment: {}", e)))?;

    // Run semantic validation if `T` implements `Validate` (no-op otherwise).
    maybe_validate(&config)?;

    Ok(config)
}

// ============================================================================
// Environment Variable Substitution
// ============================================================================

/// Substitute environment variables in a string.
///
/// Syntax: `${VAR_NAME}` or `$VAR_NAME`
///
/// # Example
///
/// ```rust
/// use mecha10::config::substitute_env_vars;
///
/// std::env::set_var("MY_VAR", "hello");
/// let result = substitute_env_vars("Value is: ${MY_VAR}").unwrap();
/// assert_eq!(result, "Value is: hello");
/// ```
pub fn substitute_env_vars(input: &str) -> Result<String> {
    let mut result = input.to_string();

    // Find all ${VAR_NAME} patterns
    let re = regex::Regex::new(r"\$\{([A-Z_][A-Z0-9_]*)\}").unwrap();

    for cap in re.captures_iter(input) {
        let var_name = &cap[1];
        let var_value = env::var(var_name).map_err(|_| {
            Mecha10Error::Configuration(format!(
                "Environment variable {} not found (required by config)",
                var_name
            ))
        })?;

        result = result.replace(&format!("${{{}}}", var_name), &var_value);
    }

    // Also support $VAR_NAME syntax (without braces)
    let re = regex::Regex::new(r"\$([A-Z_][A-Z0-9_]*)").unwrap();

    for cap in re.captures_iter(input) {
        let var_name = &cap[1];
        if let Ok(var_value) = env::var(var_name) {
            result = result.replace(&format!("${}", var_name), &var_value);
        }
    }

    Ok(result)
}

// ============================================================================
// Configuration Validation
// ============================================================================

/// Trait for validating configuration.
///
/// Implement this trait to add custom validation logic to your config types.
///
/// # Example
///
/// ```rust
/// use mecha10::prelude::*;
///
/// #[derive(Debug, Deserialize)]
/// struct MyConfig {
///     rate: f32,
///     max_speed: f32,
/// }
///
/// impl Validate for MyConfig {
///     fn validate(&self) -> Result<()> {
///         if self.rate <= 0.0 {
///             return Err(Mecha10Error::Configuration(
///                 "rate must be positive".to_string()
///             ));
///         }
///         if self.max_speed > 10.0 {
///             return Err(Mecha10Error::Configuration(
///                 "max_speed cannot exceed 10.0".to_string()
///             ));
///         }
///         Ok(())
///     }
/// }
/// ```
pub trait Validate {
    /// Validate the configuration.
    ///
    /// Returns an error if validation fails.
    fn validate(&self) -> Result<()>;
}

/// Calls [`Validate::validate`] on `config` if (and only if) `T` implements
/// [`Validate`]; otherwise this is a no-op that always returns `Ok(())`.
///
/// This is the hook that lets [`load_config`] and [`load_config_from_env`]
/// call into user-supplied semantic validation without requiring *every*
/// config type in the workspace to implement `Validate` -- non-implementors
/// silently no-op, so wiring this in is non-breaking.
///
/// # How it works
///
/// Stable Rust has no specialization, so we can't write a single blanket
/// `impl<T: DeserializeOwned> Validate for T` with a default body while still
/// allowing specific types to opt in with real validation logic (that would
/// be a conflicting/duplicate trait impl). Instead we lean on an ordinary,
/// well-established property of method resolution: an inherent method is
/// always preferred over a trait method of the same name. `Wrap<T>` gets a
/// blanket, always-available trait method (the no-op fallback) plus an
/// inherent method that only exists when `T: Validate` (the real check) --
/// the compiler picks whichever one actually exists for a given `T`.
pub(crate) fn maybe_validate<T>(config: &T) -> Result<()> {
    // No production config type in this workspace currently implements `Validate` (only
    // test fixtures in this module's `#[cfg(test)]` block do), so a `--lib`-only build never
    // monomorphizes the `T: Validate` arm below and dead-code analysis can't see that it's
    // reachable once a real config type opts in. Keep the specialization hook allowed rather
    // than deleting it -- see the doc comment above for why it exists.
    #[allow(dead_code)]
    struct Wrap<'a, T>(&'a T);

    trait NoopValidate {
        fn maybe_validate(&self) -> Result<()> {
            Ok(())
        }
    }

    impl<T> NoopValidate for Wrap<'_, T> {}

    impl<T: Validate> Wrap<'_, T> {
        #[allow(dead_code)]
        fn maybe_validate(&self) -> Result<()> {
            self.0.validate()
        }
    }

    Wrap(config).maybe_validate()
}

/// Load and validate configuration.
///
/// This is a convenience function that combines `load_config` and `Validate::validate`.
///
/// Note: `load_config` itself now runs [`Validate::validate`] automatically
/// for any `T: Validate` (see the `Validate` hook documented there), so this
/// function no longer needs to call `validate()` a second time -- it's kept
/// as an explicit, self-documenting entry point for call sites that want the
/// validation requirement visible in their own signature (the `T: Validate`
/// bound), rather than for its own behavior.
pub fn load_and_validate<T, P>(path: P) -> Result<T>
where
    T: DeserializeOwned + Validate,
    P: AsRef<Path>,
{
    load_config(path)
}

/// Load project configuration with JSON Schema validation
///
/// This function loads a mecha10.json file and validates it against the built-in schema.
/// Use this for loading project-level configuration files.
///
/// Requires the `schema-validation` feature.
///
/// # Example
///
/// ```rust
/// use mecha10::config::load_project_config;
///
/// let config = load_project_config("mecha10.json")?;
/// println!("Project: {}", config["name"]);
/// ```
#[cfg(feature = "schema-validation")]
pub fn load_project_config<P: AsRef<Path>>(path: P) -> Result<serde_json::Value> {
    use crate::schema_validation::load_and_validate_project;
    load_and_validate_project(path)
}

/// Convert a config key to its on-disk display path.
///
/// Examples:
/// - `mecha10.json` -> `mecha10.json`
/// - `@mecha10/motor` -> `nodes/@mecha10/motor/config.json`
/// - `simulation` -> `simulation/config.json`
pub fn config_key_to_path(key: &str) -> String {
    if key == "mecha10.json" {
        "mecha10.json".to_string()
    } else if key.contains('/') {
        format!("nodes/{}/config.json", key)
    } else {
        format!("{}/config.json", key)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_config_key_to_path_project_config() {
        assert_eq!(config_key_to_path("mecha10.json"), "mecha10.json");
    }

    #[test]
    fn test_config_key_to_path_scoped_node() {
        assert_eq!(config_key_to_path("@mecha10/motor"), "nodes/@mecha10/motor/config.json");
    }

    #[test]
    fn test_config_key_to_path_simple_key() {
        assert_eq!(config_key_to_path("simulation"), "simulation/config.json");
    }

    #[test]
    fn test_to_websocket_url_https() {
        assert_eq!(to_websocket_url("https://mecha.industries"), "wss://mecha.industries");
    }

    #[test]
    fn test_to_websocket_url_http() {
        assert_eq!(to_websocket_url("http://localhost:8000"), "ws://localhost:8000");
    }

    #[test]
    fn test_to_websocket_url_no_scheme() {
        // A schemeless control-plane value must still get a ws(s):// scheme,
        // not be passed through bare - a bare URL silently produces a
        // malformed relay URL that fails to connect.
        assert_eq!(to_websocket_url("mecha.industries"), "wss://mecha.industries");
    }

    struct AlwaysValid;

    impl Validate for AlwaysValid {
        fn validate(&self) -> Result<()> {
            Ok(())
        }
    }

    struct AlwaysInvalid;

    impl Validate for AlwaysInvalid {
        fn validate(&self) -> Result<()> {
            Err(Mecha10Error::Configuration("always invalid".to_string()))
        }
    }

    struct NotValidated;

    #[test]
    fn test_maybe_validate_calls_validate_when_implemented() {
        assert!(maybe_validate(&AlwaysValid).is_ok());
    }

    #[test]
    fn test_maybe_validate_propagates_validation_errors() {
        let err = maybe_validate(&AlwaysInvalid).unwrap_err();
        assert!(matches!(err, Mecha10Error::Configuration(_)));
    }

    #[test]
    fn test_maybe_validate_is_noop_for_types_without_validate() {
        // `NotValidated` doesn't implement `Validate` -- this must not fail
        // to compile, and must always succeed.
        assert!(maybe_validate(&NotValidated).is_ok());
    }
}