Make static anlisys pass

Makefile

@@ -0,0 +1,32 @@
+.PHONY: install-phive
+install-phive:
+	mkdir tools; \
+	wget -O tools/phive.phar https://phar.io/releases/phive.phar; \
+	wget -O tools/phive.phar.asc https://phar.io/releases/phive.phar.asc; \
+	gpg --keyserver pool.sks-keyservers.net --recv-keys 0x9D8A98B29B2D5D79; \
+	gpg --verify tools/phive.phar.asc tools/phive.phar; \
+	chmod +x tools/phive.phar
+
+.PHONY: setup
+setup: install-phive
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phar-ga:latest php tools/phive.phar install --force-accept-unsigned
+
+.PHONY: phpcs
+phpcs:
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpdoc/phpcs-ga:latest -d memory_limit=1024M
+
+.PHONY: phpstan
+phpstan:
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project phpstan-ga:latest analyse src --debug --no-progress --level max --configuration phpstan.neon
+
+.PHONY: psaml
+psalm:
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project mickaelandrieu/psalm-ga
+
+.PHONY: test
+test:
+	docker run -it --rm -v${PWD}:/opt/project -w /opt/project php:7.2 tools/phpunit
+
+.PHONY: pre-commit-test
+pre-commit-test: test phpcs phpstan psalm
+

composer.lock

@@ -173,32 +173,29 @@
         },
         {
             "name": "webmozart/assert",
-            "version": "1.4.0",
+            "version": "1.6.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/webmozart/assert.git",
-                "reference": "83e253c8e0be5b0257b881e1827274667c5c17a9"
+                "reference": "573381c0a64f155a0d9a23f4b0c797194805b925"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/webmozart/assert/zipball/83e253c8e0be5b0257b881e1827274667c5c17a9",
+                "url": "https://api.github.com/repos/webmozart/assert/zipball/573381c0a64f155a0d9a23f4b0c797194805b925",
-                "reference": "83e253c8e0be5b0257b881e1827274667c5c17a9",
+                "reference": "573381c0a64f155a0d9a23f4b0c797194805b925",
                 "shasum": ""
             },
             "require": {
                 "php": "^5.3.3 || ^7.0",
                 "symfony/polyfill-ctype": "^1.8"
             },
+            "conflict": {
+                "vimeo/psalm": "<3.6.0"
+            },
             "require-dev": {
-                "phpunit/phpunit": "^4.6",
+                "phpunit/phpunit": "^4.8.36 || ^7.5.13"
-                "sebastian/version": "^1.0.1"
             },
             "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "1.3-dev"
