supreme_hook_config/

mod_config.rs

//! The per-mod *authored* shape: [`ModConfig`] (one mod's `mod.json`,
//! metadata, conditional/templated rules, and the parameters it exposes),
//! plus the `${param_id}` substitution/gating logic that turns it into the
//! plain [`crate::hook_config::RedirectionRule`]s
//! [`crate::hook_config::HookConfig::load_from_mods_dir`] merges across
//! mods.

use crate::error::HookConfigError;
use crate::hook_config::{RedirectionRule, RuleTarget};
use crate::patch::{MemoryPatch, ScriptSource, StringReplacement};
use crate::script_engine;
use crate::ui::ModUi;
use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use std::fs::read_to_string;
use std::path::{Path, PathBuf};

/// The on-disk shape of a single mod's `mod.json`: metadata, the mod's
/// authored (possibly conditional/templated) rules, the parameters it
/// exposes for configuration, and default values for some or all of them.
/// Holds no *per-user* values, though, those live separately in
/// [`crate::mods_state::ModConfigurations`], keyed by mod directory name, layered on top of
/// these defaults at resolution time (see
/// [`ModConfig::effective_configuration`]). That split means re-installing
/// or updating a mod (replacing this whole file, defaults included) can
/// never take a person's own overrides for it along with it.
///
/// This is distinct from [`crate::hook_config::HookConfig`], which is the *merged, resolved*
/// shape the proxy DLL actually consumes, see [`ModConfig::resolved_rules`]
/// for how one becomes the other, given a mod's current overrides.
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
pub struct ModConfig {
    /// Mandatory, also what's shown in the launcher's mod list.
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub author: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub license: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,

    #[serde(default)]
    pub rules: Vec<RedirectionRule>,
    #[serde(default)]
    pub parameters: Vec<ModParameter>,
    /// Default value for some or all of `parameters`, keyed by
    /// [`ModParameter::id`]. A parameter with no entry here, and no
    /// override in [`crate::mods_state::ModConfigurations`], reads as fully unset: off for
    /// gating, empty string for `${param_id}` interpolation. Author-owned
    /// and distributed alongside `rules`, unlike the per-user overrides
    /// in [`crate::mods_state::ModConfigurations`].
    #[serde(default)]
    pub configuration: HashMap<String, serde_json::Value>,
    /// Optional launcher-UI schema, buttons shown for this mod and the
    /// popups they open, rendered generically by the Mods page (see
    /// [`crate::ui::ModUi`]). `None` for mods without a `ui` section:
    /// they keep the plain parameter editor only, and every pre-`ui`
    /// `mod.json` stays fully valid unchanged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ui: Option<ModUi>,
}

/// One configurable setting a mod exposes to the launcher's Mods page.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct ModParameter {
    /// Stable identifier, referenced from [`RedirectionRule::enable_if`],
    /// `${param_id}` interpolation placeholders, and as a key into both
    /// this mod's own [`ModConfig::configuration`] defaults and its entry
    /// in [`crate::mods_state::ModConfigurations`].
    pub id: String,
    /// Display name shown in the launcher UI.
    pub name: String,
    /// Shown as a tooltip/help text next to the control in the launcher UI.
    pub help_text: String,
    #[serde(flatten)]
    pub kind: ParameterKind,
    /// Optional Rhai expression that must evaluate to `true` for this
    /// parameter to be editable in the launcher UI. When `false` (or when
    /// evaluation fails), the parameter falls back to its default value
    /// from [`ModConfig::configuration`] (or the type-appropriate zero
    /// value if no default exists). Other parameters' `enable_if`
    /// expressions and rule `enable_if` expressions may still reference
    /// this parameter, gating only affects the UI control, not the
    /// parameter's availability in the evaluation scope.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enable_if: Option<String>,
    /// hide this parameter from the launcher's parameter editors
    /// entirely. Hidden parameters keep EVERY other behavior (validation,
    /// `enable_if` scope, `${...}` interpolation, configuration merge,
    /// launcher-written overrides), they are just not user-facing
    /// controls. The online-tournament mod declares its
    /// `tournament_env` / `tournament_difficulty` /
    /// `tournament_room_id` this way: the launcher sets them when the
    /// player creates or joins a room; a user has no business editing them.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub hidden: bool,
    /// Optional name of a shared validation rule set (see
    /// [`crate::validation`]) the launcher enforces live while the user
    /// edits this parameter: invalid input renders an error stroke and a
    /// warning icon whose hover carries the reason. Known tags:
    /// `player_name`, `room_name`; unknown tags fail
    /// [`ModConfig::validate`]. Only meaningful on text parameters.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validation: Option<String>,
}

