fsvalidator/

validate.rs

//! # Validation
//!
//! Contains the logic for validating filesystem paths against the model.
//!
//! This module implements the core validation functionality, checking whether real filesystem
//! paths match the expected structure defined in the model.

use crate::model::{DirNode, FileNode, Node, NodeName};
use anyhow::{Result, anyhow};
use regex::Regex;
use std::fs;
use std::path::{Path, PathBuf};
use std::fmt;
use std::error::Error;

/// Error category for classifying validation errors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorCategory {
    /// Missing file or directory that was required
    Missing,
    /// Path exists but is the wrong type (e.g., file instead of directory)
    WrongType,
    /// Name doesn't match expected literal or pattern
    NameMismatch,
    /// Unexpected entry in directory with allow_defined_only=true
    Unexpected,
    /// Invalid regex pattern
    InvalidPattern,
    /// Error accessing filesystem
    IoError,
    /// Other/miscellaneous errors
    Other,
}

/// Represents a validation error encountered during filesystem validation.
#[derive(Debug)]
pub struct ValidationError {
    /// Path where the validation error occurred
    pub path: PathBuf,
    /// Description of the validation error
    pub message: String,
    /// Category of the validation error
    pub category: ErrorCategory,
    /// Nested validation errors (for directory validation)
    pub children: Vec<ValidationError>,
}

impl ValidationError {
    /// Creates a new ValidationError with the given path, message, and category.
    pub fn new(
        path: impl AsRef<Path>,
        message: impl Into<String>,
        category: ErrorCategory
    ) -> Self {
        ValidationError {
            path: path.as_ref().to_path_buf(),
            message: message.into(),
            category,
            children: Vec::new(),
        }
    }

    /// Creates a new ValidationError with the given path, message, category, and child errors.
    pub fn with_children(
        path: impl AsRef<Path>, 
        message: impl Into<String>,
        category: ErrorCategory,
        children: Vec<ValidationError>
    ) -> Self {
        ValidationError {
            path: path.as_ref().to_path_buf(),
            message: message.into(),
            category,
            children,
        }
    }

    /// Adds a child validation error to this error.
    pub fn add_child(&mut self, error: ValidationError) {
        self.children.push(error);
    }
}

impl fmt::Display for ValidationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        writeln!(f, "At {}: {}", self.path.display(), self.message)?;
        for child in &self.children {
            write!(f, "  ")?;
            write!(f, "{}", child)?;
        }
        Ok(())
    }
}

impl Error for ValidationError {}

/// Result type for validation operations that may return multiple validation errors.
pub type ValidationResult = Result<(), ValidationError>;

impl Node {
    /// Validates a filesystem path against this node, collecting all validation errors.
    ///
    /// This method checks whether the given path matches the requirements specified by this node.
    /// For file nodes, it verifies the file exists (if required) and matches the name/pattern.
    /// For directory nodes, it checks the directory exists (if required), matches the name/pattern,
    /// and contains the expected children.
    ///
    /// # Arguments
    ///
    /// * `path` - The direct filesystem path to the item (file or directory) to validate
    ///
    /// # Returns
    ///
    /// * `Ok(())` - If the path matches the requirements
    /// * `Err(ValidationError)` - If the path doesn't match, with all validation errors found
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use fsvalidator::model::{DirNode, FileNode, NodeName};
    ///
    /// // Create a validation model
    /// let file_node = FileNode::new(NodeName::Literal("README.md".to_string()), true);
    ///
    /// // Validate a path
    /// let result = file_node.validate("./project/README.md");
    /// assert!(result.is_ok());
    /// ```
    pub fn validate(&self, path: impl AsRef<Path>) -> ValidationResult {
        let path = path.as_ref();
        match self {
            Node::File(file_rc) => {
                let file = file_rc.borrow();
                validate_file(&file, path)
            }

            Node::Dir(dir_rc) => {
                let dir = dir_rc.borrow();
                validate_dir(&dir, path)
            }
        }
    }
}

