reinhardt_conf/settings/

sources.rs

//! Configuration sources for layered settings system
//!
//! Provides different sources of configuration that can be merged together
//! in priority order (environment variables > .env files > config files > defaults).

use super::env::EnvError;
use super::env_loader::EnvLoader;
use super::profile::Profile;
use indexmap::IndexMap;
use serde_json::Value;
use std::collections::HashMap;
use std::fs;
use std::path::{Path, PathBuf};

/// Trait for configuration sources
pub trait ConfigSource: Send + Sync {
	/// Load configuration from this source
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError>;

	/// Get the priority of this source (higher = more important)
	fn priority(&self) -> u8;

	/// Get a description of this source
	fn description(&self) -> String;
}

/// Error type for configuration sources
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum SourceError {
	/// An I/O error occurred while reading the configuration source.
	#[error("IO error: {0}")]
	Io(#[from] std::io::Error),

	/// The configuration content could not be parsed.
	#[error("Parse error: {0}")]
	Parse(String),

	/// An error occurred reading environment variables.
	#[error("Environment error: {0}")]
	Env(#[from] EnvError),

	/// The TOML configuration file could not be parsed.
	#[error("TOML error: {0}")]
	Toml(#[from] toml::de::Error),

	/// The JSON configuration file could not be parsed.
	#[error("JSON error: {0}")]
	Json(#[from] serde_json::Error),

	/// The configuration source is invalid or misconfigured.
	#[error("Invalid source: {0}")]
	InvalidSource(String),

	/// A `${VAR}` interpolation failed during TOML loading.
	///
	/// `InterpolationError` is boxed so that adding this variant does
	/// not push `BuildError::Source` over the `result_large_err` clippy
	/// threshold (the `Syntax` variant carries four heap-owning fields).
	#[error("Interpolation error: {0}")]
	Interpolation(#[from] Box<super::interpolation::InterpolationError>),
}

// Allow the `?` operator to convert a bare `InterpolationError` into a
// `SourceError::Interpolation`. The auto-derived `From<Box<...>>` from
// `#[from]` would otherwise force every call site to box explicitly.
impl From<super::interpolation::InterpolationError> for SourceError {
	fn from(err: super::interpolation::InterpolationError) -> Self {
		SourceError::Interpolation(Box::new(err))
	}
}

/// Environment variable configuration source
pub struct EnvSource {
	prefix: Option<String>,
	interpolate: bool,
}

impl EnvSource {
	/// Create a new environment variable configuration source
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::EnvSource;
	///
	/// let source = EnvSource::new();
	/// // Loads all environment variables
	/// ```
	pub fn new() -> Self {
		Self {
			prefix: None,
			interpolate: false,
		}
	}
	/// Set a prefix filter for environment variables
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::EnvSource;
	///
	/// let source = EnvSource::new()
	///     .with_prefix("APP_");
	/// // Only loads env vars starting with APP_
	/// ```
	pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
		self.prefix = Some(prefix.into());
		self
	}
	/// Enable variable interpolation for environment values
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::EnvSource;
	///
	/// let source = EnvSource::new()
	///     .with_interpolation(true);
	/// // Environment variables will support $VAR expansion
	/// ```
	pub fn with_interpolation(mut self, enabled: bool) -> Self {
		self.interpolate = enabled;
		self
	}
}

impl Default for EnvSource {
	fn default() -> Self {
		Self::new()
	}
}

impl ConfigSource for EnvSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		let mut config = IndexMap::new();

		// Get all environment variables
		for (key, value) in std::env::vars() {
			// Skip if prefix is set and key doesn't start with it
			if let Some(prefix) = &self.prefix
				&& !key.starts_with(prefix)
			{
				continue;
			}

			// Remove prefix if present
			let clean_key = if let Some(prefix) = &self.prefix {
				key.strip_prefix(prefix).unwrap_or(&key).to_string()
			} else {
				key.clone()
			};

			// Convert to lowercase for consistency
			let lower_key = clean_key.to_lowercase();

			// Try to parse as appropriate type
			let parsed_value = if lower_key == "debug" {
				// Parse debug value with support for "1", "0", "true", "false", etc.
				match value.trim().to_lowercase().as_str() {
					"true" | "1" | "yes" | "on" => Value::Bool(true),
					"false" | "0" | "no" | "off" => Value::Bool(false),
					_ => {
						if let Ok(b) = value.parse::<bool>() {
							Value::Bool(b)
						} else {
							Value::String(value)
						}
					}
				}
			} else if lower_key == "allowed_hosts" {
				// Parse comma-separated list
				let list: Vec<_> = value
					.split(',')
					.map(|s| Value::String(s.trim().to_string()))
					.collect();
				Value::Array(list)
			} else if let Ok(num) = value.parse::<i64>() {
				Value::Number(num.into())
			} else if let Ok(b) = value.parse::<bool>() {
				Value::Bool(b)
			} else {
				Value::String(value)
			};

			config.insert(lower_key, parsed_value);
		}

		Ok(config)
	}

	fn priority(&self) -> u8 {
		100 // Highest priority
	}

	fn description(&self) -> String {
		match &self.prefix {
			Some(prefix) => format!("Environment variables (prefix: {})", prefix),
			None => "Environment variables".to_string(),
		}
	}
}

/// .env file configuration source
pub struct DotEnvSource {
	path: Option<PathBuf>,
	profile: Option<Profile>,
	interpolate: bool,
}

impl DotEnvSource {
	/// Create a new .env file configuration source
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DotEnvSource;
	///
	/// let source = DotEnvSource::new();
	/// // Loads from .env file
	/// ```
	pub fn new() -> Self {
		Self {
			path: None,
			profile: None,
			interpolate: false,
		}
	}
	/// Set a specific path for the .env file
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DotEnvSource;
	/// use std::path::PathBuf;
	///
	/// let source = DotEnvSource::new()
	///     .with_path(PathBuf::from(".env.local"));
	/// ```
	pub fn with_path(mut self, path: impl Into<PathBuf>) -> Self {
		self.path = Some(path.into());
		self
	}
	/// Set the profile to determine .env file name
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DotEnvSource;
	/// use reinhardt_conf::settings::profile::Profile;
	///
	/// let source = DotEnvSource::new()
	///     .with_profile(Profile::Production);
	/// // Will load .env.production
	/// ```
	pub fn with_profile(mut self, profile: Profile) -> Self {
		self.profile = Some(profile);
		self
	}
	/// Enable variable interpolation in .env files
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DotEnvSource;
	///
	/// let source = DotEnvSource::new()
	///     .with_interpolation(true);
	/// // .env file variables will support $VAR expansion
	/// ```
	pub fn with_interpolation(mut self, enabled: bool) -> Self {
		self.interpolate = enabled;
		self
	}
}

impl Default for DotEnvSource {
	fn default() -> Self {
		Self::new()
	}
}

impl ConfigSource for DotEnvSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		let path = match &self.path {
			Some(p) => p.clone(),
			None => {
				let filename = match &self.profile {
					Some(profile) => profile.env_file_name(),
					None => ".env".to_string(),
				};
				PathBuf::from(filename)
			}
		};

		// Load .env file if it exists
		let loader = EnvLoader::new()
			.path(&path)
			.interpolate(self.interpolate)
			.overwrite(false);

		// Try to load, but don't fail if file doesn't exist
		let _ = loader.load_optional()?;

		// Return empty config - the env vars are already loaded
		// The EnvSource will pick them up
		Ok(IndexMap::new())
	}

	fn priority(&self) -> u8 {
		90 // High priority, but below direct env vars
	}

	fn description(&self) -> String {
		match &self.path {
			Some(path) => format!(".env file: {}", path.display()),
			None => match &self.profile {
				Some(profile) => format!(".env file: {}", profile.env_file_name()),
				None => ".env file".to_string(),
			},
		}
	}
}