/// The type of control a [`ModParameter`] is edited with, and the data
/// that type needs. Serializes flat alongside `id`/`name`/`help_text` via
/// `#[serde(flatten)]` on [`ModParameter::kind`], tagged by a `"type"`
/// field, e.g.:
///
/// ```json
/// { "id": "Fov_Boost", "name": "FOV boost", "help_text": "...",
///   "type": "number", "min": 0.0, "max": 20.0, "step": 0.5 }
/// ```
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ParameterKind {
    /// A checkbox. May gate a [`RedirectionRule::enable_if`].
    Boolean,
    /// A dropdown among `choices`. May gate a [`RedirectionRule::enable_if`]
    /// (empty-string selection = off). "(None)" is *not* implicit, a
    /// dropdown only has a "no selection" state if `""` is itself one of
    /// `choices`; otherwise every choice is non-empty and the parameter is
    /// always "on" for gating purposes.
    Dropdown { choices: Vec<String> },
    /// A numeric slider between `min` and `max`, with an optional step.
    /// Cannot gate a rule, only usable via `${param_id}` interpolation.
    Number {
        min: f32,
        max: f32,
        #[serde(default, skip_serializing_if = "Option::is_none")]
        step: Option<f32>,
    },
    /// A free-text field. Cannot gate a rule, only usable via
    /// `${param_id}` interpolation.
    Text,
}

impl ModParameter {
    /// Structural validation, independent of any other parameter or rule,
    /// called from [`ModConfig::validate`] so a malformed `mod.json`
    /// surfaces as a clear per-mod error at load time.
    ///
    /// # Errors
    ///
    /// Returns an error describing the problem if this parameter's data is
    /// internally inconsistent (e.g. a dropdown with no choices, or a
    /// number range with `min > max`).
    pub fn validate(&self) -> Result<(), String> {
        match &self.kind {
            ParameterKind::Dropdown { choices } if choices.is_empty() => Err(format!(
                "parameter '{}': dropdown needs at least one choice",
                self.id
            )),
            ParameterKind::Number { min, max, .. } if min > max => {
                Err(format!("parameter '{}': min must be <= max", self.id))
            }
            _ => Ok(()),
        }
    }
}

impl ModConfig {
    /// Loads a `ModConfig` from a single JSON file on disk (one mod's
    /// `mod.json`).
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be read or does not contain
    /// valid JSON matching the expected shape.
    pub fn load_from_path(path: &Path) -> Result<Self, HookConfigError> {
        let bytes = std::fs::read(path).map_err(|source| HookConfigError::Read {
            path: path.to_path_buf(),
            source,
        })?;
        Ok(serde_json::from_slice(&bytes)?)
    }

    /// Like [`Self::load_from_path`], but also returns warnings about
    /// unknown keys in the JSON file. Keys prefixed with `_` are
    /// considered intentional private metadata and are never warned about.
    /// Unknown keys at any nesting level are reported with their path
    /// (e.g. `"unknown key 'future_field' at parameters[1]"`).
    pub fn load_from_path_with_warnings(
        path: &Path,
    ) -> Result<(Self, Vec<String>), HookConfigError> {
        let bytes = std::fs::read(path).map_err(|source| HookConfigError::Read {
            path: path.to_path_buf(),
            source,
        })?;

        // Parse once as raw Value for key comparison.
        let original: serde_json::Value = serde_json::from_slice(&bytes)?;

        // Parse into typed struct (silently ignores unknown keys).
        let config: ModConfig = serde_json::from_slice(&bytes)?;

        // Re-serialize to get the "known keys" view.
        let reserialized =
            serde_json::to_value(&config).expect("ModConfig serialization should never fail");

        let warnings = collect_unknown_keys(&original, &reserialized, "");

        Ok((config, warnings))
    }

