libscilo/config/

instantiated_config.rs

//! Creating and using the internal representation of all the important files, directories, and lints to check.

use regex::Regex;
use std::path::Path;
use std::str::FromStr;
use std::{path::PathBuf, sync::LazyLock};
use strum::IntoEnumIterator;

use super::file::ConfigFileRootDirs;
use super::{error::ConfigError, file::ConfigFile};
use crate::config::parse::parse_config_file;
use crate::lints::LintCheck;
use crate::lints::LintError;
use crate::version_control::project_root;

/// The default regular expression for [`code`][RootDirs::code]
/// and [`results`][RootDirs::results] folders to match against.
/// The format is `YYYY-MM-DD_kebab-case-brief-description`.
static CODE_RESULTS_SUBDIR_REGEX: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"2\d{3}-(0[1-9]|1[0-2])-([0-2][0-9]|3[0-1])_[A-Za-z-]+").unwrap());

/// The default accepted file names of the READMEs that should be present in the
/// project root and within each subdirectory in the [`code`][RootDirs::code]
/// and [`data`][RootDirs::data] directories.
static README_FILE_NAMES: LazyLock<Vec<String>> = LazyLock::new(|| {
    vec![
        String::from("README.md"),
        String::from("README.org"),
        String::from("README.txt"),
        String::from("README"),
    ]
});

/// The default accepted file names of the workflow files that should be present
/// within each subdirectory in the [`code`][RootDirs::code] directory.
static WORKFLOW_FILE_NAMES: LazyLock<Vec<String>> = LazyLock::new(|| {
    vec![
        // Snakemake
        String::from("Snakefile"),
        // Targets
        String::from("_targets.R"),
        // Cromwell, Common Workflow Language
        String::from("main.cwl"),
        // Nextflow
        String::from("main.nf"),
        // BioPipe
        String::from("main.pipe"),
        // Guix Workflow Language
        String::from("main.w"),
        // Workflow Description Language
        String::from("main.wdl"),
        // Make
        String::from("Makefile"),
    ]
});

/// The internal representation of all the important files, directories, and lints to check.
///
/// This data structure isn't created directly from a configuration file.
/// It is instead instantiated from the [`ConfigFile`] struct, using some intermediate
/// logic that can fail along the way.
#[derive(Clone, Debug)]
pub struct InstantiatedConfig {
    /// Expected top-level directories to organize the project folder.
    pub root_dirs: RootDirs,

    /// Regular expression for units of analysis within the code and their matching results.
    ///
    /// The default value for this regular expression is [`CODE_RESULTS_SUBDIR_REGEX`].
    pub code_results_subdir_regex: Option<Regex>,

    /// The explicit list of lint checks that should be performed.
    /// See [`LintCheck`] for the complete list.
    pub lints: Vec<LintCheck>,

    /// The explicit list of files that should be present at the root of the
    /// project directory.
    pub root_files: Vec<PathBuf>,

    /// The file name for the READMEs that should be present within each
    /// subdirectory in the [`code`][RootDirs::code] and [`data`][RootDirs::data]
    /// directories.
    pub readme_names: Option<Vec<String>>,

    /// The file name for the workflow file that should be present within each
    /// subdirectory in the [`code`][RootDirs::code] directory.
    pub workflow_names: Option<Vec<String>>,
}

impl Default for InstantiatedConfig {
    fn default() -> Self {
        Self {
            root_dirs: RootDirs::default(),
            code_results_subdir_regex: Some((*CODE_RESULTS_SUBDIR_REGEX).clone()),
            // by default, use all lints
            lints: LintCheck::iter().collect(),
            root_files: Vec::new(),
            readme_names: Some((*README_FILE_NAMES).clone()),
            workflow_names: Some((*WORKFLOW_FILE_NAMES).clone()),
        }
    }
}

impl TryFrom<&ConfigFile> for InstantiatedConfig {
    type Error = ConfigError;

    fn try_from(value: &ConfigFile) -> Result<Self, Self::Error> {
        // use the defaults if a non-required option is specified in the ConfigFile
        let defaults = Self::default();

        let root_dirs = RootDirs::from(value.root_dirs.clone());

        // this complicated iteration and mapping will automatically return a `ConfigError`
        // if there is a typo or other misspecification in the configuration file.
        let lints = match &value.lints {
            Some(lint_list) => {
                // map the string to the enum variant using the `strum` crate
                // and map a `strum::ParseError` into a `ConfigError` if there is an
                // error in the string conversion.
                lint_list
                    .iter()
                    .map(|lint_code| {
                        LintCheck::from_str(lint_code)
                            .map_err(|_| ConfigError::UnknownLintCode(lint_code.clone()))
                    })
                    .collect::<Result<Vec<_>, ConfigError>>()?
            }
            None => defaults.lints,
        };

        let root_files = match &value.root_files {
            Some(files) => files.iter().map(PathBuf::from).collect(),
            None => defaults.root_files,
        };

        // this regex parsing might fail, which means that we need to use a
        // `TryFrom` instead of a `From`
        let code_results_subdir_regex = match &value.code_results_subdir_regex {
            Some(str) => match Regex::new(str) {
                Ok(re) => Some(re),
                Err(_) => {
                    return Err(ConfigError::RegexError {
                        name: "code_results_subdir_regex".to_string(),
                        value: str.clone(),
                    });
                }
            },
            None => defaults.code_results_subdir_regex,
        };

        let readme_names = match &value.readme_names {
            Some(val) => Some(val.clone()),
            None => defaults.readme_names.clone(),
        };

        let workflow_names = match &value.workflow_names {
            Some(val) => Some(val.clone()),
            None => defaults.workflow_names.clone(),
        };

        Ok(Self {
            root_dirs,
            code_results_subdir_regex,
            lints,
            root_files,
            readme_names,
            workflow_names,
        })
    }
}