/// TOML file configuration source
pub struct TomlFileSource {
	path: PathBuf,
	interpolate: bool,
}

impl TomlFileSource {
	/// Create a new TOML file configuration source.
	///
	/// `${VAR}` interpolation is **enabled by default** because the vast
	/// majority of real-world settings files (secrets, per-environment
	/// hosts, 12-factor overrides) require it. Call
	/// [`Self::without_interpolation`] to opt out and preserve raw TOML
	/// strings verbatim.
	///
	/// See [`Self::with_interpolation`] for the supported syntax.
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::TomlFileSource;
	/// use std::path::PathBuf;
	///
	/// // Interpolation enabled by default — `${VAR}` is substituted from env.
	/// let source = TomlFileSource::new(PathBuf::from("config.toml"));
	/// ```
	pub fn new(path: impl Into<PathBuf>) -> Self {
		Self {
			path: path.into(),
			interpolate: true,
		}
	}

	/// Explicitly opt **in** to `${VAR}` interpolation.
	///
	/// This is a no-op for the default state — interpolation is on by
	/// default since `0.1.0-rc.27`. The method exists so call sites can
	/// document intent or re-enable interpolation after a previous
	/// [`Self::without_interpolation`] call in a builder chain.
	///
	/// Supported syntax (applied to every `toml::Value::String` in the tree):
	///
	/// | Token              | Meaning                                          |
	/// |--------------------|--------------------------------------------------|
	/// | `${VAR}`           | required — fails if `VAR` is unset or empty      |
	/// | `${VAR:-default}`  | substitutes `default` if `VAR` is unset or empty |
	/// | `${VAR:?message}`  | fails with `message` if `VAR` is unset or empty  |
	/// | `$$`               | escape — produces a literal `$`                  |
	///
	/// Only string nodes are scanned, but the walker recurses into nested
	/// tables and arrays. Numeric, boolean, and datetime values are
	/// never rewritten.
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::TomlFileSource;
	/// use std::path::PathBuf;
	///
	/// let source = TomlFileSource::new(PathBuf::from("settings.toml"))
	///     .with_interpolation();
	/// ```
	pub fn with_interpolation(mut self) -> Self {
		self.interpolate = true;
		self
	}

