SONARPY-4011 Rule S8507 TypeVar, ParamSpec, and NewType names should match their assigned variable names (#1040)

GitOrigin-RevId: 6c637df3b657e7959d17bda21463f8ce4a4bb3f7

Author: sonar-nigel[bot]

python-checks/src/main/java/org/sonar/python/checks/OpenSourceCheckList.java

@@ -451,6 +451,7 @@ public Stream<Class<?>> getChecks() {
       TrailingWhitespaceCheck.class,
       TypeAliasAnnotationCheck.class,
       TypeVarCovariantAndContravariantCheck.class,
+      TypeVarNamingConventionCheck.class,
       TfFunctionDependOnOutsideVariableCheck.class,
       TfFunctionRecursivityCheck.class,
       TfInputShapeOnModelSubclassCheck.class,

python-checks/src/main/java/org/sonar/python/checks/TypeVarNamingConventionCheck.java

@@ -0,0 +1,84 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * You can redistribute and/or modify this program under the terms of
+ * the Sonar Source-Available License Version 1, as published by SonarSource Sàrl.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import org.sonar.check.Rule;
+import org.sonar.plugins.python.api.PythonSubscriptionCheck;
+import org.sonar.plugins.python.api.SubscriptionContext;
+import org.sonar.plugins.python.api.tree.AssignmentStatement;
+import org.sonar.plugins.python.api.tree.CallExpression;
+import org.sonar.plugins.python.api.tree.ExpressionList;
+import org.sonar.plugins.python.api.tree.Name;
+import org.sonar.plugins.python.api.tree.RegularArgument;
+import org.sonar.plugins.python.api.tree.StringLiteral;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatchers;
+import org.sonar.python.tree.TreeUtils;
+
+@Rule(key = "S8507")
+public class TypeVarNamingConventionCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Rename this string to match the variable name \"%s\".";
+
+  private static final TypeMatcher TYPING_CONSTRUCT_MATCHER = TypeMatchers.any(
+    TypeMatchers.isType("typing.TypeVar"),
+    TypeMatchers.isType("typing_extensions.TypeVar"),
+    TypeMatchers.isType("typing.ParamSpec"),
+    TypeMatchers.isType("typing_extensions.ParamSpec"),
+    TypeMatchers.isType("typing.NewType"),
+    TypeMatchers.isType("typing_extensions.NewType")
+  );
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, TypeVarNamingConventionCheck::checkCall);
+  }
+
+  private static void checkCall(SubscriptionContext ctx) {
+    CallExpression call = (CallExpression) ctx.syntaxNode();
+    if (!TYPING_CONSTRUCT_MATCHER.isTrueFor(call.callee(), ctx)) {
+      return;
+    }
+    RegularArgument firstArg = TreeUtils.nthArgumentOrKeyword(0, "name", call.arguments());
+    if (firstArg == null || !firstArg.expression().is(Tree.Kind.STRING_LITERAL)) {
+      return;
+    }
+    StringLiteral stringLiteral = (StringLiteral) firstArg.expression();
+    String stringName = stringLiteral.trimmedQuotesValue();
+
+    Tree parent = call.parent();
+    if (!(parent instanceof AssignmentStatement assignment)) {
+      return;
+    }
+    if (assignment.lhsExpressions().size() != 1) {
+      return;
+    }
+    ExpressionList lhsExprList = assignment.lhsExpressions().get(0);
+    if (lhsExprList.expressions().size() != 1) {
+      return;
+    }
+    Tree lhsExpr = lhsExprList.expressions().get(0);
+    if (!lhsExpr.is(Tree.Kind.NAME)) {
+      return;
+    }
+    String variableName = ((Name) lhsExpr).name();
+    if (!stringName.equals(variableName)) {
+      ctx.addIssue(stringLiteral, String.format(MESSAGE, variableName));
+    }
+  }
+}

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S8507.html

@@ -0,0 +1,41 @@
+<p>This rule raises an issue when a <code>TypeVar</code>, <code>ParamSpec</code>, or <code>NewType</code> is assigned to a variable whose name does
+not match the string name passed to its constructor.</p>
+<h2>Why is this an issue?</h2>
+<p>In Python’s typing system, <code>TypeVar</code>, <code>ParamSpec</code>, and <code>NewType</code> are special constructs used to define generic
+types and type aliases. When creating these objects, you provide a string name as the first argument to the constructor. The convention is that this
+string name should match the variable name to which the type is assigned.</p>
+<p>When the names do not match, type checkers and runtime error messages use the string name from the constructor, which can make error messages
+confusing. IDEs and other development tools may also rely on this naming convention to provide accurate type information.</p>
+<h3>What is the potential impact?</h3>
+<p>Mismatched names create confusion for developers reading the code and make error messages harder to understand. This can slow down debugging and
+make code reviews more difficult, reducing overall development efficiency.</p>
+<p>In larger codebases with multiple type variables, mismatched names can lead to mistakes when refactoring or extending generic classes and
+functions.</p>
+<h2>How to fix it</h2>
+<p>Ensure the string name passed to the constructor matches the variable name it is assigned to.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+from typing import TypeVar, ParamSpec, NewType
+
+MyType = TypeVar("T")  # Noncompliant: variable is "MyType" but string is "T"
+MyParams = ParamSpec("P")  # Noncompliant: variable is "MyParams" but string is "P"
+MyInt = NewType("Integer", int)  # Noncompliant: variable is "MyInt" but string is "Integer"
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+from typing import TypeVar, ParamSpec, NewType
+
+MyType = TypeVar("MyType")  # Compliant: names match
+MyParams = ParamSpec("MyParams")  # Compliant: names match
+MyInt = NewType("MyInt", int)  # Compliant: names match
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/typing.html#typing.TypeVar"><code>TypeVar</code></a></li>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/typing.html#typing.ParamSpec"><code>ParamSpec</code></a></li>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/typing.html#typing.NewType"><code>NewType</code></a></li>
+  <li>PEP 484 - <a href="https://peps.python.org/pep-0484/">Type Hints</a></li>
+</ul>
+

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/S8507.json

@@ -0,0 +1,25 @@
+{
+  "title": "TypeVar, ParamSpec, and NewType names should match their assigned variable names",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "convention",
+    "type-hint",
+    "readability"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-8507",
+  "sqKey": "S8507",
+  "scope": "All",
+  "quickfix": "targeted",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "MEDIUM"
+    },
+    "attribute": "CLEAR"
+  }
+}

python-checks/src/main/resources/org/sonar/l10n/py/rules/python/Sonar_way_profile.json

@@ -332,6 +332,7 @@
     "S8494",
     "S8495",
     "S8504",
+    "S8507",
     "S8517",
     "S8520",
     "S8521",

python-checks/src/test/java/org/sonar/python/checks/TypeVarNamingConventionCheckTest.java

@@ -0,0 +1,30 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * You can redistribute and/or modify this program under the terms of
+ * the Sonar Source-Available License Version 1, as published by SonarSource Sàrl.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the Sonar Source-Available License for more details.
+ *
+ * You should have received a copy of the Sonar Source-Available License
+ * along with this program; if not, see https://sonarsource.com/license/ssal/
+ */
+package org.sonar.python.checks;
+
+import org.junit.jupiter.api.Test;
+import org.sonar.python.checks.utils.PythonCheckVerifier;
+
+class TypeVarNamingConventionCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify(
+      "src/test/resources/checks/typeVarNamingConvention.py",
+      new TypeVarNamingConventionCheck());
+  }
+}