/// Validates a filesystem path against a file node.
///
/// Checks if the file exists (when required) and matches the specified name or pattern.
///
/// # Arguments
///
/// * `file` - The file node to validate against
/// * `file_path` - The direct path to the file to validate
///
/// # Returns
///
/// * `Ok(())` - If validation succeeds
/// * `Err(ValidationError)` - If validation fails, containing all validation errors
fn validate_file(file: &FileNode, file_path: &Path) -> ValidationResult {
    // Check if the file exists and is actually a file
    if file_path.exists() {
        if !file_path.is_file() {
            return Err(ValidationError::new(
                file_path,
                format!("Path exists but is not a file"),
                ErrorCategory::WrongType,
            ));
        }

        // Get the file name to check against the pattern
        let file_name = match file_path.file_name() {
            Some(name) => name.to_string_lossy().to_string(),
            None => {
                return Err(ValidationError::new(
                    file_path,
                    format!("Invalid file path (no filename)"),
                    ErrorCategory::Other,
                ))
            }
        };

        match &file.name {
            NodeName::Literal(name) => {
                if &file_name != name {
                    return Err(ValidationError::new(
                        file_path,
                        format!(
                            "File name '{}' doesn't match expected name '{}'",
                            file_name, name
                        ),
                        ErrorCategory::NameMismatch,
                    ));
                }
                Ok(())
            }
            NodeName::Pattern(pattern) => {
                let re = match Regex::new(pattern) {
                    Ok(re) => re,
                    Err(e) => {
                        return Err(ValidationError::new(
                            file_path,
                            format!("Invalid regex pattern '{}': {}", pattern, e),
                            ErrorCategory::InvalidPattern,
                        ));
                    }
                };

                if re.is_match(&file_name) {
                    Ok(())
                } else {
                    Err(ValidationError::new(
                        file_path,
                        format!(
                            "File name '{}' doesn't match expected pattern '{}'",
                            file_name, pattern
                        ),
                        ErrorCategory::NameMismatch,
                    ))
                }
            }
        }
    } else if file.required {
        Err(ValidationError::new(
            file_path,
            format!("Missing required file"),
            ErrorCategory::Missing,
        ))
    } else {
        Ok(())
    }
}

