adrs_core/

config.rs

//! Configuration handling for ADR repositories.

use crate::{Error, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};

/// Default ADR directory name.
pub const DEFAULT_ADR_DIR: &str = "doc/adr";

/// Legacy configuration file name (adr-tools compatible).
pub const LEGACY_CONFIG_FILE: &str = ".adr-dir";

/// New configuration file name.
pub const CONFIG_FILE: &str = "adrs.toml";

/// Global configuration file name.
pub const GLOBAL_CONFIG_FILE: &str = "config.toml";

/// Environment variable for ADR directory override.
pub const ENV_ADR_DIRECTORY: &str = "ADR_DIRECTORY";

/// Environment variable for config file path override.
pub const ENV_ADRS_CONFIG: &str = "ADRS_CONFIG";

/// Configuration for an ADR repository.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
    /// The directory where ADRs are stored.
    pub adr_dir: PathBuf,

    /// The mode of operation.
    pub mode: ConfigMode,

    /// Default status for newly created ADRs.
    pub default_status: Option<String>,

    /// Skip opening the editor when creating a new ADR.
    pub no_edit: bool,

    /// Template configuration.
    #[serde(default)]
    pub templates: TemplateConfig,

    /// Generate command configuration.
    #[serde(default)]
    pub generate: GenerateConfig,

    /// Export command configuration.
    #[serde(default)]
    pub export: ExportConfig,

    /// Doctor command configuration.
    #[serde(default)]
    pub doctor: DoctorConfig,
}

impl Default for Config {
    fn default() -> Self {
        Self {
            adr_dir: PathBuf::from(DEFAULT_ADR_DIR),
            mode: ConfigMode::Compatible,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig::default(),
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        }
    }
}

/// Deserialize a [`Config`] from TOML content, reporting any keys that do not
/// match a known field instead of silently dropping them.
///
/// Returns the parsed config together with the sorted, deduplicated list of
/// unrecognized keys as dotted paths (e.g. `"doctor.path"` for a stray `path`
/// key under `[doctor]`). Malformed TOML still produces `Error::Toml`, exactly
/// as `toml::from_str` does; only the handling of *unknown but otherwise
/// well-formed* keys changes.
fn deserialize_config(content: &str) -> Result<(Config, Vec<String>)> {
    let mut unknown_keys = Vec::new();
    let deserializer = toml::Deserializer::new(content);
    let config: Config = serde_ignored::deserialize(deserializer, |path| {
        unknown_keys.push(path.to_string());
    })?;
    unknown_keys.sort();
    unknown_keys.dedup();
    Ok((config, unknown_keys))
}

impl Config {
    /// Load configuration from the given directory.
    ///
    /// Searches for configuration in the following order:
    /// 1. `adrs.toml` (new format)
    /// 2. `.adr-dir` (legacy adr-tools format)
    /// 3. Default configuration
    pub fn load(root: &Path) -> Result<Self> {
        // Try new config first
        let config_path = root.join(CONFIG_FILE);
        if config_path.exists() {
            let content = std::fs::read_to_string(&config_path)?;
            let (config, _unknown_keys) = deserialize_config(&content)?;
            if config.adr_dir.as_os_str().is_empty() {
                return Err(Error::ConfigError(
                    "adr_dir cannot be empty in adrs.toml".into(),
                ));
            }
            return Ok(config);
        }

        // Try legacy .adr-dir file
        let legacy_path = root.join(LEGACY_CONFIG_FILE);
        if legacy_path.exists() {
            let adr_dir = std::fs::read_to_string(&legacy_path)?.trim().to_string();
            if adr_dir.is_empty() {
                return Err(Error::ConfigError(
                    "ADR directory path is empty in .adr-dir file".into(),
                ));
            }
            return Ok(Self {
                adr_dir: PathBuf::from(adr_dir),
                mode: ConfigMode::Compatible,
                default_status: None,
                no_edit: false,
                templates: TemplateConfig::default(),
                generate: GenerateConfig::default(),
                export: ExportConfig::default(),
                doctor: DoctorConfig::default(),
            });
        }

        // Check if default directory exists
        let default_dir = root.join(DEFAULT_ADR_DIR);
        if default_dir.exists() {
            return Ok(Self::default());
        }

        Err(Error::AdrDirNotFound)
    }

    /// Load configuration, or return default if not found.
    pub fn load_or_default(root: &Path) -> Self {
        Self::load(root).unwrap_or_default()
    }

    /// Save configuration to the given directory.
    pub fn save(&self, root: &Path) -> Result<()> {
        match self.mode {
            ConfigMode::Compatible => {
                // Write legacy .adr-dir file
                let path = root.join(LEGACY_CONFIG_FILE);
                std::fs::write(&path, self.adr_dir.display().to_string())?;
            }
            ConfigMode::NextGen => {
                // Write adrs.toml
                let path = root.join(CONFIG_FILE);
                let content =
                    toml::to_string_pretty(self).map_err(|e| Error::ConfigError(e.to_string()))?;
                std::fs::write(&path, content)?;
            }
        }
        Ok(())
    }

    /// Returns the full path to the ADR directory.
    pub fn adr_path(&self, root: &Path) -> PathBuf {
        root.join(&self.adr_dir)
    }

    /// Returns true if running in next-gen mode.
    pub fn is_next_gen(&self) -> bool {
        matches!(self.mode, ConfigMode::NextGen)
    }

    /// Merge another config into this one (other takes precedence for set values).
    pub fn merge(&mut self, other: &Config) {
        // adr_dir: use other if it differs from default
        if other.adr_dir.as_os_str() != DEFAULT_ADR_DIR {
            self.adr_dir = other.adr_dir.clone();
        }
        // mode: other takes precedence
        self.mode = other.mode;
        // templates: merge
        if other.templates.format.is_some() {
            self.templates.format = other.templates.format.clone();
        }
        if other.templates.variant.is_some() {
            self.templates.variant = other.templates.variant.clone();
        }
        if other.templates.custom.is_some() {
            self.templates.custom = other.templates.custom.clone();
        }
        if other.default_status.is_some() {
            self.default_status = other.default_status.clone();
        }
        if other.no_edit {
            self.no_edit = other.no_edit;
        }
        if other.generate.toc_prefix.is_some() {
            self.generate.toc_prefix = other.generate.toc_prefix.clone();
        }
        if other.export.base_url.is_some() {
            self.export.base_url = other.export.base_url.clone();
        }
        if !other.doctor.ignore.is_empty() {
            self.doctor.ignore = other.doctor.ignore.clone();
        }
        if other.doctor.warnings_as_errors {
            self.doctor.warnings_as_errors = other.doctor.warnings_as_errors;
        }
        if !other.doctor.ignore_path.is_empty() {
            self.doctor.ignore_path = other.doctor.ignore_path.clone();
        }
    }
}

