libscilo/lints/

check.rs

//! Structs and functions to organize and perform lint checks.

use log::{debug, info};
use regex::Regex;
use std::{
    cmp::Ordering,
    iter::{Filter, FilterMap},
    path::Path,
};
use strum::{EnumIter, EnumString};
use walkdir::{DirEntry, Error, IntoIter, WalkDir};

use super::LintError;
use crate::InstantiatedConfig;

/// The linting checks that are currently supported.
///
/// Lint codes available in a configuration file are `snake_case` versions of
/// the enum names here.
#[derive(Clone, Copy, Debug, strum::Display, EnumIter, EnumString)]
#[strum(serialize_all = "snake_case")]
pub enum LintCheck {
    /// Check that every subdirectory within the project's [`code`][crate::RootDirs::code]
    /// directory has a corresponding subdirectory with the same name in the
    /// [`results`][crate::RootDirs::results] directory, and vice versa.
    CodeResultsSubdirPairing,

    /// All subdirectories within the project's [`code`][crate::RootDirs::code]
    /// and [`results`][crate::RootDirs::results] directory should
    /// have names that match the regular expression in
    /// [`code_results_subdir_regex`][crate::InstantiatedConfig::code_results_subdir_regex].
    CodeResultsSubdirRegex,

    /// Each subdirectory within the project's [`code`][crate::RootDirs::code]
    /// directory should contain a README file.
    CodeSubdirReadmes,

    /// Each subdirectory within the project's [`code`][crate::RootDirs::code]
    /// directory should contain a workflow file.
    CodeSubdirWorkflows,

    /// Each subdirectory within the project's [`data`][crate::RootDirs::data]
    /// directory should contain a README file.
    DataSubdirReadmes,

    /// Check for a set of required directories that should be present in the
    /// project's root directory.
    RootDirs,

    /// Check for a set of required files that should be present in the
    /// project's root directory.
    RootFiles,
}

impl LintCheck {
    /// Execute a lint check.
    ///
    /// This is effectively a large match statement that dispatches the relevant
    /// checks to other functions.
    pub fn check(self, cfg: &InstantiatedConfig) -> Result<(), LintError> {
        info!("Checking lint: {}", self);
        match self {
            Self::CodeResultsSubdirPairing => {
                if let (Some(code), Some(results)) = (&cfg.root_dirs.code, &cfg.root_dirs.results) {
                    code_results_subdir_pairing(code, results)?;
                }
            }
            Self::CodeResultsSubdirRegex => {
                if let (Some(code), Some(re)) =
                    (&cfg.root_dirs.code, &cfg.code_results_subdir_regex)
                {
                    code_results_dir_regex(code, re)?;
                }
                if let (Some(results), Some(re)) =
                    (&cfg.root_dirs.results, &cfg.code_results_subdir_regex)
                {
                    code_results_dir_regex(results, re)?;
                }
            }
            Self::CodeSubdirReadmes => {
                if let (Some(code), Some(readmes)) = (&cfg.root_dirs.code, &cfg.readme_names) {
                    // this remaps the variable so the input type matches the function signature
                    let readmes = readmes.iter().map(String::as_str).collect();
                    subdir_readmes(code, readmes)?;
                }
            }
            Self::CodeSubdirWorkflows => {
                if let (Some(code), Some(workflows)) = (&cfg.root_dirs.code, &cfg.workflow_names) {
                    // this remaps the variable so the input type matches the function signature
                    let workflows = workflows.iter().map(String::as_str).collect();
                    subdir_workflows(code, workflows)?;
                }
            }
            Self::DataSubdirReadmes => {
                if let (Some(data), Some(readmes)) = (&cfg.root_dirs.data, &cfg.readme_names) {
                    // this remaps the variable so the input type matches the function signature
                    let readmes = readmes.iter().map(String::as_str).collect();
                    subdir_readmes(data, readmes)?;
                }
            }
            Self::RootDirs => {
                let root_dirs = [
                    cfg.root_dirs.code.clone(),
                    cfg.root_dirs.data.clone(),
                    cfg.root_dirs.docs.clone(),
                    cfg.root_dirs.external.clone(),
                    cfg.root_dirs.results.clone(),
                ];
                for dir in root_dirs.iter().filter_map(|d| d.as_ref()) {
                    dir_exists(dir)?;
                }
            }
            Self::RootFiles => {
                for file in &cfg.root_files {
                    file_exists(file)?;
                }
            }
        }

        Ok(())
    }
}

/// A helper function to set up a directory walker within a given directory.
///
/// This ignores symlinks.
/// This also guarantees that the entries will be walked over in an order, sorted by file name.
fn directory_walker(
    path: &Path,
) -> Filter<
    FilterMap<IntoIter, impl FnMut(Result<DirEntry, Error>) -> Option<DirEntry>>,
    impl FnMut(&DirEntry) -> bool,
> {
    WalkDir::new(path)
        .max_depth(1)
        .min_depth(1)
        .sort_by(|a, b| a.file_name().cmp(b.file_name()))
        .into_iter()
        .filter_map(|e| e.ok())
        .filter(|e| match e.metadata() {
            Ok(meta) => meta.is_dir(),
            Err(_) => false,
        })
}

