Merge pull request #40 from rameel/fs-glob-optimization

Optimize glob pattern matching with provider-specific overrides

- New overloads in base `VirtualFileSystem` for efficient glob-based file/directory enumeration
- Support for provider-specific pattern matching optimizations
- Updated tests covering new and existing behavior
- `GlobbingFileSystem`: Match directory paths against glob patterns correctly

Author: rameel

src/Ramstack.FileSystem.Abstractions/Null/NotFoundDirectory.cs

@@ -5,7 +5,7 @@ namespace Ramstack.FileSystem.Null;
 /// <summary>
 /// Represents a non-existing directory.
 /// </summary>
-public class NotFoundDirectory : VirtualDirectory
+public sealed class NotFoundDirectory : VirtualDirectory
 {
     /// <inheritdoc />
     public override IVirtualFileSystem FileSystem { get; }
@@ -27,8 +27,11 @@ protected override ValueTask<bool> ExistsCoreAsync(CancellationToken cancellatio
         default;
 
     /// <inheritdoc />
-    protected override ValueTask CreateCoreAsync(CancellationToken cancellationToken) =>
-        default;
+    protected override ValueTask CreateCoreAsync(CancellationToken cancellationToken)
+    {
+        Error_UnauthorizedAccess(FullName);
+        return default;
+    }
 
     /// <inheritdoc />
     protected override ValueTask DeleteCoreAsync(CancellationToken cancellationToken) =>
@@ -37,4 +40,8 @@ protected override ValueTask DeleteCoreAsync(CancellationToken cancellationToken
     /// <inheritdoc />
     protected override IAsyncEnumerable<VirtualNode> GetFileNodesCoreAsync(CancellationToken cancellationToken) =>
         Array.Empty<VirtualNode>().ToAsyncEnumerable();
+
+    [DoesNotReturn]
+    private static void Error_UnauthorizedAccess(string path) =>
+        throw new UnauthorizedAccessException($"Access to the path '{path}' is denied.");
 }

src/Ramstack.FileSystem.Abstractions/Null/NotFoundFile.cs

@@ -1,5 +1,3 @@
-using System.Diagnostics.CodeAnalysis;
-
 namespace Ramstack.FileSystem.Null;
 
 /// <summary>
@@ -43,7 +41,7 @@ protected override ValueTask<Stream> OpenWriteCoreAsync(CancellationToken cancel
     /// <inheritdoc />
     protected override ValueTask WriteCoreAsync(Stream stream, bool overwrite, CancellationToken cancellationToken)
     {
-        Error_FileNotFound(FullName);
+        Error_UnauthorizedAccess(FullName);
         return default;
     }
 
@@ -54,4 +52,8 @@ protected override ValueTask DeleteCoreAsync(CancellationToken cancellationToken
     [DoesNotReturn]
     private static void Error_FileNotFound(string path) =>
         throw new FileNotFoundException($"Unable to find file '{path}'.", path);
+
+    [DoesNotReturn]
+    private static void Error_UnauthorizedAccess(string path) =>
+        throw new UnauthorizedAccessException($"Access to the path '{path}' is denied.");
 }

src/Ramstack.FileSystem.Abstractions/Ramstack.FileSystem.Abstractions.csproj

@@ -35,6 +35,12 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Using Include="System.Diagnostics" />
+    <Using Include="System.Diagnostics.CodeAnalysis" />
+    <Using Include="System.Runtime.CompilerServices" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="Microsoft.SourceLink.GitHub">
       <PrivateAssets>all</PrivateAssets>

src/Ramstack.FileSystem.Abstractions/VirtualDirectory.cs

@@ -1,6 +1,3 @@
-using System.Diagnostics;
-using System.Runtime.CompilerServices;
-
 using Ramstack.Globbing.Traversal;
 
 namespace Ramstack.FileSystem;
@@ -121,16 +118,7 @@ public IAsyncEnumerable<VirtualDirectory> GetDirectoriesAsync(CancellationToken
     public IAsyncEnumerable<VirtualNode> GetFileNodesAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(patterns);
-
-        return new FileTreeAsyncEnumerable<VirtualNode, VirtualNode>(this, cancellationToken)
-        {
-            Patterns = patterns,
-            Excludes = excludes ?? [],
-            FileNameSelector = node => node.FullName,
-            ShouldRecursePredicate = node => node is VirtualDirectory,
-            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
-            ResultSelector = node => node
-        };
+        return GetFileNodesCoreAsync(patterns, excludes, cancellationToken);
     }
 
     /// <summary>
@@ -146,17 +134,7 @@ public IAsyncEnumerable<VirtualNode> GetFileNodesAsync(string[] patterns, string
     public IAsyncEnumerable<VirtualFile> GetFilesAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(patterns);
-
-        return new FileTreeAsyncEnumerable<VirtualNode, VirtualFile>(this, cancellationToken)
-        {
-            Patterns = patterns,
-            Excludes = excludes ?? [],
-            FileNameSelector = node => node.FullName,
-            ShouldIncludePredicate = node => node is VirtualFile,
-            ShouldRecursePredicate = node => node is VirtualDirectory,
-            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
-            ResultSelector = node => (VirtualFile)node
-        };
+        return GetFilesCoreAsync(patterns, excludes, cancellationToken);
     }
 
     /// <summary>
@@ -172,17 +150,7 @@ public IAsyncEnumerable<VirtualFile> GetFilesAsync(string[] patterns, string[]?
     public IAsyncEnumerable<VirtualDirectory> GetDirectoriesAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(patterns);
-
-        return new FileTreeAsyncEnumerable<VirtualNode, VirtualDirectory>(this, cancellationToken)
-        {
-            Patterns = patterns,
-            Excludes = excludes ?? [],
-            FileNameSelector = node => node.FullName,
-            ShouldIncludePredicate = node => node is VirtualDirectory,
-            ShouldRecursePredicate = node => node is VirtualDirectory,
-            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
-            ResultSelector = node => (VirtualDirectory)node
-        };
+        return GetDirectoriesCoreAsync(patterns, excludes, cancellationToken);
     }
 
     /// <summary>
@@ -243,4 +211,75 @@ protected virtual async IAsyncEnumerable<VirtualDirectory> GetDirectoriesCoreAsy
                 yield return directory;
         }
     }
+
+    /// <summary>
+    /// Core implementation for asynchronously returning an async-enumerable collection of file nodes (both directories and files)
+    /// within the current directory that match any of the specified glob patterns.
+    /// </summary>
+    /// <param name="patterns">An array of glob patterns to match against the names of file nodes.</param>
+    /// <param name="excludes">An optional array of glob patterns to exclude file nodes.</param>
+    /// <param name="cancellationToken">An optional cancellation token to cancel the operation.</param>
+    /// <returns>
+    /// An async-enumerable collection of <see cref="VirtualNode"/> instances.
+    /// </returns>
+    protected virtual IAsyncEnumerable<VirtualNode> GetFileNodesCoreAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken)
+    {
+        return new FileTreeAsyncEnumerable<VirtualNode, VirtualNode>(this, cancellationToken)
+        {
+            Patterns = patterns,
+            Excludes = excludes ?? [],
+            FileNameSelector = node => node.Name,
+            ShouldRecursePredicate = node => node is VirtualDirectory,
+            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
+            ResultSelector = node => node
+        };
+    }
+
+    /// <summary>
+    /// Core implementation for asynchronously returning an async-enumerable collection of files within the current directory
+    /// that match any of the specified glob patterns.
+    /// </summary>
+    /// <param name="patterns">An array of glob patterns to match against the names of files.</param>
+    /// <param name="excludes">An optional array of glob patterns to exclude files.</param>
+    /// <param name="cancellationToken">An optional cancellation token to cancel the operation.</param>
+    /// <returns>
+    /// An async-enumerable collection of <see cref="VirtualFile"/> instances.
+    /// </returns>
+    protected virtual IAsyncEnumerable<VirtualFile> GetFilesCoreAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken)
+    {
+        return new FileTreeAsyncEnumerable<VirtualNode, VirtualFile>(this, cancellationToken)
+        {
+            Patterns = patterns,
+            Excludes = excludes ?? [],
+            FileNameSelector = node => node.Name,
+            ShouldIncludePredicate = node => node is VirtualFile,
+            ShouldRecursePredicate = node => node is VirtualDirectory,
+            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
+            ResultSelector = node => (VirtualFile)node
+        };
+    }
+
+    /// <summary>
+    /// Core implementation for asynchronously returning an async-enumerable collection of directories within the current directory
+    /// that match any of the specified glob patterns.
+    /// </summary>
+    /// <param name="patterns">An array of glob patterns to match against the names of directories.</param>
+    /// <param name="excludes">An optional array of glob patterns to exclude directories.</param>
+    /// <param name="cancellationToken">An optional cancellation token to cancel the operation.</param>
+    /// <returns>
+    /// An async-enumerable collection of <see cref="VirtualDirectory"/> instances.
+    /// </returns>
+    protected virtual IAsyncEnumerable<VirtualDirectory> GetDirectoriesCoreAsync(string[] patterns, string[]? excludes, CancellationToken cancellationToken)
+    {
+        return new FileTreeAsyncEnumerable<VirtualNode, VirtualDirectory>(this, cancellationToken)
+        {
+            Patterns = patterns,
+            Excludes = excludes ?? [],
+            FileNameSelector = node => node.Name,
+            ShouldIncludePredicate = node => node is VirtualDirectory,
+            ShouldRecursePredicate = node => node is VirtualDirectory,
+            ChildrenSelector = (node, token) => ((VirtualDirectory)node).GetFileNodesCoreAsync(token),
+            ResultSelector = node => (VirtualDirectory)node
+        };
+    }
 }