/// Result of discovering configuration.
#[derive(Debug, Clone)]
pub struct DiscoveredConfig {
    /// The resolved configuration.
    pub config: Config,
    /// The project root directory (where config was found).
    pub root: PathBuf,
    /// Where the config was loaded from.
    pub source: ConfigSource,
    /// Dotted paths of any keys in the loaded config file that did not match
    /// a known field (e.g. `"doctor.path"`). Empty when the config had no
    /// unrecognized keys, or when no config file was read (`ConfigSource::Default`).
    pub unknown_keys: Vec<String>,
}

/// Where the configuration was loaded from.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ConfigSource {
    /// Loaded from project config file.
    Project(PathBuf),
    /// Loaded from global config file.
    Global(PathBuf),
    /// Loaded from environment variable.
    Environment,
    /// Using defaults (no config found).
    Default,
}

/// Discover configuration by searching up the directory tree.
///
/// Search order:
/// 1. Environment variable `ADRS_CONFIG` (explicit config path)
/// 2. Search upward from `start_dir` for `.adr-dir` or `adrs.toml`
/// 3. Global config at `~/.config/adrs/config.toml`
/// 4. Default configuration
///
/// Environment variable `ADR_DIRECTORY` overrides the ADR directory.
pub fn discover(start_dir: &Path) -> Result<DiscoveredConfig> {
    // Check for explicit config path from environment
    if let Ok(config_path) = std::env::var(ENV_ADRS_CONFIG) {
        let path = PathBuf::from(&config_path);
        if path.exists() {
            let content = std::fs::read_to_string(&path)?;
            let (mut config, unknown_keys) = deserialize_config(&content)?;
            apply_env_overrides(&mut config);
            return Ok(DiscoveredConfig {
                config,
                root: path
                    .parent()
                    .map(|p| p.to_path_buf())
                    .unwrap_or_else(|| start_dir.to_path_buf()),
                source: ConfigSource::Environment,
                unknown_keys,
            });
        }
    }

    // Search upward for project config
    if let Some((root, config, source, unknown_keys)) = search_upward(start_dir)? {
        let mut config = config;
        apply_env_overrides(&mut config);
        return Ok(DiscoveredConfig {
            config,
            root,
            source,
            unknown_keys,
        });
    }

    // Try global config
    if let Some((config, path, unknown_keys)) = load_global_config()? {
        let mut config = config;
        apply_env_overrides(&mut config);
        return Ok(DiscoveredConfig {
            config,
            root: start_dir.to_path_buf(),
            source: ConfigSource::Global(path),
            unknown_keys,
        });
    }

    // Use defaults
    let mut config = Config::default();
    apply_env_overrides(&mut config);
    Ok(DiscoveredConfig {
        config,
        root: start_dir.to_path_buf(),
        source: ConfigSource::Default,
        unknown_keys: Vec::new(),
    })
}

/// Search upward from the given directory for a config file.
#[allow(clippy::type_complexity)]
fn search_upward(start_dir: &Path) -> Result<Option<(PathBuf, Config, ConfigSource, Vec<String>)>> {
    let mut current = start_dir.to_path_buf();

    loop {
        // Check for adrs.toml first
        let config_path = current.join(CONFIG_FILE);
        if config_path.exists() {
            let content = std::fs::read_to_string(&config_path)?;
            let (config, unknown_keys) = deserialize_config(&content)?;
            return Ok(Some((
                current,
                config,
                ConfigSource::Project(config_path),
                unknown_keys,
            )));
        }

        // Check for .adr-dir
        let legacy_path = current.join(LEGACY_CONFIG_FILE);
        if legacy_path.exists() {
            let adr_dir = std::fs::read_to_string(&legacy_path)?.trim().to_string();
            let config = Config {
                adr_dir: PathBuf::from(adr_dir),
                mode: ConfigMode::Compatible,
                default_status: None,
                no_edit: false,
                templates: TemplateConfig::default(),
                generate: GenerateConfig::default(),
                export: ExportConfig::default(),
                doctor: DoctorConfig::default(),
            };
            return Ok(Some((
                current,
                config,
                ConfigSource::Project(legacy_path),
                Vec::new(),
            )));
        }

        // Check for default ADR directory (indicates project root)
        let default_dir = current.join(DEFAULT_ADR_DIR);
        if default_dir.exists() {
            return Ok(Some((
                current,
                Config::default(),
                ConfigSource::Default,
                Vec::new(),
            )));
        }

        // Stop at git repository root
        if current.join(".git").exists() {
            break;
        }

        // Move to parent directory
        match current.parent() {
            Some(parent) => current = parent.to_path_buf(),
            None => break,
        }
    }

    Ok(None)
}

/// Load the global configuration file.
fn load_global_config() -> Result<Option<(Config, PathBuf, Vec<String>)>> {
    let config_dir = dirs_config_dir()?;
    let global_path = config_dir.join("adrs").join(GLOBAL_CONFIG_FILE);

    if global_path.exists() {
        let content = std::fs::read_to_string(&global_path)?;
        let (config, unknown_keys) = deserialize_config(&content)?;
        return Ok(Some((config, global_path, unknown_keys)));
    }

    Ok(None)
}

/// Get the user's config directory.
fn dirs_config_dir() -> Result<PathBuf> {
    // Try XDG_CONFIG_HOME first, then fall back to ~/.config
    if let Ok(xdg) = std::env::var("XDG_CONFIG_HOME") {
        return Ok(PathBuf::from(xdg));
    }

    if let Ok(home) = std::env::var("HOME") {
        return Ok(PathBuf::from(home).join(".config"));
    }

    // Windows fallback
    if let Ok(appdata) = std::env::var("APPDATA") {
        return Ok(PathBuf::from(appdata));
    }

    Err(Error::ConfigError(
        "Could not determine config directory".into(),
    ))
}

/// Apply environment variable overrides to a config.
fn apply_env_overrides(config: &mut Config) {
    if let Ok(adr_dir) = std::env::var(ENV_ADR_DIRECTORY) {
        config.adr_dir = PathBuf::from(adr_dir);
    }
}

/// The mode of operation for the ADR tool.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ConfigMode {
    /// Compatible with adr-tools (markdown-only, no frontmatter).
    #[default]
    Compatible,

    /// Next-gen mode with YAML frontmatter and enhanced features.
    #[serde(rename = "ng", alias = "nextgen")]
    NextGen,
}

/// Template configuration.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct TemplateConfig {
    /// The default template format to use.
    pub format: Option<String>,

    /// The default template variant to use.
    pub variant: Option<String>,

    /// Path to a custom template file.
    pub custom: Option<PathBuf>,
}

/// Generate command configuration.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct GenerateConfig {
    /// Default prefix for TOC links (used by `adrs generate toc` if `--prefix` is not given).
    pub toc_prefix: Option<String>,
}

/// Export command configuration.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct ExportConfig {
    /// Default base URL for source_uri in JSON export (used by `adrs export json` if `--base-url` is not given).
    pub base_url: Option<String>,
}