/// Validates a filesystem path against a directory node.
///
/// Checks if the directory exists (when required), matches the specified name or pattern,
/// contains the expected children, and doesn't contain unexpected entries (when allow_defined_only is true).
///
/// # Arguments
///
/// * `dir` - The directory node to validate against
/// * `dir_path` - The direct path to the directory to validate
///
/// # Returns
///
/// * `Ok(())` - If validation succeeds
/// * `Err(ValidationError)` - If validation fails, containing all validation errors
fn validate_dir(dir: &DirNode, dir_path: &Path) -> ValidationResult {
    // Check if the directory exists and is actually a directory
    if !dir_path.exists() {
        return if dir.required {
            Err(ValidationError::new(
                dir_path,
                format!("Missing required directory"),
                ErrorCategory::Missing,
            ))
        } else {
            Ok(())
        };
    }

    if !dir_path.is_dir() {
        return Err(ValidationError::new(
            dir_path,
            format!("Path exists but is not a directory"),
            ErrorCategory::WrongType,
        ));
    }

    // Get the directory name to check against pattern/literal
    let dir_name = match dir_path.file_name() {
        Some(name) => name.to_string_lossy().to_string(),
        None => {
            return Err(ValidationError::new(
                dir_path,
                format!("Invalid directory path (no directory name)"),
                ErrorCategory::Other,
            ));
        }
    };

    let mut validation_errors = Vec::new();

    // Validate directory name against expected name/pattern
    match &dir.name {
        NodeName::Literal(name) => {
            if &dir_name != name {
                validation_errors.push(ValidationError::new(
                    dir_path,
                    format!(
                        "Directory name '{}' doesn't match expected name '{}'",
                        dir_name, name
                    ),
                    ErrorCategory::NameMismatch,
                ));
            }
        }
        NodeName::Pattern(pattern) => {
            let re = match Regex::new(pattern) {
                Ok(re) => re,
                Err(e) => {
                    return Err(ValidationError::new(
                        dir_path,
                        format!("Invalid regex pattern '{}': {}", pattern, e),
                        ErrorCategory::InvalidPattern,
                    ));
                }
            };

            if !re.is_match(&dir_name) {
                validation_errors.push(ValidationError::new(
                    dir_path,
                    format!(
                        "Directory name '{}' doesn't match expected pattern '{}'",
                        dir_name, pattern
                    ),
                    ErrorCategory::NameMismatch,
                ));
            }
        }
    }

    // Check for unexpected entries if allow_defined_only is true
    if dir.allow_defined_only {
        let expected_names: Vec<String> = dir
            .children
            .iter()
            .map(|node| match node {
                Node::File(f) => f.borrow().name_name_string(),
                Node::Dir(d) => d.borrow().name_name_string(),
            })
            .collect();

        let read_dir_result = match fs::read_dir(dir_path) {
            Ok(entries) => entries,
            Err(e) => {
                validation_errors.push(ValidationError::new(
                    dir_path,
                    format!("Failed to read directory: {}", e),
                    ErrorCategory::IoError,
                ));
                // Cannot continue checking entries
                if !validation_errors.is_empty() {
                    return Err(ValidationError::with_children(
                        dir_path,
                        format!("Directory validation failed with {} errors", validation_errors.len()),
                        ErrorCategory::Other,
                        validation_errors,
                    ));
                }
                return Ok(());
            }
        };

        for entry_result in read_dir_result {
            let entry = match entry_result {
                Ok(e) => e,
                Err(e) => {
                    validation_errors.push(ValidationError::new(
                        dir_path,
                        format!("Failed to read directory entry: {}", e),
                        ErrorCategory::IoError,
                    ));
                    continue;
                }
            };

            if dir
                .excluded
                .iter()
                .any(|re| re.is_match(entry.file_name().to_string_lossy().to_string().as_str()))
            {
                continue;
            }

            let name = entry.file_name().to_string_lossy().to_string();
            if !expected_names.iter().any(|p| pattern_match(p, &name)) {
                validation_errors.push(ValidationError::new(
                    entry.path(),
                    format!("Unexpected entry in directory"),
                    ErrorCategory::Unexpected,
                ));
            }
        }
    }

    // Validate children
    let mut child_errors = Vec::new();
    for child in &dir.children {
        // For child nodes, we need to find the actual path of the child
        match child {
            Node::File(f_rc) => {
                let f = f_rc.borrow();
                match &f.name {
                    NodeName::Literal(name) => {
                        let child_path = dir_path.join(name);
                        if let Err(err) = child.validate(&child_path) {
                            child_errors.push(err);
                        }
                    }
                    NodeName::Pattern(pattern) => {
                        let re = match Regex::new(pattern) {
                            Ok(re) => re,
                            Err(e) => {
                                validation_errors.push(ValidationError::new(
                                    dir_path,
                                    format!("Invalid regex pattern '{}': {}", pattern, e),
                                    ErrorCategory::InvalidPattern,
                                ));
                                continue;
                            }
                        };

                        let read_dir_result = match fs::read_dir(dir_path) {
                            Ok(entries) => entries,
                            Err(e) => {
                                validation_errors.push(ValidationError::new(
                                    dir_path,
                                    format!("Failed to read directory when matching pattern: {}", e),
                                    ErrorCategory::IoError,
                                ));
                                continue;
                            }
                        };

                        let mut matched_path = None;
                        for entry_result in read_dir_result {
                            let entry = match entry_result {
                                Ok(e) => e,
                                Err(e) => {
                                    validation_errors.push(ValidationError::new(
                                        dir_path,
                                        format!("Failed to read directory entry: {}", e),
                                        ErrorCategory::IoError,
                                    ));
                                    continue;
                                }
                            };

                            if dir.excluded.iter().any(|re| {
                                re.is_match(
                                    entry.file_name().to_string_lossy().to_string().as_str(),
                                )
                            }) {
                                continue;
                            }

                            if entry.path().is_file() {
                                let name = entry.file_name().to_string_lossy().to_string();
                                if re.is_match(&name) {
                                    matched_path = Some(entry.path());
                                    break;
                                }
                            }
                        }

                        match matched_path {
                            Some(path) => {
                                if let Err(err) = child.validate(&path) {
                                    child_errors.push(err);
                                }
                            }
                            None => {
                                if f.required {
                                    validation_errors.push(ValidationError::new(
                                        dir_path,
                                        format!(
                                            "Missing required file matching pattern: {}",
                                            pattern
                                        ),
                                        ErrorCategory::Missing,
                                    ));
                                }
                            }
                        }
                    }
                }
            }

            Node::Dir(d_rc) => {
                let d = d_rc.borrow();
                match &d.name {
                    NodeName::Literal(name) => {
                        let child_path = dir_path.join(name);
                        if let Err(err) = child.validate(&child_path) {
                            child_errors.push(err);
                        }
                    }
                    NodeName::Pattern(pattern) => {
                        let re = match Regex::new(pattern) {
                            Ok(re) => re,
                            Err(e) => {
                                validation_errors.push(ValidationError::new(
                                    dir_path,
                                    format!("Invalid regex pattern '{}': {}", pattern, e),
                                    ErrorCategory::InvalidPattern,
                                ));
                                continue;
                            }
                        };

                        let read_dir_result = match fs::read_dir(dir_path) {
                            Ok(entries) => entries,
                            Err(e) => {
                                validation_errors.push(ValidationError::new(
                                    dir_path,
                                    format!("Failed to read directory when matching pattern: {}", e),
                                    ErrorCategory::IoError,
                                ));
                                continue;
                            }
                        };

                        let mut matched_paths = vec![];
                        for entry_result in read_dir_result {
                            let entry = match entry_result {
                                Ok(e) => e,
                                Err(e) => {
                                    validation_errors.push(ValidationError::new(
                                        dir_path,
                                        format!("Failed to read directory entry: {}", e),
                                        ErrorCategory::IoError,
                                    ));
                                    continue;
                                }
                            };

                            if dir.excluded.iter().any(|re| {
                                re.is_match(
                                    entry.file_name().to_string_lossy().to_string().as_str(),
                                )
                            }) {
                                continue;
                            }
                            if entry.path().is_dir() {
                                let name = entry.file_name().to_string_lossy().to_string();
                                if re.is_match(&name) {
                                    matched_paths.push(entry.path());
                                }
                            }
                        }

                        if matched_paths.is_empty() {
                            if d.required {
                                validation_errors.push(ValidationError::new(
                                    dir_path,
                                    format!(
                                        "Missing required directory matching pattern: {}",
                                        pattern
                                    ),
                                    ErrorCategory::Missing,
                                ));
                            }
                        } else {
                            // Validate all matching directories
                            for matched_path in matched_paths {
                                if let Err(err) = child.validate(&matched_path) {
                                    child_errors.push(err);
                                }
                            }
                        }
                    }
                }
            }
        };
    }

    // Combine all validation errors
    validation_errors.extend(child_errors);

    if validation_errors.is_empty() {
        Ok(())
    } else {
        Err(ValidationError::with_children(
            dir_path,
            format!("Directory validation failed with {} errors", validation_errors.len()),
            ErrorCategory::Other,
            validation_errors,
        ))
    }
}

