cmakefmt/config/

mod.rs

// SPDX-FileCopyrightText: Copyright 2026 Puneet Matharu
//
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Runtime formatter configuration.
//!
//! [`Config`] is the fully resolved in-memory configuration used by the
//! formatter. It is built from defaults, user config files
//! (`.cmakefmt.yaml`, `.cmakefmt.yml`, or `.cmakefmt.toml`), and CLI
//! overrides.
//!
//! # User config file schema
//!
//! User-facing config files are parsed under a separate schema
//! (internal to this module) that groups options into named sections:
//!
//! | Section | Purpose |
//! |---------|---------|
//! | `[format]` | Line width, indentation, casing, dangle-paren policy, wrapping heuristics |
//! | `[markup]` | Comment reflow knobs, markup detection patterns, ruler canonicalization |
//! | `[per_command_overrides]` | Per-command layout overrides keyed by lowercase command name |
//! | `[commands]` | Command-spec extensions (parsed by [`crate::spec::registry::CommandRegistry`]) |
//!
//! [`Config::from_file`], [`Config::from_yaml_str`], and
//! [`Config::for_file`] load these files and return a resolved
//! runtime [`Config`]. Unknown fields are rejected.

#[cfg(all(not(target_arch = "wasm32"), feature = "cli"))]
#[doc(hidden)]
pub mod editorconfig;
pub mod file;
#[cfg(all(not(target_arch = "wasm32"), feature = "cli"))]
mod legacy;
/// Render a commented starter config template.
pub use file::default_config_template;
#[cfg(feature = "cli")]
pub use file::{
    default_config_template_for, generate_json_schema, render_effective_config, DumpConfigFormat,
};
#[cfg(all(not(target_arch = "wasm32"), feature = "cli"))]
pub use legacy::convert_legacy_config_files;

use std::collections::HashMap;

use regex::Regex;
use serde::{Deserialize, Serialize};

/// How to normalise command/keyword casing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum, schemars::JsonSchema))]
#[serde(rename_all = "lowercase")]
pub enum CaseStyle {
    /// Force lowercase output.
    Lower,
    /// Force uppercase output.
    #[default]
    Upper,
    /// Preserve the original source casing.
    Unchanged,
}

/// Output line-ending style.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum, schemars::JsonSchema))]
#[serde(rename_all = "lowercase")]
pub enum LineEnding {
    /// Unix-style LF (`\n`). The default.
    #[default]
    Unix,
    /// Windows-style CRLF (`\r\n`).
    Windows,
    /// Auto-detect the line ending from the input source.
    Auto,
}

/// How to handle fractional tab indentation when [`Config::use_tabchars`] is
/// `true`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum, schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum FractionalTabPolicy {
    /// Leave fractional spaces as-is (utf-8 0x20). The default.
    #[default]
    UseSpace,
    /// Round fractional indentation up to the next full tab stop (utf-8 0x09).
    RoundUp,
}

/// How to indent continuation lines when a wrapped keyword section
/// overflows [`Config::line_width`].
///
/// Suppose `PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
/// GROUP_EXECUTE GROUP_READ` exceeds the line budget under a
/// `PATTERN *.h` subgroup:
///
/// ```cmake
/// # SameIndent — continuation wraps at the subkwarg indent:
/// PATTERN *.h
///   PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
///   GROUP_EXECUTE GROUP_READ
///
/// # UnderFirstValue — continuation aligns under the first value
/// # after the keyword:
/// PATTERN *.h
///   PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
///               GROUP_EXECUTE GROUP_READ
/// ```
///
/// cmakefmt defaults to [`ContinuationAlign::UnderFirstValue`]: when
/// a subkwarg group overflows, continuation lands under the first
/// value column so the eye can tell continuation values apart from
/// sibling subkwargs. This also matches cmake-format's hanging-indent
/// style, easing migration. [`ContinuationAlign::SameIndent`] is
/// available for consumers who prefer continuation at the subkwarg's
/// own column — consistent with how flat keyword sections
/// (`PUBLIC`/`PRIVATE`/…) and positional lists wrap elsewhere in the
/// formatter.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum, schemars::JsonSchema))]
#[serde(rename_all = "kebab-case")]
pub enum ContinuationAlign {
    /// Continuation lines wrap at the same indent as the keyword
    /// itself. Consistent with how the rest of the formatter wraps
    /// flat-list sections and positional argument lists.
    SameIndent,
    /// Continuation lines align under the first value after the
    /// keyword (cmake-format's hanging-indent style). The default.
    #[default]
    UnderFirstValue,
}