/// Doctor command configuration.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct DoctorConfig {
    /// Rule IDs or rule names to suppress repository-wide (e.g. "ADR011",
    /// "adr-numbering-sequential"). Matched case-insensitively against both
    /// Issue.rule_id and Issue.rule_name.
    pub ignore: Vec<String>,

    /// When true, `adrs doctor` exits with status 1 if there are warnings, not just errors.
    pub warnings_as_errors: bool,

    /// Path-scoped rule exemptions (issue #365). Unlike `ignore`, which
    /// suppresses a rule everywhere, each entry here suppresses `rules` only
    /// for diagnostics whose path (relative to the repository root) matches
    /// `glob`.
    pub ignore_path: Vec<DoctorIgnorePath>,
}

/// A single path-scoped rule exemption under `[[doctor.ignore_path]]`.
///
/// `glob` is matched, using `globset`, against a diagnostic's path relative
/// to the repository root with separators normalized to `/`. `rules` is
/// matched the same way `[doctor].ignore` is: case-insensitively against
/// both `Issue.rule_id` and `Issue.rule_name`.
///
/// Only diagnostics that carry a path can be scoped this way -- some rules
/// (the upstream collection rules ADR010-ADR012) never populate `path`, so
/// an entry that names only those rules can never suppress anything. See
/// `lint::check_all_filtered`.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(default)]
pub struct DoctorIgnorePath {
    /// Glob pattern matched against the diagnostic's path relative to the
    /// repository root (forward slashes, even on Windows).
    pub glob: String,

    /// Rule IDs or rule names to suppress when `glob` matches.
    pub rules: Vec<String>,
}

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

    // ========== Default and Constants Tests ==========

    #[test]
    fn test_default_config() {
        let config = Config::default();
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
        assert_eq!(config.mode, ConfigMode::Compatible);
        assert!(config.default_status.is_none());
        assert!(config.templates.format.is_none());
        assert!(config.templates.custom.is_none());
    }

    #[test]
    fn test_constants() {
        assert_eq!(DEFAULT_ADR_DIR, "doc/adr");
        assert_eq!(LEGACY_CONFIG_FILE, ".adr-dir");
        assert_eq!(CONFIG_FILE, "adrs.toml");
    }

    #[test]
    fn test_config_mode_default() {
        assert_eq!(ConfigMode::default(), ConfigMode::Compatible);
    }

    // ========== Load Configuration Tests ==========

    #[test]
    fn test_load_legacy_config() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "decisions").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("decisions"));
        assert_eq!(config.mode, ConfigMode::Compatible);
    }

    #[test]
    fn test_load_legacy_config_with_whitespace() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "  decisions  \n").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("decisions"));
    }

    #[test]
    fn test_load_legacy_config_nested_path() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "docs/architecture/decisions").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("docs/architecture/decisions"));
    }

    #[test]
    fn test_load_new_config() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "docs/decisions"
mode = "ng"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("docs/decisions"));
        assert_eq!(config.mode, ConfigMode::NextGen);
    }

    #[test]
    fn test_load_new_config_compatible_mode() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"
mode = "compatible"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.mode, ConfigMode::Compatible);
    }

    #[test]
    fn test_load_new_config_with_default_status() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"
default_status = "accepted"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.default_status, Some("accepted".to_string()));
    }

    #[test]
    fn test_load_new_config_with_templates() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "decisions"
mode = "ng"

[templates]
format = "markdown"
custom = "templates/adr.md"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.templates.format, Some("markdown".to_string()));
        assert_eq!(
            config.templates.custom,
            Some(PathBuf::from("templates/adr.md"))
        );
    }

    #[test]
    fn test_load_new_config_with_template_variant() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "decisions"
mode = "ng"

[templates]
format = "madr"
variant = "minimal"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.templates.format, Some("madr".to_string()));
        assert_eq!(config.templates.variant, Some("minimal".to_string()));
    }

    #[test]
    fn test_load_new_config_with_nextgen_alias() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "decisions"
