Implement phpstan doc parsing

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased] - yyyy-mm-dd
 
-- Drop PHP 7.4, PHP 8.0
+- Drop PHP 7.4, PHP 8.0, require PHP >= `8.1`
 - Attempt to reload the current page in a newly-selected version
 - Support PHPUnit 10, 11 and 12
 - Drop PHPUnit 7 and 8

README.rst

@@ -23,7 +23,7 @@ Installation
 
 .. caution::
 
-    Doctum requires **PHP 7.2.20** or later.
+    Doctum requires **PHP 8.1** or later.
 
 Get Doctum as a `phar file`_:
 

composer.json

@@ -44,8 +44,7 @@
         "symfony/yaml": "^6.4.26||^7.3",
         "symfony/string": "^6.4.26||^7.3",
         "symfony/process": "^6.4.26||^7.3",
-        "phpdocumentor/reflection-docblock": "~5.3",
-        "phpdocumentor/type-resolver": "1.6.*",
+        "phpdocumentor/reflection-docblock": "^5.6.3",
         "wdes/php-i18n-l10n": "^4.2",
         "code-lts/cli-tools": "^1.6",
         "league/commonmark": "^2.7"

phpstan-baseline.neon

@@ -225,7 +225,7 @@ parameters:
 		-
 			message: '#^Call to an undefined method PhpParser\\Node\\ComplexType\|PhpParser\\Node\\Identifier\|PhpParser\\Node\\Name\:\:__toString\(\)\.$#'
 			identifier: method.notFound
-			count: 1
+			count: 2
 			path: src/Parser/NodeVisitor.php
 
 		-
@@ -360,6 +360,12 @@ parameters:
 			count: 1
 			path: src/Parser/NodeVisitor.php
 
+		-
+			message: '#^Method Doctum\\Parser\\NodeVisitor\:\:typeToArray\(\) return type has no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
+			count: 1
+			path: src/Parser/NodeVisitor.php
+
 		-
 			message: '#^Method Doctum\\Parser\\NodeVisitor\:\:updateMethodParametersFromTags\(\) has parameter \$tags with no value type specified in iterable type array\.$#'
 			identifier: missingType.iterableValue
@@ -2388,6 +2394,12 @@ parameters:
 			count: 1
 			path: tests/Parser/DocBlockParserTest.php
 
+		-
+			message: '#^Method Doctum\\Tests\\Parser\\DocBlockParserTest\:\:getInvalidTagsForErrors\(\) return type has no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
+			count: 1
+			path: tests/Parser/DocBlockParserTest.php
+
 		-
 			message: '#^Method Doctum\\Tests\\Parser\\DocBlockParserTest\:\:getParseTests\(\) return type has no value type specified in iterable type array\.$#'
 			identifier: missingType.iterableValue
@@ -2400,6 +2412,12 @@ parameters:
 			count: 1
 			path: tests/Parser/DocBlockParserTest.php
 
+		-
+			message: '#^Method Doctum\\Tests\\Parser\\DocBlockParserTest\:\:testParseReportErrors\(\) has parameter \$expected with no value type specified in iterable type array\.$#'
+			identifier: missingType.iterableValue
+			count: 1
+			path: tests/Parser/DocBlockParserTest.php
+
 		-
 			message: '#^Method Doctum\\Tests\\Parser\\DocBlockParserTest\:\:testParseWithAliases\(\) has parameter \$expected with no value type specified in iterable type array\.$#'
 			identifier: missingType.iterableValue

src/Parser/DocBlockParser.php

@@ -75,7 +75,22 @@ public function parse(?string $comment, ParserContext $context): DocBlockNode
         $result->setLongDesc($docBlock->getDescription()->__toString());
 
         foreach ($docBlock->getTags() as $tag) {
-            $result->addTag($tag->getName(), $this->parseTag($tag));
+            $tagName = $tag->getName();
+
+            if ($tag instanceof InvalidTag && $tag->getException() !== null) {
+                $errorMessage = 'Invalid @return tag "' . $tag->__toString() . '" (' . $tag->getException()->getMessage() . ').';
+                $result->addError($errorMessage);
+            } elseif ($tag instanceof InvalidTag) {
+                $errorMessage = 'Invalid @return tag "' . $tag->__toString() . '".';
+                $result->addError($errorMessage);
+            }
+
+            if ($tag instanceof InvalidTag && str_starts_with($tagName, '@')) {
+                // remove the @
+                $tagName = substr($tagName, 1);
+            }
+
+            $result->addTag($tagName, $this->parseTag($tag));
         }
 
         return $result;

src/Parser/NodeVisitor.php