    /// Serializes and writes this `ModConfig` to a JSON file on disk,
    /// creating parent directories as needed.
    ///
    /// # Errors
    ///
    /// Returns an error if parent directories can't be created, the file
    /// can't be written, or serialization fails.
    pub fn write_to_path(&self, path: &Path) -> Result<(), HookConfigError> {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|source| HookConfigError::Write {
                path: path.to_path_buf(),
                source,
            })?;
        }
        let json = serde_json::to_vec_pretty(self)?;
        std::fs::write(path, json).map_err(|source| HookConfigError::Write {
            path: path.to_path_buf(),
            source,
        })
    }

    /// Structural validation of the whole mod: mandatory `name`, each
    /// parameter's own validity (see [`ModParameter::validate`]), and
    /// every rule's `enable_if` (if any), evaluated as Rhai expressions.
    ///
    /// # Errors
    ///
    /// Returns every problem found (not just the first), so a mod author
    /// or the launcher's error display for a broken mod, can see the
    /// whole picture at once.
    pub fn validate(&self) -> Result<(), Vec<String>> {
        let mut errors = Vec::new();

        if self.name.trim().is_empty() {
            errors.push("'name' is mandatory".to_string());
        }

        for param in &self.parameters {
            if let Err(e) = param.validate() {
                errors.push(e);
            }
            if let Some(tag) = &param.validation {
                if !crate::validation::is_known_tag(tag) {
                    errors.push(format!(
                        "parameter '{}': unknown validation tag `{tag}` (expected one of: {})",
                        param.id,
                        crate::validation::KNOWN_TAGS.join(", ")
                    ));
                } else if !matches!(param.kind, ParameterKind::Text) {
                    errors.push(format!(
                        "parameter '{}': carries a validation tag, which only text parameters enforce",
                        param.id
                    ));
                }
            }
            // Check for circular dependencies among parameter enable_if expressions.
            self.check_parameter_enable_if_cycles(&mut errors);
            // Validate parameter-level enable_if using the same machinery
            // as rule-level enable_if.
            self.check_enable_if(&param.enable_if, &mut errors);
        }

        for rule in &self.rules {
            self.check_enable_if(&rule.enable_if, &mut errors);
            // Managed targets : one remote URL can only name one
            // file, so the glob must be literal; the URLs must be real
            // http(s) URLs; a poll interval, when present, must be at least
            // one second (0 would spin the refresh engine).
            if let Some(RuleTarget::Managed {
                local,
                remote,
                poll_interval_secs,
                push_url,
            }) = &rule.target
            {
                if !rule.is_literal_glob() {
                    errors.push(format!(
                        "Rule `{}`: a managed (struct) target requires a literal glob; \
                         a wildcard pattern cannot be named by a single remote URL",
                        rule.glob_pattern
                    ));
                }
                if local.as_os_str().is_empty() {
                    errors.push(format!(
                        "Rule `{}`: managed target's `local` path is empty",
                        rule.glob_pattern
                    ));
                }
                // The URL check only applies to fully-authored URLs: an
                // uninterpolated `${...}` placeholder (e.g. the launcher-
                // written `${tournament_server_url}`) is checked after
                // interpolation, the shipped-package test asserts the
                // resolved form.
                if !remote.contains("${")
                    && !remote.starts_with("http://")
                    && !remote.starts_with("https://")
                {
                    errors.push(format!(
                        "Rule `{}`: managed target's `remote` must be an http(s) URL, got `{remote}`",
                        rule.glob_pattern
                    ));
                }
                // Same rule for the optional push URL : absent =
                // fetch-only; present = where game writes are POSTed.
                if let Some(push_url) = push_url
                    && !push_url.contains("${")
                    && !push_url.starts_with("http://")
                    && !push_url.starts_with("https://")
                {
                    errors.push(format!(
                        "Rule `{}`: managed target's `push_url` must be an http(s) URL, \
                         got `{push_url}`",
                        rule.glob_pattern
                    ));
                }
                if poll_interval_secs.is_some_and(|s| s == 0) {
                    errors.push(format!(
                        "Rule `{}`: managed target's `poll_interval_secs` must be at least 1 \
                         (omit it for no polling)",
                        rule.glob_pattern
                    ));
                }
            }
            for patch in &rule.patches {
                match patch {
                    MemoryPatch::ReplaceBytes { replacements } => {
                        for r in replacements {
                            self.check_enable_if(&r.enable_if, &mut errors);
                        }
                    }
                    MemoryPatch::ReplaceString { replacements } => {
                        for r in replacements {
                            self.check_enable_if(&r.enable_if, &mut errors);
                        }
                    }
                    MemoryPatch::Script { source, .. } => {
                        let script_result = match source {
                            ScriptSource::Inline { inline } => {
                                script_engine::validate_script(inline, &self.parameters)
                            }
                            ScriptSource::File { file } => match read_to_string(file) {
                                Ok(s) => script_engine::validate_script(&s, &self.parameters),
                                Err(e) => Err(script_engine::ScriptError::Runtime {
                                    message: format!(
                                        "Failed to read script file {}: {}",
                                        file.display(),
                                        e
                                    ),
                                }),
                            },
                        };
                        if let Err(e) = script_result {
                            errors.push(format!("Script patch validation failed: {}", e));
                        }
                    }
                }
            }
        }

        let mut seen_ids = HashSet::new();
        for param in &self.parameters {
            if !seen_ids.insert(param.id.as_str()) {
                errors.push(format!(
                    "Duplicate parameter id `{}`; every parameter id must be unique",
                    param.id
                ));
            }
        }

        // Same collect-everything convention for the optional `ui`
        // section: its problems surface as per-mod validation errors,
        // never as parse failures (unknown kinds are deliberately kept
        // parseable by the `Unknown` catch-alls so this check can name
        // them).
        if let Some(ui) = &self.ui
            && let Err(ui_errors) = ui.validate()
        {
            errors.extend(ui_errors);
        }

        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors)
        }
    }

    /// Checks one `enable_if` expression, appending a message to `errors`
    /// in case of problem. Shared by [`Self::validate`] for both call sites,
    /// a rule's `enable_if` and a replacement's `enable_if` mean exactly
    /// the same thing, just at different granularity.
    fn check_enable_if(&self, enable_if: &Option<String>, errors: &mut Vec<String>) {
        let Some(expr) = enable_if else { return };
        if let Err(e) = script_engine::validate_expression(expr, &self.parameters) {
            errors.push(format!("enable_if expression '{}' is invalid: {}", expr, e));
        }
    }

    /// Detects cycles in parameter `enable_if` dependencies. A parameter's
    /// `enable_if` expression may reference other parameters; those
    /// referenced parameters may themselves have `enable_if` expressions.
    /// This must form a DAG, a cycle like A→B→A would make evaluation
    /// order undefined and could cause infinite loops in a naive
    /// recursive evaluator.
    ///
    /// We extract variable references from each parameter's `enable_if`
    /// by compiling it and inspecting which declared parameter ids appear
    /// as identifiers in the expression. This is conservative: we only
    /// flag references to *declared* parameters, ignoring literals,
    /// operators, and Rhai builtins.
    fn check_parameter_enable_if_cycles(&self, errors: &mut Vec<String>) {
        // Build adjacency list: param_id -> set of param_ids its enable_if references.
        let param_ids: HashSet<&str> = self.parameters.iter().map(|p| p.id.as_str()).collect();
        let mut deps: HashMap<&str, Vec<&str>> = HashMap::new();

        for param in &self.parameters {
            let Some(expr) = &param.enable_if else {
                continue;
            };
            // Extract referenced parameter ids by checking which declared
            // ids appear as substrings in the expression. This is simpler
            // than parsing the Rhai AST and sufficient since parameter ids
            // are user-chosen identifiers that won't collide with Rhai
            // keywords or operators in practice.
            let referenced: Vec<&str> = param_ids
                .iter()
                .filter(|&&id| id != param.id.as_str() && expr.contains(id))
                .copied()
                .collect();
            if !referenced.is_empty() {
                deps.insert(param.id.as_str(), referenced);
            }
        }

        // DFS-based cycle detection with three-color marking.
        #[derive(Clone, Copy, PartialEq)]
        enum Color {
            White,
            Gray,
            Black,
        }

        let mut colors: HashMap<&str, Color> = HashMap::new();
        for param in &self.parameters {
            colors.insert(param.id.as_str(), Color::White);
        }

        fn dfs<'a>(
            node: &'a str,
            deps: &HashMap<&'a str, Vec<&'a str>>,
            colors: &mut HashMap<&'a str, Color>,
            path: &mut Vec<&'a str>,
        ) -> Option<Vec<&'a str>> {
            colors.insert(node, Color::Gray);
            path.push(node);

            if let Some(neighbors) = deps.get(node) {
                for &neighbor in neighbors {
                    match colors.get(neighbor).copied() {
                        Some(Color::Gray) => {
                            // Found a cycle, extract just the cyclic portion.
                            let cycle_start = path.iter().position(|&n| n == neighbor).unwrap();
                            let mut cycle = path[cycle_start..].to_vec();
                            cycle.push(neighbor);
                            return Some(cycle);
                        }
                        Some(Color::White) => {
                            if let Some(cycle) = dfs(neighbor, deps, colors, path) {
                                return Some(cycle);
                            }
                        }
                        _ => {} // Black = already fully explored, no cycle through here.
                    }
                }
            }

            path.pop();
            colors.insert(node, Color::Black);
            None
        }

        for param in &self.parameters {
            if colors.get(param.id.as_str()) == Some(&Color::White) {
                let mut path = Vec::new();
                if let Some(cycle) = dfs(param.id.as_str(), &deps, &mut colors, &mut path) {
                    let cycle_str = cycle
                        .iter()
                        .map(|s| s.to_string())
                        .collect::<Vec<_>>()
                        .join(" → ");
                    errors.push(format!(
                        "circular enable_if dependency detected: {}",
                        cycle_str
                    ));
                    return; // One cycle report is enough; more would be redundant.
                }
            }
        }
    }

    /// This mod's parameter values for resolution purposes: its own
    /// `configuration` defaults, with `overrides` (typically a person's
    /// entry from [`crate::mods_state::ModConfigurations`]) layered on top,
    /// then any parameter whose `enable_if` evaluates to `false` is forced
    /// back to its default value (from `self.configuration`) or the
    /// type-appropriate zero value if no default exists. This ensures
    /// disabled parameters never retain stale overrides that could affect
    /// other parameters' `enable_if` evaluations or rule interpolation.
    ///
    /// Parameters are resolved in dependency order (parameters with no
    /// `enable_if` or whose dependencies are already resolved first), so
    /// a chain like A→B→C correctly cascades: if A is disabled, B sees
    /// A's default, which may disable B, which then also falls back.
    #[must_use]
    pub fn effective_configuration(
        &self,
        overrides: &HashMap<String, serde_json::Value>,
    ) -> HashMap<String, serde_json::Value> {
        let mut merged = self.configuration.clone();
        merged.extend(overrides.iter().map(|(k, v)| (k.clone(), v.clone())));

        // Topological sort of parameters by enable_if dependencies.
        // Parameters without enable_if come first, then those depending
        // only on already-resolved parameters, etc.
        let param_map: HashMap<&str, &ModParameter> =
            self.parameters.iter().map(|p| (p.id.as_str(), p)).collect();

        let param_ids: HashSet<&str> = param_map.keys().copied().collect();
        let mut resolved: HashSet<&str> = HashSet::new();
        let mut ordered: Vec<&str> = Vec::with_capacity(self.parameters.len());

        // Simple iterative topological sort: repeatedly pick any
        // unresolved parameter whose dependencies are all resolved.
        while ordered.len() < self.parameters.len() {
            let mut progress = false;
            for param in &self.parameters {
                if resolved.contains(param.id.as_str()) {
                    continue;
                }
                let deps_satisfied = match &param.enable_if {
                    None => true,
                    Some(expr) => param_ids
                        .iter()
                        .filter(|&&id| id != param.id.as_str() && expr.contains(id))
                        .all(|&id| resolved.contains(id)),
                };
                if deps_satisfied {
                    ordered.push(param.id.as_str());
                    resolved.insert(param.id.as_str());
                    progress = true;
                }
            }
            if !progress {
                // Remaining parameters have unresolvable deps (shouldn't
                // happen if cycle detection passed, but be safe). Process
                // them in declaration order as a fallback.
                for param in &self.parameters {
                    if !resolved.contains(param.id.as_str()) {
                        ordered.push(param.id.as_str());
                        resolved.insert(param.id.as_str());
                    }
                }
                break;
            }
        }

        // Now evaluate enable_if in dependency order, forcing disabled
        // parameters to their default values.
        for &id in &ordered {
            let Some(param) = param_map.get(id) else {
                continue;
            };
            let Some(expr) = &param.enable_if else {
                continue;
            };

            let enabled = script_engine::evaluate_bool_expression(expr, &self.parameters, &merged)
                .unwrap_or(false);

            if !enabled {
                // Force this parameter to its default (or type zero value).
                let default_value =
                    self.configuration
                        .get(id)
                        .cloned()
                        .unwrap_or_else(|| match param.kind {
                            ParameterKind::Boolean => serde_json::json!(false),
                            ParameterKind::Dropdown { .. } | ParameterKind::Text => {
                                serde_json::json!("")
                            }
                            ParameterKind::Number { .. } => serde_json::json!(0.0),
                        });
                merged.insert(id.to_string(), default_value);
            }
        }

        merged
    }

    /// The rules the DLL should actually apply for this mod, given
    /// `overrides` (see [`Self::effective_configuration`]): rules gated
    /// off by their `enable_if` are dropped outright; within a surviving
    /// rule, individual replacements inside `patches` are *also* gated by
    /// their own `enable_if` the same way, independent of the rule's own
    /// gating (a rule can be unconditional while only some of its
    /// replacements are conditional, see the "Fast_Start" example this
    /// was built for). Every surviving rule and replacement's `${param_id}`
    /// placeholders (in `glob_pattern`, `target`, and any
    /// `MemoryPatch::ReplaceString` `find`/`replace` text) are interpolated
    /// via Rhai's native string interpolation. `MemoryPatch::ReplaceBytes`
    /// text is never interpolated, its `find`/`replace` are raw bytes,
    /// not text, so there's no placeholder syntax to look for, but it's
    /// still gated by its own `enable_if`.
    ///
    /// By the time a rule leaves this function there's no templating or
    /// conditionality left in it at all, this is the shape
    /// [`crate::hook_config::HookConfig::load_from_mods_dir`] merges across mods, and the
    /// shape the proxy DLL consumes.
    #[must_use]
    pub fn resolved_rules(
        &self,
        overrides: &HashMap<String, serde_json::Value>,
    ) -> Vec<RedirectionRule> {
        let configuration = self.effective_configuration(overrides);
        self.rules
            .iter()
            .filter(|rule| match &rule.enable_if {
                None => true,
                Some(expr) => {
                    script_engine::evaluate_bool_expression(expr, &self.parameters, &configuration)
                        .unwrap_or(false)
                }
            })
            .map(|rule| substitute_rule(rule, &self.parameters, &configuration))
            .collect()
    }
}