mode = "nextgen"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.mode, ConfigMode::NextGen);
    }

    #[test]
    fn test_load_new_config_minimal() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"adr_dir = "adrs""#).unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("adrs"));
        // Should use defaults for missing fields
        assert_eq!(config.mode, ConfigMode::Compatible);
    }

    #[test]
    fn test_load_prefers_new_config_over_legacy() {
        let temp = TempDir::new().unwrap();
        // Create both config files
        std::fs::write(temp.path().join(".adr-dir"), "legacy-dir").unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"adr_dir = "new-dir""#).unwrap();

        let config = Config::load(temp.path()).unwrap();
        // Should prefer adrs.toml
        assert_eq!(config.adr_dir, PathBuf::from("new-dir"));
    }

    #[test]
    fn test_load_default_dir_exists() {
        let temp = TempDir::new().unwrap();
        // Create the default directory
        std::fs::create_dir_all(temp.path().join("doc/adr")).unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
    }

    #[test]
    fn test_load_no_config_no_default_dir() {
        let temp = TempDir::new().unwrap();
        // Empty directory - no config, no default dir

        let result = Config::load(temp.path());
        assert!(result.is_err());
    }

    #[test]
    fn test_load_or_default_returns_default_on_error() {
        let temp = TempDir::new().unwrap();
        // Empty directory - would error with load()

        let config = Config::load_or_default(temp.path());
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
        assert_eq!(config.mode, ConfigMode::Compatible);
    }

    #[test]
    fn test_load_or_default_returns_config_when_exists() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "custom-dir").unwrap();

        let config = Config::load_or_default(temp.path());
        assert_eq!(config.adr_dir, PathBuf::from("custom-dir"));
    }

    // ========== Save Configuration Tests ==========

    #[test]
    fn test_save_legacy_config() {
        let temp = TempDir::new().unwrap();
        let config = Config {
            adr_dir: PathBuf::from("my/adrs"),
            mode: ConfigMode::Compatible,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig::default(),
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        config.save(temp.path()).unwrap();

        let content = std::fs::read_to_string(temp.path().join(".adr-dir")).unwrap();
        assert_eq!(content, "my/adrs");
        // Should not create adrs.toml
        assert!(!temp.path().join("adrs.toml").exists());
    }

    #[test]
    fn test_save_new_config() {
        let temp = TempDir::new().unwrap();
        let config = Config {
            adr_dir: PathBuf::from("docs/decisions"),
            mode: ConfigMode::NextGen,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig::default(),
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        config.save(temp.path()).unwrap();

        let content = std::fs::read_to_string(temp.path().join("adrs.toml")).unwrap();
        assert!(content.contains("docs/decisions"));
        assert!(content.contains("ng"));
        // Should not create .adr-dir
        assert!(!temp.path().join(".adr-dir").exists());
    }

    #[test]
    fn test_save_new_config_with_templates() {
        let temp = TempDir::new().unwrap();
        let config = Config {
            adr_dir: PathBuf::from("decisions"),
            mode: ConfigMode::NextGen,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig {
                format: Some("custom".to_string()),
                variant: None,
                custom: Some(PathBuf::from("my-template.md")),
            },
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        config.save(temp.path()).unwrap();

        let content = std::fs::read_to_string(temp.path().join("adrs.toml")).unwrap();
        assert!(content.contains("custom"));
        assert!(content.contains("my-template.md"));
    }

    #[test]
    fn test_save_and_load_roundtrip_compatible() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            adr_dir: PathBuf::from("architecture/decisions"),
            mode: ConfigMode::Compatible,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig::default(),
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(loaded.adr_dir, original.adr_dir);
        assert_eq!(loaded.mode, ConfigMode::Compatible);
    }

    #[test]
    fn test_save_and_load_roundtrip_nextgen() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            adr_dir: PathBuf::from("docs/adr"),
            mode: ConfigMode::NextGen,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig {
                format: Some("markdown".to_string()),
                variant: None,
                custom: None,
            },
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(loaded.adr_dir, original.adr_dir);
        assert_eq!(loaded.mode, ConfigMode::NextGen);
        assert_eq!(loaded.templates.format, Some("markdown".to_string()));
    }

    // ========== Helper Method Tests ==========

    #[test_case("doc/adr", "/project" => PathBuf::from("/project/doc/adr"); "default path")]
    #[test_case("decisions", "/home/user/repo" => PathBuf::from("/home/user/repo/decisions"); "simple path")]
    #[test_case("docs/architecture/decisions", "/repo" => PathBuf::from("/repo/docs/architecture/decisions"); "nested path")]
    fn test_adr_path(adr_dir: &str, root: &str) -> PathBuf {
        let config = Config {
            adr_dir: PathBuf::from(adr_dir),
            ..Default::default()
        };
        config.adr_path(Path::new(root))
    }

    #[test]
    fn test_is_next_gen() {
        let compatible = Config {
            mode: ConfigMode::Compatible,
            ..Default::default()
        };
        assert!(!compatible.is_next_gen());

        let nextgen = Config {
            mode: ConfigMode::NextGen,
            ..Default::default()
        };
        assert!(nextgen.is_next_gen());
    }

    // ========== ConfigMode Tests ==========

    #[test]
    fn test_config_mode_equality() {
        assert_eq!(ConfigMode::Compatible, ConfigMode::Compatible);
        assert_eq!(ConfigMode::NextGen, ConfigMode::NextGen);
        assert_ne!(ConfigMode::Compatible, ConfigMode::NextGen);
    }

    #[test]
    fn test_config_mode_serialization_in_config() {
        // TOML requires enums to be serialized within a struct
        let config = Config {
            mode: ConfigMode::Compatible,
            ..Default::default()
        };
        let toml = toml::to_string(&config).unwrap();
        assert!(toml.contains("mode = \"compatible\""));

        let config = Config {
            mode: ConfigMode::NextGen,
            ..Default::default()
        };
        let toml = toml::to_string(&config).unwrap();
        assert!(toml.contains("mode = \"ng\""));
    }

    #[test]
    fn test_config_mode_deserialization_in_config() {
        let config: Config = toml::from_str(r#"mode = "compatible""#).unwrap();
        assert_eq!(config.mode, ConfigMode::Compatible);

        let config: Config = toml::from_str(r#"mode = "ng""#).unwrap();
        assert_eq!(config.mode, ConfigMode::NextGen);
    }

    #[test]
    fn test_config_mode_deserialization_nextgen_alias() {
        let config: Config = toml::from_str(r#"mode = "nextgen""#).unwrap();
        assert_eq!(config.mode, ConfigMode::NextGen);
    }

    // ========== TemplateConfig Tests ==========

    #[test]
    fn test_template_config_default() {
        let config = TemplateConfig::default();
        assert!(config.format.is_none());
        assert!(config.variant.is_none());
        assert!(config.custom.is_none());
    }

    #[test]
    fn test_template_config_serialization() {
        let config = TemplateConfig {
            format: Some("nygard".to_string()),
            variant: None,
            custom: Some(PathBuf::from("templates/custom.md")),
        };

        let toml = toml::to_string(&config).unwrap();
        assert!(toml.contains("nygard"));
        assert!(toml.contains("templates/custom.md"));
    }

    // ========== Error Cases ==========

    #[test]
    fn test_load_invalid_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "this is not valid toml {{{").unwrap();

        let result = Config::load(temp.path());
        assert!(result.is_err());
    }

    #[test]
    fn test_load_empty_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "").unwrap();

        // Empty TOML should use defaults
        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
    }

    #[test]
    fn test_load_empty_adr_dir_file() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "").unwrap();

        let result = Config::load(temp.path());
        assert!(result.is_err(), "Empty .adr-dir should produce an error");
    }

    // ========== Config Discovery Tests ==========

    #[test]
    fn test_discover_finds_config_in_current_dir() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "decisions").unwrap();

        let discovered = discover(temp.path()).unwrap();
        assert_eq!(discovered.root, temp.path());
        assert_eq!(discovered.config.adr_dir, PathBuf::from("decisions"));
        assert!(matches!(discovered.source, ConfigSource::Project(_)));
    }

    #[test]
    fn test_discover_finds_config_in_parent_dir() {
        let temp = TempDir::new().unwrap();
        let subdir = temp.path().join("src").join("lib");
        std::fs::create_dir_all(&subdir).unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"adr_dir = "docs/adr""#).unwrap();

        let discovered = discover(&subdir).unwrap();
        assert_eq!(discovered.root, temp.path());
        assert_eq!(discovered.config.adr_dir, PathBuf::from("docs/adr"));
    }

    #[test]
    fn test_discover_stops_at_git_root() {
        let temp = TempDir::new().unwrap();

        // Create a git repo structure
        std::fs::create_dir(temp.path().join(".git")).unwrap();
        let subdir = temp.path().join("src");
        std::fs::create_dir(&subdir).unwrap();

        // Put config above git root (should not be found)
        // This test verifies we stop at .git

        let result = discover(&subdir);
        // Should return defaults since no config found within git repo
        assert!(result.is_ok());
        let discovered = result.unwrap();
        assert!(matches!(discovered.source, ConfigSource::Default));
    }

    #[test]
    fn test_discover_prefers_adrs_toml_over_adr_dir() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "legacy").unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"adr_dir = "modern""#).unwrap();

        let discovered = discover(temp.path()).unwrap();
        assert_eq!(discovered.config.adr_dir, PathBuf::from("modern"));
    }

    #[test]
    fn test_discover_finds_default_adr_dir() {
        let temp = TempDir::new().unwrap();
        std::fs::create_dir_all(temp.path().join("doc/adr")).unwrap();

        let discovered = discover(temp.path()).unwrap();
        assert_eq!(discovered.root, temp.path());
        assert_eq!(discovered.config.adr_dir, PathBuf::from("doc/adr"));
    }

    #[test]
    fn test_discover_returns_defaults_when_nothing_found() {
        let temp = TempDir::new().unwrap();
        // Create .git to stop search
        std::fs::create_dir(temp.path().join(".git")).unwrap();

        let discovered = discover(temp.path()).unwrap();
        assert!(matches!(discovered.source, ConfigSource::Default));
        assert_eq!(discovered.config.adr_dir, PathBuf::from("doc/adr"));
    }

    // Serializes tests that mutate the process-global ADR_DIRECTORY env var.
    // `std::env` is shared across cargo's parallel test threads, so without this
    // lock these tests race and clobber each other's values (issue #241 follow-up).
    // `unwrap_or_else(into_inner)` recovers the guard even if a prior test panicked
    // while holding the lock (poisoned mutex).
    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    #[test]
    fn test_apply_env_overrides() {
        let _env = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        // Test apply_env_overrides when ADR_DIRECTORY is not set.
        let old = std::env::var(ENV_ADR_DIRECTORY).ok();
        // SAFETY: serialized by ENV_LOCK; env restored before returning.
        unsafe { std::env::remove_var(ENV_ADR_DIRECTORY) };

        let mut config = Config::default();
        apply_env_overrides(&mut config);

        unsafe {
            if let Some(v) = old {
                std::env::set_var(ENV_ADR_DIRECTORY, v);
            }
        }

        // With no env var set, the config should remain at default
        assert_eq!(config.adr_dir, PathBuf::from(DEFAULT_ADR_DIR));
    }

    // ========== apply_env_overrides positive cases (issue #241) ==========
    // Env vars are process-global; these tests serialize via ENV_LOCK and
    // save/restore the old value so they neither race nor leak state.
    // In Rust 2024 edition, set_var/remove_var require unsafe blocks.

    #[test]
    fn test_apply_env_overrides_sets_adr_dir() {
        let _env = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        // Save old value
        let old = std::env::var(ENV_ADR_DIRECTORY).ok();

        // SAFETY: single-threaded test; restoring env after test
        unsafe { std::env::set_var(ENV_ADR_DIRECTORY, "my/custom/adr/dir") };
        let mut config = Config::default();
        apply_env_overrides(&mut config);

        // Restore before asserting (so a panic does not leave env dirty)
        unsafe {
            match old {
                Some(v) => std::env::set_var(ENV_ADR_DIRECTORY, v),
                None => std::env::remove_var(ENV_ADR_DIRECTORY),
            }
        }

        assert_eq!(config.adr_dir, PathBuf::from("my/custom/adr/dir"));
    }

    #[test]
    fn test_apply_env_overrides_overrides_non_default_adr_dir() {
        let _env = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        // Verify env override wins even when config already has a custom path
        let old = std::env::var(ENV_ADR_DIRECTORY).ok();

        // SAFETY: single-threaded test; restoring env after test
        unsafe { std::env::set_var(ENV_ADR_DIRECTORY, "env_override") };
        let mut config = Config {
            adr_dir: PathBuf::from("config_dir"),
            ..Default::default()
        };
        apply_env_overrides(&mut config);

        unsafe {
            match old {
                Some(v) => std::env::set_var(ENV_ADR_DIRECTORY, v),
                None => std::env::remove_var(ENV_ADR_DIRECTORY),
            }
        }

        assert_eq!(config.adr_dir, PathBuf::from("env_override"));
    }

    #[test]
    fn test_apply_env_overrides_no_adr_dir_var_leaves_config_unchanged() {
        let _env = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        // Without ADR_DIRECTORY set, config is unchanged
        let old = std::env::var(ENV_ADR_DIRECTORY).ok();

        // SAFETY: single-threaded test; restoring env after test
        unsafe { std::env::remove_var(ENV_ADR_DIRECTORY) };

        let mut config = Config {
            adr_dir: PathBuf::from("original/path"),
            ..Default::default()
        };
        apply_env_overrides(&mut config);

        unsafe {
            match old {
                Some(v) => std::env::set_var(ENV_ADR_DIRECTORY, v),
                None => std::env::remove_var(ENV_ADR_DIRECTORY),
            }
        }

        assert_eq!(config.adr_dir, PathBuf::from("original/path"));
    }

    #[test]
    fn test_config_source_variants() {
        // Test that ConfigSource can be compared
        let project = ConfigSource::Project(PathBuf::from("test"));
        let global = ConfigSource::Global(PathBuf::from("test"));
        let env = ConfigSource::Environment;
        let default = ConfigSource::Default;

        assert_ne!(project, global);
        assert_ne!(env, default);
        assert_eq!(default, ConfigSource::Default);
    }

    #[test]
    fn test_config_merge() {
        let mut base = Config::default();
        let other = Config {
            adr_dir: PathBuf::from("custom"),
            mode: ConfigMode::NextGen,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig {
                format: Some("madr".to_string()),
                variant: None,
                custom: None,
            },
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        base.merge(&other);
        assert_eq!(base.adr_dir, PathBuf::from("custom"));
        assert_eq!(base.mode, ConfigMode::NextGen);
        assert_eq!(base.templates.format, Some("madr".to_string()));
    }

    #[test]
    fn test_config_merge_preserves_default_adr_dir() {
        let mut base = Config {
            adr_dir: PathBuf::from("original"),
            ..Default::default()
        };
        let other = Config::default(); // has default adr_dir

        base.merge(&other);
        // Should keep original since other has default
        assert_eq!(base.adr_dir, PathBuf::from("original"));
    }

    #[test]
    fn test_config_merge_default_status() {
        let mut base = Config::default();
        let other = Config {
            default_status: Some("accepted".to_string()),
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.default_status, Some("accepted".to_string()));
    }

    // ========== no_edit Tests ==========

    #[test]
    fn test_no_edit_defaults_to_false() {
        let config = Config::default();
        assert!(!config.no_edit);
    }

    #[test]
    fn test_no_edit_true_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            "adr_dir = \"doc/adr\"\nno_edit = true\n",
        )
        .unwrap();
        let config = Config::load(temp.path()).unwrap();
        assert!(config.no_edit);
    }

    #[test]
    fn test_no_edit_false_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            "adr_dir = \"doc/adr\"\nno_edit = false\n",
        )
        .unwrap();
        let config = Config::load(temp.path()).unwrap();
        assert!(!config.no_edit);
    }

    #[test]
    fn test_no_edit_absent_from_toml_defaults_false() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "adr_dir = \"doc/adr\"\n").unwrap();
        let config = Config::load(temp.path()).unwrap();
        assert!(!config.no_edit);
    }

    #[test]
    fn test_config_merge_no_edit() {
        let mut base = Config::default();
        let other = Config {
            no_edit: true,
            ..Default::default()
        };
        base.merge(&other);
        assert!(base.no_edit);
    }

    #[test]
    fn test_config_merge_no_edit_false_does_not_overwrite_true() {
        // merge: other.no_edit=false should NOT overwrite base.no_edit=true
        let mut base = Config {
            no_edit: true,
            ..Default::default()
        };
        let other = Config::default(); // no_edit = false
        base.merge(&other);
        assert!(
            base.no_edit,
            "merge with no_edit=false should not overwrite true"
        );
    }

    #[test]
    fn test_no_edit_save_load_roundtrip() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            adr_dir: PathBuf::from("doc/adr"),
            mode: ConfigMode::NextGen,
            no_edit: true,
            ..Default::default()
        };
        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();
        assert!(loaded.no_edit);
    }

    // ========== Config Validation Tests ==========

    #[test]
    fn test_load_empty_adr_dir_in_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"adr_dir = """#).unwrap();

        let result = Config::load(temp.path());
        assert!(
            result.is_err(),
            "Empty adr_dir in TOML should produce an error"
        );
    }

    #[test]
    fn test_load_whitespace_only_adr_dir_file() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join(".adr-dir"), "   \n  ").unwrap();

        let result = Config::load(temp.path());
        assert!(
            result.is_err(),
            "Whitespace-only .adr-dir should produce an error"
        );
    }

    #[test]
    fn test_invalid_format_string_accepted_in_toml() {
        // Invalid format strings are stored as-is in config; they only error
        // when parsed at ADR creation time. This is by design — the config
        // layer stores strings, the command layer validates them.
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[templates]
format = "nonexistent"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.templates.format, Some("nonexistent".to_string()));
    }

    #[test]
    fn test_invalid_variant_string_accepted_in_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[templates]