	/// Opt **out** of `${VAR}` interpolation and keep all TOML strings as
	/// literal values.
	///
	/// Use this when you intend `${...}` substrings to survive the load —
	/// for example, when the configuration is itself a template that
	/// downstream code expands later.
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::TomlFileSource;
	/// use std::path::PathBuf;
	///
	/// let source = TomlFileSource::new(PathBuf::from("template.toml"))
	///     .without_interpolation();
	/// ```
	pub fn without_interpolation(mut self) -> Self {
		self.interpolate = false;
		self
	}

	/// Set interpolation explicitly via a boolean flag.
	///
	/// This is the legacy 0.1.0-rc API surface. New code should use
	/// [`Self::with_interpolation`] / [`Self::without_interpolation`]
	/// instead.
	#[deprecated(
		since = "0.1.0-rc.27",
		note = "Use with_interpolation()/without_interpolation() instead; will be removed in 0.2.0 (issue #4224)"
	)]
	pub fn set_interpolation(mut self, enabled: bool) -> Self {
		self.interpolate = enabled;
		self
	}
}

impl ConfigSource for TomlFileSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		if !self.path.exists() {
			return Ok(IndexMap::new());
		}

		let content = fs::read_to_string(&self.path)?;
		let mut toml_value: toml::Value = toml::from_str(&content)?;

		// Apply ${VAR} interpolation if enabled. The lookup closure
		// resolves variables from process env at load time.
		if self.interpolate {
			let lookup = |name: &str| std::env::var(name).ok();
			let interpolator = super::interpolation::Interpolator::new(&lookup);
			interpolator.interpolate_value(&mut toml_value, &self.path)?;
		}

		// Convert TOML value to JSON value
		let json_str = serde_json::to_string(&toml_value)?;
		let json_value: Value = serde_json::from_str(&json_str)?;

		// Flatten into IndexMap
		let map = json_value
			.as_object()
			.ok_or_else(|| SourceError::Parse("Expected object at root".to_string()))?;

		Ok(map.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
	}

	fn priority(&self) -> u8 {
		50 // Medium priority
	}

	fn description(&self) -> String {
		format!("TOML file: {}", self.path.display())
	}
}

