feat: add folder rename detection and harmonize FileSearcher API (#3)

* feat: add folder rename detection and harmonize FileSearcher API

- Folder rename detection now always enabled for ResilientFileSystemMonitor
  - Emits Renamed events when folders containing matching files are renamed
  - Uses high-performance FileSearcher for directory enumeration
  - Critical for correctness - prevents blind spots in file monitoring
  - Essential for certificate rotation scenarios (atomic folder swaps)

- FileSearcher API harmonization with ResilientFileSystemMonitor
  - Added .WithFilter(params string[]) for multiple patterns
  - Added .ClearFilters() to remove all patterns
  - Added .IncludeSubdirectories(int) for depth control
  - Added .IncludeSubdirectories(bool) for simple on/off
  - Fully backward compatible - all existing methods retained

- 139 tests passing, comprehensive coverage for both features

* ci: disable fail-fast in PR validation to see all platform test results

* fix: use HashSet in SubdirectoryDepthTests to handle macOS duplicate events

macOS FileSystemWatcher can fire duplicate events for the same file operation.
Using HashSet instead of List automatically deduplicates by filename, making
tests robust across all platforms while still verifying correct behavior.

Author: windischb

.github/workflows/01-pr-validation.yml

@@ -9,6 +9,7 @@ jobs:
     name: Test on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false  # Continue testing on other platforms even if one fails
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
     permissions:

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2025-11-15
+
+### Added
+- **Folder Rename Detection** for `ResilientFileSystemMonitor`
+  - Automatically emits `Renamed` events when directories containing matching files are renamed
+  - No configuration needed - works out of the box for correctness
+  - Uses high-performance `FileSearcher` for efficient directory enumeration
+  - Respects `MaxDepth` and filter patterns when checking directory contents
+  - Useful for certificate rotation scenarios where entire folders are atomically renamed (e.g., `kid2-staging` → `kid2`)
+  - When a folder containing matching files is renamed, a single `Renamed` event is emitted with the folder path
+- **API Harmonization** for `FileSearcher` (matches `ResilientFileSystemMonitor` API)
+  - `.WithFilter(params string[])` - Search for multiple file patterns (e.g., `"*.cs", "*.csproj"`)
+  - `.ClearFilters()` - Remove all configured patterns
+  - `.IncludeSubdirectories(int maxDepth)` - Control recursion depth (0 = root only, -1 = unlimited)
+  - `.IncludeSubdirectories(bool)` - Enable/disable recursion (true = unlimited, false = root only)
+  - Additive behavior - calling `.WithFilter()` multiple times adds patterns
+  - All existing methods remain unchanged - fully backward compatible
+
 ## [2.1.0] - 2025-11-13
 
 ### Added

README.md

@@ -52,6 +52,19 @@ var monitor = ResilientFileSystemMonitor
     .IncludeSubdirectories(2) // Monitor up to 2 levels deep
     .OnChanged((sender, e) => Console.WriteLine($"Changed: {e.FullPath}"))
     .Build();
+
+// Detect folder renames (certificate rotation scenario):
+var monitor = ResilientFileSystemMonitor
+    .Watch(@"C:\certs")
+    .WithFilter("*.pfx")
+    .IncludeSubdirectories()
+    .OnRenamed((sender, e) => 
+    {
+        // Fires when folders containing .pfx files are renamed
+        // OR when individual .pfx files are renamed
+        Console.WriteLine($"Renamed: {e.OldFullPath} -> {e.FullPath}");
+    })
+    .Build();
 ```
 
 **Key Features:** Auto-recovery, debouncing, depth control, reactive streams, health checks  
@@ -61,19 +74,41 @@ var monitor = ResilientFileSystemMonitor
 
 ### High-Performance File Search
 
-Fast, lazy-evaluated directory traversal:
+Fast, lazy-evaluated directory traversal with fluent API:
 
 ```csharp
 using Cocoar.FileSystem;
 
+// Find all C# files in a project (excluding build folders)
 var codeFiles = FileSearcher
     .Search(@"C:\repos\myproject", "*.cs")
     .Excluding("bin", "obj", "node_modules")
     .WithMaxDepth(5)
     .ToList();
+
+// Multiple file patterns (harmonized with ResilientFileSystemMonitor API)
+var projectFiles = FileSearcher
+    .InDirectory(@"C:\repos\myapp")
+    .WithFilter("*.cs", "*.csproj", "*.json")
+    .IncludeSubdirectories(2)  // Search 2 levels deep
+    .ToList();
+
+// Lazy evaluation with LINQ
+var largeFiles = FileSearcher
+    .InDirectory(@"C:\data")
+    .WithPattern("*.log")
+    .Recursively()
+    .Where(file => new FileInfo(file).Length > 1_000_000)
+    .Take(10);
+
+// Search only current directory (no recursion)
+var configs = FileSearcher
+    .Search(@"C:\app", "*.json")
+    .WithMaxDepth(0)  // Current directory only
+    .ToArray();
 ```
 
-**Key Features:** Lazy evaluation, depth limits, exclusion patterns, LINQ support  
+**Key Features:** Lazy evaluation, depth limits, exclusion patterns, LINQ support, efficient for large directories  
 📖 **[Examples](docs/examples.md#high-performance-file-search)**
 
 ---

docs/examples.md

@@ -470,3 +470,195 @@ public class CredentialReader
     }
 }
 ```
+
+## High-Performance File Search
+
+### Finding Code Files with Exclusions
+
+Search for source files while excluding build and dependency folders:
+
+```csharp
+using Cocoar.FileSystem;
+
+public class CodeAnalyzer
+{
+    public List<string> FindSourceFiles(string projectRoot)
+    {
+        // Find all C# files, excluding common build/dependency folders
+        var sourceFiles = FileSearcher
+            .Search(projectRoot, "*.cs")
+            .Excluding("bin", "obj", "packages", "node_modules", ".git")
+            .Recursively()
+            .ToList();
+        
+        Console.WriteLine($"Found {sourceFiles.Count} C# files");
+        return sourceFiles;
+    }
+}
+```
+
+### Lazy Evaluation with LINQ
+
+Use LINQ to process files as they're discovered without loading all results into memory:
+
+```csharp
+using Cocoar.FileSystem;
+
+public class LargeFileFinder
+{
+    public void FindAndProcessLargeFiles(string searchPath)
+    {
+        // Lazy evaluation - files are found and processed one at a time
+        var largeLogFiles = FileSearcher
+            .InDirectory(searchPath)
+            .WithPattern("*.log")
+            .WithMaxDepth(3)
+            .Where(file => new FileInfo(file).Length > 10_000_000)  // > 10 MB
+            .OrderByDescending(file => new FileInfo(file).Length)
+            .Take(10);  // Only get top 10
+        
+        foreach (var file in largeLogFiles)
+        {
+            Console.WriteLine($"Large file: {file} ({new FileInfo(file).Length:N0} bytes)");
+            ArchiveFile(file);
+        }
+    }
+    
+    private void ArchiveFile(string filePath) { /* ... */ }
+}
+```
+
+### Depth-Limited Search
+
+Control how deep the search recurses into subdirectories:
+
+```csharp
+using Cocoar.FileSystem;
+
+public class ConfigurationScanner
+{
+    public void ScanConfigs(string appRoot)
+    {
+        // Only search current directory (no subdirectories)
+        var rootConfigs = FileSearcher
+            .Search(appRoot, "*.json")
+            .WithMaxDepth(0)  // 0 = current directory only
+            .ToList();
+        
+        // Search up to 2 levels deep
+        var nestedConfigs = FileSearcher
+            .Search(appRoot, "*.json")
+            .WithMaxDepth(2)  // appRoot + 2 levels of subdirectories
+            .Excluding("node_modules")
+            .ToList();
+        
+        // Unlimited depth (all subdirectories)
+        var allConfigs = FileSearcher
+            .Search(appRoot, "*.json")
+            .Recursively()  // Same as .WithMaxDepth(null)
+            .ToList();
+        
+        Console.WriteLine($"Root: {rootConfigs.Count}, Nested: {nestedConfigs.Count}, All: {allConfigs.Count}");
+    }
+}
+```
+
+### Multiple Search Operations
+
+Combine multiple searches efficiently:
+
+```csharp
+using Cocoar.FileSystem;
+
+public class AssetScanner
+{
+    public Dictionary<string, List<string>> CategorizeAssets(string projectPath)
+    {
+        var result = new Dictionary<string, List<string>>();
+        
+        // Images
+        result["images"] = FileSearcher
+            .InDirectory(Path.Combine(projectPath, "assets"))
+            .WithPattern("*.png")
+            .Recursively()
+            .ToList();
+        
+        // Stylesheets
+        result["styles"] = FileSearcher
+            .InDirectory(Path.Combine(projectPath, "styles"))
+            .WithPattern("*.css")
+            .Excluding("dist", "build")
+            .ToList();
+        
+        // Scripts
+        result["scripts"] = FileSearcher
+            .InDirectory(Path.Combine(projectPath, "src"))
+            .WithPattern("*.js")
+            .WithMaxDepth(5)
+            .ToList();
+        
+        return result;
+    }
+}
+```
+
+### Finding Recent Files
+
+Combine FileSearcher with LINQ and FileInfo for advanced filtering:
+
+```csharp
+using Cocoar.FileSystem;
+
+public class RecentFilesFinder
+{
+    public List<string> FindRecentlyModifiedFiles(string searchPath, TimeSpan maxAge)
+    {
+        var cutoffTime = DateTime.Now - maxAge;
+        
+        // Lazy evaluation - only checks files that match the pattern
+        var recentFiles = FileSearcher
+            .InDirectory(searchPath)
+            .WithPattern("*.*")
+            .Recursively()
+            .Where(file => File.GetLastWriteTime(file) > cutoffTime)
+            .OrderByDescending(file => File.GetLastWriteTime(file))
+            .ToList();
+        
+        Console.WriteLine($"Found {recentFiles.Count} files modified in the last {maxAge.TotalHours} hours");
+        return recentFiles;
+    }
+}
+```
+
+### Performance: Lazy vs Eager Evaluation
+
+```csharp
+using Cocoar.FileSystem;
+
+public class PerformanceExample
+{
+    public void LazyEvaluation()
+    {
+        // Lazy - no I/O happens until you iterate
+        var query = FileSearcher
+            .Search(@"C:\Windows", "*.dll")
+            .Recursively();
+        
+        // I/O happens here, but stops after finding 5 files
+        var firstFive = query.Take(5).ToList();
+        
+        Console.WriteLine("Only enumerated files until we found 5 matches");
+    }
+    
+    public void EagerEvaluation()
+    {
+        // Eager - ToList() forces full enumeration immediately
+        var allFiles = FileSearcher
+            .Search(@"C:\Program Files", "*.exe")
+            .Recursively()
+            .ToList();  // All files loaded into memory at once
+        
+        Console.WriteLine($"Loaded all {allFiles.Count} files into memory");
+    }
+}
+```