<?php

declare(strict_types=1);

namespace App\Framework\Filesystem;

use App\Framework\Core\ValueObjects\Timestamp;
use App\Framework\Filesystem\ValueObjects\FileCollection;
use App\Framework\Filesystem\ValueObjects\FilePath;
use App\Framework\Filesystem\ValueObjects\FilePattern;
use Generator;

/**
 * Interface for all FileScanner implementations
 * Generic filesystem scanning interface with type-safe Value Objects
 */
interface FileScannerInterface
{
    /**
     * Find all files matching a pattern in a directory
     */
    public function findFiles(FilePath $directoryPath, ?FilePattern $pattern = null): FileCollection;

    /**
     * Get the latest modification time of all files matching pattern
     */
    public function getLatestModificationTime(FilePath $directoryPath, ?FilePattern $pattern = null): Timestamp;

    /**
     * Find files that have been modified since a given timestamp
     */
    public function findFilesModifiedSince(FilePath $directoryPath, Timestamp $since, ?FilePattern $pattern = null): FileCollection;

    /**
     * Stream files one by one for memory-efficient processing
     * @return Generator<File>
     */
    public function streamFiles(FilePath $directoryPath, ?FilePattern $pattern = null): Generator;

    /**
     * Stream files in batches for balanced memory/performance
     * @return Generator<FileCollection>
     */
    public function streamFilesInBatches(FilePath $directoryPath, ?FilePattern $pattern = null, int $batchSize = 100): Generator;
}
