ephemeris_release/proposal/

analysis.rs

//! Version bump analysis. Callers supply what Git observed about each unit
//! and how to find the required bump, so the policy here stays pure.

use std::collections::{BTreeMap, BTreeSet};

use super::ProposalError;
use crate::conventional::Commit;
use crate::unit::Unit;
use crate::version::{Bump, Proposed, Version};

/// One proposed unit version.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct Change {
    pub(crate) unit: String,
    pub(crate) version: Proposed,
    /// The direct dependencies updated in the same proposal, with their
    /// proposed versions. A first release is not an update.
    pub(crate) dependencies: BTreeMap<String, Version>,
}

impl Change {
    fn new(unit: &Unit, version: Proposed) -> Self {
        Self {
            unit: unit.name.clone(),
            version,
            dependencies: BTreeMap::new(),
        }
    }
}

/// Every change a proposal makes.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct Proposal {
    pub(crate) changes: Vec<Change>,
}

/// What Git reports about one unit since its baseline tag, or since the root
/// commit for a unit that has no tag and is still at 0.0.0.
#[derive(Clone, Debug, Eq, PartialEq)]
pub(crate) struct History {
    pub(crate) baseline_tag: Option<String>,
    pub(crate) changed: bool,
    /// Whether a commit format is set, so `commits` is meaningful.
    pub(crate) conventional: bool,
    /// The commits that change the unit, when a commit format is set.
    pub(crate) commits: Vec<Commit>,
}

/// The configured bump policy.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Policy<'a> {
    /// Applications, which are bumped without API analysis and take a patch
    /// bump when only a dependency changed.
    pub(crate) applications: &'a BTreeSet<String>,
    /// Applications that are only bumped by an explicit override.
    pub(crate) non_bumping: &'a BTreeSet<String>,
    pub(crate) overrides: &'a BTreeMap<String, Version>,
}

impl Proposal {
    /// Proposed versions keyed by unit.
    pub(crate) fn versions(&self) -> BTreeMap<String, Proposed> {
        self.changes
            .iter()
            .map(|change| (change.unit.clone(), change.version.clone()))
            .collect()
    }
}

impl Unit {
    pub(crate) fn bumped(&self, bump: Bump) -> Result<Version, ProposalError> {
        bump.apply(&self.version)
            .ok_or_else(|| ProposalError::BumpOverflow {
                unit: self.name.clone(),
                version: self.version.to_string(),
                bump,
            })
    }

    /// Apply a bump, turning a major bump below 1.0.0 into a minor one.
    fn bumped_in_development(&self, bump: Bump) -> Result<Version, ProposalError> {
        match bump {
            Bump::Major if self.version.is_initial_development() => self.bumped(Bump::Minor),
            bump @ (Bump::Patch | Bump::Minor | Bump::Major) => self.bumped(bump),
        }
    }

    pub(crate) fn transitive_dependents(
        units: &[Self],
        mut affected: BTreeSet<String>,
    ) -> BTreeSet<String> {
        loop {
            let previous = affected.len();
            for unit in units {
                if unit
                    .dependencies
                    .iter()
                    .any(|dependency| affected.contains(dependency))
                {
                    affected.insert(unit.name.clone());
                }
            }
            if affected.len() == previous {
                return affected;
            }
        }
    }
}

/// The first version of a unit at 0.0.0: its override, or the largest bump its
/// commits ask for. Applications count every commit and libraries only
/// features, fixes and breaking changes.
fn first_version(
    unit: &Unit,
    history: &History,
    policy: Policy<'_>,
) -> Result<Version, ProposalError> {
    if let Some(version) = policy.overrides.get(&unit.name) {
        return Ok(version.clone());
    }
    let application = policy.applications.contains(&unit.name);
    let bump = history
        .commits
        .iter()
        .filter(|commit| application || commit.is_release_worthy())
        .map(Commit::bump)
        .max()
        .filter(|_| history.conventional)
        .ok_or_else(|| ProposalError::FirstVersionUnknown {
            unit: unit.name.clone(),
            path: unit.version_path().clone(),
        })?;
    unit.bumped_in_development(bump)
}

