blockworx/

library.rs

//! The documents on disk: what this session opened, where a new one is born,
//! which containers the File menu offers to reopen, and every door a document
//! comes in or goes out through. The browser has no filesystem, so on the web
//! this part is a shape with nothing in it.
//!
//! It also owns what the session has to say about its files — the refusals a
//! door reports and the standing facts about the container — because every one
//! of them starts here.

#[cfg(not(target_arch = "wasm32"))]
use std::path::{Path, PathBuf};

use crate::kernel::Session;
// Every door that settles a panel is a container door, and the browser has
// none.
#[cfg(not(target_arch = "wasm32"))]
use crate::surface::Surface;
use blockworx_store::doc::Doc;

#[cfg(not(target_arch = "wasm32"))]
use blockworx_doc::repo::Repo;

/// What the session opens on.
#[cfg(not(target_arch = "wasm32"))]
#[derive(Default)]
pub enum Opening {
    /// The path a command line named: a `.bwx` container, which attaches, or
    /// a document file, which opens as a scratch session.
    Path(PathBuf),
    /// Nothing was named, so a document is born: a container under a name of
    /// three words in the documents directory, attached from its first edit.
    Born,
    /// Neither — a session with no file behind it. The browser has only this,
    /// and so does a test driving the editor without a filesystem.
    #[default]
    Detached,
}

#[derive(Default)]
pub(crate) struct Library {
    /// The file a *scratch* document was opened from, for the window title.
    /// `None` on the web (no filesystem) and when nothing was there to open.
    /// An attached container names itself.
    #[cfg(not(target_arch = "wasm32"))]
    opened: Option<String>,
    /// Where the document this session opened came from, when it was opened
    /// from an export that carried a provenance block. Advisory and
    /// session-only: the title block says it, nothing writes it, and saving
    /// into a container does not carry it past this session.
    #[cfg(not(target_arch = "wasm32"))]
    opened_from: Option<blockworx_store::stamp::Provenance>,
    /// The containers the File menu offers to reopen, persisted through the
    /// eframe storage DB.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) recent: crate::file::RecentFiles,
    /// Where File ▸ New puts the container it creates.
    #[cfg(not(target_arch = "wasm32"))]
    documents: blockworx_store::naming::Documents,
    /// The containers *this session* created that nobody has claimed: born
    /// under a generated name, never committed to and never renamed. They
    /// are removed on a clean exit, so launching and quitting leaves the
    /// documents directory as it was, and they stay off the recent list
    /// until they are claimed, so it does not fill with dead names.
    #[cfg(not(target_arch = "wasm32"))]
    unclaimed: Vec<PathBuf>,
    /// The File menu's rename box, which has to survive the frames it is
    /// open across.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) rename_draft: String,
    /// The channel an in-flight File-menu dialog delivers its pick on.
    /// Polled each frame; `None` when no dialog is open.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) pending_file: Option<crate::file::PickReceiver>,
}