src/Ramstack.FileSystem.Abstractions/VirtualFile.cs

@@ -1,5 +1,3 @@
-using System.Diagnostics;
-
 namespace Ramstack.FileSystem;
 
 /// <summary>

src/Ramstack.FileSystem.Abstractions/VirtualNode.cs

@@ -1,6 +1,3 @@
-using System.Diagnostics;
-using System.Diagnostics.CodeAnalysis;
-
 namespace Ramstack.FileSystem;
 
 /// <summary>

src/Ramstack.FileSystem.Abstractions/VirtualNodeProperties.cs

@@ -1,5 +1,3 @@
-using System.Diagnostics;
-
 namespace Ramstack.FileSystem;
 
 /// <summary>

src/Ramstack.FileSystem.Abstractions/VirtualPath.cs

@@ -118,7 +118,8 @@ public static ReadOnlySpan<char> GetFileName(ReadOnlySpan<char> path)
     /// </summary>
     /// <param name="path">The path to retrieve the directory portion from.</param>
     /// <returns>
-    /// Directory portion for <paramref name="path"/>, or an empty string if the path denotes a root directory.
+    /// The directory portion of <paramref name="path"/>, or an empty span if <paramref name="path"/>
+    /// is empty or denotes a root directory.
     /// </returns>
     public static string GetDirectoryName(string path)
     {
@@ -140,7 +141,8 @@ public static string GetDirectoryName(string path)
     /// </summary>
     /// <param name="path">The path to retrieve the directory portion from.</param>
     /// <returns>
-    /// Directory portion for <paramref name="path"/>, or an empty string if path denotes a root directory.
+    /// The directory portion of <paramref name="path"/>, or an empty span if <paramref name="path"/>
+    /// is empty or denotes a root directory.
     /// </returns>
     public static ReadOnlySpan<char> GetDirectoryName(ReadOnlySpan<char> path)
     {