/// JSON file configuration source.
///
/// TOML is the canonical Reinhardt configuration format; this type will be
/// removed in 0.2.0. Migrate `.json` files to `.toml` (TOML is a superset of
/// typical JSON config use cases) or implement the public `ConfigSource` trait
/// against `serde_json` if you need to keep JSON support out of tree. See
/// <https://github.com/kent8192/reinhardt-web/issues/4087>.
#[deprecated(
	since = "0.1.0-rc.26",
	note = "Use TomlFileSource instead. JsonFileSource will be removed in 0.2.0 (issue #4087)"
)]
pub struct JsonFileSource {
	path: PathBuf,
}

#[allow(deprecated)] // impl block on a deprecated type (issue #4087).
impl JsonFileSource {
	/// Create a new JSON file configuration source
	///
	/// # Examples
	///
	/// ```
	/// # #![allow(deprecated)]
	/// use reinhardt_conf::settings::sources::JsonFileSource;
	/// use std::path::PathBuf;
	///
	/// let source = JsonFileSource::new(PathBuf::from("config.json"));
	/// ```
	#[deprecated(
		since = "0.1.0-rc.26",
		note = "Use TomlFileSource::new instead. JsonFileSource will be removed in 0.2.0 (issue #4087)"
	)]
	pub fn new(path: impl Into<PathBuf>) -> Self {
		Self { path: path.into() }
	}
}

#[allow(deprecated)] // ConfigSource impl on a deprecated type (issue #4087).
impl ConfigSource for JsonFileSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		if !self.path.exists() {
			return Ok(IndexMap::new());
		}

		let content = fs::read_to_string(&self.path)?;
		let json_value: Value = serde_json::from_str(&content)?;

		// Flatten into IndexMap
		let map = json_value
			.as_object()
			.ok_or_else(|| SourceError::Parse("Expected object at root".to_string()))?;

		Ok(map.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
	}

	fn priority(&self) -> u8 {
		50 // Medium priority
	}

	fn description(&self) -> String {
		format!("JSON file: {}", self.path.display())
	}
}

/// Default values configuration source
pub struct DefaultSource {
	values: IndexMap<String, Value>,
}

impl DefaultSource {
	/// Create a new default values configuration source
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DefaultSource;
	/// use serde_json::Value;
	///
	/// let source = DefaultSource::new()
	///     .with_value("debug", Value::Bool(false))
	///     .with_value("port", Value::Number(8000.into()));
	/// ```
	pub fn new() -> Self {
		Self {
			values: IndexMap::new(),
		}
	}
	/// Add a default value for a configuration key
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DefaultSource;
	/// use serde_json::Value;
	///
	/// let source = DefaultSource::new()
	///     .with_value("timeout", Value::Number(30.into()));
	/// ```
	pub fn with_value(mut self, key: impl Into<String>, value: Value) -> Self {
		self.values.insert(key.into(), value);
		self
	}
	/// Add multiple default values from a HashMap
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::DefaultSource;
	/// use serde_json::Value;
	/// use std::collections::HashMap;
	///
	/// let mut defaults = HashMap::new();
	/// defaults.insert("key1".to_string(), Value::String("value1".to_string()));
	/// defaults.insert("key2".to_string(), Value::Bool(true));
	///
	/// let source = DefaultSource::new()
	///     .with_defaults(defaults);
	/// ```
	pub fn with_defaults(mut self, defaults: HashMap<String, Value>) -> Self {
		self.values.extend(defaults);
		self
	}
}

impl Default for DefaultSource {
	fn default() -> Self {
		Self::new()
	}
}

