openvcs_core/

lib.rs

//! OpenVCS Core: shared types for OpenVCS plugins and the OpenVCS client.

pub mod backend_id;
pub mod models;

pub use crate::backend_id::BackendId;

#[doc(hidden)]
pub use log as __log;

#[cfg(feature = "backend-registry")]
pub mod backend_descriptor;

#[cfg(feature = "plugin-protocol")]
pub mod plugin_protocol;

#[cfg(feature = "plugin-protocol")]
pub mod plugin_stdio;

#[cfg(feature = "plugin-protocol")]
pub mod host;

#[cfg(feature = "plugin-protocol")]
pub mod plugin_runtime;

#[cfg(feature = "plugin-protocol")]
pub mod events;

#[doc(hidden)]
pub fn __plugin_log_to_client(level: log::Level, target: &str, args: std::fmt::Arguments<'_>) {
    #[cfg(feature = "plugin-protocol")]
    {
        let msg = format!("[{level}] {target}: {args}");
        if let Ok(out) = crate::host::stdout() {
            crate::plugin_stdio::send_message_shared(
                out,
                &crate::plugin_protocol::PluginMessage::Event {
                    event: match level {
                        log::Level::Error => crate::models::VcsEvent::Error { msg },
                        log::Level::Warn => crate::models::VcsEvent::Warning { msg },
                        log::Level::Info | log::Level::Debug | log::Level::Trace => {
                            crate::models::VcsEvent::Info { msg }
                        }
                    },
                },
            );
            return;
        }
    }

    let _ = (level, target, args);
}

#[macro_export]
macro_rules! trace {
    (target: $target:expr, $($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Trace, $target, format_args!($($arg)+));
        $crate::__log::trace!(target: $target, $($arg)+);
    }};
    ($($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Trace, module_path!(), format_args!($($arg)+));
        $crate::__log::trace!($($arg)+);
    }};
}

#[macro_export]
macro_rules! debug {
    (target: $target:expr, $($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Debug, $target, format_args!($($arg)+));
        $crate::__log::debug!(target: $target, $($arg)+);
    }};
    ($($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Debug, module_path!(), format_args!($($arg)+));
        $crate::__log::debug!($($arg)+);
    }};
}

#[macro_export]
macro_rules! info {
    (target: $target:expr, $($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Info, $target, format_args!($($arg)+));
        $crate::__log::info!(target: $target, $($arg)+);
    }};
    ($($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Info, module_path!(), format_args!($($arg)+));
        $crate::__log::info!($($arg)+);
    }};
}

#[macro_export]
macro_rules! warn {
    (target: $target:expr, $($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Warn, $target, format_args!($($arg)+));
        $crate::__log::warn!(target: $target, $($arg)+);
    }};
    ($($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Warn, module_path!(), format_args!($($arg)+));
        $crate::__log::warn!($($arg)+);
    }};
}

#[macro_export]
macro_rules! error {
    (target: $target:expr, $($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Error, $target, format_args!($($arg)+));
        $crate::__log::error!(target: $target, $($arg)+);
    }};
    ($($arg:tt)+) => {{
        $crate::__plugin_log_to_client($crate::__log::Level::Error, module_path!(), format_args!($($arg)+));
        $crate::__log::error!($($arg)+);
    }};
}

#[cfg(feature = "plugin-protocol")]
pub use crate::plugin_protocol::{PluginMessage, RpcRequest, RpcResponse};

#[cfg(feature = "vcs")]
pub use crate::models::{Capabilities, FetchOptions, OnEvent};

#[cfg(feature = "vcs")]
use std::path::{Path, PathBuf};

#[cfg(feature = "vcs")]
#[derive(thiserror::Error, Debug)]
pub enum VcsError {
    #[error("not a repository: {0}")]
    NotARepo(String),
    #[error("branch not found: {0}")]
    NoSuchBranch(String),
    #[error("no upstream configured")]
    NoUpstream,
    #[error("nothing to commit")]
    NothingToCommit,
    #[error("non-fast-forward; merge or rebase required")]
    NonFastForward,
    #[error("unsupported backend: {0}")]
    Unsupported(BackendId),
    #[error("io: {0}")]
    Io(#[from] std::io::Error),
    #[error("{backend}: {msg}")]
    Backend { backend: BackendId, msg: String },
}

#[cfg(feature = "vcs")]
pub type Result<T> = std::result::Result<T, VcsError>;

/// The single trait every VCS backend implements.
#[cfg(feature = "vcs")]
pub trait Vcs: Send + Sync {
    fn id(&self) -> BackendId;
    fn caps(&self) -> models::Capabilities;

    // lifecycle
    fn open(path: &Path) -> Result<Self>
    where
        Self: Sized;
    fn clone(url: &str, dest: &Path, on: Option<models::OnEvent>) -> Result<Self>
    where
        Self: Sized;

    // context
    fn workdir(&self) -> &Path;

    // common ops
    fn current_branch(&self) -> Result<Option<String>>;
    fn branches(&self) -> Result<Vec<models::BranchItem>>;