impl Library {
    /// Open whatever the session was pointed at, and hand back the document
    /// it is to stand on. A document born here is the no-argument case.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn opening(
        opening: Opening,
        documents: blockworx_store::naming::Documents,
    ) -> (Self, Doc, Option<String>) {
        let Startup {
            doc,
            opened,
            from,
            born,
            failure,
        } = match opening {
            Opening::Path(path) => open_startup_path(&path),
            Opening::Born => born_attached(&documents),
            Opening::Detached => Startup::detached(),
        };
        let library = Self {
            opened,
            opened_from: from,
            documents,
            unclaimed: born.into_iter().collect(),
            ..Self::default()
        };
        (library, doc, failure)
    }

    /// The browser has no filesystem: nothing to open, and nowhere for a
    /// document to be born.
    #[cfg(target_arch = "wasm32")]
    pub(crate) fn opening() -> (Self, Doc, Option<String>) {
        (Self::default(), Doc::default(), None)
    }

    /// What a scratch document's source file is called — the one fact about
    /// the window title and the document's name that belongs to the platform
    /// rather than to the document.
    // The browser has no file to have opened one from, so the answer there is
    // a constant `None` — and the shape of the question is still the shell's.
    #[cfg_attr(target_arch = "wasm32", expect(clippy::unused_self))]
    fn opened_name(&self) -> Option<&str> {
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.opened.as_deref()
        }
        #[cfg(target_arch = "wasm32")]
        {
            None
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn window_title(&self, session: &Session) -> String {
        session.window_title(self.opened_name())
    }

    pub(crate) fn document_name(&self, session: &Session) -> String {
        session.document_name(self.opened_name())
    }

    /// Where this session's document came from, when it was opened from an
    /// export. The web build opens no files, so nothing there has a
    /// provenance to carry.
    #[cfg_attr(target_arch = "wasm32", expect(clippy::unused_self))]
    pub(crate) fn opened_from(&self) -> Option<blockworx_store::stamp::Provenance> {
        #[cfg(not(target_arch = "wasm32"))]
        {
            self.opened_from.clone()
        }
        #[cfg(target_arch = "wasm32")]
        {
            None
        }
    }

    /// Restore the recent list from the eframe storage DB.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn restore(&mut self, storage: &dyn eframe::Storage, session: &Session) {
        self.recent = crate::file::RecentFiles::restore(storage);
        // A container opened from the command line belongs at the front of
        // the list too — the restore above would otherwise bury it. One this
        // session invented does not: it earns its place by being written in
        // or renamed.
        if let Some(root) = attached_root(session)
            && !self.unclaimed.contains(&root)
        {
            self.recent.remember(&root);
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn save(&self, storage: &mut dyn eframe::Storage) {
        self.recent.save(storage);
    }

    /// Open the File menu's dialog for `request`; the pick comes back through
    /// [`crate::file::PickReceiver`], polled each frame.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn pick_file(
        &mut self,
        ask: &mut crate::dialogs::Ask<'_>,
        request: crate::file::FileRequest,
    ) {
        self.pending_file = Some(ask.file(request));
    }

    /// Take `doc` as the session's document and settle everything that
    /// pointed at the last one. The handle it displaces drops here, which is
    /// what gives a container's lock back — there is nothing to save on the
    /// way out, since every commit was durable when it was made.
    #[cfg(not(target_arch = "wasm32"))]
    fn take_document(&mut self, session: &mut Session, surface: &mut Surface, doc: Doc) {
        let was = self.document_name(session);
        session.opens(doc);
        // The store that just dropped gave a born container its lock back,
        // so one this session made and left behind can go now rather than
        // waiting for the exit.
        self.sweep_unclaimed(session);
        surface.forget_popup();
        surface.settle_workspace(&was, &self.document_name(session));
    }

    /// File ▸ New: a document born attached, under a name of three words. A
    /// container that cannot be created leaves the session on a scratch
    /// document — the editor opens either way — and says why.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn new_document(&mut self, session: &mut Session, surface: &mut Surface) {
        self.opened = None;
        self.opened_from = None;
        match self.documents.create(blockworx_store::naming::entropy) {
            Ok(store) => {
                if let Some(born) = store.path().map(Path::to_path_buf) {
                    self.unclaimed.push(born);
                }
                self.take_document(session, surface, Doc::attached(store));
            }
            Err(failure) => {
                // After the swap: adopting a document clears the notices
                // the last one collected, this one among them.
                self.take_document(session, surface, Doc::default());
                session.failures.report(failure.notice());
            }
        }
    }

    /// Call this document something else, which renames its container.
    /// The session carries straight on into it: the log it is appending to
    /// is held open, so the next edit lands in the renamed container.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn rename_document(
        &mut self,
        session: &mut Session,
        surface: &mut Surface,
        name: &str,
    ) {
        let Some(root) = attached_root(session) else {
            session
                .failures
                .report("This session has no diagram on disk to rename".to_owned());
            return;
        };
        let Some(called) = blockworx_store::storage::Name::of_document(name) else {
            session
                .failures
                .report(format!("\u{201c}{name}\u{201d} is not a diagram name"));
            return;
        };
        if let Err(refusal) = session.doc.rename(&called) {
            session.failures.report(format!(
                "Failed to rename {}: {refusal}",
                crate::file::document_name(&root),
            ));
            return;
        }
        self.recent.forget(&root);
        // The panel state follows the document to its new name.
        surface.settle_workspace(
            &crate::file::document_name(&root),
            &self.document_name(session),
        );
        // A name of the user's own is a claim on the document, so a
        // renamed container is never swept and joins the recent list.
        self.claim(&crate::file::renamed_beside(&root, &called));
    }

    /// A container this session created stops being unclaimed the moment
    /// the user commits to it — the first edit, or a name of their own —
    /// and joins the recent list then, so the list never fills with names
    /// nobody kept.
    #[cfg(not(target_arch = "wasm32"))]
    fn claim(&mut self, root: &Path) {
        self.unclaimed.retain(|born| born != root);
        self.recent.remember(root);
    }

    /// The first record in a born container's log is what claims it. Called
    /// from the write door, so every path that can write the first one —
    /// an edit, a paste, an import, a restore — goes through here.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn claim_if_written(&mut self, session: &Session) {
        if self.unclaimed.is_empty() || session.doc.repo().log().is_empty() {
            return;
        }
        if let Some(root) = attached_root(session)
            && self.unclaimed.contains(&root)
        {
            self.claim(&root);
        }
    }

    /// Pristine cleanup, narrowed to what this session made: a container the
    /// user opened is theirs however empty it is, and deleting it would not
    /// be ours to decide. The one still open is left for the sweep on the way
    /// out, which runs after its store — and its lock — have been dropped.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn sweep_unclaimed(&mut self, session: &Session) {
        use blockworx_store::container::{Discarded, discard_pristine};
        use blockworx_store::storage::ready_now;
        let open = attached_root(session);
        let mut still_open = Vec::new();
        for root in std::mem::take(&mut self.unclaimed) {
            if Some(&root) == open.as_ref() {
                still_open.push(root);
                continue;
            }
            match ready_now(discard_pristine(&blockworx_store::storage::Native::at(
                &root,
            ))) {
                Ok(Discarded::Removed) => {
                    tracing::info!("removed {}, which held no edit", root.display());
                }
                Ok(Discarded::Kept) => {}
                Err(e) => tracing::warn!("{} could not be tidied away: {e}", root.display()),
            }
        }
        self.unclaimed = still_open;
    }

    /// Open the container at `root`, or say why not. A held lock, a broken
    /// log and a failed write are outcomes rather than failures: the
    /// container opens read-only and the chrome carries the reason. Only a
    /// path that is no container — or has become one no longer — costs it
    /// its place in the recent list.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn open_container(
        &mut self,
        session: &mut Session,
        surface: &mut Surface,
        root: &Path,
    ) {
        // The folder picker takes any folder, so the choice is judged here
        // rather than by the store's own "it has no log" complaint, which
        // answers a question the user did not ask.
        if let Some(refusal) = crate::file::refused_as_a_diagram(root) {
            session.failures.report(refusal);
            self.recent.forget(root);
            return;
        }
        match crate::file::open_container(root) {
            Ok(store) => {
                if let Some(reason) = store.read_only_reason() {
                    tracing::warn!("{} opened read-only: {reason}", root.display());
                }
                self.recent.remember(root);
                self.opened = None;
                self.take_document(session, surface, Doc::attached(store));
            }
            Err(refusal) => {
                session
                    .failures
                    .report(format!("Failed to open {}: {refusal}", root.display()));
                self.recent.forget(root);
            }
        }
    }

    /// Write this session's document into a container at `root` — the one
    /// save left, since an attached document is written as it is edited.
    ///
    /// Two paths, because a session with a log and a session without one are
    /// different problems. A container's log *is* its document, so `scope`'s
    /// rev is a cut in its lines and the save copies them: everything the
    /// records carry — wall times, authors, edit/undo/redo kinds, tags —
    /// comes over because nothing is rewritten. A scratch session has
    /// only its commits, so those are seeded, and a cut is a prefix of them.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn save_as_container(
        &mut self,
        ctx: &egui::Context,
        session: &mut Session,
        root: &Path,
        scope: crate::file::SaveScope,
    ) {
        use crate::file::SaveScope;
        let written = if let Some(source) = session.doc.container_path().map(Path::to_path_buf) {
            let at = match scope {
                SaveScope::Through(at) => at,
                SaveScope::Whole => session.doc.repo().rev(),
            };
            crate::file::save_container_through(&source, at, root, &session.identity)
                .map_err(|refusal| refusal.to_string())
        } else {
            let log = session.doc.repo().log();
            let through = match scope {
                SaveScope::Through(at) => at.get() as usize,
                SaveScope::Whole => log.len(),
            };
            let Some(prefix) = log.get(..through) else {
                // Unreachable through the menu, which reads the rev off the
                // canvas — and cheaper to answer than to prove.
                return session
                    .failures
                    .report(format!("this session has no rev {through}"));
            };
            crate::file::create_container(root, prefix, &session.identity)
                .map_err(|refusal| refusal.to_string())
        };
        match written {
            Ok(store) => {
                self.recent.remember(root);
                self.opened = None;
                session.adopt(Doc::attached(store));
                // The document is unchanged — only its home is — so the view
                // and the selection stay put. The undo stack cannot: what
                // this session may take back is whatever the new container's
                // own trail holds, which for a seeded one is nothing (the
                // commits are its past, not steps anybody took here) and for
                // a copied log is what replaying it gave back.
                session.undo_stack =
                    crate::history::UndoStack::reconstructed(session.doc.trail(), &session.state());
                // What was on the canvas is now the head of a document this
                // session may write — which is the whole point of saving
                // from inside the lens, so the lens closes on it.
                session.view_head();
                // A save that worked is routine, so it is said in the
                // status line rather than raised as an attention event; the
                // failure below still is one.
                crate::shell::status_line::say(ctx, saved_as(root, scope));
            }
            Err(refusal) => {
                // Toasted rather than pinned as a notice: nothing about the
                // session changed, so there is no standing fact to
                // acknowledge — only news, which is what a toast is for.
                tracing::error!("Failed to write {}: {refusal}", root.display());
                crate::shell::toast::say(
                    ctx,
                    format!(
                        "Could not save as {}: {refusal}",
                        crate::file::document_name(root),
                    ),
                );
            }
        }
    }

    /// Deliver a File-menu pick once its off-thread dialog resolves.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn poll_pending_file(
        &mut self,
        ctx: &egui::Context,
        session: &mut Session,
        surface: &mut Surface,
    ) {
        let Some(rx) = &self.pending_file else {
            return;
        };
        match rx.try_recv() {
            Ok(Some(pick)) => {
                self.pending_file = None;
                match pick {
                    crate::file::FilePick::Container(root) => {
                        self.open_container(session, surface, &root);
                    }
                    crate::file::FilePick::NewContainer(root, scope) => {
                        self.save_as_container(ctx, session, &root, scope);
                    }
                }
            }
            // A cancelled dialog and a dropped sender both end the pick.
            Ok(None) | Err(std::sync::mpsc::TryRecvError::Disconnected) => {
                self.pending_file = None;
            }
            // See `Exchange::poll_pending_import`: a native picker can sit
            // open for minutes, so poll it gently.
            Err(std::sync::mpsc::TryRecvError::Empty) => {
                ctx.request_repaint_after(std::time::Duration::from_millis(100));
            }
        }
    }

    /// The document itself needs nothing written on the way out: every
    /// commit was durable when it was made. A container's lock is its
    /// store's lifetime, and eframe does not promise to drop the app on
    /// every platform, so it is given back here rather than left stale; the
    /// containers this session left unclaimed go with it.
    #[cfg(not(target_arch = "wasm32"))]
    pub(crate) fn on_exit(&mut self, session: &mut Session) {
        session.doc = Doc::default();
        self.sweep_unclaimed(session);
    }
}

