From b5ced164075950a1304f554722abdf51233cfc2a Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Thu, 27 Nov 2025 13:12:06 +0100
Subject: [PATCH] Fix VariableWrong false positives for partial doc blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, when a doc block only documented some parameters (e.g.,
only those needing complex type hints like `array<string>`), the sniff
would compare params by position rather than by name, causing false
positives.

For example, this code:
```php
/**
 * @param array<string> $lines
 */
protected function parseBlocks(Node $parent, array $lines, int $indent): void
```

Would incorrectly report: "Doc Block param variable `$lines` should be
`$parent`" because it was comparing the first doc block param with the
first method param positionally.

Now the sniff matches doc block params to method params by variable
name, allowing partial documentation to work correctly. Only params
that don't exist in the method signature at all are reported as errors.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../Sniffs/Commenting/DocBlockParamSniff.php  | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php b/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php
index c1f1e5e..2d8604a 100644
--- a/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php
+++ b/PhpCollective/Sniffs/Commenting/DocBlockParamSniff.php
@@ -153,21 +153,29 @@ public function process(File $phpcsFile, $stackPointer): void
             return;
         }
 
-        foreach ($docBlockParams as $docBlockParam) {
-            /** @var array<string, mixed> $methodParam */
-            $methodParam = array_shift($methodSignature);
-            $variableName = $tokens[$methodParam['variableIndex']]['content'];
+        // Build a map of method param variable names for lookup
+        $methodParamsByName = [];
+        foreach ($methodSignature as $methodParam) {
+            $varName = $tokens[$methodParam['variableIndex']]['content'];
+            $methodParamsByName[$varName] = $methodParam;
+        }
 
-            if ($docBlockParam['variable'] === $variableName) {
-                continue;
-            }
+        foreach ($docBlockParams as $docBlockParam) {
             // We let other sniffers take care of missing type for now
             if (str_contains($docBlockParam['type'], '$')) {
                 continue;
             }
 
-            $error = 'Doc Block param variable `' . $docBlockParam['variable'] . '` should be `' . $variableName . '`';
-            // For now just report (buggy yet)
+            $docBlockVariable = $docBlockParam['variable'];
+
+            // Check if the doc block variable exists in the method signature
+            if (isset($methodParamsByName[$docBlockVariable])) {
+                // Variable name matches a method param - this is correct
+                continue;
+            }
+
+            // Variable doesn't exist in method signature - report error
+            $error = 'Doc Block param variable `' . $docBlockVariable . '` does not exist in method signature';
             $phpcsFile->addError($error, $docBlockParam['index'], 'VariableWrong');
         }
     }