/// Changed units receive their override or the larger of the bumps their
/// commits and API analysis require. Applications take a patch bump when no
/// commit asks for more. A breaking change is a minor bump below 1.0.0 and
/// otherwise a major bump. Applications depending on a changed unit are
/// bumped too. A unit at 0.0.0 without a tag takes the same bump rules from its
/// whole history, ignoring API analysis, as a first release. A unit without
/// history is a first release at its override or its current version.
pub(crate) fn analyze(
    units: &[Unit],
    history: &BTreeMap<String, History>,
    policy: Policy<'_>,
    mut required_bump: impl FnMut(&Unit, &str) -> Result<Bump, ProposalError>,
) -> Result<Proposal, ProposalError> {
    let mut changes = Vec::new();
    for unit in units {
        let Some(unit_history) = history.get(&unit.name) else {
            changes.push(Change::new(
                unit,
                Proposed::First(
                    policy
                        .overrides
                        .get(&unit.name)
                        .unwrap_or(&unit.version)
                        .clone(),
                ),
            ));
            continue;
        };
        let Some(baseline_tag) = &unit_history.baseline_tag else {
            if policy.non_bumping.contains(&unit.name) && !policy.overrides.contains_key(&unit.name)
            {
                continue;
            }
            let version = first_version(unit, unit_history, policy)?;
            changes.push(Change::new(unit, Proposed::First(version)));
            continue;
        };
        if !unit_history.changed
            || (policy.non_bumping.contains(&unit.name)
                && !policy.overrides.contains_key(&unit.name))
        {
            continue;
        }
        let version = if let Some(version) = policy.overrides.get(&unit.name) {
            version.clone()
        } else {
            let commits = unit_history.commits.iter().map(Commit::bump).max();
            let bump = if policy.applications.contains(&unit.name) {
                commits.unwrap_or(Bump::Patch)
            } else {
                let required = required_bump(unit, baseline_tag)?;
                commits.map_or(required, |bump| bump.max(required))
            };
            unit.bumped_in_development(bump)?
        };
        changes.push(Change::new(unit, Proposed::Bump(version)));
    }
    let affected = Unit::transitive_dependents(
        units,
        changes.iter().map(|change| change.unit.clone()).collect(),
    );
    for unit in units {
        if !policy.applications.contains(&unit.name)
            || !affected.contains(&unit.name)
            || changes.iter().any(|change| change.unit == unit.name)
        {
            continue;
        }
        let version = match policy.overrides.get(&unit.name) {
            Some(version) => version.clone(),
            None => unit.bumped(Bump::Patch)?,
        };
        changes.push(Change::new(unit, Proposed::Bump(version)));
    }
    let mut proposal = Proposal { changes };
    let versions = proposal.versions();
    for change in &mut proposal.changes {
        let dependencies = units
            .iter()
            .find(|unit| unit.name == change.unit)
            .map_or(&[][..], |unit| unit.dependencies.as_slice());
        change.dependencies = dependencies
            .iter()
            .filter(|name| history.contains_key(*name))
            .filter_map(|name| match versions.get(name)? {
                Proposed::Bump(version) => Some((name.clone(), version.clone())),
                Proposed::First(_) => None,
            })
            .collect();
    }
    Ok(proposal)
}

#[cfg(test)]
mod tests {
    use std::collections::{BTreeMap, BTreeSet};
    use std::path::Path;

    use super::{Change, History, Policy, analyze};
    use crate::commit_subject::CommitSubject;
    use crate::conventional::Commit;
    use crate::state::ReleaseTarget;
    use crate::unit::Unit;
    use crate::version::{Bump, Proposed, Version};

    fn unit(name: &str, version: &str, dependencies: &[&str]) -> Unit {
        Unit {
            name: name.into(),
            package_name: Some(name.into()),
            version: Version::parse(version).unwrap(),
            target: ReleaseTarget::Cargo {
                manifest: format!("{name}/Cargo.toml").parse().unwrap(),
                publish: true,
            },
            source: vec![name.parse().unwrap()].try_into().unwrap(),
            changelog: Some(format!("{name}/CHANGELOG.md").parse().unwrap()),
            tag_prefix: format!("{name}-v"),
            dependencies: dependencies.iter().map(|value| (*value).into()).collect(),
            pins: BTreeMap::new(),
            revision: None,
        }
    }

    fn history(entries: &[(&str, &str, bool)]) -> BTreeMap<String, History> {
        entries
            .iter()
            .map(|(name, tag, changed)| {
                (
                    (*name).to_owned(),
                    History {
                        baseline_tag: Some((*tag).to_owned()),
                        changed: *changed,
                        conventional: true,
                        commits: Vec::new(),
                    },
                )
            })
            .collect()
    }

    fn version(value: &str) -> Version {
        Version::parse(value).unwrap()
    }

