blockworx_doc/

repo.rs

//! The document, in one type: the folded [`Document`] and the commit log
//! it folds.
//! Rationale: `docs/single-author-playbook.md`.

use crate::{
    commit::Commit,
    document::{Document, FoldError},
    rev::Rev,
    trail::{Direction, Entry, JournalAs, Trail},
};

/// The document and everything that writes it. A commit is folded and
/// appended inside [`Self::submit`] or [`Self::restore`], which are the
/// only doors: there is no queue, no pending head, and no rev the caller
/// can hold that the log does not.
///
/// The [`Trail`] a session steps through is *beside* this rather than in
/// it (`docs/log-vs-snapshot.md`): what a step adopts is a document
/// this type cannot reach on its own — a rev copy on disk, or a fold of a
/// prefix of its own log — so the session owns both and hands them to
/// each other.
#[derive(Default)]
pub struct Repo {
    document: Document,
    log: Vec<Commit>,
}

impl Repo {
    /// A repo standing on a document somebody else read — the head rev
    /// file a container opens on. Its log is this session's own commits
    /// and starts empty: what came before is on disk, in rows and rev
    /// files, not in memory (`docs/log-vs-snapshot.md`).
    pub fn at(document: Document) -> Self {
        Self {
            document,
            log: Vec::new(),
        }
    }

    /// Fold `commits` into a fresh repo, trailing nothing — a log that
    /// is already the document's past, not a session's edits.
    ///
    /// # Errors
    /// The fold's refusal, naming the first commit this build will not take.
    pub fn folding(commits: &[Commit]) -> Result<Self, FoldError> {
        let mut repo = Self::default();
        for commit in commits {
            repo.fold_one(commit.clone())?;
        }
        Ok(repo)
    }

    /// Fold one more commit of the document's past in, trailing nothing,
    /// and hand back what it folded to.
    ///
    /// The returned document is what makes a *verified* replay one fold
    /// instead of two: the durable log stamps every record with the
    /// document it produced, and a loader that could not see the
    /// intermediate values would have to fold once to check them and
    /// again to build the repo.
    ///
    /// # Errors
    /// The fold's refusal, leaving the repo as it stood.
    pub fn fold_one(&mut self, commit: Commit) -> Result<&Document, FoldError> {
        self.document = self.document.try_apply(&commit)?;
        self.log.push(commit);
        Ok(&self.document)
    }

    /// What the editor draws.
    pub fn document(&self) -> &Document {
        &self.document
    }

    pub fn rev(&self) -> Rev {
        self.document.rev()
    }

    /// The whole history, oldest first. `log[i]` holds `Rev(i + 1)` —
    /// contiguous because a refused commit consumes no rev, which is what
    /// lets the log be a `Vec`.
    pub fn log(&self) -> &[Commit] {
        &self.log
    }

    /// The revs assigned after `rev`, oldest first — for a caller whose own
    /// history owes a step to each commit this repo has taken since it last
    /// looked. Empty for a rev at or beyond the head, which is what lets a
    /// caller carry a watermark across a document swap without arithmetic of
    /// its own.
    pub fn revs_after(&self, rev: Rev) -> Vec<Rev> {
        let taken = self.rev().get().saturating_sub(rev.get()) as usize;
        std::iter::successors(Some(rev.next()), |rev| Some(rev.next()))
            .take(taken)
            .collect()
    }

    /// Fold, append, and record the edit on `trail`, in that order: a
    /// refused commit consumes no rev and leaves neither the log nor the
    /// trail touched.
    ///
    /// The trail comes in rather than living here so that an edit cannot
    /// be logged without standing on it — [`Self::fold_one`] is the door
    /// for a past nobody may take back.
    ///
    /// # Errors
    /// The fold's refusal.
    pub fn submit(&mut self, commit: Commit, trail: &mut Trail) -> Result<Rev, FoldError> {
        let rev = self.fold_one(commit)?.rev();
        trail.record(rev, JournalAs::Edit);
        Ok(rev)
    }