    #[deprecated(
        since = "0.1.0",
        note = "This function is being replaced by `branches`."
    )]
    fn local_branches(&self) -> Result<Vec<String>>;
    fn create_branch(&self, name: &str, checkout: bool) -> Result<()>;
    fn checkout_branch(&self, name: &str) -> Result<()>;

    // network
    fn ensure_remote(&self, name: &str, url: &str) -> Result<()>;
    fn list_remotes(&self) -> Result<Vec<(String, String)>>;
    fn remove_remote(&self, name: &str) -> Result<()>;
    fn fetch(&self, remote: &str, refspec: &str, on: Option<models::OnEvent>) -> Result<()>;
    fn fetch_with_options(
        &self,
        remote: &str,
        refspec: &str,
        _opts: models::FetchOptions,
        on: Option<models::OnEvent>,
    ) -> Result<()> {
        self.fetch(remote, refspec, on)
    }
    fn push(&self, remote: &str, refspec: &str, on: Option<models::OnEvent>) -> Result<()>;
    fn pull_ff_only(&self, remote: &str, branch: &str, on: Option<models::OnEvent>) -> Result<()>;

    // content
    fn commit(&self, message: &str, name: &str, email: &str, paths: &[PathBuf]) -> Result<String>;
    fn commit_index(&self, message: &str, name: &str, email: &str) -> Result<String>;
    fn status_summary(&self) -> Result<models::StatusSummary>;
    fn status_payload(&self) -> Result<models::StatusPayload>;
    fn log_commits(&self, query: &models::LogQuery) -> Result<Vec<models::CommitItem>>;
    fn diff_file(&self, path: &Path) -> Result<Vec<String>>;
    fn diff_commit(&self, rev: &str) -> Result<Vec<String>>;

    // conflicts
    fn conflict_details(&self, _path: &Path) -> Result<models::ConflictDetails> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn checkout_conflict_side(&self, _path: &Path, _side: models::ConflictSide) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn write_merge_result(&self, _path: &Path, _content: &[u8]) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }

    fn stage_patch(&self, patch: &str) -> Result<()>;
    fn discard_paths(&self, paths: &[PathBuf]) -> Result<()>;
    fn apply_reverse_patch(&self, patch: &str) -> Result<()>;

    // branches
    fn delete_branch(&self, name: &str, force: bool) -> Result<()>;
    fn rename_branch(&self, old: &str, new: &str) -> Result<()>;
    fn merge_into_current(&self, name: &str) -> Result<()>;
    fn merge_into_current_with_message(&self, name: &str, message: Option<&str>) -> Result<()> {
        let _ = message;
        self.merge_into_current(name)
    }
    fn merge_abort(&self) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn merge_continue(&self) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn merge_in_progress(&self) -> Result<bool> {
        Ok(false)
    }
    fn set_branch_upstream(&self, _branch: &str, _upstream: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn branch_upstream(&self, _branch: &str) -> Result<Option<String>> {
        Err(VcsError::Unsupported(self.id()))
    }

    // recovery
    fn hard_reset_head(&self) -> Result<()>;
    fn reset_soft_to(&self, _rev: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }

    // config
    fn get_identity(&self) -> Result<Option<(String, String)>>;
    fn set_identity_local(&self, name: &str, email: &str) -> Result<()>;

    // stash
    fn stash_list(&self) -> Result<Vec<models::StashItem>> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn stash_push(
        &self,
        _message: &str,
        _include_untracked: bool,
        _paths: &[PathBuf],
    ) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn stash_apply(&self, _selector: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn stash_pop(&self, _selector: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn stash_drop(&self, _selector: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn stash_show(&self, _selector: &str) -> Result<Vec<String>> {
        Err(VcsError::Unsupported(self.id()))
    }

    // lfs
    fn lfs_fetch(&self) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn lfs_pull(&self) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn lfs_prune(&self) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn lfs_track(&self, _paths: &[PathBuf]) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn lfs_untrack(&self, _paths: &[PathBuf]) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn lfs_is_tracked(&self, _path: &Path) -> Result<bool> {
        Err(VcsError::Unsupported(self.id()))
    }

    // history operations
    fn cherry_pick(&self, _rev: &str) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
    fn revert_commit(&self, _rev: &str, _no_edit: bool) -> Result<()> {
        Err(VcsError::Unsupported(self.id()))
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn log_macros_are_callable() {
        crate::trace!("trace");
        crate::debug!("debug");
        crate::info!("info");
        crate::warn!("warn");
        crate::error!("error");
    }

    #[cfg(feature = "vcs")]
    #[test]
    fn vcs_error_formats_useful_messages() {
        let e = crate::VcsError::Unsupported(crate::BackendId::from("git"));
        assert!(e.to_string().contains("unsupported backend"));

        let e = crate::VcsError::Backend {
            backend: crate::BackendId::from("git"),
            msg: "boom".into(),
        };
        assert_eq!(e.to_string(), "git: boom");
    }
}