mago_database/
exclusion.rs

1//! File and directory exclusion patterns for database loading.
2//!
3//! This module provides the [`Exclusion`] enum for defining rules that determine
4//! which files and directories should be excluded when scanning a project with
5//! [`DatabaseLoader`](crate::loader::DatabaseLoader).
6//!
7//! Exclusions support two modes:
8//!
9//! - **Exact Paths**: Exclude specific files or directories by their filesystem path
10//! - **Glob Patterns**: Exclude multiple paths matching a pattern (e.g., `*.tmp`, `**/test/**`)
11//!
12//! # Use Cases
13//!
14//! - Exclude build artifacts and cache directories (`target/`, `.cache/`)
15//! - Exclude version control metadata (`.git/`, `.svn/`)
16//! - Exclude test files or fixtures (`tests/fixtures/`)
17//! - Exclude temporary files (`*.swp`, `*.tmp`)
18
19use std::borrow::Cow;
20use std::path::Path;
21
22/// A rule for excluding files or directories from filesystem scans.
23///
24/// This enum represents two types of exclusion rules that can be used when loading
25/// a database to filter out unwanted files. Exclusions are evaluated during the
26/// scan performed by [`DatabaseLoader`](crate::loader::DatabaseLoader).
27///
28/// # Lifetime
29///
30/// The `'a` lifetime parameter allows the exclusion to borrow paths and patterns
31/// from configuration or other long-lived data structures, avoiding unnecessary
32/// allocations during database construction.
33///
34/// # Variants
35///
36/// ## Path Exclusion
37///
38/// Excludes an exact filesystem path, which can be either a file or directory.
39/// When a directory is excluded, all files and subdirectories within it are also
40/// excluded.
41///
42/// Paths can be absolute or relative to the workspace. Relative paths are
43/// canonicalized during loader construction.
44///
45/// ## Pattern Exclusion
46///
47/// Excludes paths matching a glob pattern. Glob patterns support wildcards and
48/// are matched against the full path of each discovered file.
49///
50/// Common pattern syntax:
51/// - `*` matches any characters except path separators
52/// - `**` matches any characters including path separators (recursive)
53/// - `?` matches a single character
54/// - `[abc]` matches one character from the set
55///
56/// # Ordering
57///
58/// Exclusions are ordered first by variant (Path before Pattern), then by the
59/// value within the variant. This enables efficient deduplication and set operations.
60#[derive(Debug, Clone, Hash, Eq, PartialEq, PartialOrd, Ord, serde::Serialize, serde::Deserialize)]
61pub enum Exclusion<'a> {
62    /// Exclude a specific file or directory by its exact path.
63    ///
64    /// The path can be absolute or relative to the workspace directory.
65    /// If a directory is specified, all contents within it are recursively excluded.
66    ///
67    /// Uses `Cow` to allow borrowing paths from configuration while supporting
68    /// owned paths when canonicalization is required.
69    Path(Cow<'a, Path>),
70
71    /// Exclude files and directories matching a glob pattern.
72    ///
73    /// The pattern is evaluated against the full path of each file discovered
74    /// during the scan. Supports standard glob syntax including wildcards,
75    /// character classes, and recursive matchers.
76    ///
77    /// Uses `Cow` to avoid allocating when borrowing patterns from configuration.
78    Pattern(Cow<'a, str>),
79}
mago_database/exclusion.rs

mago_database/
exclusion.rs