/// How to align the dangling closing paren.
///
/// Only takes effect when [`Config::dangle_parens`] is `true`.
/// Controls where `)` is placed when a call wraps onto multiple lines.
///
/// At the top level (block depth = 0) `Prefix` and `Close` both place
/// the `)` at column 0 because the command sits there — the two
/// variants are visually identical in this case:
///
/// ```cmake
/// # Prefix / Close at top level — `)` at column 0:
/// target_link_libraries(
///   mylib PUBLIC dep1
/// )
///
/// # Open — `)` at the opening-paren column:
/// target_link_libraries(
///   mylib PUBLIC dep1
///                      )
/// ```
///
/// Inside a nested block (`if/foreach/while/function/...`) the
/// variants diverge: `Prefix` tracks the command-name indent (one
/// tab stop per nesting level), while `Close` places the `)` at the
/// current indent level — one tab stop shallower than the command
/// name, i.e. flush with the enclosing block.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(schemars::JsonSchema))]
#[serde(rename_all = "lowercase")]
pub enum DangleAlign {
    /// Align with the start of the command name.
    #[default]
    Prefix,
    /// Align with the opening paren column.
    Open,
    /// No extra indent (flush with current indent level).
    Close,
}

/// Full formatter configuration.
///
/// Construct [`Config::default`] and set fields as needed before passing it to
/// [`format_source`](crate::format_source) or related functions.
///
/// ```
/// use cmakefmt::{Config, CaseStyle, DangleAlign};
///
/// let config = Config {
///     line_width: 100,
///     command_case: CaseStyle::Lower,
///     dangle_parens: true,
///     dangle_align: DangleAlign::Open,
///     ..Config::default()
/// };
/// ```
///
/// # Loading from disk
///
/// Programmatic callers typically don't build a [`Config`] from
/// scratch — they load a user config file:
///
/// - [`Config::for_file`] — auto-discover the nearest
///   `.cmakefmt.yaml|yml|toml` starting from a source file's parent
///   directory, walking up to the repository root and then the
///   user's home directory.
/// - [`Config::from_file`] — load a specific config file.
/// - [`Config::from_files`] — load and merge several in order (later
///   files override earlier ones).
/// - [`Config::from_yaml_str`] — deserialise from an in-memory YAML
///   string (used by the WASM playground and tests).
///
/// # Defaults
///
/// Headline defaults for the most commonly-adjusted knobs:
///
/// | Field | Default |
/// |-------|---------|
/// | `line_width` | `80` |
/// | `tab_size` | `2` |
/// | `use_tabchars` | `false` |
/// | `line_ending` | [`LineEnding::Unix`] |
/// | `max_empty_lines` | `1` |
/// | `max_lines_hwrap` | `2` |
/// | `max_pargs_hwrap` | `6` |
/// | `max_subgroups_hwrap` | `2` |
/// | `max_rows_cmdline` | `2` |
/// | `command_case` | [`CaseStyle::Lower`] |
/// | `keyword_case` | [`CaseStyle::Upper`] |
/// | `dangle_parens` | `false` |
/// | `dangle_align` | [`DangleAlign::Prefix`] |
/// | `enable_markup` | `true` |
/// | `first_comment_is_literal` | `true` |
/// | `canonicalize_hashrulers` | `true` |
/// | `hashruler_min_length` | `10` |
///
/// Fields not listed here default to `false`, empty, or their
/// variant-level defaults — see the per-field documentation below.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
    // ── Kill-switch ─────────────────────────────────────────────────────
    /// When `true`, skip all formatting and return the source unchanged.
    pub disable: bool,

    // ── Line endings ─────────────────────────────────────────────────────
    /// Output line-ending style.
    pub line_ending: LineEnding,

    // ── Layout ──────────────────────────────────────────────────────────
    /// Maximum rendered line width before wrapping is attempted.
    pub line_width: usize,
    /// Number of spaces that make up one indentation level when
    /// [`Self::use_tabchars`] is `false`.
    pub tab_size: usize,
    /// Emit tab characters for indentation instead of spaces.
    pub use_tabchars: bool,
    /// How to handle fractional indentation when [`Self::use_tabchars`] is
    /// `true`.
    pub fractional_tab_policy: FractionalTabPolicy,
    /// Maximum number of consecutive empty lines to preserve.
    pub max_empty_lines: usize,
    /// Maximum number of wrapped lines tolerated before switching to a more
    /// vertical layout.
    pub max_lines_hwrap: usize,
    /// Maximum number of positional arguments to keep in a hanging-wrap layout
    /// before going vertical.
    pub max_pargs_hwrap: usize,
    /// Maximum number of keyword/flag subgroups to keep in a horizontal wrap.
    pub max_subgroups_hwrap: usize,
    /// Maximum rows a hanging-wrap positional group may consume before the
    /// layout is rejected and nesting is forced.
    pub max_rows_cmdline: usize,
    /// Command names (lowercase) that must always use vertical layout,
    /// regardless of line width.
    pub always_wrap: Vec<String>,
    /// Return an error when any formatted output line exceeds
    /// [`Self::line_width`].
    pub require_valid_layout: bool,
    /// When wrapping, keep the first positional argument on the command
    /// line and align continuation to the open parenthesis. Can be
    /// overridden per-command via `per_command_overrides` or the spec's
    /// `layout.wrap_after_first_arg`.
    pub wrap_after_first_arg: bool,
    /// How to indent continuation lines when a wrapped keyword
    /// section overflows [`Self::line_width`]. Can be overridden
    /// per-command via `per_command_overrides` or the spec's
    /// `layout.continuation_align`.
    pub continuation_align: ContinuationAlign,
    /// Sort arguments in keyword sections marked `sortable` in the
    /// command spec. Sorting is lexicographic and case-insensitive.
    pub enable_sort: bool,
    /// Heuristically infer sortability for keyword sections without
    /// an explicit `sortable` annotation. When enabled, a section is
    /// considered sortable if all its arguments are simple unquoted
    /// tokens (no variables, generator expressions, or quoted strings).
    pub autosort: bool,

    // ── Parenthesis style ───────────────────────────────────────────────
    /// Place the closing `)` on its own line when a call wraps.
    pub dangle_parens: bool,
    /// Alignment strategy for a dangling closing `)`.
    pub dangle_align: DangleAlign,
    /// Lower bound used by layout heuristics when deciding whether a command
    /// name is short enough to prefer one style over another.
    pub min_prefix_chars: usize,
    /// Upper bound used by layout heuristics when deciding whether a command
    /// name is long enough to prefer one style over another.
    pub max_prefix_chars: usize,
    /// Insert a space before `(` for control-flow commands such as `if`.
    pub separate_ctrl_name_with_space: bool,
    /// Insert a space before `(` for `function`/`macro` definitions.
    pub separate_fn_name_with_space: bool,

    // ── Casing ──────────────────────────────────────────────────────────
    /// Output casing policy for command names.
    pub command_case: CaseStyle,
    /// Output casing policy for recognized keywords and flags.
    pub keyword_case: CaseStyle,

    // ── Comment markup ──────────────────────────────────────────────────
    /// Enable markup-aware comment handling and reflow plain line comments
    /// to fit within the configured line width.
    pub enable_markup: bool,
    /// Preserve the first comment block in a file literally.
    pub first_comment_is_literal: bool,
    /// Regex for comments that should never be reflowed.
    pub literal_comment_pattern: String,
    /// Preferred bullet character when normalizing list markup.
    pub bullet_char: String,
    /// Preferred enumeration punctuation when normalizing numbered list markup.
    pub enum_char: String,
    /// Regex describing fenced literal comment blocks.
    pub fence_pattern: String,
    /// Regex describing ruler-style comments.
    pub ruler_pattern: String,
    /// Minimum ruler length before a `#-----` style line is treated as a ruler.
    pub hashruler_min_length: usize,
    /// Normalize ruler comments when markup handling is enabled.
    pub canonicalize_hashrulers: bool,
    /// Regex pattern that marks an inline comment as explicitly trailing its
    /// preceding argument. Matching comments are rendered on the same line as
    /// the preceding token rather than on their own line.
    pub explicit_trailing_pattern: String,

    // ── Per-command overrides ────────────────────────────────────────────
    /// Per-command configuration overrides keyed by lowercase command name.
    pub per_command_overrides: HashMap<String, PerCommandConfig>,

    // ── Experimental ──────────────────────────────────────────────────
    /// Opt-in experimental formatting options. These are unstable and may
    /// change or be removed between releases. Enable all at once with
    /// `--preview` on the CLI.
    #[serde(default)]
    pub experimental: Experimental,
}

