blockworx/document/

change.rs

// The caller is autosave, which is native-only until the web gets a writer of
// its own (todo.md P5). Building this for wasm regardless is what proves it
// stayed portable rather than quietly acquiring a native-only dependency.
#![cfg_attr(target_arch = "wasm32", allow(dead_code))]

//! What one edit touched, named so the name still means the same thing later.
//!
//! This is what fills a history entry's `changed` list, which is the whole
//! reason the history is searchable: "when did this route change?" becomes a
//! grep over small sidecars rather than a reconstruct-and-diff over every
//! snapshot.
//!
//! **Only blocks and pins carry stable ids.** Routes, texts, comments and images
//! are id-less on disk — the schema mints their ids on load — so a positional
//! `r7` would name a different route after a reload, which is exactly the
//! instability content-derived asset ids removed. So the comparison runs on the
//! session-local ids (cheap and exact, both documents being in memory) while the
//! *reporting* uses names that survive a reload: a route by its endpoints, and
//! an annotation by the block holding it.

use std::collections::BTreeSet;

use super::model::Document;
use super::{AutoRoute, Block, LineAnchor};
use crate::store::{PinId, RectId};

/// A pin, named by the block that owns it.
///
/// Deliberately *absolute*, unlike the on-disk anchor it is built from: there,
/// a route's own port is written `p1` because the `route` node sits inside its
/// owner's `block` node, so the owner is implied. A change set has no enclosing
/// context, and the one spelling has to work everywhere in it — which also means
/// a search for `b0:p1` finds both that pin's own edits and every route touching
/// it, rather than only one of the two.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
pub struct PinRef {
    pub block: RectId,
    pub pin: PinId,
}

impl PinRef {
    /// Resolve an anchor against the block owning the route carrying it. A
    /// route's own port *is* a pin of that block.
    fn resolve(owner: RectId, anchor: LineAnchor) -> Self {
        match anchor {
            LineAnchor::Port(pin) => PinRef { block: owner, pin },
            LineAnchor::Pin { block, pin } => PinRef { block, pin },
        }
    }
}

impl std::fmt::Display for PinRef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}:{}", self.block, self.pin)
    }
}

/// One thing an edit touched.
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)]
pub enum Change {
    /// The document's own properties — its name, or which block is the top.
    Document,
    /// A block: added, removed, or changed in itself. "In itself" includes its
    /// annotations (texts, comments, images, icon), which have no stable name of
    /// their own, so the block is the finest thing that can be reported.
    Block(RectId),
    /// One of a block's pins.
    Pin(PinRef),
    /// A route, named by its two endpoints. The owner is not part of the name:
    /// once both endpoints are absolute it adds nothing, since a route lives in
    /// the block containing both of them. A route whose endpoints moved reports
    /// under both its old and new names, so a search for either finds the edit.
    Route { from: PinRef, to: PinRef },
}

impl std::fmt::Display for Change {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Change::Document => write!(f, "document"),
            Change::Block(id) => write!(f, "{id}"),
            Change::Pin(pin) => write!(f, "{pin}"),
            Change::Route { from, to } => write!(f, "{from}->{to}"),
        }
    }
}

/// Everything one edit touched, in a stable order so two runs over the same
/// pair of documents produce the same list.
#[derive(Clone, PartialEq, Eq, Debug, Default)]
pub struct ChangeSet(BTreeSet<Change>);

impl ChangeSet {
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// The names a history sidecar records.
    pub fn names(&self) -> Vec<String> {
        self.0.iter().map(Change::to_string).collect()
    }

    fn insert(&mut self, change: Change) {
        self.0.insert(change);
    }
}

/// What changed between two versions of a document.
///
/// Empty means they are equivalent, which is the same judgement `PartialEq`
/// makes — a settled edit that changed nothing produces no history entry.
pub fn changed(prev: &Document, next: &Document) -> ChangeSet {
    let mut set = ChangeSet::default();
    if document_itself_differs(prev, next) {
        set.insert(Change::Document);
    }
    for id in prev.blocks.keys().chain(next.blocks.keys()).copied() {
        match (prev.blocks.get(&id), next.blocks.get(&id)) {
            // Added or removed: the block itself is the change, and its pins and
            // routes came or went with it rather than being separate edits.
            (None, Some(_)) | (Some(_), None) => set.insert(Change::Block(id)),
            (Some(before), Some(after)) => compare_block(id, before, after, &mut set),
            (None, None) => unreachable!("the id came from one of the two maps"),
        }
    }
    set
}

/// Whether the document's own properties differ.
///
/// Destructured rather than field-accessed: a field added to [`Document`] is
/// then a compile error here instead of a change that silently stops being
/// reported.
fn document_itself_differs(prev: &Document, next: &Document) -> bool {
    let Document {
        name,
        top_id,
        blocks: _,
    } = prev;
    name != &next.name || top_id != &next.top_id
}