impl ConfigSource for DefaultSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		Ok(self.values.clone())
	}

	fn priority(&self) -> u8 {
		0 // Lowest priority
	}

	fn description(&self) -> String {
		"Default values".to_string()
	}
}
/// Auto-detect configuration source based on file extension.
///
/// The `*.json` branch is going away in 0.2.0 alongside [`JsonFileSource`].
/// For TOML usage, prefer constructing [`TomlFileSource::new`] directly — it
/// makes the configuration format explicit at the call site. See
/// <https://github.com/kent8192/reinhardt-web/issues/4087>.
///
/// # Examples
///
/// ```
/// # #![allow(deprecated)]
/// use reinhardt_conf::settings::sources::auto_source;
/// use std::path::PathBuf;
///
/// // Automatically detects TOML source from extension
/// let source = auto_source(PathBuf::from("config.toml")).unwrap();
///
/// // Or JSON source (deprecated; will be removed in 0.2.0)
/// let source = auto_source(PathBuf::from("settings.json")).unwrap();
/// ```
#[deprecated(
	since = "0.1.0-rc.26",
	note = "Use TomlFileSource::new directly. The *.json branch will be removed in 0.2.0 (issue #4087)"
)]
pub fn auto_source(path: impl AsRef<Path>) -> Result<Box<dyn ConfigSource>, SourceError> {
	let path = path.as_ref();
	let ext = path
		.extension()
		.and_then(|e| e.to_str())
		.ok_or_else(|| SourceError::InvalidSource("No file extension".to_string()))?;

	match ext {
		"toml" => Ok(Box::new(TomlFileSource::new(path))),
		// JsonFileSource is deprecated alongside this function (issue #4087);
		// keep wiring it through until the *.json branch is removed in 0.2.0.
		#[allow(deprecated)]
		"json" => Ok(Box::new(JsonFileSource::new(path))),
		_ => Err(SourceError::InvalidSource(format!(
			"Unsupported file extension: {}",
			ext
		))),
	}
}

/// Low-priority environment variable configuration source
///
/// This wrapper provides the same functionality as `EnvSource` but with lower priority
/// than TOML files, allowing TOML configuration to override environment variables.
///
/// Priority: 40 (lower than TOML files at 50)
///
/// # Examples
///
/// ```
/// use reinhardt_conf::settings::sources::LowPriorityEnvSource;
/// use reinhardt_conf::settings::builder::SettingsBuilder;
///
/// let settings = SettingsBuilder::new()
///     .add_source(LowPriorityEnvSource::new())
///     .build()
///     .unwrap();
/// ```
pub struct LowPriorityEnvSource {
	inner: EnvSource,
}

impl LowPriorityEnvSource {
	/// Create a new low-priority environment variable configuration source
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::LowPriorityEnvSource;
	///
	/// let source = LowPriorityEnvSource::new();
	/// ```
	pub fn new() -> Self {
		Self {
			inner: EnvSource::new(),
		}
	}

	/// Set a prefix filter for environment variables
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::LowPriorityEnvSource;
	///
	/// let source = LowPriorityEnvSource::new()
	///     .with_prefix("REINHARDT_");
	/// ```
	pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
		self.inner = self.inner.with_prefix(prefix);
		self
	}

	/// Enable variable interpolation for environment values
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::LowPriorityEnvSource;
	///
	/// let source = LowPriorityEnvSource::new()
	///     .with_interpolation(true);
	/// ```
	pub fn with_interpolation(mut self, enabled: bool) -> Self {
		self.inner = self.inner.with_interpolation(enabled);
		self
	}
}

impl Default for LowPriorityEnvSource {
	fn default() -> Self {
		Self::new()
	}
}

impl ConfigSource for LowPriorityEnvSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		self.inner.load()
	}

	fn priority(&self) -> u8 {
		40 // Lower than TOML files (50), allowing TOML to override env vars
	}

	fn description(&self) -> String {
		format!("{} (low priority)", self.inner.description())
	}
}

