rakata_formats/gff/

document.rs

//! An open GFF file, editable by path and readable as any typed view.
//!
//! # Why it holds the bytes it was opened from
//!
//! Re-serialising a parsed tree loses nothing and moves plenty. Measured over
//! every GFF in a vanilla install, the writer reproduces some files byte for
//! byte and re-lays out the rest, with every one of the rearranged files
//! re-reading to a tree equal to the original. Measured over a folder of
//! saves, it reproduces none of them. The rearranging is ordering inside a
//! block rather than a change of content: only a handful of install files come
//! out with a differently-sized block at all.
//!
//! So a document that parsed on open and serialised on save would rewrite most
//! files it was merely asked to look at. This one keeps the bytes it was handed
//! and gives them back untouched until something actually changes, which makes
//! open-then-save a no-op by construction rather than by the writer and the
//! toolset happening to agree.
//!
//! # What survives an edit
//!
//! Everything. The tree is the whole file, so a label no view models is still
//! there after [`set`](GffDocument::set) has changed one that is. That is the
//! difference between this and reading a typed view, editing it and authoring
//! it back: a view models only what the engine reads, so authoring from one
//! drops the rest.
//!
//! # A closed set of mutators, and no way past them
//!
//! [`set`](GffDocument::set), [`insert`](GffDocument::insert),
//! [`remove`](GffDocument::remove),
//! [`push_element`](GffDocument::push_element) and
//! [`set_struct_id_at`](GffDocument::set_struct_id_at) are the whole surface.
//! There is no `&mut Gff`, and that narrowing is what makes this document able
//! to say whether it has been edited at all: [`gff`](GffDocument::gff) lends
//! the tree out for reading and [`view`](GffDocument::view) hands back an owned
//! projection, so nothing outside can change the tree without going through one
//! of them.
//!
//! # The `_at` forms are the primary ones
//!
//! Every operation comes in two spellings: one taking `&str` in the dot
//! notation `ClassList[0].Class`, and an `_at` one taking a [`GffPath`]. The
//! text forms came first and read as the real API, and they are not. Each
//! parses its argument and calls the `_at` form, so the address is what this
//! document actually works in and the text is a convenience over it.
//!
//! Which matters at a call site holding a path already. A raw tree keeps a
//! [`GffPath`] per row and a change map is keyed by one, so reading through the
//! text form would render an address to a `String` and parse it back to reach
//! the value it was already pointing at. Reach for `_at` unless the address
//! genuinely arrived as text, from a config file, a lint rule or a user.
//!
//! Their error types differ for the same reason. The text forms answer
//! [`GffDocumentError`], which has a syntax arm; the `_at` forms answer
//! [`GffPathError`], because an address that already parsed cannot fail to.
//!
//! # No schema is consulted
//!
//! [`set`](GffDocument::set) takes whatever the caller's Rust type maps to and
//! [`GffStruct::set`] refuses it if the stored field is a different width. That
//! refusal is the whole check. Widening the field to fit would shift every byte
//! after it, and looking the label up in a schema would mean the document
//! deciding which format it thinks the file is, which it cannot do for a mod's
//! own label and should not do for anyone's.

use std::collections::BTreeMap;
use std::str::FromStr;

use thiserror::Error;

use super::{read_gff_from_bytes, write_gff_to_vec, Gff, GffBinaryError, GffStruct, GffValue};
use super::{GffPath, GffPathError, GffPathParseError, GffPathSegment};
use crate::schema::{FromGff, GffScalar};

/// A path that does not parse, or does not name one field of this tree.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum GffDocumentError {
    /// The path text is not an address.
    #[error(transparent)]
    Syntax(#[from] GffPathParseError),
    /// The address does not resolve, or the tree will not take the edit.
    #[error(transparent)]
    Path(#[from] GffPathError),
    /// The field is there and holds something the caller cannot read it as.
    ///
    /// Separate from the address not resolving, because those want different
    /// answers: a missing field is often ordinary and a field of the wrong
    /// width is a file that is not what it claimed to be.
    #[error("`{at}` does not hold a {wanted}")]
    WrongType {
        /// The address that resolved.
        at: String,
        /// The type the caller asked for.
        wanted: &'static str,
    },
}

/// What happened at one address, from open until now.
///
/// `before` is what was there when the document was opened, not what was there
/// last time. An editor's review pane shows a user what saving would do to the
/// file they opened, and a chain of intermediate values is not that.
///
/// `None` on either side means the address held nothing: absent before an
/// insert, absent after a remove.
#[derive(Debug, Clone, PartialEq)]
pub struct Change {
    /// What the opened file held there.
    pub before: Option<GffValue>,
    /// What it holds there now.
    pub current: Option<GffValue>,
}

/// What a mutation does to whatever is already recorded beneath its address.
///
/// The mutator's own statement, because the address does not carry it: a
/// removal and an append at one list address are both mutations of the list
/// and only the first makes a change recorded inside it obsolete.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Subtree {
    /// What was under the address is gone or replaced, so anything recorded
    /// under it no longer describes this file.
    Replaced,
    /// What was under the address is still there, untouched and still at the
    /// same addresses.
    Kept,
}

/// One open GFF file: its bytes, its tree, and what has happened to it.
#[derive(Debug, Clone, PartialEq)]
pub struct GffDocument {
    source: Vec<u8>,
    gff: Gff,
    changes: BTreeMap<GffPath, Change>,
    revision: u64,
}

impl GffDocument {
    /// Parses `source` and keeps a copy of it.
    ///
    /// # Errors
    ///
    /// Returns [`GffBinaryError`] when the bytes are not a GFF this reader
    /// accepts.
    pub fn open(source: &[u8]) -> Result<Self, GffBinaryError> {
        Ok(Self {
            gff: read_gff_from_bytes(source)?,
            source: source.to_vec(),
            changes: BTreeMap::new(),
            revision: 0,
        })
    }

    /// How many times this document has been mutated.
    ///
    /// Zero on open, rising by one per mutation that the tree accepted. A
    /// mutation returning a value to what the file held records no change and
    /// still counts, so this moves when [`changes`](Self::changes) does not.
    ///
    /// For a consumer caching state derived from the tree.
    pub fn revision(&self) -> u64 {
        self.revision
    }

    /// The parsed tree, including everything no view models.
    pub fn gff(&self) -> &Gff {
        &self.gff
    }

    /// Whether the tree differs from the file this was opened from.
    ///
    /// Whether the content differs, not whether a mutator ran. Setting a field
    /// to the value it already held leaves this `false`, which matters because
    /// a UI binding a text field writes the unchanged value on every redraw and
    /// [`save`](Self::save) re-serialises whenever this is `true`.
    pub fn is_edited(&self) -> bool {
        !self.changes.is_empty()
    }

