fix: fix tests, add api docs

src/config/builder/mod.rs

@@ -1,8 +1,7 @@
 //! The [`Builder`] struct serves as an intermediate step between raw configuration and the
 //! [`Config`] type that is used by `hoard`.
-use std::collections::{BTreeMap, HashMap};
+use std::collections::BTreeMap;
 use std::convert::TryInto;
-use std::env;
 use std::path::{Path, PathBuf};
 
 use clap::Parser;
@@ -14,11 +13,10 @@ use tokio::{fs, io};
 use environment::Environment;
 
 use crate::command::Command;
-use crate::config::builder::var_defaults::EnvVarDefaults;
+use crate::config::builder::var_defaults::{EnvVarDefaults, EnvVarDefaultsError};
 use crate::hoard::PileConfig;
 use crate::newtypes::{EnvironmentName, HoardName};
 use crate::CONFIG_FILE_STEM;
-use crate::env_vars::StringWithEnv;
 
 use super::Config;
 
@@ -27,7 +25,7 @@ use self::hoard::Hoard;
 pub mod environment;
 pub mod envtrie;
 pub mod hoard;
-mod var_defaults;
+pub mod var_defaults;
 
 const DEFAULT_CONFIG_EXT: &str = "toml";
 /// The items are listed in descending order of precedence
@@ -56,9 +54,12 @@ pub enum Error {
         "configuration file does not have file extension \".toml\", \".yaml\", or \".yml\": {0}"
     )]
     InvalidExtension(PathBuf),
+    /// Failed to set one or more environment variable default.
+    #[error(transparent)]
+    EnvVarDefaults(#[from] EnvVarDefaultsError),
 }
 
-/// Intermediate data structure to build a [`Config`](crate::config::Config).
+/// Intermediate data structure to build a [`Config`].
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize, Parser)]
 #[clap(author, version, about, long_about = None, rename_all = "kebab")]
 #[serde(rename_all = "snake_case")]
