tree_type/

lib.rs

pub mod deps;
pub mod fs;

use std::io::ErrorKind;

// Re-export the proc macros for user convenience
pub use tree_type_proc_macro::{dir_type, file_type, tree_type};

pub enum GenericPath {
    File(GenericFile),
    Dir(GenericDir),
}

impl TryFrom<std::fs::DirEntry> for GenericPath {
    type Error = std::io::Error;

    fn try_from(value: std::fs::DirEntry) -> Result<Self, Self::Error> {
        let path: &std::path::Path = &value.path();
        GenericPath::try_from(path)
    }
}

#[cfg(feature = "walk")]
impl TryFrom<crate::deps::walk::DirEntry> for GenericPath {
    type Error = std::io::Error;

    fn try_from(value: crate::deps::walk::DirEntry) -> Result<Self, Self::Error> {
        GenericPath::try_from(value.path())
    }
}

#[cfg(feature = "enhanced-errors")]
impl TryFrom<crate::deps::enhanced_errors::DirEntry> for GenericPath {
    type Error = std::io::Error; // because ::fs_err::Error is private

    fn try_from(value: crate::deps::enhanced_errors::DirEntry) -> Result<Self, Self::Error> {
        let path: &std::path::Path = &value.path();
        GenericPath::try_from(path)
    }
}

impl TryFrom<&std::path::Path> for GenericPath {
    type Error = std::io::Error;

    fn try_from(path: &std::path::Path) -> Result<Self, Self::Error> {
        let path = resolve_path(path)?;
        if path.is_file() {
            Ok(GenericPath::File(GenericFile(path)))
        } else if path.is_dir() {
            Ok(GenericPath::Dir(GenericDir(path)))
        } else {
            Err(std::io::Error::other("unsupported path type"))
        }
    }
}

impl std::fmt::Display for GenericPath {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GenericPath::File(file) => write!(f, "{}", file.0.display()),
            GenericPath::Dir(dir) => write!(f, "{}", dir.0.display()),
        }
    }
}

impl std::fmt::Debug for GenericPath {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GenericPath::File(file) => write!(f, "GenericPath::File({})", file.0.display()),
            GenericPath::Dir(dir) => write!(f, "GenericPath::Dir({})", dir.0.display()),
        }
    }
}

fn resolve_path(path: &std::path::Path) -> Result<std::path::PathBuf, std::io::Error> {
    use std::collections::HashSet;
    let mut p = path.to_path_buf();
    let mut seen = HashSet::new();
    seen.insert(p.clone());
    while p.is_symlink() {
        p = p.read_link()?;
        if seen.contains(&p) {
            return Err(std::io::Error::other("symlink loop"));
        }
    }
    Ok(p)
}

// Generate GenericFile using the proc macro
#[allow(unexpected_cfgs)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct GenericFile(std::path::PathBuf);

impl GenericFile {
    /// Create a new wrapper for a file
    ///
    /// # Errors
    ///
    /// If the file name is invalid. Invalid file name inclued empty file name.
    pub fn new(path: impl Into<std::path::PathBuf>) -> std::io::Result<Self> {
        let path_buf = path.into();
        let file_name = path_buf.file_name();
        if file_name.is_none() {
            return Err(std::io::Error::from(ErrorKind::InvalidFilename));
        }
        Ok(Self(path_buf))
    }

    #[must_use]
    pub fn as_path(&self) -> &std::path::Path {
        &self.0
    }

    #[must_use]
    pub fn exists(&self) -> bool {
        self.0.exists()
    }

    #[must_use]
    pub fn as_generic(&self) -> GenericFile {
        self.clone()
    }

    /// Reads the entire contents of a file into a bytes vector.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::read`
    pub fn read(&self) -> std::io::Result<Vec<u8>> {
        fs::read(&self.0)
    }

    /// Reads the entire contents of a file into a string.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::read_to_string`
    pub fn read_to_string(&self) -> std::io::Result<String> {
        fs::read_to_string(&self.0)
    }

    /// Writes a slice as the entire contents of a file.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::write`
    pub fn write<C: AsRef<[u8]>>(&self, contents: C) -> std::io::Result<()> {
        if let Some(parent) = self.0.parent() {
            if !parent.exists() {
                fs::create_dir_all(parent)?;
            }
        }
        fs::write(&self.0, contents)
    }

