cuenv_ignore/

lib.rs

//! Generate ignore files (.gitignore, .dockerignore, etc.)
//!
//! This crate provides a builder-based API for generating tool-specific ignore files
//! from a declarative configuration.
//!
//! # Example
//!
//! ```rust,no_run
//! use cuenv_ignore::{IgnoreFile, IgnoreFiles};
//!
//! let result = IgnoreFiles::builder()
//!     .directory(".")
//!     .file(IgnoreFile::new("git")
//!         .pattern("node_modules/")
//!         .pattern(".env"))
//!     .file(IgnoreFile::new("docker")
//!         .pattern("target/"))
//!     .generate()?;
//!
//! for file in &result.files {
//!     println!("{}: {}", file.status, file.filename);
//! }
//! # Ok::<(), cuenv_ignore::Error>(())
//! ```
//!
//! # Features
//!
//! - `serde`: Enable serde serialization/deserialization for configuration types

#![warn(missing_docs)]

use std::path::{Path, PathBuf};

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

/// A single ignore file configuration.
///
/// # Example
///
/// ```rust
/// use cuenv_ignore::IgnoreFile;
///
/// let file = IgnoreFile::new("git")
///     .pattern("node_modules/")
///     .pattern(".env")
///     .header("Generated by my-tool");
///
/// assert_eq!(file.output_filename(), ".gitignore");
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct IgnoreFile {
    tool: String,
    patterns: Vec<String>,
    filename: Option<String>,
    header: Option<String>,
}

impl IgnoreFile {
    /// Create a new ignore file configuration for a tool.
    ///
    /// The tool name is used to generate the default filename as `.{tool}ignore`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use cuenv_ignore::IgnoreFile;
    ///
    /// let file = IgnoreFile::new("git");
    /// assert_eq!(file.output_filename(), ".gitignore");
    ///
    /// let file = IgnoreFile::new("docker");
    /// assert_eq!(file.output_filename(), ".dockerignore");
    /// ```
    #[must_use]
    pub fn new(tool: impl Into<String>) -> Self {
        Self {
            tool: tool.into(),
            patterns: Vec::new(),
            filename: None,
            header: None,
        }
    }

    /// Add a single pattern to the ignore file.
    #[must_use]
    pub fn pattern(mut self, pattern: impl Into<String>) -> Self {
        self.patterns.push(pattern.into());
        self
    }

    /// Add multiple patterns to the ignore file.
    #[must_use]
    pub fn patterns(mut self, patterns: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.patterns.extend(patterns.into_iter().map(Into::into));
        self
    }

    /// Set a custom filename for the ignore file.
    ///
    /// If not set, defaults to `.{tool}ignore`.
    #[must_use]
    pub fn filename(mut self, filename: impl Into<String>) -> Self {
        self.filename = Some(filename.into());
        self
    }

    /// Optionally set a custom filename for the ignore file.
    #[must_use]
    pub fn filename_opt(mut self, filename: Option<impl Into<String>>) -> Self {
        self.filename = filename.map(Into::into);
        self
    }

    /// Set a header comment for the ignore file.
    ///
    /// The header will be added at the top of the file with `#` prefixes.
    /// Each line of the header will be prefixed with `# `.
    #[must_use]
    pub fn header(mut self, header: impl Into<String>) -> Self {
        self.header = Some(header.into());
        self
    }

    /// Get the output filename for this ignore file.
    ///
    /// Returns the custom filename if set, otherwise `.{tool}ignore`.
    #[must_use]
    pub fn output_filename(&self) -> String {
        self.filename
            .clone()
            .unwrap_or_else(|| format!(".{}ignore", self.tool))
    }

    /// Get the tool name.
    #[must_use]
    pub fn tool(&self) -> &str {
        &self.tool
    }

    /// Get the patterns.
    #[must_use]
    pub fn patterns_list(&self) -> &[String] {
        &self.patterns
    }

    /// Generate the file content.
    ///
    /// # Example
    ///
    /// ```rust
    /// use cuenv_ignore::IgnoreFile;
    ///
    /// let file = IgnoreFile::new("git")
    ///     .pattern("node_modules/")
    ///     .header("My header");
    ///
    /// let content = file.generate();
    /// assert!(content.contains("# My header"));
    /// assert!(content.contains("node_modules/"));
    /// ```
    #[must_use]
    pub fn generate(&self) -> String {
        let mut lines: Vec<String> = self
            .header
            .iter()
            .flat_map(|header| {
                header
                    .lines()
                    .map(|line| format!("# {line}"))
                    .chain(std::iter::once(String::new()))
            })
            .collect();

        // Add patterns
        lines.extend(self.patterns.iter().cloned());

        format!("{}\n", lines.join("\n"))
    }
}

