extend dead param worker (#84)

Author: TomasVotruba

src/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer.php

@@ -13,6 +13,7 @@
 use SplFileInfo;
 use Symplify\CodingStandard\Fixer\AbstractSymplifyFixer;
 use Symplify\CodingStandard\TokenRunner\Contract\DocBlock\MalformWorkerInterface;
+use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\DeadParamMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\InlineVariableDocBlockMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\InlineVarMalformWorker;
 use Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker\MissingParamNameMalformWorker;
@@ -51,6 +52,7 @@ public function __construct(
         SuperfluousReturnNameMalformWorker $superfluousReturnNameMalformWorker,
         SuperfluousVarNameMalformWorker $superfluousVarNameMalformWorker,
         SwitchedTypeAndNameMalformWorker $switchedTypeAndNameMalformWorker,
+        DeadParamMalformWorker $deadParamMalformWorker,
         private readonly TokenReverser $tokenReverser
     ) {
         $this->malformWorkers = [
@@ -63,6 +65,7 @@ public function __construct(
             $superfluousReturnNameMalformWorker,
             $superfluousVarNameMalformWorker,
             $switchedTypeAndNameMalformWorker,
+            $deadParamMalformWorker,
         ];
     }
 
@@ -123,6 +126,17 @@ public function fix(SplFileInfo $fileInfo, Tokens $tokens): void
                 continue;
             }
 
+            // doc block became empty after removing dead lines → remove it completely,
+            // including the whitespace that followed it, to avoid leaving a blank line
+            if ($this->isEmptyDocBlock($docContent)) {
+                $tokens->clearAt($index);
+                if (isset($tokens[$index + 1]) && $tokens[$index + 1]->isWhitespace()) {
+                    $tokens->clearAt($index + 1);
+                }
+
+                continue;
+            }
+
             $tokens[$index] = new Token([T_DOC_COMMENT, $docContent]);
         }
     }
@@ -137,4 +151,9 @@ public function getPriority(): int
     {
         return -37;
     }
+
+    private function isEmptyDocBlock(string $docContent): bool
+    {
+        return Strings::replace($docContent, '#/\*\*|\*/|\*|\s#', '') === '';
+    }
 }

src/TokenRunner/DocBlock/MalformWorker/DeadParamMalformWorker.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\CodingStandard\TokenRunner\DocBlock\MalformWorker;
+
+use Nette\Utils\Strings;
+use PhpCsFixer\DocBlock\DocBlock;
+use PhpCsFixer\Tokenizer\Token;
+use PhpCsFixer\Tokenizer\Tokens;
+use Symplify\CodingStandard\TokenRunner\Contract\DocBlock\MalformWorkerInterface;
+
+/**
+ * Removes dead param annotation lines that only contain a variable name and no type,
+ * e.g. "param $value" - such line carries no information and can be removed.
+ */
+final class DeadParamMalformWorker implements MalformWorkerInterface
+{
+    /**
+     * @see https://regex101.com/r/Hk4lFc/1
+     */
+    private const string PARAM_WITHOUT_TYPE_REGEX = '#@(?:psalm-|phpstan-)?param\s+\$\w+\s*$#';
+
+    /**
+     * @param Tokens<Token> $tokens
+     */
+    public function work(string $docContent, Tokens $tokens, int $position): string
+    {
+        $docBlock = new DocBlock($docContent);
+
+        foreach ($docBlock->getLines() as $line) {
+            if (! Strings::match($line->getContent(), self::PARAM_WITHOUT_TYPE_REGEX)) {
+                continue;
+            }
+
+            $line->remove();
+        }
+
+        return $docBlock->getContent();
+    }
+}

tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param.php.inc

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * @param string $name
+ * @param $age
+ */
+function withDeadParam(string $name, $age)
+{
+}
+
+?>
+-----
+<?php
+
+/**
+ * @param string $name
+ */
+function withDeadParam(string $name, $age)
+{
+}
+
+?>

tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/dead_param_only.php.inc

@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * @param $value
+ */
+function onlyDeadParam($value)
+{
+}
+
+?>
+-----
+<?php
+
+function onlyDeadParam($value)
+{
+}
+
+?>

tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong4.php.inc

@@ -36,7 +36,6 @@ function someFunction($instanceof)
 }
 
 /**
- * @param $value
  *
  * @return The normalized array value
  */

tests/Fixer/Commenting/ParamReturnAndVarTagMalformsFixer/Fixture/wrong9.php.inc

@@ -15,7 +15,6 @@ function someFunction($argument, $argument2, $exceptionMessageFactory, $items)
 <?php
 
 /**
- * @param $argument
  * @param string $argument2
  * @param ExceptionMessageFactoryInterface|null $exceptionMessageFactory
  * @param string[] $items