/// The container this session is attached to, if it is.
#[cfg(not(target_arch = "wasm32"))]
pub(crate) fn attached_root(session: &Session) -> Option<PathBuf> {
    session.doc.container_path().map(Path::to_path_buf)
}

/// A repo whose one commit creates everything `doc` holds, under the ids
/// the file gave them. The one door a document takes into the editor: the
/// courtesy open of a plain file comes through here, and a document the fold
/// refuses opens empty rather than taking the editor down.
#[cfg(not(target_arch = "wasm32"))]
fn seeded_repo(doc: &blockworx_doc::document::Document, label: &str) -> Repo {
    let commits: Vec<_> = doc.creating_commit(label).into_iter().collect();
    Repo::folding(&commits).unwrap_or_else(|e| {
        tracing::error!("{label} will not seed a repo: {e}");
        Repo::default()
    })
}

/// What opening a plain document file came back with.
#[cfg(not(target_arch = "wasm32"))]
enum Loaded {
    /// The file opened: this is what it held, under this name, and — for an
    /// export — where it says it came from. Boxed, so the enum is the size of
    /// the sentence it carries rather than of a document.
    Document {
        repo: Box<Repo>,
        name: String,
        from: Option<blockworx_store::stamp::Provenance>,
    },
    /// Nothing was there to open, which is not a complaint.
    Nothing,
    /// It was there, would not open, and this says why.
    Failed(String),
}

