ephemeris_release/

publication.rs

//! The publication contract. Every step reads the remote first and
//! converges, so a rerun after any failure finishes the job.
//!
//! 1. Check that the commit is the merged release proposal.
//! 2. Select the units whose tag points at the commit, or whose version is
//!    newer than their latest tag.
//! 3. Check the staged artifact files of the selected units.
//! 4. Publish each unit's package unless its registry has it.
//! 5. Tag the commit locally and on the forge. A tag at another commit is an
//!    error.
//! 6. Create the draft release, converge its assets, push the OCI artifacts,
//!    and publish the draft.

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

use ephemeris_files::RepositoryRoot;

use crate::adapters::{PinError, ResolveError, read_digest};
use crate::artifacts::{ArtifactError, OciLogin, PackageKind, Publication, Stage};
use crate::error::GitFailure;
use crate::git::GitHistory;
use crate::publisher::{PublishError, UnitRelease};
use crate::state::{ReleaseArtifactState, ReleaseState, ReleaseTarget};
use crate::traits::GitRefs;
use crate::unit::{Unit, UnitStatus, UnparsableTag};

/// Unit selection or artifact publication failure.
#[derive(Debug, thiserror::Error)]
pub(crate) enum PublicationError {
    /// The configured units cannot be resolved.
    #[error(transparent)]
    Discovery(#[from] ResolveError),
    /// Listing or reading tags failed.
    #[error("release publication git operation failed")]
    Git(#[from] GitFailure),
    /// Publishing the selected units failed.
    #[error(transparent)]
    Publish(#[from] PublishError),
    /// Publication needs the branch tip, and the commit is not it.
    #[error("publication commit {commit} is not the authoritative branch tip {tip}")]
    NotTip {
        /// The commit given to publish.
        commit: String,
        /// The tip of the authoritative branch.
        tip: String,
    },
    /// Artifacts are configured for a unit that does not exist.
    #[error("artifact unit {0:?} is not configured")]
    UnconfiguredArtifactUnit(String),
    /// A selected unit has artifacts, and the run was given none.
    #[error("unit {0:?} has artifacts, and no artifact manifest was given")]
    MissingArtifacts(String),
    /// A publishing unit does not declare exactly one package artifact.
    #[error("unit {unit:?} publishes to {kind} and declares {actual} {kind} artifacts, not one")]
    PackageArtifactCount {
        /// The release unit.
        unit: String,
        /// The artifact kind its target needs.
        kind: &'static str,
        /// The declared count.
        actual: usize,
    },
    /// A unit declares a package artifact its target does not publish.
    #[error("artifact {name:?} of unit {unit:?} does not match the unit's publication target")]
    UnexpectedPackageArtifact {
        /// The release unit.
        unit: String,
        /// The artifact.
        name: String,
    },
    /// A unit's revision file holds 0.
    #[error("unit {0:?} revision must be positive")]
    ZeroRevision(String),
    /// Tags exist under a unit's prefix and none of them names a version.
    #[error(transparent)]
    UnparsableTag(#[from] UnparsableTag),
    /// Staging validation failed.
    #[error(transparent)]
    Artifact(#[from] ArtifactError),
    /// A digest pin file cannot be read.
    #[error(transparent)]
    Pin(#[from] PinError),
    /// A digest pin differs from the digest of the built dependency asset.
    #[error(
        "{unit:?} pins {pinned} for the asset {artifact:?} of {dependency:?}, but the build has \
         {built}"
    )]
    DigestMismatch {
        /// The unit holding the pin.
        unit: String,
        /// The dependency that owns the asset.
        dependency: String,
        /// The asset artifact.
        artifact: String,
        /// The digest in the pin file.
        pinned: String,
        /// The digest of the built asset.
        built: String,
    },
}

impl ReleaseState {
    /// Select the configured units this run publishes or resumes.
    ///
    /// # Errors
    /// Returns an error for invalid release state, git failures, or malformed
    /// versions.
    pub(crate) fn selected_units<G: GitHistory + GitRefs>(
        &self,
        repository: &RepositoryRoot,
        commit: &str,
        git: &G,
    ) -> Result<Vec<Unit>, PublicationError> {
        let discovered = self.discover_units(repository)?;
        let mut selected = BTreeSet::new();
        for unit in &discovered {
            let tags = git
                .tags(repository.as_path(), &unit.tag_prefix)
                .map_err(GitFailure::new)
                .map_err(PublicationError::Git)?;
            let select = match unit.status(&tags)? {
                UnitStatus::Pending => true,
                UnitStatus::Released {
                    latest: _,
                    tagged: true,
                } => git
                    .reference(repository.as_path(), &format!("refs/tags/{}", unit.tag()))
                    .map_err(GitFailure::new)
                    .map_err(PublicationError::Git)?
                    .is_some_and(|target| target == commit),
                UnitStatus::Unversioned
                | UnitStatus::Released {
                    latest: _,
                    tagged: false,
                } => false,
            };
            if select {
                selected.insert(unit.name.clone());
            }
        }
        Ok(discovered
            .into_iter()
            .filter(|unit| selected.contains(&unit.name))
            .map(|mut unit| {
                unit.dependencies
                    .retain(|dependency| selected.contains(dependency.as_str()));
                unit
            })
            .collect())
    }

    /// Stage the forge release of every selected unit, checking every local
    /// file before anything is created.
    ///
    /// # Errors
    /// Returns an error for invalid artifact configuration, a zero revision, a
    /// unit with artifacts but no `artifacts`, or staged files that do not
    /// match, or an OCI artifact has no `login`.
    pub(crate) fn stage_releases<'a>(
        &'a self,
        repository: &RepositoryRoot,
        commit: &str,
        units: Vec<Unit>,
        artifacts: Option<&Stage>,
        login: Option<&OciLogin>,
    ) -> Result<Vec<UnitRelease<'a>>, PublicationError> {
        if let Some(key) = self
            .artifacts
            .keys()
            .find(|key| !self.units.contains_key(*key))
        {
            return Err(PublicationError::UnconfiguredArtifactUnit(key.clone()));
        }
        let empty = Stage::empty();
        let selected: BTreeSet<String> = units.iter().map(|unit| unit.name.clone()).collect();
        units
            .into_iter()
            .map(|unit| {
                if unit.revision == Some(0) {
                    return Err(PublicationError::ZeroRevision(unit.name));
                }
                let configured = self.artifacts.get(&unit.name);
                let staged = match (artifacts, configured) {
                    (Some(staged), _) => staged,
                    (None, Some(artifacts)) if !artifacts.is_empty() => {
                        return Err(PublicationError::MissingArtifacts(unit.name.clone()));
                    }
                    (None, _) => &empty,
                };
                let mut expected = Vec::new();
                let mut oci = Vec::new();
                for (name, artifact) in configured.into_iter().flatten() {
                    match artifact {
                        ReleaseArtifactState::Asset(spec) => expected.push((name.as_str(), spec)),
                        ReleaseArtifactState::Oci(spec) => oci.push((name.as_str(), spec)),
                        ReleaseArtifactState::Cargo { package: _ }
                        | ReleaseArtifactState::Npm { package: _ } => {}
                    }
                }
                unit.check_digest_pins(repository, staged, &selected)?;
                let package = unit.package_file(configured, staged)?;
                let publication = Publication {
                    unit: unit.name.clone(),
                    tag: unit.tag(),
                    target_commit: commit.to_owned(),
                    title: unit.title(),
                    notes: unit.release_notes(repository)?,
                    expected,
                    oci,
                    version: unit.version.to_string(),
                    working_directory: repository.as_path().to_owned(),
                };
                let release = staged.release(publication, login)?;
                Ok(UnitRelease {
                    unit,
                    release,
                    package,
                })
            })
            .collect()
    }
}

impl Unit {
    /// Check that every digest pin of a `selected` dependency holds the
    /// digest of the staged asset it names.
    ///
    /// A digest pin changes only in the release commit of its dependency, and
    /// that release selects the dependency, so the check sees every changed
    /// pin. The staged asset of an unselected dependency is a fresh build, not
    /// the published asset.
    fn check_digest_pins(
        &self,
        repository: &RepositoryRoot,
        staged: &Stage,
        selected: &BTreeSet<String>,
    ) -> Result<(), PublicationError> {
        for (dependency, pin) in &self.pins {
            if !selected.contains(dependency) {
                continue;
            }
            for (artifact, digest) in &pin.digests {
                let Some(bytes) = staged.asset_bytes(dependency, artifact)? else {
                    continue;
                };
                let built = digest.algorithm.hex(&bytes);
                let pinned = read_digest(repository, self, dependency, digest)?;
                if pinned != built {
                    return Err(PublicationError::DigestMismatch {
                        unit: self.name.clone(),
                        dependency: dependency.clone(),
                        artifact: artifact.clone(),
                        pinned,
                        built,
                    });
                }
            }
        }
        Ok(())
    }

    /// The staged package file of a unit that publishes to a registry.
    ///
    /// A unit that does not publish needs none and may not declare one.
    pub(crate) fn package_file(
        &self,
        configured: Option<&BTreeMap<String, ReleaseArtifactState>>,
        staged: &Stage,
    ) -> Result<Option<PathBuf>, PublicationError> {
        let wanted = match &self.target {
            ReleaseTarget::Cargo {
                publish: true,
                manifest: _,
            } => Some(PackageKind::Cargo),
            ReleaseTarget::Npm {
                publish: true,
                manifest: _,
            } => Some(PackageKind::Npm),
            ReleaseTarget::Cargo {
                publish: false,
                manifest: _,
            }
            | ReleaseTarget::Npm {
                publish: false,
                manifest: _,
            }
            | ReleaseTarget::VersionFile { version_file: _ }
            | ReleaseTarget::Document { path: _, key: _ } => None,
        };
        let mut declared = Vec::new();
        for (name, artifact) in configured.into_iter().flatten() {
            let (kind, package) = match artifact {
                ReleaseArtifactState::Cargo { package } => (PackageKind::Cargo, package),
                ReleaseArtifactState::Npm { package } => (PackageKind::Npm, package),
                ReleaseArtifactState::Asset(_) | ReleaseArtifactState::Oci(_) => continue,
            };
            if wanted != Some(kind) {
                return Err(PublicationError::UnexpectedPackageArtifact {
                    unit: self.name.clone(),
                    name: name.clone(),
                });
            }
            declared.push((name, package));
        }
        let Some(kind) = wanted else {
            return Ok(None);
        };
        let [(name, package)] = declared[..] else {
            return Err(PublicationError::PackageArtifactCount {
                unit: self.name.clone(),
                kind: kind.label(),
                actual: declared.len(),
            });
        };
        Ok(Some(staged.package(&self.name, kind, name, package)?))
    }
}

#[cfg(test)]
mod tests {
    use std::cell::RefCell;
    use std::collections::BTreeMap;
    use std::convert::Infallible;
    use std::fs;
    #[cfg(unix)]
    use std::os::unix::fs::symlink;
    use std::path::{Path, PathBuf};

    use ephemeris_files::RepositoryRoot;
    use ephemeris_token::Token;

    use super::PublicationError;
    use crate::artifacts::{ArtifactError, OciLogin, Stage};
    use crate::digest::DigestAlgorithm;
    use crate::git::{GitHistory, UnitScope};
    use crate::publisher::{Authority, Publisher};
    use crate::remote::{RemoteAsset, RemoteRelease};
    use crate::state::{AssetSpec, OciSpec, ReleaseArtifactState, ReleaseUnitState};
    use crate::traits::PackagePublisher;
    use crate::unit::{Unit, UnparsableTag};
    use crate::{Author, ForgeRelease, ForgeTags, GitCommands, GitRefs, ReleaseState};

    const AUTHOR: Author<'static> = Author {
        name: "Release Bot",
        email: "release@example.invalid",
    };

    const EMPTY_STATE: &str = r#"{"cargo":null,"npm":null,"authoritative_branch":"main","proposal_branch":"ephemeris/release","commit_subject":"release: {unit} {version}","commit_format":null,"units":{},"artifacts":{},"account":{"login":null,"name":{"literal":"Release Bot"},"email":{"literal":"release@example.invalid"}},"packages_credential":"forge"}"#;

    const CARGO_TARGET: &str =
        r#"{"ecosystem":"cargo","manifest":"core/Cargo.toml","publish":true}"#;

    /// A Git operation the scenario does not expect.
    struct DigestFixture {
        _directories: (tempfile::TempDir, tempfile::TempDir),
        state: ReleaseState,
        root: RepositoryRoot,
        staged: Stage,
    }

    impl DigestFixture {
        fn stage(&self) -> Result<usize, PublicationError> {
            self.stage_without("")
        }

        fn stage_without(&self, unselected: &str) -> Result<usize, PublicationError> {
            let mut units = self.state.discover_units(&self.root)?;
            units.retain(|unit| unit.name != unselected);
            self.state
                .stage_releases(&self.root, "merged", units, Some(&self.staged), None)
                .map(|releases| releases.len())
        }
    }

    #[derive(Debug, thiserror::Error)]
    #[error("unexpected git operation: {0}")]
    struct Unexpected(&'static str);

    /// Lists fixed tags, all on an earlier commit; every other Git operation
    /// is unexpected.
    struct TagsOnly(&'static [&'static str]);

    impl GitRefs for TagsOnly {
        type Error = Unexpected;

        fn reference(&self, _: &Path, name: &str) -> Result<Option<String>, Self::Error> {
            let tag = name.strip_prefix("refs/tags/").unwrap_or(name);
            Ok(self.0.contains(&tag).then(|| "released".to_owned()))
        }
    }

    impl GitHistory for TagsOnly {
        type Error = Unexpected;

        fn tags(&self, _: &Path, prefix: &str) -> Result<Vec<String>, Self::Error> {
            Ok(self
                .0
                .iter()
                .filter(|tag| tag.starts_with(prefix))
                .map(|tag| (*tag).to_owned())
                .collect())
        }

        fn resolve(&self, _: &Path, _: &str) -> Result<String, Self::Error> {
            Err(Unexpected("selection does not resolve revisions"))
        }

        fn has_changes(
            &self,
            _: &Path,
            _: Option<&str>,
            _: &str,
            _: UnitScope<'_>,
        ) -> Result<bool, Self::Error> {
            Err(Unexpected("selection does not diff"))
        }

        fn commit_messages(
            &self,
            _: &Path,
            _: Option<&str>,
            _: &str,
            _: UnitScope<'_>,
        ) -> Result<Vec<String>, Self::Error> {
            Err(Unexpected("selection does not read commits"))
        }

        fn equivalent(&self, _: &Path, _: &str, _: &str, _: &str) -> Result<bool, Self::Error> {
            Err(Unexpected("selection does not compare commits"))
        }

        fn is_ancestor(&self, _: &Path, _: &str, _: &str) -> Result<bool, Self::Error> {
            Err(Unexpected("selection does not compare ancestry"))
        }
    }

    #[derive(Default)]
    struct FakeRemote {
        release: RefCell<bool>,
        assets: RefCell<Vec<(RemoteAsset, Vec<u8>)>>,
        published: RefCell<bool>,
        drafts: RefCell<Vec<(String, String, String)>>,
    }

    impl ForgeTags for FakeRemote {
        type Error = Infallible;

        async fn tag_commit(&self, _: &str) -> Result<Option<String>, Self::Error> {
            Ok(None)
        }
    }

    impl ForgeRelease for FakeRemote {
        type Error = Infallible;

        async fn release_by_tag(&self, _: &str) -> Result<Option<RemoteRelease>, Self::Error> {
            Ok(self.release.borrow().then_some(RemoteRelease {
                id: 1,
                draft: !*self.published.borrow(),
            }))
        }
        async fn create_draft(
            &self,
            tag: &str,
            _: &str,
            title: &str,
            notes: &str,
        ) -> Result<u64, Self::Error> {
            self.drafts
                .borrow_mut()
                .push((tag.to_owned(), title.to_owned(), notes.to_owned()));
            *self.release.borrow_mut() = true;
            Ok(1)
        }
        async fn assets(&self, _: u64) -> Result<Vec<RemoteAsset>, Self::Error> {
            Ok(self
                .assets
                .borrow()
                .iter()
                .map(|(asset, _)| asset.clone())
                .collect())
        }
        async fn upload(&self, _: u64, filename: &str, bytes: &[u8]) -> Result<(), Self::Error> {
            let id = u64::try_from(self.assets.borrow().len())
                .map_or(u64::MAX, |count| count.saturating_add(1));
            self.assets.borrow_mut().push((
                RemoteAsset {
                    id,
                    name: filename.to_owned(),
                    size: u64::try_from(bytes.len()).unwrap_or(u64::MAX),
                    sha256: None,
                    download_url: String::new(),
                },
                bytes.to_vec(),
            ));
            Ok(())
        }
        async fn delete_asset(&self, _: u64, asset_id: u64) -> Result<(), Self::Error> {
            self.assets
                .borrow_mut()
                .retain(|(asset, _)| asset.id != asset_id);
            Ok(())
        }
        async fn asset_bytes(&self, asset: &RemoteAsset) -> Result<Vec<u8>, Self::Error> {
            Ok(self
                .assets
                .borrow()
                .iter()
                .find(|(candidate, _)| candidate.id == asset.id)
                .unwrap()
                .1
                .clone())
        }
        async fn publish(&self, _: u64) -> Result<(), Self::Error> {
            *self.published.borrow_mut() = true;
            Ok(())
        }
    }

    /// Stage and publish the forge release of every configured unit.
    async fn publish_configured_artifacts(
        state: &ReleaseState,
        repository: &RepositoryRoot,
        commit: &str,
        manifest: &Path,
        directory: &Path,
        remote: &FakeRemote,
    ) -> Result<(), PublicationError> {
        let login = OciLogin::new("bot".into(), Token::new("secret"));
        publish_with_login(
            state,
            repository,
            commit,
            manifest,
            directory,
            remote,
            Some(&login),
        )
        .await
    }

    async fn publish_with_login(
        state: &ReleaseState,
        repository: &RepositoryRoot,
        commit: &str,
        manifest: &Path,
        directory: &Path,
        remote: &FakeRemote,
        login: Option<&OciLogin>,
    ) -> Result<(), PublicationError> {
        let units = state.discover_units(repository)?;
        let staged = Stage::read(manifest, directory)?;
        for release in state.stage_releases(repository, commit, units, Some(&staged), login)? {
            release
                .release
                .prepare(remote)
                .await?
                .publish(remote)
                .await?;
        }
        Ok(())
    }

    fn unit(name: &str, target: &str) -> String {
        format!(
            r#"{{"target":{target},"source":["{name}"],"changelog":"{name}/CHANGELOG.md","dependencies":[],"pins":{{}},"tag_prefix":"{name}-v","kind":"application","application_bump":"patch","revision_file":null}}"#
        )
    }

    fn version_file(name: &str) -> String {
        format!(r#"{{"ecosystem":"version-file","version_file":"{name}/VERSION"}}"#)
    }

    fn state(units: &[(&str, String)]) -> ReleaseState {
        let units = units
            .iter()
            .map(|(name, unit)| format!(r#""{name}":{unit}"#))
            .collect::<Vec<_>>()
            .join(",");
        facet_json::from_str(
            &EMPTY_STATE.replace(r#""units":{}"#, &format!(r#""units":{{{units}}}"#)),
        )
        .unwrap()
    }

    fn artifact_fixture() -> (tempfile::TempDir, tempfile::TempDir, PathBuf, ReleaseState) {
        let repository = tempfile::tempdir().unwrap();
        fs::create_dir_all(repository.path().join("app")).unwrap();
        fs::write(repository.path().join("app/VERSION"), "2.4.0\n").unwrap();
        fs::write(repository.path().join("app/revision"), "3\n").unwrap();
        let stage = tempfile::tempdir().unwrap();
        fs::create_dir_all(stage.path().join("artifacts")).unwrap();
        fs::write(stage.path().join("artifacts/web.tar"), b"web asset").unwrap();
        let manifest = stage.path().join("manifest.json");
        fs::write(
            &manifest,
            r#"[{"kind":"asset","unit":"web","name":"web","package":"web-package","output":"web","filename":"web.tar","format":"tar","variant":"default","required_names":[],"path":"artifacts/web.tar"}]"#,
        )
        .unwrap();
        let web = unit("app", &version_file("app"))
            .replace("app-v", "web-v")
            .replace(
                r#""revision_file":null"#,
                r#""revision_file":"app/revision""#,
            );
        let release_state = ReleaseState {
            artifacts: BTreeMap::from([(
                "web".into(),
                BTreeMap::from([(
                    "web".into(),
                    ReleaseArtifactState::Asset(AssetSpec {
                        package: "web-package".into(),
                        output: "web".into(),
                        filename: "web.tar".into(),
                        format: "tar".into(),
                        variant: "default".into(),
                        required_names: Vec::new(),
                    }),
                )]),
            )]),
            ..state(&[("web", web)])
        };
        (repository, stage, manifest, release_state)
    }

    fn package_unit(target: &str) -> Unit {
        let state: ReleaseUnitState = facet_json::from_str(&unit("core", target)).unwrap();
        Unit::configured(
            "core",
            Some("core".into()),
            "1.0.0".parse().unwrap(),
            &state,
        )
    }

    fn package_stage(entry: &str, file: Option<&str>) -> (tempfile::TempDir, Stage) {
        let directory = tempfile::tempdir().unwrap();
        fs::create_dir_all(directory.path().join("artifacts")).unwrap();
        if let Some(file) = file {
            fs::write(directory.path().join(file), b"package").unwrap();
        }
        let manifest = directory.path().join("manifest.json");
        fs::write(&manifest, format!("[{entry}]")).unwrap();
        let stage = Stage::read(&manifest, directory.path()).unwrap();
        (directory, stage)
    }

    fn declared(artifact: ReleaseArtifactState) -> BTreeMap<String, ReleaseArtifactState> {
        BTreeMap::from([("crate".to_owned(), artifact)])
    }

    /// Initialize a repository at `root` that tracks every file in it.
    fn track_all(root: &Path) {
        let repository = git2::Repository::init(root).unwrap();
        let mut index = repository.index().unwrap();
        index
            .add_all(["*"], git2::IndexAddOption::DEFAULT, None)
            .unwrap();
        index.write().unwrap();
    }

    fn publication_units<G: GitHistory + GitRefs>(
        state: &ReleaseState,
        repository: &RepositoryRoot,
        commit: &str,
        git: &G,
    ) -> Result<Vec<Unit>, PublicationError> {
        state.selected_units(repository, commit, git)
    }

    #[test]
    fn a_publishing_cargo_unit_gets_its_staged_crate() {
        let (directory, stage) = package_stage(
            r#"{"kind":"cargo","unit":"core","name":"crate","package":"crate-core","path":"artifacts/core.crate"}"#,
            Some("artifacts/core.crate"),
        );
        let configured = declared(ReleaseArtifactState::Cargo {
            package: "crate-core".into(),
        });
        assert_eq!(
            package_unit(CARGO_TARGET)
                .package_file(Some(&configured), &stage)
                .unwrap(),
            Some(directory.path().join("artifacts/core.crate"))
        );
    }

    #[test]
    fn a_publishing_npm_unit_gets_its_staged_tarball() {
        let (directory, stage) = package_stage(
            r#"{"kind":"npm","unit":"core","name":"crate","package":"npm-pack-core","path":"artifacts/core.tgz"}"#,
            Some("artifacts/core.tgz"),
        );
        let configured = declared(ReleaseArtifactState::Npm {
            package: "npm-pack-core".into(),
        });
        let target = r#"{"ecosystem":"npm","manifest":"core/package.json","publish":true}"#;
        assert_eq!(
            package_unit(target)
                .package_file(Some(&configured), &stage)
                .unwrap(),
            Some(directory.path().join("artifacts/core.tgz"))
        );
    }

    #[test]
    fn a_staged_package_file_that_is_absent_is_an_error() {
        let (_directory, stage) = package_stage(
            r#"{"kind":"cargo","unit":"core","name":"crate","package":"crate-core","path":"artifacts/core.crate"}"#,
            None,
        );
        let configured = declared(ReleaseArtifactState::Cargo {
            package: "crate-core".into(),
        });
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(Some(&configured), &stage),
            Err(PublicationError::Artifact(ArtifactError::Io {
                path: _,
                source: _
            }))
        ));
    }

    #[test]
    fn a_staged_package_of_another_name_is_a_mismatch() {
        let (_directory, stage) = package_stage(
            r#"{"kind":"cargo","unit":"core","name":"crate","package":"other","path":"artifacts/core.crate"}"#,
            Some("artifacts/core.crate"),
        );
        let configured = declared(ReleaseArtifactState::Cargo {
            package: "crate-core".into(),
        });
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(Some(&configured), &stage),
            Err(PublicationError::Artifact(
                ArtifactError::ArtifactMismatch {
                    name: _,
                    field: "package"
                }
            ))
        ));
    }

    #[test]
    fn a_staged_package_at_another_path_is_rejected() {
        let (_directory, stage) = package_stage(
            r#"{"kind":"cargo","unit":"core","name":"crate","package":"crate-core","path":"artifacts/other.crate"}"#,
            Some("artifacts/other.crate"),
        );
        let configured = declared(ReleaseArtifactState::Cargo {
            package: "crate-core".into(),
        });
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(Some(&configured), &stage),
            Err(PublicationError::Artifact(ArtifactError::UnexpectedPath {
                name: _,
                path: _
            }))
        ));
    }

    #[test]
    fn a_publishing_unit_needs_exactly_one_package_artifact() {
        let (_directory, stage) = package_stage("", None);
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(None, &stage),
            Err(PublicationError::PackageArtifactCount {
                unit: _,
                kind: "cargo",
                actual: 0
            })
        ));
        let configured = BTreeMap::from([
            (
                "a".to_owned(),
                ReleaseArtifactState::Cargo {
                    package: "a".into(),
                },
            ),
            (
                "b".to_owned(),
                ReleaseArtifactState::Cargo {
                    package: "b".into(),
                },
            ),
        ]);
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(Some(&configured), &stage),
            Err(PublicationError::PackageArtifactCount {
                unit: _,
                kind: "cargo",
                actual: 2
            })
        ));
    }

    #[test]
    fn a_package_artifact_of_the_wrong_kind_is_rejected() {
        let (_directory, stage) = package_stage("", None);
        let configured = declared(ReleaseArtifactState::Npm {
            package: "npm-pack-core".into(),
        });
        assert!(matches!(
            package_unit(CARGO_TARGET).package_file(Some(&configured), &stage),
            Err(PublicationError::UnexpectedPackageArtifact { unit: _, name })
                if name == "crate"
        ));
        let private = r#"{"ecosystem":"cargo","manifest":"core/Cargo.toml","publish":false}"#;
        assert!(matches!(
            package_unit(private).package_file(Some(&configured), &stage),
            Err(PublicationError::UnexpectedPackageArtifact { unit: _, name: _ })
        ));
    }

    #[test]
    fn a_unit_that_does_not_publish_needs_no_package_file() {
        let (_directory, stage) = package_stage("", None);
        let private = r#"{"ecosystem":"cargo","manifest":"core/Cargo.toml","publish":false}"#;
        assert_eq!(
            package_unit(private).package_file(None, &stage).unwrap(),
            None
        );
    }

    #[tokio::test]
    async fn version_file_artifact_publication_does_not_need_a_cargo_workspace() {
        let (repository, stage, manifest, release_state) = artifact_fixture();
        let remote = FakeRemote::default();
        publish_configured_artifacts(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &remote,
        )
        .await
        .unwrap();
        assert!(*remote.published.borrow());
    }

    #[tokio::test]
    async fn revision_tracked_artifact_unit_gets_exactly_one_tag_and_one_release() {
        struct FakeGit {
            events: RefCell<Vec<String>>,
        }
        impl GitCommands for FakeGit {
            type Error = Infallible;
            fn authoritative_head(&self, _: &Path, _: &str) -> Result<String, Self::Error> {
                Ok("0123456789abcdef0123456789abcdef01234567".into())
            }
            fn create_tag(
                &self,
                _: &Path,
                tag: &str,
                _: &str,
                _: Author<'_>,
            ) -> Result<(), Self::Error> {
                self.events.borrow_mut().push(format!("tag:{tag}"));
                Ok(())
            }
            fn push_tag(&self, _: &Path, tag: &str) -> Result<(), Self::Error> {
                self.events.borrow_mut().push(format!("push:{tag}"));
                Ok(())
            }
        }
        impl GitRefs for FakeGit {
            type Error = Infallible;
            fn reference(&self, _: &Path, _: &str) -> Result<Option<String>, Self::Error> {
                Ok(None)
            }
        }
        struct NoPackages;
        impl PackagePublisher for NoPackages {
            type Error = Infallible;
            async fn is_published(&self, _: &Unit) -> Result<bool, Self::Error> {
                Ok(true)
            }
            async fn publish(&self, _: &Unit, _: &Path) -> Result<(), Self::Error> {
                Ok(())
            }
        }

        let (repository, stage, manifest, release_state) = artifact_fixture();
        fs::write(
            repository.path().join("app/CHANGELOG.md"),
            "# Changelog\n\n## [Unreleased]\n\n## [2.4.0] - 2026-10-21\n\n### Changed\n\n- Faster \
             uploads.\n\n## [2.3.0] - 2026-09-01\n\n- Older.\n",
        )
        .unwrap();
        let root = RepositoryRoot::new(repository.path()).unwrap();
        let units = release_state.discover_units(&root).unwrap();
        assert_eq!(units.len(), 1);
        assert_eq!(units[0].revision, Some(3));
        assert_eq!(units[0].tag(), "web-v2.4.0-3");
        let releases = release_state
            .stage_releases(
                &root,
                "0123456789abcdef0123456789abcdef01234567",
                units,
                Some(&Stage::read(&manifest, stage.path()).unwrap()),
                None,
            )
            .unwrap();

        let git = FakeGit {
            events: RefCell::new(Vec::new()),
        };
        let remote = FakeRemote::default();
        Publisher::new(&git, &NoPackages, &remote, AUTHOR)
            .publish(
                repository.path(),
                &Authority {
                    branch: "origin/main".into(),
                    commit: "0123456789abcdef0123456789abcdef01234567".into(),
                },
                &releases,
            )
            .await
            .unwrap();
        assert_eq!(
            &*git.events.borrow(),
            &["tag:web-v2.4.0-3", "push:web-v2.4.0-3"]
        );
        assert!(*remote.published.borrow());
        assert_eq!(remote.assets.borrow().len(), 1);
        assert_eq!(
            &*remote.drafts.borrow(),
            &[(
                "web-v2.4.0-3".to_owned(),
                "web 2.4.0-3".to_owned(),
                "### Changed\n\n- Faster uploads.".to_owned()
            )]
        );
    }

    #[tokio::test]
    async fn artifact_unit_without_revision_file_publishes_under_the_plain_version() {
        let (repository, stage, manifest, mut release_state) = artifact_fixture();
        release_state.units.get_mut("web").unwrap().revision_file = None;
        let root = RepositoryRoot::new(repository.path()).unwrap();
        let units = release_state.discover_units(&root).unwrap();
        assert_eq!(units[0].revision, None);
        assert_eq!(units[0].tag(), "web-v2.4.0");
        let remote = FakeRemote::default();
        publish_configured_artifacts(
            &release_state,
            &root,
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &remote,
        )
        .await
        .unwrap();
        assert!(*remote.published.borrow());
        assert_eq!(
            &*remote.drafts.borrow(),
            &[(
                "web-v2.4.0".to_owned(),
                "web 2.4.0".to_owned(),
                String::new()
            )]
        );
    }

    #[cfg(unix)]
    fn oci_fixture(
        script: &str,
        latest: bool,
    ) -> (
        tempfile::TempDir,
        tempfile::TempDir,
        PathBuf,
        ReleaseState,
        PathBuf,
    ) {
        use std::os::unix::fs::PermissionsExt as _;

        let (repository, stage, manifest, mut release_state) = artifact_fixture();
        let log = stage.path().join("pushed");
        let program = stage.path().join("push");
        fs::write(&program, format!("#!/bin/sh\n{script}\n")).unwrap();
        fs::set_permissions(&program, fs::Permissions::from_mode(0o755)).unwrap();
        fs::write(
            &manifest,
            format!(
                r#"[{{"kind":"asset","unit":"web","name":"web","package":"web-package","output":"web","filename":"web.tar","format":"tar","variant":"default","required_names":[],"path":"artifacts/web.tar"}},{{"kind":"oci","unit":"web","name":"image","package":"web-image","registry":"registry.example/team","repository":"web","latest":{latest},"program":{program:?}}}]"#
            ),
        )
        .unwrap();
        release_state.artifacts.get_mut("web").unwrap().insert(
            "image".into(),
            ReleaseArtifactState::Oci(OciSpec {
                package: "web-image".into(),
                registry: "registry.example/team".into(),
                repository: "web".into(),
                latest,
            }),
        );
        (repository, stage, manifest, release_state, log)
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn oci_artifact_is_pushed_for_the_version_and_latest() {
        let (repository, stage, manifest, release_state, log) = oci_fixture(
            "printf '%s\\n' \"$1\" >> \"$(dirname \"$0\")/pushed\"\npwd -P > \"$(dirname \
             \"$0\")/cwd\"\nprintf '%s:%s' \"$EPHEMERIS_OCI_USERNAME\" \
             \"$EPHEMERIS_OCI_PASSWORD\" > \"$(dirname \"$0\")/login\"",
            true,
        );
        let remote = FakeRemote::default();
        publish_configured_artifacts(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &remote,
        )
        .await
        .unwrap();
        assert!(*remote.published.borrow());
        assert_eq!(
            fs::read_to_string(log).unwrap(),
            "registry.example/team/web:2.4.0\nregistry.example/team/web:latest\n"
        );
        assert_eq!(
            fs::read_to_string(stage.path().join("cwd")).unwrap().trim(),
            repository.path().canonicalize().unwrap().to_str().unwrap()
        );
        assert_eq!(
            fs::read_to_string(stage.path().join("login")).unwrap(),
            "bot:secret"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn oci_artifact_without_a_registry_login_is_an_error_before_any_push() {
        let (repository, stage, manifest, release_state, log) =
            oci_fixture("touch \"$(dirname \"$0\")/pushed\"", true);
        let remote = FakeRemote::default();
        let error = publish_with_login(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &remote,
            None,
        )
        .await
        .unwrap_err();
        assert!(matches!(
            error,
            PublicationError::Artifact(ArtifactError::MissingRegistryLogin(name))
                if name == "image"
        ));
        assert!(!log.exists());
        assert!(remote.drafts.borrow().is_empty());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn oci_artifact_without_latest_is_pushed_once() {
        let (repository, stage, manifest, release_state, log) = oci_fixture(
            "printf '%s\\n' \"$1\" >> \"$(dirname \"$0\")/pushed\"",
            false,
        );
        publish_configured_artifacts(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &FakeRemote::default(),
        )
        .await
        .unwrap();
        assert_eq!(
            fs::read_to_string(log).unwrap(),
            "registry.example/team/web:2.4.0\n"
        );
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn failing_oci_push_names_the_artifact_and_status() {
        let (repository, stage, manifest, release_state, log) = oci_fixture("exit 3", true);
        let error = publish_configured_artifacts(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &FakeRemote::default(),
        )
        .await
        .unwrap_err();
        assert!(matches!(
            error,
            PublicationError::Artifact(ArtifactError::OciPush { name, status })
                if name == "image" && status.code() == Some(3)
        ));
        assert!(!log.exists());
    }

    #[tokio::test]
    async fn artifact_unit_with_zero_revision_is_rejected() {
        let (repository, stage, manifest, release_state) = artifact_fixture();
        fs::write(repository.path().join("app/revision"), "0\n").unwrap();
        let remote = FakeRemote::default();
        let error = publish_configured_artifacts(
            &release_state,
            &RepositoryRoot::new(repository.path()).unwrap(),
            "0123456789abcdef0123456789abcdef01234567",
            &manifest,
            stage.path(),
            &remote,
        )
        .await
        .unwrap_err();
        assert!(matches!(error, PublicationError::ZeroRevision(key) if key == "web"));
        assert!(remote.drafts.borrow().is_empty());
    }

    #[test]
    fn selection_uses_configured_tag_prefix() {
        let root = tempfile::tempdir().unwrap();
        fs::write(
            root.path().join("Cargo.toml"),
            "[workspace]\nmembers = [\"core\"]\n",
        )
        .unwrap();
        fs::create_dir_all(root.path().join("core/src")).unwrap();
        fs::write(root.path().join("core/src/lib.rs"), "pub fn fixture() {}\n").unwrap();
        fs::write(
            root.path().join("core/Cargo.toml"),
            "[package]\nname = \"core\"\nversion = \"1.1.0\"\n",
        )
        .unwrap();
        fs::write(root.path().join("README.md"), "fixture\n").unwrap();
        track_all(root.path());

        let core = unit(
            "core",
            r#"{"ecosystem":"cargo","manifest":"core/Cargo.toml","publish":true}"#,
        )
        .replace(r#""kind":"application""#, r#""kind":"library""#)
        .replace("core-v", "custom-");
        let state = state(&[("core", core)]);
        #[cfg(unix)]
        let repository_alias = {
            let alias = root.path().with_extension("repository-alias");
            symlink(root.path(), &alias).unwrap();
            alias
        };
        #[cfg(not(unix))]
        let repository_alias = root.path().to_path_buf();
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(&repository_alias).unwrap(),
            "commit",
            &TagsOnly(&["custom-1.0.0"]),
        )
        .unwrap();
        assert_eq!(selected.len(), 1);
        assert_eq!(selected[0].tag_prefix, "custom-");
    }

    #[test]
    fn selection_preserves_an_explicit_empty_tag_prefix() {
        let root = tempfile::tempdir().unwrap();
        fs::write(
            root.path().join("Cargo.toml"),
            "[workspace]\nmembers = [\"core\"]\n",
        )
        .unwrap();
        fs::create_dir_all(root.path().join("core/src")).unwrap();
        fs::write(root.path().join("core/src/lib.rs"), "pub fn fixture() {}\n").unwrap();
        fs::write(
            root.path().join("core/Cargo.toml"),
            "[package]\nname = \"core\"\nversion = \"1.1.0\"\n",
        )
        .unwrap();
        fs::write(root.path().join("README.md"), "fixture\n").unwrap();
        track_all(root.path());

        let core = unit(
            "core",
            r#"{"ecosystem":"cargo","manifest":"core/Cargo.toml","publish":true}"#,
        )
        .replace(r#""kind":"application""#, r#""kind":"library""#)
        .replace("core-v", "");
        let state = state(&[("core", core)]);
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "commit",
            &TagsOnly(&["1.0.0"]),
        )
        .unwrap();
        assert_eq!(selected.len(), 1);
        assert_eq!(selected[0].tag_prefix, "");
    }

    #[test]
    fn existing_numeric_revision_tag_covers_its_base_version() {
        let root = tempfile::tempdir().unwrap();
        fs::create_dir_all(root.path().join("app")).unwrap();
        fs::write(root.path().join("app/VERSION"), "1.2.3\n").unwrap();
        track_all(root.path());
        let state = state(&[("app", unit("app", &version_file("app")))]);
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "commit",
            &TagsOnly(&["app-v1.2.3", "app-v1.2.3-2"]),
        )
        .unwrap();
        assert_eq!(selected, Vec::<Unit>::new());

        let reselected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "commit",
            &TagsOnly(&["app-v1.2.3-2"]),
        )
        .unwrap();
        assert_eq!(
            reselected,
            Vec::<Unit>::new(),
            "a revision tag of 1.2.3 already covers 1.2.3, so it is not reselected"
        );
    }

    #[test]
    fn revision_only_release_is_selected() {
        let root = tempfile::tempdir().unwrap();
        fs::create_dir_all(root.path().join("app")).unwrap();
        fs::write(root.path().join("app/VERSION"), "1.2.3\n").unwrap();
        fs::write(root.path().join("app/revision"), "1\n").unwrap();
        let app = unit("app", &version_file("app")).replace(
            r#""revision_file":null"#,
            r#""revision_file":"app/revision""#,
        );
        let state = state(&[("app", app)]);
        let select = || {
            publication_units(
                &state,
                &RepositoryRoot::new(root.path()).unwrap(),
                "commit",
                &TagsOnly(&["app-v1.2.3-1"]),
            )
            .unwrap()
        };
        assert_eq!(select(), Vec::<Unit>::new());

        fs::write(root.path().join("app/revision"), "2\n").unwrap();
        let selected = select();
        assert_eq!(selected.len(), 1);
        assert_eq!(selected[0].tag(), "app-v1.2.3-2");
    }

    fn two_app_state(root: &Path) -> ReleaseState {
        for name in ["app", "new"] {
            fs::create_dir_all(root.join(name)).unwrap();
            fs::write(root.join(name).join("VERSION"), "1.2.3\n").unwrap();
        }
        state(&[
            ("app", unit("app", &version_file("app"))),
            ("new", unit("new", &version_file("new"))),
        ])
    }

    #[test]
    fn an_untagged_unit_is_selected_as_a_first_release_beside_a_released_one() {
        let root = tempfile::tempdir().unwrap();
        let state = two_app_state(root.path());
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "merged",
            &TagsOnly(&["app-v1.2.3"]),
        )
        .unwrap();
        assert_eq!(
            selected.iter().map(Unit::tag).collect::<Vec<_>>(),
            ["new-v1.2.3"]
        );
    }

    #[test]
    fn tags_under_the_prefix_that_name_no_version_are_an_error() {
        let root = tempfile::tempdir().unwrap();
        let state = two_app_state(root.path());
        let result = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "merged",
            &TagsOnly(&["app-vlatest"]),
        );
        assert!(matches!(
            result,
            Err(PublicationError::UnparsableTag(UnparsableTag { unit, tag }))
                if unit == "app" && tag == "app-vlatest"
        ));
    }

    #[test]
    fn a_unit_tagged_at_the_commit_is_selected_again_to_resume_it() {
        let root = tempfile::tempdir().unwrap();
        let state = two_app_state(root.path());
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "released",
            &TagsOnly(&["app-v1.2.3", "new-v1.2.3"]),
        )
        .unwrap();
        assert_eq!(selected.len(), 2);
    }

    #[test]
    fn a_selected_unit_with_artifacts_needs_the_artifact_input() {
        let (repository, _stage, _manifest, release_state) = artifact_fixture();
        let root = RepositoryRoot::new(repository.path()).unwrap();
        let units = release_state.discover_units(&root).unwrap();
        assert!(matches!(
            release_state.stage_releases(&root, "merged", units, None, None),
            Err(PublicationError::MissingArtifacts(unit)) if unit == "web"
        ));
    }

    fn digest_pin_fixture(pinned: &str, artifact: &str) -> DigestFixture {
        let (repository, stage, _, mut release_state) = artifact_fixture();
        fs::create_dir_all(repository.path().join("action")).unwrap();
        fs::write(
            repository.path().join("action/action.yml"),
            format!("version: 1.0.0\ndigest: {pinned}\n"),
        )
        .unwrap();
        let action = unit(
            "action",
            r#"{"ecosystem":"document","path":"action/action.yml","key":["version"]}"#,
        )
        .replace(r#""dependencies":[]"#, r#""dependencies":["web"]"#)
        .replace(
            r#""pins":{}"#,
            &format!(
                r#""pins":{{"web":{{"path":"action/action.yml","key":["version"],"digests":{{"{artifact}":{{"path":"action/action.yml","key":["digest"],"algorithm":"sha256","package":"web-package","output":"web"}}}}}}}}"#
            ),
        );
        release_state.units.extend(
            state(&[("action", action)])
                .units
                .into_iter()
                .filter(|(name, _)| name == "action"),
        );
        let root = RepositoryRoot::new(repository.path()).unwrap();
        let staged = Stage::read(&stage.path().join("manifest.json"), stage.path()).unwrap();
        DigestFixture {
            _directories: (repository, stage),
            state: release_state,
            root,
            staged,
        }
    }

    #[test]
    fn a_digest_pin_that_matches_the_built_asset_is_staged() {
        let pinned = DigestAlgorithm::Sha256.hex(b"web asset");
        assert_eq!(digest_pin_fixture(&pinned, "web").stage().unwrap(), 2);
    }

    #[test]
    fn a_digest_pin_that_differs_from_the_built_asset_fails_before_any_upload() {
        let built = DigestAlgorithm::Sha256.hex(b"web asset");
        assert!(matches!(
            digest_pin_fixture("stale", "web").stage(),
            Err(PublicationError::DigestMismatch { unit, dependency, artifact, pinned, built: actual })
                if unit == "action"
                    && dependency == "web"
                    && artifact == "web"
                    && pinned == "stale"
                    && actual == built
        ));
    }

    #[test]
    fn a_digest_pin_is_not_checked_without_the_asset_in_the_manifest() {
        assert_eq!(digest_pin_fixture("stale", "absent").stage().unwrap(), 2);
    }

    #[test]
    fn a_digest_pin_of_an_unselected_dependency_is_not_checked() {
        assert_eq!(
            digest_pin_fixture("", "web").stage_without("web").unwrap(),
            1
        );
    }

    #[test]
    fn an_untagged_unit_at_0_0_0_is_not_selected() {
        let root = tempfile::tempdir().unwrap();
        let state = two_app_state(root.path());
        fs::write(root.path().join("new/VERSION"), "0.0.0\n").unwrap();
        let selected = publication_units(
            &state,
            &RepositoryRoot::new(root.path()).unwrap(),
            "merged",
            &TagsOnly(&["app-v1.2.3"]),
        )
        .unwrap();
        assert_eq!(selected, Vec::<Unit>::new());
    }
}