    /// Take the step `entry` names: adopt `target` — the document the
    /// session stood on before the record at `entry.rev` was written — and
    /// log it as a commit of its own, so a step back stays *in* the
    /// history rather than erasing what it crossed.
    ///
    /// The commit carries no ops. A rev was validated by the fold when it
    /// was written, so restoring it needs no second fold and no inverse to
    /// build one from (`docs/log-vs-snapshot.md`): what a step records
    /// is `label`, which the caller reads off the record it is moving.
    ///
    /// The adopted document keeps the one thing a session accumulates
    /// rather than holds — the allocator's marks, which must never fall
    /// (see `Document::restored_at`). Payloads it does not: they live in
    /// the store, and a rev that references one gets it back when it is
    /// read.
    pub fn restore(&mut self, trail: &mut Trail, step: Restoring<'_>) -> Rev {
        let Restoring {
            entry,
            direction,
            target,
            label,
        } = step;
        let rev = self.rev().next();
        let mut adopted = target;
        adopted.restored_at(rev, &self.document);
        self.document = adopted;
        self.log.push(Commit::new(
            format!("{} {label}", direction.verb()),
            Vec::new(),
        ));
        trail.record(rev, direction.journal(entry.rev));
        rev
    }
}

/// One history step, as [`Repo::restore`] takes it: which entry is being
/// stepped, which way, the document that step adopts, and what the record
/// it moves is called.
pub struct Restoring<'a> {
    pub entry: Entry,
    pub direction: Direction,
    /// The document the session stood on before the record at
    /// `entry.rev` was written — read back from wherever this session
    /// keeps its rev copies.
    pub target: Document,
    pub label: &'a str,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fixtures::{block_id, commit, pin_id, projection, rev};
    use crate::opcode::{Crud, OpCodes};
    use crate::trail::UndoRefusal;
    use crate::{
        block_model::{Block, BlockUpdate, Icon, Label, Pin},
        geometry::{FracVal, GridPoint, GridRect, GridSize, PinSlot},
        id::BlockId,
        values::{LabelSide, PinDir, Role},
    };
    use std::collections::BTreeMap;

    fn rect(x: i32, y: i32) -> GridRect {
        GridRect {
            top_left: GridPoint { x, y },
            size: GridSize { w: 4, h: 4 },
        }
    }

    fn label_init(name: String) -> Label {
        Label {
            name,
            side: LabelSide::default(),
            offset: FracVal::default(),
            hidden: false,
        }
    }

    fn block_create(n: u32) -> OpCodes {
        OpCodes::Block(
            block_id(n),
            Crud::Create(Block {
                parent: BlockId::NULL,
                rect: rect(0, 0),
                locked: false,
                role: Role::default(),
                title: label_init(format!("b{n}")),
                type_label: label_init(String::new()),
                icon: Icon::default(),
            }),
        )
    }

    fn resize(n: u32, to: GridRect) -> OpCodes {
        OpCodes::Block(block_id(n), Crud::Update(BlockUpdate::Rect(to)))
    }

    /// A pin whose owner block does not exist — refused by the fold's
    /// commit-end validation.
    fn orphan_pin(n: u32) -> OpCodes {
        OpCodes::Pin(
            pin_id(n),
            Crud::Create(Pin {
                owner: block_id(200),
                name: format!("p{n}"),
                type_name: String::new(),
                tag: String::new(),
                tag_hidden: false,
                rect: rect(0, 0),
                slot: PinSlot::default(),
                dir: PinDir::default(),
                port_accent: Role::default(),
                flip_lr: false,
            }),
        )
    }

    /// A session holding one top-level block, submitted rather than
    /// seeded, so the create stands on the trail.
    fn one_block() -> Session {
        let mut live = Session::default();
        live.edit("Added a block", vec![block_create(1)]);
        live
    }

    /// The log's shape, stated once: every accepted commit takes the next
    /// rev, and the rev a submission returns is the position its commit
    /// occupies in the log.
    #[test]
    fn submit_assigns_contiguous_revs() {
        let mut live = Session::default();
        assert_eq!(
            live.repo.rev(),
            Rev::ZERO,
            "an empty document holds no position",
        );

        let assigned: Vec<Rev> = (1..=3)
            .map(|n| live.edit("Added a block", vec![block_create(n)]))
            .collect();
        let repo = &live.repo;

        assert_eq!(
            assigned.iter().map(|rev| rev.get()).collect::<Vec<_>>(),
            [1, 2, 3],
        );
        assert_eq!(repo.rev(), assigned[2], "the head is the last assignment");
        assert_eq!(repo.log().len(), 3);
        assert_eq!(repo.revs_after(Rev::ZERO), assigned);
        assert_eq!(repo.revs_after(assigned[1]), [assigned[2]]);
        assert!(repo.revs_after(repo.rev()).is_empty(), "caught up");
        assert!(
            repo.revs_after(repo.rev().next()).is_empty(),
            "and a rev beyond the head does not panic",
        );
    }

    #[test]
    fn a_commit_the_fold_refuses_takes_no_rev_and_trails_nothing() {
        let mut live = Session::default();
        let before = live.repo.document().clone();

        assert!(
            live.repo
                .submit(commit("Orphan pin", vec![orphan_pin(3)]), &mut live.trail)
                .is_err(),
        );
        assert_eq!(live.repo.rev(), Rev::ZERO, "a refusal mints no rev");
        assert!(live.repo.log().is_empty(), "and logs nothing");
        assert!(!live.trail.can_undo(), "and stands on nothing");
        assert_eq!(live.repo.document(), &before, "the document is untouched");

        let next = live.edit("Added a block", vec![block_create(1)]);
        assert_eq!(
            next,
            Rev::ZERO.next(),
            "the next commit takes the rev the refusal did not consume",
        );
    }

    /// A step names the commit it means, and one that names anything but the
    /// top is refused rather than silently inverting its neighbour.
    #[test]
    fn a_step_naming_anything_but_the_top_is_refused() {
        let mut live = one_block();
        let first = live.trail.next_undo().expect("the create stands");
        let second = live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        assert_eq!(
            live.trail.undo_revs(),
            [first, second],
            "precondition: the named edit sits below the top",
        );

        assert_eq!(
            live.stepping(first, Direction::Undo),
            Err(UndoRefusal::Stale { top: second }),
        );
        assert_eq!(live.trail.undo_depth(), 2, "and the refusal took no step");
        assert!(
            live.stepping(second, Direction::Undo).is_ok(),
            "the step naming the top is taken",
        );
    }

    /// A spent stack refuses rather than reporting a step it did not take.
    #[test]
    fn a_step_on_a_spent_stack_is_refused() {
        let mut live = one_block();
        let only = live.trail.next_undo().expect("the setup edit stands");
        live.undo();
        assert_eq!(live.trail.next_undo(), None);
        assert_eq!(
            live.stepping(only, Direction::Undo),
            Err(UndoRefusal::Spent),
        );
    }

    /// Undo and redo take revs of their own — the log records what was
    /// taken back rather than losing it — and each adopts the document the
    /// session stood on, so a round trip returns to the value it held.
    #[test]
    fn undo_and_redo_travel_as_ordinary_commits_and_round_trip_the_document() {
        let mut live = one_block();
        let placed = live.repo.document().clone();
        let edit = live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        let moved = live.repo.document().clone();
        assert_ne!(placed, moved, "the edit must be observable");

        let undone = live.undo();
        assert_eq!(undone, edit.next(), "the step took the next rev");
        assert_eq!(
            live.repo.document(),
            &placed,
            "undo restored the document the create left",
        );
        assert_eq!(
            live.repo.log().last().map(Commit::label),
            Some("Undo Moved it"),
            "a step's commit is its label and nothing else",
        );
        assert!(
            live.repo
                .log()
                .last()
                .is_some_and(|step| step.ops().is_empty()),
            "a step carries no ops: the rev copy is what it adopts",
        );
        assert_eq!(
            live.trail.standing(),
            edit.prev().expect("an edit before it")
        );
        assert!(live.trail.can_redo());

        let redone = live.redo();
        assert_eq!(redone, undone.next());
        assert_eq!(
            live.repo.document(),
            &moved,
            "and a round trip lands on the value the edit produced",
        );
        assert_eq!(
            live.trail.standing(),
            edit,
            "and the trail stands where it started",
        );
        assert!(live.trail.can_undo());
        assert!(!live.trail.can_redo(), "the redo future is spent");
    }

    #[test]
    fn a_fresh_edit_abandons_the_redo_future() {
        let mut live = one_block();
        live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        live.undo();
        assert!(live.trail.can_redo());

        live.edit("Moved it elsewhere", vec![resize(1, rect(7, 7))]);
        assert!(!live.trail.can_redo(), "a new edit forks the history");
    }

    #[test]
    fn folding_a_log_reproduces_the_document_that_wrote_it() {
        let mut live = Session::default();
        for n in 1..=3 {
            live.edit("Added a block", vec![block_create(n)]);
        }

        let replayed = Repo::folding(live.repo.log()).expect("the log folds");
        assert_eq!(replayed.rev(), live.repo.rev());
        assert_eq!(
            replayed.document(),
            live.repo.document(),
            "a replayed log reproduces the document exactly",
        );
    }

    // ── Trail reconstruction ─────────────────────────────────────────────

    type Projection = Vec<(BlockId, BlockId, GridRect, String)>;

    /// A session at this crate's altitude: the repo, the trail beside it,
    /// and the record kinds its log would carry — what a durable store
    /// writes beside each commit, and all a replay is given.
    ///
    /// It answers "where did I stand" from its own copy of the document
    /// at every rev, which is what a session with no files beside it does
    /// (`docs/log-vs-snapshot.md`, in memory).
    #[derive(Default)]
    struct Session {
        repo: Repo,
        trail: Trail,
        kinds: Vec<JournalAs>,
        revs: BTreeMap<Rev, Document>,
        labels: BTreeMap<Rev, String>,
    }

    impl Session {
        fn edit(&mut self, label: &str, ops: Vec<OpCodes>) -> Rev {
            let rev = self
                .repo
                .submit(commit(label, ops), &mut self.trail)
                .expect("the edit folds");
            self.took(rev, JournalAs::Edit, label.to_owned());
            rev
        }

        fn took(&mut self, rev: Rev, kind: JournalAs, label: String) {
            self.kinds.push(kind);
            self.revs.insert(rev, self.repo.document().clone());
            self.labels.insert(rev, label);
        }

        fn at(&self, rev: Rev) -> Document {
            self.revs.get(&rev).cloned().unwrap_or_default()
        }

        fn stepping(&mut self, edit: Rev, direction: Direction) -> Result<Rev, UndoRefusal> {
            let entry = self.trail.stepping(edit, direction)?;
            let target = self.at(entry.restores);
            let label = self.labels[&edit].clone();
            let rev = self.repo.restore(
                &mut self.trail,
                Restoring {
                    entry,
                    direction,
                    target,
                    label: &label,
                },
            );
            self.took(
                rev,
                direction.journal(edit),
                format!("{} {label}", direction.verb()),
            );
            Ok(rev)
        }

        fn undo(&mut self) -> Rev {
            let of = self.trail.next_undo().expect("a step to take back");
            self.stepping(of, Direction::Undo)
                .expect("the top names itself")
        }

        fn redo(&mut self) -> Rev {
            let of = self.trail.next_redo().expect("a step to put back");
            self.stepping(of, Direction::Redo)
                .expect("the top names itself")
        }

        /// What reopening this session's container hands back: the log
        /// folded record by record, with the trail rebuilt from the kinds
        /// alone.
        fn reopened(&self) -> Session {
            let mut reopened = Session::default();
            for (nth, kind) in self.kinds.iter().enumerate() {
                let at = rev(nth as u64 + 1);
                reopened.trail.record(at, *kind);
                reopened.kinds.push(*kind);
                reopened.revs.insert(at, self.at(at));
                reopened.labels.insert(at, self.labels[&at].clone());
            }
            reopened.repo = Repo::at(self.at(self.repo.rev()));
            reopened
        }
    }

    /// At this crate's altitude: the trail a reopened document carries is
    /// the one its session closed with, entry for entry.
    #[test]
    fn a_replayed_log_rebuilds_the_trail_its_session_had() {
        let mut live = Session::default();
        live.edit("Added a block", vec![block_create(1)]);
        live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        live.edit("Added another", vec![block_create(2)]);
        live.undo();
        live.undo();
        live.redo();
        assert_eq!(
            (live.trail.undo_depth(), live.trail.redo_depth()),
            (2, 1),
            "precondition: the session closes with depth both ways",
        );

        let reopened = live.reopened();
        assert_eq!(
            reopened.trail, live.trail,
            "the reopened trail is the one the session closed with",
        );
        assert_eq!(reopened.repo.document(), live.repo.document(),);
    }

    /// The reopened trail is not just the right shape — walking it all
    /// the way down and back up moves the document through the same values
    /// the live session's walk would have.
    #[test]
    fn walking_a_reopened_trail_moves_the_document_as_the_session_would_have() {
        let mut live = Session::default();
        live.edit("Added a block", vec![block_create(1)]);
        live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        live.edit("Added another", vec![block_create(2)]);
        live.undo();

        let mut reopened = live.reopened();
        let drained = drain(&mut live);
        assert!(
            drained.windows(2).any(|pair| pair[0] != pair[1]),
            "the walk must move the document or it proves nothing",
        );
        assert_eq!(drain(&mut reopened), drained);
    }

    /// Undo every step, then redo every step, reporting the document at
    /// each stop. The oracle for "the reconstructed trail is the live
    /// one": two trails that walk the same document through the same
    /// values *are* the same trail.
    fn drain(live: &mut Session) -> Vec<Projection> {
        let mut seen = vec![projection(live.repo.document())];
        while live.trail.can_undo() {
            live.undo();
            seen.push(projection(live.repo.document()));
        }
        while live.trail.can_redo() {
            live.redo();
            seen.push(projection(live.repo.document()));
        }
        seen
    }

    /// "Edit, undo, quit, reopen": the redo future survives the restart,
    /// because the undo record says which edit it took back.
    #[test]
    fn a_reopened_undo_can_still_be_redone() {
        let mut live = Session::default();
        live.edit("Added a block", vec![block_create(1)]);
        live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        let moved = projection(live.repo.document());
        live.undo();

        let mut reopened = live.reopened();
        assert!(
            reopened.trail.can_redo(),
            "the reopened document lost its future",
        );
        reopened.redo();
        assert_eq!(
            projection(reopened.repo.document()),
            moved,
            "redoing after a restart did not restore what the undo took back",
        );
    }

    /// "Edit, undo, edit, quit, reopen": the second edit forked the
    /// history before the restart, so there is no future to come back to.
    #[test]
    fn a_reopened_edit_after_an_undo_has_no_redo_future() {
        let mut live = Session::default();
        live.edit("Added a block", vec![block_create(1)]);
        live.edit("Moved it", vec![resize(1, rect(5, 5))]);
        live.undo();
        live.edit("Moved it elsewhere", vec![resize(1, rect(7, 7))]);
        assert!(!live.trail.can_redo(), "precondition: the fork spent it");

        assert!(
            !live.reopened().trail.can_redo(),
            "the reconstructed trail offers a redo the session had abandoned",
        );
    }

    /// A log a container was *seeded* with carries edit records, so it
    /// replays as ordinary edits: reopening one makes the whole seeded past
    /// undoable, which is the point rather than an accident of it.
    /// Seeding itself stands on no trail — [`Repo::fold_one`] takes none.
    #[test]
    fn a_seeded_past_replays_as_edits_and_is_undoable() {
        let mut seeded = Repo::default();
        for n in 1..=3 {
            seeded
                .fold_one(commit("Added a block", vec![block_create(n)]))
                .expect("the seed folds");
        }
        let mut reopened = Session::default();
        for past in seeded.log() {
            let rev = reopened
                .repo
                .fold_one(past.clone())
                .expect("the log folds")
                .rev();
            reopened.trail.record(rev, JournalAs::Edit);
        }
        assert_eq!(reopened.trail.undo_revs(), [rev(1), rev(2), rev(3)]);
        assert_eq!(reopened.repo.document(), seeded.document(),);
    }
}