feat(documentator): IncludePackageList (`include:include:package-li…

…st`) will also detect path to `UPGRADE.md` (should be in the same directory where README)

README.md

@@ -38,7 +38,7 @@ composer require lastdragon-ru/lara-asp-core
 # Packages
 
 [include:package-list]: ./packages
-[//]: # (start: 157880c5194e7203b2fa2be487292ca79231698a26623d4ca6431196b3f64d0f)
+[//]: # (start: df3ee6374fabefbdeb79b26164b3f2ef88f6ed94646bb5d44751ea6da758de19)
 [//]: # (warning: Generated automatically. Do not edit.)
 
 ## Core
@@ -99,4 +99,4 @@ This package provides various useful asserts for [PHPUnit](https://phpunit.de/)
 
 [Read more](<packages/testing/README.md>).
 
-[//]: # (end: 157880c5194e7203b2fa2be487292ca79231698a26623d4ca6431196b3f64d0f)
+[//]: # (end: df3ee6374fabefbdeb79b26164b3f2ef88f6ed94646bb5d44751ea6da758de19)

packages/documentator/defaults/views/package-list/markdown.blade.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * @var list<array{path: string, title: string, summary: ?string}> $packages
+ * @var list<array{path: string, title: string, summary: ?string, upgrade: ?string}> $packages
  */
 
 ?>

packages/documentator/defaults/views/package-list/upgrade.blade.php

@@ -0,0 +1,11 @@
+<?php
+/**
+ * @var list<array{path: string, title: string, summary: ?string, upgrade: ?string}> $packages
+ */
+
+?>
+@foreach ($packages as $package)
+@if ($package['upgrade'])
+* [{!! $package['title'] !!}](<{{ $package['upgrade'] }}>)
+@endif
+@endforeach

packages/documentator/src/Preprocessor/Instructions/IncludePackageList.php

@@ -114,10 +114,16 @@ public function process(string $path, string $target, Serializable $parameters):
             $readmePath   = Path::join($target, $package->getFilename(), $readme);
 
             if ($packageTitle) {
+                $upgrade     = $this->getPackageUpgrade($packagePath, $packageInfo);
+                $upgradePath = $upgrade
+                    ? Path::join($target, $package->getFilename(), $upgrade)
+                    : null;
+
                 $packages[] = [
                     'path'    => $readmePath,
                     'title'   => $packageTitle,
                     'summary' => Markdown::getSummary($content),
+                    'upgrade' => $upgradePath,
                 ];
             } else {
                 throw new DocumentTitleIsMissing($path, $target, $readmePath);
@@ -167,19 +173,34 @@ protected function getPackageInfo(string $path): ?array {
      * @param array<array-key, mixed> $package
      */
     protected function getPackageReadme(string $path, array $package): ?string {
-        $readme   = null;
-        $variants = [
+        return $this->getPackageFile($path, [
             $package['readme'] ?? null,
             'README.md',
-        ];
+        ]);
+    }
+
+    /**
+     * @param array<array-key, mixed> $package
+     */
+    protected function getPackageUpgrade(string $path, array $package): ?string {
+        return $this->getPackageFile($path, [
+            'UPGRADE.md',
+        ]);
+    }
+
+    /**
+     * @param array<array-key, mixed> $variants
+     */
+    private function getPackageFile(string $path, array $variants): ?string {
+        $file = null;
 
         foreach ($variants as $variant) {
             if ($variant && is_string($variant) && is_file(Path::getPath($path, $variant))) {
-                $readme = $variant;
+                $file = $variant;
                 break;
             }
         }
 
-        return $readme;
+        return $file;
     }
 }

packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest.php

@@ -16,15 +16,20 @@
  */
 #[CoversClass(IncludePackageList::class)]
 final class IncludePackageListTest extends TestCase {
-    public function testProcess(): void {
+    // <editor-fold desc="Tests">
+    // =========================================================================
+    /**
+     * @dataProvider dataProviderProcess
+     */
+    public function testProcess(string $expected, ?string $template): void {
         $path     = self::getTestData()->file('Document.md')->getPathname();
         $target   = basename(self::getTestData()->path('/packages'));
-        $params   = new IncludePackageListParameters();
+        $params   = new IncludePackageListParameters(template: $template);
         $instance = Container::getInstance()->make(IncludePackageList::class);
         $actual   = $instance->process($path, $target, $params);
 
         self::assertEquals(
-            self::getTestData()->content('.md'),
+            self::getTestData()->content($expected),
             <<<MARKDOWN
             <!-- markdownlint-disable -->
 
@@ -83,4 +88,19 @@ public function testProcessNoTitle(): void {
 
         $instance->process($path, $target, $params);
     }
+    //</editor-fold>
+
+    // <editor-fold desc="DataProviders">
+    // =========================================================================
+    /**
+     * @return array<string, array{string, ?string}>
+     */
+    public static function dataProviderProcess(): array {
+        return [
+            'no template' => ['~markdown.md', null],
+            'markdown'    => ['~markdown.md', 'markdown'],
+            'upgrade'     => ['~upgrade.md', 'upgrade'],
+        ];
+    }
+    // </editor-fold>
 }

packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest/packages/package/README.md

@@ -1,3 +1,17 @@
 # The `<` Package `>`
 
 Summary text with special characters `<`, `>`, `&`.
+
+## A
+
+SDfsdfsdf
+
+### B sdfsf
+
+sdfsdfd
+
+### sdfsdf
+
+fsdfsdfsdf
+
+## sdfsdfdsf

packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest/packages/package/UPGRADE.md

@@ -0,0 +1,3 @@
+# Upgrade Guide
+
+bla bla bla

packages/documentator/src/Preprocessor/Instructions/IncludePackageListTest~upgrade.md

@@ -0,0 +1,3 @@
+<!-- markdownlint-disable -->
+
+* [The `<` Package `>`](<packages/package/UPGRADE.md>)