blockworx/store/

notes.rs

//! Authored narration: what a log's `note` records say, and at which revs
//! (D17). A projection of the log, rebuilt on every open, exactly as
//! [`Tags`](super::tags::Tags) is — the records are the truth and this is
//! the map they fold to.
//!
//! Where the two diverge is the rev. A tag *names* one; a note *occupies*
//! one, as the empty commit it is, which is what buys it undo for free:
//! taking back a note is taking back a commit, so a note is shown only
//! while the step that wrote it still stands.
//!
//! Which step that is has to be followed rather than looked up. An undo is
//! a forward commit with a rev of its own, and the journal's redo stack
//! holds *it*, not the rev it took back — so
//! [`Repo::redo_revs`](blockworx_doc::repo::Repo::redo_revs) can never
//! answer "is this note undone". What can is the record sequence itself:
//! each undo and redo names the step it moved, so a note is followed along
//! the chain of stand-ins from the record that wrote it to whichever step
//! is holding its place now.

use std::collections::BTreeMap;

use blockworx_doc::rev::Rev;

use super::record::{Anchor, LogRecord, NoteDisplay, RecordKind};

/// One authored note, as its record wrote it.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Note {
    pub text: String,
    pub anchor: Option<Anchor>,
    pub show: NoteDisplay,
}

/// Whether a note currently stands. Not a bool: a note that has been taken
/// back is still in the log, so "gone" is never the answer and the two
/// states are named rather than counted.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Standing {
    Shown,
    Hidden,
}

/// A note and where it stands.
#[derive(Clone, Debug, PartialEq, Eq)]
struct Held {
    note: Note,
    standing: Standing,
}

/// What a log's notes say, keyed by the rev each one was written at.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Notes {
    notes: BTreeMap<Rev, Held>,
    /// Which note each history step is about: the note's own rev to begin
    /// with, then the undo that took it back, then the redo that brought it
    /// back, each naming the last. Only steps that concern a note are held,
    /// so a document with no narration in it carries nothing.
    stands_for: BTreeMap<Rev, Rev>,
}

impl Notes {
    /// Take `record` into the projection. Every record is offered, because
    /// an undo or a redo of a note is as much a part of what the notes say
    /// as the note itself; the kinds that concern no note fall through.
    pub fn take(&mut self, record: &LogRecord) {
        match record.kind {
            RecordKind::Note { anchor, show } => {
                self.written(record.rev, &record.label, anchor, show);
            }
            RecordKind::Undo { of } => self.undone(record.rev, of),
            RecordKind::Redo { of } => self.redone(record.rev, of),
            RecordKind::Edit | RecordKind::Tag => {}
        }
    }

    /// A note written at `at`. The three steps below are what a session
    /// with no records behind it calls instead of [`Self::take`]: a scratch
    /// note still occupies a rev in the in-process repo, and is still taken
    /// back by taking back that rev.
    pub fn written(&mut self, at: Rev, text: &str, anchor: Option<Anchor>, show: NoteDisplay) {
        self.notes.insert(
            at,
            Held {
                note: Note {
                    text: text.to_owned(),
                    anchor,
                    show,
                },
                standing: Standing::Shown,
            },
        );
        self.stands_for.insert(at, at);
    }

    /// The step at `at` took back the step at `of`.
    pub fn undone(&mut self, at: Rev, of: Rev) {
        self.moved(at, of, Standing::Hidden);
    }

    /// The step at `at` re-applied the step at `of`.
    pub fn redone(&mut self, at: Rev, of: Rev) {
        self.moved(at, of, Standing::Shown);
    }

    fn moved(&mut self, at: Rev, of: Rev, standing: Standing) {
        let Some(note) = self.stands_for.get(&of).copied() else {
            return;
        };
        if let Some(held) = self.notes.get_mut(&note) {
            held.standing = standing;
        }
        self.stands_for.insert(at, note);
    }

    /// The note written at `at`, shown or not — the record, which the log
    /// holds however often it is taken back.
    pub fn get(&self, at: Rev) -> Option<&Note> {
        self.notes.get(&at).map(|held| &held.note)
    }

    /// Whether the note written at `at` currently stands.
    pub fn is_shown(&self, at: Rev) -> bool {
        self.notes
            .get(&at)
            .is_some_and(|held| held.standing == Standing::Shown)
    }

