blockworx/tutorial/

reader.rs

//! Reading a tutorial: a `.bwx` container whose log *is* the demo.
//!
//! A tutorial is an ordinary document that was recorded rather than
//! authored — so there is no tutorial format, no scaffold, and nothing to
//! keep in step with the editor. What a level file used to declare, the log
//! already holds: a step is the commit it made, the narration beside it is a
//! `note` record (D17), and the sections a viewer navigates by are the notes
//! marked [`Chapter`](crate::store::record::NoteDisplay::Chapter).
//!
//! This is the whole substrate/UI contract. The reader answers three
//! questions — which chapters are there and how long is each, what does the
//! commit at this rev look like being made, and what is said while it
//! happens — and the UI half answers none of them for itself. A chapter's
//! duration in particular is summed here, from [`Tutorial::span`], so the
//! "40 seconds" on a library card is the time the player will really spend.
//!
//! Two answers arrived with the UI half, and both stay here rather than in
//! the player: what a tutorial *teaches* — a `teaches/<tool>` tag, which is
//! the tutorial's own log saying what it is about — and the document a
//! timeline is depicted against, which nothing but a fold can produce.

use core::time::Duration;
use std::cell::RefCell;
use std::path::Path;

use blockworx_doc::document::{DocIndex, Document};
use blockworx_doc::repo::Repo;
use blockworx_doc::rev::Rev;

use crate::choreography::{Timeline, synthesize};
use crate::store::container::ContainerError;
use crate::store::handle::Store;
use crate::store::notes::Note;
use crate::store::record::NoteDisplay;
use crate::tools::names::{self, ToolName};

/// What a tag's name has to begin with to be a claim about teaching. The
/// rest of it is a `ToolName::command_name` spelling.
pub const TEACHES: &str = "teaches/";

/// How long a rev that depicts nothing but says something holds on screen —
/// what the level format used to spell `pause`. One number, in the substrate,
/// so a chapter's advertised length and the player's clock cannot disagree.
pub const DWELL: Duration = Duration::from_millis(1_400);

/// One section of a tutorial: where it begins, what it is called, and how
/// long it plays for.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Chapter {
    pub at: Rev,
    pub title: String,
    pub duration: Duration,
}

/// A tutorial container, opened for playback.
pub struct Tutorial {
    name: String,
    chapters: Vec<Chapter>,
    store: Store,
    /// The last fold this reader made. A player walks the log forwards, so
    /// carrying one document forward turns a per-commit prefix fold into a
    /// per-commit `try_apply`; a rev asked for out of order simply re-folds
    /// its prefix.
    folded: RefCell<Folded>,
}

struct Folded {
    at: Rev,
    document: Document,
}

impl Tutorial {
    /// Open the container at `root`.
    ///
    /// Read-only in the honest sense — [`Store::reading`] never claims the
    /// lock — because playing a tutorial must not cost anyone the right to
    /// write the container it is playing.
    ///
    /// # Errors
    /// As [`Store::reading`]: there is no container at `root`, or its log
    /// cannot be read.
    pub fn open(root: &Path) -> Result<Self, ContainerError> {
        let name = root
            .file_stem()
            .unwrap_or_default()
            .to_string_lossy()
            .into_owned();
        let mut tutorial = Self {
            name,
            chapters: Vec::new(),
            store: Store::reading(root)?,
            folded: RefCell::new(Folded {
                at: Rev::ZERO,
                document: Document::default(),
            }),
        };
        tutorial.chapters = tutorial.sections();
        Ok(tutorial)
    }

    /// What this tutorial is called: the container's own name (D20).
    pub fn name(&self) -> &str {
        &self.name
    }

    pub fn chapters(&self) -> &[Chapter] {
        &self.chapters
    }

    /// The log this tutorial is, in play order.
    pub fn revs(&self) -> impl Iterator<Item = Rev> {
        revs(Rev::ZERO.next(), self.store.repo().rev().next())
    }