fn substitute_rule(
    rule: &RedirectionRule,
    parameters: &[ModParameter],
    configuration: &HashMap<String, serde_json::Value>,
) -> RedirectionRule {
    RedirectionRule {
        glob_pattern: substitute_placeholders(&rule.glob_pattern, parameters, configuration, true),
        target: rule.target.as_ref().map(|t| match t {
            RuleTarget::Path(p) => RuleTarget::Path(PathBuf::from(substitute_placeholders(
                &p.to_string_lossy(),
                parameters,
                configuration,
                false,
            ))),
            RuleTarget::Managed {
                local,
                remote,
                poll_interval_secs,
                push_url,
            } => RuleTarget::Managed {
                local: PathBuf::from(substitute_placeholders(
                    &local.to_string_lossy(),
                    parameters,
                    configuration,
                    false,
                )),
                remote: substitute_placeholders(remote, parameters, configuration, false),
                poll_interval_secs: *poll_interval_secs,
                push_url: push_url
                    .as_ref()
                    .map(|u| substitute_placeholders(u, parameters, configuration, false)),
            },
        }),
        mode: rule.mode,
        patches: rule
            .patches
            .iter()
            .map(|p| substitute_patch(p, parameters, configuration))
            .collect(),
        enable_if: rule.enable_if.clone(),
    }
}