-                }
-            },
             "autoload": {
                 "psr-4": {
                     "Webmozart\\Assert\\": "src/"
@@ -220,7 +217,7 @@
                 "check",
                 "validate"
             ],
-            "time": "2018-12-25T11:19:39+00:00"
+            "time": "2019-11-24T13:36:37+00:00"
         }
     ],
     "packages-dev": [

phive.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phive xmlns="https://phar.io/phive">
+  <phar name="phpunit" version="^8.4.3" installed="8.4.3" location="./tools/phpunit" copy="true"/>
+  <phar name="phpstan" version="^0.9.1" installed="0.10.2" location="./tools/phpstan" copy="true"/>
+</phive>

phpstan.neon

@@ -6,5 +6,3 @@ parameters:
     ignoreErrors:
         # false positive
         - '#Method phpDocumentor\Reflection\DocBlock\Tags\Method::filterArguments() should return array<array> but returns array<array|string>#'
-        - "~Parameter #1 $function of function call_user_func_array expects callable(): mixed, array(string, 'create') given.~"
-        - '#Cannot call method render\(\) on phpDocumentor\\Reflection\\DocBlock\\Description\|string#'

phpunit.xml.dist

@@ -1,8 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
 
 <phpunit
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/8.0/phpunit.xsd"
         colors="true"
-        checkForUnintentionallyCoveredCode="true"
         beStrictAboutOutputDuringTests="true"
         forceCoversAnnotation="true"
         verbose="true"
@@ -20,17 +21,10 @@
     <whitelist>
         <directory suffix=".php">./src/</directory>
     </whitelist>
-    <blacklist>
-      <directory>./vendor/</directory>
-    </blacklist>
   </filter>
   <logging>
     <log type="coverage-html"
-         title="phpDocumentor Reflection DocBlock"
          target="build/coverage"
-         charset="UTF-8"
-         yui="true"
-         highlight="false"
          lowUpperBound="35"
          highLowerBound="70"/>
   </logging>

src/DocBlock/StandardTagFactory.php

@@ -177,8 +177,8 @@ final class StandardTagFactory implements TagFactory
     public function registerTagHandler(string $tagName, string $handler) : void
     {
         Assert::stringNotEmpty($tagName);
-        Assert::stringNotEmpty($handler);
         Assert::classExists($handler);
+        /** @var object $handler stupid hack to make phpstan happy.  */
         Assert::implementsInterface($handler, StaticMethod::class);
 
         if (strpos($tagName, '\\') && $tagName[0] !== '\\') {
@@ -224,7 +224,9 @@ final class StandardTagFactory implements TagFactory
         );
 
         try {
-            return call_user_func_array([$handlerClassName, 'create'], $arguments);
+            /** @var callable $callable */
+            $callable = [$handlerClassName, 'create'];
+            return call_user_func_array($callable, $arguments);
         } catch (InvalidArgumentException $e) {
             return null;
         }

src/DocBlock/Tags/BaseTag.php

@@ -24,7 +24,7 @@ abstract class BaseTag implements DocBlock\Tag
     /** @var string Name of the tag */
     protected $name = '';
 
-    /** @var Description|string|null Description of the tag. */
+    /** @var Description|null Description of the tag. */
     protected $description;
 
     /**
@@ -37,10 +37,7 @@ abstract class BaseTag implements DocBlock\Tag
         return $this->name;
     }
 
-    /**
+    public function getDescription() : ?Description
-     * @return Description|string|null
-     */
-    public function getDescription()
     {
         return $this->description;
     }

src/DocBlock/Tags/Deprecated.php

@@ -94,6 +94,6 @@ final class Deprecated extends BaseTag implements Factory\StaticMethod
      */
     public function __toString() : string
     {
-        return $this->version . ($this->description ? ' ' . $this->description->render() : '');
+        return ($this->version ?? '') . ($this->description ? ' ' . $this->description->render() : '');
     }
 }

src/DocBlock/Tags/Example.php

@@ -13,7 +13,6 @@ declare(strict_types=1);
 
 namespace phpDocumentor\Reflection\DocBlock\Tags;
 
-use phpDocumentor\Reflection\DocBlock\Description;
 use phpDocumentor\Reflection\DocBlock\Tag;
 use Webmozart\Assert\Assert;
 use function array_key_exists;
@@ -26,7 +25,7 @@ use function trim;
 /**
  * Reflection class for a {@}example tag in a Docblock.
  */
-final class Example extends BaseTag
+final class Example implements Tag
 {
     /** @var string Path to a file to use as an example. May also be an absolute URI. */
     private $filePath;
@@ -43,10 +42,10 @@ final class Example extends BaseTag
     /** @var int */
     private $lineCount;
 
-    /**
+    /** @var string|null */
-     * @param string|Description|null $description
+    private $content;
-     */
+
-    public function __construct(string $filePath, bool $isURI, int $startingLine, int $lineCount, $description)
+    public function __construct(string $filePath, bool $isURI, int $startingLine, int $lineCount, ?string $content)
     {
         Assert::notEmpty($filePath);
         Assert::greaterThanEq($startingLine, 0);
@@ -55,20 +54,16 @@ final class Example extends BaseTag
         $this->filePath     = $filePath;
         $this->startingLine = $startingLine;
         $this->lineCount    = $lineCount;
-        $this->name         = 'example';
+        if ($content !== null) {
-        if ($description !== null) {
+            $this->content = trim((string) $content);
-            $this->description = trim((string) $description);
         }
 
         $this->isURI = $isURI;
     }
 
-    /**
+    public function getContent() : string
-     * {@inheritdoc}
-     */
-    public function getContent()
     {
-        if ($this->description === null) {
+        if ($this->content === null) {
             $filePath = '"' . $this->filePath . '"';
             if ($this->isURI) {
                 $filePath = $this->isUriRelative($this->filePath)
@@ -76,10 +71,15 @@ final class Example extends BaseTag
                     : $this->filePath;
             }
 
-            return trim($filePath . ' ' . parent::getDescription());
+            return trim($filePath);
         }
 
-        return $this->description;
+        return $this->content;
+    }
+
+    public function getDescription() : ?string
+    {
+        return $this->content;
     }
 
     /**
@@ -121,7 +121,7 @@ final class Example extends BaseTag
         }
 
         return new static(
-            $filePath ?? $fileUri,
+            $filePath ?? ($fileUri ?? ''),
             $fileUri !== null,
             $startingLine,
             $lineCount,
@@ -145,7 +145,7 @@ final class Example extends BaseTag
      */
     public function __toString() : string
     {
-        return $this->filePath . ($this->description ? ' ' . $this->description : '');
+        return $this->filePath . ($this->content ? ' ' . $this->content : '');
     }
 
     /**
@@ -165,4 +165,18 @@ final class Example extends BaseTag
     {
         return $this->lineCount;
     }
+
+    public function getName() : string
+    {
+        return 'example';
+    }
+
+    public function render(?Formatter $formatter = null) : string
+    {
+        if ($formatter === null) {
+            $formatter = new Formatter\PassthroughFormatter();
+        }
+
+        return $formatter->format($this);
+    }
 }

src/DocBlock/Tags/Generic.php

@@ -24,7 +24,7 @@ use function preg_match;
 /**
  * Parses a tag definition for a DocBlock.
  */
-class Generic extends BaseTag implements Factory\StaticMethod
+final class Generic extends BaseTag implements Factory\StaticMethod
 {
     /**
      * Parses a tag and populates the member variables.

src/DocBlock/Tags/Method.php

@@ -27,7 +27,6 @@ use function implode;
 use function is_string;
 use function preg_match;
 use function sort;
-use function strlen;
 use function strpos;
 use function substr;
 use function trim;
@@ -54,7 +53,9 @@ final class Method extends BaseTag implements Factory\StaticMethod
     private $returnType;
 
     /**
-     * @param mixed[][] $arguments $arguments
+     * @param mixed[][] $arguments
+     *
+     * @psalm-param array<int, array<string, string|Type>|string> $arguments
      */
     public function __construct(
         string $methodName,
@@ -64,7 +65,6 @@ final class Method extends BaseTag implements Factory\StaticMethod
         ?Description $description = null
     ) {
         Assert::stringNotEmpty($methodName);
-        Assert::boolean($static);
 
         if ($returnType === null) {
             $returnType = new Void_();
@@ -151,7 +151,7 @@ final class Method extends BaseTag implements Factory\StaticMethod
         $returnType  = $typeResolver->resolve($returnType, $context);
         $description = $descriptionFactory->create($description, $context);
 
-        if (is_string($arguments) && strlen($arguments) > 0) {
+        if ($arguments !== '') {
             $arguments = explode(',', $arguments);
             foreach ($arguments as &$argument) {
                 $argument = explode(' ', self::stripRestArg(trim($argument)), 2);
@@ -222,13 +222,17 @@ final class Method extends BaseTag implements Factory\StaticMethod
     }
 
     /**
-     * @param mixed[][] $arguments
+     * @param mixed[][]|string[] $arguments
      *
      * @return mixed[][]
+     *
+     * @psalm-param array<int, array<string, string|Type>|string> $arguments
+     * @psalm-return array<int, array<string, string|Type>> $arguments
      */
     private function filterArguments(array $arguments = []) : array
     {
-        foreach ($arguments as &$argument) {
+        $result = [];
+        foreach ($arguments as $argument) {
             if (is_string($argument)) {
                 $argument = ['name' => $argument];
             }
@@ -244,9 +248,11 @@ final class Method extends BaseTag implements Factory\StaticMethod
                     'Arguments can only have the "name" and "type" fields, found: ' . var_export($keys, true)
                 );
             }
+
+            $result[] = $argument;
         }
 
-        return $arguments;
+        return $result;
     }
 
     private static function stripRestArg(string $argument) : string

src/DocBlock/Tags/Param.php

@@ -37,14 +37,14 @@ final class Param extends BaseTag implements Factory\StaticMethod
     /** @var Type|null */
     private $type;
 
-    /** @var string */
+    /** @var string|null */
-    private $variableName = '';
+    private $variableName;
 
     /** @var bool determines whether this is a variadic argument */
-    private $isVariadic = false;
+    private $isVariadic;
 
     public function __construct(
-        string $variableName,
+        ?string $variableName,
         ?Type $type = null,
         bool $isVariadic = false,
         ?Description $description = null
@@ -105,7 +105,7 @@ final class Param extends BaseTag implements Factory\StaticMethod
     /**
      * Returns the variable's name.
      */
-    public function getVariableName() : string
+    public function getVariableName() : ?string
     {
         return $this->variableName;
     }
@@ -133,7 +133,7 @@ final class Param extends BaseTag implements Factory\StaticMethod
     {
         return ($this->type ? $this->type . ' ' : '')
             . ($this->isVariadic() ? '...' : '')
-            . '$' . $this->variableName
+            . ($this->variableName !== null ? '$' . $this->variableName : '')
             . ($this->description ? ' ' . $this->description : '');
     }
 }

src/DocBlock/Tags/Property.php

@@ -29,7 +29,7 @@ use function substr;
 /**
  * Reflection class for a {@}property tag in a Docblock.
  */
-class Property extends BaseTag implements Factory\StaticMethod
+final class Property extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property';
@@ -37,10 +37,10 @@ class Property extends BaseTag implements Factory\StaticMethod
     /** @var Type|null */
     private $type;
 
-    /** @var string */
+    /** @var string|null */
     protected $variableName = '';
 
-    public function __construct(string $variableName, ?Type $type = null, ?Description $description = null)
+    public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
         $this->variableName = $variableName;
         $this->type         = $type;
@@ -89,7 +89,7 @@ class Property extends BaseTag implements Factory\StaticMethod
     /**
      * Returns the variable's name.
      */
-    public function getVariableName() : string
+    public function getVariableName() : ?string
     {
         return $this->variableName;
     }
@@ -108,7 +108,7 @@ class Property extends BaseTag implements Factory\StaticMethod
     public function __toString() : string
     {
         return ($this->type ? $this->type . ' ' : '')
-            . '$' . $this->variableName
+            . ($this->variableName ? '$' . $this->variableName : '')
             . ($this->description ? ' ' . $this->description : '');
     }
 }

src/DocBlock/Tags/PropertyRead.php

@@ -29,7 +29,7 @@ use function substr;
 /**
  * Reflection class for a {@}property-read tag in a Docblock.
  */
-class PropertyRead extends BaseTag implements Factory\StaticMethod
+final class PropertyRead extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property-read';
@@ -37,10 +37,10 @@ class PropertyRead extends BaseTag implements Factory\StaticMethod
     /** @var Type|null */
     private $type;
 
-    /** @var string */
+    /** @var string|null */
     protected $variableName = '';
 
-    public function __construct(string $variableName, ?Type $type = null, ?Description $description = null)
+    public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
         $this->variableName = $variableName;
         $this->type         = $type;
@@ -89,7 +89,7 @@ class PropertyRead extends BaseTag implements Factory\StaticMethod
     /**
      * Returns the variable's name.
      */
-    public function getVariableName() : string
+    public function getVariableName() : ?string
     {
         return $this->variableName;
     }
@@ -108,7 +108,7 @@ class PropertyRead extends BaseTag implements Factory\StaticMethod
     public function __toString() : string
     {
         return ($this->type ? $this->type . ' ' : '')
-            . '$' . $this->variableName
+            . ($this->variableName ? '$' . $this->variableName : '')
             . ($this->description ? ' ' . $this->description : '');
     }
 }

src/DocBlock/Tags/PropertyWrite.php

@@ -30,7 +30,7 @@ use function substr;
 /**
  * Reflection class for a {@}property-write tag in a Docblock.
  */
-class PropertyWrite extends BaseTag implements Factory\StaticMethod
+final class PropertyWrite extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'property-write';
@@ -38,10 +38,10 @@ class PropertyWrite extends BaseTag implements Factory\StaticMethod
     /** @var Type|null */
     private $type;
 
-    /** @var string */
+    /** @var string|null */
     protected $variableName = '';
 
-    public function __construct(string $variableName, ?Type $type = null, ?Description $description = null)
+    public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
         $this->variableName = $variableName;
         $this->type         = $type;
@@ -90,7 +90,7 @@ class PropertyWrite extends BaseTag implements Factory\StaticMethod
     /**
      * Returns the variable's name.
      */
-    public function getVariableName() : string
+    public function getVariableName() : ?string
     {
         return $this->variableName;
     }
@@ -109,7 +109,7 @@ class PropertyWrite extends BaseTag implements Factory\StaticMethod
     public function __toString() : string
     {
         return ($this->type ? $this->type . ' ' : '')
-            . '$' . $this->variableName
+            . ($this->variableName ? '$' . $this->variableName : '')
             . ($this->description ? ' ' . $this->description : '');
     }
 }

src/DocBlock/Tags/Return_.php

@@ -69,6 +69,6 @@ final class Return_ extends BaseTag implements Factory\StaticMethod
 
     public function __toString() : string
     {
-        return $this->type . ' ' . $this->description;
+        return $this->type . ' ' . (string) $this->description;
     }
 }

src/DocBlock/Tags/See.php

@@ -27,7 +27,7 @@ use function preg_split;
 /**
  * Reflection class for an {@}see tag in a Docblock.
  */
-class See extends BaseTag implements Factory\StaticMethod
+final class See extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'see';

src/DocBlock/Tags/Since.php

@@ -88,6 +88,6 @@ final class Since extends BaseTag implements Factory\StaticMethod
      */
     public function __toString() : string
     {
-        return $this->version . ($this->description ? ' ' . $this->description->render() : '');
+        return (string) $this->version . ($this->description ? ' ' . (string) $this->description : '');
     }
 }

src/DocBlock/Tags/Source.php

@@ -72,7 +72,7 @@ final class Source extends BaseTag implements Factory\StaticMethod
             $description = $matches[3];
         }
 
-        return new static($startingLine, $lineCount, $descriptionFactory->create($description, $context));
+        return new static($startingLine, $lineCount, $descriptionFactory->create($description??'', $context));
     }
 
     /**
@@ -101,6 +101,6 @@ final class Source extends BaseTag implements Factory\StaticMethod
     {
         return $this->startingLine
             . ($this->lineCount !== null ? ' ' . $this->lineCount : '')
-            . ($this->description ? ' ' . $this->description->render() : '');
+            . ($this->description ? ' ' . (string) $this->description : '');
     }
 }

src/DocBlock/Tags/Throws.php

@@ -69,6 +69,6 @@ final class Throws extends BaseTag implements Factory\StaticMethod
 
     public function __toString() : string
     {
-        return $this->type . ' ' . $this->description;
+        return (string) $this->type . ' ' . (string) $this->description;
     }
 }

src/DocBlock/Tags/Uses.php

@@ -76,6 +76,6 @@ final class Uses extends BaseTag implements Factory\StaticMethod
      */
     public function __toString() : string
     {
-        return $this->refers . ' ' . $this->description->render();
+        return $this->refers . ' ' . (string) $this->description;
     }
 }

