Relative file path will be used to generate prefix for Footnotes/Refe…

…rences.
LastDragon-ru · Aug 15, 2024 · a7aab5b · a7aab5b
1 parent 9b96edd
commit a7aab5b
Show file tree

Hide file tree

Showing 16 changed files with 77 additions and 132 deletions.
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/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');

diff --git a/.../documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Instruction.php b/.../documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/Instruction.php
@@ -12,6 +12,7 @@
 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\IncludeDocBlock\Exceptions\TargetIsNotValidPhpFile;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\Utils;
 use Override;
 
 use function trim;
@@ -60,7 +61,9 @@ public function __invoke(Context $context, string $target, mixed $parameters): G
         // Parse
         $document = $document->mutate(new Move($context->file->getPath()));
         $result   = match (true) {
-            $parameters->summary && $parameters->description => $document->toInlinable(),
+            $parameters->summary && $parameters->description => $document->toInlinable(
+                Utils::getSeed($context, $target),
+            ),
             $parameters->summary                             => $document->toSplittable()->getSummary(),
             $parameters->description                         => $document->toSplittable()->getBody(),
             default                                          => '',

diff --git a/...Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest/ValidExpected.txt b/...Processor/Tasks/Preprocess/Instructions/IncludeDocBlock/InstructionTest/ValidExpected.txt
@@ -1,9 +1,9 @@
-Summary [A][b5c7e4eb170b3071-link][^b5c7e4eb170b3071-1].
+Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
 
 Description description description description description description
 description description description description description description
 description description description description description description
-[description][b5c7e4eb170b3071-link][^b5c7e4eb170b3071-1].
+[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
 
 Description with inline tags:
 
@@ -12,6 +12,6 @@ Description with inline tags:
 - `LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction`
 - `LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction::getName()`
 
-[b5c7e4eb170b3071-link]: https://example.com/
+[ffe8b433904a50b3-link]: https://example.com/
 
-[^b5c7e4eb170b3071-1]: Footnote
+[^ffe8b433904a50b3-1]: Footnote
diff --git a/...asks/Preprocess/Instructions/IncludeDocBlock/InstructionTest/ValidWithSummaryExpected.txt b/...asks/Preprocess/Instructions/IncludeDocBlock/InstructionTest/ValidWithSummaryExpected.txt
@@ -1,9 +1,9 @@
-Summary [A][b5c7e4eb170b3071-link][^b5c7e4eb170b3071-1].
+Summary [A][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
 
 Description description description description description description
 description description description description description description
 description description description description description description
-[description][b5c7e4eb170b3071-link][^b5c7e4eb170b3071-1].
+[description][ffe8b433904a50b3-link][^ffe8b433904a50b3-1].
 
 Description with inline tags:
 
@@ -12,6 +12,6 @@ Description with inline tags:
 - `LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction`
 - `LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeDocBlock\Instruction::getName()`
 
-[b5c7e4eb170b3071-link]: https://example.com/
+[ffe8b433904a50b3-link]: https://example.com/
 
-[^b5c7e4eb170b3071-1]: Footnote
+[^ffe8b433904a50b3-1]: Footnote
diff --git a/...s/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/Instruction.php b/...s/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/Instruction.php
@@ -13,6 +13,7 @@
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Contracts\Instruction as InstructionContract;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample\Contracts\Runner;
 use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\IncludeExample\Exceptions\ExampleFailed;
+use LastDragon_ru\LaraASP\Documentator\Processor\Tasks\Preprocess\Instructions\Utils;
 use Override;
 use Throwable;
 
@@ -91,7 +92,8 @@ public function __invoke(Context $context, string $target, mixed $parameters): G
                     subject : $output,
                     flags   : PREG_UNMATCHED_AS_NULL,
                 );
-                $output = (new Document($output, $target->getPath()))->mutate(new Move($path))->toInlinable();
+                $output = (new Document($output, $target->getPath()))->mutate(new Move($path));
+                $output = $output->toInlinable(Utils::getSeed($context, $target));
                 $output = trim((string) $output);
             }
 

diff --git a/...cumentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php b/...cumentator/src/Processor/Tasks/Preprocess/Instructions/IncludeExample/InstructionTest.php
@@ -156,9 +156,9 @@ public static function dataProviderInvoke(): array {
                 {$content}
                 ```
 
-                [example](InstructionTest/path/to/file.txt)[^8ef253b8d2355372-1]
+                [example](InstructionTest/path/to/file.txt)[^fe8f9df8acedaee3-1]
 
-                [^8ef253b8d2355372-1]: Footnote.
+                [^fe8f9df8acedaee3-1]: Footnote.
                 EXPECTED,
                 <<<'TEXT'
                 <markdown>

diff --git a/...ages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/Instruction.php b/...ages/documentator/src/Processor/Tasks/Preprocess/Instructions/IncludeFile/Instruction.php
@@ -11,6 +11,7 @@
 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\Utils;
 use Override;
 
 use function trim;
@@ -47,7 +48,8 @@ public function __invoke(Context $context, string $target, mixed $parameters): G
         $markdown = $file->getMetadata($this->markdown);
 
         if ($markdown) {
-            $content = $markdown->mutate(new Move($context->file->getPath()))->toInlinable();
+            $content = $markdown->mutate(new Move($context->file->getPath()));
+            $content = $content->toInlinable(Utils::getSeed($context, $file));
             $content = (string) $content;
         }
 

diff --git a/.../Tasks/Preprocess/Instructions/IncludeFile/InstructionTest/Markdown~expected.md b/.../Tasks/Preprocess/Instructions/IncludeFile/InstructionTest/Markdown~expected.md
@@ -2,8 +2,8 @@
 
 # File ${a}
 
-Content of the [${a}](Instruction.php) with [variable][d772f13860660865-link] "${b}"[^d772f13860660865-1].
+Content of the [${a}](Instruction.php) with [variable][6d22a594ebe2ecea-link] "${b}"[^6d22a594ebe2ecea-1].
 
-[d772f13860660865-link]: Instruction.php
+[6d22a594ebe2ecea-link]: Instruction.php
 
-[^d772f13860660865-1]: Footnote.
+[^6d22a594ebe2ecea-1]: Footnote.