/// Whether `path` names a document in a format this build no longer reads.
/// The reader is gone, so the honest answer is a refusal naming the format —
/// not a JSON parse failure over a file that was never JSON.
#[cfg(not(target_arch = "wasm32"))]
fn names_a_retired_format(path: &Path) -> bool {
    path.extension()
        .is_some_and(|ext| ext.eq_ignore_ascii_case("kdl"))
}

#[cfg(not(target_arch = "wasm32"))]
fn retired_format_notice(name: &str) -> String {
    format!("{name} is in the retired KDL document format, which this build no longer reads")
}

/// A plain document file — an export, or a hand-written one — read into a
/// fresh repo and named for the window title. Nothing there opens blank
/// without complaint — a boot invents no content the user never authored; a
/// read or parse failure comes back as [`Loaded::Failed`] and the session
/// opens blank around it, since refusing to start helps nobody.
#[cfg(not(target_arch = "wasm32"))]
fn open_document_file(path: &Path) -> Loaded {
    if !path.is_file() {
        return Loaded::Nothing;
    }
    let name = path
        .file_name()
        .map_or_else(String::new, |n| n.to_string_lossy().into_owned());
    if names_a_retired_format(path) {
        return Loaded::Failed(retired_format_notice(&name));
    }
    let src = match std::fs::read_to_string(path) {
        Ok(src) => src,
        Err(e) => return Loaded::Failed(format!("Failed to open {}: {e}", path.display())),
    };
    match blockworx_store::document_file::parse(&src, &name) {
        Ok(doc) => Loaded::Document {
            repo: Box::new(seeded_repo(&doc, &format!("Opened {name}"))),
            from: blockworx_store::stamp::exported_stamp_in(&src).and_then(|s| s.provenance),
            name,
        },
        Err(e) => {
            // The console gets the spans and the offending source; the canvas
            // gets the sentence, since a rendered diagnostic is a wall of text
            // in a notice.
            tracing::error!("Failed to open {}:\n{e:?}", path.display());
            Loaded::Failed(format!("Failed to open {}: {e}", path.display()))
        }
    }
}

