chore: add some docs

Signed-off-by: James Petersen <jpetersenames@gmail.com>

Author: found-it

src/lib.rs

@@ -1,6 +1,12 @@
 use log::{error, info, warn};
 use std::fmt;
 
+/// CheckResultValue is the final value for the result of an individual check.
+///
+/// Failed means a check ran successfully but did not pass. Errored means a check hit an
+/// error while executing.
+///
+/// Failed and Errored should contain a descriptive string explaining the result.
 pub enum CheckResultValue {
     Passed,
     Failed(String),
@@ -19,8 +25,13 @@ impl fmt::Display for CheckResultValue {
     }
 }
 
+/// CheckResult is the end result of an individual check. It carries the name of the individual
+/// check as well as the end result.
 pub struct CheckResult {
+    /// name is the name of the individual check
     pub name: String,
+
+    /// result is the final result of an individual check
     pub result: CheckResultValue,
 }
 
@@ -33,9 +44,17 @@ impl CheckResult {
     }
 }
 
+/// CheckGroupResult is the result for a top-level group of checks. The result field is calculated
+/// from the set of individual checks within that group.
 pub struct CheckGroupResult {
+    /// name is the name of the group of checks
     pub name: String,
+
+    /// result is the top-level result of the group of checks. It is calculated from the results of
+    /// each individual check.
     pub result: CheckResultValue,
+
+    /// results is the list of results from each individual check within this group.
     pub results: Vec<CheckResult>,
 }
 
@@ -47,6 +66,9 @@ impl CheckGroupResult {
             results: Vec::new(),
         }
     }
+
+    /// log_group is a pretty-print helper to log the result of the group based on what the result
+    /// value is.
     pub fn log_group(&self) {
         let name = &self.name;
         let result = &self.result;
@@ -59,6 +81,8 @@ impl CheckGroupResult {
         }
     }
 
+    /// log_individual_checks is a pretty-print helper to log the results of each individual check
+    /// within a group.
     pub fn log_individual_checks(&self) {
         let group_name = &self.name;
         for check_result in self.results.iter() {
@@ -75,12 +99,22 @@ impl CheckGroupResult {
     }
 }
 
+/// CheckGroup is a trait representing a group of checks.
 pub trait CheckGroup {
+    /// name is the name of the check group
     fn name(&self) -> &str;
+
+    /// id is the identifier for the check group. This field is used when skipping or selecting
+    /// certain check groups to run so it should be env/cli friendly.
     fn id(&self) -> &str;
+
+    /// description is a longer form text field explaining what this check group is intended for.
     fn description(&self) -> &str;
+
+    /// run is the main entry point that runs the checks within the check group.
     fn run(&self) -> CheckGroupResult;
 }
 
+// modules
 pub mod script;
 pub mod system;

src/main.rs

@@ -31,8 +31,11 @@ fn main() -> Result<()> {
         }
 
         info!("Running Group [{}] - {}", group.name(), group.description());
+
         let check_group_result = group.run();
+
         check_group_result.log_group();
+
         if env::var("EDERA_PREFLIGHT_VERBOSE").unwrap_or_default() == "true" {
             check_group_result.log_individual_checks();
         }
@@ -48,7 +51,7 @@ fn main() -> Result<()> {
     }
 
     match final_result {
-        Errored(_) | Failed(_) => bail!("checks failed"),
+        Errored(_) | Failed(_) => bail!("Preflight checks did not pass"),
         _ => Ok(()),
     }
 }

src/script/mod.rs

@@ -13,9 +13,13 @@ use std::process::Command;
 const GROUP_IDENTIFIER: &str = "ScriptedChecks";
 const NAME: &str = "Scripted Checks";
 
+/// ScriptChecks is a special type of check that is intended to run a series of
+/// small shell scripts. The intent here is to make a pluggable interface for to
+/// quickly implement checks. Ideally all checks end up in their own CheckGroup.
 pub struct ScriptChecks;
 
 impl ScriptChecks {
+    /// run_all runs all shell scripts within the directory $EDERA_PREFLIGHT_SCRIPTS_DIR
     pub fn run_all(&self) -> CheckGroupResult {
         let mut results = Vec::new();
 
@@ -53,11 +57,16 @@ impl ScriptChecks {
         }
     }
 
+    /// scripts_dir sets the directory to search for scripts
     fn scripts_dir(&self) -> PathBuf {
         let sdir = env::var("EDERA_PREFLIGHT_SCRIPTS_DIR").unwrap_or("./scripts".to_string());
         PathBuf::from(sdir)
     }
 
+    /// script_list attempts to collect a list of shell scripts to execute. It
+    /// will return an empty list if the path does not exist or is not a
+    /// directory. If the path is a directory it will scrape all files (without
+    /// recursing into subdirectories) and return them as a list.
     fn script_list(&self) -> Result<Vec<PathBuf>> {
         let scripts_dir = self.scripts_dir();
 
@@ -77,7 +86,7 @@ impl ScriptChecks {
             let entry = entry?;
             if !entry.file_type()?.is_file() {
                 warn!(
-                    "skipping load of {}",
+                    "skipping load of {}: not a file",
                     entry.file_name().to_str().unwrap_or("unknown")
                 );
                 continue;
@@ -86,11 +95,18 @@ impl ScriptChecks {
             scripts.push(entry.path());
         }
 
-        scripts.push(PathBuf::from("/totally/fake/script"));
-
         Ok(scripts)
     }
 
+    /// run_script will run an individual script and return the result. It will
+    /// attempt to scrape some details from the script output (like a name for
+    /// the check).
+    ///
+    /// If there is an error running the script (eg: script is not executable) then
+    /// the check will return an error result.
+    ///
+    /// If the script runs successfully but exits with a non-zero exit code, then
+    /// the check will reutrn a fail result.
     fn run_script(&self, path: &PathBuf) -> CheckResult {
         let output = Command::new(path).output();
 

src/system/mod.rs

@@ -14,7 +14,7 @@ pub struct SystemChecks;
 
 impl SystemChecks {
     pub fn run_all(&self) -> CheckGroupResult {
-        let results = vec![self.enough_memory(), self.erroring(), self.failing()];
+        let results = vec![self.enough_memory()];
 
         let mut group_result = Passed;
         for res in results.iter() {
@@ -50,16 +50,6 @@ impl SystemChecks {
         }
         CheckResult::new(&name, result)
     }
-
-    fn failing(&self) -> CheckResult {
-        let name = String::from("Should Fail");
-        CheckResult::new(&name, Failed(String::from("Pretending to fail")))
-    }
-
-    fn erroring(&self) -> CheckResult {
-        let name = String::from("Should Error");
-        CheckResult::new(&name, Errored(String::from("Pretending to error")))
-    }
 }
 
 impl CheckGroup for SystemChecks {