/// High-priority environment variable configuration source for test overrides
///
/// This wrapper provides the same functionality as `EnvSource` but with higher priority
/// than TOML files, allowing environment variables to override TOML configuration.
/// Intended for integration tests where dynamic values (e.g., TestContainer ports)
/// must override file-based settings.
///
/// Priority: 60 (higher than TOML files at 50, lower than `DotEnvSource` at 90)
///
/// # Examples
///
/// ```
/// use reinhardt_conf::settings::sources::HighPriorityEnvSource;
/// use reinhardt_conf::settings::builder::SettingsBuilder;
///
/// let settings = SettingsBuilder::new()
///     .add_source(HighPriorityEnvSource::new().with_prefix("REINHARDT_TEST_"))
///     .build()
///     .unwrap();
/// ```
pub struct HighPriorityEnvSource {
	inner: EnvSource,
}

impl HighPriorityEnvSource {
	/// Create a new high-priority environment variable configuration source
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::HighPriorityEnvSource;
	///
	/// let source = HighPriorityEnvSource::new();
	/// ```
	pub fn new() -> Self {
		Self {
			inner: EnvSource::new(),
		}
	}

	/// Set a prefix filter for environment variables
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::HighPriorityEnvSource;
	///
	/// let source = HighPriorityEnvSource::new()
	///     .with_prefix("REINHARDT_TEST_");
	/// ```
	pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
		self.inner = self.inner.with_prefix(prefix);
		self
	}

	/// Enable variable interpolation for environment values
	///
	/// # Examples
	///
	/// ```
	/// use reinhardt_conf::settings::sources::HighPriorityEnvSource;
	///
	/// let source = HighPriorityEnvSource::new()
	///     .with_interpolation(true);
	/// ```
	pub fn with_interpolation(mut self, enabled: bool) -> Self {
		self.inner = self.inner.with_interpolation(enabled);
		self
	}
}

impl Default for HighPriorityEnvSource {
	fn default() -> Self {
		Self::new()
	}
}

impl ConfigSource for HighPriorityEnvSource {
	fn load(&self) -> Result<IndexMap<String, Value>, SourceError> {
		self.inner.load()
	}

	fn priority(&self) -> u8 {
		60 // Higher than TOML files (50), allowing env vars to override TOML config
	}

	fn description(&self) -> String {
		format!("{} (high priority)", self.inner.description())
	}
}

#[cfg(test)]
mod tests {
	use super::*;
	use std::env;
	use std::fs::File;
	use std::io::Write;
	use tempfile::TempDir;

	#[test]
	fn test_env_source() {
		// SAFETY: Setting environment variables is unsafe in multi-threaded programs.
		// This test uses #[serial] to ensure exclusive access to environment variables.
		unsafe {
			env::set_var("SECRET_KEY", "test-secret");
			env::set_var("DEBUG", "true");
		}

		let source = EnvSource::new();
		let config = source.load().unwrap();

		assert_eq!(
			config.get("secret_key").unwrap(),
			&Value::String("test-secret".to_string())
		);
		assert_eq!(config.get("debug").unwrap(), &Value::Bool(true));

		// SAFETY: Removing environment variables is unsafe in multi-threaded programs.
		// This test uses #[serial] to ensure exclusive access to environment variables.
		unsafe {
			env::remove_var("SECRET_KEY");
			env::remove_var("DEBUG");
		}
	}

	#[test]
	fn test_toml_source() {
		let temp_dir = TempDir::new().unwrap();
		let config_path = temp_dir.path().join("config.toml");

		let mut file = File::create(&config_path).unwrap();
		writeln!(
			file,
			r#"
debug = true
secret_key = "test-key"
        "#
		)
		.unwrap();

		let source = TomlFileSource::new(&config_path);
		let config = source.load().unwrap();

		assert_eq!(config.get("debug").unwrap(), &Value::Bool(true));
		assert_eq!(
			config.get("secret_key").unwrap(),
			&Value::String("test-key".to_string())
		);
	}