/// Entry point for building and generating ignore files.
pub struct IgnoreFiles;

impl IgnoreFiles {
    /// Create a new builder for generating ignore files.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use cuenv_ignore::{IgnoreFile, IgnoreFiles};
    ///
    /// let result = IgnoreFiles::builder()
    ///     .directory(".")
    ///     .file(IgnoreFile::new("git").pattern("*.log"))
    ///     .generate()?;
    /// # Ok::<(), cuenv_ignore::Error>(())
    /// ```
    #[must_use]
    pub fn builder() -> IgnoreFilesBuilder {
        IgnoreFilesBuilder::default()
    }
}

/// Builder for generating multiple ignore files.
///
/// # Example
///
/// ```rust,no_run
/// use cuenv_ignore::{IgnoreFile, IgnoreFiles};
///
/// let result = IgnoreFiles::builder()
///     .directory("/path/to/project")
///     .require_git_repo(true)
///     .dry_run(false)
///     .file(IgnoreFile::new("git")
///         .pattern("node_modules/")
///         .pattern(".env"))
///     .file(IgnoreFile::new("docker")
///         .pattern("target/"))
///     .generate()?;
/// # Ok::<(), cuenv_ignore::Error>(())
/// ```
#[derive(Debug, Default)]
pub struct IgnoreFilesBuilder {
    directory: Option<PathBuf>,
    files: Vec<IgnoreFile>,
    require_git_repo: bool,
    dry_run: bool,
}

impl IgnoreFilesBuilder {
    /// Set the directory where ignore files will be generated.
    ///
    /// Defaults to the current directory if not set.
    #[must_use]
    pub fn directory(mut self, dir: impl AsRef<Path>) -> Self {
        self.directory = Some(dir.as_ref().to_path_buf());
        self
    }

    /// Add a single ignore file configuration.
    #[must_use]
    pub fn file(mut self, file: IgnoreFile) -> Self {
        self.files.push(file);
        self
    }

    /// Add multiple ignore file configurations.
    #[must_use]
    pub fn files(mut self, files: impl IntoIterator<Item = IgnoreFile>) -> Self {
        self.files.extend(files);
        self
    }

    /// Require that the directory is within a Git repository.
    ///
    /// Defaults to `false`. When `true`, returns an error if the directory
    /// is not within a Git repository.
    #[must_use]
    pub const fn require_git_repo(mut self, require: bool) -> Self {
        self.require_git_repo = require;
        self
    }

    /// Enable dry-run mode.
    ///
    /// When `true`, no files will be written. The result will indicate
    /// what would happen with `WouldCreate` and `WouldUpdate` statuses.
    #[must_use]
    pub const fn dry_run(mut self, dry_run: bool) -> Self {
        self.dry_run = dry_run;
        self
    }

    /// Generate the ignore files.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - `require_git_repo` is true and the directory is not within a Git repository
    /// - A tool name contains invalid characters (path separators)
    /// - File I/O fails
    pub fn generate(self) -> Result<SyncResult> {
        let dir = self.directory.unwrap_or_else(|| PathBuf::from("."));

        tracing::info!("Starting ignore file generation");

        if self.require_git_repo {
            verify_git_repository(&dir)?;
        }

        let mut sorted_files = self.files;
        sorted_files.sort_by(|a, b| a.tool.cmp(&b.tool));

        let dry_run = self.dry_run;
        let results = sorted_files
            .iter()
            .filter(|f| !f.patterns.is_empty())
            .map(|file| process_ignore_file(&dir, file, dry_run))
            .collect::<Result<Vec<_>>>()?;

        Ok(SyncResult { files: results })
    }
}

/// Process a single ignore file and return its result.
fn process_ignore_file(dir: &Path, file: &IgnoreFile, dry_run: bool) -> Result<FileResult> {
    validate_tool_name(&file.tool)?;

    let filename = file.output_filename();
    validate_filename(&filename)?;

    let filepath = dir.join(&filename);
    let content = file.generate();
    let pattern_count = file.patterns.len();

    let status = determine_file_status(&filepath, &content, dry_run)?;

    tracing::info!(
        filename = %filename,
        status = %status,
        patterns = pattern_count,
        "Processed ignore file"
    );

    Ok(FileResult {
        filename,
        status,
        pattern_count,
    })
}

