refactor(documentator)!: Markdown locations detection (#218)

composer.json

@@ -72,6 +72,7 @@
     "phpstan/phpdoc-parser": "^2.0.0",
     "phpstan/phpstan": "^2.1.1",
     "phpunit/phpunit": "^10.5.0|^11.0.0",
+    "psr/event-dispatcher": "^1.0",
     "psr/http-message": "^1.0.0|^2.0.0",
     "sebastian/comparator": "^5.0|^6.0.0",
     "sebastian/exporter": "^5.0|^6.0.0",

packages/documentator/composer.json

@@ -31,6 +31,7 @@
     "league/config": "^1.1.1",
     "nikic/php-parser": "^5.4.0",
     "phpstan/phpdoc-parser": "^2.0.0",
+    "psr/event-dispatcher": "^1.0",
     "symfony/console": "^7.0.0",
     "symfony/deprecation-contracts": "^3.0.0",
     "symfony/filesystem": "^7.0.0",

packages/documentator/src/Editor/Locations/Location.php

@@ -62,6 +62,9 @@ public function getIterator(): Traversable {
         yield from [];
     }
 
+    /**
+     * @return new<self>
+     */
     public function withOffset(int $offset): self {
         return new self(
             $this->startLine,
@@ -73,6 +76,9 @@ public function withOffset(int $offset): self {
         );
     }
 
+    /**
+     * @return new<self>
+     */
     public function withLength(?int $length): self {
         return new self(
             $this->startLine,

packages/documentator/src/Markdown/Data/Content.php

@@ -0,0 +1,13 @@
+<?php declare(strict_types = 1);
+
+namespace LastDragon_ru\LaraASP\Documentator\Markdown\Data;
+
+use LastDragon_ru\LaraASP\Documentator\Editor\Locations\Location;
+
+/**
+ * @internal
+ * @extends Data<Location>
+ */
+readonly class Content extends Data {
+    // empty
+}

packages/documentator/src/Markdown/Data/Data.php

@@ -3,6 +3,7 @@
 namespace LastDragon_ru\LaraASP\Documentator\Markdown\Data;
 
 use LastDragon_ru\LaraASP\Documentator\Markdown\Exceptions\DataMissed;
+use LastDragon_ru\LaraASP\Documentator\Package;
 use League\CommonMark\Node\Node;
 
 use function is_a;
@@ -26,7 +27,7 @@ final public function __construct(
      * @return T
      */
     public static function get(Node $node): mixed {
-        $data  = $node->data->get(static::class, null);
+        $data  = $node->data->get(Package::Name.'.'.static::class, null);
         $value = is_object($data) && is_a($data, static::class, true)
             ? $data->value
             : static::default($node);
@@ -55,7 +56,7 @@ public static function optional(): Optional {
      * @return T
      */
     public static function set(Node $node, mixed $value): mixed {
-        $node->data->set(static::class, new static($value));
+        $node->data->set(Package::Name.'.'.static::class, new static($value));
 
         return $value;
     }

packages/documentator/src/Markdown/Data/Lines.php

@@ -9,7 +9,7 @@
 
 /**
  * @internal
- * @extends Data<array<array-key, string>>
+ * @extends Data<array<int, string>>
  */
 readonly class Lines extends Data {
     #[Override]

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

@@ -3,37 +3,11 @@
 namespace LastDragon_ru\LaraASP\Documentator\Markdown\Data;
 
 use LastDragon_ru\LaraASP\Documentator\Editor\Locations\Location as LocationContract;
-use LastDragon_ru\LaraASP\Documentator\Markdown\Utils;
-use League\CommonMark\Node\Block\AbstractBlock;
-use League\CommonMark\Node\Block\Document;
-use League\CommonMark\Node\Node;
-use Override;
 
 /**
  * @internal
  * @extends Data<LocationContract>
  */
 readonly class Location extends Data {
-    #[Override]
-    protected static function default(Node $node): mixed {
-        $location = null;
-
-        if ($node instanceof AbstractBlock) {
-            $start   = $node->getStartLine();
-            $end     = $node->getEndLine();
-            $offset  = Offset::optional()->get($node) ?? 0;
-            $length  = Length::optional()->get($node);
-            $padding = Utils::getPadding($node, null, null);
-
-            if ($padding === null && $node->parent() instanceof Document) {
-                $padding = 0;
-            }
-
-            if ($start !== null && $end !== null && $padding !== null) {
-                $location = new LocationContract($start, $end, $offset, $length, $padding);
-            }
-        }
-
-        return $location;
-    }
+    // empty
 }

packages/documentator/src/Markdown/Document.php

@@ -114,7 +114,7 @@ public function mutate(Mutation ...$mutations): self {
     }
 
     /**
-     * @return array<array-key, string>
+     * @return array<int, string>
      */
     protected function getLines(): array {
         return Lines::get($this->node);

packages/documentator/src/Markdown/Extensions/Aware.php → packages/documentator/src/Markdown/Environment/Aware.php

@@ -1,6 +1,6 @@
 <?php declare(strict_types = 1);
 
-namespace LastDragon_ru\LaraASP\Documentator\Markdown\Extensions;
+namespace LastDragon_ru\LaraASP\Documentator\Markdown\Environment;
 
 use League\CommonMark\Environment\EnvironmentAwareInterface;
 use League\CommonMark\Environment\EnvironmentInterface;
@@ -17,7 +17,7 @@
 trait Aware {
     #[Override]
     public function setEnvironment(EnvironmentInterface $environment): void {
-        $object = $this->getObject();
+        $object = $this->getParser();
 
         if ($object instanceof EnvironmentAwareInterface) {
             $object->setEnvironment($environment);
@@ -26,12 +26,12 @@ public function setEnvironment(EnvironmentInterface $environment): void {
 
     #[Override]
     public function setConfiguration(ConfigurationInterface $configuration): void {
-        $object = $this->getObject();
+        $object = $this->getParser();
 
         if ($object instanceof ConfigurationAwareInterface) {
             $object->setConfiguration($configuration);
         }
     }
 
-    abstract protected function getObject(): object;
+    abstract protected function getParser(): object;
 }