/// Experimental formatting options gated behind `--preview` or the
/// `[experimental]` config section. All options default to `false`.
///
/// These may be promoted to stable defaults in a future release, changed
/// incompatibly, or removed entirely.
///
/// This struct is re-exported at the crate root even when it
/// contains no options so consumers can write forward-compatible
/// initialisers:
///
/// ```
/// use cmakefmt::{Config, Experimental};
///
/// let config = Config {
///     experimental: Experimental::default(),
///     ..Config::default()
/// };
/// ```
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(schemars::JsonSchema))]
#[serde(default)]
#[non_exhaustive]
pub struct Experimental {
    // No experimental options yet. Add new options here as they are
    // developed. Each option should default to false.
}

/// Per-command overrides. All fields are optional — only specified fields
/// override the global config for that command.
///
/// # YAML/TOML key names
///
/// Two fields use different names in config files than in this Rust
/// struct (for historical reasons):
///
/// | Rust field | YAML/TOML key |
/// |------------|---------------|
/// | `max_pargs_hwrap` | `max_hanging_wrap_positional_args` |
/// | `max_subgroups_hwrap` | `max_hanging_wrap_groups` |
///
/// All other fields use the same name in both.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[cfg_attr(feature = "cli", derive(schemars::JsonSchema))]
#[serde(deny_unknown_fields)]
pub struct PerCommandConfig {
    /// Override the command casing rule for this command only.
    pub command_case: Option<CaseStyle>,
    /// Override the keyword casing rule for this command only.
    pub keyword_case: Option<CaseStyle>,
    /// Override the line width for this command only.
    pub line_width: Option<usize>,
    /// Override the indentation width for this command only.
    pub tab_size: Option<usize>,
    /// Override dangling paren placement for this command only.
    pub dangle_parens: Option<bool>,
    /// Override dangling paren alignment for this command only.
    pub dangle_align: Option<DangleAlign>,
    /// Override the hanging-wrap positional argument threshold for this
    /// command only.
    #[serde(rename = "max_hanging_wrap_positional_args")]
    pub max_pargs_hwrap: Option<usize>,
    /// Override the hanging-wrap subgroup threshold for this command only.
    #[serde(rename = "max_hanging_wrap_groups")]
    pub max_subgroups_hwrap: Option<usize>,
    /// Keep the first positional argument on the command line when wrapping.
    pub wrap_after_first_arg: Option<bool>,
    /// Override the continuation-alignment rule for this command.
    pub continuation_align: Option<ContinuationAlign>,
}

