[filesystem] Isolate Finder creation behind a factory (#90) (#91)

* Inject finder factory for mutable scans

* Update wiki submodule pointer for PR #91

* Use local filesystem interface for services

* Update wiki submodule pointer for PR #91

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -19,10 +19,10 @@
 
 namespace FastForward\DevTools\Agent\Skills;
 
+use FastForward\DevTools\Filesystem\FinderFactoryInterface;
+use FastForward\DevTools\Filesystem\FilesystemInterface;
 use Psr\Log\LoggerAwareInterface;
 use Psr\Log\LoggerInterface;
-use Symfony\Component\Filesystem\Filesystem;
-use Symfony\Component\Finder\Finder;
 use Symfony\Component\Filesystem\Path;
 
 /**
@@ -35,15 +35,15 @@
 final class SkillsSynchronizer implements LoggerAwareInterface
 {
     /**
-     * Initializes the synchronizer with a filesystem and finder instance.
+     * Initializes the synchronizer with a filesystem and finder factory.
      *
-     * @param Filesystem $filesystem Filesystem instance for file operations
-     * @param Finder $finder Finder instance for locating skill directories in the package
+     * @param FilesystemInterface $filesystem Filesystem instance for file operations
+     * @param FinderFactoryInterface $finderFactory Factory for locating skill directories in the package
      * @param LoggerInterface $logger Logger for recording synchronization actions and decisions
      */
     public function __construct(
-        private readonly Filesystem $filesystem,
-        private readonly Finder $finder,
+        private readonly FilesystemInterface $filesystem,
+        private readonly FinderFactoryInterface $finderFactory,
         private LoggerInterface $logger,
     ) {}
 
@@ -103,7 +103,8 @@ private function syncPackageSkills(
         string $packageSkillsPath,
         SynchronizeResult $result,
     ): void {
-        $finder = $this->finder
+        $finder = $this->finderFactory
+            ->create()
             ->directories()
             ->in($packageSkillsPath)
             ->depth('== 0');

src/Agent/Skills/SkillsSynchronizer.php

@@ -20,14 +20,14 @@
 namespace FastForward\DevTools\Console\Command;
 
 use Composer\Command\BaseCommand;
+use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use Symfony\Component\Config\FileLocatorInterface;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Filesystem\Path;
-use Symfony\Component\Finder\Finder;
 
 /**
  * Copies packaged or local resources into the consumer repository.
@@ -44,12 +44,12 @@ final class CopyResourceCommand extends BaseCommand
      *
      * @param FilesystemInterface $filesystem the filesystem used for copy operations
      * @param FileLocatorInterface $fileLocator the locator used to resolve source resources
-     * @param Finder $finder the finder used to iterate directory resources
+     * @param FinderFactoryInterface $finderFactory the factory used to create finders for directory resources
      */
     public function __construct(
         private readonly FilesystemInterface $filesystem,
         private readonly FileLocatorInterface $fileLocator,
-        private readonly Finder $finder,
+        private readonly FinderFactoryInterface $finderFactory,
     ) {
         parent::__construct();
     }
@@ -126,7 +126,8 @@ private function copyDirectory(
         bool $overwrite,
         OutputInterface $output
     ): int {
-        $files = $this->finder
+        $files = $this->finderFactory
+            ->create()
             ->files()
             ->in($sourcePath);
 

src/Console/Command/CopyResourceCommand.php

@@ -19,9 +19,9 @@
 
 namespace FastForward\DevTools\Console\Command;
 
+use Composer\Command\BaseCommand;
 use FastForward\DevTools\Composer\Json\ComposerJsonInterface;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
-use Composer\Command\BaseCommand;
 use FastForward\DevTools\GitAttributes\CandidateProviderInterface;
 use FastForward\DevTools\GitAttributes\ExistenceCheckerInterface;
 use FastForward\DevTools\GitAttributes\ExportIgnoreFilterInterface;
@@ -31,7 +31,6 @@
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
-use Symfony\Component\Filesystem\Filesystem;
 
 use function Safe\getcwd;
 
@@ -66,7 +65,7 @@ final class GitAttributesCommand extends BaseCommand
      * @param MergerInterface $merger the merger component
      * @param ReaderInterface $reader the reader component
      * @param WriterInterface $writer the writer component
-     * @param Filesystem $filesystem the filesystem component
+     * @param FilesystemInterface $filesystem the filesystem component
      * @param ComposerJsonInterface $composer the composer.json accessor
      */
     public function __construct(

src/Console/Command/GitAttributesCommand.php

@@ -20,6 +20,7 @@
 namespace FastForward\DevTools\Console\Command;
 
 use Composer\Command\BaseCommand;
+use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use FastForward\DevTools\Filesystem\FilesystemInterface;
 use FastForward\DevTools\Process\ProcessBuilderInterface;
 use FastForward\DevTools\Process\ProcessQueueInterface;
@@ -29,7 +30,6 @@
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Filesystem\Path;
-use Symfony\Component\Finder\Finder;
 
 /**
  * Installs Git hooks and initializes GrumPHP hooks for the consumer repository.
@@ -48,14 +48,14 @@ final class GitHooksCommand extends BaseCommand
      * @param FileLocatorInterface $fileLocator the locator used to find packaged hooks
      * @param ProcessBuilderInterface $processBuilder the builder used to assemble GrumPHP processes
      * @param ProcessQueueInterface $processQueue the queue used to execute GrumPHP initialization
-     * @param Finder $finder the finder used to iterate hook files
+     * @param FinderFactoryInterface $finderFactory the factory used to create finders for hook files
      */
     public function __construct(
         private readonly FilesystemInterface $filesystem,
         private readonly FileLocatorInterface $fileLocator,
         private readonly ProcessBuilderInterface $processBuilder,
         private readonly ProcessQueueInterface $processQueue,
-        private readonly Finder $finder,
+        private readonly FinderFactoryInterface $finderFactory,
     ) {
         parent::__construct();
     }
@@ -118,7 +118,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $targetPath = (string) $this->filesystem->getAbsolutePath((string) $input->getOption('target'));
         $overwrite = ! $input->getOption('no-overwrite');
 
-        $files = $this->finder
+        $files = $this->finderFactory
+            ->create()
             ->files()
             ->in($sourcePath);
 

src/Console/Command/GitHooksCommand.php

@@ -19,12 +19,12 @@
 
 namespace FastForward\DevTools\Console\CommandLoader;
 
-use ReflectionClass;
+use FastForward\DevTools\Filesystem\FinderFactoryInterface;
 use Psr\Container\ContainerInterface;
+use ReflectionClass;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\CommandLoader\ContainerCommandLoader;
-use Symfony\Component\Finder\Finder;
 
 /**
  * Responsible for dynamically discovering and loading Symfony Console commands
@@ -50,26 +50,27 @@ final class DevToolsCommandLoader extends ContainerCommandLoader
      * instantiable and have the AsCommand attribute.
      * It builds a command map associating command names with their respective classes.
      *
-     * @param Finder $finder
+     * @param FinderFactoryInterface $finderFactory
      * @param ContainerInterface $container
      */
-    public function __construct(Finder $finder, ContainerInterface $container)
+    public function __construct(FinderFactoryInterface $finderFactory, ContainerInterface $container)
     {
-        parent::__construct($container, $this->getCommandMap($finder));
+        parent::__construct($container, $this->getCommandMap($finderFactory));
     }
 
     /**
      * Builds a command map by scanning the Command directory for classes that are instantiable and have the AsCommand attribute.
      *
-     * @param Finder $finder
+     * @param FinderFactoryInterface $finderFactory
      *
      * @return array
      */
-    private function getCommandMap(Finder $finder): array
+    private function getCommandMap(FinderFactoryInterface $finderFactory): array
     {
         $commandMap = [];
 
-        $commandsDirectory = $finder
+        $commandsDirectory = $finderFactory
+            ->create()
             ->files()
             ->in(__DIR__ . '/../Command')
             ->name('*.php');

src/Console/CommandLoader/DevToolsCommandLoader.php

@@ -102,6 +102,44 @@ public function chmod(string|iterable $files, int $mode, int $umask = 0o000, boo
         parent::chmod($this->getAbsolutePath($files), $mode, $umask, $recursive);
     }
 
+    /**
+     * Removes files, symbolic links, or directories.
+     *
+     * @param iterable<string>|string $files the file(s), link(s), or directory(ies) to remove
+     */
+    #[Override]
+    public function remove(string|iterable $files): void
+    {
+        parent::remove($this->getAbsolutePath($files));
+    }
+
+    /**
+     * Creates a symbolic link.
+     *
+     * @param string $originDir the origin path the link MUST point to
+     * @param string $targetDir the link path to create
+     * @param bool $copyOnWindows whether directories SHOULD be copied on Windows instead of linked
+     */
+    #[Override]
+    public function symlink(string $originDir, string $targetDir, bool $copyOnWindows = false): void
+    {
+        parent::symlink($this->getAbsolutePath($originDir), $this->getAbsolutePath($targetDir), $copyOnWindows);
+    }
+
+    /**
+     * Reads a symbolic link target.
+     *
+     * @param string $path the symbolic link path
+     * @param bool $canonicalize whether the returned path SHOULD be canonicalized
+     *
+     * @return string|null the link target, or null when the path is not a symbolic link
+     */
+    #[Override]
+    public function readlink(string $path, bool $canonicalize = false): ?string
+    {
+        return parent::readlink($this->getAbsolutePath($path), $canonicalize);
+    }
+
     /**
      * Resolves a path or iterable of paths into their absolute path representation.
      *

src/Filesystem/Filesystem.php

@@ -75,6 +75,32 @@ public function copy(string $originFile, string $targetFile, bool $overwriteNewe
      */
     public function chmod(string|iterable $files, int $mode, int $umask = 0o000, bool $recursive = false): void;
 
+    /**
+     * Removes files, symbolic links, or directories.
+     *
+     * @param iterable<string>|string $files the file(s), link(s), or directory(ies) to remove
+     */
+    public function remove(string|iterable $files): void;
+
+    /**
+     * Creates a symbolic link.
+     *
+     * @param string $originDir the origin path the link MUST point to
+     * @param string $targetDir the link path to create
+     * @param bool $copyOnWindows whether directories SHOULD be copied on Windows instead of linked
+     */
+    public function symlink(string $originDir, string $targetDir, bool $copyOnWindows = false): void;
+
+    /**
+     * Reads a symbolic link target.
+     *
+     * @param string $path the symbolic link path
+     * @param bool $canonicalize whether the returned path SHOULD be canonicalized
+     *
+     * @return string|null the link target, or null when the path is not a symbolic link
+     */
+    public function readlink(string $path, bool $canonicalize = false): ?string;
+
     /**
      * Resolves a path or iterable of paths into their absolute path representation.
      *

src/Filesystem/FilesystemInterface.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Filesystem;
+
+use Symfony\Component\Finder\Finder;
+
+/**
+ * Default factory for Symfony Finder instances.
+ */
+final class FinderFactory implements FinderFactoryInterface
+{
+    /**
+     * {@inheritDoc}
+     */
+    public function create(): Finder
+    {
+        return new Finder();
+    }
+}

src/Filesystem/FinderFactory.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Fast Forward Development Tools for PHP projects.
+ *
+ * This file is part of fast-forward/dev-tools project.
+ *
+ * @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license  https://opensource.org/licenses/MIT MIT License
+ *
+ * @see      https://github.com/php-fast-forward/
+ * @see      https://github.com/php-fast-forward/dev-tools
+ * @see      https://github.com/php-fast-forward/dev-tools/issues
+ * @see      https://php-fast-forward.github.io/dev-tools/
+ * @see      https://datatracker.ietf.org/doc/html/rfc2119
+ */
+
+namespace FastForward\DevTools\Filesystem;
+
+use Symfony\Component\Finder\Finder;
+
+/**
+ * Creates fresh Symfony Finder instances for each filesystem scan.
+ */
+interface FinderFactoryInterface
+{
+    /**
+     * Creates a new mutable Finder instance.
+     *
+     * @return Finder a Finder instance that callers MAY configure for one scan
+     */
+    public function create(): Finder;
+}