blockworx/edit/

restore.rs

//! Inventory row "Restore rev": the ops that carry the head document back
//! to what it held at some earlier rev.
//! Rationale: `docs/single-author-playbook.md`, Phase 4.
//!
//! The log is never rewritten — restoring is one ordinary forward commit,
//! so the trail records that the author went back rather than pretending
//! they never went forward. What makes that a *diff* rather than a reload
//! is D10: entity ids are uuids drawn from one space across the whole log,
//! so "the block that was at rev N" and "the block at head" are the same
//! entity, and the difference between them is per-entity.
//!
//! Per entity, then: alive at N and absent at head is a create, alive at N
//! and tombstoned at head is a restore, alive at head and not at N is a
//! delete, and everything alive on both sides has its registers carried
//! over by [`Entity::updates_toward`] — generated from the field list, so
//! a register added tomorrow is restored without anyone remembering to
//! come back here.

use ahash::{HashMap, HashSet, HashSetExt as _};
use blockworx_doc::{
    block_model::Live,
    commit::CommitBuilder,
    document::Document,
    entity::Entity,
    opcode::{Crud, OpCodes},
};

/// The label a restore commit lands under. Named here because the panel's
/// button and the commit have to agree, and the log is what the user reads
/// back.
pub fn label(rev: blockworx_doc::rev::Rev) -> String {
    format!("Restore rev {}", rev.get())
}

/// Carry `head` to `target`. Pushes nothing when the two already agree, so
/// restoring the rev you are already at seals to no commit.
pub fn restore(head: &Document, target: &Document, builder: &mut CommitBuilder) {
    // Payloads first: an image or icon that comes back needs its bytes in
    // the same commit, and an asset is create-only, so "already there" is
    // simply nothing to push.
    for (hash, asset) in target.assets() {
        if head.asset(&hash).is_none() {
            builder.push(OpCodes::Asset(hash, asset.clone()));
        }
    }
    for update in head
        .title_block()
        .updates_toward(&target.title_block().to_init())
    {
        builder.push(OpCodes::Document(update));
    }
    kind(head.blocks(), target.blocks(), OpCodes::Block, builder);
    kind(head.pins(), target.pins(), OpCodes::Pin, builder);
    kind(head.routes(), target.routes(), OpCodes::Route, builder);
    kind(
        head.route_labels(),
        target.route_labels(),
        OpCodes::RouteLabel,
        builder,
    );
    kind(head.texts(), target.texts(), OpCodes::Text, builder);
    kind(head.areas(), target.areas(), OpCodes::Area, builder);
    kind(head.images(), target.images(), OpCodes::Image, builder);
}