    /// Create an empty file if it doesn't already exist
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::open`
    pub fn create(&self) -> std::io::Result<()> {
        if let Some(parent) = self.0.parent() {
            if !parent.exists() {
                fs::create_dir_all(parent)?;
            }
        }
        fs::create_file(&self.0)
    }

    /// Removes a file from the filesystem.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::remove_file`
    pub fn remove(&self) -> std::io::Result<()> {
        fs::remove_file(&self.0)
    }

    /// Given a path, queries the file system to get information about a file, directory, etc.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::metadata`
    pub fn fs_metadata(&self) -> std::io::Result<fs::Metadata> {
        fs::metadata(&self.0)
    }

    /// Returns the final component of the path as a String.
    /// See [`std::path::Path::file_name`] for more details.
    ///
    #[must_use]
    #[allow(clippy::missing_panics_doc)]
    pub fn file_name(&self) -> String {
        self.0
            .file_name()
            .expect("validated in new")
            .to_string_lossy()
            .to_string()
    }

    /// Rename/move this file to a new path.
    ///
    /// Consumes the original instance and returns a new instance with the updated path on success.
    /// On failure, returns both the error and the original instance for recovery.
    /// Parent directories are created automatically if they don't exist.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let file = GenericFile::new("old.txt");
    /// match file.rename("new.txt") {
    ///     Ok(renamed_file) => {
    ///         // Use renamed_file
    ///     }
    ///     Err((error, original_file)) => {
    ///         // Handle error, original_file is still available
    ///     }
    /// }
    /// ```
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::rename`
    pub fn rename(
        self,
        new_path: impl AsRef<std::path::Path>,
    ) -> Result<Self, (std::io::Error, Self)> {
        let new_path = new_path.as_ref();

        // Create parent directories if they don't exist
        if let Some(parent) = new_path.parent() {
            if !parent.exists() {
                if let Err(e) = fs::create_dir_all(parent) {
                    return Err((e, self));
                }
            }
        }

        // Attempt the rename
        match fs::rename(&self.0, new_path) {
            Ok(()) => Self::new(new_path).map_err(|e| (e, self)),
            Err(e) => Err((e, self)),
        }
    }

    /// Set file permissions to 0o600 (read/write for owner only).
    ///
    /// This method is only available on Unix systems.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let file = GenericFile::new("secret.txt");
    /// file.secure()?;
    /// ```
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::set_permissions`
    #[cfg(unix)]
    pub fn secure(&self) -> std::io::Result<()> {
        use std::os::unix::fs::PermissionsExt;
        let permissions = std::fs::Permissions::from_mode(0o600);
        fs::set_permissions(&self.0, permissions)
    }

    /// Get the parent directory as `GenericDir`.
    /// Files always have a parent directory.
    #[must_use]
    #[allow(clippy::missing_panics_doc)]
    pub fn parent(&self) -> GenericDir {
        let parent_path = self.0.parent().expect("Files must have a parent directory");
        GenericDir::new(parent_path).expect("Parent path should be valid")
    }
}

impl AsRef<std::path::Path> for GenericFile {
    fn as_ref(&self) -> &std::path::Path {
        &self.0
    }
}

impl std::fmt::Display for GenericFile {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0.display())
    }
}

impl std::fmt::Debug for GenericFile {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "GenericFile({})", self.0.display())
    }
}

/// Generic directory type for type-erased directory operations.
///
/// This type can be used when you need to work with directories in a generic way,
/// without knowing their specific type at compile time. It supports conversion
/// to and from any typed directory struct.
///
/// # Examples
///
/// ```ignore
/// use tree_type::{dir_type, GenericDir};
///
/// dir_type!(CacheDir);
///
/// let cache = CacheDir::new("/var/cache");
/// let generic: GenericDir = cache.into();
/// let cache_again = CacheDir::from_generic(generic);
/// ```
#[allow(unexpected_cfgs)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct GenericDir(std::path::PathBuf);

impl GenericDir {
    /// Create a new wrapper for a directory
    ///
    /// # Errors
    ///
    /// If the directory is invalid. Invalid directory includes being empty.
    pub fn new(path: impl Into<std::path::PathBuf>) -> std::io::Result<Self> {
        let path_buf = path.into();
        // For directories, allow root paths and paths with filename components
        // Only reject empty paths or invalid paths like ".."
        if path_buf.as_os_str().is_empty() {
            return Err(std::io::Error::from(ErrorKind::InvalidFilename));
        }
        Ok(Self(path_buf))
    }

