rustledger_loader/

options.rs

//! Beancount options parsing and storage.

use rust_decimal::Decimal;
use rustc_hash::{FxHashMap, FxHashSet};
use std::str::FromStr;

/// Known beancount option names.
const KNOWN_OPTIONS: &[&str] = &[
    "title",
    "filename",
    "operating_currency",
    "name_assets",
    "name_liabilities",
    "name_equity",
    "name_income",
    "name_expenses",
    "account_rounding",
    "account_previous_balances",
    "account_previous_earnings",
    "account_previous_conversions",
    "account_current_earnings",
    "account_current_conversions",
    "account_unrealized_gains",
    "conversion_currency",
    "inferred_tolerance_default",
    "inferred_tolerance_multiplier",
    "infer_tolerance_from_cost",
    "use_legacy_fixed_tolerances",
    "experiment_explicit_tolerances",
    "use_precise_interpolation",
    "booking_method",
    "render_commas",
    "display_precision",
    "allow_pipe_separator",
    "long_string_maxlines",
    "documents",
    "insert_pythonpath",
    "plugin_processing_mode",
    "plugin",               // Deprecated, but still known
    "tolerance_multiplier", // Renamed from inferred_tolerance_multiplier
];

/// The E7004 message for a deprecated option, if it is one.
///
/// One table rather than three inline strings: the include-scope check has to
/// report deprecation as well, and a second copy of these messages would drift
/// from the arms that raise them.
fn deprecation_message(key: &str) -> Option<&'static str> {
    match key {
        "inferred_tolerance_multiplier" => Some("Renamed to 'tolerance_multiplier'."),
        "allow_pipe_separator" => Some("Option 'allow_pipe_separator' is deprecated"),
        "plugin" => Some("Option 'plugin' is deprecated; use the 'plugin' directive instead"),
        _ => None,
    }
}

/// Options that survive an `include` boundary.
///
/// Everything else is taken from the TOP-LEVEL file only. The split is by what
/// an option governs, not by one blanket rule (#2151):
///
/// * These describe the file that declares them. A sub-ledger naming its own
///   operating currency or document root is describing itself, not overriding
///   its includer, so they accumulate.
/// * Everything else defines global computation or the ledger's identity.
///   `booking_method` decides which lot a sale consumes and
///   `inferred_tolerance_default` decides what counts as balanced, so letting
///   an included file set them means a sub-ledger silently changes results for
///   every other entity in the tree — including the master's own transactions.
///
/// Note this is NOT the same list as [`REPEATABLE_OPTIONS`]. Repeating within
/// one file and carrying across an include are different properties:
/// `inferred_tolerance_default` accumulates within a file and must still not
/// cross an include, which is exactly the combination that let an unbalanced
/// transaction pass.
///
/// Plugins are absent for a reason that needs the two spellings kept apart.
/// The `plugin "name"` DIRECTIVE never reaches this function: it is collected
/// separately and already accumulates from any file, which is deliberate.
/// bean-query discards plugins declared in included files, leaving the user
/// with errors about accounts a plugin they did declare would have opened.
///
/// The deprecated `option "plugin"` form is a different thing and IS a known
/// option, so it does route through here and is scoped out like the rest.
/// That is why the include-scope branch re-raises E7004: the option was
/// already an error before this list existed, and being ignored must not
/// quietly downgrade it.
const ACCUMULATE_ACROSS_INCLUDES: &[&str] = &[
    "operating_currency",
    "documents",
    "insert_pythonpath",
    "display_precision",
];

/// Options that can be specified multiple times.
const REPEATABLE_OPTIONS: &[&str] = &[
    "operating_currency",
    "insert_pythonpath",
    "documents",
    "inferred_tolerance_default",
    "display_precision",
];

/// Options that are read-only and cannot be set by users.
const READONLY_OPTIONS: &[&str] = &["filename"];

/// Option validation warning.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OptionWarning {
    /// Warning code (E7001 through E7008).
    pub code: &'static str,
    /// Warning message.
    pub message: String,
    /// Option name.
    pub option: String,
    /// Option value.
    pub value: String,
}

