nordisk/facett

facett-source-link/src/lib.rs

//! **The error-code source link, built in ONE place** (RA2-14).
//!
//! facett, dwarves and korp each keep a registry of stable error codes, and each code
//! links the source file that raises it, on the repository's public file pages on
//! gunnar.rs: `<base>/blob/<branch>/<path>`. That form was three hand copies (facett-core,
//! dwarves, korp); a fourth spelling would drift. Each registry now names its repository
//! once, as a [`SourceRepo`], and every link is built here.
//!
//! std only, so a CLI (dwarves) links it without facett-core's GPU stack.

#![forbid(unsafe_code)]

/// The branch a source link resolves against, unless a repository says otherwise.
pub const MAIN: &str = "main";

/// **A repository's public file pages**: its base URL (the workspace `repository`
/// field, e.g. `https://gunnar.rs/nordisk/facett`) and the branch links resolve on.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SourceRepo {
    /// The repository's page, with no trailing `/`.
    pub base: &'static str,
    /// The branch a file link resolves against.
    pub branch: &'static str,
}

impl SourceRepo {
    /// The repository at `base`, linked on [`MAIN`].
    pub const fn new(base: &'static str) -> Self {
        Self { base, branch: MAIN }
    }

    /// The file page of `path` (relative to the repository root): `<base>/blob/<branch>/<path>`.
    pub fn blob(&self, path: &str) -> String {
        format!("{}{}", self.blob_base(), path.trim_start_matches('/'))
    }

    /// Where every file link starts: `<base>/blob/<branch>/`.
    pub fn blob_base(&self) -> String {
        format!("{}/blob/{}/", self.base, self.branch)
    }

    /// The file page of `path` when there is one, else the repository's own page (an
    /// unknown code links the repository, never a dead page).
    pub fn link_or_repo(&self, path: Option<&str>) -> String {
        path.map_or_else(|| self.base.to_string(), |p| self.blob(p))
    }
}

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

    const FACETT: SourceRepo = SourceRepo::new("https://gunnar.rs/nordisk/facett");

    #[test]
    fn a_file_links_its_blob_page_on_main() {
        assert_eq!(FACETT.branch, "main");
        assert_eq!(FACETT.blob("facett-map/src/lib.rs"), "https://gunnar.rs/nordisk/facett/blob/main/facett-map/src/lib.rs");
        assert_eq!(FACETT.blob_base(), "https://gunnar.rs/nordisk/facett/blob/main/");
    }

    #[test]
    fn a_leading_slash_never_doubles_the_separator() {
        assert_eq!(FACETT.blob("/src/x.rs"), "https://gunnar.rs/nordisk/facett/blob/main/src/x.rs");
    }

    #[test]
    fn another_branch_is_honoured() {
        let r = SourceRepo { branch: "release", ..FACETT };
        assert_eq!(r.blob("a.rs"), "https://gunnar.rs/nordisk/facett/blob/release/a.rs");
    }

    #[test]
    fn an_unknown_file_links_the_repository() {
        assert_eq!(FACETT.link_or_repo(None), "https://gunnar.rs/nordisk/facett");
        assert_eq!(FACETT.link_or_repo(Some("src/a.rs")), FACETT.blob("src/a.rs"));
    }
}