impl Default for Config {
    fn default() -> Self {
        Self {
            disable: false,
            line_ending: LineEnding::Unix,
            line_width: 80,
            tab_size: 2,
            use_tabchars: false,
            fractional_tab_policy: FractionalTabPolicy::UseSpace,
            max_empty_lines: 1,
            max_lines_hwrap: 2,
            max_pargs_hwrap: 6,
            max_subgroups_hwrap: 2,
            max_rows_cmdline: 2,
            always_wrap: Vec::new(),
            require_valid_layout: false,
            wrap_after_first_arg: false,
            continuation_align: ContinuationAlign::UnderFirstValue,
            enable_sort: false,
            autosort: false,
            dangle_parens: false,
            dangle_align: DangleAlign::Prefix,
            min_prefix_chars: 4,
            max_prefix_chars: 10,
            separate_ctrl_name_with_space: false,
            separate_fn_name_with_space: false,
            command_case: CaseStyle::Lower,
            keyword_case: CaseStyle::Upper,
            enable_markup: true,
            first_comment_is_literal: true,
            literal_comment_pattern: String::new(),
            bullet_char: "*".to_string(),
            enum_char: ".".to_string(),
            fence_pattern: DEFAULT_FENCE_PATTERN.to_string(),
            ruler_pattern: DEFAULT_RULER_PATTERN.to_string(),
            hashruler_min_length: 10,
            canonicalize_hashrulers: true,
            explicit_trailing_pattern: DEFAULT_EXPLICIT_TRAILING_PATTERN.to_string(),
            per_command_overrides: HashMap::new(),
            experimental: Experimental::default(),
        }
    }
}

/// CMake control-flow commands that get `separate_ctrl_name_with_space`.
const CONTROL_FLOW_COMMANDS: &[&str] = &[
    "if",
    "elseif",
    "else",
    "endif",
    "foreach",
    "endforeach",
    "while",
    "endwhile",
    "break",
    "continue",
    "return",
    "block",
    "endblock",
];

/// CMake function/macro definition commands that get
/// `separate_fn_name_with_space`.
const FN_DEFINITION_COMMANDS: &[&str] = &["function", "endfunction", "macro", "endmacro"];

impl Config {
    /// Returns a `Config` with any per-command overrides applied for the
    /// given command name, plus the appropriate space-before-paren setting.
    pub fn for_command(&self, command_name: &str) -> CommandConfig<'_> {
        let lower = command_name.to_ascii_lowercase();
        let per_cmd = self.per_command_overrides.get(&lower);

        let space_before_paren = if CONTROL_FLOW_COMMANDS.contains(&lower.as_str()) {
            self.separate_ctrl_name_with_space
        } else if FN_DEFINITION_COMMANDS.contains(&lower.as_str()) {
            self.separate_fn_name_with_space
        } else {
            false
        };