@@ -68,6 +69,7 @@ pub struct Builder {
     #[serde(rename = "envs")]
     environments: Option<BTreeMap<EnvironmentName, Environment>>,
     #[clap(skip)]
+    #[serde(default)]
     var_defaults: EnvVarDefaults,
     #[clap(skip)]
     exclusivity: Option<Vec<Vec<EnvironmentName>>>,
@@ -441,6 +443,9 @@ mod tests {
     mod builder {
         use super::*;
 
+        const DEFAULT_VAR: &str = "UNSET";
+        const DEFAULT_VAR_VALUE: &str = "no longer unset";
+
         fn get_default_populated_builder() -> Builder {
             Builder {
                 config_file: Some(Builder::default_config_file()),
@@ -452,6 +457,7 @@ mod tests {
                 hoards: None,
                 force: false,
                 global_config: None,
+                var_defaults: EnvVarDefaults::default(),
             }
         }
 
@@ -468,6 +474,11 @@ mod tests {
                 hoards: None,
                 force: false,
                 global_config: None,
+                var_defaults: {
+                    let mut defaults = EnvVarDefaults::default();
+                    defaults.insert(DEFAULT_VAR.into(), DEFAULT_VAR_VALUE.into());
+                    defaults
+                }
             }
         }
 
@@ -488,6 +499,7 @@ mod tests {
                 exclusivity: None,
                 force: false,
                 global_config: None,
+                var_defaults: EnvVarDefaults::default(),
             };
 
             assert_eq!(
@@ -518,16 +530,28 @@ mod tests {
 
         #[test]
         fn layered_builder_prefers_argument_to_self() {
-            let layer1 = get_default_populated_builder();
-            let layer2 = get_non_default_populated_builder();
+            let mut layer1 = get_default_populated_builder();
+            let mut layer2 = get_non_default_populated_builder();
+
+            // Add extra env values to ensure they merge properly
+            layer1.var_defaults.insert("ENV1".into(), "1".into());
+            layer1.var_defaults.insert(DEFAULT_VAR.into(), "non default".into());
+            layer2.var_defaults.insert("ENV2".into(), "2".into());
+
+            let mut expected = layer2.clone();
+            expected.var_defaults.insert("ENV1".into(), "1".into());
 
             assert_eq!(
-                layer2,
+                expected,
                 layer1.clone().layer(layer2.clone()),
                 "layer() should prefer the argument"
             );
+
+            let mut expected = layer1.clone();
+            expected.var_defaults.insert("ENV2".into(), "2".into());
+
             assert_eq!(
-                layer1,
+                expected,
                 layer2.layer(layer1.clone()),
                 "layer() should prefer the argument"
             );
@@ -577,5 +601,13 @@ mod tests {
             assert_eq!(Some(config.config_file), builder.config_file);
             assert_eq!(Some(config.command), builder.command);
         }
+
+        #[test]
+        #[serial_test::serial]
+        fn builder_sets_env_vars_correctly() {
+            let builder = get_non_default_populated_builder();
+            builder.build().unwrap();
+            assert_eq!(std::env::var(DEFAULT_VAR).unwrap(), DEFAULT_VAR_VALUE);
+        }
     }
 }

src/config/builder/var_defaults.rs

@@ -1,14 +1,44 @@
+//! See [`EnvVarDefaults`].
+
 use std::collections::BTreeMap;
-use std::env;
+use std::{env, fmt};
+use std::fmt::Formatter;
 use serde::{Deserialize, Serialize};
 use crate::env_vars::StringWithEnv;
 
+/// Failed to apply one or more environment variables in [`EnvVarDefaults::apply`].
+///
+/// Most common reasons for this occurring is trying to use an unset variable in a default value,
+/// or having two unset variables' values dependent on each other.
+#[derive(Debug, thiserror::Error)]
+pub struct EnvVarDefaultsError(BTreeMap<String, String>);
+
+impl fmt::Display for EnvVarDefaultsError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        assert!(!self.0.is_empty());
+        write!(f, "Could not apply environment variable defaults. One or more default values requires an unset variable.")?;
+        for (var, value) in &self.0 {
+            write!(f, "\n{var}: {value:?}")?;
+        }
+        Ok(())
+    }
+}
+
+/// Define variables and their default values, should that variable not otherwise be defined.
+///
+/// Variable default values can interpolate the values of other environment variables.
+/// See [`StringWithEnv`] for the required syntax.
 #[derive(Clone, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(transparent)]
 #[repr(transparent)]
 pub struct EnvVarDefaults(BTreeMap<String, String>);
 
 impl EnvVarDefaults {
+    #[cfg(test)]
+    pub(super) fn insert(&mut self, var: String, value: String) -> Option<String> {
+        self.0.insert(var, value)
+    }
+
     pub(super) fn merge_with(&mut self, other: Self) {
         for (var, value) in other.0 {
             self.0.insert(var, value);
@@ -19,14 +49,17 @@ impl EnvVarDefaults {
     /// values first.
     ///
     /// This will repeatedly attempt to apply variables as long as at least one successfully applies.
-    pub(super) fn apply(self) -> Result<(), ()> {
+    ///
+    /// # Errors
+    ///
+    /// See [`EnvVarDefaultsError`].
+    pub(super) fn apply(self) -> Result<(), EnvVarDefaultsError> {
         // Add one just so the `while` condition is true once.
         let mut remaining_last_loop = self.0.len() + 1;
-        let mut last_loop = BTreeMap::new();
         let mut this_loop = self.0;
 
         while remaining_last_loop != this_loop.len() {
-            last_loop = std::mem::take(&mut this_loop);
+            let last_loop = std::mem::take(&mut this_loop);
             remaining_last_loop = last_loop.len();
             for (var, value) in last_loop {
                 if env::var_os(&var).is_none() {
@@ -45,7 +78,7 @@ impl EnvVarDefaults {
         if this_loop.is_empty() {
             Ok(())
         } else {
-            Err(())
+            Err(EnvVarDefaultsError(this_loop))
         }
     }
 }