/// One entity kind's whole diff, in id order so a restore of the same two
/// documents always emits the same ops.
fn kind<'a, I, E: Entity + 'a>(
    head: impl Iterator<Item = (I, &'a Live<E>)>,
    target: impl Iterator<Item = (I, &'a Live<E>)>,
    op: impl Fn(I, Crud<E::Init, E::Update>) -> OpCodes,
    builder: &mut CommitBuilder,
) where
    I: Copy + Eq + std::hash::Hash + Ord,
{
    let head: HashMap<I, &Live<E>> = head.collect();
    let mut target: Vec<(I, &Live<E>)> = target.collect();
    target.sort_unstable_by_key(|(id, _)| *id);
    let mut seen = HashSet::with_capacity(target.len());

    for (id, want) in target {
        seen.insert(id);
        match (head.get(&id), want.is_alive()) {
            // Never existed at head, and the fold cannot produce that from
            // a prefix — but a diff that only works on prefixes is a diff
            // waiting to be wrong.
            (None, true) => builder.push(op(id, Crud::Create(want.as_ref().to_init()))),
            (None, false) => {}
            (Some(have), true) => {
                if !have.is_alive() {
                    builder.push(op(id, Crud::Restore));
                }
                let init = want.as_ref().to_init();
                for update in have.as_ref().updates_toward(&init) {
                    builder.push(op(id, Crud::Update(update)));
                }
            }
            (Some(have), false) => {
                if have.is_alive() {
                    builder.push(op(id, Crud::Delete));
                }
            }
        }
    }
    // Born after the rev being restored: tombstoned, never erased.
    let mut born_since: Vec<I> = head
        .iter()
        .filter(|(id, live)| live.is_alive() && !seen.contains(*id))
        .map(|(id, _)| *id)
        .collect();
    born_since.sort_unstable();
    for id in born_since {
        builder.push(op(id, Crud::Delete));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::edit::harness as h;
    use crate::store::tests::fixture as fx_store;
    use blockworx_doc::{
        commit::Commit,
        fixtures::{block_id, pin_id},
        repo::Repo,
    };

    /// The oracle: two documents whose *projections* agree hold the same
    /// diagram. `content_hash` cannot serve here — it covers the rev and
    /// every register's write order, and a restore is a forward commit, so
    /// the two can never be bit-equal however right the restore is.
    fn projected(repo: &Repo) -> String {
        crate::schema::project::to_json(repo)
    }

    /// Fold `commits`, then restore the document as it stood after the
    /// first `prefix` of them, and report the repos on both sides.
    fn restore_to_prefix(commits: &[Commit], prefix: usize) -> (Repo, Repo) {
        let head = Repo::folding(commits).expect("the history folds");
        let target = Repo::folding(&commits[..prefix]).expect("the prefix folds");
        let mut builder = CommitBuilder::new(label(target.rev()));
        restore(head.document(), target.document(), &mut builder);
        let mut restored = head;
        if let Some(commit) = builder.seal() {
            restored.submit(commit).expect("the restore folds");
        }
        (restored, target)
    }

    fn assert_restores(commits: &[Commit], prefix: usize) {
        let (restored, target) = restore_to_prefix(commits, prefix);
        assert_eq!(
            projected(&restored),
            projected(&target),
            "the restored head is not the document rev {} held",
            target.rev().get(),
        );
    }

    fn block(byte: u8, name: &str) -> Commit {
        fx_store::commit("Added a block", vec![fx_store::block_create(byte, name)])
    }

    /// The three lifecycle arms in one history: a block that survives, a
    /// block born after the rev (so the restore must tombstone it), and a
    /// block deleted before head (so the restore must bring it back).
    fn history() -> Vec<Commit> {
        vec![
            block(1, "Adder"),
            block(2, "Summer"),
            // rev 2 is the target below: both blocks alive, unrenamed.
            fx_store::commit("Renamed it", vec![fx_store::block_rename(1, "Renamed")]),
            fx_store::commit(
                "Deleted it",
                vec![OpCodes::Block(block_id(2), Crud::Delete)],
            ),
            block(3, "Born later"),
        ]
    }

    #[test]
    fn a_restore_carries_deletes_creates_and_renames_back_together() {
        let commits = history();
        let (restored, target) = restore_to_prefix(&commits, 2);

        assert_eq!(
            restored.log().len(),
            commits.len() + 1,
            "a restore is one forward commit, never a rewrite",
        );
        assert!(
            restored
                .document()
                .block(&block_id(2))
                .expect("the deleted block is still an entity")
                .is_alive(),
            "the block deleted after the rev did not come back",
        );
        assert!(
            !restored
                .document()
                .block(&blockworx_doc::fixtures::block_id(3))
                .expect("the later block is still an entity")
                .is_alive(),
            "the block born after the rev was not tombstoned",
        );
        assert_eq!(
            restored
                .document()
                .block(&block_id(1))
                .expect("the surviving block")
                .as_ref()
                .title
                .name
                .as_ref(),
            "Adder",
            "the rename made after the rev was not carried back",
        );
        assert_eq!(projected(&restored), projected(&target));
    }

    /// Every rev of the same history, so no arm of the diff is only ever
    /// exercised from one direction.
    #[test]
    fn every_rev_of_a_history_restores_to_itself() {
        let commits = history();
        for prefix in 0..=commits.len() {
            assert_restores(&commits, prefix);
        }
    }

    /// Restoring the rev you are already at must author nothing — the
    /// no-op rule every emitter follows, and what keeps a stray click out
    /// of the audit trail.
    #[test]
    fn restoring_the_head_seals_to_nothing() {
        let head = Repo::folding(&history()).expect("the history folds");
        let mut builder = CommitBuilder::new("Restore".to_owned());
        restore(head.document(), head.document(), &mut builder);
        h::seals_to_nothing(builder);
    }

    /// A pin and the wire on it: a restore that brings a route back has to
    /// bring its endpoints back in the same commit, or the fold refuses
    /// the whole thing.
    #[test]
    fn a_wire_and_its_endpoints_come_back_in_one_commit() {
        use crate::path::Scope;
        use crate::widget::test_fixtures as fx;
        use blockworx_doc::values::PinSide;

        let commits = vec![
            fx_store::commit(
                "Built a scene",
                vec![
                    fx::block_in(
                        1,
                        Scope::Root,
                        egui::Rect::from_min_max(egui::pos2(0.0, 0.0), egui::pos2(60.0, 150.0)),
                    ),
                    fx::block_in(
                        2,
                        Scope::Root,
                        egui::Rect::from_min_max(egui::pos2(180.0, 0.0), egui::pos2(240.0, 150.0)),
                    ),
                    fx::pin(3, 1, PinSide::East, 0),
                    fx::pin(4, 2, PinSide::West, 0),
                    fx::route(5, Scope::Root, 3, 4, &[(20, 4)]),
                ],
            ),
            // Deleting the pin takes the wire with it, so the restore must
            // put both back.
            fx_store::commit(
                "Deleted a pin and its wire",
                vec![
                    OpCodes::Route(blockworx_doc::fixtures::route_id(5), Crud::Delete),
                    OpCodes::Pin(pin_id(3), Crud::Delete),
                ],
            ),
        ];
        let (restored, target) = restore_to_prefix(&commits, 1);
        assert!(
            restored
                .document()
                .route(&blockworx_doc::fixtures::route_id(5))
                .expect("the route is still an entity")
                .is_alive(),
            "the wire did not come back with its pin",
        );
        assert_eq!(projected(&restored), projected(&target));
    }
}