/// What the session starts on: the document, the name the window title says
/// was opened, the container this startup created if it made one, and
/// whatever would not open on the way — which the canvas says out loud
/// rather than only the console.
#[cfg(not(target_arch = "wasm32"))]
struct Startup {
    doc: Doc,
    opened: Option<String>,
    from: Option<blockworx_store::stamp::Provenance>,
    born: Option<PathBuf>,
    failure: Option<String>,
}

#[cfg(not(target_arch = "wasm32"))]
impl Startup {
    /// A session with nothing behind it — the blank canvas the editor opens
    /// on when there is nowhere to be born.
    fn detached() -> Self {
        Startup {
            doc: Doc::default(),
            opened: None,
            from: None,
            born: None,
            failure: None,
        }
    }
}

/// What the toast says a Save-as did. Two sentences, because two things
/// happened: at the head the document has a new home, and under the lens a
/// *rev* of it does — and which one it was is the thing the user needs to
/// read back.
#[cfg(not(target_arch = "wasm32"))]
fn saved_as(root: &Path, scope: crate::file::SaveScope) -> String {
    let named = crate::file::document_name(root);
    match scope {
        crate::file::SaveScope::Whole => format!("Saved as {named}"),
        crate::file::SaveScope::Through(at) => {
            format!("Saved through rev {} as {named}", at.get())
        }
    }
}