src/DocBlock/Tags/Var_.php

@@ -29,7 +29,7 @@ use function substr;
 /**
  * Reflection class for a {@}var tag in a Docblock.
  */
-class Var_ extends BaseTag implements Factory\StaticMethod
+final class Var_ extends BaseTag implements Factory\StaticMethod
 {
     /** @var string */
     protected $name = 'var';
@@ -37,10 +37,10 @@ class Var_ extends BaseTag implements Factory\StaticMethod
     /** @var Type|null */
     private $type;
 
-    /** @var string */
+    /** @var string|null */
     protected $variableName = '';
 
-    public function __construct(string $variableName, ?Type $type = null, ?Description $description = null)
+    public function __construct(?string $variableName, ?Type $type = null, ?Description $description = null)
     {
         $this->variableName = $variableName;
         $this->type         = $type;
@@ -68,9 +68,7 @@ class Var_ extends BaseTag implements Factory\StaticMethod
 
         // if the first item that is encountered is not a variable; it is a type
         if (isset($parts[0]) && ($parts[0] !== '') && ($parts[0][0] !== '$')) {
-            if ($typeResolver !== null) {
             $type = $typeResolver->resolve(array_shift($parts), $context);
-            }
             array_shift($parts);
         }
 
@@ -92,7 +90,7 @@ class Var_ extends BaseTag implements Factory\StaticMethod
     /**
      * Returns the variable's name.
      */
-    public function getVariableName() : string
+    public function getVariableName() : ?string
     {
         return $this->variableName;
     }

tests/unit/DocBlock/ExampleFinderTest.php

@@ -39,7 +39,7 @@ class ExampleFinderTest extends TestCase
      */
     public function testFileNotFound() : void
     {
-        $example = new Example('./example.php', false, 1, 0, new Description('Test'));
+        $example = new Example('./example.php', false, 1, 0, 'Test');
         $this->assertSame('** File not found : ./example.php **', $this->fixture->find($example));
     }
 }

tests/unit/DocBlockFactoryTest.php

@@ -221,7 +221,8 @@ DOCBLOCK;
                 <<<DOCBLOCK
 This is a DocBlock.
 This should be a Description.
-DOCBLOCK,
+DOCBLOCK
+,
                 'This is a DocBlock.',
                 'This should be a Description.',
             ],
@@ -230,7 +231,8 @@ DOCBLOCK,
 This is a
 multiline Summary.
 This should be a Description.
-DOCBLOCK,
+DOCBLOCK
+,
                 "This is a\nmultiline Summary.",
                 'This should be a Description.',
             ],
@@ -239,7 +241,8 @@ DOCBLOCK,
 This is a Summary without dot but with a whiteline
 
 This should be a Description.
-DOCBLOCK,
+DOCBLOCK
+,
                 'This is a Summary without dot but with a whiteline',
                 'This should be a Description.',
             ],
@@ -248,7 +251,8 @@ DOCBLOCK,
 This is a Summary with dot and with a whiteline.
 
 This should be a Description.
-DOCBLOCK,
+DOCBLOCK
+,
                 'This is a Summary with dot and with a whiteline.',
                 'This should be a Description.',
             ],