tiger_lib/

context.rs

//! [`ScopeContext`] tracks our knowledge of the scope types used in script and validates its consistency.

use std::borrow::Cow;
use std::thread::panicking;

use crate::everything::Everything;
use crate::game::Game;
use crate::helpers::{ActionOrEvent, TigerHashMap, stringify_choices};
use crate::report::{ErrorKey, ReportBuilderFull, err, warn};
use crate::scopes::Scopes;
use crate::token::Token;

/// When reporting an unknown scope, list alternative scope names if there are not more than this.
const MAX_SCOPE_NAME_LIST: usize = 6;

/// The `ScopeContext` represents what we know about the scopes leading to the `Block`
/// currently being validated.
#[derive(Clone, Debug)]
pub struct ScopeContext {
    /// `scope_stack` contains all known previous scopes, with `this` at the end. The oldest scope
    /// is at index 0. INVARIANT: it is never empty, because there is always `this`.
    ///
    /// Normally, `this` starts as a `ScopeEntry::Rootref`, but there are cases where the
    /// relationship to root is not known.
    scope_stack: Vec<ScopeEntry>,

    /// root is always a `ScopeEntry::Scope`
    root: ScopeEntry,

    /// `from` is the previous event root, and can be stacked like `from.from`.
    /// The topmost `from` is at index 0, the next older one is at index 1, etc.
    /// A `from` entry is always a `ScopeEntry::Scope`.
    #[cfg(feature = "hoi4")]
    from: Vec<ScopeEntry>,

    /// Names of named scopes; the values are indices into the `named` vector.
    scope_names: TigerHashMap<&'static str, (usize, Temporary)>,
    /// Names of named lists; the values are indices into the `named` vector.
    scope_list_names: TigerHashMap<&'static str, (usize, Temporary)>,
    /// Names of local variables; the values are indices into the `named` vector.
    local_names: TigerHashMap<&'static str, usize>,
    /// Names of local variable lists; the values are indices into the `named` vector.
    local_list_names: TigerHashMap<&'static str, usize>,

    /// Named scope values are `ScopeEntry::Scope` or `ScopeEntry::Named` or `ScopeEntry::Rootref`.
    /// Invariant: there are no cycles in the array via `ScopeEntry::Named` entries.
    /// Invariant: entries are only added, never removed or rearranged.
    /// This is because the indices are used by `ScopeEntry::Named` values throughout this `ScopeContext`.
    named: Vec<ScopeEntry>,

    /// Same indices as `named`, is a token iff the named scope is expected to be set on entry to the current scope context.
    /// Invariant: `named` and `is_input` are the same length.
    is_input: Vec<Option<Token>>,

    /// Is this scope level a level in progress? `is_builder` is used when evaluating scope chains
    /// like `root.liege.primary_title`. It affects the handling of `prev`, because the builder
    /// scope is not a real scope level yet.
    is_builder: bool,

    /// Was this `ScopeContext` created as an unrooted context? Unrooted means we do not know
    /// whether `this` and `root` are the same at the start.
    is_unrooted: bool,

    /// How many dummy `prev` levels were added to this scope context?
    /// They affect how the scope context is cleaned up.
    /// Usually 0 or 1, but imperator and hoi4 can have multiple prev levels.
    prev_levels: usize,

    /// Is this scope context one where all the named scopes are (or should be) known in advance?
    /// If `strict_scopes` is false, then the `ScopeContext` will assume any name might be a valid
    /// scope name that we just don't know about yet.
    strict_scopes: bool,

    /// A special flag for scope contexts that are known to be wrong. It's used for the
    /// `scope_override` config file feature. If `no_warn` is set then this `ScopeContext` will not
    /// emit any reports.
    no_warn: bool,

    /// A token indicating where this context was created and its named scopes were initialized.
    source: Token,

    /// A history of the actions and events that were triggered on the way from `source` to the
    /// current context.
    traceback: Vec<ActionOrEvent>,
}

#[derive(Clone, Debug, Default)]
/// `ScopeEntry` is a description of what we know of a scope's type and its connection to other
/// scopes.
///
/// It is used both to look up a scope's type, and to propagate knowledge about that type backward
/// to the scope's source. For example if `this` is a Rootref, and we find out that `this` is a
/// `Character`, then `root` must be a `Character` too.
enum ScopeEntry {
    /// Backref is for when the current scope is made with `prev` or `this`.
    /// It counts as a scope in the chain, for purposes of `prev` and such, but any updates
    /// to it (such as narrowing of scope types) need to be propagated back to the
    /// real origin of that scope.
    ///
    /// The backref number is a relative count into `scope_stack`, counting backwards from the
    /// entry in question.
    /// It may go past the edge of `scope_stack`, if the script being analyzed uses `prev` farther
    /// than we know about
    ///
    /// INVARIANT: The `usize` must not be zero.
    Backref(usize),

    /// Fromref is for when the current scope is made with `from`.
    /// The fromref number is 0 for a single `from`, 1 for `from.from`, etc.
    #[cfg(feature = "hoi4")]
    Fromref(usize),

    /// A Rootref is for when the current scope is made with `root`. Most of the time,
    /// we also start with `this` being a Rootref.
    #[default]
    Rootref,

    /// `Reason` why we think the `Scopes` value is what it is.
    /// It's usually the token that was the cause of the latest narrowing.
    Scope(Scopes, Reason),

    /// The scope takes its value from a named scope. The `usize` is an index into the `ScopeContext::named` vector.
    Named(usize),

