Merge pull request #183 from LastDragon-ru/documentator/preprocessor-…

…relinking `Preprocessor` relinking
LastDragon-ru · Aug 15, 2024 · b610f65 · b610f65
2 parents a137201 + a7aab5b
commit b610f65
Show file tree

Hide file tree

Showing 59 changed files with 333 additions and 535 deletions.
diff --git a/README.md b/README.md
@@ -65,7 +65,7 @@ This package contains useful extensions and mixins for [Eloquent](https://larave
 
 ## (Laravel) GraphQL Extensions for Lighthouse
 
-This package provides highly powerful `@searchBy`, `@sortBy`, `@stream` directives for [lighthouse-php](https://lighthouse-php.com/). The `@searchBy` directive provides basic conditions like `=`, `>`, `<`, etc, relations, `not (<condition>)`, enums, and custom operators support. All are strictly typed so you no need to use `Mixed` type anymore. The `@sortBy` is not only about standard sorting by columns but also allows use relations. 😎
+This package provides highly powerful [`@searchBy`](packages/graphql/docs/Directives/@searchBy.md), [`@sortBy`](packages/graphql/docs/Directives/@sortBy.md), [`@stream`](packages/graphql/docs/Directives/@stream.md) directives for [lighthouse-php](https://lighthouse-php.com/). The [`@searchBy`](packages/graphql/docs/Directives/@searchBy.md) directive provides basic conditions like `=`, `>`, `<`, etc, relations, `not (<condition>)`, enums, and custom operators support. All are strictly typed so you no need to use `Mixed` type anymore. The [`@sortBy`](packages/graphql/docs/Directives/@sortBy.md) is not only about standard sorting by columns but also allows use relations. 😎
 
 [Read more](<packages/graphql/README.md>).
 
@@ -111,16 +111,10 @@ Independent (from Laravel and Lighthouse) package that allow you to print GraphQ
 
 [//]: # (end: fed4ec353a970d6253d640feee67d7662b2a28757689a2bd7276fe1136209b8a)
 
-[include:file]: ./docs/Shared/Upgrading.md
-[//]: # (start: c18391a9383a4b80e3507a660c7927062227f2c3f8d7a34ba11721a5cc9c5294)
-[//]: # (warning: Generated automatically. Do not edit.)
-
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: c18391a9383a4b80e3507a660c7927062227f2c3f8d7a34ba11721a5cc9c5294)
-
 # Development
 
 1. Fork & clone

diff --git a/docs/Shared/Links.md b/docs/Shared/Links.md
diff --git a/docs/Shared/Upgrading.md b/docs/Shared/Upgrading.md
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -42,16 +42,10 @@ composer require lastdragon-ru/lara-asp-core
 
 Please see the [source code](./src) to find something interesting 😅
 
-[include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-[//]: # (warning: Generated automatically. Do not edit.)
-
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-
 [include:file]: ../../docs/Shared/Contributing.md
 [//]: # (start: fc88f84f187016cb8144e9a024844024492f0c3a5a6f8d128bf69a5814cc8cc5)
 [//]: # (warning: Generated automatically. Do not edit.)

diff --git a/packages/core/src/Utils/PathTest.php b/packages/core/src/Utils/PathTest.php
@@ -25,6 +25,7 @@ public function testGetPath(): void {
 
     public function testGetRelativePath(): void {
         self::assertEquals('../to/file', Path::getRelativePath('/any/path', '/any/path/../to/file'));
+        self::assertEquals('', Path::getRelativePath('/any/path', '/any/path'));
         self::assertEquals('to/file', Path::getRelativePath('/absolute/path', 'to/./file'));
         self::assertEquals(basename(__FILE__), Path::getRelativePath(__FILE__, __FILE__));
     }

diff --git a/packages/dev/README.md b/packages/dev/README.md
@@ -37,16 +37,10 @@ composer require --dev lastdragon-ru/lara-asp-dev
 
 _In progress_.
 
-[include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-[//]: # (warning: Generated automatically. Do not edit.)
-
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-
 [include:file]: ../../docs/Shared/Contributing.md
 [//]: # (start: fc88f84f187016cb8144e9a024844024492f0c3a5a6f8d128bf69a5814cc8cc5)
 [//]: # (warning: Generated automatically. Do not edit.)

diff --git a/packages/documentator/README.md b/packages/documentator/README.md
@@ -58,16 +58,10 @@ Generates a table with the required versions of PHP/Laravel/etc in Markdown form
 
 [//]: # (end: afb4e2440d52a76ba0a75c90795760817a659138d71c9a463a0e417d9abb178a)
 
-[include:file]: ../../docs/Shared/Upgrading.md
-[//]: # (start: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-[//]: # (warning: Generated automatically. Do not edit.)
-
 # Upgrading
 
 Please follow [Upgrade Guide](UPGRADE.md).
 
-[//]: # (end: bf9c1ede9e482e5ee353d24490c6493a56ff023fc987625dc02aefe6b298696d)
-
 [include:file]: ../../docs/Shared/Contributing.md
 [//]: # (start: fc88f84f187016cb8144e9a024844024492f0c3a5a6f8d128bf69a5814cc8cc5)
 [//]: # (warning: Generated automatically. Do not edit.)

diff --git a/packages/documentator/src/Markdown/Document.php b/packages/documentator/src/Markdown/Document.php
@@ -139,7 +139,7 @@ public function mutate(Mutation ...$mutations): static {
      *
      * @return new<static>
      */
-    public function toInlinable(?string $seed = null): static {
+    public function toInlinable(string $seed): static {
         return $this->mutate(new FootnotesPrefix($seed), new ReferencesPrefix($seed));
     }
 

diff --git a/packages/documentator/src/Markdown/Mutations/FootnotesPrefix.php b/packages/documentator/src/Markdown/Mutations/FootnotesPrefix.php
@@ -11,22 +11,15 @@
 use League\CommonMark\Node\Block\Document as DocumentNode;
 use Override;
 
-use function hash;
 use function mb_strlen;
 use function mb_substr;
-use function uniqid;
 
 /**
  * Adds unique prefix for all footnotes.
  */
 readonly class FootnotesPrefix implements Mutation {
     public function __construct(
-        /**
-         * If the prefix is not specified, the hash of the document path will
-         * be used. If the document path is unknown, the random hash will be
-         * used.
-         */
-        protected ?string $prefix = null,
+        protected string $prefix,
     ) {
         // empty
     }
@@ -36,7 +29,6 @@ public function __construct(
      */
     #[Override]
     public function __invoke(Document $document, DocumentNode $node): array {
-        $prefix  = $this->prefix ?: hash('xxh3', $document->getPath() ?: uniqid($this::class)); // @phpstan-ignore disallowed.function
         $changes = [];
 
         foreach ($node->iterator() as $child) {
@@ -50,7 +42,7 @@ public function __invoke(Document $document, DocumentNode $node): array {
             $location = $label ? $this->getLabelLocation($child, $label) : null;
 
             if ($location) {
-                $changes[] = [$location, "{$prefix}-{$label}"];
+                $changes[] = [$location, "{$this->prefix}-{$label}"];
             }
         }
 

diff --git a/packages/documentator/src/Markdown/Mutations/FootnotesPrefixTest.php b/packages/documentator/src/Markdown/Mutations/FootnotesPrefixTest.php
@@ -17,66 +17,32 @@
  */
 #[CoversClass(FootnotesPrefix::class)]
 final class FootnotesPrefixTest extends TestCase {
-    private const Markdown = <<<'MARKDOWN'
-        # Header[^1]
-
-        Text text text[^2] text text [^1] text text text [^2] text text text
-        text text[^1] text text text [^2] text text text [^3] text[^bignote].
-
-        [^1]: footnote 1
-
-        Text text text[^2].
-
-        [^2]: footnote 2
-
-        [^4]: footnote 4
-
-        [^bignote]: Text text text text text text text text text text text
-            text text text text text text text text text text text text text
-            text.
-
-            Text text text text text text text text text text text text text
-            text text text text text text text text text text text text text
-            text.
-        MARKDOWN;
-
     public function testInvoke(): void {
-        $document = new Document(self::Markdown, 'path/to/file.md');
-        $node     = Cast::to(DocumentNode::class, (new ReflectionProperty($document, 'node'))->getValue($document));
-        $lines    = Data::get($node, Lines::class) ?? [];
-        $mutation = new FootnotesPrefix();
-        $changes  = $mutation($document, $node);
-        $actual   = (string) (new Editor($lines))->mutate($changes);
-
-        self::assertEquals(
+        $document = new Document(
             <<<'MARKDOWN'
-            # Header[^a282e9c32e7eee65-1]
+            # Header[^1]
 
-            Text text text[^a282e9c32e7eee65-2] text text [^a282e9c32e7eee65-1] text text text [^a282e9c32e7eee65-2] text text text
-            text text[^a282e9c32e7eee65-1] text text text [^a282e9c32e7eee65-2] text text text [^3] text[^a282e9c32e7eee65-bignote].
+            Text text text[^2] text text [^1] text text text [^2] text text text
+            text text[^1] text text text [^2] text text text [^3] text[^bignote].
 
-            [^a282e9c32e7eee65-1]: footnote 1
+            [^1]: footnote 1
 
-            Text text text[^a282e9c32e7eee65-2].
+            Text text text[^2].
 
-            [^a282e9c32e7eee65-2]: footnote 2
+            [^2]: footnote 2
 
             [^4]: footnote 4
 
-            [^a282e9c32e7eee65-bignote]: Text text text text text text text text text text text
+            [^bignote]: Text text text text text text text text text text text
                 text text text text text text text text text text text text text
                 text.
 
                 Text text text text text text text text text text text text text
                 text text text text text text text text text text text text text
                 text.
             MARKDOWN,
-            $actual,
+            __FILE__,
         );
-    }
-
-    public function testInvokeExplicit(): void {
-        $document = new Document(self::Markdown, __FILE__);
         $node     = Cast::to(DocumentNode::class, (new ReflectionProperty($document, 'node'))->getValue($document));
         $lines    = Data::get($node, Lines::class) ?? [];
         $mutation = new FootnotesPrefix('prefix');

diff --git a/packages/documentator/src/Markdown/Mutations/ReferencesPrefix.php b/packages/documentator/src/Markdown/Mutations/ReferencesPrefix.php
@@ -15,21 +15,14 @@
 use League\CommonMark\Node\Block\Document as DocumentNode;
 use Override;
 
-use function hash;
 use function mb_strlen;
-use function uniqid;
 
 /**
  * Adds unique prefix for all references.
  */
 class ReferencesPrefix implements Mutation {
     public function __construct(
-        /**
-         * If the prefix is not specified, the hash of the document path will
-         * be used. If the document path is unknown, the random hash will be
-         * used.
-         */
-        protected ?string $prefix = null,
+        protected string $prefix,
     ) {
         // empty
     }
@@ -39,7 +32,6 @@ public function __construct(
      */
     #[Override]
     public function __invoke(Document $document, DocumentNode $node): array {
-        $prefix     = $this->prefix ?: hash('xxh3', $document->getPath() ?: uniqid($this::class)); // @phpstan-ignore disallowed.function
         $changes    = [];
         $references = $this->getReferences($node);
 
@@ -60,7 +52,7 @@ public function __invoke(Document $document, DocumentNode $node): array {
 
                 if ($location !== null) {
                     $target = Utils::getReference($reference)?->getLabel();
-                    $target = "{$prefix}-{$target}";
+                    $target = "{$this->prefix}-{$target}";
                     $target = Utils::escapeTextInTableCell($reference, $target);
                     $text   = "[{$target}]";
                 }
@@ -77,7 +69,7 @@ public function __invoke(Document $document, DocumentNode $node): array {
                     $endLine   = $startLine;
                     $offset    = $coordinate->offset + 1;
                     $length    = mb_strlen($reference->getLabel());
-                    $text      = "{$prefix}-{$reference->getLabel()}";
+                    $text      = "{$this->prefix}-{$reference->getLabel()}";
                     $location  = new Location($startLine, $endLine, $offset, $length);
                 }
             } else {

diff --git a/packages/documentator/src/Markdown/Mutations/ReferencesPrefixTest.php b/packages/documentator/src/Markdown/Mutations/ReferencesPrefixTest.php
@@ -17,70 +17,34 @@
  */
 #[CoversClass(ReferencesPrefix::class)]
 final class ReferencesPrefixTest extends TestCase {
-    private const Markdown = <<<'MARKDOWN'
-        # Header
-
-        Text text [link](https://example.com) text text [`link`][link] text
-        text text ![image][image] text text.
-
-        ![image][image]
-
-        [link]: https://example.com
-        [image]: https://example.com
-
-        # Special
-
-        ## Inside Quote
-
-        > ![image][link]
-
-        ## Inside Table
-
-        | Header                  |  [Header][link]               |
-        |-------------------------|-------------------------------|
-        | Cell [link][link] cell. | Cell `\|` \\| ![table][image] |
-        | Cell                    | Cell cell [table][link].      |
-        MARKDOWN;
-
     public function testInvoke(): void {
-        $document = new Document(self::Markdown, 'path/to/file.md');
-        $node     = Cast::to(DocumentNode::class, (new ReflectionProperty($document, 'node'))->getValue($document));
-        $lines    = Data::get($node, Lines::class) ?? [];
-        $mutation = new ReferencesPrefix();
-        $changes  = $mutation($document, $node);
-        $actual   = (string) (new Editor($lines))->mutate($changes);
-
-        self::assertEquals(
+        $document = new Document(
             <<<'MARKDOWN'
             # Header
 
-            Text text [link](https://example.com) text text [`link`][a282e9c32e7eee65-link] text
-            text text ![image][a282e9c32e7eee65-image] text text.
+            Text text [link](https://example.com) text text [`link`][link] text
+            text text ![image][image] text text.
 
-            ![image][a282e9c32e7eee65-image]
+            ![image][image]
 
-            [a282e9c32e7eee65-link]: https://example.com
-            [a282e9c32e7eee65-image]: https://example.com
+            [link]: https://example.com
+            [image]: https://example.com
 
             # Special
 
             ## Inside Quote
 
-            > ![image][a282e9c32e7eee65-link]
+            > ![image][link]
 
             ## Inside Table
 
-            | Header                  |  [Header][a282e9c32e7eee65-link]               |
+            | Header                  |  [Header][link]               |
             |-------------------------|-------------------------------|
-            | Cell [link][a282e9c32e7eee65-link] cell. | Cell `\|` \\| ![table][a282e9c32e7eee65-image] |
-            | Cell                    | Cell cell [table][a282e9c32e7eee65-link].      |
+            | Cell [link][link] cell. | Cell `\|` \\| ![table][image] |
+            | Cell                    | Cell cell [table][link].      |
             MARKDOWN,
-            $actual,
+            'path/to/file.md',
         );
-    }
-
-    public function testInvokeExplicit(): void {
-        $document = new Document(self::Markdown, 'path/to/file.md');
         $node     = Cast::to(DocumentNode::class, (new ReflectionProperty($document, 'node'))->getValue($document));
         $lines    = Data::get($node, Lines::class) ?? [];
         $mutation = new ReferencesPrefix('prefix');