    /// Every address whose content differs from the opened file, in path
    /// order.
    ///
    /// Recorded as the edits are made rather than derived by comparing trees.
    /// This document is the only thing that can change its own tree, so a map
    /// it keeps cannot fall behind: [`gff`](Self::gff) lends the tree for
    /// reading, [`view`](Self::view) hands back an owned projection, and the
    /// four mutators all funnel through one recording point. The drift that
    /// makes an event log untrustworthy is a hazard for something *observing*
    /// mutations, not for the one making them.
    ///
    /// An address that has come back to what it held is not in here. Setting a
    /// field and setting it back leaves nothing, appending an element and
    /// removing it again leaves nothing, and setting one field twice leaves one
    /// entry against the value the file was opened with.
    pub fn changes(&self) -> &BTreeMap<GffPath, Change> {
        &self.changes
    }

    /// Reads this file as a typed view.
    ///
    /// The view is a projection and reading one changes nothing here, so a
    /// caller can take several views of the same document and still save the
    /// file it opened.
    ///
    /// # Errors
    ///
    /// Whatever the view's own reader reports.
    pub fn view<T: FromGff>(&self) -> Result<T, T::Error> {
        T::from_gff(&self.gff)
    }

    /// Reads the value at `path`, in the dot notation `ClassList[0].Class`.
    ///
    /// Parses the text and delegates to [`get_at`](Self::get_at). A caller that
    /// already holds a [`GffPath`] wants that one instead: this renders nothing
    /// and allocates nothing, but it does have to parse, and a caller looping
    /// over addresses it already has would be paying for a round trip through
    /// text it never needed.
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address, and
    /// [`GffDocumentError::Path`] when it does not name exactly one field of
    /// this tree.
    pub fn get(&self, path: &str) -> Result<&GffValue, GffDocumentError> {
        let path = GffPath::from_str(path)?;
        Ok(self.get_at(&path)?)
    }

    /// Reads the value `at` names.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when the address does not name exactly one field of
    /// this tree. There is no syntax error to report, which is the whole
    /// difference between this family and the text one.
    pub fn get_at(&self, at: &GffPath) -> Result<&GffValue, GffPathError> {
        self.gff.root.get(at)
    }

    /// The struct id of the list element `at` names.
    ///
    /// The reader half of [`set_struct_id_at`](Self::set_struct_id_at), and the
    /// only way to see an id without reaching past this document into the tree.
    /// Several formats put meaning there and in no field: a UTC's equipment
    /// slot **is** its `Equip_ItemList` element's id, so reading which slot an
    /// item occupies is exactly this call.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when `at` does not end in a list index, or indexes past
    /// the end of the list.
    pub fn struct_id_at(&self, at: &GffPath) -> Result<i32, GffPathError> {
        self.gff.root.struct_id(at)
    }

    /// Reads the value at `path` as `T`.
    ///
    /// The typed counterpart to [`get`](Self::get), which hands back the wire
    /// value and leaves the caller to match on its variant. Every field a
    /// panel binds a control to goes through that unwrap, so it is written
    /// here once instead of at each of them.
    ///
    /// Accepts every encoding the type can be read from, which is
    /// [`GffScalar`]'s own tolerance rather than a second rule: a field
    /// declared narrower than the caller's type still reads.
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address,
    /// [`GffDocumentError::Path`] when it names no single field, and
    /// [`GffDocumentError::WrongType`] when the field is there and holds
    /// something else. The last is kept apart from the second because a field
    /// that is absent and a field that is the wrong shape are different facts
    /// about the file.
    pub fn get_as<T: GffScalar>(&self, path: &str) -> Result<T, GffDocumentError> {
        let value = self.get(path)?;
        T::from_gff_value(value).ok_or_else(|| GffDocumentError::WrongType {
            at: path.to_owned(),
            wanted: T::GFF_TYPE.name(),
        })
    }

    /// Replaces the value at `path`, returning what was there.
    ///
    /// The field has to be present already and the replacement has to be the
    /// width the field stores. Both refusals are [`GffStruct::set`]'s, and its
    /// docs say why.
    ///
    /// [`GffStruct::set`]: super::GffStruct::set
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address, and
    /// [`GffDocumentError::Path`] when the field is absent, is carried more
    /// than once, or stores a different width.
    pub fn set(&mut self, path: &str, value: impl GffScalar) -> Result<GffValue, GffDocumentError> {
        let path = GffPath::from_str(path)?;
        Ok(self.set_at(&path, value.to_gff_value())?)
    }

    /// Adds the field `path` names, which must not already be there.
    ///
    /// The value's own type decides the field's type: there is nothing stored
    /// to preserve, which is why this takes what it is given where
    /// [`set`](Self::set) refuses a width change.
    ///
    /// Scalars only, and that is this spelling's limit rather than the
    /// document's: [`insert_at`](Self::insert_at) takes a [`GffValue`], so a
    /// caller adding a list or a nested struct goes through that one. A raw
    /// tree offering "add a field" does exactly that.
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address, and
    /// [`GffDocumentError::Path`] when the parent does not resolve or the
    /// label is already there.
    pub fn insert(&mut self, path: &str, value: impl GffScalar) -> Result<(), GffDocumentError> {
        let path = GffPath::from_str(path)?;
        Ok(self.insert_at(&path, value.to_gff_value())?)
    }

    /// Removes what `path` names, returning it.
    ///
    /// A path ending in a label removes that field; one ending in an index
    /// removes that list element and hands it back wrapped in a
    /// [`GffValue::Struct`]. Siblings are not renumbered, for the reason
    /// [`GffStruct::remove`] gives.
    ///
    /// [`GffStruct::remove`]: super::GffStruct::remove
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address, and
    /// [`GffDocumentError::Path`] when it names nothing, names a field carried
    /// more than once, or indexes past the end of a list.
    pub fn remove(&mut self, path: &str) -> Result<GffValue, GffDocumentError> {
        let path = GffPath::from_str(path)?;
        Ok(self.remove_at(&path)?)
    }

    /// Replaces the value at `at`, taking the address and the value as they
    /// stand.
    ///
    /// The typed counterpart to [`set`](Self::set), for a caller that already
    /// holds both. Reverting a change-review row is the case this exists for:
    /// [`changes`](Self::changes) is keyed by [`GffPath`] and hands back a
    /// [`GffValue`], so rendering that address back to text and picking a
    /// Rust type to put the value through would be undoing work twice.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when the field is absent, is carried more than once,
    /// or stores a different width.
    pub fn set_at(&mut self, at: &GffPath, value: GffValue) -> Result<GffValue, GffPathError> {
        self.edit(at.clone(), Subtree::Replaced, |root| root.set(at, value))
    }