/// Check that every subdirectory within [`code`][crate::RootDirs::code]
/// has a corresponding subdirectory in [`results`][crate::RootDirs::results]
/// and vice versa.
pub(crate) fn code_results_subdir_pairing(code: &Path, results: &Path) -> Result<(), LintError> {
    let mut code_walker = directory_walker(code);
    let mut results_walker = directory_walker(results);

    let mut code_subdir_opt = code_walker.next();
    let mut results_subdir_opt = results_walker.next();

    loop {
        // because these are guaranteed to be in sorted order, we just need to
        // compare them element by element
        match (code_subdir_opt, results_subdir_opt) {
            (None, None) => break,
            (Some(code_subdir), None) => {
                let formatted_code_subdir_name = code.join(code_subdir.file_name()).to_path_buf();
                let formatted_results_subdir_name =
                    results.join(code_subdir.file_name()).to_path_buf();
                return Err(LintError::CodeSubdirectoryMissingInResults {
                    code: formatted_code_subdir_name,
                    results: formatted_results_subdir_name,
                });
            }
            (None, Some(results_subdir)) => {
                let formatted_results_subdir_name =
                    results.join(results_subdir.file_name()).to_path_buf();
                let formatted_code_subdir_name =
                    code.join(results_subdir.file_name()).to_path_buf();
                return Err(LintError::ResultsSubdirectoryMissingInCode {
                    code: formatted_code_subdir_name,
                    results: formatted_results_subdir_name,
                });
            }
            (Some(code_subdir), Some(results_subdir)) => {
                match code_subdir.file_name().cmp(results_subdir.file_name()) {
                    Ordering::Equal => {
                        // move to the next set of item to compare
                        code_subdir_opt = code_walker.next();
                        results_subdir_opt = results_walker.next();
                    }
                    Ordering::Less => {
                        let formatted_code_subdir_name =
                            code.join(code_subdir.file_name()).to_path_buf();
                        let formatted_results_subdir_name =
                            results.join(code_subdir.file_name()).to_path_buf();
                        return Err(LintError::CodeSubdirectoryMissingInResults {
                            code: formatted_code_subdir_name,
                            results: formatted_results_subdir_name,
                        });
                    }
                    Ordering::Greater => {
                        let formatted_results_subdir_name =
                            results.join(results_subdir.file_name()).to_path_buf();
                        let formatted_code_subdir_name =
                            code.join(results_subdir.file_name()).to_path_buf();
                        return Err(LintError::ResultsSubdirectoryMissingInCode {
                            code: formatted_code_subdir_name,
                            results: formatted_results_subdir_name,
                        });
                    }
                }
            }
        }
    }

    Ok(())
}

/// Check that the directories under the [`code`][crate::RootDirs::code]
/// and [`results`][crate::RootDirs::results] follow the correct style.
pub(crate) fn code_results_dir_regex(path: &Path, re: &Regex) -> Result<(), LintError> {
    let walker = directory_walker(path);
    for entry in walker {
        if let Some(dir_name) = entry.path().file_name() {
            if let Some(dir_str) = dir_name.to_str() {
                if !re.is_match_at(dir_str, 0) {
                    return Err(LintError::CodeResultsSubdirectoryRegexMismatch(
                        entry.into_path(),
                        re.to_string(),
                    ));
                }
            }
        }
    }
    Ok(())
}

/// Check that a required directory exists.
///
/// This is a wrapper around [`Path::is_dir()`] that returns the correct [`LintError`].
pub fn dir_exists(path: &Path) -> Result<(), LintError> {
    if path.is_dir() && path.exists() {
        Ok(())
    } else {
        Err(LintError::RequiredDirectoryDoesNotExist(path.to_path_buf()))
    }
}

/// Check that a required file exists.
///
/// This is a wrapper around [`Path::is_file()`] that returns the correct [`LintError`].
pub fn file_exists(path: &Path) -> Result<(), LintError> {
    if path.is_file() && path.exists() {
        Ok(())
    } else {
        Err(LintError::RequiredFileDoesNotExist(path.to_path_buf()))
    }
}

/// Check for the presence of README files within each subdirectory of a [root directory][crate::RootDirs].
fn subdir_readmes(path: &Path, readmes: Vec<&str>) -> Result<(), LintError> {
    debug!("Checking for READMEs in {}", path.display());
    let walker = directory_walker(path);
    for entry in walker {
        debug!("Checking for README in {}", entry.path().display());
        let mut subdir_readme = false;

        for readme in &readmes {
            let readme_path = entry.path().join(readme);
            debug!("Checking for {}", readme_path.display());
            if readme_path.exists() {
                subdir_readme = true;
            }
        }

        if !subdir_readme {
            return Err(LintError::SubdirectoryMissingReadme(
                entry.path().to_path_buf(),
            ));
        }
    }

    Ok(())
}

/// Check for the presence of workflow files within each [`code`][crate::RootDirs::code] subdirectory.
fn subdir_workflows(path: &Path, workflows: Vec<&str>) -> Result<(), LintError> {
    debug!("Checking for workflow files in {}", path.display());
    let walker = directory_walker(path);
    for entry in walker {
        debug!("Checking for workflow file in {}", entry.path().display());
        let mut subdir_workflow = false;

        for workflow in &workflows {
            let workflow_path = entry.path().join(workflow);
            debug!("Checking for {}", workflow_path.display());
            if workflow_path.exists() {
                subdir_workflow = true;
            }
        }

        if !subdir_workflow {
            return Err(LintError::SubdirectoryMissingWorkflow(
                entry.path().to_path_buf(),
            ));
        }
    }

    Ok(())
}