rigless 0.1.0

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! How a build writes its version from where its source came from. `build.rs` finds the facts and
//! includes this file for the rule, so the rule has tests of its own.

/// Where a build's source came from.
#[derive(Debug, PartialEq, Eq)]
pub(crate) enum Provenance {
    /// An official release: a package from the registry, or a clean checkout at the tag its version
    /// names.
    Release,
    /// Any other commit, and whether the tree had changes the commit doesn't hold.
    Commit { commit: String, dirty: bool },
    /// Neither a package nor a checkout, so nothing says which source this is.
    Unknown,
}

/// The version a build reports: the crate's own for a release, and semver build metadata naming the
/// source for anything else, which never changes how two versions order.
pub(crate) fn describe(version: &str, provenance: &Provenance) -> String {
    match provenance {
        Provenance::Release => version.to_owned(),
        Provenance::Commit {
            commit,
            dirty: false,
        } => format!("{version}+{commit}"),
        Provenance::Commit {
            commit,
            dirty: true,
        } => format!("{version}+{commit}.dirty"),
        Provenance::Unknown => format!("{version}+unknown"),
    }
}

/// What cargo recorded in a package's `.cargo_vcs_info.json`: the commit it packed, and `"dirty":
/// true` when the tree held changes. Only the tag's pipeline publishes, and it publishes a clean
/// tree, so a clean record is a release.
// ceiling: a crate packed by hand from a clean commit that isn't a release reads as one; upgrade
// when packages travel some way other than the tag's pipeline.
pub(crate) fn from_vcs_info(json: &str) -> Provenance {
    let commit = json
        .split("\"sha1\"")
        .nth(1)
        .and_then(|rest| rest.split('"').nth(1))
        .map(|sha| sha.chars().take(SHORT).collect::<String>());
    let dirty = json.contains("\"dirty\": true") || json.contains("\"dirty\":true");
    match commit {
        Some(commit) if dirty => Provenance::Commit {
            commit,
            dirty: true,
        },
        Some(_) => Provenance::Release,
        None => Provenance::Unknown,
    }
}

/// A checkout: a release when `HEAD` carries the tag its version names and nothing that builds has
/// changed, and its commit otherwise. `tags` is every tag at `HEAD`, one a line.
pub(crate) fn from_checkout(version: &str, commit: &str, tags: &str, dirty: bool) -> Provenance {
    if !dirty && tags.lines().any(|tag| tag.trim() == version) {
        Provenance::Release
    } else {
        Provenance::Commit {
            commit: commit.chars().take(SHORT).collect(),
            dirty,
        }
    }
}

/// How much of a commit's hash a version names, what `git log --oneline` shows.
pub(crate) const SHORT: usize = 7;

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

    const COMMIT: &str = "abcdef0123456789abcdef0123456789abcdef01";

    #[test]
    fn a_release_reports_its_version_alone_and_anything_else_names_its_source() {
        let commit = |dirty| Provenance::Commit {
            commit: "abcdef0".to_owned(),
            dirty,
        };
        assert_eq!(describe("1.2.3", &Provenance::Release), "1.2.3");
        assert_eq!(describe("1.2.3", &commit(false)), "1.2.3+abcdef0");
        assert_eq!(describe("1.2.3", &commit(true)), "1.2.3+abcdef0.dirty");
        assert_eq!(describe("1.2.3", &Provenance::Unknown), "1.2.3+unknown");
    }

    #[test]
    fn a_checkout_is_a_release_only_at_its_own_tag_with_nothing_changed() {
        let commit = |dirty| Provenance::Commit {
            commit: "abcdef0".to_owned(),
            dirty,
        };
        assert_eq!(
            from_checkout("1.2.3", COMMIT, "1.2.3\n", false),
            Provenance::Release
        );
        assert_eq!(
            from_checkout("1.2.3", COMMIT, "1.2.3\n", true),
            commit(true),
            "the tag with changes on top is not the release"
        );
        assert_eq!(
            from_checkout("1.2.3", COMMIT, "1.2.2\n", false),
            commit(false),
            "another version's tag is not this one's"
        );
        assert_eq!(from_checkout("1.2.3", COMMIT, "", false), commit(false));
    }

    /// The record `cargo package` writes, which carries `dirty` only when the tree was.
    #[test]
    fn a_package_reads_its_commit_and_whether_it_was_dirty_from_what_cargo_recorded() {
        let clean = format!(
            "{{\n  \"git\": {{\n    \"sha1\": \"{COMMIT}\"\n  }},\n  \"path_in_vcs\": \"\"\n}}"
        );
        let dirty = format!(
            "{{\n  \"git\": {{\n    \"sha1\": \"{COMMIT}\",\n    \"dirty\": true\n  }},\n  \"path_in_vcs\": \"\"\n}}"
        );
        assert_eq!(from_vcs_info(&clean), Provenance::Release);
        assert_eq!(
            from_vcs_info(&dirty),
            Provenance::Commit {
                commit: "abcdef0".to_owned(),
                dirty: true
            }
        );
        assert_eq!(from_vcs_info("{}"), Provenance::Unknown);
    }
}