kcode_rust_libs_v2/
lib.rs

1//! Six-operation managed Rust-library boundary.
2
3mod model;
4mod repository;
5mod sandbox;
6
7use std::fmt;
8use std::path::{Path, PathBuf};
9
10pub use model::{Error, File, Result};
11use model::{ValidSource, validate_name, validate_source};
12
13/// One complete editable managed-library source snapshot.
14///
15/// Edit `files` directly and call [`Lib::write`] to commit the complete
16/// replacement. Private fields bind the source to its repository generation
17/// and publication credential.
18pub struct Lib {
19    /// Every useful UTF-8 source file, canonically sorted by path after open or write.
20    pub files: Vec<File>,
21    repository: PathBuf,
22    name: String,
23    identity: String,
24    token: Secret,
25}
26
27/// Creates a minimal Rust 2024 library and returns its complete source.
28pub fn create(
29    rust_libs_root: impl AsRef<Path>,
30    name: &str,
31    crates_io_registry_token: impl AsRef<str>,
32) -> Result<Lib> {
33    let token = Secret::new(crates_io_registry_token.as_ref())?;
34    validate_name(name)?;
35    let source = initial_source(name)?;
36    let snapshot = repository::create(rust_libs_root.as_ref(), name, &source)?;
37    Ok(Lib {
38        files: snapshot.files,
39        repository: snapshot.repository,
40        name: name.to_owned(),
41        identity: snapshot.identity,
42        token,
43    })
44}
45
46/// Opens an existing library, migrating a valid legacy flat repository when needed.
47pub fn open(
48    rust_libs_root: impl AsRef<Path>,
49    name: &str,
50    crates_io_registry_token: impl AsRef<str>,
51) -> Result<Lib> {
52    let token = Secret::new(crates_io_registry_token.as_ref())?;
53    validate_name(name)?;
54    let snapshot = repository::open(rust_libs_root.as_ref(), name)?;
55    Ok(Lib {
56        files: snapshot.files,
57        repository: snapshot.repository,
58        name: name.to_owned(),
59        identity: snapshot.identity,
60        token,
61    })
62}
63
64/// Returns the package version and root `Documentation.md`, migrating when needed.
65pub fn docs(rust_libs_root: impl AsRef<Path>, name: &str) -> Result<(String, String)> {
66    validate_name(name)?;
67    repository::docs(rust_libs_root.as_ref(), name)
68}
69
70impl Lib {
71    /// Atomically commits `files` as the complete source if this snapshot is current.
72    pub fn write(&mut self) -> Result<()> {
73        let source = validate_source(&self.files, &self.name)?;
74        let snapshot = repository::replace(&self.repository, &self.identity, &source)?;
75        self.files = snapshot.files;
76        self.identity = snapshot.identity;
77        Ok(())
78    }
79
80    /// Validates exactly the current in-memory complete source.
81    pub fn check(&self) -> Result<()> {
82        let source = validate_source(&self.files, &self.name)?;
83        sandbox::check(&source)
84    }
85
86    /// Rechecks and publishes exactly the current in-memory complete source.
87    pub fn publish(&self) -> Result<()> {
88        let source = validate_source(&self.files, &self.name)?;
89        sandbox::publish(&source, self.token.expose())
90    }
91}
92
93impl fmt::Debug for Lib {
94    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
95        formatter
96            .debug_struct("Lib")
97            .field("files", &self.files)
98            .field("repository", &self.repository)
99            .field("name", &self.name)
100            .field("identity", &"[PRIVATE]")
101            .field("token", &"[REDACTED]")
102            .finish()
103    }
104}
105
106struct Secret(String);
107
108impl Secret {
109    fn new(value: &str) -> Result<Self> {
110        let value = value.trim();
111        if value.is_empty() {
112            return Err(Error::new(
113                "invalid_token",
114                "the crates.io registry token is empty",
115            ));
116        }
117        Ok(Self(value.to_owned()))
118    }
119
120    fn expose(&self) -> &str {
121        &self.0
122    }
123}
124
125fn initial_source(name: &str) -> Result<ValidSource> {
126    validate_source(
127        &[
128            File {
129                path: "Cargo.toml".to_owned(),
130                contents: format!(
131                    "[package]\nname = \"{name}\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[dependencies]\n"
132                ),
133            },
134            File {
135                path: "Documentation.md".to_owned(),
136                contents: String::new(),
137            },
138            File {
139                path: "src/lib.rs".to_owned(),
140                contents: String::new(),
141            },
142        ],
143        name,
144    )
145}
kcode_rust_libs_v2/lib.rs

kcode_rust_libs_v2/
lib.rs