        CommandConfig {
            global: self,
            per_cmd,
            space_before_paren,
        }
    }

    /// Apply the command_case rule to a command name.
    pub fn apply_command_case(&self, name: &str) -> String {
        apply_case(self.command_case, name)
    }

    /// Apply the keyword_case rule to a keyword token.
    pub fn apply_keyword_case(&self, keyword: &str) -> String {
        apply_case(self.keyword_case, keyword)
    }

    /// The indentation string (spaces or tab).
    pub fn indent_str(&self) -> String {
        if self.use_tabchars {
            "\t".to_string()
        } else {
            " ".repeat(self.tab_size)
        }
    }

    /// Validate that all regex patterns in the config are valid.
    ///
    /// Returns `Ok(())` if all patterns compile, or an error message
    /// identifying the first invalid pattern.
    pub fn validate_patterns(&self) -> Result<(), String> {
        // Fast path for defaults — the built-in pattern strings are known
        // to be valid. Avoids compiling three regexes on every
        // format_source() call, which dominates per-file overhead on
        // whole-tree runs over many small files.
        if self.has_default_regex_patterns() {
            return Ok(());
        }
        let patterns = [
            ("literal_comment_pattern", &self.literal_comment_pattern),
            ("explicit_trailing_pattern", &self.explicit_trailing_pattern),
            ("fence_pattern", &self.fence_pattern),
            ("ruler_pattern", &self.ruler_pattern),
        ];
        for (name, pattern) in &patterns {
            if !pattern.is_empty() {
                if let Err(err) = Regex::new(pattern) {
                    return Err(format!("invalid regex in {name}: {err}"));
                }
            }
        }
        Ok(())
    }

    fn has_default_regex_patterns(&self) -> bool {
        self.literal_comment_pattern.is_empty()
            && self.explicit_trailing_pattern == DEFAULT_EXPLICIT_TRAILING_PATTERN
            && self.fence_pattern == DEFAULT_FENCE_PATTERN
            && self.ruler_pattern == DEFAULT_RULER_PATTERN
    }

    /// Compile all regex patterns into a cache for internal formatting use.
    ///
    /// Callers that build [`Config`] programmatically should use
    /// [`Config::validate_patterns`] to validate regexes up front.
    pub(crate) fn compiled_patterns(&self) -> Result<CompiledPatterns, String> {
        // Fast path for the common default configuration. Compiling the
        // default regex repeatedly is a measurable cost on whole-tree runs
        // that process many small files.
        if self.literal_comment_pattern.is_empty()
            && self.explicit_trailing_pattern == DEFAULT_EXPLICIT_TRAILING_PATTERN
        {
            return Ok(CompiledPatterns {
                literal_comment: None,
                explicit_trailing: Some(default_explicit_trailing_regex().clone()),
            });
        }
        Ok(CompiledPatterns {
            literal_comment: compile_optional(
                "literal_comment_pattern",
                &self.literal_comment_pattern,
            )?,
            explicit_trailing: compile_optional(
                "explicit_trailing_pattern",
                &self.explicit_trailing_pattern,
            )?,
        })
    }
}

const DEFAULT_EXPLICIT_TRAILING_PATTERN: &str = "#<";
const DEFAULT_FENCE_PATTERN: &str = r"^\s*[`~]{3}[^`\n]*$";
const DEFAULT_RULER_PATTERN: &str = r"^[^\w\s]{3}.*[^\w\s]{3}$";

fn default_explicit_trailing_regex() -> &'static Regex {
    static CACHE: std::sync::OnceLock<Regex> = std::sync::OnceLock::new();
    CACHE.get_or_init(|| Regex::new(DEFAULT_EXPLICIT_TRAILING_PATTERN).expect("default regex"))
}

fn compile_optional(name: &str, pattern: &str) -> Result<Option<Regex>, String> {
    if pattern.is_empty() {
        Ok(None)
    } else {
        Regex::new(pattern)
            .map(Some)
            .map_err(|err| format!("invalid regex in {name}: {err}"))
    }
}

/// Pre-compiled regex patterns from [`Config`] used internally while formatting.
pub(crate) struct CompiledPatterns {
    /// Compiled `literal_comment_pattern`.
    pub(crate) literal_comment: Option<Regex>,
    /// Compiled `explicit_trailing_pattern`. Currently unused by the
    /// formatter (trailing comments are kept inline by width), but
    /// retained for future use and config compatibility.
    #[allow(dead_code)]
    pub(crate) explicit_trailing: Option<Regex>,
}

