feat(manifests): add a from_manifest method to BuildManifest and do s…

…ome drive-by docs work (#213)

crates/nassun/src/package.rs

@@ -70,15 +70,15 @@ impl Package {
         self.fetcher.corgi_metadata(self).await
     }
 
-    /// [`AsyncRead`] of the raw tarball data for this package. The data will
+    /// `AsyncRead` of the raw tarball data for this package. The data will
     /// not be checked for integrity based on the current `Package`'s
     /// [`Integrity`]. That is, bad or incomplete data may be returned.
     pub async fn tarball_unchecked(&self) -> Result<Tarball> {
         let data = self.fetcher.tarball(self).await?;
         Ok(Tarball::new_unchecked(data))
     }
 
-    /// [`AsyncRead`] of the raw tarball data for this package. The data will
+    /// `AsyncRead` of the raw tarball data for this package. The data will
     /// be checked for integrity based on the current `Package`'s
     /// [`Integrity`], if present in its [`Package::metadata`]. An
     /// [`std::io::Error`] with [`std::io::ErrorKind::InvalidData`] will be
@@ -92,7 +92,7 @@ impl Package {
         }
     }
 
-    /// [`AsyncRead`] of the raw tarball data for this package. The data will
+    /// `AsyncRead` of the raw tarball data for this package. The data will
     /// be checked for integrity based on the given [`Integrity`].  An
     /// [`std::io::Error`] with [`std::io::ErrorKind::InvalidData`] will be
     /// returned in case of integrity validation failure.

crates/oro-common/src/build_manifest.rs

@@ -7,7 +7,7 @@ use std::{
 use serde::{Deserialize, Serialize};
 use walkdir::WalkDir;
 
-use crate::{Bin, Directories};
+use crate::{Bin, Directories, Manifest};
 
 #[derive(Clone, Default, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -41,15 +41,29 @@ pub struct BuildManifest {
 }
 
 impl BuildManifest {
-    /// Create a new [`BuildManifest`] from a given path, normalizing its bin
-    /// field (or its `directories.bin`) into a plain HashMap.
+    /// Create a new [`BuildManifest`] from a given path to a full manifest (package.json),
+    /// normalizing its bin field (or its `directories.bin`) into a plain HashMap.
     pub fn from_path(path: impl AsRef<Path>) -> std::io::Result<Self> {
         let path = path.as_ref();
         let pkg_str = std::fs::read_to_string(path)?;
         let raw: RawBuildManifest = serde_json::from_str(&pkg_str)?;
         Self::normalize(raw)
     }
 
+    /// Create a new [`BuildManifest`] from an already fully loaded [`Manifest`],
+    /// normalizing its bin field (or its `directories.bin`) into a plain HashMap.
+    pub fn from_manifest(manifest: &Manifest) -> std::io::Result<Self> {
+        // This is a bit ineffecient but honestly it's not a big deal,
+        // we already did a bunch of I/O to get the Manifest.
+        let raw = RawBuildManifest {
+            name: manifest.name.clone(),
+            bin: manifest.bin.clone(),
+            directories: manifest.directories.clone(),
+            scripts: manifest.scripts.clone(),
+        };
+        Self::normalize(raw)
+    }
+
     fn normalize(raw: RawBuildManifest) -> std::io::Result<Self> {
         let mut bin_map = HashMap::new();
         if let Some(Bin::Hash(bins)) = raw.bin {

crates/oro-common/src/manifest.rs

@@ -32,10 +32,18 @@ pub struct CorgiManifest {
 #[derive(Builder, Default, Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Manifest {
+    /// The name of the package.
+    ///
+    /// If this is missing, it usually indicates that this package exists only to
+    /// describe a workspace, similar to Cargo's notion of a "virtual manifest".
     #[builder(setter(into, strip_option), default)]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub name: Option<String>,
 
+    /// The version of the package.
+    ///
+    /// Package managers generally require this to be populated to actually publish
+    /// the package, but will tolerate its absence during local development.
     #[builder(setter(strip_option), default)]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub version: Option<Version>,
@@ -60,6 +68,10 @@ pub struct Manifest {
     #[builder(default)]
     pub keywords: Vec<String>,
 
+    /// Information about the names and locations of binaries this package provides.
+    ///
+    /// Use [`crate::BuildManifest::from_manifest`][] to get a normalized version
+    /// of this field (and other related fields).
     #[builder(setter(strip_option), default)]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub bin: Option<Bin>,
@@ -100,10 +112,19 @@ pub struct Manifest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub imports: Option<Imports>,
 
+    /// Information about the repository this project is hosted in.
+    ///
+    /// [`Repository::Str`][] can contain many different formats (or plain garbage),
+    /// we recommend trying to `.parse()` it as oro-package-spec's GitInfo type,
+    /// as it understands most of the relevant formats.
     #[builder(setter(strip_option), default)]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub repository: Option<Repository>,
 
+    /// Information about build scripts the package uses.
+    ///
+    /// Use [`crate::BuildManifest::from_manifest`][] to get a normalized version
+    /// of this field (and other related fields).
     #[serde(default, skip_serializing_if = "HashMap::is_empty")]
     #[builder(default)]
     pub scripts: HashMap<String, String>,

crates/oro-shim-bin/src/lib.rs

@@ -1,5 +1,5 @@
 //! Creates shims for package bins on Windows. Basically a Rust port of
-//! https://github.com/npm/cmd-shim.
+//! <https://github.com/npm/cmd-shim>.
 
 // The original project is licensed as follows:
 //