fn substitute_patch(
    patch: &MemoryPatch,
    parameters: &[ModParameter],
    configuration: &HashMap<String, serde_json::Value>,
) -> MemoryPatch {
    match patch {
        MemoryPatch::ReplaceBytes { replacements } => MemoryPatch::ReplaceBytes {
            replacements: replacements
                .iter()
                .filter(|r| match &r.enable_if {
                    None => true,
                    Some(expr) => {
                        script_engine::evaluate_bool_expression(expr, parameters, configuration)
                            .unwrap_or(false)
                    }
                })
                .cloned()
                .collect(),
        },
        MemoryPatch::ReplaceString { replacements } => MemoryPatch::ReplaceString {
            replacements: replacements
                .iter()
                .filter(|r| match &r.enable_if {
                    None => true,
                    Some(expr) => {
                        script_engine::evaluate_bool_expression(expr, parameters, configuration)
                            .unwrap_or(false)
                    }
                })
                .map(|r| StringReplacement {
                    find: substitute_placeholders(&r.find, parameters, configuration, false),
                    replace: substitute_placeholders(&r.replace, parameters, configuration, false),
                    enable_if: r.enable_if.clone(),
                })
                .collect(),
        },
        MemoryPatch::Script { source, .. } => MemoryPatch::Script {
            source: source.clone(),
            parameters: parameters.to_vec(),
            configuration: configuration.clone(),
        },
    }
}

