fix(documentator)!: Location detection/update for links with inline n…

…odes inside label (#182)

packages/documentator/src/Markdown/Document.php

@@ -9,7 +9,6 @@
 use LastDragon_ru\LaraASP\Documentator\Markdown\Data\Lines;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Coordinate;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Location;
-use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Locator;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\FootnotesPrefix;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\FootnotesRemove;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Mutations\ReferencesInline;
@@ -93,7 +92,7 @@ public function getBody(): ?string {
         $start   = $summary?->getEndLine();
         $end     = array_key_last($this->getLines());
         $body    = $start !== null && is_int($end)
-            ? $this->getText(new Locator($start + 1, $end))
+            ? $this->getText(new Location($start + 1, $end))
             : null;
         $body    = trim((string) $body) ?: null;
 
@@ -234,7 +233,7 @@ private function getFirstNode(string $class, ?Closure $filter = null, ?Closure $
 
     private function getBlockText(?AbstractBlock $node): ?string {
         $location = $node?->getStartLine() !== null && $node->getEndLine() !== null
-            ? new Locator($node->getStartLine(), $node->getEndLine())
+            ? new Location($node->getStartLine(), $node->getEndLine())
             : null;
         $text     = $location
             ? $this->getText($location)

packages/documentator/src/Markdown/Editor.php

@@ -84,14 +84,14 @@ public function mutate(array $changes): static {
         $paddings = [];
 
         foreach ($changes as $change) {
-            [$coordinate, $padding, $text] = $change;
-            $line                          = $lines[$coordinate->line] ?? '';
-            $prefix                        = mb_substr($line, 0, $coordinate->offset);
-            $suffix                        = $coordinate->length
+            [$coordinate, $text]         = $change;
+            $line                        = $lines[$coordinate->line] ?? '';
+            $prefix                      = mb_substr($line, 0, $coordinate->offset);
+            $suffix                      = $coordinate->length
                 ? mb_substr($line, $coordinate->offset + $coordinate->length)
                 : '';
-            $lines[$coordinate->line]      = $prefix.$text.$suffix;
-            $paddings[$coordinate->line]   = $padding;
+            $lines[$coordinate->line]    = $prefix.$text.$suffix;
+            $paddings[$coordinate->line] = $coordinate->padding;
 
             if ($text === null && !$suffix) {
                 $lines[$coordinate->line] = trim($prefix);
@@ -136,7 +136,7 @@ public function mutate(array $changes): static {
     /**
      * @param array<array-key, array{Location, ?string}> $changes
      *
-     * @return list<array{Coordinate, int, ?string}>
+     * @return list<array{Coordinate, ?string}>
      */
     protected function expand(array $changes): array {
         $expanded = [];
@@ -153,7 +153,7 @@ protected function expand(array $changes): array {
             usort($coordinates, $sort);
 
             foreach ($coordinates as $coordinate) {
-                $expanded[] = [$coordinate, $location->getPadding(), $text[$line++] ?? null];
+                $expanded[] = [$coordinate, $text[$line++] ?? null];
             }
 
             // If `$text` contains more lines than `$coordinates` that means

packages/documentator/src/Markdown/EditorTest.php

@@ -3,7 +3,7 @@
 namespace LastDragon_ru\LaraASP\Documentator\Markdown;
 
 use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Coordinate;
-use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Locator;
+use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Location;
 use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase;
 use Override;
 use PHPUnit\Framework\Attributes\CoversClass;
@@ -33,11 +33,11 @@ public function testMutate(): void {
         ];
         $editor   = new Editor($lines);
         $changes  = [
-            [new Locator(1, 1, 2, 3), '123'],
-            [new Locator(2, 4, 4, 4), '123'],
-            [new Locator(6, 8, 4, 4), "123\n345"],
-            [new Locator(11, 12, 4, 3, 2), "123\n345"],
-            [new Locator(14, 15, 4, 3, 2), '123'],
+            [new Location(1, 1, 2, 3), '123'],
+            [new Location(2, 4, 4, 4), '123'],
+            [new Location(6, 8, 4, 4), "123\n345"],
+            [new Location(11, 12, 4, 3, 2), "123\n345"],
+            [new Location(14, 15, 4, 3, 2), '123'],
         ];
         $actual   = $editor->mutate($changes);
         $expected = [
@@ -73,19 +73,19 @@ public function removeOverlaps(array $changes): array {
             }
         };
         $changes  = [
-            0 => [new Locator(10, 10, 15, 10), 'a'],
-            1 => [new Locator(10, 10, 10, null), 'b'],
-            2 => [new Locator(12, 15, 5, 10), 'c'],
-            3 => [new Locator(14, 15, 5, 10), 'd'],
-            4 => [new Locator(17, 17, 5, 10), 'e'],
-            5 => [new Locator(17, 17, 11, 10), 'f'],
-            6 => [new Locator(18, 18, 5, 10), 'g'],
+            0 => [new Location(10, 10, 15, 10), 'a'],
+            1 => [new Location(10, 10, 10, null), 'b'],
+            2 => [new Location(12, 15, 5, 10), 'c'],
+            3 => [new Location(14, 15, 5, 10), 'd'],
+            4 => [new Location(17, 17, 5, 10), 'e'],
+            5 => [new Location(17, 17, 11, 10), 'f'],
+            6 => [new Location(18, 18, 5, 10), 'g'],
         ];
         $expected = [
-            1 => [new Locator(10, 10, 10, null), 'b'],
-            3 => [new Locator(14, 15, 5, 10), 'd'],
-            5 => [new Locator(17, 17, 11, 10), 'f'],
-            6 => [new Locator(18, 18, 5, 10), 'g'],
+            1 => [new Location(10, 10, 10, null), 'b'],
+            3 => [new Location(14, 15, 5, 10), 'd'],
+            5 => [new Location(17, 17, 11, 10), 'f'],
+            6 => [new Location(18, 18, 5, 10), 'g'],
         ];
 
         self::assertEquals($expected, $editor->removeOverlaps($changes));
@@ -102,18 +102,18 @@ public function expand(array $changes): array {
             }
         };
         $changes  = [
-            [new Locator(1, 1, 5, 10), 'text'],
-            [new Locator(2, 3, 5, null), 'text'],
-            [new Locator(4, 5, 5, 5, 1), "text a\ntext b"],
-            [new Locator(6, 6, 5, 10, 2), "text a\ntext b"],
+            [new Location(1, 1, 5, 10), 'text'],
+            [new Location(2, 3, 5, null), 'text'],
+            [new Location(4, 5, 5, 5, 1), "text a\ntext b"],
+            [new Location(6, 6, 5, 10, 2), "text a\ntext b"],
         ];
         $expected = [
-            [new Coordinate(6, 7, 10), 2, 'text a'],
-            [new Coordinate(5, 1, 5), 1, 'text b'],
-            [new Coordinate(4, 6, null), 1, 'text a'],
-            [new Coordinate(3, 0, null), 0, null],
-            [new Coordinate(2, 5, null), 0, 'text'],
-            [new Coordinate(1, 5, 10), 0, 'text'],
+            [new Coordinate(6, 7, 10, 2), 'text a'],
+            [new Coordinate(5, 1, 5, 1), 'text b'],
+            [new Coordinate(4, 6, null, 1), 'text a'],
+            [new Coordinate(3, 0, null, 0), null],
+            [new Coordinate(2, 5, null, 0), 'text'],
+            [new Coordinate(1, 5, 10, 0), 'text'],
         ];
 
         self::assertEquals($expected, $editor->expand($changes));
@@ -130,16 +130,16 @@ public function testGetText(): void {
             6 => 'u v w x',
         ]);
 
-        self::assertNull($editor->getText(new Locator(25, 25, 0)));
-        self::assertEquals('f g', $editor->getText(new Locator(1, 1, 2, 3)));
+        self::assertNull($editor->getText(new Location(25, 25, 0)));
+        self::assertEquals('f g', $editor->getText(new Location(1, 1, 2, 3)));
         self::assertEquals(
             <<<'TEXT'
             k l
             m n o p
 
             q r s
             TEXT,
-            $editor->getText(new Locator(2, 5, 4, 5)),
+            $editor->getText(new Location(2, 5, 4, 5)),
         );
         self::assertEquals(
             <<<'TEXT'

packages/documentator/src/Markdown/Location/Coordinate.php

@@ -7,6 +7,7 @@ public function __construct(
         public int $line,
         public int $offset,
         public ?int $length,
+        public int $padding = 0,
     ) {
         // empty
     }

packages/documentator/src/Markdown/Location/Location.php

@@ -3,10 +3,61 @@
 namespace LastDragon_ru\LaraASP\Documentator\Markdown\Location;
 
 use IteratorAggregate;
+use Override;
+use Traversable;
 
 /**
- * @extends IteratorAggregate<array-key, Coordinate>
+ * @implements IteratorAggregate<array-key, Coordinate>
  */
-interface Location extends IteratorAggregate {
-    public function getPadding(): int;
+readonly class Location implements IteratorAggregate {
+    public function __construct(
+        public int $startLine,
+        public int $endLine,
+        public int $offset = 0,
+        public ?int $length = null,
+        public int $startLinePadding = 0,
+        public ?int $internalPadding = null,
+    ) {
+        // empty
+    }
+
+    /**
+     * @return Traversable<array-key, Coordinate>
+     */
+    #[Override]
+    public function getIterator(): Traversable {
+        if ($this->startLine === $this->endLine) {
+            yield new Coordinate(
+                $this->startLine,
+                $this->startLinePadding + $this->offset,
+                $this->length,
+                $this->startLinePadding,
+            );
+        } else {
+            for ($line = $this->startLine; $line <= $this->endLine; $line++) {
+                yield match (true) {
+                    $line === $this->startLine => new Coordinate(
+                        $line,
+                        $this->startLinePadding + $this->offset,
+                        null,
+                        $this->startLinePadding,
+                    ),
+                    $line === $this->endLine   => new Coordinate(
+                        $line,
+                        $this->internalPadding ?? $this->startLinePadding,
+                        $this->length,
+                        $this->internalPadding ?? $this->startLinePadding,
+                    ),
+                    default                    => new Coordinate(
+                        $line,
+                        $this->internalPadding ?? $this->startLinePadding,
+                        null,
+                        $this->internalPadding ?? $this->startLinePadding,
+                    ),
+                };
+            }
+        }
+
+        yield from [];
+    }
 }

packages/documentator/src/Markdown/Location/LocationTest.php

@@ -0,0 +1,51 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Markdown\Location;
+
+use LastDragon_ru\LaraASP\Documentator\Testing\Package\TestCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+use function iterator_to_array;
+
+/**
+ * @internal
+ */
+#[CoversClass(Location::class)]
+final class LocationTest extends TestCase {
+    public function testGetIterator(): void {
+        self::assertEquals(
+            [
+                new Coordinate(1, 0, null, 0),
+            ],
+            iterator_to_array(new Location(1, 1)),
+        );
+        self::assertEquals(
+            [
+                new Coordinate(1, 10, 10, 0),
+            ],
+            iterator_to_array(new Location(1, 1, 10, 10)),
+        );
+        self::assertEquals(
+            [
+                new Coordinate(1, 12, 10, 2),
+            ],
+            iterator_to_array(new Location(1, 1, 10, 10, 2, 4)),
+        );
+        self::assertEquals(
+            [
+                new Coordinate(1, 12, null, 2),
+                new Coordinate(2, 2, null, 2),
+                new Coordinate(3, 2, 10, 2),
+            ],
+            iterator_to_array(new Location(1, 3, 10, 10, 2, null)),
+        );
+        self::assertEquals(
+            [
+                new Coordinate(1, 12, null, 2),
+                new Coordinate(2, 4, null, 4),
+                new Coordinate(3, 4, 10, 4),
+            ],
+            iterator_to_array(new Location(1, 3, 10, 10, 2, 4)),
+        );
+    }
+}

packages/documentator/src/Markdown/Mutations/FootnotesPrefix.php

@@ -5,7 +5,6 @@
 use LastDragon_ru\LaraASP\Documentator\Markdown\Contracts\Mutation;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Document;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Location;
-use LastDragon_ru\LaraASP\Documentator\Markdown\Location\Locator;
 use LastDragon_ru\LaraASP\Documentator\Markdown\Utils;
 use League\CommonMark\Extension\Footnote\Node\Footnote;
 use League\CommonMark\Extension\Footnote\Node\FootnoteRef;
@@ -93,6 +92,6 @@ private function getLabelLocation(Footnote|FootnoteRef $footnote, string $label)
         $offset    = $coordinate->offset + 2;
         $length    = mb_strlen($label);
 
-        return new Locator($startLine, $endLine, $offset, $length);
+        return new Location($startLine, $endLine, $offset, $length);
     }
 }