    /// The commit at `rev`, depicted: synthesized against the document as it
    /// stood at `rev - 1`. `None` for a rev this log does not hold, or a
    /// prefix this build will not fold.
    pub fn timeline(&self, rev: Rev) -> Option<Timeline> {
        let pre = rev.prev()?;
        let log = self.store.repo().log();
        let commit = log.get(pre.get() as usize)?;
        let mut folded = self.folded.borrow_mut();
        if folded.at != pre {
            let repo = Repo::folding(log.get(..pre.get() as usize)?).ok()?;
            *folded = Folded {
                at: pre,
                document: repo.document().clone(),
            };
        }
        let mut index = DocIndex::default();
        let timeline = synthesize(&index.view(&folded.document), commit);
        if let Ok(after) = folded.document.try_apply(commit) {
            *folded = Folded {
                at: rev,
                document: after,
            };
        }
        Some(timeline)
    }

    /// The tools this tutorial teaches, in the order its log names them.
    ///
    /// A `teaches/<tool>` tag on the rev whose commit that tool made
    /// (`docs/tutorial-levels.md`): the tutorial's own log says what it is
    /// about, so there is no sidecar, no filename convention and nothing to
    /// keep in step with the containers. A spelling no tool answers to is
    /// skipped rather than refused — a tag is authored text.
    pub fn teaches(&self) -> Vec<ToolName> {
        let mut taught = Vec::new();
        for (_, name) in self.store.tags().iter() {
            let Some(tool) = name
                .strip_prefix(TEACHES)
                .and_then(names::from_command_name)
            else {
                continue;
            };
            if !taught.contains(&tool) {
                taught.push(tool);
            }
        }
        taught
    }

    /// The document the commit at `rev` is depicted against — what a player
    /// draws the timeline over.
    ///
    /// Cloned rather than borrowed: the reader carries one fold forward and
    /// a player asks for this once per step, where it asks for a
    /// [`Frame`](crate::choreography::Frame) once per frame.
    pub fn document(&self, rev: Rev) -> Option<Document> {
        let pre = rev.prev()?;
        let log = self.store.repo().log();
        if pre.get() as usize > log.len() {
            return None;
        }
        let mut folded = self.folded.borrow_mut();
        if folded.at != pre {
            let repo = Repo::folding(log.get(..pre.get() as usize)?).ok()?;
            *folded = Folded {
                at: pre,
                document: repo.document().clone(),
            };
        }
        Some(folded.document.clone())
    }

    /// What is said at `rev` — a note that has been taken back says nothing
    /// (D17). A chapter's own rev answers with the chapter note: a note that
    /// opens a section is still a note, and it is what a viewer arriving
    /// there should be told.
    pub fn narration(&self, rev: Rev) -> Option<&Note> {
        self.store.notes().shown_at(rev)
    }

    pub fn store(&self) -> &Store {
        &self.store
    }

    /// The chapter notes, each carrying the summed length of the commits
    /// from its own rev up to the next chapter's.
    fn sections(&self) -> Vec<Chapter> {
        let opens: Vec<(Rev, String)> = self
            .store
            .notes()
            .shown()
            .filter(|(_, note)| note.show == NoteDisplay::Chapter)
            .map(|(at, note)| (at, note.text.clone()))
            .collect();
        let end = self.store.repo().rev().next();
        opens
            .iter()
            .enumerate()
            .map(|(nth, (at, title))| Chapter {
                at: *at,
                title: title.clone(),
                duration: self.spans(*at, opens.get(nth + 1).map_or(end, |(next, _)| *next)),
            })
            .collect()
    }

    /// How long the rev at `rev` holds on screen.
    ///
    /// Its depiction — or, where it depicts nothing and something is *said*
    /// at it, long enough to read that. A note is an empty commit and
    /// synthesizes a zero-length timeline (7·7), so without this a
    /// walkthrough's narration would flash past in one frame and a
    /// tool-pick chapter would never be seen at all.
    ///
    /// One resolver, two consumers: the player's clock reads it and so does
    /// [`Chapter::duration`], so the length a library card advertises is the
    /// length the player really spends (7·8's rule, kept while the UI half
    /// gave the substrate something new to answer).
    pub fn span(&self, rev: Rev) -> Duration {
        let depicted = self
            .timeline(rev)
            .map_or(Duration::ZERO, |timeline| timeline.duration());
        if depicted.is_zero() && self.narration(rev).is_some() {
            DWELL
        } else {
            depicted
        }
    }

    /// How long the commits in `from..until` take to play.
    fn spans(&self, from: Rev, until: Rev) -> Duration {
        revs(from, until).map(|rev| self.span(rev)).sum()
    }
}