/// The born-attached start: a container of its own, so append-on-commit holds
/// from the first edit. A container that cannot be created is a notice and a
/// scratch session, never a refusal to start.
#[cfg(not(target_arch = "wasm32"))]
fn born_attached(documents: &blockworx_store::naming::Documents) -> Startup {
    match documents.create(blockworx_store::naming::entropy) {
        Ok(store) => Startup {
            born: store.path().map(Path::to_path_buf),
            doc: Doc::attached(store),
            opened: None,
            from: None,
            failure: None,
        },
        Err(failure) => Startup {
            failure: Some(failure.notice()),
            ..Startup::detached()
        },
    }
}

/// What a named path opens: a container attached, or — for a plain document
/// file, and for anything that will not open — a scratch session, which
/// persists nothing.
///
/// The plain-file half is the command line's alone. Nothing in the chrome
/// offers to open a `document.json`: it is the projection beside a
/// log, carrying neither that log nor the assets, so opening one would hand
/// the user half a diagram wearing its name. A developer naming one on the
/// command line has asked for exactly that, and is told what they got by the
/// title bar's "[nothing persisted]".
#[cfg(not(target_arch = "wasm32"))]
fn open_startup_path(path: &Path) -> Startup {
    if crate::file::names_an_archive(path) {
        return match crate::file::open_archive(path) {
            Ok(store) => Startup {
                doc: Doc::attached(store),
                ..Startup::detached()
            },
            Err(e) => Startup {
                failure: Some(format!("Failed to open {}: {e}", path.display())),
                ..Startup::detached()
            },
        };
    }
    let mut failure = None;
    if crate::file::names_a_container(path) {
        match crate::file::open_container(path) {
            Ok(store) => {
                if let Some(reason) = store.read_only_reason() {
                    tracing::warn!("{} opened read-only: {reason}", path.display());
                }
                return Startup {
                    doc: Doc::attached(store),
                    ..Startup::detached()
                };
            }
            Err(e) => {
                failure = Some(format!("Failed to open {}: {e}", path.display()));
            }
        }
    }
    let (repo, opened, from, load_failure) = match open_document_file(path) {
        Loaded::Document { repo, name, from } => (*repo, Some(name), from, None),
        Loaded::Nothing => (Repo::default(), None, None, None),
        Loaded::Failed(why) => (Repo::default(), None, None, Some(why)),
    };
    Startup {
        doc: Doc::scratch(repo),
        opened,
        from,
        born: None,
        failure: failure.or(load_failure),
    }
}