/// Determine the status of an ignore file based on `dry_run` mode and existing content.
fn determine_file_status(filepath: &Path, content: &str, dry_run: bool) -> Result<FileStatus> {
    if dry_run {
        Ok(determine_dry_run_status(filepath, content)?)
    } else {
        write_ignore_file(filepath, content)
    }
}

/// Determine what would happen to a file in dry-run mode.
fn determine_dry_run_status(filepath: &Path, content: &str) -> Result<FileStatus> {
    if !filepath.exists() {
        return Ok(FileStatus::WouldCreate);
    }
    let existing = std::fs::read_to_string(filepath)?;
    Ok(if existing == content {
        FileStatus::Unchanged
    } else {
        FileStatus::WouldUpdate
    })
}

// ============================================================================
// Result types
// ============================================================================

/// Result of generating ignore files.
#[derive(Debug)]
pub struct SyncResult {
    /// Results for each file that was processed.
    pub files: Vec<FileResult>,
}

/// Result for a single ignore file.
#[derive(Debug)]
pub struct FileResult {
    /// The filename that was generated (e.g., ".gitignore").
    pub filename: String,
    /// The status of the file operation.
    pub status: FileStatus,
    /// Number of patterns in the file.
    pub pattern_count: usize,
}

/// Status of a file operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FileStatus {
    /// File was newly created.
    Created,
    /// File existed and was updated with new content.
    Updated,
    /// File existed and content was unchanged.
    Unchanged,
    /// Would be created (dry-run mode).
    WouldCreate,
    /// Would be updated (dry-run mode).
    WouldUpdate,
}

impl std::fmt::Display for FileStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Created => write!(f, "Created"),
            Self::Updated => write!(f, "Updated"),
            Self::Unchanged => write!(f, "Unchanged"),
            Self::WouldCreate => write!(f, "Would create"),
            Self::WouldUpdate => write!(f, "Would update"),
        }
    }
}

// ============================================================================
// Error types
// ============================================================================

/// Errors that can occur during ignore file generation.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// Invalid tool name (contains path separators or is empty).
    #[error("Invalid tool name '{name}': {reason}")]
    InvalidToolName {
        /// The invalid tool name.
        name: String,
        /// Reason why it's invalid.
        reason: String,
    },

    /// Not inside a Git repository.
    #[error("Must be run within a Git repository")]
    NotInGitRepo,

    /// Cannot operate in a bare repository.
    #[error("Cannot operate in a bare Git repository")]
    BareRepository,

    /// Target directory is outside the Git repository.
    #[error("Target directory must be within the Git repository")]
    OutsideGitRepo,

    /// IO error during file operations.
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),
}

/// Result type for ignore operations.
pub type Result<T> = std::result::Result<T, Error>;

// ============================================================================
// Internal helpers
// ============================================================================

/// Verify that the directory is within a Git repository.
fn verify_git_repository(dir: &Path) -> Result<()> {
    let repo = gix::discover(dir).map_err(|e| {
        tracing::debug!("Git discovery failed: {}", e);
        Error::NotInGitRepo
    })?;

    let git_root = repo.workdir().ok_or(Error::BareRepository)?;

    // Canonicalize paths for comparison
    let canonical_dir = std::fs::canonicalize(dir)?;
    let canonical_git = std::fs::canonicalize(git_root)?;

    if !canonical_dir.starts_with(&canonical_git) {
        return Err(Error::OutsideGitRepo);
    }

    tracing::debug!(
        git_root = %canonical_git.display(),
        target_dir = %canonical_dir.display(),
        "Verified directory is within Git repository"
    );

    Ok(())
}

/// Validate that a tool name doesn't contain path separators.
fn validate_tool_name(tool: &str) -> Result<()> {
    if tool.is_empty() {
        return Err(Error::InvalidToolName {
            name: tool.to_string(),
            reason: "tool name cannot be empty".to_string(),
        });
    }

    if tool.contains('/') || tool.contains('\\') {
        return Err(Error::InvalidToolName {
            name: tool.to_string(),
            reason: "tool name cannot contain path separators".to_string(),
        });
    }

    if tool.contains("..") {
        return Err(Error::InvalidToolName {
            name: tool.to_string(),
            reason: "tool name cannot contain parent directory references".to_string(),
        });
    }

    Ok(())
}