@@ -178,7 +178,7 @@ protected function typeToArray($type): array
             }
             $typeArray[] = [$typeAsStr, false];
         } elseif ($type instanceof NullableType) {
-            $typeArray = array_merge($typeArray, $this->typeToArray($type->type));
+            $typeArray   = array_merge($typeArray, $this->typeToArray($type->type));
             $typeArray[] = ['null', false];
         } elseif ($type instanceof UnionType || $type instanceof IntersectionType) {
             foreach ($type->types as $subType) {

tests/Parser/DocBlockParserTest.php

@@ -29,6 +29,52 @@ class DocBlockParserTest extends TestCase
         'SomeClass' => '\\Foo\\SomeClass',
     ];
 
+    /**
+     * @dataProvider getInvalidTagsForErrors
+     */
+    #[\PHPUnit\Framework\Attributes\DataProvider('getInvalidTagsForErrors')]
+    public function testParseReportErrors(string $comment, array $expected): void
+    {
+        $parser = new DocBlockParser();
+        $parsed = $parser->parse($comment, $this->getContextMock());
+        $this->assertEquals($expected, $parsed->getErrors());
+    }
+
+    public static function getInvalidTagsForErrors(): array
+    {
+        return [
+            'Check for a known invalid format' => [
+                '
+                /**
+                 * @return array, $message Foo bar
+                 */
+                ',
+                [
+                    'Invalid @return tag "array, $message Foo bar".',
+                ],
+            ],
+            'Check for non closed array shape' => [
+                '
+                /**
+                 * @return array{key1: string
+                 */
+                ',
+                [
+                    'Invalid @return tag "array{key1: string".',
+                ],
+            ],
+            'Check array shape is okay' => [
+                '
+                /**
+                 * @return array{key1: string}
+                 */
+                ',
+                [
+                ],
+            ],
+        ];
+    }
+
     /**
      * @dataProvider getParseTests
      */
@@ -301,7 +347,7 @@ public static function getParseTests(): array
                     ],
                 ],
             ],
-            [
+            'Test that @throws with a dot at the end works' => [
                 '
                 /**
                  * @throws \InvalidArgumentException.
@@ -314,8 +360,14 @@ public static function getParseTests(): array
                         'longDesc' => '',
                         'tags' => [
                             'throws' => [
-                                '\InvalidArgumentException.',
-                                '\Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException.',
+                                [
+                                    '\InvalidArgumentException',
+                                    '',
+                                ],
+                                [
+                                    '\Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException',
+                                    '',
+                                ],
                             ],
                         ],
                     ],
@@ -597,15 +649,15 @@ public static function getParseTests(): array
                     ],
                 ]],
             ],
-            [
+            'Test that invalid @return format also works' => [
                 '/**
          * Prepares queries for adding users and
          * also create database and return query and message
          *
          * @param boolean $_error               whether user create or not
          * @param string  $real_sql_query       SQL query for add a user
          *
-         * @return array, $message
+         * @return array $message
          */',
                 [[
                     'shortDesc' => "Prepares queries for adding users and\nalso create database and return query and message",
@@ -633,8 +685,12 @@ public static function getParseTests(): array
                                 'SQL query for add a user',
                             ],
                         ],
-                        'return' => [
-                            'array, $message',
+
+                        'return' => [ // Array from found tags.
+                            [ // First found tag.
+                                [['array', false]], // Array from data types.
+                                '$message', // The description
+                            ],
                         ],
                     ],
                 ]],

tests/Parser/NodeVisitorTest.php

@@ -456,7 +456,7 @@ public function testUpdateMethodParametersFromInvalidTags(): void
             . '* @param $param9' . "\n"
             . '* @param foo' . "\n"
             . '* @param type1 $param4 Description 4' . "\n"
-            . '* @param array[\Illuminate\Notifications\Channels\Notification]  $notification' . "\n"
+            . '* @param array[\Illuminate\Notifications\Channels\Notification] $notification' . "\n"
             . '**/' . "\n",
             $parserContext
         );
@@ -476,7 +476,7 @@ public function testUpdateMethodParametersFromInvalidTags(): void
                 'The "param2" parameter of the method "fun1" is missing a @param tag',
                 'The method "fun1" has "6" @param tags but only "2" where expected.',
                 'The method "fun1" has "1" invalid @param tags.',
-                'Invalid @param tag on "fun1": "array[\Illuminate\Notifications\Channels\Notification]  $notification"',
+                'Invalid @param tag on "fun1": "array[\Illuminate\Notifications\Channels\Notification] $notification"',
             ],
             $this->callMethod(
                 $visitor,
@@ -498,7 +498,7 @@ public function testUpdateMethodParametersFromInvalidTagsReport(): void
         $docBlockParser = new DocBlockParser();
         $docBlockNode   = $docBlockParser->parse(
             '/**' . "\n"
-            . '* @param array[\Illuminate\Notifications\Channels\Notification]  $notification' . "\n"
+            . '* @param array[\Illuminate\Notifications\Channels\Notification] $notification' . "\n"
             . '**/' . "\n",
             $parserContext
         );
@@ -513,7 +513,7 @@ public function testUpdateMethodParametersFromInvalidTagsReport(): void
             [
                 'The "notification" parameter of the method "fun1" is missing a @param tag',
                 'The method "fun1" has "1" invalid @param tags.',
-                'Invalid @param tag on "fun1": "array[\Illuminate\Notifications\Channels\Notification]  $notification"',
+                'Invalid @param tag on "fun1": "array[\Illuminate\Notifications\Channels\Notification] $notification"',
             ],
             $this->callMethod(
                 $visitor,

tests/composer-package-auto-test.sh

@@ -27,6 +27,7 @@ recreateSetup() {
                 }
             }
         ],