    /// The note shown at `at`, or `None` where there is none or it has been
    /// taken back.
    pub fn shown_at(&self, at: Rev) -> Option<&Note> {
        let held = self.notes.get(&at)?;
        (held.standing == Standing::Shown).then_some(&held.note)
    }

    /// Every note the log holds, oldest first, shown or not.
    pub fn iter(&self) -> impl Iterator<Item = (Rev, &Note)> {
        self.notes.iter().map(|(rev, held)| (*rev, &held.note))
    }

    /// The notes a reader would see, oldest first.
    pub fn shown(&self) -> impl Iterator<Item = (Rev, &Note)> {
        self.notes
            .iter()
            .filter(|(_, held)| held.standing == Standing::Shown)
            .map(|(rev, held)| (*rev, &held.note))
    }

    pub fn len(&self) -> usize {
        self.notes.len()
    }

    pub fn is_empty(&self) -> bool {
        self.notes.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use blockworx_doc::fixtures::rev;

    fn narration(text: &str) -> Note {
        Note {
            text: text.to_owned(),
            anchor: None,
            show: NoteDisplay::Narration,
        }
    }

    fn notes() -> Notes {
        let mut notes = Notes::default();
        notes.written(rev(1), "Earlier", None, NoteDisplay::Narration);
        notes.written(rev(2), "Later", None, NoteDisplay::Narration);
        notes
    }

    #[test]
    fn the_last_note_for_a_rev_wins() {
        let mut notes = Notes::default();
        notes.written(rev(2), "First", None, NoteDisplay::Narration);
        notes.written(rev(2), "Second", None, NoteDisplay::Chapter);
        assert_eq!(notes.len(), 1);
        assert_eq!(
            notes.get(rev(2)).map(|note| note.show),
            Some(NoteDisplay::Chapter),
        );
    }

    #[test]
    fn notes_read_back_oldest_first() {
        assert_eq!(
            notes()
                .iter()
                .map(|(rev, note)| (rev, note.text.clone()))
                .collect::<Vec<_>>(),
            [(rev(1), "Earlier".to_owned()), (rev(2), "Later".to_owned()),],
        );
    }

    /// D17's undo rule, over the step revs the journal really mints: the
    /// undo of the note at r2 is a commit of its own at r3, and the redo of
    /// *that* is another at r4 — so the note is followed through its
    /// stand-ins rather than looked for on a stack.
    #[test]
    fn an_undo_hides_the_note_it_names_and_a_redo_of_the_undo_brings_it_back() {
        let mut notes = notes();
        assert_eq!(notes.shown().count(), 2, "precondition: both stand");

        notes.undone(rev(3), rev(2));
        assert_eq!(notes.shown_at(rev(2)), None);
        assert_eq!(notes.shown_at(rev(1)), Some(&narration("Earlier")));
        assert_eq!(
            notes.get(rev(2)),
            Some(&narration("Later")),
            "the record is still in the log — it is the showing that stopped",
        );

        notes.redone(rev(4), rev(3));
        assert_eq!(notes.shown_at(rev(2)), Some(&narration("Later")));

        notes.undone(rev(5), rev(4));
        assert_eq!(notes.shown_at(rev(2)), None, "and back again, any depth");
    }

    /// A history that forks away from an undone note leaves it undone:
    /// nothing names it again, so nothing shows it again. The abandonment
    /// the journal's redo stack loses is not a fact this has to be told.
    #[test]
    fn a_note_the_history_forked_away_from_stays_hidden() {
        let mut notes = notes();
        notes.undone(rev(3), rev(2));
        // The fork: an ordinary edit at r4, which abandons the redo the
        // journal was holding. It concerns no note.
        notes.undone(rev(5), rev(4));
        assert_eq!(notes.shown_at(rev(2)), None);
        assert_eq!(notes.shown().count(), 1);
    }

    /// A step that stands in for no note moves nothing — which is what lets
    /// every record be offered without the caller sorting them first.
    #[test]
    fn an_undo_of_an_ordinary_edit_touches_no_note() {
        let mut notes = notes();
        notes.undone(rev(9), rev(8));
        assert_eq!(notes.shown().count(), 2);
        assert!(!notes.stands_for.contains_key(&rev(9)));
    }
}