refactor(documentator)!: Processor simplification (#207)

LastDragon-ru · Dec 13, 2024 · 0afab17 · 0afab17
2 parents ed142ce + 44765c2
commit 0afab17
Show file tree

Hide file tree

Showing 37 changed files with 324 additions and 423 deletions.
diff --git a/packages/documentator/src/Commands/Preprocess.php b/packages/documentator/src/Commands/Preprocess.php
@@ -3,19 +3,29 @@
 namespace LastDragon_ru\LaraASP\Documentator\Commands;
 
 use Illuminate\Console\Command;
+use LastDragon_ru\LaraASP\Core\Application\ContainerResolver;
 use LastDragon_ru\LaraASP\Core\Path\DirectoryPath;
 use LastDragon_ru\LaraASP\Core\Path\FilePath;
 use LastDragon_ru\LaraASP\Core\Utils\Cast;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Document\Move;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Heading\Renumber;
 use LastDragon_ru\LaraASP\Documentator\Package;
-use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Factory;
 use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Task;
+use LastDragon_ru\LaraASP\Documentator\Processor\InstanceFactory;
 use LastDragon_ru\LaraASP\Documentator\Processor\Processor;
 use LastDragon_ru\LaraASP\Documentator\Processor\Result;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\CodeLinks\Task as CodeLinksTask;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Parameters;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeArtisan\Instruction as PreprocessIncludeArtisan;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction as PreprocessIncludeDocBlock;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Instruction as PreprocessIncludeDocumentList;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample\Instruction as PreprocessIncludeExample;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExec\Instruction as PreprocessIncludeExec;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeFile\Instruction as PreprocessIncludeFile;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeGraphqlDirective\Instruction as PreprocessIncludeGraphqlDirective;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludePackageList\Instruction as PreprocessIncludePackageList;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeTemplate\Instruction as PreprocessIncludeTemplate;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Task as PreprocessTask;
 use LastDragon_ru\LaraASP\Documentator\Utils\PhpDoc;
 use LastDragon_ru\LaraASP\Documentator\Utils\PhpDocumentFactory;
@@ -80,7 +90,7 @@ class Preprocess extends Command {
     private ?PhpDocumentFactory $phpDocumentFactory = null;
 
     public function __construct(
-        protected readonly Factory $factory,
+        protected readonly ContainerResolver $container,
     ) {
         parent::__construct();
     }
@@ -108,12 +118,42 @@ public function __invoke(Formatter $formatter): void {
             $this->output->writeln($line, OutputInterface::OUTPUT_NORMAL | $resultVerbosity);
         };
 
-        $duration = ($this->factory)()->run($path, $exclude, $listener);
+        $duration = $this->processor()->exclude($exclude)->run($path, $listener);
 
         $this->output->newLine();
         $this->output->writeln("<fg=green;options=bold>DONE ({$formatter->duration($duration)})</>");
     }
 
+    private function processor(): Processor {
+        $processor = new Processor($this->container);
+
+        foreach ($this->tasks() as $task) {
+            $processor->task($task);
+        }
+
+        return $processor;
+    }
+
+    /**
+     * @return list<InstanceFactory<covariant Task>|Task|class-string<covariant Task>>
+     */
+    protected function tasks(): array {
+        return [
+            new InstanceFactory(PreprocessTask::class, static function (PreprocessTask $task): void {
+                $task->addInstruction(PreprocessIncludeFile::class);
+                $task->addInstruction(PreprocessIncludeExec::class);
+                $task->addInstruction(PreprocessIncludeExample::class);
+                $task->addInstruction(PreprocessIncludeArtisan::class);
+                $task->addInstruction(PreprocessIncludeTemplate::class);
+                $task->addInstruction(PreprocessIncludeDocBlock::class);
+                $task->addInstruction(PreprocessIncludePackageList::class);
+                $task->addInstruction(PreprocessIncludeDocumentList::class);
+                $task->addInstruction(PreprocessIncludeGraphqlDirective::class);
+            }),
+            CodeLinksTask::class,
+        ];
+    }
+
     #[Override]
     public function getProcessedHelp(): string {
         try {
@@ -129,7 +169,7 @@ protected function getProcessedHelpTasks(int $level): string {
         $help      = '';
         $heading   = str_repeat('#', $level);
         $default   = '_No description provided_.';
-        $processor = ($this->factory)();
+        $processor = $this->processor();
 
         foreach ($processor->tasks() as $index => $task) {
             $description = trim($this->getProcessedHelpTaskDescription($task, $level + 1));

diff --git a/packages/documentator/src/Commands/PreprocessTest.php b/packages/documentator/src/Commands/PreprocessTest.php
@@ -2,7 +2,7 @@
 
 namespace LastDragon_ru\LaraASP\Documentator\Commands;
 
-use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Factory;
+use LastDragon_ru\LaraASP\Core\Application\ContainerResolver;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Parameters;
@@ -19,8 +19,7 @@
 #[CoversClass(Preprocess::class)]
 final class PreprocessTest extends TestCase {
     public function testGetProcessedHelpTaskPreprocessInstructions(): void {
-        $factory = Mockery::mock(Factory::class);
-        $task    = Mockery::mock(PreprocessTask::class);
+        $task = Mockery::mock(PreprocessTask::class);
         $task->shouldAllowMockingProtectedMethods();
         $task
             ->shouldReceive('getInstructions')
@@ -31,7 +30,8 @@ public function testGetProcessedHelpTaskPreprocessInstructions(): void {
                 PreprocessTest__InstructionNotSerializable::class,
             ]);
 
-        $command = new class($factory) extends Preprocess {
+        $container = $this->app()->make(ContainerResolver::class);
+        $command   = new class($container) extends Preprocess {
             #[Override]
             public function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $task, int $level): string {
                 return parent::getProcessedHelpTaskPreprocessInstructions($task, $level);
@@ -84,8 +84,8 @@ public function getProcessedHelpTaskPreprocessInstructions(PreprocessTask $task,
     }
 
     public function testGetProcessedHelpTaskPreprocessInstructionTarget(): void {
-        $factory = Mockery::mock(Factory::class);
-        $command = new class($factory) extends Preprocess {
+        $container = $this->app()->make(ContainerResolver::class);
+        $command   = new class($container) extends Preprocess {
             #[Override]
             public function getProcessedHelpTaskPreprocessInstructionTarget(
                 string $instruction,
@@ -114,8 +114,8 @@ public function getProcessedHelpTaskPreprocessInstructionTarget(
     }
 
     public function testGetProcessedHelpTaskPreprocessParameters(): void {
-        $factory = Mockery::mock(Factory::class);
-        $command = new class($factory) extends Preprocess {
+        $container = $this->app()->make(ContainerResolver::class);
+        $command   = new class($container) extends Preprocess {
             #[Override]
             public function getProcessedHelpTaskPreprocessParameters(
                 string $instruction,
@@ -148,8 +148,8 @@ public function getProcessedHelpTaskPreprocessParameters(
     }
 
     public function testGetProcessedHelpTaskPreprocessParametersNoParameters(): void {
-        $factory = Mockery::mock(Factory::class);
-        $command = new class($factory) extends Preprocess {
+        $container = $this->app()->make(ContainerResolver::class);
+        $command   = new class($container) extends Preprocess {
             #[Override]
             public function getProcessedHelpTaskPreprocessParameters(
                 string $instruction,
@@ -170,8 +170,8 @@ public function getProcessedHelpTaskPreprocessParameters(
     }
 
     public function testGetProcessedHelpTaskPreprocessParametersNotSerializable(): void {
-        $factory = Mockery::mock(Factory::class);
-        $command = new class($factory) extends Preprocess {
+        $container = $this->app()->make(ContainerResolver::class);
+        $command   = new class($container) extends Preprocess {
             #[Override]
             public function getProcessedHelpTaskPreprocessParameters(
                 string $instruction,

diff --git a/packages/documentator/src/PackageProvider.php b/packages/documentator/src/PackageProvider.php
@@ -9,8 +9,6 @@
 use LastDragon_ru\LaraASP\Documentator\Commands\Requirements;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Contracts\Markdown as MarkdownContract;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Markdown;
-use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Factory as ProcessorFactoryContract;
-use LastDragon_ru\LaraASP\Documentator\Processor\Factory as ProcessorFactory;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\CodeLinks\Contracts\LinkFactory as LinkFactoryContract;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\CodeLinks\Links\Factory as LinkFactory;
 use Override;
@@ -22,7 +20,6 @@ class PackageProvider extends ServiceProvider {
     public function register(): void {
         parent::register();
 
-        $this->app->scopedIf(ProcessorFactoryContract::class, ProcessorFactory::class);
         $this->app->scopedIf(LinkFactoryContract::class, LinkFactory::class);
         $this->app->scopedIf(MarkdownContract::class, Markdown::class);
     }

diff --git a/packages/documentator/src/Processor/Contracts/Factory.php b/packages/documentator/src/Processor/Contracts/Factory.php
diff --git a/packages/documentator/src/Processor/Contracts/Task.php b/packages/documentator/src/Processor/Contracts/Task.php
@@ -22,19 +22,13 @@ public static function getExtensions(): array;
      * or failed (`false`).
      *
      * The {@see Generator} means that the task has dependencies (= other files
-     * which should be processed before the task). Each returned value will be
+     * which should be processed before the current). Each returned value will be
      * resolved relative to the directory where the `$file` located, processed,
      * and then send back into the generator.
      *
-     * And, finally, the `null`. Special value that will postpone processing
-     * until all other files (and their dependencies) are processed. It may be
-     * useful, for example, if the task should collect information from all
-     * other files. Please note, the `null` can be returned only once, the
-     * second time will automatically mark the task as failed.
-     *
-     * @return Generator<mixed, Dependency<*>, mixed, bool>|bool|null
-     *      fixme(documentator): The correct type is `Generator<mixed, Dependency<V>, V, bool>|bool|null`
+     * @return Generator<mixed, Dependency<*>, mixed, bool>|bool
+     *      fixme(documentator): The correct type is `Generator<mixed, Dependency<V>, V, bool>|bool`
      *          but it is not yet supported by phpstan (see https://github.com/phpstan/phpstan/issues/4245)
      */
-    public function __invoke(Directory $root, File $file): Generator|bool|null;
+    public function __invoke(Directory $root, File $file): Generator|bool;
 }
diff --git a/packages/documentator/src/Processor/Dependencies/DirectoryIteratorTest.php b/packages/documentator/src/Processor/Dependencies/DirectoryIteratorTest.php
@@ -23,7 +23,7 @@
 final class DirectoryIteratorTest extends TestCase {
     public function testToString(): void {
         $path      = (new DirectoryPath(__DIR__))->getNormalizedPath();
-        $directory = new Directory($path, false);
+        $directory = new Directory($path);
 
         self::assertEquals('path/to/directory', (string) (new DirectoryIterator('path/to/directory')));
         self::assertEquals((string) $directory, (string) (new DirectoryIterator($directory)));
@@ -33,11 +33,11 @@ public function testToString(): void {
     public function testInvoke(): void {
         $fs        = new FileSystem();
         $path      = (new DirectoryPath(self::getTestData()->path('')))->getNormalizedPath();
-        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file      = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file      = new File((new FilePath(__FILE__))->getNormalizedPath());
         $absolute  = new DirectoryIterator($path);
         $relative  = new DirectoryIterator(basename((string) $path));
-        $directory = new DirectoryIterator(new Directory($path, false));
+        $directory = new DirectoryIterator(new Directory($path));
         $formatter = static function (Directory $directory) use ($path): string {
             return (string) $path->getRelativePath($directory->getPath());
         };
@@ -57,8 +57,8 @@ public function testInvoke(): void {
 
     public function testInvokeNotFound(): void {
         $fs   = new FileSystem();
-        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file = new File((new FilePath(__FILE__))->getNormalizedPath());
         $path = 'path/to/directory';
 
         self::expectException(DependencyNotFound::class);

diff --git a/packages/documentator/src/Processor/Dependencies/DirectoryReferenceTest.php b/packages/documentator/src/Processor/Dependencies/DirectoryReferenceTest.php
@@ -20,7 +20,7 @@
 final class DirectoryReferenceTest extends TestCase {
     public function testToString(): void {
         $path      = (new DirectoryPath(__DIR__))->getNormalizedPath();
-        $directory = new Directory($path, false);
+        $directory = new Directory($path);
 
         self::assertEquals('path/to/directory', (string) (new DirectoryReference('path/to/directory')));
         self::assertEquals((string) $directory, (string) (new DirectoryReference($directory)));
@@ -30,9 +30,9 @@ public function testToString(): void {
     public function testInvoke(): void {
         $fs        = new FileSystem();
         $dir       = (new DirectoryPath(__DIR__))->getNormalizedPath();
-        $root      = new Directory($dir, false);
-        $file      = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
-        $another   = new Directory($dir, false);
+        $root      = new Directory($dir);
+        $file      = new File((new FilePath(__FILE__))->getNormalizedPath());
+        $another   = new Directory($dir);
         $dirpath   = new DirectoryReference($dir);
         $absolute  = new DirectoryReference(__DIR__);
         $relative  = new DirectoryReference('.');
@@ -46,8 +46,8 @@ public function testInvoke(): void {
 
     public function testInvokeNotFound(): void {
         $fs   = new FileSystem();
-        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file = new File((new FilePath(__FILE__))->getNormalizedPath());
         $path = 'path/to/directory';
 
         self::expectException(DependencyNotFound::class);

diff --git a/packages/documentator/src/Processor/Dependencies/FileIteratorTest.php b/packages/documentator/src/Processor/Dependencies/FileIteratorTest.php
@@ -23,7 +23,7 @@
 final class FileIteratorTest extends TestCase {
     public function testToString(): void {
         $path      = (new DirectoryPath(__DIR__))->getNormalizedPath();
-        $directory = new Directory($path, false);
+        $directory = new Directory($path);
 
         self::assertEquals('path/to/directory', (string) (new FileIterator('path/to/directory')));
         self::assertEquals((string) $directory, (string) (new FileIterator($directory)));
@@ -33,12 +33,12 @@ public function testToString(): void {
     public function testInvoke(): void {
         $fs        = new FileSystem();
         $path      = (new DirectoryPath(self::getTestData()->path('')))->getNormalizedPath();
-        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file      = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file      = new File((new FilePath(__FILE__))->getNormalizedPath());
         $pattern   = '*.txt';
         $absolute  = new FileIterator($path, $pattern);
         $relative  = new FileIterator(basename((string) $path), $pattern);
-        $directory = new FileIterator(new Directory($path, false), $pattern);
+        $directory = new FileIterator(new Directory($path), $pattern);
         $formatter = static function (File $file) use ($path): string {
             return (string) $path->getRelativePath($file->getPath());
         };
@@ -59,8 +59,8 @@ public function testInvoke(): void {
 
     public function testInvokeNotFound(): void {
         $fs   = new FileSystem();
-        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file = new File((new FilePath(__FILE__))->getNormalizedPath());
         $path = 'path/to/directory';
 
         self::expectException(DependencyNotFound::class);

diff --git a/packages/documentator/src/Processor/Dependencies/FileReferenceTest.php b/packages/documentator/src/Processor/Dependencies/FileReferenceTest.php
@@ -21,7 +21,7 @@
 final class FileReferenceTest extends TestCase {
     public function testToString(): void {
         $path = (new FilePath(__FILE__))->getNormalizedPath();
-        $file = new File($path, false);
+        $file = new File($path);
 
         self::assertEquals('path/to/file', (string) (new FileReference('path/to/file')));
         self::assertEquals((string) $file, (string) (new FileReference($file)));
@@ -30,10 +30,10 @@ public function testToString(): void {
 
     public function testInvoke(): void {
         $fs        = new FileSystem();
-        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
+        $root      = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
         $path      = (new FilePath(__FILE__))->getNormalizedPath();
-        $file      = new File($path, false);
-        $another   = new File($path, false);
+        $file      = new File($path);
+        $another   = new File($path);
         $absolute  = new FileReference(__FILE__);
         $relative  = new FileReference(basename(__FILE__));
         $filepath  = new FileReference($path);
@@ -47,8 +47,8 @@ public function testInvoke(): void {
 
     public function testInvokeNotFound(): void {
         $fs   = new FileSystem();
-        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
-        $file = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $root = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath());
+        $file = new File((new FilePath(__FILE__))->getNormalizedPath());
         $path = 'path/to/file';
 
         self::expectException(DependencyNotFound::class);