[rule] Param name to type convention (#187)

Author: TomasVotruba

README.md

@@ -53,6 +53,40 @@ parameters:
 
 <br>
 
+### ParamNameToTypeConventionRule
+
+By convention, we can define parameter type by its name. If we know the "userId" is always an `int`, PHPStan can warn us about it and let us know to fill the type.
+
+```yaml
+services:
+    -
+        class: Symplify\PHPStanRules\Rules\Convention\ParamNameToTypeConventionRule
+        tags: [phpstan.rules.rule]
+        arguments:
+            paramNamesToTypes:
+                userId: int
+```
+
+```php
+function run($userId)
+{
+}
+```
+
+:x:
+
+<br>
+
+```php
+function run(int $userId)
+{
+}
+```
+
+:+1:
+
+<br>
+
 ### CheckRequiredInterfaceInContractNamespaceRule
 
 Interface must be located in "Contract" or "Contracts" namespace

composer.json

@@ -8,15 +8,15 @@
         "webmozart/assert": "^1.11",
         "phpstan/phpstan": "^2.1.8",
         "nette/utils": "^3.2|^4.0",
-        "phpstan/phpdoc-parser": "^2.0"
+        "phpstan/phpdoc-parser": "^2.1"
     },
     "require-dev": {
-        "nikic/php-parser": "^5.3",
+        "nikic/php-parser": "^5.4",
         "phpunit/phpunit": "^11.5",
         "symfony/framework-bundle": "6.1.*",
-        "symplify/easy-coding-standard": "^12.5",
+        "phpecs/phpecs": "^2.0",
         "tomasvotruba/class-leak": "^2.0",
-        "rector/rector": "^2.0.6",
+        "rector/rector": "^2.0.10",
         "phpstan/extension-installer": "^1.4",
         "symplify/phpstan-extensions": "^12.0",
         "tomasvotruba/unused-public": "^2.0",

src/Enum/RuleIdentifier.php

@@ -71,4 +71,6 @@ final class RuleIdentifier
     public const NO_JUST_PROPERTY_ASSIGN = 'symplify.noJustPropertyAssign';
 
     public const NO_PROTECTED_CLASS_STMT = 'symplify.noProtectedClassStmt';
+
+    public const CONVENTION_PARAM_NAME_TO_TYPE = 'symplify.conventionParamNameToType';
 }

src/Rules/Convention/ParamNameToTypeConventionRule.php

@@ -0,0 +1,84 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\PHPStanRules\Rules\Convention;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\Variable;
+use PhpParser\Node\Param;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleError;
+use PHPStan\Rules\RuleErrorBuilder;
+use Symplify\PHPStanRules\Enum\RuleIdentifier;
+use Webmozart\Assert\Assert;
+
+/**
+ * @implements Rule<Param>
+ * @see \Symplify\PHPStanRules\Tests\Rules\Convention\ParamNameToTypeConventionRule\ParamNameToTypeConventionRuleTest
+ */
+final class ParamNameToTypeConventionRule implements Rule
+{
+    /**
+     * @var string
+     */
+    public const ERROR_MESSAGE = 'Parameter name "$%s" should probably have "%s" type';
+
+    /**
+     * @param array<string, string> $paramNamesToTypes
+     */
+    public function __construct(
+        private array $paramNamesToTypes
+    ) {
+        Assert::notEmpty($paramNamesToTypes);
+
+        Assert::allString(array_keys($paramNamesToTypes));
+        Assert::allString($paramNamesToTypes);
+    }
+
+    public function getNodeType(): string
+    {
+        return Param::class;
+    }
+
+    /**
+     * @param Param $node
+     * @return RuleError[]
+     */
+    public function processNode(Node $node, Scope $scope): array
+    {
+        // param type is known, let's skip it
+        if ($node->type instanceof Node) {
+            return [];
+        }
+
+        // unable to fill the type
+        if ($node->variadic) {
+            return [];
+        }
+
+        if (! $node->var instanceof Variable) {
+            return [];
+        }
+
+        if (! is_string($node->var->name)) {
+            return [];
+        }
+
+        $variableName = $node->var->name;
+
+        $expectedType = $this->paramNamesToTypes[$variableName] ?? null;
+        if ($expectedType === null) {
+            return [];
+        }
+
+        $errorMessage = sprintf(self::ERROR_MESSAGE, $variableName, $expectedType);
+
+        $identifierRuleError = RuleErrorBuilder::message($errorMessage)
+            ->identifier(RuleIdentifier::CONVENTION_PARAM_NAME_TO_TYPE)
+            ->build();
+
+        return [$identifierRuleError];
+    }
+}

tests/Rules/Convention/ParamNameToTypeConventionRule/Fixture/SkipAlreadyTyped.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Convention\ParamNameToTypeConventionRule\Fixture;
+
+final class SkipAlreadyTyped
+{
+    public function run(int $userId)
+    {
+    }
+}

tests/Rules/Convention/ParamNameToTypeConventionRule/Fixture/SkipVariadic.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Convention\ParamNameToTypeConventionRule\Fixture;
+
+final class SkipVariadic
+{
+    public function run(...$userId)
+    {
+    }
+}

tests/Rules/Convention/ParamNameToTypeConventionRule/Fixture/SomeUntypedParam.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Symplify\PHPStanRules\Tests\Rules\Convention\ParamNameToTypeConventionRule\Fixture;
+
+final class SomeUntypedParam
+{
+    public function run($userId)
+    {
+    }
+}

tests/Rules/Convention/ParamNameToTypeConventionRule/ParamNameToTypeConventionRuleTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Symplify\PHPStanRules\Tests\Rules\Convention\ParamNameToTypeConventionRule;
+
+use Iterator;
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Symplify\PHPStanRules\Rules\Convention\ParamNameToTypeConventionRule;
+
+final class ParamNameToTypeConventionRuleTest extends RuleTestCase
+{
+    /**
+     * @param mixed[] $expectedErrorsWithLines
+     */
+    #[DataProvider('provideData')]
+    public function testRule(string $filePath, array $expectedErrorsWithLines): void
+    {
+        $this->analyse([$filePath], $expectedErrorsWithLines);
+    }
+
+    public static function provideData(): Iterator
+    {
+        $errorMessage = sprintf(ParamNameToTypeConventionRule::ERROR_MESSAGE, 'userId', 'int');
+
+        yield [__DIR__ . '/Fixture/SomeUntypedParam.php', [
+            [$errorMessage, 7],
+        ]];
+
+        yield [__DIR__ . '/Fixture/SkipVariadic.php', []];
+        yield [__DIR__ . '/Fixture/SkipAlreadyTyped.php', []];
+    }
+
+    /**
+     * @return string[]
+     */
+    public static function getAdditionalConfigFiles(): array
+    {
+        return [__DIR__ . '/config/configured_rule.neon'];
+    }
+
+    protected function getRule(): Rule
+    {
+        return self::getContainer()->getByType(ParamNameToTypeConventionRule::class);
+    }
+}

tests/Rules/Convention/ParamNameToTypeConventionRule/config/configured_rule.neon

@@ -0,0 +1,6 @@
+services:
+    -
+        class: Symplify\PHPStanRules\Rules\Convention\ParamNameToTypeConventionRule
+        arguments:
+            paramNamesToTypes:
+                userId: int