Reorganize kernel

Author: SerafimArts

README.md

@@ -9,9 +9,12 @@
     <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/version?style=for-the-badge" alt="Latest Stable Version"></a>
     <a href="https://packagist.org/packages/type-lang/phpdoc"><img src="https://poser.pugx.org/type-lang/phpdoc/v/unstable?style=for-the-badge" alt="Latest Unstable Version"></a>
     <a href="https://raw.githubusercontent.com/php-type-language/phpdoc/blob/master/LICENSE"><img src="https://poser.pugx.org/type-lang/phpdoc/license?style=for-the-badge" alt="License MIT"></a>
+    <a href="https://github.com/xepozz/meta-storm-idea-plugin"><img src="https://img.shields.io/static/v1?label=Powered+by&message=Meta+Storm&color=db5860&style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iMTExIiBoZWlnaHQ9IjExMSIgdmlld0JveD0iMCAwIDExMSAxMTEiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTYwLjQ2MTcgOEwzMC4xNjU0IDguMjQ3OUMyNy4yNDYgOC4yNzE3OSAyNC42NDggMTAuMTA1IDIzLjY0NyAxMi44NDc1TDAuNDMwNTkgNzYuODMxNEMtMS4yNDQ1OSA4MS40MjA4IDIuMTc4MDUgODYuMjcxMyA3LjA2MzUzIDg2LjIzMTNMMzIuMTE5NyA4Ni4wMjYzTDM1LjQxNDcgNzYuOTk5TDkuODczOTEgNzcuMjA4TDMxLjYyNTkgMTcuMjM2Mkw1Ny4xNjY2IDE3LjAyNzNMNjAuNDYxNyA4WiIgZmlsbD0iI0FGQjFCMyIvPjxwYXRoIGQ9Ik00OS40MTQ5IDEwMi45OTlMNzkuNzEyMiAxMDIuOTk5QzgyLjYzMTcgMTAyLjk5OSA4NS4yNDQ2IDEwMS4xODcgODYuMjY4IDk4LjQ1MjlMMTEwLjAxMyAzNC40NTI0QzExMS43MjYgMjkuODc2OCAxMDguMzQzIDI0Ljk5ODUgMTAzLjQ1NyAyNC45OTg1TDc4LjQwMDQgMjQuOTk4NUw3NS4wMzE2IDMzLjk5ODVMMTAwLjU3MyAzMy45OTg1TDc4LjMyNTMgOTMuOTk5TDUyLjc4MzcgOTMuOTk5TDQ5LjQxNDkgMTAyLjk5OVoiIGZpbGw9IiNBRkIxQjMiLz48cGF0aCBkPSJNMjIgNjFMODYgOEw1NyA1MEw4OS45OTk3IDQ5Ljk5OTdMMjYgMTAzTDU1IDYxSDIyWiIgZmlsbD0iI0M3NTQ1MCIvPjwvc3ZnPg==" alt="MetaStorm"></a>
 </p>
 <p align="center">
-    <a href="https://github.com/php-type-language/phpdoc/actions"><img src="https://github.com/php-type-language/phpdoc/workflows/tests/badge.svg"></a>
+    <a href="https://github.com/php-type-language/phpdoc/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/php-type-language/phpdoc/tests.yml?label=Tests&style=flat-square&logo=unpkg"></a>
+    <a href="https://github.com/php-type-language/phpdoc/actions/workflows/codestyle.yml"><img src="https://img.shields.io/github/actions/workflow/status/php-type-language/phpdoc/codestyle.yml?label=PER-2+CodeStyle&style=flat-square&logo=telegraph"></a>
+    <a href="https://github.com/php-type-language/phpdoc/actions/workflows/static-analysis.yml"><img src="https://img.shields.io/github/actions/workflow/status/php-type-language/phpdoc/static-analysis.yml?label=PHPStan&style=flat-square&logo=data:image/png;base64,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"></a>
 </p>
 
 Reference implementation for TypeLang PHPDoc Parser.