/// Renders a configured parameter value as a plain string, used when
/// pre-escaping substituted values for glob context (see
/// [`substitute_placeholders`]).
fn stringify_configured_value(value: &serde_json::Value) -> String {
    match value {
        serde_json::Value::Bool(b) => b.to_string(),
        serde_json::Value::Number(n) => n.to_string(),
        serde_json::Value::String(s) => s.clone(),
        _ => String::new(),
    }
}

/// Interpolates `${...}` expressions in `text` using Rhai's native string
/// interpolation, with each parameter's value from `configuration`
/// available as a variable in the evaluation scope. The expression inside
/// `${...}` can be a bare parameter id (e.g. `${Board_Style}`) or any
/// valid Rhai expression (e.g. `${Board_Style + "_v2"}`).
///
/// When `escape_for_glob` is true, glob-special characters in configured
/// values are escaped first (see [`escape_glob_special_chars`]) so they
/// are matched literally by [`glob::Pattern`] rather than reinterpreted
/// as wildcard syntax.
///
/// If interpolation fails (e.g. an unknown variable, or a malformed
/// `${...}` expression), `text` is returned unchanged, this should be
/// caught by [`ModConfig::validate`] at load time, not silently
/// misbehave here.
fn substitute_placeholders(
    text: &str,
    parameters: &[ModParameter],
    configuration: &HashMap<String, serde_json::Value>,
    escape_for_glob: bool,
) -> String {
    if escape_for_glob {
        // Pre-escape glob-special characters in all configured values so
        // they are matched literally by `glob::Pattern` after interpolation.
        let escaped_config: HashMap<String, serde_json::Value> = configuration
            .iter()
            .map(|(k, v)| {
                let escaped = escape_glob_special_chars(&stringify_configured_value(v));
                (k.clone(), serde_json::Value::String(escaped))
            })
            .collect();
        script_engine::interpolate_string(text, parameters, &escaped_config)
            .unwrap_or_else(|_| text.to_string())
    } else {
        script_engine::interpolate_string(text, parameters, configuration)
            .unwrap_or_else(|_| text.to_string())
    }
}

