Trait FileSystemProvider 

pub trait FileSystemProvider: Send + Sync {
    // Required methods
    fn read_file_bytes(
        &self,
        path: &Path,
    ) -> Result<FileContent, FileSystemError>;
    fn list_files(
        &self,
        path: &Path,
        pattern: &str,
        recursive: bool,
    ) -> Result<Vec<PathBuf>, FileSystemError>;
    fn exists(&self, path: &Path) -> bool;

    // Provided methods
    fn metadata(&self, path: &Path) -> Result<FileMeta, FileSystemError> { ... }
    fn is_file(&self, path: &Path) -> bool { ... }
    fn is_dir(&self, path: &Path) -> bool { ... }
    fn walk_files(
        &self,
        path: &Path,
        _max_depth: usize,
        _skip_dirs: &[&str],
    ) -> Result<Vec<PathBuf>, FileSystemError> { ... }
}

Trait for file system operations - allows mocking in tests

Implement this trait to provide custom file system access. The default implementation is StdFileSystemProvider.

Required Methods

fn read_file_bytes(&self, path: &Path) -> Result<FileContent, FileSystemError>

Read raw file contents

Errors

Returns FileSystemError::PathNotFound if the file does not exist, or FileSystemError::IoError for other I/O errors.

fn list_files( &self, path: &Path, pattern: &str, recursive: bool, ) -> Result<Vec<PathBuf>, FileSystemError>

List files in a directory matching a glob pattern

Arguments

• path - The directory to search
• pattern - A glob pattern (e.g., “*.md”)
• recursive - Whether to search subdirectories

fn exists(&self, path: &Path) -> bool

Check if a path exists

Provided Methods

fn metadata(&self, path: &Path) -> Result<FileMeta, FileSystemError>

Look up the size (and other minimal metadata) for a path.

Adapters with direct filesystem access (the std adapter, mocks with explicit metadata) MUST override this method to avoid the default implementation, which reads the entire file via read_file_bytes just to obtain the length. The StdFileSystemProvider override uses std::fs::metadata (a single stat syscall) instead.

Errors

Returns FileSystemError::PathNotFound when the path does not exist, or FileSystemError::IoError for other I/O failures.

fn is_file(&self, path: &Path) -> bool

Whether path resolves to a regular file.

Used by the scanner entrypoints to decide between single-file and package scans. Routing this through the port (instead of calling Path::is_file directly) keeps test doubles consistent with production behaviour and preserves the hexagonal contract.

The default implementation derives the answer from read_file_bytes: a path whose bytes can be read is treated as a file. This is correct for the std adapter but slow; adapters with cheaper file-type access SHOULD override.

fn is_dir(&self, path: &Path) -> bool

Whether path resolves to a directory.

Counterpart of FileSystemProvider::is_file. The default implementation treats an existing path that is not a file as a directory. Adapters MUST override this when they need to model special files (devices, sockets, FIFOs) explicitly.

fn walk_files( &self, path: &Path, _max_depth: usize, _skip_dirs: &[&str], ) -> Result<Vec<PathBuf>, FileSystemError>

Walk regular files under path, returning their absolute paths.

max_depth caps descent depth (0 means unlimited). skip_dirs names directories whose subtrees MUST be skipped — used to keep the walker out of vendored / generated trees on adversarial inputs. Implementations MUST NOT follow symlinks.

The default implementation delegates to list_files(path, "*", recursive=true) and ignores max_depth / skip_dirs. This is correct (just less efficient) and lets test mocks pick up the new method without bespoke walk logic. The std adapter overrides to honour both knobs.

Errors

Returns FileSystemError::PathNotFound when the root does not exist, or FileSystemError::IoError for other I/O failures on the root path. Errors on individual children are logged and the walk continues, mirroring FileSystemProvider::list_files.

Implementors

impl FileSystemProvider for StdFileSystemProvider