    #[test]
    fn dependent_closure_reaches_non_publishing_application_through_a_diamond() {
        let units = [
            unit("core", "1.0.0", &[]),
            unit("left", "1.0.0", &["core"]),
            unit("right", "1.0.0", &["core"]),
            unit("app", "1.0.0", &["left", "right"]),
            unit("unrelated", "1.0.0", &[]),
        ];
        assert_eq!(
            Unit::transitive_dependents(&units, BTreeSet::from(["core".into()])),
            BTreeSet::from(["app".into(), "core".into(), "left".into(), "right".into()])
        );
    }

    #[test]
    fn application_patch_skips_the_analysis() {
        let units = [unit("app", "3.1.0", &[])];
        let proposal = analyze(
            &units,
            &history(&[("app", "dpdhl-llm-3.1.0-2", true)]),
            Policy {
                applications: &BTreeSet::from(["app".into()]),
                non_bumping: &BTreeSet::new(),
                overrides: &BTreeMap::new(),
            },
            |_, _| panic!("applications are not analyzed"),
        )
        .unwrap();
        assert_eq!(
            proposal.changes,
            [Change {
                unit: "app".into(),
                version: Proposed::Bump(version("3.1.1")),
                dependencies: BTreeMap::new(),
            }]
        );
    }

    #[test]
    fn bumped_units_record_the_updated_versions_of_their_direct_dependencies() {
        let units = [
            unit("core", "1.0.0", &[]),
            unit("lib", "1.0.0", &["core"]),
            unit("fresh", "0.1.0", &[]),
            unit("app", "2.0.0", &["lib", "core", "fresh"]),
        ];
        let history = history(&[
            ("core", "core-v1.0.0", true),
            ("lib", "lib-v1.0.0", false),
            ("app", "app-v2.0.0", true),
        ]);
        let proposal = analyze(
            &units,
            &history,
            Policy {
                applications: &BTreeSet::from(["app".into()]),
                non_bumping: &BTreeSet::new(),
                overrides: &BTreeMap::new(),
            },
            |_, _| Ok(Bump::Minor),
        )
        .unwrap();
        let dependencies = |name: &str| {
            proposal
                .changes
                .iter()
                .find(|change| change.unit == name)
                .map(|change| change.dependencies.clone())
        };
        assert_eq!(dependencies("core"), Some(BTreeMap::new()));
        assert_eq!(dependencies("lib"), None);
        assert_eq!(
            dependencies("app"),
            Some(BTreeMap::from([("core".into(), version("1.1.0"))]))
        );
    }

    #[test]
    fn application_bump_none_skips_automatic_version_but_accepts_override() {
        let units = [unit("app", "1.0.0", &[])];
        let history = history(&[("app", "app-v1.0.0", true)]);
        let non_bumping = BTreeSet::from(["app".into()]);
        let mut policy = Policy {
            applications: &BTreeSet::new(),
            non_bumping: &non_bumping,
            overrides: &BTreeMap::new(),
        };
        let proposal = analyze(&units, &history, policy, |_, _| Ok(Bump::Patch)).unwrap();
        assert_eq!(proposal.changes, Vec::<Change>::new());

        let overrides = BTreeMap::from([("app".into(), version("1.1.0"))]);
        policy.overrides = &overrides;
        let overridden = analyze(&units, &history, policy, |_, _| Ok(Bump::Patch)).unwrap();
        assert_eq!(
            overridden.changes[0].version,
            Proposed::Bump(version("1.1.0"))
        );
    }

    #[test]
    fn breaking_library_change_bumps_major_and_dependent_applications() {
        let units = [unit("core", "1.0.0", &[]), unit("app", "2.0.0", &["core"])];
        let history = history(&[("core", "core-v1.0.0", true), ("app", "app-v2.0.0", false)]);
        let applications = BTreeSet::from(["app".into()]);
        let mut policy = Policy {
            applications: &applications,
            non_bumping: &BTreeSet::new(),
            overrides: &BTreeMap::new(),
        };
        let expected = BTreeMap::from([
            ("app".into(), Proposed::Bump(version("2.0.1"))),
            ("core".into(), Proposed::Bump(version("2.0.0"))),
        ]);
        assert_eq!(
            analyze(&units, &history, policy, |_, _| Ok(Bump::Major))
                .unwrap()
                .versions(),
            expected
        );

        let overrides = BTreeMap::from([("core".into(), version("3.0.0"))]);
        policy.overrides = &overrides;
        let proposal = analyze(&units, &history, policy, |_, _| Ok(Bump::Major)).unwrap();
        assert_eq!(
            proposal.versions()["core"],
            Proposed::Bump(version("3.0.0"))
        );
    }