/// Recursively compares two JSON values structurally, collecting keys
/// present in `original` but absent from `reserialized` at every level.
/// Keys starting with `_` are intentionally ignored (reserved for mod
/// authors' private metadata).
///
/// `path` tracks the current location for human-readable warning messages
/// (e.g. `"parameters[1]"`, `"rules[0].patches"`).
fn collect_unknown_keys(
    original: &serde_json::Value,
    reserialized: &serde_json::Value,
    path: &str,
) -> Vec<String> {
    let mut warnings = Vec::new();

    match (original, reserialized) {
        (serde_json::Value::Object(orig_map), serde_json::Value::Object(reser_map)) => {
            for (key, orig_val) in orig_map {
                if key.starts_with('_') {
                    continue; // Intentionally private/ignored by convention.
                }
                match reser_map.get(key) {
                    Some(reser_val) => {
                        // Key exists in both, recurse into the value.
                        let child_path = if path.is_empty() {
                            key.clone()
                        } else {
                            format!("{path}.{key}")
                        };
                        warnings.extend(collect_unknown_keys(orig_val, reser_val, &child_path));
                    }
                    None => {
                        // Key in original but not in reserialized → unknown.
                        let location = if path.is_empty() {
                            "root".to_string()
                        } else {
                            path.to_string()
                        };
                        warnings.push(format!(
                            "This mod may require a newer launcher version (unknown key `{key}` at {location})"
                        ));
                    }
                }
            }
        }
        (serde_json::Value::Array(orig_arr), serde_json::Value::Array(reser_arr)) => {
            // Compare paired elements by index. Extra elements in original
            // beyond reserialized length shouldn't happen with round-trip,
            // but handle gracefully.
            for (i, orig_elem) in orig_arr.iter().enumerate() {
                let child_path = format!("{path}[{i}]");
                if let Some(reser_elem) = reser_arr.get(i) {
                    warnings.extend(collect_unknown_keys(orig_elem, reser_elem, &child_path));
                }
            }
        }
        // Leaf values or type mismatches, nothing to compare.
        _ => {}
    }

    warnings
}

/// Escapes glob-special characters (`*`, `?`, `[`, `]`) in a substituted
/// value so it's matched as literal text by [`glob::Pattern`] rather than
/// reinterpreted as wildcard syntax, each special character is wrapped in
/// its own one-character class (e.g. `*` becomes `[*]`), the standard
/// technique for embedding a literal character in glob syntax.
///
/// This does *not*, and structurally can't, prevent a literal `/` or `\`
/// in a substituted value from acting as a path separator once it lands in
/// the pattern, `glob`'s separator handling treats both natively (see the
/// note on [`crate::hook_config::MATCH_OPTIONS`]). Parameter values meant to fill a single
/// path segment (like a dropdown choice used in a `target` or
/// `glob_pattern`) simply shouldn't contain separators.
fn escape_glob_special_chars(value: &str) -> String {
    let mut out = String::with_capacity(value.len());
    for c in value.chars() {
        match c {
            '*' | '?' | '[' | ']' => {
                out.push('[');
                out.push(c);
                out.push(']');
            }
            _ => out.push(c),
        }
    }
    out
}