@@ -45,12 +48,13 @@ var_dump($result);
 ```
 
 **Expected Output:**
+
 ```php
 TypeLang\PHPDoc\DocBlock {
-  -description: TypeLang\PHPDoc\Tag\Description\Description {
+  -description: TypeLang\PHPDoc\DocBlock\Description\Description {
     -template: "Example description %1$s and blah-blah-blah."
     -tags: array:1 [
-      0 => TypeLang\PHPDoc\Tag\Tag {
+      0 => TypeLang\PHPDoc\DocBlock\Tag {
         #description: TypeLang\PHPDoc\Tag\Description\Description {
           -template: "some"
           -tags: []
@@ -60,21 +64,21 @@ TypeLang\PHPDoc\DocBlock {
     ]
   }
   -tags: array:3 [
-    0 => TypeLang\PHPDoc\Tag\Tag {
+    0 => TypeLang\PHPDoc\DocBlock\Tag {
       #description: TypeLang\PHPDoc\Tag\Description\Description {
         -template: "("foo")"
         -tags: []
       }
       #name: "Example\Annotation"
     }
-    1 => TypeLang\PHPDoc\Tag\Tag {
+    1 => TypeLang\PHPDoc\DocBlock\Tag {
       #description: TypeLang\PHPDoc\Tag\Description\Description {
         -template: "array<non-empty-string, TypeStatement>"
         -tags: []
       }
       #name: "return"
     }
-    2 => TypeLang\PHPDoc\Tag\Tag {
+    2 => TypeLang\PHPDoc\DocBlock\Tag {
       #description: TypeLang\PHPDoc\Tag\Description\Description {
         -template: "\Throwable"
         -tags: []

composer.json

@@ -12,13 +12,18 @@
         "php": "^8.1",
         "type-lang/parser": "^1.4"
     },
+    "replace": {
+        "type-lang/phpdoc-docblock": "*"
+    },
     "autoload": {
         "psr-4": {
-            "TypeLang\\PHPDoc\\": "src"
+            "TypeLang\\PHPDoc\\": "src",
+            "TypeLang\\PHPDoc\\DocBlock\\": "libs/phpdoc-docblock/src"
         }
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.70",
+        "phpdocumentor/reflection-docblock": "^5.6",
         "phpstan/phpstan": "^2.1",
         "phpstan/phpstan-strict-rules": "^2.0",
         "phpunit/phpunit": "^10.5|^11.0|^12.0",
@@ -27,8 +32,12 @@
     },
     "autoload-dev": {
         "psr-4": {
+            "TypeLang\\PHPDoc\\DocBlock\\Tests\\": "libs/phpdoc-docblock/tests",
             "TypeLang\\PHPDoc\\Tests\\": "tests"
-        }
+        },
+        "files": [
+            "libs/phpdoc-docblock/src/polyfill.php"
+        ]
     },
     "extra": {
         "branch-alias": {
@@ -46,18 +55,18 @@
         }
     },
     "scripts": {
-        "test": ["@test:unit", "@test:functional"],
+        "test": [
+            "@test:unit",
+            "@test:functional"
+        ],
         "test:unit": "phpunit --testdox --testsuite=unit",
         "test:functional": "phpunit --testsuite=functional",
-
         "linter": "@linter:check",
         "linter:check": "phpstan analyse --configuration phpstan.neon",
         "linter:baseline": "phpstan analyse --configuration phpstan.neon --generate-baseline",
-
         "phpcs": "@phpcs:check",
         "phpcs:check": "php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --dry-run --verbose --diff",
         "phpcs:fix": "php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --verbose --diff",
-
         "dev:merge": "monorepo-builder merge"
     },
     "minimum-stability": "dev",

libs/phpdoc-docblock/composer.json

@@ -0,0 +1,65 @@
+{
+    "name": "type-lang/phpdoc-docblock",
+    "type": "library",
+    "keywords": ["language", "php", "phpdoc", "docblock", "tags", "dictionary"],
+    "license": "MIT",
+    "support": {
+        "source": "https://github.com/php-type-language/phpdoc-docblock",
+        "issues": "https://github.com/php-type-language/phpdoc-docblock/issues"
+    },
+    "require": {
+        "php": "^8.1",
+        "type-lang/parser": "^1.4"
+    },
+    "autoload": {
+        "psr-4": {
+            "TypeLang\\PHPDoc\\DocBlock\\": "src"
+        },
+        "files": [
+            "src/polyfill.php"
+        ]
+    },
+    "require-dev": {
+        "friendsofphp/php-cs-fixer": "^3.70",
+        "phpstan/phpstan": "^2.1",
+        "phpstan/phpstan-strict-rules": "^2.0",
+        "phpunit/phpunit": "^10.5|^11.0|^12.0",
+        "symfony/var-dumper": "^5.4|^6.0|^7.0",
+        "phpdocumentor/reflection-docblock": "^5.6"
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "TypeLang\\PHPDoc\\DocBlock\\Tests\\": "tests"
+        }
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-master": "1.x-dev",
+            "dev-main": "1.x-dev"
+        }
+    },
+    "config": {
+        "sort-packages": true,
+        "platform-check": true,
+        "bin-compat": "full",
+        "optimize-autoloader": true,
+        "preferred-install": {
+            "*": "dist"
+        }
+    },
+    "scripts": {
+        "test": ["@test:unit", "@test:functional"],
+        "test:unit": "phpunit --testdox --testsuite=unit",
+        "test:functional": "phpunit --testsuite=functional",
+
+        "linter": "@linter:check",
+        "linter:check": "phpstan analyse --configuration phpstan.neon",
+        "linter:baseline": "phpstan analyse --configuration phpstan.neon --generate-baseline",
+
+        "phpcs": "@phpcs:check",
+        "phpcs:check": "php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --dry-run --verbose --diff",
+        "phpcs:fix": "php-cs-fixer fix --config=.php-cs-fixer.php --allow-risky=yes --verbose --diff"
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

src/Tag/Description/Description.php renamed to libs/phpdoc-docblock/src/Description/Description.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag\Description;
+namespace TypeLang\PHPDoc\DocBlock\Description;
 
 class Description implements DescriptionInterface
 {
@@ -30,11 +30,15 @@ public static function fromStringable(string|\Stringable $description): Descript
      */
     public static function fromStringableOrNull(string|\Stringable|null $description): ?DescriptionInterface
     {
-        if ($description === null) {
+        if ($description instanceof DescriptionInterface) {
+            return $description;
+        }
+
+        if ($description === null || ((string) $description) === '') {
             return null;
         }
 
-        return self::fromStringable($description);
+        return new self($description);
     }
 
     public function __toString(): string

src/Tag/Description/DescriptionInterface.php renamed to libs/phpdoc-docblock/src/Description/DescriptionInterface.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag\Description;
+namespace TypeLang\PHPDoc\DocBlock\Description;
 
 /**
  * Any class that implements this interface is a description object

libs/phpdoc-docblock/src/Description/DescriptionProviderInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Description;
+
+/**
+ * Representation of any entry that contain an description.
+ */
+interface DescriptionProviderInterface extends OptionalDescriptionProviderInterface
+{
+    /**
+     * Gets description object which can be represented as a {@see string}
+     * and contains additional information.
+     *
+     * @readonly
+     */
+    public DescriptionInterface $description { get; }
+}

libs/phpdoc-docblock/src/Description/OptionalDescriptionProviderInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Description;
+
+/**
+ * Representation of any entry that MAY contain an optional description.
+ */
+interface OptionalDescriptionProviderInterface
+{
+    /**
+     * Gets optional description object which can be represented as
+     * a {@see string} and contains additional information or {@see null}
+     * in case of description is not defined in the entry.
+     *
+     * @readonly
+     */
+    public ?DescriptionInterface $description { get; }
+}

src/Tag/Description/TaggedDescription.php renamed to libs/phpdoc-docblock/src/Description/TaggedDescription.php

@@ -2,13 +2,13 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag\Description;
+namespace TypeLang\PHPDoc\DocBlock\Description;
 
-use TypeLang\PHPDoc\Tag\TagInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\TagInterface;
 
 /**
- * @template-implements \ArrayAccess<array-key, TagInterface|DescriptionInterface|null>
- * @template-implements \IteratorAggregate<array-key, TagInterface|DescriptionInterface>
+ * @template-implements \ArrayAccess<array-key, TagInterface|null>
+ * @template-implements \IteratorAggregate<array-key, TagInterface>
  */
 class TaggedDescription implements
     TaggedDescriptionInterface,
@@ -18,54 +18,48 @@ class TaggedDescription implements
     /**
      * @var list<TagInterface|DescriptionInterface>
      */
-    private readonly array $components;
+    public readonly array $components;
+
+    /**
+     * @var list<TagInterface>
+     */
+    public readonly array $tags;
 
     /**
      * @param iterable<array-key, TagInterface|DescriptionInterface> $components
      */
     public function __construct(iterable $components = [])
     {
         $this->components = \array_values([...$components]);
+
+        $this->tags = $this->getTagsFromComponents($this->components);
     }
 
     /**
-     * @return list<TagInterface|DescriptionInterface>
+     * @param iterable<mixed, object> $components
+     * @return list<TagInterface>
      */
-    public function getComponents(): iterable
+    private function getTagsFromComponents(iterable $components): array
     {
-        return $this->components;
-    }
+        $result = [];
 
-    public function getTags(): iterable
-    {
-        foreach ($this->components as $component) {
+        foreach ($components as $component) {
             if ($component instanceof TagInterface) {
-                yield $component;
+                $result[] = $component;
             }
         }
-    }
 
-    public function getIterator(): \Traversable
-    {
-        return new \ArrayIterator($this->components);
-    }
-
-    /**
-     * @return int<0, max>
-     */
-    public function count(): int
-    {
-        return \count($this->components);
+        return $result;
     }
 
     public function offsetExists(mixed $offset): bool
     {
-        return isset($this->components[$offset]);
+        return isset($this->tags[$offset]);
     }
 
-    public function offsetGet(mixed $offset): TagInterface|DescriptionInterface|null
+    public function offsetGet(mixed $offset): ?TagInterface
     {
-        return $this->components[$offset] ?? null;
+        return $this->tags[$offset] ?? null;
     }
 
     /**
@@ -84,8 +78,29 @@ public function offsetUnset(mixed $offset): void
         throw new \BadMethodCallException(static::class . ' objects are immutable');
     }
 
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator($this->tags);
+    }
+
+    /**
+     * @return int<0, max>
+     */
+    public function count(): int
+    {
+        return \count($this->tags);
+    }
+
     public function __toString(): string
     {
-        return \implode('', $this->components);
+        $result = [];
+
+        foreach ($this->components as $component) {
+            $result[] = $component instanceof TagInterface
+                ? \sprintf('{%s}', $component)
+                : $component;
+        }
+
+        return \implode('', $result);
     }
 }