    #[test]
    fn unchanged_units_are_not_proposed() {
        let units = [unit("core", "1.0.0", &[])];
        let policy = Policy {
            applications: &BTreeSet::new(),
            non_bumping: &BTreeSet::new(),
            overrides: &BTreeMap::new(),
        };
        let unchanged = history(&[("core", "core-v1.0.0", false)]);
        assert_eq!(
            analyze(&units, &unchanged, policy, |_, _| Ok(Bump::Patch))
                .unwrap()
                .changes,
            Vec::<Change>::new()
        );
    }

    #[test]
    fn an_untagged_unit_is_a_first_release_beside_tagged_units() {
        let units = [unit("core", "1.0.0", &[]), unit("new", "0.3.0", &[])];
        let history = history(&[("core", "core-v1.0.0", true)]);
        let mut policy = Policy {
            applications: &BTreeSet::new(),
            non_bumping: &BTreeSet::from(["new".into()]),
            overrides: &BTreeMap::new(),
        };
        assert_eq!(
            analyze(&units, &history, policy, |unit, _| {
                assert_eq!(unit.name, "core", "a first release has nothing to compare");
                Ok(Bump::Patch)
            })
            .unwrap()
            .versions(),
            BTreeMap::from([
                ("core".into(), Proposed::Bump(version("1.0.1"))),
                ("new".into(), Proposed::First(version("0.3.0"))),
            ])
        );

        let overrides = BTreeMap::from([("new".into(), version("1.0.0"))]);
        policy.overrides = &overrides;
        assert_eq!(
            analyze(&units, &history, policy, |_, _| Ok(Bump::Patch))
                .unwrap()
                .versions()["new"],
            Proposed::First(version("1.0.0"))
        );
    }

    #[test]
    fn bump_overflow_names_the_bump() {
        assert_eq!(
            unit("a", "1.2.3", &[]).bumped(Bump::Patch).unwrap(),
            version("1.2.4")
        );
        assert!(matches!(
            unit("a", "1.2.18446744073709551615", &[]).bumped(Bump::Patch),
            Err(super::ProposalError::BumpOverflow { unit, version: _, bump: Bump::Patch })
                if unit == "a"
        ));
        assert!(matches!(
            unit("a", "1.18446744073709551615.0", &[]).bumped(Bump::Minor),
            Err(super::ProposalError::BumpOverflow {
                unit: _,
                version: _,
                bump: Bump::Minor
            })
        ));
    }

    fn library_bump(version: &str, bump: Bump) -> Result<Version, super::ProposalError> {
        let units = [unit("core", version, &[])];
        analyze(
            &units,
            &history(&[("core", "core-v1", true)]),
            Policy {
                applications: &BTreeSet::new(),
                non_bumping: &BTreeSet::new(),
                overrides: &BTreeMap::new(),
            },
            |_, _| Ok(bump),
        )
        .map(|proposal| proposal.versions()["core"].version().clone())
    }

    #[test]
    fn library_takes_the_bump_analysis_requires() {
        assert_eq!(
            library_bump("1.2.3", Bump::Patch).unwrap(),
            version("1.2.4")
        );
        assert_eq!(
            library_bump("1.2.3", Bump::Minor).unwrap(),
            version("1.3.0")
        );
    }

    #[test]
    fn major_below_one_is_a_minor_bump() {
        assert_eq!(
            library_bump("0.4.7", Bump::Major).unwrap(),
            version("0.5.0")
        );
    }

    fn commits(messages: &[&str]) -> Vec<Commit> {
        Commit::from_messages(
            messages.iter().copied(),
            &CommitSubject::try_from("release: {unit} {version}").unwrap(),
        )
    }

    fn commit_bump(version: &str, application: bool, required: Bump, messages: &[&str]) -> Version {
        let units = [unit("core", version, &[])];
        let mut history = history(&[("core", "core-v1", true)]);
        history.get_mut("core").unwrap().commits = commits(messages);
        let applications = if application {
            BTreeSet::from(["core".into()])
        } else {
            BTreeSet::new()
        };
        let policy = Policy {
            applications: &applications,
            non_bumping: &BTreeSet::new(),
            overrides: &BTreeMap::new(),
        };
        analyze(&units, &history, policy, |_, _| Ok(required))
            .unwrap()
            .versions()["core"]
            .version()
            .clone()
    }