/// A resolved config for formatting a specific command, with per-command
/// overrides already applied.
///
/// Each accessor resolves values in this priority order:
///
/// 1. Per-command user override from
///    [`Config::per_command_overrides`] (if set for this command).
/// 2. Command-spec `layout` overrides for the selected form (passed
///    in where applicable, e.g. [`CommandConfig::wrap_after_first_arg`]).
/// 3. Global [`Config`] default.
///
/// Construct via [`Config::for_command`].
#[derive(Debug)]
pub struct CommandConfig<'a> {
    /// The global configuration before per-command overrides are applied.
    global: &'a Config,
    per_cmd: Option<&'a PerCommandConfig>,
    /// Whether this command should render a space before `(`.
    space_before_paren: bool,
}

impl CommandConfig<'_> {
    /// Whether this command should render a space before `(`.
    pub fn space_before_paren(&self) -> bool {
        self.space_before_paren
    }

    pub(crate) fn global(&self) -> &Config {
        self.global
    }

    /// Effective line width for the current command.
    pub fn line_width(&self) -> usize {
        self.per_cmd
            .and_then(|p| p.line_width)
            .unwrap_or(self.global.line_width)
    }

    /// Effective indentation width for the current command.
    pub fn tab_size(&self) -> usize {
        self.per_cmd
            .and_then(|p| p.tab_size)
            .unwrap_or(self.global.tab_size)
    }

    /// Effective dangling-paren setting for the current command.
    pub fn dangle_parens(&self) -> bool {
        self.per_cmd
            .and_then(|p| p.dangle_parens)
            .unwrap_or(self.global.dangle_parens)
    }

    /// Effective dangling-paren alignment for the current command.
    pub fn dangle_align(&self) -> DangleAlign {
        self.per_cmd
            .and_then(|p| p.dangle_align)
            .unwrap_or(self.global.dangle_align)
    }

    /// Effective command casing rule for the current command.
    pub fn command_case(&self) -> CaseStyle {
        self.per_cmd
            .and_then(|p| p.command_case)
            .unwrap_or(self.global.command_case)
    }

    /// Effective keyword casing rule for the current command.
    pub fn keyword_case(&self) -> CaseStyle {
        self.per_cmd
            .and_then(|p| p.keyword_case)
            .unwrap_or(self.global.keyword_case)
    }

    /// Effective hanging-wrap positional argument threshold for the current
    /// command.
    pub fn max_pargs_hwrap(&self) -> usize {
        self.per_cmd
            .and_then(|p| p.max_pargs_hwrap)
            .unwrap_or(self.global.max_pargs_hwrap)
    }

    /// Effective hanging-wrap subgroup threshold for the current command.
    pub fn max_subgroups_hwrap(&self) -> usize {
        self.per_cmd
            .and_then(|p| p.max_subgroups_hwrap)
            .unwrap_or(self.global.max_subgroups_hwrap)
    }

    /// Effective `wrap_after_first_arg` for the current command.
    ///
    /// Resolution order: per-command user override > `spec_value` (from
    /// the command spec's layout overrides) > global config default.
    pub fn wrap_after_first_arg(&self, spec_value: Option<bool>) -> bool {
        self.per_cmd
            .and_then(|p| p.wrap_after_first_arg)
            .or(spec_value)
            .unwrap_or(self.global.wrap_after_first_arg)
    }

    /// Effective continuation-alignment rule for the current command.
    ///
    /// Resolution order: per-command user override > `spec_value`
    /// (from the command spec's layout overrides) > global config
    /// default.
    pub fn continuation_align(&self, spec_value: Option<ContinuationAlign>) -> ContinuationAlign {
        self.per_cmd
            .and_then(|p| p.continuation_align)
            .or(spec_value)
            .unwrap_or(self.global.continuation_align)
    }

    /// Effective indentation unit for the current command.
    pub fn indent_str(&self) -> String {
        if self.global.use_tabchars {
            "\t".to_string()
        } else {
            " ".repeat(self.tab_size())
        }
    }
}