    /// Adds the field `at` names, taking the value as it stands.
    ///
    /// The typed counterpart to [`insert`](Self::insert), and the other half
    /// of reverting a row: a change whose `before` was `None` reverts by
    /// removing, and one whose `current` is `None` reverts by inserting what
    /// was there.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when the parent does not resolve or the label is
    /// already there.
    ///
    /// A field the opened file carried goes back where the file had it. A
    /// struct stores its fields in order and the writer emits them in that
    /// order, so putting one back on the end would rewrite the file from the
    /// hole onwards. A field the file never had is appended, there being no
    /// position to restore.
    pub fn insert_at(&mut self, at: &GffPath, value: GffValue) -> Result<(), GffPathError> {
        let position = self.position_in_source(at).unwrap_or(usize::MAX);
        self.edit(at.clone(), Subtree::Replaced, |root| {
            root.insert_at_position(at, value, position)
        })
    }

    /// Where the opened file kept the field `at` names.
    ///
    /// Reparses, which costs a parse of the whole document. Only inserts pay
    /// it, and an insert is a thing somebody clicked rather than something a
    /// frame does.
    fn position_in_source(&self, at: &GffPath) -> Option<usize> {
        Self::open(&self.source).ok()?.gff.root.position(at)
    }

    /// Removes what `at` names, returning it.
    ///
    /// The typed counterpart to [`remove`](Self::remove).
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when it names nothing, names a field carried more than
    /// once, or indexes past the end of a list.
    pub fn remove_at(&mut self, at: &GffPath) -> Result<GffValue, GffPathError> {
        let node = Self::records_at(at);
        self.edit(node, Subtree::Replaced, |root| root.remove(at))
    }

    /// Appends `element` to the list `path` names, returning its index.
    ///
    /// The element carries its own struct id and choosing it is the caller's,
    /// because several lists have the engine skip an element whose id is wrong
    /// and which id belongs to which list is per-format knowledge this layer
    /// does not hold.
    ///
    /// # Errors
    ///
    /// [`GffDocumentError::Syntax`] when the text is not an address, and
    /// [`GffDocumentError::Path`] when it does not name a list of this tree.
    pub fn push_element(
        &mut self,
        path: &str,
        element: GffStruct,
    ) -> Result<usize, GffDocumentError> {
        let path = GffPath::from_str(path)?;
        Ok(self.push_element_at(&path, element)?)
    }

    /// Appends `element` to the list `at` names, returning its index.
    ///
    /// The typed counterpart to [`push_element`](Self::push_element). Choosing
    /// the element's struct id stays the caller's, for the reason given there.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when `at` does not name a list of this tree.
    pub fn push_element_at(
        &mut self,
        at: &GffPath,
        element: GffStruct,
    ) -> Result<usize, GffPathError> {
        self.edit(at.clone(), Subtree::Kept, |root| {
            root.push_element(at, element)
        })
    }

    /// Sets the struct id of the list element `at` names, returning the old one.
    ///
    /// Some formats carry meaning in an element's id rather than in any field.
    /// A UTC's equipment slot **is** its `Equip_ItemList` element's struct id,
    /// so moving an item between slots is this call rather than a removal and
    /// an append. Which ids a list accepts stays the caller's to know, for the
    /// reason it is on [`push_element`](Self::push_element).
    ///
    /// # The change lands on the list, not on the element
    ///
    /// Not a choice about where it reads best. A [`Change`] holds a
    /// [`GffValue`], a list holds its elements as [`GffStruct`], and no value
    /// in the tree stands for one element. That is the same shortfall
    /// [`get`](Self::get) refuses an index-terminated address over. The list is
    /// the shallowest node that has a value, and an element's id is inside it,
    /// so the comparison already sees an id change with nothing new to observe
    /// it with.
    ///
    /// Nothing inside the element moves, so a change recorded under it stays
    /// recorded.
    ///
    /// # Errors
    ///
    /// [`GffPathError`] when `at` does not end in a list index, or indexes past
    /// the end of the list.
    pub fn set_struct_id_at(&mut self, at: &GffPath, struct_id: i32) -> Result<i32, GffPathError> {
        self.edit(Self::records_at(at), Subtree::Kept, |root| {
            root.set_struct_id(at, struct_id)
        })
    }

    /// The address a mutation on `path` is recorded against.
    ///
    /// The path itself, except for a list element: removing `ItemList[1]`
    /// shifts every sibling after it, so `ItemList[1]` now holds what
    /// `ItemList[2]` did and recording against it would describe a change
    /// nobody made. The list is the shallowest node whose content actually
    /// differs, so that is where it lands.
    ///
    /// Public because a caller building an undo stack has to read the same
    /// value either side of a mutation, and it can only do that if it knows
    /// where the mutation will land. Working it out a second time from the
    /// same rule is how the two come to disagree about a list element.
    pub fn records_at(path: &GffPath) -> GffPath {
        match path.segments().last() {
            Some(GffPathSegment::Index(_)) => path
                .parent()
                .expect("a path with a last segment has a parent"),
            _ => path.clone(),
        }
    }

    /// Applies one mutation and records what it did.
    ///
    /// The only place the tree is mutated. `apply` gets the root, and the
    /// value at `at` is read either side of it, so a mutator added later
    /// cannot record nothing: it has no other way to reach a `&mut GffStruct`.
    ///
    /// A recording that comes back to what the file held is dropped rather
    /// than kept as a no-change row, which is what collapses a set-and-set-back
    /// and an append-then-remove to nothing at all.
    ///
    /// # What a mutation does to what is already recorded under it
    ///
    /// `scope` is the mutator's own statement about its subtree, because the
    /// address alone does not say. Removing a list shifts and discards
    /// everything under it; appending to the same list leaves every existing
    /// element where it was. Both are mutations at the list's address and only
    /// one of them makes a change recorded under it obsolete.
    fn edit<T>(
        &mut self,
        at: GffPath,
        scope: Subtree,
        apply: impl FnOnce(&mut super::GffStruct) -> Result<T, GffPathError>,
    ) -> Result<T, GffPathError> {
        // Descendants sort contiguously after their ancestor with nothing able
        // to sort between, so the range stops at the first path that is not
        // under `at`.
        let obsolete: Vec<GffPath> = match scope {
            Subtree::Kept => Vec::new(),
            Subtree::Replaced => self
                .changes
                .range(at.clone()..)
                .take_while(|(path, _)| path.starts_with(&at))
                .filter(|(path, _)| **path != at)
                .map(|(path, _)| path.clone())
                .collect(),
        };

        let before = if obsolete.is_empty() {
            // Nothing under `at` has been edited, so the tree still holds what
            // the file did.
            self.gff.root.get(&at).ok().cloned()
        } else {
            // Something under `at` has been edited, so the tree does not. Read
            // the opened file instead: `before` means what the file held, and a
            // subtree carrying an interim edit is not that.
            //
            // Reparsing costs a parse of the whole document, and this is the
            // only path that pays it: replacing a subtree somebody had already
            // edited inside.
            Self::open(&self.source)
                .ok()
                .and_then(|opened| opened.gff.root.get(&at).ok().cloned())
        };

        let outcome = apply(&mut self.gff.root)?;
        // After `apply` succeeded, so it rises exactly when the tree moved.
        self.revision += 1;
        let current = self.gff.root.get(&at).ok().cloned();

        // Dropped after the mutation rather than before, so a failing `apply`
        // leaves the map as it was.
        for path in obsolete {
            self.changes.remove(&path);
        }

        match self.changes.entry(at) {
            std::collections::btree_map::Entry::Occupied(mut entry) => {
                // `before` stays what the file held; only the near side moves.
                entry.get_mut().current = current;
                if entry.get().before == entry.get().current {
                    entry.remove();
                }
            }
            std::collections::btree_map::Entry::Vacant(entry) => {
                if before != current {
                    entry.insert(Change { before, current });
                }
            }
        }
        Ok(outcome)
    }

