vtcode_commons/
walk.rs

1#![expect(
2    unused_results,
3    reason = "WalkBuilder configuration uses fluent setters only for their mutation side effects."
4)]
5
6//! Shared directory walker helpers built on the `ignore` crate.
7//!
8//! All file traversal in vtcode should go through these builders so that
9//! `.gitignore`, `.ignore`, `.git/exclude`, and the centralized exclusion
10//! constants are applied consistently.
11
12use ignore::{DirEntry, WalkBuilder};
13use std::path::Path;
14
15use crate::exclusions::{DEFAULT_EXCLUDED_DIRS, VTCODE_IGNORE_FILE};
16
17/// Build a multi-threaded [`WalkBuilder`] with sensible defaults.
18///
19/// - Respects `.gitignore`, `.ignore`, `.git/exclude`, and parent ignore files
20/// - Does not follow symlinks
21/// - Uses the `ignore` crate's default thread pool
22///
23/// Callers that need to prune additional directories should use
24/// [`filter_entry`](WalkBuilder::filter_entry) with [`is_excluded_dir`].
25pub fn build_default_walker(root: &Path) -> WalkBuilder {
26    let mut builder = WalkBuilder::new(root);
27    apply_defaults(&mut builder);
28    builder
29}
30
31/// Build a single-threaded [`WalkBuilder`] with the same defaults as
32/// [`build_default_walker`].
33///
34/// Use this in synchronous contexts where spawning the `ignore` crate's
35/// thread pool would be wasteful (e.g., inside `spawn_blocking` closures
36/// that already run on a dedicated thread).
37pub fn build_walker_single_threaded(root: &Path) -> WalkBuilder {
38    let mut builder = WalkBuilder::new(root);
39    builder.threads(1);
40    apply_defaults(&mut builder);
41    builder
42}
43
44/// Apply standard walker defaults to an existing [`WalkBuilder`].
45///
46/// Sets gitignore support, hidden file visibility, and symlink policy.
47/// Callers that need additional customization (e.g., parallel walkers,
48/// symlink following) can call this then override specific settings.
49pub fn apply_defaults(builder: &mut WalkBuilder) {
50    // Respect all standard ignore-file mechanisms.
51    builder.git_ignore(true);
52    builder.git_global(true);
53    builder.git_exclude(true);
54    builder.ignore(true);
55    builder.parents(true);
56
57    // `.vtcodegitignore` mirrors `.gitignore` but is scoped to VT Code's own
58    // file operations. It has higher precedence than the standard ignore files
59    // (including its `!` re-include rules), so a user can whitelist a path that
60    // `.gitignore` prunes.
61    builder.add_custom_ignore_filename(VTCODE_IGNORE_FILE);
62
63    // Do not follow symlinks by default.
64    builder.follow_links(false);
65
66    // Do not skip hidden files by default.  The `ignore` crate skips them
67    // by default, but the previous traversal code did not.  Callers that
68    // want to hide dotfiles should filter them explicitly.
69    builder.hidden(false);
70}
71
72/// Returns `true` if `entry` is a directory whose name appears in
73/// [`DEFAULT_EXCLUDED_DIRS`].
74///
75/// Intended for use inside [`WalkBuilder::filter_entry`] closures:
76///
77/// ```ignore
78/// builder.filter_entry(|entry| !vtcode_commons::walk::is_excluded_dir(entry));
79/// ```
80pub fn is_excluded_dir(entry: &DirEntry) -> bool {
81    if !entry.file_type().is_some_and(|ft| ft.is_dir()) {
82        return false;
83    }
84
85    entry
86        .file_name()
87        .to_str()
88        .is_some_and(|name| DEFAULT_EXCLUDED_DIRS.contains(&name))
89}
90
91#[cfg(test)]
92mod tests {
93    use std::fs;
94
95    use tempfile::tempdir;
96
97    use super::*;
98
99    fn collected_paths(root: &Path) -> Vec<String> {
100        let walker = build_default_walker(root).build();
101        let mut paths = walker
102            .filter_map(Result::ok)
103            .filter(|entry| entry.path() != root)
104            .map(|entry| {
105                entry
106                    .path()
107                    .strip_prefix(root)
108                    .unwrap_or_else(|_| entry.path())
109                    .to_string_lossy()
110                    .into_owned()
111            })
112            .collect::<Vec<_>>();
113        paths.sort();
114        paths
115    }
116
117    #[test]
118    fn default_walker_respects_vtcodegitignore() {
119        let temp = tempdir().expect("tempdir");
120        let root = temp.path();
121        fs::write(root.join(".vtcodegitignore"), "ignored_dir/\nignored_file.txt\n").expect("write ignore file");
122        fs::create_dir(root.join("ignored_dir")).expect("mkdir ignored_dir");
123        fs::write(root.join("ignored_dir/secret.rs"), "x").expect("write secret");
124        fs::write(root.join("ignored_file.txt"), "x").expect("write ignored file");
125        fs::write(root.join("kept.rs"), "x").expect("write kept file");
126
127        let paths = collected_paths(root);
128
129        assert!(paths.contains(&"kept.rs".to_owned()), "kept file should remain: {paths:?}");
130        assert!(!paths.iter().any(|p| p.contains("ignored_file.txt")), "ignored file leaked: {paths:?}");
131        assert!(!paths.iter().any(|p| p.contains("ignored_dir")), "ignored dir leaked: {paths:?}");
132    }
133
134    #[test]
135    fn default_walker_vtcodegitignore_negation_reincludes() {
136        let temp = tempdir().expect("tempdir");
137        let root = temp.path();
138        // Exclude every log, then re-include one. The custom-ignore file's
139        // negation must win over its own earlier pattern (mirrors the repo's
140        // `!README.md` style allow-list).
141        fs::write(root.join(".vtcodegitignore"), "*.log\n!important.log\n").expect("write ignore file");
142        fs::write(root.join("important.log"), "x").expect("write important log");
143        fs::write(root.join("noise.log"), "x").expect("write noise log");
144        fs::write(root.join("kept.rs"), "x").expect("write kept file");
145
146        let paths = collected_paths(root);
147
148        assert!(paths.contains(&"important.log".to_owned()), "negated file should be re-included: {paths:?}");
149        assert!(!paths.iter().any(|p| p.ends_with("noise.log")), "non-negated file leaked: {paths:?}");
150        assert!(paths.contains(&"kept.rs".to_owned()), "unrelated file should remain: {paths:?}");
151    }
152}
vtcode_commons/walk.rs

vtcode_commons/
walk.rs