    /// The scope takes its value from a global variable
    #[cfg(feature = "jomini")]
    GlobalVar(&'static str, Reason),

    /// The scope takes its value from a global variable list
    #[cfg(feature = "jomini")]
    GlobalList(&'static str, Reason),

    /// The scope takes its value from a normal variable
    #[cfg(feature = "jomini")]
    Var(&'static str, Reason),

    /// The scope takes its value from a variable list
    #[cfg(feature = "jomini")]
    VarList(&'static str, Reason),
}

/// This enum records the reason why we think a certain scope has the type it does.
/// It is used for error reporting.
///
/// TODO: make a `ReasonRef` that contains an `&Token`, and a `Borrow` impl for it.
/// This will avoid some cloning.
#[derive(Clone, Debug)]
pub enum Reason {
    /// The reason can be explained by pointing at some token
    Token(Token),
    /// The scope type was deduced from a named scope's name; the `Token` points at that name in
    /// the script.
    Name(Token),
    /// The scope was supplied by the game engine. The `Token` points at a key explaining this, for
    /// example the key of an `Item` or the field key of a trigger or effect in an item.
    Builtin(Token),
    /// The vic3 engine evaluates `multiplier` in `add_modifier` in root scope, which is probably a
    /// bug. Explain it to the user when it comes up. The `Token` points at the `multiplier` key.
    #[cfg(feature = "vic3")]
    MultiplierBug(Token),
    /// The scope type was taken from info about a variable or variable list in the given namespace.
    #[cfg(feature = "jomini")]
    VariableReference(Token, &'static str),
}

/// Information about a temporarily suspended scope-building operation.
/// This is used in constructs like `squared_distance(prev.capital_province)`,
/// where the builder scope opened by `squared_distance` needs to be preserved
/// while `prev.capital_province` is evaluated in the original scope.
#[repr(transparent)]
#[cfg(any(feature = "ck3", feature = "vic3", feature = "eu5"))]
pub struct StashedBuilder {
    this: ScopeEntry,
}

/// The essential characteristics of a `ScopeContext` for the purpose of deciding whether an event
/// has already been evaluated with a similar-enough `ScopeContext`.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Signature {
    root: Scopes,
    // these are all sorted
    scope_names: Vec<(&'static str, Scopes)>,
    scope_list_names: Vec<(&'static str, Scopes)>,
    local_names: Vec<(&'static str, Scopes)>,
    local_list_names: Vec<(&'static str, Scopes)>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Temporary {
    No,
    Yes,
    Wiped,
}

/// Backref index to pass to refer to the `this` scope.
const THIS: usize = 1;
/// Backref index to pass to refer to the `prev` scope.
const PREV: usize = 2;

impl Reason {
    pub fn token(&self) -> &Token {
        match self {
            Reason::Token(t) | Reason::Name(t) | Reason::Builtin(t) => t,
            #[cfg(feature = "vic3")]
            Reason::MultiplierBug(t) => t,
            #[cfg(feature = "jomini")]
            Reason::VariableReference(t, _) => t,
        }
    }

    // TODO: change this to Display ?
    pub fn msg(&self) -> Cow<'_, str> {
        match self {
            Reason::Token(t) => Cow::Owned(format!("deduced from `{t}` here")),
            Reason::Name(_) => Cow::Borrowed("deduced from the scope's name"),
            Reason::Builtin(_) => Cow::Borrowed("supplied by the game engine"),
            #[cfg(feature = "vic3")]
            Reason::MultiplierBug(_) => {
                Cow::Borrowed("evaluated in root scope for `multiplier` (as of 1.9.8")
            }
            #[cfg(feature = "jomini")]
            Reason::VariableReference(t, namespace) => {
                Cow::Owned(format!("based on {namespace}{t}"))
            }
        }
    }
}

impl ScopeEntry {
    fn deduce<T: Into<Token>>(token: T) -> ScopeEntry {
        let token = token.into();
        if let Some(scopes) = scope_type_from_name(token.as_str()) {
            ScopeEntry::Scope(scopes, Reason::Name(token))
        } else {
            ScopeEntry::Scope(Scopes::all(), Reason::Token(token))
        }
    }
}

impl ScopeContext {
    /// Make a new `ScopeContext`, with `this` and `root` the same, and `root` of the given scope
    /// types. `token` is used when reporting errors about the use of `root`.
    pub fn new<T: Into<Token>>(root: Scopes, token: T) -> Self {
        let token = token.into();
        ScopeContext {
            scope_stack: vec![ScopeEntry::Rootref],
            root: ScopeEntry::Scope(root, Reason::Builtin(token.clone())),
            #[cfg(feature = "hoi4")]
            from: Vec::new(),
            scope_names: TigerHashMap::default(),
            scope_list_names: TigerHashMap::default(),
            local_names: TigerHashMap::default(),
            local_list_names: TigerHashMap::default(),
            named: Vec::new(),
            is_input: Vec::new(),
            is_builder: false,
            is_unrooted: false,
            prev_levels: 0,
            strict_scopes: true,
            no_warn: false,
            source: token,
            traceback: Vec::new(),
        }
    }

    /// Make a new `ScopeContext`, with `this` and `root` unconnected, and `this` of the given scope
    /// types. `token` is used when reporting errors about the use of `this`, `root`, or `prev`.
    ///
    /// This function is useful for the scope contexts created for scripted effects, scripted
    /// triggers, and script values. In those, it's not known what the caller's `root` is.
    pub fn new_unrooted<T: Into<Token>>(this: Scopes, token: T) -> Self {
        let token = token.into();
        ScopeContext {
            scope_stack: vec![ScopeEntry::Scope(this, Reason::Token(token.clone()))],
            root: ScopeEntry::Scope(Scopes::all(), Reason::Token(token.clone())),
            #[cfg(feature = "hoi4")]
            from: Vec::new(),
            scope_names: TigerHashMap::default(),
            scope_list_names: TigerHashMap::default(),
            local_names: TigerHashMap::default(),
            local_list_names: TigerHashMap::default(),
            named: Vec::new(),
            is_input: Vec::new(),
            is_builder: false,
            is_unrooted: true,
            prev_levels: 0,
            strict_scopes: true,
            no_warn: false,
            source: token,
            traceback: Vec::new(),
        }
    }

    /// Make a new `ScopeContext`, with `this` and `root` unconnected
    /// and of separate scope types.
    /// `token` is used when reporting errors about the use of `this` or `root`.
    ///
    /// This function is useful in specialized contexts where the game engine
    /// provides different `this` and `root`.
    #[cfg(feature = "hoi4")]
    pub fn new_separate_root<T: Into<Token>>(root: Scopes, this: Scopes, token: T) -> Self {
        let token = token.into();
        let mut sc = ScopeContext::new(root, token.clone());
        *sc.scope_stack.last_mut().unwrap() = ScopeEntry::Scope(this, Reason::Builtin(token));
        sc
    }

    #[cfg(feature = "hoi4")]
    pub fn new_with_prev<T: Into<Token>>(root: Scopes, prev: Scopes, token: T) -> Self {
        let token = token.into();
        let mut sc = ScopeContext::new(root, token.clone());
        sc.scope_stack
            .insert(sc.scope_stack.len() - 1, ScopeEntry::Scope(prev, Reason::Token(token)));
        sc.prev_levels += 1;
        sc
    }

    /// Declare whether all the named scopes in this scope context are known. Default is true.
    ///
    /// Set this to false in for example events, which start with the scopes defined by their
    /// triggering context.
    ///
    /// Having strict scopes set to true makes the `ScopeContext` emit errors when encountering
    /// unknown scope names.
    pub fn set_strict_scopes(&mut self, strict: bool) {
        self.strict_scopes = strict;
    }

    /// Return whether this `ScopeContext` has strict scopes set to true.
    /// See [`Self::set_strict_scopes`].
    pub fn is_strict(&self) -> bool {
        self.strict_scopes
    }

    /// Set whether this `ScopeContext` should emit reports at all. `no_warn` defaults to false.
    ///
    /// It's used for scope contexts that are known to be wrong, related to the `scope_override` config file feature.
    pub fn set_no_warn(&mut self, no_warn: bool) {
        self.no_warn = no_warn;
    }

    /// Change this context's `source` value to something more appropriate than the default (which
    /// is the token passed to `new`).
    pub fn set_source<T: Into<Token>>(&mut self, source: T) {
        self.source = source.into();
    }

    /// Helper function for `root_for_event` and `root_for_action`.
    fn root_for(&self, trace: ActionOrEvent, data: &Everything) -> Option<Self> {
        if !self.strict_scopes || self.no_warn || self.traceback.contains(&trace) {
            return None;
        }
        let mut new_sc = self.clone();
        for named in &mut new_sc.named {
            if matches!(named, ScopeEntry::Rootref) {
                *named = new_sc.root.clone();
            }
        }
        #[cfg(feature = "hoi4")]
        new_sc.from.insert(0, new_sc.root.clone());
        let (scopes, reason) = new_sc.scopes_reason(data);
        new_sc.root = ScopeEntry::Scope(scopes, reason.clone());
        new_sc.scope_stack = vec![ScopeEntry::Rootref];
        new_sc.prev_levels = 0;
        new_sc.is_unrooted = false;
        new_sc.traceback.push(trace);
        new_sc.wipe_temporaries();
        Some(new_sc)
    }

    /// Create a `ScopeContext` to use for a triggered event, if validating the event with this
    /// scope context is useful.
    pub fn root_for_event<T: Into<Token>>(&self, event_id: T, data: &Everything) -> Option<Self> {
        self.root_for(ActionOrEvent::new_event(event_id.into()), data)
    }

    /// Create a `ScopeContext` to use for a triggered action, if validating the action with this
    /// scope context is useful.
    pub fn root_for_action<T: Into<Token>>(&self, action: T, data: &Everything) -> Option<Self> {
        let action = action.into();
        if self.source == action {
            return None;
        }
        self.root_for(ActionOrEvent::new_action(action), data)
    }

    pub fn wipe_temporaries(&mut self) {
        for (_, t) in self.scope_names.values_mut() {
            if *t == Temporary::Yes {
                *t = Temporary::Wiped;
            }
        }
        for (_, t) in self.scope_list_names.values_mut() {
            if *t == Temporary::Yes {
                *t = Temporary::Wiped;
            }
        }
    }

    /// Change the scope type and related token of `root` for this `ScopeContext`.
    ///
    /// This function is mainly used in the setup of a `ScopeContext` before using it.
    /// It's a bit of a hack and shouldn't be used.
    /// TODO: get rid of this.
    #[cfg(feature = "ck3")] // happens not to be used by vic3
    pub fn change_root<T: Into<Token>>(&mut self, root: Scopes, token: T) {
        self.root = ScopeEntry::Scope(root, Reason::Builtin(token.into()));
    }

    #[doc(hidden)]
    fn define_name_internal(
        &mut self,
        name: &'static str,
        scopes: Scopes,
        reason: Reason,
        temp: Temporary,
    ) {
        if let Some((idx, t)) = self.scope_names.get_mut(name) {
            *t = temp;
            let idx = *idx;
            Self::break_chains_to(&mut self.named, idx);
            self.named[idx] = ScopeEntry::Scope(scopes, reason);
        } else {
            self.scope_names.insert(name, (self.named.len(), temp));
            self.named.push(ScopeEntry::Scope(scopes, reason));
            self.is_input.push(None);
        }
    }

    /// Declare that this `ScopeContext` contains a named scope of the given name and type,
    /// supplied by the game engine.
    ///
    /// The associated `token` will be used in error reports related to this named scope.
    pub fn define_name<T: Into<Token>>(&mut self, name: &'static str, scopes: Scopes, token: T) {
        self.define_name_internal(name, scopes, Reason::Builtin(token.into()), Temporary::No);
    }

    /// Declare that this `ScopeContext` contains a named scope of the given name and type,
    /// *not* supplied by the game engine but deduced from script.
    ///
    /// The associated `token` will be used in error reports related to this named scope.
    /// The token should reflect why we think the named scope has the scope type it has.
    pub fn define_name_token<T: Into<Token>>(
        &mut self,
        name: &'static str,
        scopes: Scopes,
        token: T,
        temp: Temporary,
    ) {
        self.define_name_internal(name, scopes, Reason::Token(token.into()), temp);
    }

    /// Look up a named scope and return its scope types if it's known.
    ///
    /// Callers should probably check [`Self::is_strict()`] as well.
    pub fn is_name_defined(&mut self, name: &str, data: &Everything) -> Option<Scopes> {
        if let Some(&(idx, temp)) = self.scope_names.get(name) {
            if temp == Temporary::Wiped {
                None
            } else {
                #[allow(clippy::indexing_slicing)] // invariant guarantees no panic
                Some(match self.named[idx] {
                    ScopeEntry::Scope(s, _) => s,
                    ScopeEntry::Backref(_) => unreachable!(),
                    #[cfg(feature = "hoi4")]
                    ScopeEntry::Fromref(_) => unreachable!(),
                    ScopeEntry::Rootref => self.resolve_root().0,
                    ScopeEntry::Named(idx) => self.resolve_named(idx, data).0,
                    #[cfg(feature = "jomini")]
                    ScopeEntry::GlobalVar(name, _) => data.global_scopes.scopes(name),
                    #[cfg(feature = "jomini")]
                    ScopeEntry::GlobalList(name, _) => data.global_list_scopes.scopes(name),
                    #[cfg(feature = "jomini")]
                    ScopeEntry::Var(name, _) => data.variable_scopes.scopes(name),
                    #[cfg(feature = "jomini")]
                    ScopeEntry::VarList(name, _) => data.variable_list_scopes.scopes(name),
                })
            }
        } else {
            None
        }
    }

    /// Put a scope entry on the FROM chain. It becomes the new FROM, and the old one (if any)
    /// becomes FROM.FROM, etc.
    #[cfg(feature = "hoi4")]
    pub fn push_as_from<T: Into<Token>>(&mut self, scopes: Scopes, token: T) {
        self.from.insert(0, ScopeEntry::Scope(scopes, Reason::Builtin(token.into())));
    }

    /// This is called when the script does `exists = scope:name`.
    ///
    /// It records `name` as "known", but with no scope type information, and records that the
    /// caller is expected to provide this scope.
    ///
    /// The `ScopeContext` is not smart enough to track optionally existing scopes. It assumes
    /// that if you do `exists` on a scope, then from that point on it exists. Improving this would
    /// be a big project.
    pub fn exists_scope<T: Into<Token>>(&mut self, name: &'static str, token: T) {
        if !self.scope_names.contains_key(name) {
            let idx = self.named.len();
            self.scope_names.insert(name, (idx, Temporary::No));
            self.named.push(ScopeEntry::deduce(token));
            self.is_input.push(None);
        }
    }

    /// This is called when the script does `exists = local_var:name` or `has_local_variable = name`.
    ///
    /// It records `name` as "known", but with no scope type information, and records that the
    /// caller is expected to provide this local variable.
    pub fn exists_local<T: Into<Token>>(&mut self, name: &'static str, token: T) {
        if !self.local_names.contains_key(name) {
            self.local_names.insert(name, self.named.len());
            self.named.push(ScopeEntry::deduce(token));
            self.is_input.push(None);
        }
    }

    /// This is called when the script does `has_local_variable_list = name`.
    ///
    /// It records `name` as "known", but with no scope type information, and records that the
    /// caller is expected to provide this local variable list.
    pub fn exists_local_list<T: Into<Token>>(&mut self, name: &'static str, token: T) {
        if !self.local_list_names.contains_key(name) {
            self.local_list_names.insert(name, self.named.len());
            self.named.push(ScopeEntry::deduce(token));
            self.is_input.push(None);
        }
    }

    #[doc(hidden)]
    fn define_list_internal(
        &mut self,
        name: &'static str,
        scopes: Scopes,
        reason: Reason,
        temp: Temporary,
    ) {
        if let Some(&(idx, _)) = self.scope_list_names.get(name) {
            Self::break_chains_to(&mut self.named, idx);
            self.named[idx] = ScopeEntry::Scope(scopes, reason);
        } else {
            self.scope_list_names.insert(name, (self.named.len(), temp));
            self.named.push(ScopeEntry::Scope(scopes, reason));
            self.is_input.push(None);
        }
    }

    /// Declare that this `ScopeContext` contains a list of the given name and type,
    /// supplied by the game engine.
    ///
    /// The associated `token` will be used in error reports related to this list.
    ///
    /// Lists and named scopes exist in different namespaces, but under the hood
    /// `ScopeContext` treats them the same. This means that lists are expected to
    /// contain items of a single scope type, which sometimes leads to false positives.
    pub fn define_list<T: Into<Token>>(&mut self, name: &'static str, scopes: Scopes, token: T) {
        self.define_list_internal(name, scopes, Reason::Builtin(token.into()), Temporary::No);
    }

    /// This is like [`Self::define_name()`], but `scope:name` is declared equal to the current `this`.
    pub fn save_current_scope(&mut self, name: &'static str, temp: Temporary) {
        if let Some((idx, t)) = self.scope_names.get_mut(name) {
            *t = temp;
            let idx = *idx;
            Self::break_chains_to(&mut self.named, idx);
            let entry = self.resolve_backrefs(THIS);
            // Guard against `scope:foo = { save_scope_as = foo }`
            if let ScopeEntry::Named(i) = entry {
                if *i == idx {
                    // Leave the scope as its original value
                    return;
                }
            }
            self.named[idx] = entry.clone();
        } else {
            self.scope_names.insert(name, (self.named.len(), temp));
            self.named.push(self.resolve_backrefs(THIS).clone());
            self.is_input.push(None);
        }
    }

    /// Sets a local variable to the provided scope type
    #[cfg(feature = "jomini")]
    pub fn set_local_variable(&mut self, name: &Token, scope: Scopes) {
        if let Some(&idx) = self.local_names.get(name.as_str()) {
            Self::break_chains_to(&mut self.named, idx);
            self.named[idx] = ScopeEntry::Scope(scope, Reason::Token(name.clone()));
        } else {
            self.local_names.insert(name.as_str(), self.named.len());
            self.named.push(ScopeEntry::Scope(scope, Reason::Token(name.clone())));
            self.is_input.push(None);
        }
    }

    /// If list `name` exists, narrow its scope type down to `this` and narrow the `this` scope
    /// types down to the existing list.
    /// Otherwise, define it as having the same scope type as `this`.
    pub fn define_or_expect_list_this(&mut self, name: &Token, data: &Everything, temp: Temporary) {
        if let Some((idx, t)) = self.scope_list_names.get_mut(name.as_str()) {
            *t = temp;
            let idx = *idx;
            // TODO: remove need to clone reason
            let (s, reason) = self.resolve_named(idx, data);
            self.expect(s, &reason.clone(), data);
            let (s, reason) = self.scopes_reason(data);
            let reason = reason.clone();
            self.expect_named(idx, s, &reason, data);
            // It often happens that an iterator does is_in_list before add_to_list,
            // and in those cases we want the add_to_list to take precedence: conclude that the
            // list is being built here, and isn't an input list.
            self.is_input[idx] = None;
        } else {
            self.scope_list_names.insert(name.as_str(), (self.named.len(), temp));
            self.named.push(self.resolve_backrefs(THIS).clone());
            self.is_input.push(None);
        }
    }

    /// If list `name` exists, narrow its scope type down to the given scopes.
    /// Otherwise, define it as having the given scopes.
    #[allow(dead_code)]
    pub fn define_or_expect_list(
        &mut self,
        name: &Token,
        scope: Scopes,
        data: &Everything,
        temp: Temporary,
    ) {
        if let Some((idx, t)) = self.scope_list_names.get_mut(name.as_str()) {
            *t = temp;
            let idx = *idx;
            self.expect_named(idx, scope, &Reason::Token(name.clone()), data);
            // It often happens that an iterator does is_in_list before add_to_list,
            // and in those cases we want the add_to_list to take precedence: conclude that the
            // list is being built here, and isn't an input list.
            self.is_input[idx] = None;
        } else {
            self.scope_list_names.insert(name.as_str(), (self.named.len(), temp));
            self.named.push(ScopeEntry::Scope(scope, Reason::Token(name.clone())));
            self.is_input.push(None);
        }
    }

    /// If local variable list `name` exists, narrow its scope type down to the given scopes.
    /// Otherwise, define it as having the given scopes.
    pub fn define_or_expect_local_list(&mut self, name: &Token, scope: Scopes, data: &Everything) {
        if let Some(&idx) = self.local_list_names.get(name.as_str()) {
            self.expect_named(idx, scope, &Reason::Token(name.clone()), data);
            // It often happens that an iterator does is_in_list before add_to_list,
            // and in those cases we want the add_to_list to take precedence: conclude that the
            // list is being built here, and isn't an input list.
            self.is_input[idx] = None;
        } else {
            self.local_list_names.insert(name.as_str(), self.named.len());
            self.named.push(ScopeEntry::Scope(scope, Reason::Token(name.clone())));
            self.is_input.push(None);
        }
    }

    /// Expect list `name` to be known and (with strict scopes) warn if it isn't.
    /// Narrow the type of `this` down to the list's type.
    pub fn expect_list(&mut self, name: &Token, data: &Everything) {
        if let Some((idx, t)) = self.scope_list_names.get(name.as_str()) {
            if *t == Temporary::Wiped {
                let msg = format!("list `{name}` was temporary and is no longer available here");
                err(ErrorKey::TemporaryScope).weak().msg(msg).loc(name).push();
            } else {
                let (s, reason) = self.resolve_named(*idx, data);
                let reason = reason.clone(); // TODO: remove need to clone
                self.expect3(s, &reason, name, THIS, "list", data);
            }
        } else if self.strict_scopes {
            let msg = "unknown list";
            err(ErrorKey::UnknownList).weak().msg(msg).loc(name).push();
        }
    }

    /// Expect local variable list `name` to be known and (with strict scopes) warn if it isn't.
    /// Narrow the type of `this` down to the list's type.
    #[cfg(feature = "jomini")]
    pub fn expect_local_list(&mut self, name: &Token, data: &Everything) {
        if let Some(&idx) = self.local_list_names.get(name.as_str()) {
            let (s, reason) = self.resolve_named(idx, data);
            let reason = reason.clone(); // TODO: remove need to clone
            self.expect3(s, &reason, name, THIS, "local variable list", data);
        } else if self.strict_scopes {
            let msg = "unknown local variable list";
            err(ErrorKey::UnknownList).weak().msg(msg).loc(name).push();
        }
    }

    /// Expect local variable `name` to be known and (with strict scopes) warn if it isn't.
    #[cfg(feature = "jomini")]
    pub fn expect_local(&mut self, name: &Token, scope: Scopes, data: &Everything) {
        if let Some(&idx) = self.local_names.get(name.as_str()) {
            self.expect_named(idx, scope, &Reason::Token(name.clone()), data);
        } else if self.strict_scopes {
            let msg = "unknown local variable";
            err(ErrorKey::UnknownVariable).msg(msg).loc(name).push();
        }
    }

    /// Cut `idx` out of any [`ScopeEntry::Named`] chains. This avoids infinite loops.
    #[doc(hidden)]
    fn break_chains_to(named: &mut [ScopeEntry], idx: usize) {
        for i in 0..named.len() {
            if i == idx {
                continue;
            }
            if let ScopeEntry::Named(ni) = named[i] {
                if ni == idx {
                    named[i] = named[idx].clone();
                }
            }
        }
    }

    /// Open a new scope level of `scopes` scope type. Record `token` as the reason for this type.
    ///
    /// This is mostly used by iterators.
    /// `prev` will refer to the previous scope level.
    pub fn open_scope(&mut self, scopes: Scopes, token: Token) {
        self.scope_stack.push(ScopeEntry::Scope(scopes, Reason::Token(token)));
    }

    /// Open a new, temporary scope level. Initially it will have its `this` the same as the
    /// previous level's `this`.
    ///
    /// The purpose is to handle scope chains like `root.liege.primary_title`. Call the `replace_`
    /// functions to update the value of `this`, and at the end either confirm the new scope level
    /// with [`Self::finalize_builder()`] or discard it with [`Self::close()`].
    pub fn open_builder(&mut self) {
        self.scope_stack.push(ScopeEntry::Backref(THIS));
        self.is_builder = true;
    }

    #[cfg(any(feature = "ck3", feature = "vic3", feature = "eu5"))]
    pub fn stash_builder(&mut self) -> StashedBuilder {
        let stash = StashedBuilder { this: self.scope_stack.pop().unwrap() };
        self.is_builder = false;
        stash
    }

    #[cfg(any(feature = "ck3", feature = "vic3", feature = "eu5"))]
    pub fn unstash_builder(&mut self, stash: StashedBuilder) {
        self.scope_stack.push(stash.this);
        self.is_builder = true;
    }

    /// Declare that the temporary scope level opened with [`Self::open_builder()`] is a real scope level.
    pub fn finalize_builder(&mut self) {
        self.is_builder = false;
    }

    /// Exit a scope level and return to the previous level.
    pub fn close(&mut self) {
        self.scope_stack.pop().expect("matching open and close scopes");
        self.is_builder = false;
    }

    /// Return an object that captures the essentials of this `ScopeContext`, to be used for
    /// hashing.
    pub fn signature(&self, data: &Everything) -> Signature {
        fn process_scope_names(
            sc: &ScopeContext,
            names: &TigerHashMap<&'static str, (usize, Temporary)>,
            data: &Everything,
        ) -> Vec<(&'static str, Scopes)> {
            let mut names: Vec<_> = names
                .iter()
                .filter(|(_, (_, temp))| *temp != Temporary::Wiped)
                .map(|(&name, (i, _))| (name, sc.resolve_named(*i, data).0))
                .collect();
            names.sort_by(|(name1, _), (name2, _)| name1.cmp(name2));
            names
        }

        fn process_local_names(
            sc: &ScopeContext,
            names: &TigerHashMap<&'static str, usize>,
            data: &Everything,
        ) -> Vec<(&'static str, Scopes)> {
            let mut names: Vec<_> =
                names.iter().map(|(&name, &i)| (name, sc.resolve_named(i, data).0)).collect();
            names.sort_by(|(name1, _), (name2, _)| name1.cmp(name2));
            names
        }

        let root = self.resolve_root().0;

        Signature {
            root,
            scope_names: process_scope_names(self, &self.scope_names, data),
            scope_list_names: process_scope_names(self, &self.scope_list_names, data),
            local_names: process_local_names(self, &self.local_names, data),
            local_list_names: process_local_names(self, &self.local_list_names, data),
        }
    }

    /// Replace the `this` in a temporary scope level with the given `scopes` type and record
    /// `token` as the reason for this type.
    ///
    /// This is used when a scope chain starts with something absolute like `faith:catholic`.
    pub fn replace(&mut self, scopes: Scopes, token: Token) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::Scope(scopes, Reason::Token(token));
    }

    /// Replace the `this` in a temporary scope level with a reference to `root`.
    pub fn replace_root(&mut self) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::Rootref;
    }

    /// Replace the `this` in a temporary scope level with a reference to the previous scope level.
    pub fn replace_prev(&mut self) {
        let this = self.scope_stack.last_mut().unwrap();
        let backref = if Game::is_imperator() || Game::is_hoi4() {
            // Allow `prev.prev` etc
            match this {
                ScopeEntry::Backref(r) => *r + 1,
                _ => PREV,
            }
        } else {
            PREV
        };
        *this = ScopeEntry::Backref(backref);
        while 1 + backref > self.scope_stack.len() {
            // We went further back up the scope chain than we know about.
            let entry = if self.is_unrooted {
                ScopeEntry::Scope(Scopes::all(), Reason::Token(self.source.clone()))
            } else {
                ScopeEntry::Scope(Scopes::None, Reason::Builtin(self.source.clone()))
            };
            self.scope_stack.insert(0, entry);
            self.prev_levels += 1;
        }
    }

    /// Replace the `this` in a temporary scope level with a reference to its previous event root.
    #[cfg(feature = "hoi4")]
    pub fn replace_from(&mut self) {
        let this = self.scope_stack.last_mut().unwrap();
        match this {
            ScopeEntry::Fromref(r) => *this = ScopeEntry::Fromref(*r + 1),
            _ => *this = ScopeEntry::Fromref(0),
        }
    }

    /// Replace the `this` in a temporary scope level with a reference to the real level below it.
    ///
    /// This is usually a no-op, used when scope chains start with `this`. If a scope chain has
    /// `this` in the middle of the chain (which itself will trigger a warning) then it resets the
    /// temporary scope level to the way it started.
    pub fn replace_this(&mut self) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::Backref(THIS);
    }

    /// Replace the `this` in a temporary scope level with a reference to the named scope `name`.
    ///
    /// This is used when a scope chain starts with `scope:name`. The `token` is expected to be the
    /// `scope:name` token.
    pub fn replace_named_scope(&mut self, name: &'static str, token: &Token) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::Named(self.named_index(name, token));
    }

    /// Replace the `this` in a temporary scope level with a reference to the local variable `name`.
    ///
    /// This is used when a scope chain starts with `local_var:name`. The `token` is expected to be the
    /// `local_var:name` token.
    pub fn replace_local_variable(&mut self, name: &'static str, token: &Token) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::Named(self.local_index(name, token));
    }

    /// Replace the `this` in a temporary scope level with a reference to the global variable `name`.
    ///
    /// This is used when a scope chain starts with `global_var:name`. The `token` is expected to be the
    /// `global_var:name` token.
    #[cfg(feature = "jomini")]
    pub fn replace_global_variable(&mut self, name: &'static str, token: &Token) {
        *self.scope_stack.last_mut().unwrap() =
            ScopeEntry::GlobalVar(name, Reason::VariableReference(token.clone(), "global_var:"));
    }

    /// Replace the `this` in a temporary scope level with a reference to the variable `name`.
    ///
    /// This is used when a scope chain starts with `var:name`. The `token` is expected to be the
    /// `var:name` token.
    #[cfg(feature = "jomini")]
    pub fn replace_variable(&mut self, name: &'static str, token: &Token) {
        *self.scope_stack.last_mut().unwrap() =
            ScopeEntry::Var(name, Reason::VariableReference(token.clone(), "var:"));
    }

    /// Replace the `this` in a temporary scope level with a reference to the scope type of the
    /// list `name`.
    #[cfg(feature = "jomini")]
    pub fn replace_list_entry(&mut self, name: &Token) {
        *self.scope_stack.last_mut().unwrap() =
            ScopeEntry::Named(self.named_list_index(name.as_str(), name));
    }

    /// Replace the `this` in a temporary scope level with a reference to the scope type of the
    /// local variable list `name`.
    #[cfg(feature = "jomini")]
    pub fn replace_local_list_entry(&mut self, name: &Token) {
        *self.scope_stack.last_mut().unwrap() =
            ScopeEntry::Named(self.local_list_index(name.as_str(), name));
    }

    /// Replace the `this` in a temporary scope level with a reference to the scope type of the
    /// global variable list `name`.
    #[cfg(feature = "jomini")]
    pub fn replace_global_list_entry(&mut self, name: &Token) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::GlobalList(
            name.as_str(),
            Reason::VariableReference(name.clone(), "global list "),
        );
    }

    /// Replace the `this` in a temporary scope level with a reference to the scope type of the
    /// variable list `name`.
    #[cfg(feature = "jomini")]
    pub fn replace_variable_list_entry(&mut self, name: &Token) {
        *self.scope_stack.last_mut().unwrap() = ScopeEntry::VarList(
            name.as_str(),
            Reason::VariableReference(name.clone(), "variable list "),
        );
    }

    /// Get the internal index of named scope `name`, either its existing index or a newly created one.
    ///
    /// If a new index has to be created, and `strict_scopes` is on, then a warning will be emitted.
    #[doc(hidden)]
    fn named_index(&mut self, name: &'static str, token: &Token) -> usize {
        if let Some(&(idx, t)) = self.scope_names.get(name) {
            if t == Temporary::Wiped {
                let msg = format!("`scope:{name}` was temporary and is no longer available here");
                self.log_traceback(err(ErrorKey::TemporaryScope).weak().msg(msg).loc(token)).push();
            }
            idx
        } else {
            let idx = self.named.len();
            self.named.push(ScopeEntry::deduce(token));
            if self.strict_scopes {
                if !self.no_warn {
                    let msg = format!("scope:{name} might not be available here");
                    let mut builder = err(ErrorKey::StrictScopes).weak().msg(msg);
                    if self.scope_names.len() <= MAX_SCOPE_NAME_LIST && !self.scope_names.is_empty()
                    {
                        let mut names: Vec<_> = self.scope_names.keys().copied().collect();
                        names.sort_unstable();
                        let info = format!("available names are {}", stringify_choices(&names));
                        builder = builder.info(info);
                    }
                    self.log_traceback(builder.loc(token)).push();
                }
                // Don't treat it as an input scope, because we already warned about it
                self.is_input.push(None);
            } else {
                self.is_input.push(Some(token.clone()));
            }
            // do this after the warnings above, so that it's not listed as available
            self.scope_names.insert(name, (idx, Temporary::No));
            idx
        }
    }

    /// Get the internal index of local variable `name`, either its existing index or a newly created one.
    ///
    /// If a new index has to be created, and `strict_scopes` is on, then a warning will be emitted.
    #[doc(hidden)]
    fn local_index(&mut self, name: &'static str, token: &Token) -> usize {
        if let Some(&idx) = self.local_names.get(name) {
            idx
        } else {
            let idx = self.named.len();
            self.named.push(ScopeEntry::deduce(token));
            if self.strict_scopes {
                if !self.no_warn {
                    let msg = format!("local_var:{name} might not be available here");
                    let mut builder = err(ErrorKey::StrictScopes).weak().msg(msg);
                    if self.local_names.len() <= MAX_SCOPE_NAME_LIST && !self.local_names.is_empty()
                    {
                        let mut names: Vec<_> = self.local_names.keys().copied().collect();
                        names.sort_unstable();
                        let info = format!("available names are {}", stringify_choices(&names));
                        builder = builder.info(info);
                    }
                    self.log_traceback(builder.loc(token)).push();
                }
                // Don't treat it as an input scope, because we already warned about it
                self.is_input.push(None);
            } else {
                self.is_input.push(Some(token.clone()));
            }
            // do this after the warnings above, so that it's not listed as available
            self.local_names.insert(name, idx);
            idx
        }
    }

    /// Same as [`Self::named_index()`], but for lists. No warning is emitted if a new list is created.
    /// Do warn if a temporary list was used after it was wiped.
    #[doc(hidden)]
    #[cfg(feature = "jomini")]
    fn named_list_index(&mut self, name: &'static str, token: &Token) -> usize {
        if let Some(&(idx, t)) = self.scope_list_names.get(name) {
            if t == Temporary::Wiped {
                let msg = format!("list `{name}` was temporary and is no longer available here");
                self.log_traceback(err(ErrorKey::TemporaryScope).weak().msg(msg).loc(token)).push();
            }
            idx
        } else {
            let idx = self.named.len();
            self.scope_list_names.insert(name, (idx, Temporary::No));
            self.named.push(ScopeEntry::Scope(Scopes::all(), Reason::Token(token.clone())));
            self.is_input.push(Some(token.clone()));
            idx
        }
    }

    /// Same as [`Self::named_index()`], but for local variable lists.
    /// No warning is emitted if a new list is created.
    #[doc(hidden)]
    #[cfg(feature = "jomini")]
    fn local_list_index(&mut self, name: &'static str, token: &Token) -> usize {
        if let Some(&idx) = self.local_list_names.get(name) {
            idx
        } else {
            let idx = self.named.len();
            self.local_list_names.insert(name, idx);
            self.named.push(ScopeEntry::Scope(Scopes::all(), Reason::Token(token.clone())));
            self.is_input.push(Some(token.clone()));
            idx
        }
    }

    /// Return true iff it's possible that `this` is the same type as one of the `scopes` types.
    pub fn can_be(&self, scopes: Scopes, data: &Everything) -> bool {
        self.scopes(data).intersects(scopes)
    }

    /// Return the possible scope types of this scope level.
    // TODO: maybe specialize this function for performance?
    pub fn scopes(&self, data: &Everything) -> Scopes {
        self.scopes_reason(data).0
    }

    /// Return the possible scope types of this local variable.
    #[cfg(feature = "jomini")]
    pub fn local_variable_scopes(&self, name: &str, data: &Everything) -> Scopes {
        if let Some(idx) = self.local_names.get(name).copied() {
            self.resolve_named(idx, data).0
        } else {
            Scopes::all_but_none()
        }
    }

    /// Return the possible scope types of this local variable list.
    pub fn local_list_scopes(&self, name: &str, data: &Everything) -> Scopes {
        if let Some(idx) = self.local_list_names.get(name).copied() {
            self.resolve_named(idx, data).0
        } else {
            Scopes::all_but_none()
        }
    }

    #[cfg(feature = "vic3")]
    pub fn get_multiplier_context(&self, key: &Token) -> Self {
        let scopes = self.resolve_root().0;
        let mut sc = ScopeContext::new(scopes, key);
        sc.root = ScopeEntry::Scope(scopes, Reason::MultiplierBug(key.clone()));
        sc
    }

    /// Return the possible scope types of `root`, and the reason why we think it has those types
    fn resolve_root(&self) -> (Scopes, &Reason) {
        match self.root {
            ScopeEntry::Scope(s, ref reason) => (s, reason),
            _ => unreachable!(),
        }
    }

    /// Return the possible scope types of a named scope or list, and the reason why we think it
    /// has those types.
    ///
    /// The `idx` must be an index from the `names` or `list_names` vectors.
    #[doc(hidden)]
    #[allow(clippy::only_used_in_recursion)] // hoi4 doesn't use data
    fn resolve_named(&self, idx: usize, data: &Everything) -> (Scopes, &Reason) {
        #[allow(clippy::indexing_slicing)]
        match self.named[idx] {
            ScopeEntry::Scope(s, ref reason) => (s, reason),
            ScopeEntry::Rootref => self.resolve_root(),
            ScopeEntry::Named(idx) => self.resolve_named(idx, data),
            ScopeEntry::Backref(_) => unreachable!(),
            #[cfg(feature = "hoi4")]
            ScopeEntry::Fromref(_) => unreachable!(),
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(name, ref reason) => (data.global_scopes.scopes(name), reason),
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalList(name, ref reason) => {
                (data.global_list_scopes.scopes(name), reason)
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::Var(name, ref reason) => (data.variable_scopes.scopes(name), reason),
            #[cfg(feature = "jomini")]
            ScopeEntry::VarList(name, ref reason) => {
                (data.variable_list_scopes.scopes(name), reason)
            }
        }
    }

    /// Search through the scope levels to find out what a scope actually refers to.
    /// Pass 1 for `back` to examine the `this` scope.
    ///
    /// The returned `ScopeEntry` will not be a `ScopeEntry::Backref`.
    #[doc(hidden)]
    fn resolve_backrefs(&self, mut back: usize) -> &ScopeEntry {
        loop {
            // SAFETY: `replace_prev` ensures that when backrefs are added, enough scope
            // stack entries are added too.
            assert!(back > 0);
            assert!(back <= self.scope_stack.len());
            let entry = &self.scope_stack[self.scope_stack.len() - back];
            match entry {
                ScopeEntry::Backref(r) => back += *r,
                _ => {
                    return entry;
                }
            }
        }
    }

    /// Search through the scope levels to find out what a scope actually refers to.
    /// Pass 1 for `back` to examine the `this` scope.
    ///
    /// The returned `ScopeEntry` will not be a `ScopeEntry::Backref`.
    #[doc(hidden)]
    fn resolve_backrefs_mut(&mut self, mut back: usize) -> &mut ScopeEntry {
        // TODO: can the duplication with resolve_backrefs be avoided?
        loop {
            // SAFETY: `replace_prev` ensures that when backrefs are added, enough scope
            // stack entries are added too.
            assert!(back > 0);
            assert!(back <= self.scope_stack.len());
            let idx = self.scope_stack.len() - back;
            match self.scope_stack[idx] {
                ScopeEntry::Backref(r) => back += r,
                _ => {
                    return &mut self.scope_stack[idx];
                }
            }
        }
    }

    /// Return the possible scope types for the current scope layer, together with the reason why
    /// we think that.
    pub fn scopes_reason(&self, data: &Everything) -> (Scopes, &Reason) {
        self.scopes_reason_backref(THIS, data)
    }

    /// Return the possible scope types for a `from` entry, together with the reason why we think
    /// that.
    #[cfg(feature = "hoi4")]
    #[doc(hidden)]
    fn resolve_from(&self, back: usize) -> (Scopes, &Reason) {
        match self.from.get(back) {
            None => {
                // We went further up the FROM chain than we know about.
                let scopes = if self.strict_scopes { Scopes::None } else { Scopes::all() };
                // just nab the `reason` from root
                match self.root {
                    ScopeEntry::Scope(_, ref reason) => (scopes, reason),
                    _ => unreachable!(),
                }
            }
            Some(ScopeEntry::Scope(s, reason)) => (*s, reason),
            Some(_) => unreachable!(),
        }
    }

    #[doc(hidden)]
    fn scopes_reason_backref(&self, back: usize, data: &Everything) -> (Scopes, &Reason) {
        match self.resolve_backrefs(back) {
            ScopeEntry::Scope(s, reason) => (*s, reason),
            ScopeEntry::Backref(_) => unreachable!(),
            #[cfg(feature = "hoi4")]
            ScopeEntry::Fromref(r) => self.resolve_from(*r),
            ScopeEntry::Rootref => self.resolve_root(),
            ScopeEntry::Named(idx) => self.resolve_named(*idx, data),
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(name, reason) => (data.global_scopes.scopes(name), reason),
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalList(name, reason) => (data.global_list_scopes.scopes(name), reason),
            #[cfg(feature = "jomini")]
            ScopeEntry::Var(name, reason) => (data.variable_scopes.scopes(name), reason),
            #[cfg(feature = "jomini")]
            ScopeEntry::VarList(name, reason) => (data.variable_list_scopes.scopes(name), reason),
        }
    }

    /// Add messages to a report that describe where this `ScopeContext` came from.
    pub fn log_traceback(&self, mut builder: ReportBuilderFull) -> ReportBuilderFull {
        for elem in self.traceback.iter().rev() {
            builder = builder.loc_msg(elem.token(), "triggered from here");
        }
        builder.loc_msg(&self.source, "scopes initialized here")
    }

    #[doc(hidden)]
    #[allow(unused_variables)] // hoi4 does not use data
    fn expect_check(e: &mut ScopeEntry, scopes: Scopes, reason: &Reason, data: &Everything) {
        match e {
            ScopeEntry::Scope(s, r) => {
                if s.intersects(scopes) {
                    // if s is narrowed by the scopes info, remember why
                    if (*s & scopes) != *s {
                        *s &= scopes;
                        *r = reason.clone();
                    }
                } else {
                    let token = reason.token();
                    let msg = format!("`{token}` is for {scopes} but scope seems to be {s}");
                    let msg2 = format!("scope was {}", r.msg());
                    warn(ErrorKey::Scopes).msg(msg).loc(token).loc_msg(r.token(), msg2).push();
                }
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(name, reason) => {
                data.global_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalList(name, reason) => {
                data.global_list_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::Var(name, reason) => {
                data.variable_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::VarList(name, reason) => {
                data.variable_list_scopes.expect(name, reason.token(), scopes);
            }
            _ => unreachable!(),
        }
    }

    #[doc(hidden)]
    #[allow(unused_variables)] // hoi4 does not use data
    fn expect_check3(
        e: &mut ScopeEntry,
        scopes: Scopes,
        reason: &Reason,
        key: &Token,
        report: &str,
        data: &Everything,
    ) {
        match e {
            ScopeEntry::Scope(s, r) => {
                if s.intersects(scopes) {
                    // if s is narrowed by the scopes info, remember its token
                    if (*s & scopes) != *s {
                        *s &= scopes;
                        *r = reason.clone();
                    }
                } else {
                    let msg = format!(
                        "`{key}` expects {report} to be {scopes} but {report} seems to be {s}"
                    );
                    let msg2 = format!("expected {report} was {}", reason.msg());
                    let msg3 = format!("actual {report} was {}", r.msg());
                    warn(ErrorKey::Scopes)
                        .msg(msg)
                        .loc(key)
                        .loc_msg(reason.token(), msg2)
                        .loc_msg(r.token(), msg3)
                        .push();
                }
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(name, reason) => {
                data.global_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalList(name, reason) => {
                data.global_list_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::Var(name, reason) => {
                data.variable_scopes.expect(name, reason.token(), scopes);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::VarList(name, reason) => {
                data.variable_list_scopes.expect(name, reason.token(), scopes);
            }
            _ => unreachable!(),
        }
    }

    #[doc(hidden)]
    #[cfg(feature = "hoi4")]
    fn expect_fromref(&mut self, idx: usize, scopes: Scopes, reason: &Reason, data: &Everything) {
        if idx < self.from.len() {
            Self::expect_check(&mut self.from[idx], scopes, reason, data);
        }
    }

    #[doc(hidden)]
    #[cfg(feature = "hoi4")]
    fn expect_fromref3(
        &mut self,
        idx: usize,
        scopes: Scopes,
        reason: &Reason,
        key: &Token,
        report: &str,
        data: &Everything,
    ) {
        if idx < self.from.len() {
            Self::expect_check3(&mut self.from[idx], scopes, reason, key, report, data);
        }
    }

    // TODO: find a way to report the chain of Named tokens to the user
    #[doc(hidden)]
    fn expect_named(&mut self, mut idx: usize, scopes: Scopes, reason: &Reason, data: &Everything) {
        loop {
            #[allow(clippy::indexing_slicing)]
            match self.named[idx] {
                ScopeEntry::Scope(_, _) => {
                    Self::expect_check(&mut self.named[idx], scopes, reason, data);
                    return;
                }
                ScopeEntry::Rootref => {
                    Self::expect_check(&mut self.root, scopes, reason, data);
                    return;
                }
                ScopeEntry::Named(i) => idx = i,
                ScopeEntry::Backref(_) => unreachable!(),
                #[cfg(feature = "hoi4")]
                ScopeEntry::Fromref(_) => unreachable!(),
                #[cfg(feature = "jomini")]
                ScopeEntry::GlobalVar(_, _)
                | ScopeEntry::GlobalList(_, _)
                | ScopeEntry::Var(_, _)
                | ScopeEntry::VarList(_, _) => {
                    Self::expect_check(&mut self.named[idx], scopes, reason, data);
                    return;
                }
            }
        }
    }

    #[doc(hidden)]
    fn expect_named3(
        &mut self,
        mut idx: usize,
        scopes: Scopes,
        reason: &Reason,
        key: &Token,
        report: &str,
        data: &Everything,
    ) {
        loop {
            #[allow(clippy::indexing_slicing)]
            match self.named[idx] {
                ScopeEntry::Scope(_, _) => {
                    Self::expect_check3(&mut self.named[idx], scopes, reason, key, report, data);
                    return;
                }
                ScopeEntry::Rootref => {
                    Self::expect_check3(&mut self.root, scopes, reason, key, report, data);
                    return;
                }
                ScopeEntry::Named(i) => idx = i,
                ScopeEntry::Backref(_) => unreachable!(),
                #[cfg(feature = "hoi4")]
                ScopeEntry::Fromref(_) => unreachable!(),
                #[cfg(feature = "jomini")]
                ScopeEntry::GlobalVar(_, _)
                | ScopeEntry::GlobalList(_, _)
                | ScopeEntry::Var(_, _)
                | ScopeEntry::VarList(_, _) => {
                    Self::expect_check3(&mut self.named[idx], scopes, reason, key, report, data);
                    return;
                }
            }
        }
    }

    /// Record that the `this` in the current scope level is one of the scope types `scopes`, and
    /// if this is new information, record `token` as the reason we think that.
    /// Emit an error if what we already know about `this` is incompatible with `scopes`.
    pub fn expect(&mut self, scopes: Scopes, reason: &Reason, data: &Everything) {
        // The None scope is special, it means the scope isn't used or inspected
        if self.no_warn || scopes == Scopes::None {
            return;
        }
        let this = self.resolve_backrefs_mut(THIS);
        match this {
            ScopeEntry::Scope(_, _) => Self::expect_check(this, scopes, reason, data),
            ScopeEntry::Backref(_) => unreachable!(),
            #[cfg(feature = "hoi4")]
            &mut ScopeEntry::Fromref(r) => self.expect_fromref(r, scopes, reason, data),
            ScopeEntry::Rootref => Self::expect_check(&mut self.root, scopes, reason, data),
            &mut ScopeEntry::Named(idx) => self.expect_named(idx, scopes, reason, data),
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(_, _)
            | ScopeEntry::GlobalList(_, _)
            | ScopeEntry::Var(_, _)
            | ScopeEntry::VarList(_, _) => Self::expect_check(this, scopes, reason, data),
        }
    }

    /// Like [`Self::expect()`], but the error emitted will be located at token `key`.
    ///
    /// This function is used when the expectation of scope compatibility comes from `key`, for
    /// example when matching up a caller's scope context with a scripted effect's scope context.
    fn expect3(
        &mut self,
        scopes: Scopes,
        reason: &Reason,
        key: &Token,
        back: usize,
        report: &str,
        data: &Everything,
    ) {
        // The None scope is special, it means the scope isn't used or inspected
        if scopes == Scopes::None {
            return;
        }
        let this = self.resolve_backrefs_mut(back);
        match this {
            ScopeEntry::Scope(_, _) => Self::expect_check3(this, scopes, reason, key, report, data),
            ScopeEntry::Backref(_) => unreachable!(),
            #[cfg(feature = "hoi4")]
            &mut ScopeEntry::Fromref(r) => {
                self.expect_fromref3(r, scopes, reason, key, report, data);
            }
            ScopeEntry::Rootref => {
                Self::expect_check3(&mut self.root, scopes, reason, key, report, data);
            }
            &mut ScopeEntry::Named(idx) => {
                self.expect_named3(idx, scopes, reason, key, report, data);
            }
            #[cfg(feature = "jomini")]
            ScopeEntry::GlobalVar(_, _)
            | ScopeEntry::GlobalList(_, _)
            | ScopeEntry::Var(_, _)
            | ScopeEntry::VarList(_, _) => {
                Self::expect_check3(this, scopes, reason, key, report, data);
            }
        }
    }

    /// Compare this scope context to `other`, with `key` as the token that identifies `other`.
    ///
    /// This function examines the `root`, `this`, `prev`, and named scopes of the two scope
    /// contexts and warns about any contradictions it finds.
    ///
    /// It expects `self` to be the caller and `other` to be the callee.
    pub fn expect_compatibility(&mut self, other: &ScopeContext, key: &Token, data: &Everything) {
        if self.no_warn {
            return;
        }
        // Compare restrictions on `root`
        match other.root {
            ScopeEntry::Scope(scopes, ref token) => {
                Self::expect_check3(&mut self.root, scopes, token, key, "root", data);
            }
            _ => unreachable!(),
        }

        // Compare restrictions on `this`
        let (scopes, reason) = other.scopes_reason(data);
        self.expect3(scopes, reason, key, THIS, "scope", data);

        // Compare restrictions on `prev`
        // TODO: for imperator and hoi4, go multiple prev levels back
        // TODO: The self.prev_levels > 0 check isn't right. Instead, create enough prev levels.
        if other.prev_levels > 0 && self.prev_levels > 0 {
            let (scopes, reason) = other.scopes_reason_backref(PREV, data);
            self.expect3(scopes, reason, key, PREV + usize::from(self.is_builder), "prev", data);
        }

        // Compare restrictions on `from`
        // TODO: go all the way back up the chains
        #[cfg(feature = "hoi4")]
        {
            let (scopes, reason) = other.resolve_from(0);
            self.expect_fromref3(0, scopes, reason, key, "from", data);
            let (scopes, reason) = other.resolve_from(1);
            self.expect_fromref3(1, scopes, reason, key, "from.from", data);
        }

        // Compare restrictions on named scopes
        for (name, &(oidx, otemp)) in &other.scope_names {
            if let Some((idx, t)) = self.scope_names.get(name).copied() {
                let (s, reason) = other.resolve_named(oidx, data);
                if other.is_input[oidx].is_some() {
                    let report = format!("scope:{name}");
                    if t == Temporary::Wiped {
                        let msg = format!(
                            "`{key}` expects {report} to be set but {report} was temporary and is no longer available here"
                        );
                        err(ErrorKey::TemporaryScope).weak().msg(msg).loc(key).push();
                    }
                    self.expect_named3(idx, s, reason, key, &report, data);
                } else {
                    // Their scopes now become our scopes.
                    self.scope_names.get_mut(name).unwrap().1 = otemp;
                    Self::break_chains_to(&mut self.named, idx);
                    self.named[idx] = ScopeEntry::Scope(s, reason.clone());
                }
            } else if self.strict_scopes && other.is_input[oidx].is_some() {
                let token = other.is_input[oidx].as_ref().unwrap();
                let msg = format!("`{key}` expects scope:{name} to be set");
                let msg2 = "here";
                self.log_traceback(
                    warn(ErrorKey::StrictScopes).msg(msg).loc(key).loc_msg(token, msg2),
                )
                .push();
            } else {
                // Their scopes now become our scopes.
                let (s, reason) = other.resolve_named(oidx, data);
                self.scope_names.insert(name, (self.named.len(), otemp));
                self.named.push(ScopeEntry::Scope(s, reason.clone()));
                self.is_input.push(other.is_input[oidx].clone());
            }
        }

        // Compare restrictions on lists
        for (name, &(oidx, otemp)) in &other.scope_list_names {
            if let Some((idx, t)) = self.scope_list_names.get(name).copied() {
                let (s, reason) = other.resolve_named(oidx, data);
                if other.is_input[oidx].is_some() {
                    let report = format!("list {name}");
                    if t == Temporary::Wiped {
                        let msg = format!(
                            "`{key}` expects {report} to be set but {report} was temporary and is no longer available here"
                        );
                        err(ErrorKey::TemporaryScope).weak().msg(msg).loc(key).push();
                    }
                    self.expect_named3(idx, s, reason, key, &report, data);
                } else {
                    // Their lists now become our lists.
                    self.scope_list_names.get_mut(name).unwrap().1 = otemp;
                    Self::break_chains_to(&mut self.named, idx);
                    self.named[idx] = ScopeEntry::Scope(s, reason.clone());
                }
            } else if self.strict_scopes && other.is_input[oidx].is_some() {
                let token = other.is_input[oidx].as_ref().unwrap();
                let msg = format!("`{key}` expects list {name} to exist");
                let msg2 = "here";
                self.log_traceback(
                    warn(ErrorKey::StrictScopes).msg(msg).loc(key).loc_msg(token, msg2),
                )
                .push();
            } else {
                // Their lists now become our lists.
                let (s, reason) = other.resolve_named(oidx, data);
                self.scope_list_names.insert(name, (self.named.len(), otemp));
                self.named.push(ScopeEntry::Scope(s, reason.clone()));
                self.is_input.push(other.is_input[oidx].clone());
            }
        }

        // Compare restrictions on local variables
        for (name, &oidx) in &other.local_names {
            if let Some(idx) = self.local_names.get(name).copied() {
                let (s, reason) = other.resolve_named(oidx, data);
                if other.is_input[oidx].is_some() {
                    let report = format!("local_var:{name}");
                    self.expect_named3(idx, s, reason, key, &report, data);
                } else {
                    // Their variables now become our variables
                    Self::break_chains_to(&mut self.named, idx);
                    self.named[idx] = ScopeEntry::Scope(s, reason.clone());
                }
            } else if self.strict_scopes && other.is_input[oidx].is_some() {
                let token = other.is_input[oidx].as_ref().unwrap();
                let msg = format!("`{key}` expects local_var:{name} to be set");
                let msg2 = "here";
                self.log_traceback(
                    warn(ErrorKey::StrictScopes).msg(msg).loc(key).loc_msg(token, msg2),
                )
                .push();
            } else {
                // Their variables now become our variables
                let (s, reason) = other.resolve_named(oidx, data);
                self.local_names.insert(name, self.named.len());
                self.named.push(ScopeEntry::Scope(s, reason.clone()));
                self.is_input.push(other.is_input[oidx].clone());
            }
        }

        // Compare restrictions on local variable lists
        for (name, &oidx) in &other.local_list_names {
            if let Some(idx) = self.local_list_names.get(name).copied() {
                let (s, reason) = other.resolve_named(oidx, data);
                if other.is_input[oidx].is_some() {
                    let report = format!("local list {name}");
                    self.expect_named3(idx, s, reason, key, &report, data);
                } else {
                    // Their lists now become our lists.
                    Self::break_chains_to(&mut self.named, idx);
                    self.named[idx] = ScopeEntry::Scope(s, reason.clone());
                }
            } else if self.strict_scopes && other.is_input[oidx].is_some() {
                let token = other.is_input[oidx].as_ref().unwrap();
                let msg = format!("`{key}` expects local variable list {name} to exist");
                let msg2 = "here";
                self.log_traceback(
                    warn(ErrorKey::StrictScopes).msg(msg).loc(key).loc_msg(token, msg2),
                )
                .push();
            } else {
                // Their lists now become our lists.
                let (s, reason) = other.resolve_named(oidx, data);
                self.local_list_names.insert(name, self.named.len());
                self.named.push(ScopeEntry::Scope(s, reason.clone()));
                self.is_input.push(other.is_input[oidx].clone());
            }
        }
    }

    /// Safely destroy a `ScopeContext` without fully unwinding its stack.
    /// This is useful when a `ScopeContext` needed to be cloned for some reason.
    #[allow(dead_code)]
    pub(crate) fn destroy(mut self) {
        self.prev_levels = self.scope_stack.len() - 1;
    }
}

impl Drop for ScopeContext {
    /// This `drop` function checks that every opened scope level was also closed.
    fn drop(&mut self) {
        // Only assert if not already panicking, to avoid a double panic during unwind.
        if !panicking() {
            // Expect only the prev levels and the `this` level to remain.
            assert_eq!(
                self.scope_stack.len(),
                self.prev_levels + 1,
                "scope chain not properly unwound"
            );
        }
    }
}

/// Deduce a scope type from a scope's name. This leads to better error messages.
///
/// It should be limited to names that are so obvious that it's extremely unlikely that anyone
/// would use them for a different type.
#[allow(unused_variables)] // hoi4 does not use `name`
#[allow(unused_mut)] // hoi4 does not use `name`
fn scope_type_from_name(mut name: &str) -> Option<Scopes> {
    #[cfg(feature = "jomini")]
    if let Some(real_name) = name.strip_prefix("scope:") {
        name = real_name;
    } else if let Some(real_name) = name.strip_prefix("local_var:") {
        name = real_name;
    } else {
        return None;
    }

    #[cfg(feature = "ck3")]
    if Game::is_ck3() {
        return match name {
            "accolade" => Some(Scopes::Accolade),
            "accolade_type" => Some(Scopes::AccoladeType),
            "activity" => Some(Scopes::Activity),
            "actor"
            | "recipient"
            | "secondary_actor"
            | "secondary_recipient"
            | "mother"
            | "father"
            | "real_father"
            | "child"
            | "councillor"
            | "liege"
            | "courtier"
            | "guest"
            | "host" => Some(Scopes::Character),
            "army" => Some(Scopes::Army),
            "artifact" => Some(Scopes::Artifact),
            "barony" | "county" | "title" | "landed_title" => Some(Scopes::LandedTitle),
            "combat_side" => Some(Scopes::CombatSide),
            "council_task" => Some(Scopes::CouncilTask),
            "culture" => Some(Scopes::Culture),
            "faction" => Some(Scopes::Faction),
            "faith" => Some(Scopes::Faith),
            "province" => Some(Scopes::Province),
            "scheme" => Some(Scopes::Scheme),
            "struggle" => Some(Scopes::Struggle),
            "story" => Some(Scopes::StoryCycle),
            "travel_plan" => Some(Scopes::TravelPlan),
            "war" => Some(Scopes::War),
            _ => None,
        };
    }

    #[cfg(feature = "vic3")]
    if Game::is_vic3() {
        // Due to differences in state vs state_region, law vs law_type, etc, less can be deduced
        // with certainty for vic3.
        return match name {
            "admiral" | "general" | "character" => Some(Scopes::Character),
            "actor" | "country" | "enemy_country" | "initiator" | "target_country" => {
                Some(Scopes::Country)
            }
            "battle" => Some(Scopes::Battle),
            "interest_group" => Some(Scopes::InterestGroup),
            "journal_entry" => Some(Scopes::JournalEntry),
            "market" => Some(Scopes::Market),
            _ => None,
        };
    }

    #[cfg(feature = "imperator")]
    if Game::is_imperator() {
        return match name {
            "party" | "character_party" => Some(Scopes::Party),
            "employer" | "party_country" | "country" | "overlord" | "unit_owner"
            | "attacker_warleader" | "defender_warleader" | "former_overlord"
            | "target_subject" | "future_overlord" | "old_country" | "controller" | "owner"
            | "family_country" | "losing_side" | "home_country" => Some(Scopes::Country),
            "fam" | "family" => Some(Scopes::Family),
            "preferred_heir" | "deified_ruler" | "personal_loyalty" | "character"
            | "siege_controller" | "party_leader" | "next_in_family" | "ruler" | "governor"
            | "governor_or_ruler" | "commander" | "former_ruler" | "newborn" | "spouse"
            | "job_holder" | "consort" | "current_heir" | "current_ruler" | "primary_heir"
            | "secondary_heir" | "current_co_ruler" | "head_of_family" | "holding_owner"
            | "char" | "mother" | "father" => Some(Scopes::Character),
            "job" => Some(Scopes::Job),
            "legion" => Some(Scopes::Legion),
            "dominant_province_religion" | "religion" => Some(Scopes::Religion),
            "area" => Some(Scopes::Area),
            "region" => Some(Scopes::Region),
            "governorship" => Some(Scopes::Governorship),
            "country_culture" => Some(Scopes::CountryCulture),
            "location"
            | "unit_destination"
            | "unit_objective_destination"
            | "unit_location"
            | "unit_next_location"
            | "capital_scope"
            | "holy_site" => Some(Scopes::Province),
            "dominant_province_culture_group" | "culture_group" => Some(Scopes::CultureGroup),
            "dominant_province_culture" | "culture" => Some(Scopes::Culture),
            "owning_unit" => Some(Scopes::Unit),
            "deity" | "province_deity" => Some(Scopes::Deity),
            "state" => Some(Scopes::State),
            "treasure" => Some(Scopes::Treasure),
            "siege" => Some(Scopes::Siege),
            _ => None,
        };
    }

    #[cfg(feature = "eu5")]
    if Game::is_eu5() {
        return match name {
            // TODO: EU5 fill in good guesses
            _ => None,
        };
    }

    None
}