+        "minimum-stability": "dev",
         "require": {
             "code-lts/doctum": "5.x-dev"
         }

tests/phar/data/absolute_1.out

@@ -4,26 +4,26 @@ Version main
 ------------
 
 
-Parsing Foo\Foo total: 62 errors
-Parsing Head total: 62 errors
-Parsing Body total: 62 errors
-Parsing Footer total: 62 errors
-Parsing IntersectionDocument total: 62 errors
-Parsing Models\LaravelModel total: 62 errors
-Parsing RoundaboutIntersection\Foo total: 62 errors
-Parsing RoundaboutIntersection\Bar total: 62 errors
-Parsing RoundaboutIntersection\FooAndBar total: 62 errors
-Parsing RoundaboutIntersection\Baz total: 62 errors
-Parsing IPv4Address total: 62 errors
-Parsing MyContainer total: 63 errors
-Parsing Collection total: 63 errors
-Parsing DogCollection total: 63 errors
-Parsing PersistentCollection total: 63 errors
-Parsing Cat total: 63 errors
-Parsing Foo total: 63 errors
-Parsing Bar total: 63 errors
-Parsing SuperCoolLibrary\Meta total: 63 errors
-Parsing Net_Sample total: 63 errors
+Parsing Foo\Foo total: 20 errors
+Parsing Head total: 20 errors
+Parsing Body total: 20 errors
+Parsing Footer total: 20 errors
+Parsing IntersectionDocument total: 20 errors
+Parsing Models\LaravelModel total: 24 errors
+Parsing RoundaboutIntersection\Foo total: 24 errors
+Parsing RoundaboutIntersection\Bar total: 24 errors
+Parsing RoundaboutIntersection\FooAndBar total: 24 errors
+Parsing RoundaboutIntersection\Baz total: 24 errors
+Parsing IPv4Address total: 24 errors
+Parsing MyContainer total: 24 errors
+Parsing Collection total: 24 errors
+Parsing DogCollection total: 24 errors
+Parsing PersistentCollection total: 24 errors
+Parsing Cat total: 24 errors
+Parsing Foo total: 24 errors
+Parsing Bar total: 24 errors
+Parsing SuperCoolLibrary\Meta total: 24 errors
+Parsing Net_Sample total: 29 errors
 Parsing done
 
 Rendering Global index.html

tests/phar/data/absolute_fr_1.out

@@ -4,26 +4,26 @@ Version main
 ------------
 
 
-Parsing Foo\Foo total: 62 errors
-Parsing Head total: 62 errors
-Parsing Body total: 62 errors
-Parsing Footer total: 62 errors
-Parsing IntersectionDocument total: 62 errors
-Parsing Models\LaravelModel total: 62 errors
-Parsing RoundaboutIntersection\Foo total: 62 errors
-Parsing RoundaboutIntersection\Bar total: 62 errors
-Parsing RoundaboutIntersection\FooAndBar total: 62 errors
-Parsing RoundaboutIntersection\Baz total: 62 errors
-Parsing IPv4Address total: 62 errors
-Parsing MyContainer total: 63 errors
-Parsing Collection total: 63 errors
-Parsing DogCollection total: 63 errors
-Parsing PersistentCollection total: 63 errors
-Parsing Cat total: 63 errors
-Parsing Foo total: 63 errors
-Parsing Bar total: 63 errors
-Parsing SuperCoolLibrary\Meta total: 63 errors
-Parsing Net_Sample total: 63 errors
+Parsing Foo\Foo total: 20 errors
+Parsing Head total: 20 errors
+Parsing Body total: 20 errors
+Parsing Footer total: 20 errors
+Parsing IntersectionDocument total: 20 errors
+Parsing Models\LaravelModel total: 24 errors
+Parsing RoundaboutIntersection\Foo total: 24 errors
+Parsing RoundaboutIntersection\Bar total: 24 errors
+Parsing RoundaboutIntersection\FooAndBar total: 24 errors
+Parsing RoundaboutIntersection\Baz total: 24 errors
+Parsing IPv4Address total: 24 errors
+Parsing MyContainer total: 24 errors
+Parsing Collection total: 24 errors
+Parsing DogCollection total: 24 errors
+Parsing PersistentCollection total: 24 errors
+Parsing Cat total: 24 errors
+Parsing Foo total: 24 errors
+Parsing Bar total: 24 errors
+Parsing SuperCoolLibrary\Meta total: 24 errors
+Parsing Net_Sample total: 29 errors
 Parsing done
 
 Rendering Global index.html