    #[test]
    fn commits_replace_the_application_patch() {
        let bump = |version, messages| commit_bump(version, true, Bump::Major, messages);
        assert_eq!(bump("1.2.3", &["fix: a", "feat: b"]), version("1.3.0"));
        assert_eq!(bump("1.2.3", &["fix: a", "docs: b"]), version("1.2.4"));
        assert_eq!(bump("1.2.3", &["fix!: a"]), version("2.0.0"));
        assert_eq!(
            bump("0.2.3", &["fix: a\n\nBREAKING CHANGE: b"]),
            version("0.3.0")
        );
        assert_eq!(bump("1.2.3", &[]), version("1.2.4"));
    }

    #[test]
    fn a_library_takes_the_larger_of_the_commit_and_api_bumps() {
        let bump = |required, messages| commit_bump("1.2.3", false, required, messages);
        assert_eq!(bump(Bump::Patch, &["feat: a"]), version("1.3.0"));
        assert_eq!(bump(Bump::Minor, &["fix: a"]), version("1.3.0"));
        assert_eq!(bump(Bump::Patch, &["fix: a", "Change b"]), version("1.2.4"));
        assert_eq!(bump(Bump::Minor, &["refactor!: a"]), version("2.0.0"));
        assert_eq!(
            commit_bump("0.4.0", false, Bump::Patch, &["feat!: a"]),
            version("0.5.0")
        );
    }

    fn first_version(
        application: bool,
        conventional: bool,
        overrides: &BTreeMap<String, Version>,
        messages: &[&str],
    ) -> Result<Proposed, super::ProposalError> {
        let units = [unit("core", "0.0.0", &[])];
        let history = BTreeMap::from([(
            "core".to_owned(),
            History {
                baseline_tag: None,
                changed: true,
                conventional,
                commits: commits(messages),
            },
        )]);
        let applications = if application {
            BTreeSet::from(["core".into()])
        } else {
            BTreeSet::new()
        };
        analyze(
            &units,
            &history,
            Policy {
                applications: &applications,
                non_bumping: &BTreeSet::new(),
                overrides,
            },
            |_, _| Ok(Bump::Major),
        )
        .map(|proposal| proposal.versions()["core"].clone())
    }

    #[test]
    fn an_unversioned_unit_takes_its_first_version_from_its_commits() {
        let first = |application, messages: &[&str]| {
            first_version(application, true, &BTreeMap::new(), messages).unwrap()
        };
        assert_eq!(
            first(false, &["feat: a"]),
            Proposed::First(version("0.1.0"))
        );
        assert_eq!(
            first(false, &["fix: a", "feat: b"]),
            Proposed::First(version("0.1.0"))
        );
        assert_eq!(first(false, &["fix: a"]), Proposed::First(version("0.0.1")));
        assert_eq!(
            first(false, &["fix!: a"]),
            Proposed::First(version("0.1.0"))
        );
        assert_eq!(
            first(true, &["chore: a"]),
            Proposed::First(version("0.0.1"))
        );
    }

    #[test]
    fn an_unversioned_override_wins() {
        let overrides = BTreeMap::from([("core".into(), version("1.0.0"))]);
        assert_eq!(
            first_version(false, false, &overrides, &[]).unwrap(),
            Proposed::First(version("1.0.0"))
        );
        assert_eq!(
            first_version(false, true, &overrides, &["feat: a"]).unwrap(),
            Proposed::First(version("1.0.0"))
        );
    }

    #[test]
    fn an_unversioned_unit_without_a_bumping_commit_is_an_error() {
        for (application, conventional, messages) in [
            (false, false, &["feat: a"][..]),
            (true, false, &["feat: a"][..]),
            (false, true, &["chore: a"][..]),
            (false, true, &[][..]),
            (true, true, &[][..]),
        ] {
            assert!(
                matches!(
                    first_version(application, conventional, &BTreeMap::new(), messages),
                    Err(super::ProposalError::FirstVersionUnknown { unit, path })
                        if unit == "core" && path.as_path() == Path::new("core/Cargo.toml")
                ),
                "{application} {conventional} {messages:?}"
            );
        }
    }

    #[test]
    fn major_from_one_is_a_major_bump() {
        assert_eq!(
            library_bump("1.4.2", Bump::Major).unwrap(),
            version("2.0.0")
        );
    }
}