    /// The file to write back.
    ///
    /// The bytes this document was opened with, byte for byte, until an edit
    /// has landed. After one, the tree re-serialised.
    ///
    /// # Errors
    ///
    /// Returns [`GffBinaryError`] when the edited tree cannot be encoded, which
    /// a tree read out of a file and edited through these mutators cannot
    /// reach: everything they store is a value this crate can encode.
    pub fn save(&self) -> Result<Vec<u8>, GffBinaryError> {
        if self.is_edited() {
            write_gff_to_vec(&self.gff)
        } else {
            Ok(self.source.clone())
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::gff::GffField;
    use crate::gff_label;

    const UTW: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/test.utw"
    ));

    fn open() -> GffDocument {
        GffDocument::open(UTW).expect("the fixture is a GFF")
    }

    /// Every label the file arrived with, so a test can say what an edit left
    /// alone rather than only what it changed.
    fn labels(document: &GffDocument) -> Vec<String> {
        document
            .gff()
            .root
            .fields
            .iter()
            .map(|field| field.label.to_string())
            .collect()
    }

    /// A field the file carried goes back where the file had it.
    ///
    /// A struct stores its fields in order and the writer emits them in that
    /// order, so restoring one by appending rewrites the file from the hole
    /// onwards. That is what undoing a deletion in the editor produced, and
    /// what reverting a removed row produced, both of them through here.
    #[test]
    fn a_removed_field_goes_back_where_it_was() {
        let mut document = open();
        let order = labels(&document);
        let middle = order.len() / 2;
        let at = GffPath::from_str(&order[middle]).expect("a label is an address");

        let held = document.remove_at(&at).expect("the field is there");
        assert_ne!(labels(&document), order, "nothing was removed");

        document.insert_at(&at, held).expect("it goes back");
        assert_eq!(
            labels(&document),
            order,
            "a restored field landed somewhere else"
        );
    }

    /// And the bytes agree, which is the claim that actually matters: what the
    /// editor writes after an undo has to be what it would have written without
    /// the round trip.
    ///
    /// Measured against a second document carrying only the unrelated edit,
    /// rather than against the file. A removal and its undo cancel out in the
    /// change map, so on their own they leave the document unedited and `save`
    /// hands back the source without encoding anything: comparing that to the
    /// file passes whatever the field order is. The unrelated edit is what
    /// forces the writer to run.
    #[test]
    fn a_field_removed_and_put_back_encodes_where_it_started() {
        let order = labels(&open());
        let moved = GffPath::from_str(&order[1]).expect("a label is an address");
        let elsewhere = GffPath::from_str(&order[order.len() - 1]).expect("an address");

        let dirty = |document: &mut GffDocument| {
            let held = document.get_at(&elsewhere).expect("it is there").clone();
            document
                .remove_at(&elsewhere)
                .expect("something to make this document encode");
            held
        };

        let mut untouched = open();
        dirty(&mut untouched);

        let mut round_tripped = open();
        dirty(&mut round_tripped);
        let held = round_tripped.remove_at(&moved).expect("the field is there");
        round_tripped.insert_at(&moved, held).expect("it goes back");

        assert!(round_tripped.is_edited(), "nothing would be encoded");
        assert_eq!(
            round_tripped.save().expect("it encodes"),
            untouched.save().expect("it encodes"),
            "a removal and its undo did not cancel out in the bytes"
        );
    }

    /// The revision rises on a mutation that records no change.
    ///
    /// The property that makes it usable as a cache key and the reason it is
    /// not derived from the change map. Setting a value back to what the file
    /// held prunes the row, so the map looks exactly as it did while the tree
    /// has moved twice; a reader keyed on the map would hand back rows built
    /// from a tree that no longer exists.
    #[test]
    fn a_mutation_that_records_nothing_still_counts() {
        let mut document = open();
        let at = GffPath::from_str(&labels(&document)[1]).expect("a label is an address");
        let held = document.get_at(&at).expect("a field").clone();

        // Removed and put back rather than set twice, so the mutation does not
        // depend on guessing the field's width.
        let start = document.revision();
        document.remove_at(&at).expect("the field is there");
        document.insert_at(&at, held).expect("it goes back");

        assert!(
            document.changes().is_empty(),
            "the round trip left a change, so this is not testing the pruned case"
        );
        assert_eq!(
            document.revision(),
            start + 2,
            "a pruned mutation did not count"
        );
    }

    /// A failed mutation does not count, since the tree did not move.
    #[test]
    fn a_refused_mutation_does_not_count() {
        let mut document = open();
        let start = document.revision();
        document
            .set_at(
                &GffPath::from_str("NoSuchField").expect("an address"),
                GffValue::UInt32(1),
            )
            .expect_err("the address resolves to nothing");
        assert_eq!(document.revision(), start, "a refused edit counted");
    }

    /// A field the file never had has no position to restore, so it goes on
    /// the end. This is the add-a-field case rather than the undo case.
    #[test]
    fn a_field_the_file_never_had_is_appended() {
        let mut document = open();
        let at = GffPath::from_str("RakataMarker").expect("an address");

        document
            .insert_at(&at, GffValue::UInt32(7))
            .expect("it is new");

        assert_eq!(
            labels(&document).last().map(String::as_str),
            Some("RakataMarker"),
            "a new field did not go on the end"
        );
    }