/// `from..until`, in steps of one. A [`Rev`] is minted by the fold and never
/// by arithmetic, so a range over them is walked rather than constructed.
fn revs(from: Rev, until: Rev) -> impl Iterator<Item = Rev> {
    std::iter::successors(Some(from), |rev| Some(rev.next())).take_while(move |rev| *rev < until)
}

/// Every commit in `tutorial` plays: the C3 oracle over the timeline the
/// reader hands out, against a fold this walk makes for itself rather than
/// through the reader's own cache.
#[cfg(test)]
pub(crate) fn assert_plays(tutorial: &Tutorial) {
    let log = tutorial.store().repo().log().to_vec();
    assert_eq!(
        log.len(),
        tutorial.revs().count(),
        "precondition: one rev per commit",
    );
    for (nth, (rev, commit)) in tutorial.revs().zip(&log).enumerate() {
        let before = Repo::folding(&log[..nth])
            .expect("the prefix folds")
            .document()
            .clone();
        let timeline = tutorial
            .timeline(rev)
            .expect("the reader depicts every rev it holds");
        assert_eq!(timeline.label(), commit.label());
        if commit.ops().is_empty() {
            assert!(
                timeline.duration().is_zero() && timeline.recovered().is_none(),
                "an empty commit depicts nothing at rev {}",
                rev.get(),
            );
        } else {
            crate::choreography::tests::assert_timeline_recovers(&before, commit, &timeline);
        }
    }
}

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

    use std::path::PathBuf;

    use crate::atomic::tests::TempDir;
    use crate::store::container::{Access, Container, ReadOnlyReason};
    use crate::store::handle::Clock;
    use crate::store::record::{Identity, WallTime};
    use crate::store::tests::fixture;

    /// A container built through the real write door: two setup commits, then
    /// two chapters, each opened by a chapter note, narrated, and worked in.
    fn recorded(dir: &TempDir) -> PathBuf {
        let root = dir.join("demo.bwx");
        let author = Identity::new("ada");
        let mut store = Store::create(
            &root,
            Clock::Pinned {
                at: WallTime::EPOCH,
                step: Duration::from_secs(1),
            },
        )
        .expect("the container is laid out");
        for commit in fixture::edits(2) {
            store.submit_edit(commit, &author).expect("a setup commit");
        }
        store
            .note("Draw a block", None, NoteDisplay::Chapter, &author)
            .expect("the first chapter");
        store
            .note(
                "Pick the tool, then click",
                None,
                NoteDisplay::Narration,
                &author,
            )
            .expect("its narration");
        store
            .submit_edit(
                fixture::commit("Added a block", vec![fixture::block_create(3, "c")]),
                &author,
            )
            .expect("the chapter's edit");
        store
            .note("Move it", None, NoteDisplay::Chapter, &author)
            .expect("the second chapter");
        store
            .submit_edit(
                fixture::commit("Moved a block", vec![fixture::block_move(3, 12)]),
                &author,
            )
            .expect("the chapter's edit");
        store
            .submit_edit(
                fixture::commit("Renamed a block", vec![fixture::block_rename(3, "core")]),
                &author,
            )
            .expect("the chapter's second edit");
        root
    }

    #[test]
    fn a_tutorial_reads_back_its_chapters() {
        let dir = fixture::dir("tutorial-chapters");
        let tutorial = Tutorial::open(&recorded(&dir)).expect("the tutorial opens");

        assert_eq!(tutorial.name(), "demo");
        assert_eq!(
            tutorial
                .chapters()
                .iter()
                .map(|chapter| (chapter.at.get(), chapter.title.clone()))
                .collect::<Vec<_>>(),
            [(3, "Draw a block".to_owned()), (6, "Move it".to_owned())],
        );
    }

    /// The number the UI half is not allowed to invent: a chapter runs as
    /// long as the revs inside it hold on screen — their depictions, plus
    /// [`DWELL`] wherever something is *said* over a commit that depicts
    /// nothing — and the commits outside every chapter (the setup) belong to
    /// none of them.
    #[test]
    fn a_chapters_duration_is_the_sum_of_the_commits_it_holds() {
        let dir = fixture::dir("tutorial-durations");
        let tutorial = Tutorial::open(&recorded(&dir)).expect("the tutorial opens");
        let played = |from: u64, until: u64| -> Duration {
            tutorial
                .revs()
                .filter(|rev| rev.get() >= from && rev.get() < until)
                .map(|rev| tutorial.span(rev))
                .sum()
        };
        assert!(
            !played(1, 9).is_zero(),
            "precondition: this container depicts something",
        );

        let [first, second] = tutorial.chapters() else {
            panic!("two chapters were recorded");
        };
        assert_eq!(first.duration, played(3, 6));
        assert_eq!(second.duration, played(6, 9));
        assert_eq!(
            first.duration + second.duration,
            played(3, 9),
            "the chapters must partition everything after the first one begins",
        );
        assert!(
            !played(1, 3).is_zero() && played(3, 9) < played(1, 9),
            "the setup commits belong to no chapter",
        );
    }

    /// A note's own commit is empty, so the two notes inside the first
    /// chapter add nothing to its length.
    #[test]
    fn a_notes_commit_depicts_nothing() {
        let dir = fixture::dir("tutorial-note-duration");
        let tutorial = Tutorial::open(&recorded(&dir)).expect("the tutorial opens");
        for rev in tutorial
            .revs()
            .filter(|rev| rev.get() == 3 || rev.get() == 4)
        {
            let timeline = tutorial.timeline(rev).expect("a timeline per rev");
            assert!(timeline.duration().is_zero());
            assert!(timeline.recovered().is_none());
        }
    }

    #[test]
    fn narration_is_read_at_the_rev_it_was_written_at() {
        let dir = fixture::dir("tutorial-narration");
        let tutorial = Tutorial::open(&recorded(&dir)).expect("the tutorial opens");
        let said = |rev: u64| {
            tutorial
                .revs()
                .find(|at| at.get() == rev)
                .and_then(|at| tutorial.narration(at))
                .map(|note| (note.text.clone(), note.show))
        };
        assert_eq!(
            said(4),
            Some((
                "Pick the tool, then click".to_owned(),
                NoteDisplay::Narration
            )),
        );
        assert_eq!(
            said(3),
            Some(("Draw a block".to_owned(), NoteDisplay::Chapter)),
            "a chapter note is what is said where the chapter opens",
        );
        assert_eq!(said(5), None, "an edit narrates nothing");
    }

    /// D17's undo rule reaching the reader: a note taken back is not said,
    /// and the chapter it opened is not offered.
    #[test]
    fn a_chapter_taken_back_is_not_offered() {
        let dir = fixture::dir("tutorial-undone-chapter");
        let root = recorded(&dir);
        let author = Identity::new("ada");
        let mut store = Store::open(&root, Clock::System).expect("the container reopens");
        let at = store
            .note("Wrap up", None, NoteDisplay::Chapter, &author)
            .expect("a third chapter");
        assert_eq!(
            Tutorial::open(&root)
                .expect("the tutorial opens")
                .chapters()
                .len(),
            3,
            "precondition: the third chapter stands before it is taken back",
        );
        store.undo(at, &author).expect("the chapter is taken back");
        drop(store);

        let tutorial = Tutorial::open(&root).expect("the tutorial opens");
        assert_eq!(tutorial.narration(at), None);
        assert_eq!(
            tutorial
                .chapters()
                .iter()
                .map(|chapter| chapter.title.clone())
                .collect::<Vec<_>>(),
            ["Draw a block".to_owned(), "Move it".to_owned()],
        );
    }

    /// The reader carries one fold forward, so a timeline must not depend on
    /// the order the player asked for it in.
    #[test]
    fn a_timeline_is_the_same_whichever_order_it_is_asked_for() {
        let dir = fixture::dir("tutorial-order");
        let tutorial = Tutorial::open(&recorded(&dir)).expect("the tutorial opens");
        let described = |rev| {
            tutorial
                .timeline(rev)
                .expect("a timeline per rev")
                .describe()
        };
        let forwards: Vec<String> = tutorial.revs().map(described).collect();
        let mut order: Vec<Rev> = tutorial.revs().collect();
        order.reverse();
        let mut backwards: Vec<String> = order.into_iter().map(described).collect();
        backwards.reverse();
        assert!(
            forwards.iter().any(|text| text.contains("morph")),
            "precondition: this container depicts a move",
        );
        assert_eq!(forwards, backwards);
    }

    #[test]
    fn every_commit_in_a_hand_built_tutorial_plays() {
        let dir = fixture::dir("tutorial-plays");
        assert_plays(&Tutorial::open(&recorded(&dir)).expect("the tutorial opens"));
    }

    /// The three tutorials the repo actually ships: each opens through the
    /// read-only door, reports the chapters it was recorded with, and every
    /// commit in it depicts a timeline that recovers the commit. The
    /// containers are checked-in text, so this holds the reader to the demos
    /// rather than to a container the test just built.
    #[test]
    fn every_shipped_tutorial_plays() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("fixtures/tutorials");
        for id in ["first-block", "first-route", "resize-move"] {
            let tutorial = Tutorial::open(&dir.join(format!("{id}.bwx")))
                .unwrap_or_else(|e| panic!("{id} does not open: {e:?}"));
            assert_eq!(tutorial.name(), id);
            assert!(
                !tutorial.chapters().is_empty(),
                "{id} was recorded with no chapter to navigate by",
            );
            assert_plays(&tutorial);
        }
    }

    /// What each shipped tutorial teaches, and the rev whose commit the tool
    /// made — the tag goes there because a tag names a rev, and the rev that
    /// used the tool is the one that has anything to say about it.
    const TAUGHT: [(&str, u64, ToolName); 3] = [
        ("first-block", 6, ToolName::NewBlock),
        ("first-route", 6, ToolName::Route),
        ("resize-move", 6, ToolName::Select),
    ];

    fn shipped() -> PathBuf {
        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("fixtures/tutorials")
    }

    /// The user's format ruling: *"Include any meta information about the
    /// tutorial in the log of the tutorial."* So what a tutorial teaches is
    /// a `teaches/<tool>` tag in its own log, and this test is both the
    /// check and — under `BLOCKWORX_TAG_TUTORIALS=1` — the way the shipped
    /// containers were given theirs, on the deleted converter's own
    /// precedent (`docs/tutorial-levels.md`).
    #[test]
    fn every_shipped_tutorial_says_what_it_teaches() {
        if std::env::var_os("BLOCKWORX_TAG_TUTORIALS").is_some() {
            publish_the_teaching_tags();
        }
        for (id, _, tool) in TAUGHT {
            let tutorial =
                Tutorial::open(&shipped().join(format!("{id}.bwx"))).expect("the tutorial opens");
            assert_eq!(
                tutorial.teaches(),
                vec![tool],
                "{id} does not say what it teaches",
            );
        }
    }

    /// Append the tags the table names, through the ordinary write door. A
    /// tag folds nothing and spends no rev, so this leaves `document.json`
    /// and every existing line of `log.jsonl` exactly as they were.
    ///
    /// Idempotent, so re-running it is not a way to grow the log: a
    /// container that already says what it teaches is left alone.
    fn publish_the_teaching_tags() {
        let author = Identity::new("tutorial converter");
        for (id, at, tool) in TAUGHT {
            let root = shipped().join(format!("{id}.bwx"));
            let name = format!("{TEACHES}{}", tool.command_name().expect("a named tool"));
            let at = blockworx_doc::fixtures::rev(at);
            if Tutorial::open(&root)
                .expect("the tutorial opens")
                .store()
                .tags()
                .get(at)
                == Some(name.as_str())
            {
                continue;
            }
            let mut store = Store::open(
                &root,
                // Past the last record the converter wrote, and pinned, so a
                // re-run of this produces the same bytes.
                Clock::Pinned {
                    at: WallTime::from_unix_millis(9_000),
                    step: Duration::from_secs(1),
                },
            )
            .expect("the container opens for writing");
            store.tag(at, &name, &author).expect("the tag is appended");
        }
    }

    /// The lock discipline a reader owes the user: opening a tutorial takes
    /// nothing, so the container stays writable — and a container someone
    /// else is writing still opens to be read.
    #[test]
    fn opening_a_tutorial_leaves_the_lock_alone() {
        let dir = fixture::dir("tutorial-lock");
        let root = recorded(&dir);
        let tutorial = Tutorial::open(&root).expect("the tutorial opens");
        assert!(matches!(
            tutorial.store().access(),
            Access::ReadOnly(ReadOnlyReason::Reading),
        ));
        assert!(
            matches!(
                Container::open(&root, WallTime::EPOCH)
                    .expect("a writer opens")
                    .access(),
                Access::Writable(_),
            ),
            "the reader took the lock",
        );

        let held = Store::create(&dir.join("held.bwx"), Clock::System).expect("a live session");
        assert!(
            Tutorial::open(held.root()).is_ok(),
            "a locked container must still be readable",
        );
    }
}