/// Beancount file options.
///
/// These correspond to the `option` directives in beancount files.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Options {
    /// Title for the ledger.
    pub title: Option<String>,

    /// Source filename (auto-set).
    pub filename: Option<String>,

    /// Operating currencies (for reporting).
    pub operating_currency: Vec<String>,

    /// Name prefix for Assets accounts.
    pub name_assets: String,

    /// Name prefix for Liabilities accounts.
    pub name_liabilities: String,

    /// Name prefix for Equity accounts.
    pub name_equity: String,

    /// Name prefix for Income accounts.
    pub name_income: String,

    /// Name prefix for Expenses accounts.
    pub name_expenses: String,

    /// Account for rounding errors.
    pub account_rounding: Option<String>,

    /// Account for previous balances (opening balances).
    pub account_previous_balances: String,

    /// Account for previous earnings.
    pub account_previous_earnings: String,

    /// Account for previous conversions.
    pub account_previous_conversions: String,

    /// Account for current earnings.
    pub account_current_earnings: String,

    /// Account for current conversion differences.
    pub account_current_conversions: Option<String>,

    /// Account for unrealized gains.
    pub account_unrealized_gains: Option<String>,

    /// Currency for conversion (if specified).
    pub conversion_currency: Option<String>,

    /// Default tolerances per currency (e.g., "USD:0.005" or "*:0.001").
    pub inferred_tolerance_default: FxHashMap<String, Decimal>,

    /// Tolerance multiplier for balance assertions.
    pub inferred_tolerance_multiplier: Decimal,

    /// Whether to infer tolerance from cost.
    pub infer_tolerance_from_cost: bool,

    /// Whether to use legacy fixed tolerances.
    pub use_legacy_fixed_tolerances: bool,

    /// Enable experimental explicit tolerances in balance assertions.
    pub experiment_explicit_tolerances: bool,

    /// Beancount 3.x `use_precise_interpolation` flag, parsed for compatibility.
    /// rustledger always interpolates with exact `rust_decimal` arithmetic, so
    /// this is effectively always-on; the field records the user's declared
    /// value but does not change booking results (issue #1416).
    pub use_precise_interpolation: bool,

    /// Default booking method.
    pub booking_method: String,

    /// Whether to render commas in numbers.
    pub render_commas: bool,

    /// Display precision per currency (e.g., "USD:2" means format USD with 2 decimal places).
    /// Format: CURRENCY:PRECISION where PRECISION is the number of decimal places.
    pub display_precision: FxHashMap<String, u32>,

    /// Whether to allow pipe separator in numbers.
    pub allow_pipe_separator: bool,

    /// Maximum lines in multi-line strings.
    pub long_string_maxlines: u32,

    /// Directories to scan for document files.
    pub documents: Vec<String>,

    /// Plugin processing mode: "default" or "raw".
    pub plugin_processing_mode: String,

    /// Any other custom options.
    pub custom: FxHashMap<String, String>,

    /// Options that have been set (for duplicate detection).
    #[doc(hidden)]
    pub set_options: FxHashSet<String>,

    /// Validation warnings collected during parsing.
    pub warnings: Vec<OptionWarning>,
}

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

impl Options {
    /// Create new options with defaults.
    #[must_use]
    pub fn new() -> Self {
        Self {
            title: None,
            filename: None,
            operating_currency: Vec::new(),
            name_assets: "Assets".to_string(),
            name_liabilities: "Liabilities".to_string(),
            name_equity: "Equity".to_string(),
            name_income: "Income".to_string(),
            name_expenses: "Expenses".to_string(),
            account_rounding: None,
            account_previous_balances: "Equity:Opening-Balances".to_string(),
            account_previous_earnings: "Equity:Earnings:Previous".to_string(),
            account_previous_conversions: "Equity:Conversions:Previous".to_string(),
            account_current_earnings: "Equity:Earnings:Current".to_string(),
            account_current_conversions: None,
            account_unrealized_gains: None,
            conversion_currency: None,
            inferred_tolerance_default: FxHashMap::default(),
            inferred_tolerance_multiplier: Decimal::new(5, 1), // 0.5
            infer_tolerance_from_cost: false,
            use_legacy_fixed_tolerances: false,
            experiment_explicit_tolerances: false,
            use_precise_interpolation: false,
            booking_method: "STRICT".to_string(),
            render_commas: false, // Python beancount default is FALSE
            display_precision: FxHashMap::default(),
            allow_pipe_separator: false,
            long_string_maxlines: 64,
            documents: Vec::new(),
            plugin_processing_mode: "default".to_string(),
            custom: FxHashMap::default(),
            set_options: FxHashSet::default(),
            warnings: Vec::new(),
        }
    }

    /// Set an option by name.
    ///
    /// Validates the option and collects any warnings in `self.warnings`.
    pub fn set(&mut self, key: &str, value: &str) {
        self.set_scoped(key, value, true);
    }

    /// Raise E7004 if `key` is deprecated.
    ///
    /// The three arms that handle deprecated options and the include-scope
    /// branch all need this, and all four previously spelled it out. Reaching
    /// for `deprecation_message(key).unwrap_or_default()` in the arms was the
    /// worst of those: an entry dropped from the table would have produced an
    /// E7004 with an EMPTY message rather than any visible failure.
    fn warn_if_deprecated(&mut self, key: &str, value: &str) {
        let Some(message) = deprecation_message(key) else {
            return;
        };
        self.warnings.push(OptionWarning {
            code: "E7004",
            message: message.to_string(),
            option: key.to_string(),
            value: value.to_string(),
        });
    }

    /// Apply an option, knowing whether it came from the top-level file.
    ///
    /// See the `ACCUMULATE_ACROSS_INCLUDES` list. An option outside it, seen in
    /// an INCLUDED file, is reported and dropped rather than applied: the
    /// top-level file's value governs, so an included sub-ledger cannot change
    /// how the whole tree books or balances.
    pub fn set_scoped(&mut self, key: &str, value: &str, top_level: bool) {
        if !top_level && KNOWN_OPTIONS.contains(&key) && !ACCUMULATE_ACROSS_INCLUDES.contains(&key)
        {
            // A deprecated option is still deprecated when it is also ignored,
            // and E7004 is an error where the notice below is a warning. Raise
            // it first so scoping cannot quietly downgrade the severity of a
            // diagnostic that existed before this check did.
            self.warn_if_deprecated(key, value);
            // Its own code, not E7003. That one means "specified twice, last
            // wins" and is mapped downstream to `ErrorCode::DuplicateOption`;
            // this option may be the only one of its name in the tree.
            self.warnings.push(OptionWarning {
                code: "E7009",
                message: format!(
                    "Option \"{key}\" set in an included file is ignored; \
                     the top-level ledger's value governs"
                ),
                option: key.to_string(),
                value: value.to_string(),
            });
            return;
        }
        self.set_inner(key, value);
    }