    #[test]
    fn a_document_opens_unedited_and_hands_back_the_bytes_it_was_given() {
        let document = open();
        assert!(!document.is_edited());
        assert_eq!(document.save().expect("no edit, no encode"), UTW);
    }

    #[test]
    fn inserting_adds_a_field_and_refuses_one_that_is_there() {
        let mut document = open();
        let before = labels(&document);
        assert!(!before.contains(&"RakataMarker".to_owned()));

        document
            .insert("RakataMarker", 7_u8)
            .expect("the label is not there yet");
        assert!(document.is_edited());
        assert_eq!(
            document.get("RakataMarker").expect("just inserted"),
            &GffValue::UInt8(7)
        );

        // Every label the file arrived with is still there, in order, with the
        // new one after them.
        let after = labels(&document);
        assert_eq!(&after[..before.len()], &before[..]);
        assert_eq!(after.last().map(String::as_str), Some("RakataMarker"));

        assert!(
            document.insert("RakataMarker", 8_u8).is_err(),
            "a second insert would append a duplicate the first would win over"
        );
    }

    #[test]
    fn removing_takes_a_field_away_and_hands_it_back() {
        let mut document = open();
        let before = labels(&document);
        let target = before.first().expect("the fixture holds fields").clone();

        let removed = document.remove(&target).expect("the field is there");
        assert!(document.is_edited());
        assert!(
            !matches!(removed, GffValue::List(_)),
            "the fixture's first field is a scalar"
        );
        assert!(!labels(&document).contains(&target));
        assert!(document.get(&target).is_err(), "it is gone");
    }

    /// A document holding a list, authored rather than read, because the
    /// committed scalar fixtures carry none.
    fn with_a_list() -> GffDocument {
        let gff = Gff::new(
            *b"UTW ",
            GffStruct {
                struct_id: -1,
                fields: vec![
                    GffField {
                        label: gff_label!("Mark"),
                        value: GffValue::UInt32(5),
                    },
                    GffField {
                        label: gff_label!("RakataList"),
                        value: GffValue::List(Vec::new()),
                    },
                    GffField {
                        label: gff_label!("Nested"),
                        value: GffValue::Struct(Box::new(GffStruct {
                            struct_id: 0,
                            fields: vec![GffField {
                                label: gff_label!("Inner"),
                                value: GffValue::UInt32(7),
                            }],
                        })),
                    },
                ],
            },
        );
        let bytes = write_gff_to_vec(&gff).expect("a list of nothing encodes");
        GffDocument::open(&bytes).expect("what this crate wrote, it reads")
    }

    fn element(mark: u8) -> GffStruct {
        GffStruct {
            struct_id: 3,
            fields: vec![GffField {
                label: gff_label!("Mark"),
                value: GffValue::UInt8(mark),
            }],
        }
    }

    #[test]
    fn pushing_an_element_appends_it_and_says_where_it_landed() {
        let mut document = with_a_list();
        assert!(!document.is_edited());

        assert_eq!(document.push_element("RakataList", element(1)), Ok(0));
        assert_eq!(document.push_element("RakataList", element(2)), Ok(1));
        assert!(document.is_edited());

        assert_eq!(document.get("RakataList[1].Mark"), Ok(&GffValue::UInt8(2)));
        assert!(
            document.push_element("Nope", element(3)).is_err(),
            "a path naming no list is refused rather than creating one"
        );
    }

    /// Removing by index takes the element out and leaves the ones around it,
    /// which is what an inventory row deletion is.
    #[test]
    fn removing_an_element_leaves_its_siblings_where_they_were() {
        let mut document = with_a_list();
        for mark in 1..=3 {
            document
                .push_element("RakataList", element(mark))
                .expect("the list is there");
        }

        let removed = document
            .remove("RakataList[1]")
            .expect("the element is there");
        assert!(matches!(removed, GffValue::Struct(_)));
        assert_eq!(document.get("RakataList[0].Mark"), Ok(&GffValue::UInt8(1)));
        assert_eq!(document.get("RakataList[1].Mark"), Ok(&GffValue::UInt8(3)));
        assert!(document.get("RakataList[2].Mark").is_err());
    }

    /// The point of the document. An edit through any mutator leaves every
    /// other field exactly where it was, including ones no view models.
    #[test]
    fn an_edit_through_any_mutator_leaves_the_rest_of_the_file_alone() {
        let untouched = open();
        for edit in ["insert", "remove"] {
            let mut document = open();
            let before = labels(&document);
            match edit {
                "insert" => document.insert("RakataMarker", 1_u8).expect("insert"),
                "remove" => {
                    document.remove(&before[0]).expect("remove");
                }
                other => panic!("{other}"),
            }
            for label in &before {
                let changed = edit == "remove" && *label == before[0];
                assert_eq!(
                    document.get(label).is_ok(),
                    !changed,
                    "`{label}` after an {edit}"
                );
                if !changed {
                    assert_eq!(
                        document.get(label).expect("still there"),
                        untouched.get(label).expect("was there"),
                        "`{label}` changed value during an {edit}"
                    );
                }
            }
        }
    }

    #[test]
    fn every_mutator_makes_save_re_serialise() {
        let mut inserted = open();
        inserted.insert("RakataMarker", 1_u8).expect("insert");
        assert!(inserted.is_edited());
        assert_ne!(inserted.save().expect("encode"), UTW);

        let mut removed = open();
        let first = labels(&removed)[0].clone();
        removed.remove(&first).expect("remove");
        assert!(removed.is_edited());
        assert_ne!(removed.save().expect("encode"), UTW);
    }

    // ------------------------------------------------------------------
    // What the document records, which is #101.
    // ------------------------------------------------------------------

    /// The bug this replaced. `set` flagged the file edited whenever it ran,
    /// so a UI writing back the value already in a text field made `save`
    /// re-serialise a file nothing had changed — and re-serialising is not
    /// byte-faithful for most of the corpus.
    #[test]
    fn writing_back_the_value_a_field_already_held_is_not_an_edit() {
        let mut document = with_a_list();
        let untouched = document.save().expect("nothing changed yet");

        document.set("Mark", 5_u32).expect("Mark is a UInt32");

        assert!(
            !document.is_edited(),
            "a value written back unchanged left the file counting as edited"
        );
        assert!(document.changes().is_empty());
        assert_eq!(document.save().expect("still nothing changed"), untouched);
    }

    #[test]
    fn setting_twice_records_one_row_against_what_the_file_held() {
        let mut document = with_a_list();
        document.set("Mark", 111_u32).expect("set");
        document.set("Mark", 222_u32).expect("set again");

        assert_eq!(document.changes().len(), 1);
        let change = document.changes().values().next().expect("one row");
        assert_eq!(change.before, Some(GffValue::UInt32(5)));
        assert_eq!(change.current, Some(GffValue::UInt32(222)));
    }