variant = "bogus"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.templates.variant, Some("bogus".to_string()));
    }

    #[test]
    fn test_invalid_mode_string_rejected() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), r#"mode = "invalid_mode""#).unwrap();

        let result = Config::load(temp.path());
        assert!(
            result.is_err(),
            "Invalid mode should produce a TOML parse error"
        );
    }

    #[test]
    fn test_unknown_toml_fields_accepted() {
        // Unknown fields don't fail `Config::load` -- they never have, and
        // still don't after adding unknown-key reporting (see the
        // `deserialize_config` tests below for the reporting behavior itself).
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"
unknown_field = "hello"

[templates]
also_unknown = true
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
    }

    // ========== deserialize_config / unknown-key reporting tests (issue #363) ==========

    #[test]
    fn test_deserialize_config_reports_unknown_top_level_key() {
        let (config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"
made_up_key = "hello"
"#,
        )
        .unwrap();

        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
        assert_eq!(unknown_keys, vec!["made_up_key".to_string()]);
    }

    #[test]
    fn test_deserialize_config_reports_nested_doctor_key_as_dotted_path() {
        // The issue's exact reproduction: an invented `[doctor].path` key.
        let (_config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[doctor]
path = "docs/decisions/0025-example.md"
ignore = ["ADR014"]
"#,
        )
        .unwrap();

        assert_eq!(unknown_keys, vec!["doctor.path".to_string()]);
    }

    #[test]
    fn test_deserialize_config_reports_typo_in_warnings_as_errors() {
        let (config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[doctor]
warnings_as_erors = true
"#,
        )
        .unwrap();

        // The typo'd key is reported...
        assert_eq!(unknown_keys, vec!["doctor.warnings_as_erors".to_string()]);
        // ...and the real field silently keeps its default, exactly the trap
        // described in the issue: no diagnostic either way without this fix.
        assert!(!config.doctor.warnings_as_errors);
    }

    #[test]
    fn test_deserialize_config_reports_nothing_for_valid_config() {
        let (config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"
mode = "ng"
default_status = "accepted"
no_edit = true

[templates]
format = "madr"
variant = "minimal"
custom = "templates/adr.md"

[generate]
toc_prefix = "./"

[export]
base_url = "https://example.com/adr"

[doctor]
ignore = ["ADR011"]
warnings_as_errors = true
"#,
        )
        .unwrap();

        assert!(
            unknown_keys.is_empty(),
            "expected no unknown keys, got {unknown_keys:?}"
        );
        assert_eq!(config.adr_dir, PathBuf::from("doc/adr"));
    }

    #[test]
    fn test_deserialize_config_reports_unknown_key_in_templates() {
        let (_config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[templates]
format = "madr"
bogus = "value"
"#,
        )
        .unwrap();

        assert_eq!(unknown_keys, vec!["templates.bogus".to_string()]);
    }

    #[test]
    fn test_deserialize_config_reports_unknown_key_in_generate() {
        let (_config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[generate]
toc_prefix = "./"
bogus = "value"
"#,
        )
        .unwrap();

        assert_eq!(unknown_keys, vec!["generate.bogus".to_string()]);
    }

    #[test]
    fn test_deserialize_config_reports_unknown_key_in_export() {
        let (_config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[export]
base_url = "https://example.com/adr"
bogus = "value"
"#,
        )
        .unwrap();

        assert_eq!(unknown_keys, vec!["export.bogus".to_string()]);
    }

    #[test]
    fn test_deserialize_config_malformed_toml_still_errors() {
        let result = deserialize_config("this is not valid toml {{{");
        assert!(result.is_err(), "malformed TOML should still error");
        assert!(
            matches!(result, Err(Error::Toml(_))),
            "malformed TOML should still produce Error::Toml, unchanged from toml::from_str"
        );
    }

    #[test]
    fn test_deserialize_config_written_by_adrs_config_reports_no_unknown_keys() {
        // Round-trip: a config written by `Config::save` (what `adrs config`
        // and `adrs init --ng` write) must not itself look like it has
        // unrecognized keys.
        let temp = TempDir::new().unwrap();
        let original = Config {
            adr_dir: PathBuf::from("docs/decisions"),
            mode: ConfigMode::NextGen,
            default_status: Some("accepted".to_string()),
            no_edit: true,
            templates: TemplateConfig {
                format: Some("madr".to_string()),
                variant: Some("minimal".to_string()),
                custom: Some(PathBuf::from("templates/adr.md")),
            },
            generate: GenerateConfig {
                toc_prefix: Some("./".to_string()),
            },
            export: ExportConfig {
                base_url: Some("https://example.com/adr".to_string()),
            },
            doctor: DoctorConfig {
                ignore: vec!["ADR011".to_string()],
                warnings_as_errors: true,
                ignore_path: Vec::new(),
            },
        };
        original.save(temp.path()).unwrap();

        let content = std::fs::read_to_string(temp.path().join("adrs.toml")).unwrap();
        let (_config, unknown_keys) = deserialize_config(&content).unwrap();

        assert!(
            unknown_keys.is_empty(),
            "a config written by Config::save should report no unknown keys, got {unknown_keys:?}"
        );
    }

    #[test]
    fn test_custom_template_path_in_config() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"
