feat(documentator): New instruction include:graphql-directive (#158)

.markdownlint.yaml

@@ -259,4 +259,5 @@ MD053:
     "include:package-list",
     "include:template",
     "include:docblock",
+    "include:graphql-directive"
   ]

packages/dev/composer.json

@@ -25,14 +25,11 @@
     "illuminate/support": "^10.34.0|^11.0.0",
     "larastan/larastan": "^2.8.1",
     "lastdragon-ru/lara-asp-core": "self.version",
-    "lastdragon-ru/lara-asp-graphql-printer": "self.version",
     "nikic/php-parser": "^4.18|^5.0",
     "nette/neon": "^3.4",
-    "nuwave/lighthouse": "^6.5.0|dev-laravel-11",
     "phpstan/phpstan": "^1.10",
     "symfony/console": "^6.3.0|^7.0.0",
-    "symfony/var-dumper": "^6.3.0|^7.0.0",
-    "webonyx/graphql-php": "^15.4.0"
+    "symfony/var-dumper": "^6.3.0|^7.0.0"
   },
   "require-dev": {
     "phpunit/phpunit": "^10.1.0|^11.0.0"

packages/dev/src/App/Provider.php

@@ -7,7 +7,6 @@
 class Provider extends ServiceProvider {
     public function boot(): void {
         $this->commands(
-            Directive::class,
             Example::class,
         );
     }

packages/documentator/composer.json

@@ -36,13 +36,15 @@
     "symfony/polyfill-php83": "^1.28",
     "symfony/serializer": "^6.3.3|^7.0.0",
     "lastdragon-ru/lara-asp-core": "self.version",
+    "lastdragon-ru/lara-asp-graphql-printer": "self.version",
     "lastdragon-ru/lara-asp-serializer": "self.version"
   },
   "require-dev": {
     "lastdragon-ru/lara-asp-testing": "self.version",
     "mockery/mockery": "^1.6.2",
     "orchestra/testbench": "^8.0.0|^9.0.0",
-    "phpunit/phpunit": "^10.1.0|^11.0.0"
+    "phpunit/phpunit": "^10.1.0|^11.0.0",
+    "webonyx/graphql-php": "^15.4.0"
   },
   "autoload": {
     "psr-4": {

packages/documentator/docs/Commands/preprocess.md

@@ -75,6 +75,12 @@ Executes the `<target>` and returns result.
 
 Includes the `<target>` file.
 
+### `[include:graphql-directive]: <target>`
+
+* `<target>` - Directive name (started with `@` sign)
+
+Includes the definition of the directive as a Markdown code block.
+
 ### `[include:package-list]: <target> <parameters>`
 
 * `<target>` - Directory path.

packages/documentator/src/Preprocessor/Exceptions/DependencyIsMissing.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions;
+
+use Throwable;
+
+use function sprintf;
+
+class DependencyIsMissing extends InstructionFailed {
+    /**
+     * @param class-string $class
+     */
+    public function __construct(
+        string $path,
+        string $target,
+        private readonly string $class,
+        Throwable $previous = null,
+    ) {
+        parent::__construct(
+            $path,
+            $target,
+            sprintf(
+                'The dependency `%s` is missed (in `%s`).',
+                $this->class,
+                $path,
+            ),
+            $previous,
+        );
+    }
+
+    public function getClass(): string {
+        return $this->class;
+    }
+}

packages/documentator/src/Preprocessor/Exceptions/TargetIsNotDirective.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions;
+
+use Throwable;
+
+use function sprintf;
+
+class TargetIsNotDirective extends InstructionFailed {
+    public function __construct(string $path, string $target, Throwable $previous = null) {
+        parent::__construct(
+            $path,
+            $target,
+            sprintf(
+                'The `%s` is not a directive (in `%s`).',
+                $target,
+                $path,
+            ),
+            $previous,
+        );
+    }
+}

packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/Instruction.php

@@ -0,0 +1,72 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective;
+
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Contracts\ProcessableInstruction;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DependencyIsMissing;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirective;
+use LastDragon_ru\LaraASP\GraphQLPrinter\Contracts\Printer;
+use LastDragon_ru\LaraASP\GraphQLPrinter\Settings\ImmutableSettings;
+use Override;
+
+use function mb_substr;
+use function trim;
+
+class Instruction implements ProcessableInstruction {
+    public function __construct(
+        protected readonly ?Printer $printer = null,
+    ) {
+        // empty
+    }
+
+    #[Override]
+    public static function getName(): string {
+        return 'include:graphql-directive';
+    }
+
+    #[Override]
+    public static function getDescription(): string {
+        return <<<'DESC'
+            Includes the definition of the directive as a Markdown code block.
+            DESC;
+    }
+
+    #[Override]
+    public static function getTargetDescription(): ?string {
+        return 'Directive name (started with `@` sign)';
+    }
+
+    #[Override]
+    public function process(string $path, string $target): string {
+        // Dependencies?
+        if (!$this->printer) {
+            throw new DependencyIsMissing($path, $target, Printer::class);
+        }
+
+        // Directive?
+        $directive  = mb_substr($target, 1);
+        $definition = $this->printer->getDirectiveResolver()?->getDefinition($directive);
+
+        if ($definition === null) {
+            throw new TargetIsNotDirective($path, $target);
+        }
+
+        // Print
+        $origin = $this->printer->getSettings();
+
+        try {
+            $settings = ImmutableSettings::createFrom($origin)->setPrintDirectives(false);
+            $exported = trim((string) $this->printer->setSettings($settings)->export($definition));
+            $markdown = <<<MARKDOWN
+                ```graphql
+                {$exported}
+                ```
+                MARKDOWN;
+        } finally {
+            $this->printer->setSettings($origin);
+        }
+
+        // Return
+        return $markdown;
+    }
+}

packages/documentator/src/Preprocessor/Instructions/IncludeGraphqlDirective/InstructionTest.php

@@ -0,0 +1,111 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective;
+
+use GraphQL\Language\Parser;
+use Illuminate\Container\Container;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\DependencyIsMissing;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Exceptions\TargetIsNotDirective;
+use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase;
+use LastDragon_ru\LaraASP\GraphQLPrinter\Contracts\DirectiveResolver;
+use LastDragon_ru\LaraASP\GraphQLPrinter\Contracts\Printer as PrinterContract;
+use LastDragon_ru\LaraASP\GraphQLPrinter\Printer;
+use Mockery;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+/**
+ * @internal
+ */
+#[CoversClass(Instruction::class)]
+final class InstructionTest extends TestCase {
+    // <editor-fold desc="Tests">
+    // =========================================================================
+    public function testProcess(): void {
+        $directive = <<<'GRAPHQL'
+            directive @test
+            on
+                | SCALAR
+            GRAPHQL;
+
+        $this->override(PrinterContract::class, static function () use ($directive): PrinterContract {
+            $resolver = Mockery::mock(DirectiveResolver::class);
+            $resolver
+                ->shouldReceive('getDefinition')
+                ->with('test')
+                ->atLeast()
+                ->once()
+                ->andReturn(
+                    Parser::directiveDefinition($directive),
+                );
+
+            return (new Printer())->setDirectiveResolver($resolver);
+        });
+
+        $instance = Container::getInstance()->make(Instruction::class);
+        $actual   = $instance->process('path/to/file.md', '@test');
+
+        self::assertEquals(
+            <<<MARKDOWN
+            ```graphql
+            {$directive}
+            ```
+            MARKDOWN,
+            $actual,
+        );
+    }
+
+    public function testProcessNoPrinter(): void {
+        unset(Container::getInstance()[PrinterContract::class]);
+
+        $path     = 'path/to/file.md';
+        $target   = '@test';
+        $instance = Container::getInstance()->make(Instruction::class);
+
+        self::expectExceptionObject(
+            new DependencyIsMissing($path, $target, PrinterContract::class),
+        );
+
+        $instance->process($path, $target);
+    }
+
+    public function testProcessNoDirective(): void {
+        $this->override(PrinterContract::class, static function (): PrinterContract {
+            $resolver = Mockery::mock(DirectiveResolver::class);
+            $resolver
+                ->shouldReceive('getDefinition')
+                ->with('test')
+                ->once()
+                ->andReturn(
+                    null,
+                );
+
+            return (new Printer())->setDirectiveResolver($resolver);
+        });
+
+        $path     = 'path/to/file.md';
+        $target   = '@test';
+        $instance = Container::getInstance()->make(Instruction::class);
+
+        self::expectExceptionObject(
+            new TargetIsNotDirective($path, $target),
+        );
+
+        $instance->process($path, $target);
+    }
+
+    public function testProcessNoDirectiveResolver(): void {
+        $this->override(PrinterContract::class, static function (): PrinterContract {
+            return (new Printer())->setDirectiveResolver(null);
+        });
+
+        $path     = 'path/to/file.md';
+        $target   = '@test';
+        $instance = Container::getInstance()->make(Instruction::class);
+
+        self::expectExceptionObject(
+            new TargetIsNotDirective($path, $target),
+        );
+
+        $instance->process($path, $target);
+    }
+}

packages/documentator/src/Preprocessor/Preprocessor.php

@@ -2,6 +2,8 @@
 
 namespace LastDragon_ru\LaraASP\Documentator\Preprocessor;
 
+// @phpcs:disable Generic.Files.LineLength.TooLong
+
 use Exception;
 use Illuminate\Container\Container;
 use LastDragon_ru\LaraASP\Core\Utils\Path;
@@ -15,6 +17,7 @@
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeExample\Instruction as IncludeExample;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeExec\Instruction as IncludeExec;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeFile\Instruction as IncludeFile;
+use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeGraphqlDirective\Instruction as IncludeGraphqlDirective;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludePackageList\Instruction as IncludePackageList;
 use LastDragon_ru\LaraASP\Documentator\Preprocessor\Instructions\IncludeTemplate\Instruction as IncludeTemplate;
 use LastDragon_ru\LaraASP\Serializer\Contracts\Serializer;
@@ -92,6 +95,7 @@ public function __construct(
         $this->addInstruction(IncludeDocBlock::class);
         $this->addInstruction(IncludePackageList::class);
         $this->addInstruction(IncludeDocumentList::class);
+        $this->addInstruction(IncludeGraphqlDirective::class);
     }
 
     /**