fn apply_case(style: CaseStyle, s: &str) -> String {
    match style {
        CaseStyle::Lower => s.to_ascii_lowercase(),
        CaseStyle::Upper => s.to_ascii_uppercase(),
        CaseStyle::Unchanged => s.to_string(),
    }
}

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

    // ── Config::for_command ───────────────────────────────────────────────

    #[test]
    fn for_command_control_flow_sets_space_before_paren() {
        let config = Config {
            separate_ctrl_name_with_space: true,
            ..Config::default()
        };
        for cmd in ["if", "elseif", "foreach", "while", "return"] {
            let cc = config.for_command(cmd);
            assert!(
                cc.space_before_paren(),
                "{cmd} should have space_before_paren=true"
            );
        }
    }

    #[test]
    fn for_command_fn_definition_sets_space_before_paren() {
        let config = Config {
            separate_fn_name_with_space: true,
            ..Config::default()
        };
        for cmd in ["function", "endfunction", "macro", "endmacro"] {
            let cc = config.for_command(cmd);
            assert!(
                cc.space_before_paren(),
                "{cmd} should have space_before_paren=true"
            );
        }
    }

    #[test]
    fn for_command_regular_command_no_space_before_paren() {
        let config = Config {
            separate_ctrl_name_with_space: true,
            separate_fn_name_with_space: true,
            ..Config::default()
        };
        let cc = config.for_command("message");
        assert!(
            !cc.space_before_paren(),
            "message should not have space_before_paren"
        );
    }

    #[test]
    fn for_command_lookup_is_case_insensitive() {
        let mut overrides = HashMap::new();
        overrides.insert(
            "message".to_string(),
            PerCommandConfig {
                line_width: Some(120),
                ..Default::default()
            },
        );
        let config = Config {
            per_command_overrides: overrides,
            ..Config::default()
        };
        // uppercase lookup should still find the "message" override
        assert_eq!(config.for_command("MESSAGE").line_width(), 120);
    }

    // ── CommandConfig accessors ───────────────────────────────────────────

    #[test]
    fn command_config_returns_global_defaults_when_no_override() {
        let config = Config::default();
        let cc = config.for_command("set");
        assert_eq!(cc.line_width(), config.line_width);
        assert_eq!(cc.tab_size(), config.tab_size);
        assert_eq!(cc.dangle_parens(), config.dangle_parens);
        assert_eq!(cc.command_case(), config.command_case);
        assert_eq!(cc.keyword_case(), config.keyword_case);
        assert_eq!(cc.max_pargs_hwrap(), config.max_pargs_hwrap);
        assert_eq!(cc.max_subgroups_hwrap(), config.max_subgroups_hwrap);
    }

    #[test]
    fn command_config_per_command_overrides_take_effect() {
        let mut overrides = HashMap::new();
        overrides.insert(
            "set".to_string(),
            PerCommandConfig {
                line_width: Some(120),
                tab_size: Some(4),
                dangle_parens: Some(true),
                dangle_align: Some(DangleAlign::Open),
                command_case: Some(CaseStyle::Upper),
                keyword_case: Some(CaseStyle::Lower),
                max_pargs_hwrap: Some(10),
                max_subgroups_hwrap: Some(5),
                wrap_after_first_arg: None,
                continuation_align: None,
            },
        );
        let config = Config {
            per_command_overrides: overrides,
            ..Config::default()
        };
        let cc = config.for_command("set");
        assert_eq!(cc.line_width(), 120);
        assert_eq!(cc.tab_size(), 4);
        assert!(cc.dangle_parens());
        assert_eq!(cc.dangle_align(), DangleAlign::Open);
        assert_eq!(cc.command_case(), CaseStyle::Upper);
        assert_eq!(cc.keyword_case(), CaseStyle::Lower);
        assert_eq!(cc.max_pargs_hwrap(), 10);
        assert_eq!(cc.max_subgroups_hwrap(), 5);
    }

    #[test]
    fn indent_str_spaces() {
        let config = Config {
            tab_size: 4,
            use_tabchars: false,
            ..Config::default()
        };
        assert_eq!(config.indent_str(), "    ");
        assert_eq!(config.for_command("set").indent_str(), "    ");
    }

    #[test]
    fn indent_str_tab() {
        let config = Config {
            use_tabchars: true,
            ..Config::default()
        };
        assert_eq!(config.indent_str(), "\t");
        assert_eq!(config.for_command("set").indent_str(), "\t");
    }

    // ── Case helpers ─────────────────────────────────────────────────────

    #[test]
    fn apply_command_case_lower() {
        let config = Config {
            command_case: CaseStyle::Lower,
            ..Config::default()
        };
        assert_eq!(
            config.apply_command_case("TARGET_LINK_LIBRARIES"),
            "target_link_libraries"
        );
    }

    #[test]
    fn apply_command_case_upper() {
        let config = Config {
            command_case: CaseStyle::Upper,
            ..Config::default()
        };
        assert_eq!(
            config.apply_command_case("target_link_libraries"),
            "TARGET_LINK_LIBRARIES"
        );
    }

    #[test]
    fn apply_command_case_unchanged() {
        let config = Config {
            command_case: CaseStyle::Unchanged,
            ..Config::default()
        };
        assert_eq!(
            config.apply_command_case("Target_Link_Libraries"),
            "Target_Link_Libraries"
        );
    }

    #[test]
    fn apply_keyword_case_variants() {
        let config_upper = Config {
            keyword_case: CaseStyle::Upper,
            ..Config::default()
        };
        assert_eq!(config_upper.apply_keyword_case("public"), "PUBLIC");

        let config_lower = Config {
            keyword_case: CaseStyle::Lower,
            ..Config::default()
        };
        assert_eq!(config_lower.apply_keyword_case("PUBLIC"), "public");
    }

    // ── Error Display ─────────────────────────────────────────────────────

    #[test]
    fn error_layout_too_wide_display() {
        use crate::error::Error;
        let err = Error::LayoutTooWide {
            line_no: 5,
            width: 95,
            limit: 80,
        };
        let msg = err.to_string();
        assert!(msg.contains("5"), "should mention line number");
        assert!(msg.contains("95"), "should mention actual width");
        assert!(msg.contains("80"), "should mention limit");
    }

    #[test]
    fn error_formatter_display() {
        use crate::error::Error;
        let err = Error::Formatter("something went wrong".to_string());
        assert!(err.to_string().contains("something went wrong"));
    }

    // ── Regex fast paths ──────────────────────────────────────────────────

    #[test]
    fn from_files_empty_path_returns_defaults() {
        let config = Config::from_files(&[]).expect("default config should load");
        let defaults = Config::default();
        assert_eq!(
            config.literal_comment_pattern,
            defaults.literal_comment_pattern
        );
        assert_eq!(
            config.explicit_trailing_pattern,
            defaults.explicit_trailing_pattern
        );
        assert_eq!(config.fence_pattern, defaults.fence_pattern);
        assert_eq!(config.ruler_pattern, defaults.ruler_pattern);
        assert_eq!(config.line_width, defaults.line_width);
    }

    #[test]
    fn validate_patterns_accepts_defaults() {
        let config = Config::default();
        assert!(
            config.validate_patterns().is_ok(),
            "default patterns must pass validation"
        );
    }

    #[test]
    fn validate_patterns_rejects_invalid_custom_pattern() {
        let config = Config {
            fence_pattern: "(".to_string(),
            ..Config::default()
        };
        let err = config
            .validate_patterns()
            .expect_err("invalid fence_pattern must be rejected");
        assert!(
            err.contains("fence_pattern"),
            "error should identify fence_pattern, got: {err}"
        );
    }

    #[test]
    fn validate_patterns_accepts_valid_custom_pattern() {
        let config = Config {
            fence_pattern: r"^\s*[#]{3,}$".to_string(),
            ..Config::default()
        };
        assert!(config.validate_patterns().is_ok());
    }

    #[test]
    fn compiled_patterns_uses_cached_default_regex() {
        let config = Config::default();
        let compiled = config.compiled_patterns().expect("defaults must compile");
        assert!(
            compiled.literal_comment.is_none(),
            "empty literal_comment_pattern should produce None"
        );
        let explicit = compiled
            .explicit_trailing
            .expect("default explicit_trailing_pattern should compile to Some");
        assert!(
            explicit.is_match("#<"),
            "default explicit_trailing regex should match the default marker"
        );
    }

    #[test]
    fn compiled_patterns_compiles_custom_literal_comment() {
        let config = Config {
            literal_comment_pattern: r"^\s*TODO:".to_string(),
            ..Config::default()
        };
        let compiled = config
            .compiled_patterns()
            .expect("custom literal_comment_pattern must compile");
        let literal = compiled
            .literal_comment
            .expect("custom literal_comment_pattern should compile to Some");
        assert!(literal.is_match("  TODO: fix me"));
        assert!(!literal.is_match("# regular comment"));
    }

    #[test]
    fn compiled_patterns_compiles_custom_explicit_trailing() {
        let config = Config {
            explicit_trailing_pattern: r"^#>".to_string(),
            ..Config::default()
        };
        let compiled = config
            .compiled_patterns()
            .expect("custom explicit_trailing_pattern must compile");
        let explicit = compiled
            .explicit_trailing
            .expect("custom explicit_trailing_pattern should compile to Some");
        assert!(explicit.is_match("#>"));
        assert!(
            !explicit.is_match("x#<"),
            "custom pattern must not fall back to the cached default"
        );
    }

    #[test]
    fn compiled_patterns_errors_on_invalid_custom() {
        let config = Config {
            literal_comment_pattern: "(".to_string(),
            ..Config::default()
        };
        match config.compiled_patterns() {
            Ok(_) => panic!("invalid custom pattern must error"),
            Err(err) => assert!(
                err.contains("literal_comment_pattern"),
                "error should identify literal_comment_pattern, got: {err}"
            ),
        }
    }
}