mode = "ng"

[templates]
custom = "templates/my-adr.md"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(
            config.templates.custom,
            Some(PathBuf::from("templates/my-adr.md"))
        );
    }

    // ========== Save/Load Roundtrip Tests ==========

    #[test]
    fn test_save_and_load_roundtrip_nextgen_with_templates() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            adr_dir: PathBuf::from("docs/decisions"),
            mode: ConfigMode::NextGen,
            default_status: None,
            no_edit: false,
            templates: TemplateConfig {
                format: Some("madr".to_string()),
                variant: Some("minimal".to_string()),
                custom: Some(PathBuf::from("templates/custom.md")),
            },
            generate: GenerateConfig::default(),
            export: ExportConfig::default(),
            doctor: DoctorConfig::default(),
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(loaded.adr_dir, PathBuf::from("docs/decisions"));
        assert_eq!(loaded.mode, ConfigMode::NextGen);
        assert_eq!(loaded.templates.format, Some("madr".to_string()));
        assert_eq!(loaded.templates.variant, Some("minimal".to_string()));
        assert_eq!(
            loaded.templates.custom,
            Some(PathBuf::from("templates/custom.md"))
        );
    }

    #[test]
    fn test_save_and_load_roundtrip_nextgen_mode_serializes_as_ng() {
        // NextGen serializes as "ng" but should load back as NextGen
        let temp = TempDir::new().unwrap();
        let original = Config {
            mode: ConfigMode::NextGen,
            ..Default::default()
        };

        original.save(temp.path()).unwrap();

        // Verify the file contains "ng" not "nextgen"
        let content = std::fs::read_to_string(temp.path().join("adrs.toml")).unwrap();
        assert!(content.contains(r#"mode = "ng""#));

        // Load it back
        let loaded = Config::load(temp.path()).unwrap();
        assert_eq!(loaded.mode, ConfigMode::NextGen);
    }

    // ========== Config Merge Validation Tests ==========

    #[test]
    fn test_config_merge_variant_field() {
        let mut base = Config::default();
        let other = Config {
            templates: TemplateConfig {
                format: None,
                variant: Some("minimal".to_string()),
                custom: None,
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.templates.variant, Some("minimal".to_string()));
    }

    #[test]
    fn test_config_merge_custom_field() {
        let mut base = Config::default();
        let other = Config {
            templates: TemplateConfig {
                format: None,
                variant: None,
                custom: Some(PathBuf::from("my-template.md")),
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.templates.custom, Some(PathBuf::from("my-template.md")));
    }

    #[test]
    fn test_config_merge_does_not_overwrite_with_none() {
        let mut base = Config {
            templates: TemplateConfig {
                format: Some("madr".to_string()),
                variant: Some("minimal".to_string()),
                custom: Some(PathBuf::from("template.md")),
            },
            ..Default::default()
        };
        let other = Config::default(); // all template fields are None

        base.merge(&other);

        // None values in other should NOT overwrite existing values
        assert_eq!(base.templates.format, Some("madr".to_string()));
        assert_eq!(base.templates.variant, Some("minimal".to_string()));
        assert_eq!(base.templates.custom, Some(PathBuf::from("template.md")));
    }

    // ========== GenerateConfig / toc_prefix Tests ==========

    #[test]
    fn test_generate_config_default() {
        let config = GenerateConfig::default();
        assert!(config.toc_prefix.is_none());
    }

    #[test]
    fn test_generate_toc_prefix_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[generate]
toc_prefix = "./"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.generate.toc_prefix, Some("./".to_string()));
    }

    #[test]
    fn test_generate_toc_prefix_absent_defaults_none() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "adr_dir = \"doc/adr\"\n").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert!(config.generate.toc_prefix.is_none());
    }

    #[test]
    fn test_config_merge_generate_toc_prefix() {
        let mut base = Config::default();
        let other = Config {
            generate: GenerateConfig {
                toc_prefix: Some("./".to_string()),
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.generate.toc_prefix, Some("./".to_string()));
    }

    #[test]
    fn test_config_merge_generate_toc_prefix_none_does_not_overwrite() {
        let mut base = Config {
            generate: GenerateConfig {
                toc_prefix: Some("docs/".to_string()),
            },
            ..Default::default()
        };
        let other = Config::default(); // toc_prefix = None

        base.merge(&other);
        assert_eq!(
            base.generate.toc_prefix,
            Some("docs/".to_string()),
            "merge with toc_prefix=None should not overwrite existing value"
        );
    }

    #[test]
    fn test_generate_toc_prefix_save_load_roundtrip() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            mode: ConfigMode::NextGen,
            generate: GenerateConfig {
                toc_prefix: Some("wiki/adr/".to_string()),
            },
            ..Default::default()
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(
            loaded.generate.toc_prefix,
            Some("wiki/adr/".to_string()),
            "toc_prefix should survive a save/load round-trip"
        );
    }

    // ========== ExportConfig / base_url Tests ==========

    #[test]
    fn test_export_config_default() {
        let config = ExportConfig::default();
        assert!(config.base_url.is_none());
    }

    #[test]
    fn test_export_base_url_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[export]