/// Checks if a name matches a pattern string.
///
/// If the pattern starts with "PATTERN(", it's treated as a regex pattern.
/// Otherwise, it's treated as a literal string that must match exactly.
///
/// # Arguments
///
/// * `pattern` - The pattern string (either a regex pattern or literal)
/// * `name` - The name to check against the pattern
///
/// # Returns
///
/// * `true` if the name matches the pattern
/// * `false` if the name doesn't match
fn pattern_match(pattern: &str, name: &str) -> bool {
    if pattern.starts_with("PATTERN(") && pattern.ends_with(")") {
        let inner = &pattern[8..pattern.len() - 1]; // Extract regex pattern
        match Regex::new(inner) {
            Ok(re) => re.is_match(name),
            Err(e) => {
                eprintln!("Error compiling regex pattern '{}': {}", inner, e);
                false
            }
        }
    } else {
        pattern == name
    }
}

/// Converts a `ValidationResult` to a standard `anyhow::Result`.
///
/// This helper function is useful for code that can't work with a ValidationResult directly.
pub fn to_anyhow_result(result: ValidationResult) -> Result<()> {
    match result {
        Ok(()) => Ok(()),
        Err(validation_err) => Err(anyhow!(validation_err.to_string())),
    }
}

/// A trait for converting a NodeName to a string representation.
///
/// This is used internally for comparing node names during validation.
trait NameString {
    /// Converts a node name to a string representation.
    fn name_name_string(&self) -> String;
}

impl NameString for DirNode {
    fn name_name_string(&self) -> String {
        match &self.name {
            NodeName::Literal(s) => s.clone(),
            NodeName::Pattern(p) => format!("PATTERN({})", p),
        }
    }
}

impl NameString for FileNode {
    fn name_name_string(&self) -> String {
        match &self.name {
            NodeName::Literal(s) => s.clone(),
            NodeName::Pattern(p) => format!("PATTERN({})", p),
        }
    }
}