    fn set_inner(&mut self, key: &str, value: &str) {
        // Check for unknown options (E7001)
        let is_known = KNOWN_OPTIONS.contains(&key);
        if !is_known {
            self.warnings.push(OptionWarning {
                code: "E7001",
                message: format!("Invalid option \"{key}\""),
                option: key.to_string(),
                value: value.to_string(),
            });
        }

        // Check for read-only options (E7005)
        if READONLY_OPTIONS.contains(&key) {
            self.warnings.push(OptionWarning {
                code: "E7005",
                message: format!("Option '{key}' may not be set"),
                option: key.to_string(),
                value: value.to_string(),
            });
            return; // Don't apply the value
        }

        // Check for duplicate non-repeatable options (E7003).
        //
        // Emitted as a WARNING (not an error), matching `bean-check`, which
        // silently lets the last value win (exit 0). A master ledger that
        // `include`s self-contained sub-ledgers — each setting its own
        // `option "title"` / `booking_method` / ... for standalone use — is a
        // legitimate layout (issue #1546). The value below is applied last-wins
        // to match. `cmd::check` and `validate` both surface this as a warning.
        let is_repeatable = REPEATABLE_OPTIONS.contains(&key);
        if is_known && !is_repeatable && self.set_options.contains(key) {
            self.warnings.push(OptionWarning {
                code: "E7003",
                message: format!("Option \"{key}\" is set more than once; the last value wins"),
                option: key.to_string(),
                value: value.to_string(),
            });
        }

        // Track that this option was set
        self.set_options.insert(key.to_string());

        // Apply the option value
        match key {
            "title" => self.title = Some(value.to_string()),
            "operating_currency" => self.operating_currency.push(value.to_string()),
            "name_assets" => {
                self.warn_if_invalid_root("name_assets", value);
                self.name_assets = value.to_string();
            }
            "name_liabilities" => {
                self.warn_if_invalid_root("name_liabilities", value);
                self.name_liabilities = value.to_string();
            }
            "name_equity" => {
                self.warn_if_invalid_root("name_equity", value);
                self.name_equity = value.to_string();
            }
            "name_income" => {
                self.warn_if_invalid_root("name_income", value);
                self.name_income = value.to_string();
            }
            "name_expenses" => {
                self.warn_if_invalid_root("name_expenses", value);
                self.name_expenses = value.to_string();
            }
            "account_rounding" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                // Accepted for Beancount compatibility but intentionally a no-op.
                // Beancount uses `account_rounding` to absorb the residual created
                // when an interpolated leg is *rounded* and the rounding breaks the
                // sum. rustledger never produces such a residual: `round_interpolated`
                // (rustledger-booking) preserves full precision instead of rounding a
                // non-zero residual to zero, so there is nothing for a rounding
                // account to catch. Warn so the option isn't silently swallowed.
                self.warnings.push(OptionWarning {
                    code: "E7007",
                    message: "Option 'account_rounding' is accepted for compatibility \
                              but has no effect: rustledger preserves full precision \
                              during interpolation rather than rounding into a rounding \
                              account, so no rounding residual is produced."
                        .to_string(),
                    option: key.to_string(),
                    value: value.to_string(),
                });
                self.account_rounding = Some(value.to_string());
            }
            "account_current_conversions" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_current_conversions = Some(value.to_string());
            }
            "account_unrealized_gains" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_unrealized_gains = Some(value.to_string());
            }
            "inferred_tolerance_multiplier" => {
                // Deprecated: renamed to tolerance_multiplier in Python beancount
                self.warn_if_deprecated(key, value);
                if let Ok(d) = Decimal::from_str(value) {
                    self.inferred_tolerance_multiplier = d;
                } else {
                    // E7002: Invalid option value
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{value}\" for option \"{key}\": expected decimal number"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
            }
            "tolerance_multiplier" => {
                if let Ok(d) = Decimal::from_str(value) {
                    self.inferred_tolerance_multiplier = d;
                } else {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{value}\" for option \"{key}\": expected decimal number"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
            }
            "infer_tolerance_from_cost" => {
                // Same vocabulary as every other boolean in ledger source
                // (`parse_bool_word`). This arm used to take TRUE/FALSE only
                // and warn on `1`, which Python beancount accepts as true for
                // every boolean option.
                let parsed = rustledger_core::parse_bool_word(value);
                if parsed.is_none() {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{value}\" for option \"{key}\": expected TRUE, FALSE, 1 or 0"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.infer_tolerance_from_cost = parsed == Some(true);
            }
            "booking_method" => {
                let valid_methods = [
                    "STRICT",
                    "STRICT_WITH_SIZE",
                    "FIFO",
                    "LIFO",
                    "HIFO",
                    "AVERAGE",
                    "NONE",
                ];
                if !valid_methods.contains(&value.to_uppercase().as_str()) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{}\" for option \"{}\": expected one of {}",
                            value,
                            key,
                            valid_methods.join(", ")
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.booking_method = value.to_string();
            }
            "render_commas" => {
                // Accept TRUE/FALSE, true/false, 1/0 (Python beancount
                // compatibility). Shared with `render_commas:` metadata so one
                // concept has one vocabulary — see `parse_bool_word`.
                let parsed = rustledger_core::parse_bool_word(value);
                let is_true = parsed == Some(true);
                if parsed.is_none() {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{value}\" for option \"{key}\": expected TRUE, FALSE, 1 or 0"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.render_commas = is_true;
            }
            "display_precision" => {
                // Parse "CURRENCY:EXAMPLE" where EXAMPLE's decimal places define the precision.
                // E.g., "CHF:0.01" means 2 decimal places for CHF.
                // E.g., "USD:0.001" means 3 decimal places for USD.
                if let Some((curr, example)) = value.split_once(':') {
                    if let Ok(d) = Decimal::from_str(example) {
                        // Get the precision from the example number's decimal places
                        let precision = d.scale();
                        self.display_precision.insert(curr.to_string(), precision);
                    } else {
                        self.warnings.push(OptionWarning {
                            code: "E7002",
                            message: format!(
                                "Invalid precision value \"{example}\" in option \"{key}\""
                            ),
                            option: key.to_string(),
                            value: value.to_string(),
                        });
                    }
                } else {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid format for option \"{key}\": expected CURRENCY:EXAMPLE (e.g., CHF:0.01)"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
            }
            "filename" => self.filename = Some(value.to_string()),
            "account_previous_balances" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_previous_balances = value.to_string();
            }
            "account_previous_earnings" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_previous_earnings = value.to_string();
            }
            "account_previous_conversions" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_previous_conversions = value.to_string();
            }
            "account_current_earnings" => {
                if !Self::is_valid_account(value) {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid leaf account name: '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.account_current_earnings = value.to_string();
            }
            "conversion_currency" => self.conversion_currency = Some(value.to_string()),
            "inferred_tolerance_default" => {
                // Parse "CURRENCY:TOLERANCE" or "*:TOLERANCE"
                if let Some((curr, tol)) = value.split_once(':') {
                    if let Ok(d) = Decimal::from_str(tol) {
                        self.inferred_tolerance_default.insert(curr.to_string(), d);
                    } else {
                        self.warnings.push(OptionWarning {
                            code: "E7002",
                            message: format!(
                                "Invalid tolerance value \"{tol}\" in option \"{key}\""
                            ),
                            option: key.to_string(),
                            value: value.to_string(),
                        });
                    }
                } else {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid format for option \"{key}\": expected CURRENCY:TOLERANCE"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
            }
            "use_legacy_fixed_tolerances" => {
                self.use_legacy_fixed_tolerances = value.eq_ignore_ascii_case("true");
            }
            "experiment_explicit_tolerances" => {
                self.experiment_explicit_tolerances = value.eq_ignore_ascii_case("true");
            }
            "use_precise_interpolation" => {
                // Accepted for beancount 3.x compatibility. rustledger already
                // interpolates with exact decimals, so this is a no-op on
                // results — recorded only to reflect the user's declaration.
                self.use_precise_interpolation = value.eq_ignore_ascii_case("true");
            }
            "allow_pipe_separator" => {
                // This option is deprecated in Python beancount
                self.warn_if_deprecated(key, value);
                self.allow_pipe_separator = value.eq_ignore_ascii_case("true");
            }
            "long_string_maxlines" => {
                if let Ok(n) = value.parse::<u32>() {
                    self.long_string_maxlines = n;
                } else {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!(
                            "Invalid value \"{value}\" for option \"{key}\": expected integer"
                        ),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
            }
            "documents" => {
                // NO existence check here. A relative `documents` path is
                // relative to the LEDGER FILE, as it is in beancount and as
                // `include` is — and option parsing does not know where that
                // file is. `Path::new(value).exists()` therefore asked about
                // the process CWD, so `rledger check path/to/ledger` reported
                // E7006 for a document root that was present (#1999), while
                // `query` — which resolves through `resolve_document_dirs` —
                // found it.
                //
                // The check now happens where the source map exists, in
                // `Loader::load`, through that same canonical resolver.
                self.documents.push(value.to_string());
            }
            "plugin_processing_mode" => {
                // Valid values are "default" and "raw" (case-sensitive, like Python)
                if value != "default" && value != "raw" {
                    self.warnings.push(OptionWarning {
                        code: "E7002",
                        message: format!("Invalid value '{value}'"),
                        option: key.to_string(),
                        value: value.to_string(),
                    });
                }
                self.plugin_processing_mode = value.to_string();
            }
            "plugin" => {
                // Deprecated: should use `plugin` directive instead of `option "plugin"`
                self.warn_if_deprecated(key, value);
            }
            _ => {
                // Unknown options go to custom map
                self.custom.insert(key.to_string(), value.to_string());
            }
        }
    }

    /// Get a custom option value.
    #[must_use]
    pub fn get(&self, key: &str) -> Option<&str> {
        self.custom.get(key).map(String::as_str)
    }

    /// Config-aware [`rustledger_core::AccountTypes`] classifier honoring the
    /// `name_*` renames. Consumers that route or sign accounts by root type
    /// must use this, not the rename-blind `ACCOUNT_TYPES` defaults.
    #[must_use]
    pub fn to_account_types(&self) -> rustledger_core::AccountTypes {
        rustledger_core::AccountTypes {
            assets: self.name_assets.clone(),
            liabilities: self.name_liabilities.clone(),
            equity: self.name_equity.clone(),
            income: self.name_income.clone(),
            expenses: self.name_expenses.clone(),
        }
    }

    /// Get all account type prefixes.
    #[must_use]
    pub fn account_types(&self) -> [&str; 5] {
        [
            &self.name_assets,
            &self.name_liabilities,
            &self.name_equity,
            &self.name_income,
            &self.name_expenses,
        ]
    }

    /// Warn (E7008) when a `name_*` account-type rename is not a lexable
    /// account root: every account under such a root is unparsable (both
    /// rledger and Python beancount fail at parse time with "unexpected
    /// NUMBER"-style errors), so the rename can only produce a broken
    /// ledger. Accepted anyway for option-handling parity — the warning
    /// makes the failure mode visible at the option site instead of at
    /// every account mention. The `account_*` options get the analogous
    /// E7002 guard; `name_*` used to be the unguarded exception.
    fn warn_if_invalid_root(&mut self, key: &str, value: &str) {
        if !Self::is_valid_account_root(value) {
            self.warnings.push(OptionWarning {
                code: "E7008",
                message: format!(
                    "Invalid account type name: '{value}' cannot begin an \
                     account name (accounts under it will never parse)"
                ),
                option: key.to_string(),
                value: value.to_string(),
            });
        }
    }

    /// Check if a value looks like a valid account name.
    ///
    /// Delegates to the canonical [`rustledger_parser::is_valid_account_name`]
    /// (the lexer itself), so option values are held to exactly the rule the
    /// parser applies to account tokens. The old hand-written check here was a
    /// third, divergent variant (it accepted lowercase-adjacent first chars the
    /// lexer rejects and had no per-character rule at all).
    fn is_valid_account(value: &str) -> bool {
        rustledger_parser::is_valid_account_name(value)
    }

    /// Check if a value is usable as an account TYPE root (a `name_*` option
    /// value): a single component (no `:`) such that accounts under it are
    /// lexable. Checked by running the canonical account predicate on
    /// `value:X` — a root is valid exactly when it can head a real account.
    fn is_valid_account_root(value: &str) -> bool {
        !value.contains(':') && rustledger_parser::is_valid_account_name(&format!("{value}:X"))
    }
}

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

    #[test]
    fn test_default_options() {
        let opts = Options::new();
        assert_eq!(opts.name_assets, "Assets");
        assert_eq!(opts.booking_method, "STRICT");
        assert!(!opts.infer_tolerance_from_cost);
    }

    #[test]
    fn test_set_options() {
        let mut opts = Options::new();
        opts.set("title", "My Ledger");
        opts.set("operating_currency", "USD");
        opts.set("operating_currency", "EUR");
        opts.set("booking_method", "FIFO");

        assert_eq!(opts.title, Some("My Ledger".to_string()));
        assert_eq!(opts.operating_currency, vec!["USD", "EUR"]);
        assert_eq!(opts.booking_method, "FIFO");
    }

    #[test]
    fn test_custom_options() {
        let mut opts = Options::new();
        opts.set("my_custom_option", "my_value");

        assert_eq!(opts.get("my_custom_option"), Some("my_value"));
        assert_eq!(opts.get("nonexistent"), None);
    }

    #[test]
    fn test_unknown_option_warning() {
        let mut opts = Options::new();
        opts.set("unknown_option", "value");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7001");
        assert!(opts.warnings[0].message.contains("Invalid option"));
    }

    /// #1416: the beancount 3.x `use_precise_interpolation` option must be
    /// accepted (no E7001) — rustledger already interpolates precisely.
    #[test]
    fn test_use_precise_interpolation_accepted() {
        let mut opts = Options::new();
        opts.set("use_precise_interpolation", "TRUE");

        assert!(
            opts.warnings.is_empty(),
            "should not warn on a known option: {:?}",
            opts.warnings
        );
        assert!(opts.use_precise_interpolation);
    }

    #[test]
    fn test_duplicate_option_warning() {
        let mut opts = Options::new();
        opts.set("title", "First Title");
        opts.set("title", "Second Title");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7003");
        // Wording matters here: the old text said the option "can only be
        // specified once", which is not true -- bean-check accepts a
        // redefinition and takes the last value, which is why #1546 asked for
        // this to stop being an error. Saying so is the difference between a
        // warning a reader can act on and one that looks like a rule.
        assert!(
            opts.warnings[0].message.contains("the last value wins"),
            "got: {}",
            opts.warnings[0].message,
        );
        // ...and last-wins is what actually happened.
        assert_eq!(opts.title.as_deref(), Some("Second Title"));
    }

    /// An option set in an INCLUDED file does not govern the ledger.
    ///
    /// The value-changing cases are the point. `booking_method` decides which
    /// lot a sale consumes and `inferred_tolerance_default` decides what
    /// counts as balanced, so a sub-ledger setting either used to change
    /// results for every other entity in the tree, including the master's own
    /// transactions (#2151).
    #[test]
    fn included_files_do_not_govern_scoped_options() {
        let mut opts = Options::new();
        opts.set_scoped("title", "Master", true);
        opts.set_scoped("booking_method", "LIFO", false);
        opts.set_scoped("title", "Sub-ledger", false);

        assert_eq!(
            opts.title.as_deref(),
            Some("Master"),
            "the top-level ledger names the combined result, not whichever \
             sub-ledger was included last",
        );
        assert!(
            !opts.set_options.contains("booking_method"),
            "an included booking_method must not reach the booker",
        );
        assert_eq!(opts.warnings.len(), 2, "each ignored option is reported");
        assert!(
            opts.warnings.iter().all(|w| w.code == "E7009"),
            "must not reuse E7003: that one means specified-twice-last-wins and \
             maps downstream to DuplicateOption, but an ignored option may be \
             the only one of its name in the tree",
        );
        assert!(
            opts.warnings
                .iter()
                .all(|w| w.message.contains("is ignored")),
            "the warning has to say the value was dropped, or the user cannot \
             tell why their setting had no effect",
        );
    }

    /// Scoping must not downgrade a diagnostic that already existed.
    ///
    /// `option "plugin"` is deprecated and raises E7004, which `rledger check`
    /// treats as an error. Reporting only the E7009 notice would silently turn
    /// that into a warning, making an included file the one place a deprecated
    /// option stopped failing the build.
    #[test]
    fn scoping_out_an_option_still_reports_its_deprecation() {
        let mut opts = Options::new();
        opts.set_scoped("plugin", "some.module", false);

        let codes: Vec<&str> = opts.warnings.iter().map(|w| w.code).collect();
        assert!(
            codes.contains(&"E7004"),
            "deprecation survives scoping: {codes:?}"
        );
        assert!(
            codes.contains(&"E7009"),
            "and the ignore is still reported: {codes:?}"
        );
        assert!(
            opts.warnings
                .iter()
                .any(|w| w.code == "E7004" && w.message.contains("deprecated")),
            "the message must come from the shared table, not an empty default",
        );
    }

    /// Options that describe the file declaring them still accumulate.
    ///
    /// A sub-ledger naming its own operating currency or document root is
    /// describing itself rather than overriding its includer, so scoping must
    /// not swallow these.
    #[test]
    fn included_files_still_contribute_accumulating_options() {
        let mut opts = Options::new();
        opts.set_scoped("operating_currency", "USD", true);
        opts.set_scoped("operating_currency", "EUR", false);
        opts.set_scoped("documents", "docs-from-include", false);

        assert!(
            opts.operating_currency.iter().any(|c| c == "EUR"),
            "an included operating_currency must still be collected",
        );
        assert!(
            opts.documents.iter().any(|d| d == "docs-from-include"),
            "an included documents root must still be collected",
        );
    }

    #[test]
    fn test_repeatable_option_no_warning() {
        let mut opts = Options::new();
        opts.set("operating_currency", "USD");
        opts.set("operating_currency", "EUR");

        // No warnings for repeatable options
        assert!(
            opts.warnings.is_empty(),
            "Should not warn for repeatable options: {:?}",
            opts.warnings
        );
        assert_eq!(opts.operating_currency, vec!["USD", "EUR"]);
    }

    #[test]
    fn test_invalid_tolerance_value() {
        let mut opts = Options::new();
        opts.set("inferred_tolerance_multiplier", "not_a_number");

        // E7004 (deprecated name) + E7002 (invalid value)
        assert_eq!(opts.warnings.len(), 2);
        assert_eq!(opts.warnings[0].code, "E7004");
        assert!(opts.warnings[0].message.contains("Renamed"));
        assert_eq!(opts.warnings[1].code, "E7002");
        assert!(opts.warnings[1].message.contains("expected decimal"));
    }

    #[test]
    fn test_tolerance_multiplier_new_name() {
        let mut opts = Options::new();
        opts.set("tolerance_multiplier", "1.5");

        assert!(opts.warnings.is_empty());
        assert_eq!(opts.inferred_tolerance_multiplier, Decimal::new(15, 1));
    }

    #[test]
    fn test_inferred_tolerance_multiplier_deprecated() {
        let mut opts = Options::new();
        opts.set("inferred_tolerance_multiplier", "1.01");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7004");
        assert!(
            opts.warnings[0]
                .message
                .contains("Renamed to 'tolerance_multiplier'")
        );
        assert_eq!(
            opts.inferred_tolerance_multiplier,
            Decimal::from_str("1.01").unwrap()
        );
    }

    #[test]
    fn test_invalid_boolean_value() {
        let mut opts = Options::new();
        opts.set("infer_tolerance_from_cost", "maybe");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7002");
        assert!(
            opts.warnings[0].message.contains("TRUE, FALSE, 1 or 0"),
            "the message must name the vocabulary actually accepted: {}",
            opts.warnings[0].message
        );
    }

    /// Every boolean option in ledger source shares one vocabulary, and the
    /// E7002 message names it accurately.
    ///
    /// `infer_tolerance_from_cost` used to take TRUE/FALSE only and warn on
    /// `1`, which Python beancount accepts as true for every boolean option;
    /// `render_commas` took `1`/`0` as well. The message said "TRUE or FALSE"
    /// on both. A test that only checks the rejected value cannot catch a
    /// message that under-promises, so this asserts the accepted ones too.
    #[test]
    fn boolean_options_share_one_vocabulary() {
        for key in ["infer_tolerance_from_cost", "render_commas"] {
            for (value, expected) in [
                ("TRUE", true),
                ("true", true),
                ("1", true),
                ("FALSE", false),
                ("false", false),
                ("0", false),
            ] {
                let mut opts = Options::new();
                opts.set(key, value);
                assert!(
                    opts.warnings.is_empty(),
                    "{key} = {value:?} must be accepted without a warning: {:?}",
                    opts.warnings
                );
                let actual = if key == "render_commas" {
                    opts.render_commas
                } else {
                    opts.infer_tolerance_from_cost
                };
                assert_eq!(actual, expected, "{key} = {value:?}");
            }

            let mut opts = Options::new();
            opts.set(key, "yes");
            assert_eq!(
                opts.warnings.len(),
                1,
                "{key}: `yes` is outside the shared vocabulary and must warn"
            );
        }
    }

    #[test]
    fn test_invalid_booking_method() {
        let mut opts = Options::new();
        opts.set("booking_method", "RANDOM");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7002");
        assert!(opts.warnings[0].message.contains("STRICT"));
    }

    #[test]
    fn test_valid_booking_methods() {
        for method in &["STRICT", "FIFO", "LIFO", "AVERAGE", "NONE"] {
            let mut opts = Options::new();
            opts.set("booking_method", method);
            assert!(
                opts.warnings.is_empty(),
                "Should accept {method} as valid booking method"
            );
        }
    }

    #[test]
    fn test_readonly_option_warning() {
        let mut opts = Options::new();
        opts.set("filename", "/some/path.beancount");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7005");
        assert!(opts.warnings[0].message.contains("may not be set"));
    }

    #[test]
    fn test_account_rounding_accepted_but_warns_noop() {
        let mut opts = Options::new();
        opts.set("account_rounding", "Equity:Rounding");

        // Still stored for Beancount compatibility...
        assert_eq!(opts.account_rounding.as_deref(), Some("Equity:Rounding"));
        // ...but a no-op warning is emitted so the option isn't silently swallowed.
        let w = opts
            .warnings
            .iter()
            .find(|w| w.code == "E7007")
            .expect("expected an E7007 no-op warning for account_rounding");
        assert!(w.message.contains("no effect"));
        assert_eq!(w.option, "account_rounding");
        // A valid account name must NOT also trip E7002 (invalid value).
        assert!(!opts.warnings.iter().any(|w| w.code == "E7002"));
    }

    #[test]
    fn test_invalid_account_name_validation() {
        // account_rounding with an invalid value: both the invalid-account
        // warning (E7002) and the accepted-but-no-op warning (E7007) fire.
        let mut opts = Options::new();
        opts.set("account_rounding", "invalid");

        assert!(
            opts.warnings
                .iter()
                .any(|w| w.code == "E7002" && w.message.contains("Invalid leaf account"))
        );
        assert!(opts.warnings.iter().any(|w| w.code == "E7007"));
    }

    #[test]
    fn test_valid_account_name() {
        let mut opts = Options::new();
        opts.set("account_rounding", "Equity:Rounding");

        // A valid account name does not trip E7002; the value is stored, but
        // account_rounding is a no-op in rustledger so an E7007 warning fires.
        assert!(!opts.warnings.iter().any(|w| w.code == "E7002"));
        assert!(opts.warnings.iter().any(|w| w.code == "E7007"));
        assert_eq!(opts.account_rounding, Some("Equity:Rounding".to_string()));
    }

    #[test]
    fn test_render_commas_with_numeric_values() {
        let mut opts = Options::new();
        opts.set("render_commas", "1");
        assert!(opts.render_commas);
        assert!(opts.warnings.is_empty());

        let mut opts2 = Options::new();
        opts2.set("render_commas", "0");
        assert!(!opts2.render_commas);
        assert!(opts2.warnings.is_empty());
    }

    #[test]
    fn test_plugin_processing_mode_validation() {
        // Valid values
        let mut opts = Options::new();
        opts.set("plugin_processing_mode", "default");
        assert!(opts.warnings.is_empty());
        assert_eq!(opts.plugin_processing_mode, "default");

        let mut opts2 = Options::new();
        opts2.set("plugin_processing_mode", "raw");
        assert!(opts2.warnings.is_empty());
        assert_eq!(opts2.plugin_processing_mode, "raw");

        // Invalid value
        let mut opts3 = Options::new();
        opts3.set("plugin_processing_mode", "invalid");
        assert_eq!(opts3.warnings.len(), 1);
        assert_eq!(opts3.warnings[0].code, "E7002");
    }

    #[test]
    fn test_deprecated_plugin_option() {
        let mut opts = Options::new();
        opts.set("plugin", "some.plugin");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7004");
        assert!(opts.warnings[0].message.contains("deprecated"));
    }

    #[test]
    fn test_deprecated_allow_pipe_separator() {
        let mut opts = Options::new();
        opts.set("allow_pipe_separator", "true");

        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7004");
        assert!(opts.warnings[0].message.contains("deprecated"));
    }

    #[test]
    fn test_is_valid_account() {
        // Valid accounts — ASCII
        assert!(Options::is_valid_account("Assets:Bank"));
        assert!(Options::is_valid_account("Equity:Rounding:Precision"));

        // Valid accounts — Unicode
        assert!(Options::is_valid_account("Капитал:Retained"));
        assert!(Options::is_valid_account("资产:银行:支票"));

        // Invalid accounts
        assert!(!Options::is_valid_account("invalid")); // No colon
        assert!(!Options::is_valid_account("assets:bank")); // Lowercase ASCII
        assert!(!Options::is_valid_account("Assets:")); // Empty component
        assert!(!Options::is_valid_account(":Bank")); // Empty first component
    }

    #[test]
    fn test_account_validation_options() {
        // Test all account options that require validation
        let account_options = [
            "account_rounding",
            "account_current_conversions",
            "account_unrealized_gains",
            "account_previous_balances",
            "account_previous_earnings",
            "account_previous_conversions",
            "account_current_earnings",
        ];

        for opt in account_options {
            let mut opts = Options::new();
            opts.set(opt, "lowercase:invalid");

            assert!(
                !opts.warnings.is_empty(),
                "Option '{opt}' should warn on invalid account name"
            );
            assert_eq!(opts.warnings[0].code, "E7002");
        }
    }

    #[test]
    fn test_inferred_tolerance_default() {
        let mut opts = Options::new();
        opts.set("inferred_tolerance_default", "USD:0.005");

        assert!(opts.warnings.is_empty());
        assert_eq!(
            opts.inferred_tolerance_default.get("USD"),
            Some(&rust_decimal_macros::dec!(0.005))
        );

        // Test wildcard
        let mut opts2 = Options::new();
        opts2.set("inferred_tolerance_default", "*:0.01");
        assert!(opts2.warnings.is_empty());
        assert_eq!(
            opts2.inferred_tolerance_default.get("*"),
            Some(&rust_decimal_macros::dec!(0.01))
        );

        // Test invalid format
        let mut opts3 = Options::new();
        opts3.set("inferred_tolerance_default", "INVALID");
        assert_eq!(opts3.warnings.len(), 1);
        assert_eq!(opts3.warnings[0].code, "E7002");
    }

    #[test]
    fn test_display_precision_basic() {
        let mut opts = Options::new();
        opts.set("display_precision", "USD:0.01");
        assert!(opts.warnings.is_empty(), "warnings: {:?}", opts.warnings);
        assert_eq!(opts.display_precision.get("USD"), Some(&2));
    }

    #[test]
    fn test_display_precision_high_precision() {
        let mut opts = Options::new();
        opts.set("display_precision", "BTC:0.00000001");
        assert!(opts.warnings.is_empty());
        assert_eq!(opts.display_precision.get("BTC"), Some(&8));
    }

    #[test]
    fn test_display_precision_zero_decimals() {
        // "JPY:1" → no fractional digits → precision 0.
        let mut opts = Options::new();
        opts.set("display_precision", "JPY:1");
        assert!(opts.warnings.is_empty());
        assert_eq!(opts.display_precision.get("JPY"), Some(&0));
    }

    #[test]
    fn test_display_precision_repeatable_per_currency() {
        let mut opts = Options::new();
        opts.set("display_precision", "USD:0.01");
        opts.set("display_precision", "EUR:0.001");
        assert!(opts.warnings.is_empty(), "warnings: {:?}", opts.warnings);
        assert_eq!(opts.display_precision.get("USD"), Some(&2));
        assert_eq!(opts.display_precision.get("EUR"), Some(&3));
    }

    #[test]
    fn test_display_precision_missing_colon_warns() {
        let mut opts = Options::new();
        opts.set("display_precision", "USD0.01");
        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7002");
        assert!(opts.warnings[0].message.contains("CURRENCY:EXAMPLE"));
        assert!(opts.display_precision.is_empty());
    }

    #[test]
    fn test_name_option_invalid_root_warns_e7008() {
        // Digit-start root: every account under it is unparsable (both
        // rledger and Python fail at parse time) — the option site now
        // says so up front instead of the ledger erroring at every mention.
        let mut opts = Options::new();
        opts.set("name_assets", "1Assets");
        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7008");
        assert!(opts.warnings[0].message.contains("1Assets"));
        // Accepted anyway (option-handling parity).
        assert_eq!(opts.name_assets, "1Assets");

        // Colon inside a root can never match a root component.
        let mut opts = Options::new();
        opts.set("name_income", "In:Come");
        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7008");
    }

    #[test]
    fn test_name_option_valid_roots_no_warning() {
        let mut opts = Options::new();
        opts.set("name_income", "Revenue");
        opts.set("name_assets", "Activa");
        opts.set("name_expenses", "Ausgaben");
        opts.set("name_liabilities", "負債"); // caseless (\p{Lo}) root
        assert!(
            opts.warnings.is_empty(),
            "lexable renames must not warn: {:?}",
            opts.warnings
        );
    }

    #[test]
    fn test_account_option_uses_canonical_rule() {
        // The old hand-written is_valid_account had no per-character rule:
        // 'Equity:Ro unding' style values with invalid chars slipped through
        // as long as first chars looked right. The canonical predicate
        // rejects what the lexer rejects.
        let mut opts = Options::new();
        opts.set("account_current_conversions", "Equity:Conv ersions");
        assert!(opts.warnings.iter().any(|w| w.code == "E7002"));

        let mut opts = Options::new();
        opts.set("account_current_conversions", "Equity:Conversions:Current");
        assert!(opts.warnings.is_empty(), "{:?}", opts.warnings);
    }

    #[test]
    fn test_display_precision_invalid_example_warns() {
        let mut opts = Options::new();
        opts.set("display_precision", "USD:abc");
        assert_eq!(opts.warnings.len(), 1);
        assert_eq!(opts.warnings[0].code, "E7002");
        assert!(opts.warnings[0].message.contains("Invalid precision"));
        assert!(opts.display_precision.is_empty());
    }
}