    #[must_use]
    pub fn as_path(&self) -> &std::path::Path {
        &self.0
    }

    #[must_use]
    pub fn exists(&self) -> bool {
        self.0.exists()
    }

    /// Returns a clone of the `GenericDir`
    #[must_use]
    pub fn as_generic(&self) -> GenericDir {
        self.clone()
    }

    /// Creates a new, empty directory at the provided path
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::create_dir`
    pub fn create(&self) -> std::io::Result<()> {
        fs::create_dir(&self.0)
    }

    /// Recursively create a directory and all of its parent components if they are missing.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::create_dir_all`
    pub fn create_all(&self) -> std::io::Result<()> {
        fs::create_dir_all(&self.0)
    }

    /// Removes an empty directory.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::remove_all`
    pub fn remove(&self) -> std::io::Result<()> {
        fs::remove_dir(&self.0)
    }

    /// Removes a directory at this path, after removing all its contents. Use carefully!
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::remove_dir_all`
    pub fn remove_all(&self) -> std::io::Result<()> {
        fs::remove_dir_all(&self.0)
    }

    /// Returns an iterator over the entries within a directory.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::read_dir`
    #[cfg(feature = "enhanced-errors")]
    pub fn read_dir(&self) -> std::io::Result<impl Iterator<Item = std::io::Result<GenericPath>>> {
        crate::deps::enhanced_errors::read_dir(&self.0)
            .map(|read_dir| read_dir.map(|result| result.and_then(GenericPath::try_from)))
    }

    /// Returns an iterator over the entries within a directory.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::read_dir`
    #[cfg(not(feature = "enhanced-errors"))]
    pub fn read_dir(&self) -> std::io::Result<impl Iterator<Item = std::io::Result<GenericPath>>> {
        std::fs::read_dir(&self.0)
            .map(|read_dir| read_dir.map(|result| result.and_then(GenericPath::try_from)))
    }

    /// Given a path, queries the file system to get information about a file, directory, etc.
    ///
    /// # Errors
    ///
    /// May return any of the same errors as `std::fs::metadata`
    pub fn fs_metadata(&self) -> std::io::Result<std::fs::Metadata> {
        fs::metadata(&self.0)
    }

    #[cfg(feature = "walk")]
    pub fn walk_dir(&self) -> crate::deps::walk::WalkDir {
        crate::deps::walk::WalkDir::new(&self.0)
    }

    #[cfg(feature = "walk")]
    pub fn walk(&self) -> impl Iterator<Item = std::io::Result<GenericPath>> {
        crate::deps::walk::WalkDir::new(&self.0)
            .into_iter()
            .map(|r| r.map_err(|e| e.into()).and_then(GenericPath::try_from))
    }

    #[cfg(feature = "walk")]
    /// Calculate total size in bytes of directory contents
    pub fn size_in_bytes(&self) -> std::io::Result<u64> {
        let mut total = 0u64;
        for entry in crate::deps::walk::WalkDir::new(&self.0) {
            let entry = entry?;
            if entry.file_type().is_file() {
                total += entry.metadata()?.len();
            }
        }
        Ok(total)
    }

    #[cfg(feature = "walk")]
    /// List directory contents with metadata
    pub fn lsl(&self) -> std::io::Result<Vec<(std::path::PathBuf, std::fs::Metadata)>> {
        let mut results = Vec::new();
        for entry in crate::deps::walk::WalkDir::new(&self.0) {
            let entry = entry?;
            let metadata = entry.metadata()?;
            results.push((entry.path().to_path_buf(), metadata));
        }
        Ok(results)
    }

    /// Returns the final component of the path as a String.
    /// For root paths like "/", returns an empty string.
    /// See [`std::path::Path::file_name`] for more details.
    #[must_use]
    pub fn file_name(&self) -> String {
        self.0
            .file_name()
            .map(|name| name.to_string_lossy().to_string())
            .unwrap_or_default()
    }

