Add invalid tags support

Author: Kirill Nesmeyanov

src/Exception/ParsingException.php

@@ -47,7 +47,7 @@ public function withSource(string $source, int $offset): self
             offset: $offset,
             message: $this->message,
             code: $this->code,
-            previous: $this->getPrevious(),
+            previous: $this,
         );
     }
 

src/Parser.php

@@ -5,6 +5,8 @@
 namespace TypeLang\PHPDoc;
 
 use JetBrains\PhpStorm\Language;
+use TypeLang\PHPDoc\Exception\InvalidTagException;
+use TypeLang\PHPDoc\Exception\InvalidTagNameException;
 use TypeLang\PHPDoc\Exception\ParsingException;
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Comment\CommentParserInterface;

src/Parser/Tag/TagParser.php

@@ -9,6 +9,7 @@
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 use TypeLang\PHPDoc\Tag\Factory\FactoryInterface;
 use TypeLang\PHPDoc\Tag\Content;
+use TypeLang\PHPDoc\Tag\InvalidTag;
 use TypeLang\PHPDoc\Tag\TagInterface;
 
 final class TagParser implements TagParserInterface
@@ -66,7 +67,14 @@ private function getTagName(string $content): string
      */
     public function parse(string $tag, DescriptionParserInterface $parser): TagInterface
     {
-        $name = $this->getTagName($tag);
+        try {
+            $name = $this->getTagName($tag);
+        } catch (InvalidTagNameException $e) {
+            return new InvalidTag($e, $parser->parse(
+                description: \substr($tag, 1),
+            ));
+        }
+
         /** @var non-empty-string $name */
         $name = \substr($name, 1);
 

src/Tag/Content.php

@@ -17,7 +17,7 @@
 
 class Content implements \Stringable
 {
-    private readonly string $original;
+    public readonly string $source;
 
     /**
      * @var int<0, max>
@@ -28,7 +28,7 @@ class Content implements \Stringable
     public function __construct(
         public string $value,
     ) {
-        $this->original = $this->value;
+        $this->source = $this->value;
     }
 
     /**
@@ -54,7 +54,7 @@ public function shift(int $offset, bool $ltrim = true): void
     public function getTagException(string $message, \Throwable $previous = null): InvalidTagException
     {
         return new InvalidTagException(
-            source: $this->original,
+            source: $this->source,
             offset: $this->offset,
             message: $message,
             previous: $previous,

src/Tag/Factory/TagFactory.php

@@ -8,6 +8,7 @@
 use TypeLang\PHPDoc\Exception\ParsingException;
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\InvalidTag;
 use TypeLang\PHPDoc\Tag\Tag;
 use TypeLang\PHPDoc\Tag\Content;
 use TypeLang\PHPDoc\Tag\TagInterface;
@@ -34,21 +35,22 @@ public function create(string $name, Content $content, DescriptionParserInterfac
 
         if ($delegate !== null) {
             try {
-                return $delegate->create($name, $content, $descriptions);
-            } catch (ParsingException $e) {
-                throw $e;
+                try {
+                    return $delegate->create($name, $content, $descriptions);
+                } catch (RuntimeExceptionInterface $e) {
+                    throw $e;
+                } catch (\Throwable $e) {
+                    throw InvalidTagException::fromCreatingTag(
+                        tag: $name,
+                        source: $content->value,
+                        prev: $e,
+                    );
+                }
             } catch (RuntimeExceptionInterface $e) {
-                throw InvalidTagException::fromCreatingTag(
-                    tag: $name,
-                    source: $e->getSource(),
-                    offset: $e->getOffset(),
-                    prev: $e,
-                );
-            } catch (\Throwable $e) {
-                throw InvalidTagException::fromCreatingTag(
-                    tag: $name,
-                    source: $content->value,
-                    prev: $e,
+                return new InvalidTag(
+                    reason: $e,
+                    description: $descriptions->parse($content->source),
+                    name: $name,
                 );
             }
         }

src/Tag/InvalidTag.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+final class InvalidTag extends Tag
+{
+    /**
+     * @var non-empty-string
+     */
+    public const DEFAULT_UNKNOWN_TAG_NAME = '<unknown>';
+
+    /**
+     * @param non-empty-string $name
+     */
+    public function __construct(
+        protected readonly \Throwable $reason,
+        \Stringable|string|null $description = null,
+        string $name = self::DEFAULT_UNKNOWN_TAG_NAME,
+    ) {
+        parent::__construct($name, $description);
+    }
+
+    public function getReason(): \Throwable
+    {
+        return $this->reason;
+    }
+
+    public function __toString(): string
+    {
+        $name = $this->name === self::DEFAULT_UNKNOWN_TAG_NAME ? '' : $this->name;
+
+        if ($this->description === null) {
+            return \sprintf('@%s', $name);
+        }
+
+        return \rtrim(\vsprintf('@%s %s', [
+            $name,
+            (string) $this->description,
+        ]));
+    }
+}