base_url = "https://github.com/org/repo/blob/main/doc/adr"
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(
            config.export.base_url,
            Some("https://github.com/org/repo/blob/main/doc/adr".to_string())
        );
    }

    #[test]
    fn test_export_base_url_absent_defaults_none() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "adr_dir = \"doc/adr\"\n").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert!(config.export.base_url.is_none());
    }

    #[test]
    fn test_config_merge_export_base_url() {
        let mut base = Config::default();
        let other = Config {
            export: ExportConfig {
                base_url: Some("https://example.com/adr".to_string()),
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(
            base.export.base_url,
            Some("https://example.com/adr".to_string())
        );
    }

    #[test]
    fn test_config_merge_export_base_url_none_does_not_overwrite() {
        let mut base = Config {
            export: ExportConfig {
                base_url: Some("https://existing.example.com/adr".to_string()),
            },
            ..Default::default()
        };
        let other = Config::default(); // export.base_url = None

        base.merge(&other);
        assert_eq!(
            base.export.base_url,
            Some("https://existing.example.com/adr".to_string()),
            "merge with export.base_url=None should not overwrite existing value"
        );
    }

    #[test]
    fn test_export_base_url_save_load_roundtrip() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            mode: ConfigMode::NextGen,
            export: ExportConfig {
                base_url: Some("https://github.com/org/repo/blob/main/doc/adr".to_string()),
            },
            ..Default::default()
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(
            loaded.export.base_url,
            Some("https://github.com/org/repo/blob/main/doc/adr".to_string()),
            "export.base_url should survive a save/load round-trip"
        );
    }

    // ========== DoctorConfig / ignore, warnings_as_errors Tests ==========

    #[test]
    fn test_doctor_config_default() {
        let config = DoctorConfig::default();
        assert!(config.ignore.is_empty());
        assert!(!config.warnings_as_errors);
    }

    #[test]
    fn test_doctor_ignore_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[doctor]
ignore = ["ADR011", "MD013"]
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(
            config.doctor.ignore,
            vec!["ADR011".to_string(), "MD013".to_string()]
        );
    }

    #[test]
    fn test_doctor_warnings_as_errors_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[doctor]
