Fix VariableWrong false positives for partial doc blocks (#40)

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 <[email protected]>

Author: dereuromark

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');
         }
     }