    #[test]
    fn setting_a_field_back_to_what_it_held_drops_the_row() {
        let mut document = with_a_list();
        document.set("Mark", 99_u32).expect("set");
        assert_eq!(document.changes().len(), 1);

        document.set("Mark", 5_u32).expect("set back");
        assert!(document.changes().is_empty(), "the row survived the undo");
        assert!(!document.is_edited());
    }

    #[test]
    fn appending_an_element_and_removing_it_again_nets_to_nothing() {
        let mut document = with_a_list();
        let at = document
            .push_element("RakataList", element(1))
            .expect("the list is there");
        assert_eq!(document.changes().len(), 1);

        document
            .remove(&format!("RakataList[{at}]"))
            .expect("the element is there");
        assert!(document.changes().is_empty(), "the list did not come back");
        assert!(!document.is_edited());
    }

    /// A list mutation records against the list rather than the index the
    /// caller named: removing an element shifts its siblings, so the index no
    /// longer holds what it did and a row against it would describe a change
    /// nobody made.
    #[test]
    fn a_list_mutation_is_recorded_against_the_list() {
        let mut document = with_a_list();
        for mark in 1..=3 {
            document
                .push_element("RakataList", element(mark))
                .expect("the list is there");
        }
        document
            .remove("RakataList[0]")
            .expect("the element is there");

        let keys: Vec<String> = document.changes().keys().map(ToString::to_string).collect();
        assert_eq!(keys, vec!["RakataList".to_owned()]);
    }

    /// A document whose file already carries one element, so an id change is
    /// measured against what was read rather than against an append.
    fn with_an_element() -> GffDocument {
        let mut document = with_a_list();
        document
            .push_element("RakataList", element(1))
            .expect("the list is there");
        let bytes = document.save().expect("an element encodes");
        GffDocument::open(&bytes).expect("what this crate wrote, it reads")
    }

    /// An element's id is data in several formats, so changing it has to record
    /// like any other edit and prune like one.
    #[test]
    fn changing_an_element_id_records_against_the_list_and_prunes() {
        let mut document = with_an_element();
        let at = GffPath::from_str("RakataList[0]").expect("the test's own address");
        assert!(!document.is_edited());
        assert_eq!(document.gff().root.struct_id(&at), Ok(3));

        assert_eq!(document.set_struct_id_at(&at, 9), Ok(3));
        assert_eq!(document.gff().root.struct_id(&at), Ok(9));
        assert!(
            document.is_edited(),
            "an id change left nothing for the review pane"
        );

        // The list, because a change holds a value and no value in the tree
        // stands for one element.
        let keys: Vec<String> = document.changes().keys().map(ToString::to_string).collect();
        assert_eq!(keys, vec!["RakataList".to_owned()]);

        document
            .set_struct_id_at(&at, 3)
            .expect("the element is still there");
        assert!(
            !document.is_edited(),
            "an id set back to what the file held stayed on the review pane"
        );
    }

    /// Changing an id moves nothing inside the element, so an edit already
    /// recorded in there is still recorded afterwards.
    ///
    /// This is the half `Subtree::Kept` decides. Under `Replaced` the inner row
    /// would be dropped as obsolete, and reverting the list would then be the
    /// only way back to a field the user never meant to touch.
    #[test]
    fn an_id_change_leaves_an_edit_inside_the_element_alone() {
        let mut document = with_an_element();
        let at = GffPath::from_str("RakataList[0]").expect("the test's own address");

        document
            .set("RakataList[0].Mark", 42_u8)
            .expect("the element carries a mark");
        document
            .set_struct_id_at(&at, 9)
            .expect("the element is there");

        let keys: Vec<String> = document.changes().keys().map(ToString::to_string).collect();
        assert_eq!(
            keys,
            vec!["RakataList".to_owned(), "RakataList[0].Mark".to_owned()],
            "the edit inside the element did not survive the id change"
        );
        assert_eq!(document.get("RakataList[0].Mark"), Ok(&GffValue::UInt8(42)));
    }

    /// An id belongs to a list element, so an address naming anything else is
    /// refused rather than resolved to something nearby.
    #[test]
    fn only_a_list_element_has_an_id_to_set() {
        let mut document = with_an_element();
        for text in ["RakataList", "Mark", "Nested.Inner"] {
            let at = GffPath::from_str(text).expect("the test's own address");
            assert!(
                document.set_struct_id_at(&at, 9).is_err(),
                "`{text}` is not a list element and took an id anyway"
            );
        }
        assert!(!document.is_edited(), "a refused id change recorded one");
    }

    /// The addressed forms reach what the text forms reach.
    ///
    /// Be clear about which half of this is doing work. The equality between
    /// `get` and `get_at` cannot fail today, because `get` parses and calls
    /// `get_at`, so that line guards the delegation rather than the lookup: it
    /// fails only if somebody gives the text form an implementation of its own,
    /// which is the drift the pairing exists to stop. The assertions pinning
    /// actual values and ids are the ones testing behaviour.
    #[test]
    fn the_text_forms_and_the_addressed_forms_agree() {
        let mut document = with_an_element();
        let at = GffPath::from_str("RakataList[0].Mark").expect("the test's own address");

        assert_eq!(
            document.get_at(&at).ok(),
            document.get(&at.to_string()).ok()
        );
        assert_eq!(document.get_at(&at), Ok(&GffValue::UInt8(1)));

        let list = GffPath::from_str("RakataList").expect("the test's own address");
        assert_eq!(document.push_element_at(&list, element(2)), Ok(1));
        assert_eq!(document.push_element(&list.to_string(), element(3)), Ok(2));

        // And the id reader reaches what the mutator writes, without going
        // through the tree behind the document's back.
        let second = GffPath::from_str("RakataList[1]").expect("the test's own address");
        assert_eq!(document.struct_id_at(&second), Ok(3));
        document
            .set_struct_id_at(&second, 11)
            .expect("the element is there");
        assert_eq!(document.struct_id_at(&second), Ok(11));
    }

    /// An address that already parsed cannot fail to parse, so the `_at` forms
    /// report the path error directly.
    ///
    /// The reason the two families carry different error types rather than one
    /// with an arm that never fires on half its callers.
    #[test]
    fn an_addressed_form_reports_a_path_error_with_no_syntax_arm() {
        let document = with_an_element();
        let missing = GffPath::from_str("Nope").expect("the test's own address");

        let refused: Result<&GffValue, GffPathError> = document.get_at(&missing);
        assert!(refused.is_err());

        // The text form wraps the same failure, plus a syntax arm this one has
        // no way to reach.
        assert!(matches!(
            document.get("Nope"),
            Err(GffDocumentError::Path(_))
        ));
        assert!(matches!(
            document.get("Nope["),
            Err(GffDocumentError::Syntax(_))
        ));
    }

