Better include:document-list instruction

packages/documentator/README.md

@@ -38,19 +38,19 @@ composer require lastdragon-ru/lara-asp-documentator
 [//]: # (start: preprocess/820df828d96420b5)
 [//]: # (warning: Generated automatically. Do not edit.)
 
-## `lara-asp-documentator:commands`
+## [`lara-asp-documentator:commands`](<docs/Commands/commands.md>)
 
 Saves help for each command in the `namespace` into a separate file in the `target` directory.
 
 [Read more](<docs/Commands/commands.md>).
 
-## `lara-asp-documentator:preprocess`
+## [`lara-asp-documentator:preprocess`](<docs/Commands/preprocess.md>)
 
 Perform one or more task on the file.
 
 [Read more](<docs/Commands/preprocess.md>).
 
-## `lara-asp-documentator:requirements`
+## [`lara-asp-documentator:requirements`](<docs/Commands/requirements.md>)
 
 Generates a table with the required versions of PHP/Laravel/etc in Markdown format.
 

packages/documentator/defaults/views/document-list/default.blade.php

@@ -1,17 +1,17 @@
 <?php
 /**
- * @var list<array{path: string, title: string, summary: ?string}> $documents
+ * @var \LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data $data
  */
 
 ?>
-@foreach ($documents as $document)
-## {!! $document['title'] !!}
-@if($document['summary'])
+@foreach ($data->documents as $document)
+{{ str_repeat('#', $data->level) }} [{!! $document->title !!}](<{{ $document->path }}>)
+@if($document->summary)
 
-{!! $document['summary'] !!}
+{!! $document->summary !!}
 @endif
 
-[Read more](<{{ $document['path'] }}>).
+[Read more](<{{ $document->path }}>).
 @if (!$loop->last)
 
 @endif

packages/documentator/docs/Commands/preprocess.md

@@ -72,8 +72,14 @@ which will be replaced to FQCN (if possible). Other tags are ignored.
 * `<parameters>` - additional parameters
   * `depth`: `array|string|int|null` = `0` - [Directory Depth](https://symfony.com/doc/current/components/finder.html#directory-depth)
     (eg the `0` means no nested directories, the `null` removes limits).
-  * `template`: `string` = `'default'` - Blade template.
+  * `template`: `string` = `'default'` - Blade template. The documents passed in the `$data` ([`Data`][code-links/84d51020d324cc16])
+    variable. Also, be careful with leading whitespaces.
   * `order`: [`SortOrder`][code-links/7e5c66e8748c6ff8] = [`SortOrder::Asc`][code-links/08e0648f66e2d1a5] - Sort order.
+  * `level`: `?int` = `null` - Headings level. Possible values are
+
+    * `null`: `<current level> + 1`
+    * `int`: explicit level (`1-6`)
+    * `0`: `<current level>`
 
 Returns the list of `*.md` files in the `<target>` directory. Each file
 must have `# Header` as the first construction. The first paragraph
@@ -164,6 +170,9 @@ Glob(s) to exclude.
 [//]: # (start: code-links)
 [//]: # (warning: Generated automatically. Do not edit.)
 
+[code-links/84d51020d324cc16]: ../../src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Template/Data.php
+    "\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data"
+
 [code-links/f9077a28b352f84b]: ../../src/Processor/Tasks/Preprocess/Instructions/IncludeExample/Contracts/Runner.php
     "\LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample\Contracts\Runner"
 

packages/documentator/src/Processor/Tasks/Preprocess/Context.php

@@ -13,15 +13,16 @@
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesInline;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesPrefix;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\SelfLinksRemove;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
 
 class Context {
     public function __construct(
         public readonly Directory $root,
         public readonly File $file,
-        public readonly string $target,
-        public readonly ?string $parameters,
+        public readonly Document $document,
+        public readonly Block $node,
         private readonly Mutation $mutation,
     ) {
         // empty

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandError.php

@@ -17,7 +17,7 @@ public function __construct(
             $context,
             sprintf(
                 'Artisan command `%s` failed (in `%s`).',
-                $context->target,
+                $context->node->getDestination(),
                 $context->root->getRelativePath($context->file),
             ),
             $previous,

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/Exceptions/ArtisanCommandFailed.php

@@ -18,7 +18,7 @@ public function __construct(
             $context,
             sprintf(
                 'Artisan command `%s` exited with status code `%s` (in `%s`).',
-                $context->target,
+                $context->node->getDestination(),
                 $this->result,
                 $context->root->getRelativePath($context->file),
             ),

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeArtisan/InstructionTest.php

@@ -8,7 +8,9 @@
 use LastDragon_ru\LaraASP\Core\Application\ApplicationResolver;
 use LastDragon_ru\LaraASP\Core\Path\DirectoryPath;
 use LastDragon_ru\LaraASP\Core\Path\FilePath;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Document;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context;
@@ -36,7 +38,7 @@ public function testInvoke(): void {
         $params   = new Parameters('...');
         $expected = 'result';
         $command  = 'command to execute';
-        $context  = new Context($root, $file, $command, '{...}', new Nop());
+        $context  = new Context($root, $file, new Document(''), new Block(), new Nop());
         $instance = $this->app()->make(Instruction::class);
 
         $this->override(Kernel::class, static function (MockInterface $mock) use ($command, $expected): void {
@@ -82,9 +84,15 @@ static function (InputInterface $input, OutputInterface $output) use ($expected)
     public function testInvokeFailed(): void {
         $root     = new Directory((new DirectoryPath(__DIR__))->getNormalizedPath(), false);
         $file     = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
+        $node     = new class() extends Block {
+            #[Override]
+            public function getDestination(): string {
+                return 'command to execute';
+            }
+        };
         $params   = new Parameters('...');
-        $command  = 'command to execute';
-        $context  = new Context($root, $file, $command, '{...}', new Nop());
+        $command  = $node->getDestination();
+        $context  = new Context($root, $file, new Document(''), $node, new Nop());
         $instance = $this->app()->make(Instruction::class);
 
         $this->override(Kernel::class, static function (MockInterface $mock) use ($command): void {
@@ -140,7 +148,7 @@ public function testGetCommand(): void {
         $file     = new File((new FilePath(__FILE__))->getNormalizedPath(), false);
         $params   = new Parameters('...');
         $command  = 'artisan:command $directory {$directory} "{$directory}" $file {$file} "{$file}"';
-        $context  = new Context($root, $file, $command, '{...}', new Nop());
+        $context  = new Context($root, $file, new Document(''), new Block(), new Nop());
         $instance = new class (Mockery::mock(ApplicationResolver::class)) extends Instruction {
             #[Override]
             public function getCommand(Context $context, string $target, Parameters $parameters): string {

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Exceptions/TargetIsNotValidPhpFile.php

@@ -14,7 +14,7 @@ public function __construct(Context $context, ?Throwable $previous = null) {
             $context,
             sprintf(
                 'The `%s` is not a valid PHP file (in `%s`).',
-                $context->target,
+                $context->node->getDestination(),
                 $context->root->getRelativePath($context->file),
             ),
             $previous,

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest.php

@@ -7,6 +7,7 @@
 use LastDragon_ru\LaraASP\Core\Path\FilePath;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Document;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\Nop;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\Directory;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context;
@@ -34,7 +35,7 @@ public function testInvoke(Closure|string $expected, string $file, Parameters $p
         $root     = new Directory($path->getDirectoryPath(), false);
         $file     = new File($path, false);
         $target   = $file->getName();
-        $context  = new Context($root, $file, $target, null, new Nop());
+        $context  = new Context($root, $file, new Document(''), new Block(), new Nop());
         $instance = $this->app()->make(Instruction::class);
 
         if ($expected instanceof Closure) {

packages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocumentList/Instruction.php

@@ -5,17 +5,23 @@
 use Generator;
 use Iterator;
 use LastDragon_ru\LaraASP\Core\Utils\Cast;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Nodes\Reference\Block;
 use LastDragon_ru\LaraASP\Documentator\PackageViewer;
 use LastDragon_ru\LaraASP\Documentator\Processor\Contracts\Dependency;
 use LastDragon_ru\LaraASP\Documentator\Processor\Dependencies\FileIterator;
 use LastDragon_ru\LaraASP\Documentator\Processor\FileSystem\File;
 use LastDragon_ru\LaraASP\Documentator\Processor\Metadata\Markdown;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Context;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction as InstructionContract;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Data as TemplateData;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocumentList\Template\Document as TemplateDocument;
 use LastDragon_ru\LaraASP\Documentator\Utils\Sorter;
 use LastDragon_ru\LaraASP\Documentator\Utils\Text;
+use League\CommonMark\Extension\CommonMark\Node\Block\Heading;
 use Override;
 
+use function max;
+use function min;
 use function usort;
 
 /**
@@ -54,7 +60,6 @@ public static function getParameters(): string {
      */
     #[Override]
     public function __invoke(Context $context, string $target, mixed $parameters): Generator {
-        /** @var list<array{path: string, title: string, summary: ?string}> $documents */
         $documents = [];
         $iterator  = Cast::to(Iterator::class, yield new FileIterator($target, '*.md', $parameters->depth));
         $self      = $context->file->getPath();
@@ -77,11 +82,11 @@ public function __invoke(Context $context, string $target, mixed $parameters): G
 
             // Add
             $document    = $context->toSplittable($document);
-            $documents[] = [
-                'path'    => $context->file->getRelativePath($file),
-                'title'   => $document->getTitle() ?? Text::getPathTitle($file->getName()),
-                'summary' => $document->getSummary(),
-            ];
+            $documents[] = new TemplateDocument(
+                $context->file->getRelativePath($file),
+                $document->getTitle() ?? Text::getPathTitle($file->getName()),
+                $document->getSummary(),
+            );
         }
 
         // Empty?
@@ -92,17 +97,48 @@ public function __invoke(Context $context, string $target, mixed $parameters): G
         // Sort
         $comparator = $this->sorter->forString($parameters->order);
 
-        usort($documents, static function (array $a, $b) use ($comparator): int {
-            return $comparator($a['title'], $b['title']);
+        usort($documents, static function ($a, $b) use ($comparator): int {
+            return $comparator($a->title, $b->title);
         });
 
         // Render
         $template = "document-list.{$parameters->template}";
+        $level    = $this->getLevel($context->node, $parameters);
         $list     = $this->viewer->render($template, [
-            'documents' => $documents,
+            'data' => new TemplateData($documents, $level),
         ]);
 
         // Return
         return $list;
     }
+
+    /**
+     * @return int<1,6>
+     */
+    private function getLevel(Block $node, Parameters $parameters): int {
+        $level = match ($parameters->level) {
+            0       => $this->getNodeLevel($node),
+            null    => $this->getNodeLevel($node) + 1,
+            default => $parameters->level,
+        };
+        $level = min($level, 6);
+        $level = max($level, 1);
+
+        return $level;
+    }
+
+    private function getNodeLevel(Block $block): int {
+        $level = 0;
+
+        do {
+            $block = $block->previous();
+
+            if ($block instanceof Heading) {
+                $level = $block->getLevel();
+                $block = null;
+            }
+        } while ($block);
+
+        return $level;
+    }
 }