From 2e9c4f51008456e34dda7d3be3465702a433180e Mon Sep 17 00:00:00 2001 From: Aria Beingessner Date: Sat, 25 Mar 2023 22:50:58 -0400 Subject: [PATCH] feat(manifests): add a from_manifest method to BuildManifest and do some drive-by docs work (#213) --- crates/nassun/src/package.rs | 6 +++--- crates/oro-common/src/build_manifest.rs | 20 +++++++++++++++++--- crates/oro-common/src/manifest.rs | 21 +++++++++++++++++++++ crates/oro-shim-bin/src/lib.rs | 2 +- 4 files changed, 42 insertions(+), 7 deletions(-) diff --git a/crates/nassun/src/package.rs b/crates/nassun/src/package.rs index 7bbf423b..de49ea2c 100644 --- a/crates/nassun/src/package.rs +++ b/crates/nassun/src/package.rs @@ -70,7 +70,7 @@ 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 { @@ -78,7 +78,7 @@ impl Package { 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. diff --git a/crates/oro-common/src/build_manifest.rs b/crates/oro-common/src/build_manifest.rs index 37a72623..c7f1db8b 100644 --- a/crates/oro-common/src/build_manifest.rs +++ b/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,8 +41,8 @@ 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) -> std::io::Result { let path = path.as_ref(); let pkg_str = std::fs::read_to_string(path)?; @@ -50,6 +50,20 @@ impl BuildManifest { 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 { + // 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 { let mut bin_map = HashMap::new(); if let Some(Bin::Hash(bins)) = raw.bin { diff --git a/crates/oro-common/src/manifest.rs b/crates/oro-common/src/manifest.rs index cd1fb374..e93c81a3 100644 --- a/crates/oro-common/src/manifest.rs +++ b/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, + /// 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, @@ -60,6 +68,10 @@ pub struct Manifest { #[builder(default)] pub keywords: Vec, + /// 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, @@ -100,10 +112,19 @@ pub struct Manifest { #[serde(skip_serializing_if = "Option::is_none")] pub imports: Option, + /// 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, + /// 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, diff --git a/crates/oro-shim-bin/src/lib.rs b/crates/oro-shim-bin/src/lib.rs index 02a0fcf3..60529c6a 100644 --- a/crates/oro-shim-bin/src/lib.rs +++ b/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. +//! . // The original project is licensed as follows: //