feat(documentator): The Processor (#162)

Small helper to iterate files and their dependencies (= other files) it the right order.

(cherry picked from commit 2fdac35)

Author: LastDragon-ru

packages/documentator/src/Processor/Contracts/Task.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Contracts;
+
+use Generator;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
+use SplFileInfo;
+
+interface Task {
+    /**
+     * Returns the file extensions which task is processing.
+     *
+     * @return non-empty-list<string>
+     */
+    public function getExtensions(): array;
+
+    /**
+     * Performs action on the `$file`.
+     *
+     * Each returned value will be treated as a dependency of the task. It will
+     * be resolved relative to the directory where the `$file` located,
+     * processed, and then send back into the generator.
+     *
+     * @return Generator<mixed, SplFileInfo|File|string, File, bool>|bool
+     */
+    public function __invoke(Directory $root, File $file): Generator|bool;
+}

packages/documentator/src/Processor/Exceptions/CircularDependency.php

@@ -0,0 +1,60 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
+use Throwable;
+
+use function array_map;
+use function implode;
+use function sprintf;
+
+class CircularDependency extends ProcessorError {
+    /**
+     * @param list<File> $stack
+     */
+    public function __construct(
+        protected Directory $root,
+        protected readonly File $target,
+        protected readonly File $dependency,
+        protected readonly array $stack,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                <<<'MESSAGE'
+                Circular Dependency detected:
+
+                %2$s
+                ! %1$s
+
+                (root: `%3$s`)
+                MESSAGE,
+                $this->dependency->getRelativePath($this->root),
+                '* '.implode("\n* ", array_map(fn ($f) => $f->getRelativePath($this->root), $this->stack)),
+                $this->root->getPath(),
+            ),
+            $previous,
+        );
+    }
+
+    public function getRoot(): Directory {
+        return $this->root;
+    }
+
+    public function getTarget(): File {
+        return $this->target;
+    }
+
+    public function getDependency(): File {
+        return $this->dependency;
+    }
+
+    /**
+     * @return list<File>
+     */
+    public function getStack(): array {
+        return $this->stack;
+    }
+}

packages/documentator/src/Processor/Exceptions/FileDependencyNotFound.php

@@ -0,0 +1,37 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Core\Utils\Path;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
+use Throwable;
+
+use function sprintf;
+
+class FileDependencyNotFound extends ProcessorError {
+    public function __construct(
+        protected Directory $root,
+        protected readonly File $target,
+        protected readonly string $path,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                'Dependency `%s` of `%s` not found (root: `%s`).',
+                Path::getRelativePath($this->root->getPath(), $this->path),
+                $this->target->getRelativePath($this->root),
+                $this->root->getPath(),
+            ),
+            $previous,
+        );
+    }
+
+    public function getRoot(): Directory {
+        return $this->root;
+    }
+
+    public function getPath(): string {
+        return $this->path;
+    }
+}

packages/documentator/src/Processor/Exceptions/FileSaveFailed.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
+use Throwable;
+
+use function sprintf;
+
+class FileSaveFailed extends ProcessorError {
+    public function __construct(
+        protected Directory $root,
+        protected readonly File $target,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                'Failed to save `%s` file (root: `%s`).',
+                $this->target->getRelativePath($this->root),
+                $this->root->getPath(),
+            ),
+            $previous,
+        );
+    }
+
+    public function getRoot(): Directory {
+        return $this->root;
+    }
+
+    public function getTarget(): File {
+        return $this->target;
+    }
+}

packages/documentator/src/Processor/Exceptions/FileTaskFailed.php

@@ -0,0 +1,41 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Task;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
+use Throwable;
+
+use function sprintf;
+
+class FileTaskFailed extends ProcessorError {
+    public function __construct(
+        protected Directory $root,
+        protected readonly File $target,
+        protected readonly Task $task,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                'The `%s` task failed for `%s` file (root: `%s`).',
+                $this->target->getRelativePath($this->root),
+                $this->task::class,
+                $this->root->getPath(),
+            ),
+            $previous,
+        );
+    }
+
+    public function getRoot(): Directory {
+        return $this->root;
+    }
+
+    public function getTarget(): File {
+        return $this->target;
+    }
+
+    public function getTask(): Task {
+        return $this->task;
+    }
+}

packages/documentator/src/Processor/Exceptions/ProcessingFailed.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
+use Throwable;
+
+use function sprintf;
+
+class ProcessingFailed extends ProcessorError {
+    public function __construct(
+        protected Directory $root,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                'Processing failed (root: `%s`)',
+                $this->root->getPath(),
+            ),
+            $previous,
+        );
+    }
+
+    public function getRoot(): Directory {
+        return $this->root;
+    }
+}

packages/documentator/src/Processor/Exceptions/ProcessorError.php

@@ -0,0 +1,9 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Processor\Exceptions;
+
+use LastDragon_ru\LaraASP\Documentator\PackageException;
+
+abstract class ProcessorError extends PackageException {
+    // empty
+}