    /// A list that is not there can be created and then filled.
    ///
    /// `insert` takes a scalar, so a creature with no `ItemList` is given one
    /// through `insert_at`, which takes a [`GffValue`]. The two calls have to
    /// work in this order and nothing else asserts that.
    #[test]
    fn a_list_that_is_not_there_can_be_created_and_then_appended_to() {
        let mut document = open();
        let at = GffPath::from_str("ItemList").expect("the test's own address");
        assert!(
            document.get_at(&at).is_err(),
            "the fixture is supposed to carry no such list"
        );

        // Appending is refused while there is nothing to append to, and the
        // refusal leaves no change: the funnel returns before recording, and
        // nothing moved at the address either way.
        let refused = document
            .push_element_at(&at, element(1))
            .expect_err("there is no list to append to yet");
        assert!(
            matches!(refused, GffPathError::NoSuchField { .. }),
            "{refused}"
        );
        assert!(
            !document.is_edited(),
            "a refused append left the document looking edited"
        );

        document
            .insert_at(&at, GffValue::List(Vec::new()))
            .expect("the root takes a new label");
        assert_eq!(document.push_element_at(&at, element(1)), Ok(0));
        assert_eq!(document.get_at(&at), Ok(&GffValue::List(vec![element(1)])));
    }

    /// One mutation to run against a document.
    type Step = Box<dyn Fn(&mut GffDocument)>;

    /// Every way the API can mutate a document, as sequences to run against
    /// one. Named so a failure says which program disagreed.
    fn programs() -> Vec<(&'static str, Vec<Step>)> {
        fn set(path: &'static str, to: u32) -> Step {
            Box::new(move |d: &mut GffDocument| {
                d.set(path, to).expect("the field is there");
            })
        }
        fn push(mark: u8) -> Step {
            Box::new(move |d: &mut GffDocument| {
                d.push_element("RakataList", element(mark))
                    .expect("the list is there");
            })
        }
        fn drop_at(path: &'static str) -> Step {
            Box::new(move |d: &mut GffDocument| {
                d.remove(path).expect("it is there");
            })
        }
        fn add(path: &'static str) -> Step {
            Box::new(move |d: &mut GffDocument| {
                d.insert(path, 1_u32).expect("it is not there yet");
            })
        }

        vec![
            ("nothing", vec![]),
            ("one scalar", vec![set("Mark", 9)]),
            ("scalar twice", vec![set("Mark", 9), set("Mark", 10)]),
            ("scalar and back", vec![set("Mark", 9), set("Mark", 5)]),
            ("nested scalar", vec![set("Nested.Inner", 8)]),
            (
                "nested and back",
                vec![set("Nested.Inner", 8), set("Nested.Inner", 7)],
            ),
            ("insert", vec![add("Fresh")]),
            ("insert then remove", vec![add("Fresh"), drop_at("Fresh")]),
            ("remove a field", vec![drop_at("Mark")]),
            ("push one", vec![push(1)]),
            ("push and pop", vec![push(1), drop_at("RakataList[0]")]),
            (
                "push three, drop the first",
                vec![push(1), push(2), push(3), drop_at("RakataList[0]")],
            ),
            (
                "everything at once",
                vec![
                    set("Mark", 9),
                    set("Nested.Inner", 8),
                    add("Fresh"),
                    push(1),
                ],
            ),
            (
                "everything, then undone",
                vec![
                    set("Mark", 9),
                    set("Nested.Inner", 8),
                    add("Fresh"),
                    push(1),
                    set("Mark", 5),
                    set("Nested.Inner", 7),
                    drop_at("Fresh"),
                    drop_at("RakataList[0]"),
                ],
            ),
        ]
    }

    /// The addresses at which two trees differ, computed the slow way.
    ///
    /// Reports the shallowest node whose content differs: a changed scalar
    /// inside a nested struct is reported at the scalar, and a list that
    /// gained or lost an element is reported at the list rather than at each
    /// shifted index.
    fn diff_trees(before: &Gff, after: &Gff) -> Vec<String> {
        fn walk(before: &GffStruct, after: &GffStruct, at: &GffPath, out: &mut Vec<String>) {
            let mut labels: Vec<_> = before
                .fields
                .iter()
                .chain(after.fields.iter())
                .map(|field| field.label)
                .collect();
            labels.sort();
            labels.dedup();

            for label in labels {
                let here = at.then(GffPathSegment::Field(label));
                let find = |s: &GffStruct| {
                    s.fields
                        .iter()
                        .find(|field| field.label == label)
                        .map(|field| field.value.clone())
                };
                match (find(before), find(after)) {
                    (Some(was), Some(now)) if was == now => {}
                    (Some(GffValue::Struct(was)), Some(GffValue::Struct(now))) => {
                        walk(&was, &now, &here, out);
                    }
                    (None, None) => {}
                    _ => out.push(here.to_string()),
                }
            }
        }

        let mut out = Vec::new();
        walk(&before.root, &after.root, &GffPath::default(), &mut out);
        out.sort();
        out
    }

    /// The guard. Whatever the recording says, a diff computed by reparsing
    /// the bytes this was opened from and walking both trees has to say the
    /// same thing.
    ///
    /// That derived diff is exactly what recording exists to avoid running on
    /// every redraw. Keeping it as a check rather than as the implementation
    /// is what catches a mutator that forgets to record.
    #[test]
    fn the_recorded_changes_match_a_diff_of_the_two_trees() {
        for (name, steps) in programs() {
            let mut document = with_a_list();
            for step in &steps {
                step(&mut document);
            }
            let opened = read_gff_from_bytes(&document.source).expect("the source parses");
            let derived = diff_trees(&opened, &document.gff);
            let recorded: Vec<String> =
                document.changes().keys().map(ToString::to_string).collect();
            assert_eq!(recorded, derived, "`{name}`: recorded and derived disagree");
            assert_eq!(
                document.is_edited(),
                !derived.is_empty(),
                "`{name}`: is_edited disagrees with the tree"
            );
        }
    }

