bake-readme 0.1.6

Reusable readme.md maintenance tasks for Bake
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

// Released under the MIT License.
// Copyright, 2026, by Samuel Williams.

//! Reusable `readme.md` maintenance tasks for Bake.
//!
//! The task adds a short summary of recent entries from `releases.md` when a
//! project `readme.md` does not already contain an authored Releases section. When
//! the project root has a Cargo package manifest, it also adds or refreshes a
//! generated package entry in the `readme.md` See Also section when the source
//! repository link is not already present elsewhere in the readme.
mod document;
mod metadata;

pub use document::{
    PackageMetadata, Release, ensure_releases_section, recent_releases, update_document,
    update_document_with_releases, update_releases_section,
};

/// Tasks exported by this package register beneath the `readme` namespace.
pub mod readme {
    use bake::{Context, Error, Result};
    use std::fs;
    use std::io::Write;
    use std::path::PathBuf;

    use super::{metadata::read_project_package, recent_releases, update_document_with_releases};

    trait TemporaryFile: Write {
        fn set_permissions(&self, permissions: fs::Permissions) -> std::io::Result<()>;
        fn sync_all(&self) -> std::io::Result<()>;
    }

    impl TemporaryFile for fs::File {
        fn set_permissions(&self, permissions: fs::Permissions) -> std::io::Result<()> {
            fs::File::set_permissions(self, permissions)
        }

        fn sync_all(&self) -> std::io::Result<()> {
            fs::File::sync_all(self)
        }
    }

    fn prepare_temporary_file(
        file: &mut impl TemporaryFile,
        path: &std::path::Path,
        document: &str,
    ) -> Result<()> {
        file.write_all(document.as_bytes())?;
        file.set_permissions(fs::metadata(path)?.permissions())?;
        file.sync_all()?;
        Ok(())
    }

    fn write_document_atomically(path: &std::path::Path, document: &str) -> Result<()> {
        let directory = path
            .parent()
            .expect("a canonical readme file path should have a parent directory");
        let mut temporary = tempfile::NamedTempFile::new_in(directory)?;
        prepare_temporary_file(temporary.as_file_mut(), path, document)?;
        temporary
            .persist(path)
            .map_err(|error| Error::from(error.error))?;
        Ok(())
    }

    /// Add recent release notes and Cargo package links to `readme.md` when needed.
    #[bake::task]
    pub fn update(
        context: &mut Context,
        #[bake(
            default = "readme.md",
            help = "readme file relative to the project root."
        )]
        path: PathBuf,
    ) -> Result<()> {
        let path = context.root().join(path).canonicalize()?;
        let document = fs::read_to_string(&path)
            .map_err(|error| Error::new(format!("{}: {error}", path.display())))?;
        let package = read_project_package(context)?;
        let release_path = context.root().join("releases.md");
        let releases = if release_path.is_file() {
            let release_document = fs::read_to_string(&release_path)
                .map_err(|error| Error::new(format!("{}: {error}", release_path.display())))?;
            recent_releases(&release_document)
        } else {
            Vec::new()
        };
        let updated = update_document_with_releases(&document, package.as_ref(), &releases);

        if updated == document {
            return Ok(());
        }

        write_document_atomically(&path, &updated)
    }

    #[cfg(test)]
    #[path = "readme_tests.rs"]
    mod tests;
}