warnings_as_errors = true
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert!(config.doctor.warnings_as_errors);
    }

    #[test]
    fn test_doctor_config_absent_defaults() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "adr_dir = \"doc/adr\"\n").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert!(config.doctor.ignore.is_empty());
        assert!(!config.doctor.warnings_as_errors);
    }

    #[test]
    fn test_config_merge_doctor_ignore() {
        let mut base = Config::default();
        let other = Config {
            doctor: DoctorConfig {
                ignore: vec!["ADR011".to_string()],
                warnings_as_errors: false,
                ..Default::default()
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.doctor.ignore, vec!["ADR011".to_string()]);

        // An empty ignore list in `other` must not clobber an existing base list.
        let mut base = Config {
            doctor: DoctorConfig {
                ignore: vec!["ADR011".to_string()],
                warnings_as_errors: false,
                ..Default::default()
            },
            ..Default::default()
        };
        let other = Config::default(); // doctor.ignore is empty

        base.merge(&other);
        assert_eq!(
            base.doctor.ignore,
            vec!["ADR011".to_string()],
            "merge with empty doctor.ignore should not overwrite existing value"
        );
    }

    #[test]
    fn test_config_merge_doctor_warnings_as_errors() {
        // merge: other.warnings_as_errors=false should NOT overwrite base.warnings_as_errors=true
        let mut base = Config {
            doctor: DoctorConfig {
                ignore: vec![],
                warnings_as_errors: true,
                ..Default::default()
            },
            ..Default::default()
        };
        let other = Config::default(); // warnings_as_errors = false
        base.merge(&other);
        assert!(
            base.doctor.warnings_as_errors,
            "merge with warnings_as_errors=false should not overwrite true"
        );
    }

    #[test]
    fn test_doctor_config_save_load_roundtrip() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            mode: ConfigMode::NextGen,
            doctor: DoctorConfig {
                ignore: vec!["ADR011".to_string()],
                warnings_as_errors: true,
                ..Default::default()
            },
            ..Default::default()
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(loaded.doctor.ignore, vec!["ADR011".to_string()]);
        assert!(loaded.doctor.warnings_as_errors);
    }

    // ========== DoctorConfig / ignore_path Tests (issue #365) ==========

    #[test]
    fn test_doctor_ignore_path_default_empty() {
        let config = DoctorConfig::default();
        assert!(config.ignore_path.is_empty());
    }

    #[test]
    fn test_doctor_ignore_path_from_toml() {
        let temp = TempDir::new().unwrap();
        std::fs::write(
            temp.path().join("adrs.toml"),
            r#"
adr_dir = "doc/adr"

[doctor]
ignore = ["ADR011"]

[[doctor.ignore_path]]
glob = "doc/adr/0025-*.md"
rules = ["ADR014"]

[[doctor.ignore_path]]
glob = "doc/adr/legacy/**"
rules = ["ADR001", "adr-required-sections"]
"#,
        )
        .unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert_eq!(config.doctor.ignore, vec!["ADR011".to_string()]);
        assert_eq!(config.doctor.ignore_path.len(), 2);
        assert_eq!(config.doctor.ignore_path[0].glob, "doc/adr/0025-*.md");
        assert_eq!(
            config.doctor.ignore_path[0].rules,
            vec!["ADR014".to_string()]
        );
        assert_eq!(config.doctor.ignore_path[1].glob, "doc/adr/legacy/**");
        assert_eq!(
            config.doctor.ignore_path[1].rules,
            vec!["ADR001".to_string(), "adr-required-sections".to_string()]
        );
    }

    #[test]
    fn test_doctor_ignore_path_absent_defaults_empty() {
        let temp = TempDir::new().unwrap();
        std::fs::write(temp.path().join("adrs.toml"), "adr_dir = \"doc/adr\"\n").unwrap();

        let config = Config::load(temp.path()).unwrap();
        assert!(config.doctor.ignore_path.is_empty());
    }

    #[test]
    fn test_doctor_ignore_path_save_load_roundtrip() {
        let temp = TempDir::new().unwrap();
        let original = Config {
            mode: ConfigMode::NextGen,
            doctor: DoctorConfig {
                ignore: vec!["ADR011".to_string()],
                warnings_as_errors: true,
                ignore_path: vec![DoctorIgnorePath {
                    glob: "doc/adr/0025-*.md".to_string(),
                    rules: vec!["ADR014".to_string()],
                }],
            },
            ..Default::default()
        };

        original.save(temp.path()).unwrap();
        let loaded = Config::load(temp.path()).unwrap();

        assert_eq!(loaded.doctor.ignore_path.len(), 1);
        assert_eq!(loaded.doctor.ignore_path[0].glob, "doc/adr/0025-*.md");
        assert_eq!(
            loaded.doctor.ignore_path[0].rules,
            vec!["ADR014".to_string()]
        );
    }

    #[test]
    fn test_config_merge_doctor_ignore_path() {
        let mut base = Config::default();
        let other = Config {
            doctor: DoctorConfig {
                ignore_path: vec![DoctorIgnorePath {
                    glob: "doc/adr/0025-*.md".to_string(),
                    rules: vec!["ADR014".to_string()],
                }],
                ..Default::default()
            },
            ..Default::default()
        };

        base.merge(&other);
        assert_eq!(base.doctor.ignore_path.len(), 1);
        assert_eq!(base.doctor.ignore_path[0].glob, "doc/adr/0025-*.md");

        // An empty ignore_path list in `other` must not clobber an existing base list.
        let mut base = Config {
            doctor: DoctorConfig {
                ignore_path: vec![DoctorIgnorePath {
                    glob: "doc/adr/0025-*.md".to_string(),
                    rules: vec!["ADR014".to_string()],
                }],
                ..Default::default()
            },
            ..Default::default()
        };
        let other = Config::default(); // doctor.ignore_path is empty

        base.merge(&other);
        assert_eq!(
            base.doctor.ignore_path.len(),
            1,
            "merge with empty doctor.ignore_path should not overwrite existing value"
        );
    }

    #[test]
    fn test_deserialize_config_reports_unknown_key_in_doctor_ignore_path() {
        // The #363 warning walks the whole document, so an unknown key inside
        // an array-of-tables entry must be reported the same way as an unknown
        // top-level or nested-table key.
        let (_config, unknown_keys) = deserialize_config(
            r#"
adr_dir = "doc/adr"

[[doctor.ignore_path]]
glob = "doc/adr/0025-*.md"
rules = ["ADR014"]
reason = "false positive on this record"
"#,
        )
        .unwrap();

        assert_eq!(
            unknown_keys,
            vec!["doctor.ignore_path.0.reason".to_string()]
        );
    }
}