    /// Renames this directory to a new name, replacing the original item if
    /// `to` already exists.
    ///
    /// Consumes the original instance and returns a new instance with the updated path on success.
    /// On failure, returns both the error and the original instance for recovery.
    /// Parent directories are created automatically if they don't exist.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let dir = GenericDir::new("old_dir");
    /// match dir.rename("new_dir") {
    ///     Ok(renamed_dir) => {
    ///         // Use renamed_dir
    ///     }
    ///     Err((error, original_dir)) => {
    ///         // Handle error, original_dir is still available
    ///     }
    /// }
    /// ```
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::rename`
    pub fn rename(
        self,
        new_path: impl AsRef<std::path::Path>,
    ) -> Result<Self, (std::io::Error, Self)> {
        let new_path = new_path.as_ref();

        // Create parent directories if they don't exist
        if let Some(parent) = new_path.parent() {
            if !parent.exists() {
                if let Err(e) = std::fs::create_dir_all(parent) {
                    return Err((e, self));
                }
            }
        }

        // Attempt the rename
        match fs::rename(&self.0, new_path) {
            Ok(()) => Self::new(new_path).map_err(|e| (e, self)),
            Err(e) => Err((e, self)),
        }
    }

    /// Set directory permissions to 0o700 (read/write/execute for owner only).
    ///
    /// This method is only available on Unix systems.
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let dir = GenericDir::new("secret_dir");
    /// dir.secure()?;
    /// ```
    ///
    /// # Errors
    ///  
    /// May return any of the same errors as `std::fs::set_permissions`
    #[cfg(unix)]
    pub fn secure(&self) -> std::io::Result<()> {
        use std::os::unix::fs::PermissionsExt;
        let permissions = std::fs::Permissions::from_mode(0o700);
        fs::set_permissions(&self.0, permissions)
    }

    /// Get the parent directory as `GenericDir`.
    /// Returns None for directories at the root level.
    #[must_use]
    pub fn parent(&self) -> Option<GenericDir> {
        self.0
            .parent()
            .and_then(|parent_path| GenericDir::new(parent_path).ok())
    }
}

impl AsRef<std::path::Path> for GenericDir {
    fn as_ref(&self) -> &std::path::Path {
        &self.0
    }
}

impl std::fmt::Display for GenericDir {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0.display())
    }
}

impl std::fmt::Debug for GenericDir {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "GenericDir({})", self.0.display())
    }
}

/// Outcome of calling `create_default()` on a file type
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CreateDefaultOutcome {
    /// File was created with default content
    Created,
    /// File already existed, no action taken
    AlreadyExists,
}

/// Error type for `setup()` operations
#[derive(Debug)]
pub enum BuildError {
    /// Error creating a directory
    Directory(std::path::PathBuf, std::io::Error),
    /// Error creating a file with default content
    File(std::path::PathBuf, Box<dyn std::error::Error>),
}

/// Controls whether validation/ensure operations recurse into child paths
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Recursive {
    /// Validate/ensure only this level
    No,
    /// Validate/ensure entire tree
    Yes,
}

/// Validation error for a specific path
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationError {
    /// Path that failed validation
    pub path: std::path::PathBuf,
    /// Error message
    pub message: String,
}

/// Validation warning for a specific path
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationWarning {
    /// Path that generated warning
    pub path: std::path::PathBuf,
    /// Warning message
    pub message: String,
}

/// Result of validation operation
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationReport {
    /// Validation errors
    pub errors: Vec<ValidationError>,
    /// Validation warnings
    pub warnings: Vec<ValidationWarning>,
}

impl ValidationReport {
    /// Create empty validation report
    #[must_use]
    pub fn new() -> Self {
        Self {
            errors: Vec::new(),
            warnings: Vec::new(),
        }
    }

    /// Check if validation passed (no errors)
    #[must_use]
    pub fn is_ok(&self) -> bool {
        self.errors.is_empty()
    }

    /// Merge another report into this one
    pub fn merge(&mut self, other: ValidationReport) {
        self.errors.extend(other.errors);
        self.warnings.extend(other.warnings);
    }
}

impl Default for ValidationReport {
    fn default() -> Self {
        Self::new()
    }
}

/// Result returned by validator functions
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct ValidatorResult {
    /// Validation errors
    pub errors: Vec<String>,
    /// Validation warnings
    pub warnings: Vec<String>,
}