	// `JsonFileSource::new` is deprecated until removal in 0.2.0 (issue #4087);
	// the test exercises load behavior so we still want to construct one here.
	#[allow(deprecated)]
	#[test]
	fn test_json_source() {
		let temp_dir = TempDir::new().unwrap();
		let config_path = temp_dir.path().join("config.json");

		let mut file = File::create(&config_path).unwrap();
		writeln!(
			file,
			r#"{{
            "debug": false,
            "secret_key": "json-key"
        }}"#
		)
		.unwrap();

		let source = JsonFileSource::new(&config_path);
		let config = source.load().unwrap();

		assert_eq!(config.get("debug").unwrap(), &Value::Bool(false));
		assert_eq!(
			config.get("secret_key").unwrap(),
			&Value::String("json-key".to_string())
		);
	}

	#[test]
	fn test_default_source() {
		let source = DefaultSource::new()
			.with_value("key1", Value::String("value1".to_string()))
			.with_value("key2", Value::Bool(true));

		let config = source.load().unwrap();

		assert_eq!(
			config.get("key1").unwrap(),
			&Value::String("value1".to_string())
		);
		assert_eq!(config.get("key2").unwrap(), &Value::Bool(true));
	}

	#[test]
	fn test_source_priority() {
		assert_eq!(EnvSource::new().priority(), 100);
		assert_eq!(DotEnvSource::new().priority(), 90);
		assert_eq!(HighPriorityEnvSource::new().priority(), 60);
		assert_eq!(TomlFileSource::new("test.toml").priority(), 50);
		assert_eq!(LowPriorityEnvSource::new().priority(), 40);
		assert_eq!(DefaultSource::new().priority(), 0);
	}

	#[test]
	fn test_high_priority_env_source_wraps_env_source() {
		// Arrange
		let source = HighPriorityEnvSource::new();

		// Act
		let priority = source.priority();
		let description = source.description();

		// Assert
		assert_eq!(priority, 60);
		assert!(description.contains("high priority"));
	}

	#[test]
	fn test_high_priority_env_source_with_prefix() {
		// Arrange
		let source = HighPriorityEnvSource::new().with_prefix("REINHARDT_TEST_");

		// Act
		let description = source.description();

		// Assert
		assert!(description.contains("REINHARDT_TEST_"));
		assert!(description.contains("high priority"));
	}

	#[test]
	fn toml_file_source_without_interpolation_preserves_literal() {
		// Arrange — issue #4224: explicit opt-out keeps `${...}` verbatim.
		let temp_dir = TempDir::new().unwrap();
		let config_path = temp_dir.path().join("config.toml");
		let mut file = File::create(&config_path).unwrap();
		writeln!(file, r#"host = "${{LITERAL_VAR}}""#).unwrap();

		// Act
		let source = TomlFileSource::new(&config_path).without_interpolation();
		let config = source.load().unwrap();

		// Assert
		assert_eq!(
			config.get("host").unwrap(),
			&Value::String("${LITERAL_VAR}".to_string())
		);
	}

	#[test]
	fn test_high_priority_env_source_overrides_toml() {
		// Arrange
		let temp_dir = TempDir::new().unwrap();
		let config_path = temp_dir.path().join("config.toml");
		let mut file = File::create(&config_path).unwrap();
		writeln!(file, r#"port = 1025"#).unwrap();

		let prefix = "HPENV_TEST_3518_";
		let env_key = format!("{prefix}PORT");

		// SAFETY: Single-threaded test, no concurrent env access.
		unsafe { env::set_var(&env_key, "9999") };

		// Act
		let settings = crate::settings::builder::SettingsBuilder::new()
			.add_source(TomlFileSource::new(&config_path))
			.add_source(HighPriorityEnvSource::new().with_prefix(prefix))
			.build()
			.unwrap();

		// Assert — HighPriorityEnvSource (60) overrides TOML (50)
		let port: i64 = settings.get("port").unwrap();
		assert_eq!(port, 9999);

		// Cleanup
		unsafe { env::remove_var(&env_key) };
	}
}