impl TryFrom<ConfigFile> for InstantiatedConfig {
    type Error = ConfigError;

    fn try_from(value: ConfigFile) -> Result<Self, Self::Error> {
        Self::try_from(&value)
    }
}

impl TryFrom<&Path> for InstantiatedConfig {
    type Error = ConfigError;

    fn try_from(value: &Path) -> Result<Self, Self::Error> {
        let cfg_file = parse_config_file(value)?;
        InstantiatedConfig::try_from(cfg_file)
    }
}

impl TryFrom<&PathBuf> for InstantiatedConfig {
    type Error = ConfigError;

    fn try_from(value: &PathBuf) -> Result<Self, Self::Error> {
        let cfg_file = parse_config_file(value.as_path())?;
        InstantiatedConfig::try_from(cfg_file)
    }
}

impl TryFrom<PathBuf> for InstantiatedConfig {
    type Error = ConfigError;

    fn try_from(value: PathBuf) -> Result<Self, Self::Error> {
        Self::try_from(&value)
    }
}

impl InstantiatedConfig {
    /// The main method to run all the requested lints on the project directory.
    pub fn execute_lints(self) -> Result<(), LintError> {
        for lint in self.lints.iter() {
            lint.check(&self)?;
        }
        Ok(())
    }
}

/// Expected top-level directories to organize the project folder.
#[derive(Clone, Debug)]
pub struct RootDirs {
    /// Top-level path for code.
    ///
    /// This folder contains all the code used to process files from [`data`][Self::data],
    /// perform statistical analyses, create visualizations, and save the outputs
    /// in [`results`][Self::results].
    /// Generally, this directory contains a series of subdirectories, each of
    /// which contain a set of related scripts for a single research question.
    /// For example, each subdirectory may contain:
    /// - a workflow file (e.g. [`Snakefile`](https://snakemake.github.io/) or [`Nextflow`](https://www.nextflow.io/))
    /// - a data pre-processing script
    /// - a statistical analysis and calculation script
    /// - a plotting script
    pub(crate) code: Option<PathBuf>,

    /// Top-level path for data.
    ///
    /// All raw and processed data should be found within this directory.
    /// The datasets located here will then be sourced by code within the [`code`][Self::code]
    /// directory and used to generate outputs in the [`results`][Self::results]
    /// directory.
    pub(crate) data: Option<PathBuf>,

    /// Top-level path for results.
    ///
    /// Code and scripts in the [`code`][Self::code] directory should create outputs
    /// in this directory to ensure a separation of inputs, code, and outputs.
    /// Generally, this directory contains a series of subdirectories, each of
    /// which will contain all the outputs originating from the code in the
    /// corresponding [`code`][Self::code] subdirectory.
    pub(crate) results: Option<PathBuf>,

    /// Top-level path for vendored external code.
    ///
    /// In many research projects you will need a copy of some external code,
    /// such as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules),
    /// or a package manifest of some kind, like a [Nix derivation](https://nixos.org/)
    /// or an [Anaconda recipe](https://anaconda.org/).
    /// This folder can be used to house all of the relevant code so as to not
    /// populate the custom code present in [`code`][Self::code].
    pub(crate) external: Option<PathBuf>,

    /// Top-level path for documentation.
    ///
    /// Documentation such as a manuscript, experimental descriptions from contract
    /// research organizations, or interactive HTML notebooks displaying the data
    /// and its results can go here.
    /// Data that belongs in [`data`][Self::data] or notebooks which process data
    /// that belong in [`code`][Self::code] should not be placed in here.
    pub(crate) docs: Option<PathBuf>,
}

impl Default for RootDirs {
    fn default() -> Self {
        let root = project_root();

        Self {
            code: Some(root.join("code")),
            data: Some(root.join("data")),
            results: Some(root.join("results")),
            external: Some(root.join("pkgs")),
            docs: Some(root.join("docs")),
        }
    }
}

impl From<Option<ConfigFileRootDirs>> for RootDirs {
    fn from(value: Option<ConfigFileRootDirs>) -> Self {
        let defaults = Self::default();

        match value {
            Some(dirs) => {
                let code = parse_root_dir_name(dirs.code.as_deref(), defaults.code);
                let data = parse_root_dir_name(dirs.data.as_deref(), defaults.data);
                let docs = parse_root_dir_name(dirs.docs.as_deref(), defaults.docs);
                let external = parse_root_dir_name(dirs.external.as_deref(), defaults.external);
                let results = parse_root_dir_name(dirs.results.as_deref(), defaults.results);

                Self {
                    code,
                    data,
                    docs,
                    external,
                    results,
                }
            }
            None => RootDirs::default(),
        }
    }
}

/// A helper function to parse the directory name for a root directory.
///
/// If the directory specified in the configuration file is an empty string,
/// then it will be considered as `None`.
fn parse_root_dir_name(s: Option<&str>, default: Option<PathBuf>) -> Option<PathBuf> {
    match s {
        Some("") => None,
        Some(dir_name) => Some(PathBuf::from(dir_name)),
        None => default,
    }
}