fn compare_block(id: RectId, before: &Block, after: &Block, set: &mut ChangeSet) {
    if block_itself_differs(before, after) {
        set.insert(Change::Block(id));
    }
    for pin in before.pins.keys().chain(after.pins.keys()).copied() {
        if before.pins.get(&pin) != after.pins.get(&pin) {
            set.insert(Change::Pin(PinRef { block: id, pin }));
        }
    }
    for route in before.routes.keys().chain(after.routes.keys()) {
        let (was, now) = (before.routes.get(route), after.routes.get(route));
        if was == now {
            continue;
        }
        // Both names when the endpoints moved: searching for either the old or
        // the new one should find the edit that moved it.
        for r in [was, now].into_iter().flatten() {
            set.insert(route_change(id, r));
        }
    }
}

fn route_change(owner: RectId, route: &AutoRoute) -> Change {
    Change::Route {
        from: PinRef::resolve(owner, route.start()),
        to: PinRef::resolve(owner, route.finish()),
    }
}

/// Whether the block's own properties differ — everything except its pins and
/// routes, which are reported at their own granularity.
///
/// Destructured for the same reason as [`document_itself_differs`]: a new field
/// on [`Block`] must not quietly become invisible to the history.
fn block_itself_differs(before: &Block, after: &Block) -> bool {
    let Block {
        inner,
        decorations,
        pins: _,
        children,
        routes: _,
        texts,
        comments,
        images,
        icon,
        role,
        locked,
    } = before;
    inner != &after.inner
        || decorations != &after.decorations
        || children != &after.children
        || texts != &after.texts
        || comments != &after.comments
        || images != &after.images
        || icon != &after.icon
        || role != &after.role
        || locked != &after.locked
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::document::schema_convert::{load, to_kdl};
    use crate::presentation::store::IdMapExt as _;
    use crate::store::{RectId, RouteId};

    /// Two blocks wired to a third's ports, so there are pins and routes to
    /// report separately from the blocks holding them.
    const SRC: &str = r#"
top "b0"
block "b0" x=0 y=0 w=40 h=30 {
    pin "p1" "in" loc="w1"
    pin "p2" "out" loc="e1"
    route "p1" "b1:p1"
    route "p2" "b2:p1"
    children "b1" "b2"
}
block "b1" x=5 y=5 w=8 h=8 { pin "p1" "a" loc="e1" }
block "b2" x=5 y=20 w=8 h=8 { pin "p1" "b" loc="e1" }
"#;

    fn doc() -> Document {
        load(SRC, "t.kdl").expect("the fixture parses")
    }

    fn b(n: usize) -> RectId {
        RectId::nth_default(n)
    }

    fn names(prev: &Document, next: &Document) -> Vec<String> {
        changed(prev, next).names()
    }

    #[test]
    fn an_unchanged_document_reports_nothing() {
        let d = doc();
        assert!(changed(&d, &d.clone()).is_empty());
    }

    #[test]
    fn moving_a_block_reports_only_that_block() {
        let before = doc();
        let mut after = before.clone();
        let block = after.blocks.get_mut(&b(1)).expect("b1");
        block.inner.min.x += 3;
        assert_eq!(names(&before, &after), vec!["b1"]);
    }

    /// A pin is reported at its own granularity, not as a change to the block
    /// carrying it — "when did this pin get renamed?" is a question the history
    /// should be able to answer.
    #[test]
    fn renaming_a_pin_reports_the_pin_not_the_block() {
        let before = doc();
        let mut after = before.clone();
        let pin = *after.blocks[&b(1)].pins.keys().next().expect("a pin");
        after
            .blocks
            .get_mut(&b(1))
            .expect("b1")
            .pins
            .get_mut(&pin)
            .expect("the pin")
            .name = "renamed".to_string();
        assert_eq!(names(&before, &after), vec![format!("b1:{pin}")]);
    }

    /// A block arriving or leaving is one change, not one per pin and route it
    /// happened to carry.
    #[test]
    fn adding_and_removing_a_block_reports_the_block_alone() {
        let before = doc();
        let mut after = before.clone();
        // What a real delete does: drop the block *and* unlink it from its
        // parent, so the parent's child list is a change of its own.
        after.blocks.shift_remove(&b(2));
        after
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .children
            .shift_remove(&b(2));
        assert_eq!(names(&before, &after), vec!["b0", "b2"]);

        let mut grown = before.clone();
        let added = grown.blocks.insert_value(Block::default());
        assert_eq!(names(&before, &grown), vec![added.to_string()]);
    }

    /// Annotations carry no stable name of their own, so the block holding them
    /// is the finest thing that can be reported.
    #[test]
    fn an_annotation_reports_the_block_holding_it() {
        use crate::document::TextBox;
        let before = doc();
        let mut after = before.clone();
        after
            .blocks
            .get_mut(&b(1))
            .expect("b1")
            .texts
            .insert_value(TextBox {
                text: "a note".to_string(),
                anchor: crate::document::GridPos { x: 1, y: 1 },
                role: None,
            });
        assert_eq!(names(&before, &after), vec!["b1"]);
    }

    #[test]
    fn renaming_the_document_reports_the_document() {
        let before = doc();
        let mut after = before.clone();
        after.name = Some("CT Scanner".to_string());
        assert_eq!(names(&before, &after), vec!["document"]);
    }

    /// A route is named by the block owning it and by its endpoints — never by
    /// its id, which is minted on load.
    #[test]
    fn a_route_is_named_by_its_endpoints() {
        let before = doc();
        let mut after = before.clone();
        let route = *after.blocks[&b(0)].routes.keys().next().expect("a route");
        after
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .routes
            .get_mut(&route)
            .expect("the route")
            .set_role(Some(3));

        let reported = names(&before, &after);
        assert_eq!(reported, vec!["b0:p1->b1:p1"]);
        assert!(
            !reported.iter().any(|n| n.contains(&route.to_string())),
            "the route's session-local id leaked into {reported:?}"
        );
    }

    /// Re-pointing a route reports both names, so a search for either the old or
    /// the new endpoint finds the edit that moved it.
    #[test]
    fn a_repointed_route_reports_both_names() {
        let before = doc();
        let mut after = before.clone();
        let route = *after.blocks[&b(0)].routes.keys().next().expect("a route");
        let elsewhere = LineAnchor::Pin {
            block: b(2),
            pin: crate::store::PinId::nth_default(1),
        };
        after
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .routes
            .get_mut(&route)
            .expect("the route")
            .finish = elsewhere;

        assert_eq!(
            names(&before, &after),
            vec!["b0:p1->b1:p1", "b0:p1->b2:p1"],
            "both the old and the new endpoint should be findable"
        );
    }

    /// The property the endpoint naming exists for. Route ids are minted on
    /// load, so they shift when an earlier route is removed — a positional name
    /// would mean a *different* route after a reload. The name must not.
    #[test]
    fn a_route_name_survives_a_reload_that_shifts_its_id() {
        let full = doc();
        let mut trimmed = full.clone();
        let first = *trimmed.blocks[&b(0)].routes.keys().next().expect("a route");
        trimmed
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .routes
            .shift_remove(&first);

        let reloaded = load(&to_kdl(&trimmed), "t.kdl").expect("the round trip parses");

        let ids =
            |d: &Document| -> Vec<RouteId> { d.blocks[&b(0)].routes.keys().copied().collect() };
        // Proves the precondition: without it this test would pass vacuously.
        assert_ne!(
            ids(&trimmed),
            ids(&reloaded),
            "the surviving route kept its id, so nothing is being tested"
        );

        let recolor = |d: &Document| {
            let mut next = d.clone();
            let r = *next.blocks[&b(0)].routes.keys().next().expect("a route");
            next.blocks
                .get_mut(&b(0))
                .expect("b0")
                .routes
                .get_mut(&r)
                .expect("the route")
                .set_role(Some(5));
            next
        };

        assert_eq!(
            names(&trimmed, &recolor(&trimmed)),
            names(&reloaded, &recolor(&reloaded)),
            "the same route reported under different names either side of a reload"
        );
    }

    /// The reason a route's endpoints are absolute rather than owner-relative
    /// (`b0:p1`, not the on-disk `p1`): one pin has one spelling, so a single
    /// search finds both the pin's own edits and every route touching it.
    #[test]
    fn a_pin_is_spelled_the_same_way_in_a_route_name_as_on_its_own() {
        let before = doc();

        // The pin's own edit.
        let mut renamed = before.clone();
        let pin = *renamed.blocks[&b(0)].pins.keys().next().expect("a pin");
        renamed
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .pins
            .get_mut(&pin)
            .expect("the pin")
            .name = "renamed".to_string();
        let pin_name = names(&before, &renamed);

        // An edit to a route that lands on that same pin. It is a `Port` anchor
        // there — the form the on-disk document writes bare as `p1`.
        let mut recolored = before.clone();
        let route = *recolored.blocks[&b(0)]
            .routes
            .keys()
            .next()
            .expect("a route");
        assert_eq!(
            recolored.blocks[&b(0)].routes[&route].start(),
            LineAnchor::Port(pin),
            "the fixture's first route should start at that port"
        );
        recolored
            .blocks
            .get_mut(&b(0))
            .expect("b0")
            .routes
            .get_mut(&route)
            .expect("the route")
            .set_role(Some(3));
        let route_name = names(&before, &recolored);

        let token = &pin_name[0];
        assert_eq!(token, &format!("b0:{pin}"));
        assert!(
            route_name[0].starts_with(&format!("{token}->")),
            "searching for {token:?} would miss the route: {route_name:?}"
        );
    }
}