Flag docblock parameters that have no counterparts in function signature

Fixes vimeo/psalm#3166

config.xsd

@@ -484,6 +484,7 @@
             <xs:element name="UnusedClass" type="ClassIssueHandlerType" minOccurs="0" />
             <xs:element name="UnusedClosureParam" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnusedConstructor" type="MethodIssueHandlerType" minOccurs="0" />
+            <xs:element name="UnusedDocblockParam" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnusedForeachValue" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UnusedFunctionCall" type="FunctionIssueHandlerType" minOccurs="0" />
             <xs:element name="UnusedMethod" type="MethodIssueHandlerType" minOccurs="0" />

docs/running_psalm/error_levels.md

@@ -302,6 +302,7 @@ Level 5 and above allows a more non-verifiable code, and higher levels are even
  - [UnusedClass](issues/UnusedClass.md)
  - [UnusedClosureParam](issues/UnusedClosureParam.md)
  - [UnusedConstructor](issues/UnusedConstructor.md)
+ - [UnusedDocblockParam](issues/UnusedDocblockParam.md)
  - [UnusedForeachValue](issues/UnusedForeachValue.md)
  - [UnusedMethod](issues/UnusedMethod.md)
  - [UnusedParam](issues/UnusedParam.md)

docs/running_psalm/issues.md

@@ -288,6 +288,7 @@
  - [UnusedClass](issues/UnusedClass.md)
  - [UnusedClosureParam](issues/UnusedClosureParam.md)
  - [UnusedConstructor](issues/UnusedConstructor.md)
+ - [UnusedDocblockParam](issues/UnusedDocblockParam.md)
  - [UnusedForeachValue](issues/UnusedForeachValue.md)
  - [UnusedFunctionCall](issues/UnusedFunctionCall.md)
  - [UnusedMethod](issues/UnusedMethod.md)

docs/running_psalm/issues/UnusedDocblockParam.md

@@ -0,0 +1,14 @@
+# UnusedDocblockParam
+
+Emitted when `--find-dead-code` is turned on and a parameter specified in docblock does not have a corresponding parameter in function / method signature.
+
+```php
+<?php
+
+/**
+ * @param string $legacy_param was renamed to $newParam
+ */
+function f(string $newParam): string {
+    return strtolower($newParam);
+}
+```

src/Psalm/Internal/Analyzer/FunctionLikeAnalyzer.php

@@ -42,6 +42,7 @@ use Psalm\Issue\ReferenceConstraintViolation;
 use Psalm\Issue\ReservedWord;
 use Psalm\Issue\UnresolvableConstant;
 use Psalm\Issue\UnusedClosureParam;
+use Psalm\Issue\UnusedDocblockParam;
 use Psalm\Issue\UnusedParam;
 use Psalm\IssueBuffer;
 use Psalm\Plugin\EventHandler\Event\AfterFunctionLikeAnalysisEvent;
@@ -361,14 +362,22 @@ abstract class FunctionLikeAnalyzer extends SourceAnalyzer
             $context->external_mutation_free = true;
         }
 
-        if ($storage->has_undertyped_native_parameters) {
-            foreach ($storage->unused_docblock_parameters as $param_name => $param_location) {
+        foreach ($storage->unused_docblock_parameters as $param_name => $param_location) {
+            if ($storage->has_undertyped_native_parameters) {
                 IssueBuffer::maybeAdd(
                     new InvalidDocblockParamName(
                         'Incorrect param name $' . $param_name . ' in docblock for ' . $cased_method_id,
                         $param_location,
                     ),
                 );
+            } elseif ($codebase->find_unused_code) {
+                 IssueBuffer::maybeAdd(
+                     new UnusedDocblockParam(
+                         'Docblock parameter $' . $param_name . ' in docblock for ' . $cased_method_id
+                         . ' does not have a counterpart in signature parameter list',
+                         $param_location,
+                     ),
+                 );
             }
         }
 

src/Psalm/Issue/UnusedDocblockParam.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Psalm\Issue;
+
+final class UnusedDocblockParam extends CodeIssue
+{
+    public const ERROR_LEVEL = -2;
+    public const SHORTCODE = 319;
+}

tests/UnusedCodeTest.php

@@ -1757,7 +1757,7 @@ class UnusedCodeTest extends TestCase
             'exitInlineHtml' => [
                 'code' => '<?php
                     exit(0);
-                    ?'.'>foo
+                    ?' . '>foo
                 ',
                 'error_message' => 'UnevaluatedCode',
             ],
@@ -1836,6 +1836,16 @@ class UnusedCodeTest extends TestCase
                     PHP,
                 'error_message' => 'PossiblyUnusedParam',
             ],
+            'unused param tag' => [
+                'code' => <<<'PHP'
+                    <?php
+                    /**
+                     * @param string $param
+                     */
+                    function f(): void {}
+                    PHP,
+                'error_message' => 'UnusedDocblockParam',
+            ],
         ];
     }
 }