/// Validate that a filename doesn't contain path separators.
fn validate_filename(filename: &str) -> Result<()> {
    if filename.contains('/') || filename.contains('\\') {
        return Err(Error::InvalidToolName {
            name: filename.to_string(),
            reason: "filename cannot contain path separators".to_string(),
        });
    }

    if filename.contains("..") {
        return Err(Error::InvalidToolName {
            name: filename.to_string(),
            reason: "filename cannot contain parent directory references".to_string(),
        });
    }

    Ok(())
}

/// Write an ignore file and return the status.
fn write_ignore_file(filepath: &Path, content: &str) -> Result<FileStatus> {
    let status = if filepath.exists() {
        let existing = std::fs::read_to_string(filepath)?;
        if existing == content {
            return Ok(FileStatus::Unchanged);
        }
        FileStatus::Updated
    } else {
        FileStatus::Created
    };

    std::fs::write(filepath, content)?;
    Ok(status)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_ignore_file_new() {
        let file = IgnoreFile::new("git");
        assert_eq!(file.tool(), "git");
        assert!(file.patterns_list().is_empty());
        assert_eq!(file.output_filename(), ".gitignore");
    }

    #[test]
    fn test_ignore_file_builder() {
        let file = IgnoreFile::new("docker")
            .pattern("node_modules/")
            .pattern(".env")
            .filename(".mydockerignore")
            .header("My header");

        assert_eq!(file.tool(), "docker");
        assert_eq!(file.patterns_list(), &["node_modules/", ".env"]);
        assert_eq!(file.output_filename(), ".mydockerignore");
    }

    #[test]
    fn test_ignore_file_patterns() {
        let file = IgnoreFile::new("git").patterns(["a", "b", "c"]);
        assert_eq!(file.patterns_list(), &["a", "b", "c"]);
    }

    #[test]
    fn test_ignore_file_generate_no_header() {
        let file = IgnoreFile::new("git")
            .pattern("node_modules/")
            .pattern(".env");

        let content = file.generate();
        assert_eq!(content, "node_modules/\n.env\n");
    }

    #[test]
    fn test_ignore_file_generate_with_header() {
        let file = IgnoreFile::new("git")
            .pattern("node_modules/")
            .header("Generated by my-tool\nDo not edit");

        let content = file.generate();
        assert!(content.starts_with("# Generated by my-tool\n# Do not edit\n\n"));
        assert!(content.contains("node_modules/"));
    }

    #[test]
    fn test_output_filename_default() {
        assert_eq!(IgnoreFile::new("git").output_filename(), ".gitignore");
        assert_eq!(IgnoreFile::new("docker").output_filename(), ".dockerignore");
        assert_eq!(IgnoreFile::new("npm").output_filename(), ".npmignore");
    }

    #[test]
    fn test_output_filename_custom() {
        let file = IgnoreFile::new("git").filename(".my-gitignore");
        assert_eq!(file.output_filename(), ".my-gitignore");
    }

    #[test]
    fn test_validate_tool_name_valid() {
        assert!(validate_tool_name("git").is_ok());
        assert!(validate_tool_name("docker").is_ok());
        assert!(validate_tool_name("my-custom-tool").is_ok());
        assert!(validate_tool_name("tool_with_underscore").is_ok());
    }

    #[test]
    fn test_validate_tool_name_invalid() {
        assert!(validate_tool_name("").is_err());
        assert!(validate_tool_name("../etc").is_err());
        assert!(validate_tool_name("foo/bar").is_err());
        assert!(validate_tool_name("foo\\bar").is_err());
        assert!(validate_tool_name("..").is_err());
        assert!(validate_tool_name("foo..bar").is_err());
    }

    #[test]
    fn test_file_status_display() {
        assert_eq!(FileStatus::Created.to_string(), "Created");
        assert_eq!(FileStatus::Updated.to_string(), "Updated");
        assert_eq!(FileStatus::Unchanged.to_string(), "Unchanged");
        assert_eq!(FileStatus::WouldCreate.to_string(), "Would create");
        assert_eq!(FileStatus::WouldUpdate.to_string(), "Would update");
    }

    #[test]
    fn test_ignore_file_clone() {
        let file = IgnoreFile::new("git")
            .pattern("node_modules/")
            .header("Test");
        let cloned = file.clone();
        assert_eq!(file, cloned);
    }

    #[test]
    fn test_ignore_file_debug() {
        let file = IgnoreFile::new("git");
        let debug_str = format!("{file:?}");
        assert!(debug_str.contains("IgnoreFile"));
        assert!(debug_str.contains("git"));
    }

    #[test]
    fn test_ignore_file_equality() {
        let file1 = IgnoreFile::new("git").pattern("*.log");
        let file2 = IgnoreFile::new("git").pattern("*.log");
        let file3 = IgnoreFile::new("docker").pattern("*.log");

        assert_eq!(file1, file2);
        assert_ne!(file1, file3);
    }

    #[test]
    fn test_ignore_file_filename_opt_some() {
        let file = IgnoreFile::new("git").filename_opt(Some(".custom-ignore"));
        assert_eq!(file.output_filename(), ".custom-ignore");
    }

    #[test]
    fn test_ignore_file_filename_opt_none() {
        let file: IgnoreFile = IgnoreFile::new("git").filename_opt(None::<String>);
        assert_eq!(file.output_filename(), ".gitignore");
    }

    #[test]
    fn test_ignore_files_builder_default() {
        let builder = IgnoreFiles::builder();
        let debug_str = format!("{builder:?}");
        assert!(debug_str.contains("IgnoreFilesBuilder"));
    }

    #[test]
    fn test_validate_filename_valid() {
        assert!(validate_filename(".gitignore").is_ok());
        assert!(validate_filename(".my-custom-ignore").is_ok());
    }

    #[test]
    fn test_validate_filename_invalid() {
        assert!(validate_filename("path/to/file").is_err());
        assert!(validate_filename("..\\file").is_err());
        assert!(validate_filename("file..test").is_err());
    }

    #[test]
    fn test_sync_result_debug() {
        let result = SyncResult {
            files: vec![FileResult {
                filename: ".gitignore".to_string(),
                status: FileStatus::Created,
                pattern_count: 5,
            }],
        };
        let debug_str = format!("{result:?}");
        assert!(debug_str.contains("SyncResult"));
        assert!(debug_str.contains("gitignore"));
    }

    #[test]
    fn test_file_result_debug() {
        let result = FileResult {
            filename: ".gitignore".to_string(),
            status: FileStatus::Updated,
            pattern_count: 3,
        };
        let debug_str = format!("{result:?}");
        assert!(debug_str.contains("FileResult"));
        assert!(debug_str.contains("Updated"));
    }

    #[test]
    fn test_file_status_eq() {
        assert_eq!(FileStatus::Created, FileStatus::Created);
        assert_eq!(FileStatus::WouldCreate, FileStatus::WouldCreate);
        assert_ne!(FileStatus::Created, FileStatus::Updated);
    }

    #[test]
    fn test_file_status_clone() {
        let status = FileStatus::WouldUpdate;
        let cloned = status;
        assert_eq!(status, cloned);
    }

    #[test]
    fn test_error_display() {
        let err = Error::InvalidToolName {
            name: "foo/bar".to_string(),
            reason: "cannot contain path separators".to_string(),
        };
        let display = format!("{err}");
        assert!(display.contains("foo/bar"));
        assert!(display.contains("path separators"));
    }

    #[test]
    fn test_error_not_in_git_repo_display() {
        let err = Error::NotInGitRepo;
        let display = format!("{err}");
        assert!(display.contains("Git repository"));
    }

    #[test]
    fn test_error_bare_repository_display() {
        let err = Error::BareRepository;
        let display = format!("{err}");
        assert!(display.contains("bare Git repository"));
    }

    #[test]
    fn test_error_outside_git_repo_display() {
        let err = Error::OutsideGitRepo;
        let display = format!("{err}");
        assert!(display.contains("within the Git repository"));
    }

    #[test]
    fn test_ignore_file_generate_empty() {
        let file = IgnoreFile::new("git");
        let content = file.generate();
        assert_eq!(content, "\n");
    }

    #[test]
    fn test_ignore_files_builder_files() {
        let files = vec![
            IgnoreFile::new("git").pattern("*.log"),
            IgnoreFile::new("docker").pattern("target/"),
        ];
        let _builder = IgnoreFiles::builder().files(files);
    }
}