    /// The revert control the change-review pane needs, done with the values
    /// and addresses the pane already holds.
    ///
    /// Reverting every row has to leave the document exactly as opened, which
    /// is the property that makes the pane trustworthy: the map empties rather
    /// than filling with rows that cancel out.
    #[test]
    fn every_row_reverts_through_the_address_it_is_keyed_by() {
        let mut document = open();
        document
            .set("Tag", "edited".to_owned())
            .expect("the fixture carries a Tag");
        document
            .insert("RakataMarker", 7_u32)
            .expect("a label the file does not carry");
        let removed_from = "LocalizedName";
        document
            .remove(removed_from)
            .expect("the fixture carries a localized name");

        let rows: Vec<(GffPath, Change)> = document
            .changes()
            .iter()
            .map(|(path, change)| (path.clone(), change.clone()))
            .collect();
        assert_eq!(rows.len(), 3, "one row per address touched");

        for (path, change) in rows {
            match (change.before, change.current) {
                (Some(before), Some(_)) => {
                    document.set_at(&path, before).expect("changed reverts");
                }
                (None, Some(_)) => {
                    document.remove_at(&path).expect("added reverts");
                }
                (Some(before), None) => {
                    document.insert_at(&path, before).expect("removed reverts");
                }
                (None, None) => panic!("`{path}` is a row that cannot occur"),
            }
        }

        assert!(
            !document.is_edited(),
            "reverting every row left {:?}",
            document.changes()
        );
        assert_eq!(
            document.save().expect("nothing to encode"),
            UTW,
            "the bytes came back but not the original ones"
        );
    }

    /// A typed read distinguishes the three ways it can fail.
    ///
    /// Collapsing "no such field" into "wrong type" is the tempting
    /// simplification and it is the one that makes a caller unable to tell an
    /// ordinary absence from a file that is not what it claimed to be.
    #[test]
    fn a_typed_read_keeps_absent_and_wrong_apart() {
        let document = open();

        // The fixture's tag is a string, and reads as one.
        let tag: String = document.get_as("Tag").expect("the fixture carries a tag");
        assert!(!tag.is_empty());

        // A label the file does not carry is a path failure.
        assert!(matches!(
            document.get_as::<String>("RakataMissing"),
            Err(GffDocumentError::Path(_))
        ));

        // A label it does carry, read as something it is not.
        assert!(matches!(
            document.get_as::<[f32; 4]>("Tag"),
            Err(GffDocumentError::WrongType { .. })
        ));

        // And text that is not an address at all is a third thing again.
        assert!(matches!(
            document.get_as::<String>("Tag["),
            Err(GffDocumentError::Syntax(_))
        ));
    }

    // -- A mutation at an ancestor of something already recorded --

    /// A tree with one list holding one struct, so a change can be recorded
    /// inside a container that is then replaced.
    fn nested() -> GffDocument {
        let mut element = GffStruct::new(0);
        element.push_field(gff_label!("Tag"), GffValue::String("a".to_owned()));
        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("Items"), GffValue::List(vec![element]));
        let bytes = write_gff_to_vec(&Gff {
            file_type: *b"GIT ",
            root,
        })
        .expect("a tree this small encodes");
        GffDocument::open(&bytes).expect("it reads back")
    }

    /// Removing a container drops what was recorded inside it.
    ///
    /// The map claims to describe what saving would do. An entry naming a
    /// field inside a list that has been removed describes a field the saved
    /// file will not contain, and the review pane built on this would show a
    /// row for it.
    #[test]
    fn removing_a_container_drops_what_was_recorded_inside_it() {
        let mut document = nested();
        let inner = GffPath::from_str("Items[0].Tag").expect("an address");
        let list = GffPath::from_str("Items").expect("an address");

        document
            .set_at(&inner, GffValue::String("b".to_owned()))
            .expect("the field takes it");
        document.remove_at(&list).expect("the list goes");

        let addresses: Vec<String> = document.changes().keys().map(ToString::to_string).collect();
        assert_eq!(
            addresses,
            ["Items"],
            "a change was left recorded inside a container that no longer exists"
        );
    }

    /// And the entry it leaves says what the *file* held, not what the tree
    /// held a moment before.
    ///
    /// `before` is documented as the opened file's value. Read off the tree it
    /// would carry the interim edit, which is a value the file never had, and
    /// anything later trusting `before` would inherit that.
    #[test]
    fn the_entry_left_behind_describes_the_opened_file() {
        let mut document = nested();
        let inner = GffPath::from_str("Items[0].Tag").expect("an address");
        let list = GffPath::from_str("Items").expect("an address");
        let as_opened = document.get("Items").expect("a list").clone();

        document
            .set_at(&inner, GffValue::String("b".to_owned()))
            .expect("the field takes it");
        document.remove_at(&list).expect("the list goes");

        let entry = document.changes().get(&list).expect("the list is recorded");
        assert_eq!(
            entry.before.as_ref(),
            Some(&as_opened),
            "`before` carried an edit the opened file never had"
        );
        assert_eq!(entry.current, None, "the list was removed");
    }

    /// Putting the container back leaves the document clean.
    ///
    /// A deliberate consequence rather than a side effect: reverting restores
    /// the file's version, so an edit made inside the container before it was
    /// deleted is discarded. The alternative is a `before` that means "what
    /// was there a moment ago" for containers and "what the file held"
    /// everywhere else, and one meaning across the map is worth more than the
    /// interim edit.
    #[test]
    fn reverting_the_container_restores_the_file_and_nothing_else() {
        let mut document = nested();
        let inner = GffPath::from_str("Items[0].Tag").expect("an address");
        let list = GffPath::from_str("Items").expect("an address");
        let source = document.save().expect("the opened bytes");

        document
            .set_at(&inner, GffValue::String("b".to_owned()))
            .expect("the field takes it");
        let removed = document.remove_at(&list).expect("the list goes");
        let restore = document
            .changes()
            .get(&list)
            .and_then(|change| change.before.clone())
            .expect("the list is recorded");
        drop(removed);

        document.insert_at(&list, restore).expect("it goes back");

        assert!(
            !document.is_edited(),
            "reverting left the document dirty: {:?}",
            document.changes().keys().collect::<Vec<_>>()
        );
        assert_eq!(
            document.save().expect("bytes"),
            source,
            "the file was not put back as it was opened"
        );
        assert_eq!(
            document.get("Items[0].Tag").expect("the field is back"),
            &GffValue::String("a".to_owned()),
            "the interim edit survived a revert that was meant to discard it"
        );
    }

    /// Appending to a list leaves what is recorded inside it alone.
    ///
    /// The case that stops this being a rule about addresses. An append and a
    /// removal are both mutations of the list, and only the removal moves what
    /// is already in it.
    #[test]
    fn appending_to_a_list_keeps_what_was_recorded_in_it() {
        let mut document = nested();
        document
            .set_at(
                &GffPath::from_str("Items[0].Tag").expect("an address"),
                GffValue::String("b".to_owned()),
            )
            .expect("the field takes it");

        document
            .push_element("Items", GffStruct::new(0))
            .expect("the list takes an element");

        assert!(
            document
                .changes()
                .contains_key(&GffPath::from_str("Items[0].Tag").expect("path")),
            "appending to a list discarded a change recorded inside it"
        );
    }
}