SONARPY-3980 Rule S8515 TypeVars should not be both covariant and contravariant (#1014)

GitOrigin-RevId: e1596360a39433be9b8b6783cb293b438cab9962

Author: sonar-nigel[bot]

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

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

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

@@ -0,0 +1,61 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * 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.CallExpression;
+import org.sonar.plugins.python.api.tree.RegularArgument;
+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.checks.utils.Expressions;
+import org.sonar.python.tree.TreeUtils;
+
+@Rule(key = "S8515")
+public class TypeVarCovariantAndContravariantCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Remove either \"covariant=True\" or \"contravariant=True\"; a TypeVar cannot be both covariant and contravariant.";
+  private static final TypeMatcher TYPEVAR_MATCHER = TypeMatchers.any(
+    TypeMatchers.isType("typing.TypeVar"),
+    TypeMatchers.isType("typing_extensions.TypeVar")
+  );
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.CALL_EXPR, TypeVarCovariantAndContravariantCheck::checkTypeVarCall);
+  }
+
+  private static void checkTypeVarCall(SubscriptionContext ctx) {
+    CallExpression call = (CallExpression) ctx.syntaxNode();
+    if (!TYPEVAR_MATCHER.isTrueFor(call.callee(), ctx)) {
+      return;
+    }
+    RegularArgument covariantArg = TreeUtils.argumentByKeyword("covariant", call.arguments());
+    if (covariantArg == null) {
+      return;
+    }
+    RegularArgument contravariantArg = TreeUtils.argumentByKeyword("contravariant", call.arguments());
+    if (contravariantArg == null) {
+      return;
+    }
+    if (Expressions.isTruthy(covariantArg.expression()) && Expressions.isTruthy(contravariantArg.expression())) {
+      ctx.addIssue(call.callee(), MESSAGE);
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+<p>This rule raises an issue when a <code>TypeVar</code> is declared with both <code>covariant=True</code> and <code>contravariant=True</code>.</p>
+<h2>Why is this an issue?</h2>
+<p>A <code>TypeVar</code> in Python represents a type variable used in generic programming. It can have one of three variance modes:</p>
+<ul>
+  <li><strong>invariant</strong>, the default: the type must match exactly</li>
+  <li><strong>covariant</strong> with <code>covariant=True</code>: the type can be replaced with a subtype</li>
+  <li><strong>contravariant</strong> with <code>contravariant=True</code>: the type can be replaced with a supertype</li>
+</ul>
+<p>These variance modes are mutually exclusive. A type variable cannot be both covariant and contravariant simultaneously because these represent opposite relationships in the type hierarchy. Python's <code>typing</code> module will raise a <code>ValueError</code> at runtime when it encounters such a declaration.</p>
+<h3>What is the potential impact?</h3>
+<ul>
+  <li>Python raises a <code>ValueError</code> when the module is imported, causing the application to crash immediately.</li>
+  <li>Static type checkers cannot analyze the code properly, reducing confidence in the type safety of the codebase.</li>
+</ul>
+<h2>How to fix it</h2>
+<p>Choose the appropriate variance mode for your type variable:</p>
+<ul>
+  <li>if you need covariance to allow subtypes, use only <code>covariant=True</code></li>
+  <li>if you need contravariance to allow supertypes, use only <code>contravariant=True</code></li>
+  <li>if you need exact type matching, omit both parameters for the default invariant behavior</li>
+</ul>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+from typing import TypeVar
+
+T = TypeVar('T', covariant=True, contravariant=True)  # Noncompliant
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+from typing import TypeVar
+
+T_co = TypeVar('T_co', covariant=True)
+</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>PEP 484 - <a href="https://peps.python.org/pep-0484/#covariance-and-contravariance">Covariance and Contravariance</a></li>
+  <li>Mypy - <a href="https://mypy.readthedocs.io/en/stable/generics.html#variance-of-generic-types">Variance of generic types</a></li>
+</ul>

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

@@ -0,0 +1,15 @@
+{
+  "title": "TypeVars should not be both covariant and contravariant",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [],
+  "defaultSeverity": "Blocker",
+  "ruleSpecification": "RSPEC-8515",
+  "sqKey": "S8515",
+  "scope": "All",
+  "quickfix": "unknown"
+}

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

@@ -0,0 +1,30 @@
+/*
+ * SonarQube Python Plugin
+ * Copyright (C) 2011-2025 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the Sonar Source-Available License Version 1, as published by SonarSource SA.
+ *
+ * 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 TypeVarCovariantAndContravariantCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify(
+      "src/test/resources/checks/typeVarCovariantAndContravariant.py",
+      new TypeVarCovariantAndContravariantCheck());
+  }
+}

python-checks/src/test/resources/checks/typeVarCovariantAndContravariant.py

@@ -0,0 +1,111 @@
+from typing import TypeVar
+from typing import TypeVar as TV
+from typing_extensions import TypeVar as ExtTV
+import typing
+import typing_extensions
+
+T1 = TypeVar('T1', covariant=True, contravariant=True)  # Noncompliant
+#    ^^^^^^^
+T2 = TypeVar('T2', contravariant=True, covariant=True)  # Noncompliant
+#    ^^^^^^^
+T3 = TypeVar('T3', int, str, covariant=True, contravariant=True)  # Noncompliant
+#    ^^^^^^^
+T4 = TypeVar('T4', bound=int, covariant=True, contravariant=True)  # Noncompliant
+#    ^^^^^^^
+T5 = typing.TypeVar('T5', covariant=True, contravariant=True)  # Noncompliant
+#    ^^^^^^^^^^^^^^
+T6 = typing_extensions.TypeVar('T6', covariant=True, contravariant=True)  # Noncompliant
+#    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+cov = True
+T7 = TypeVar('T7', covariant=cov, contravariant=True)  # Noncompliant
+#    ^^^^^^^
+
+contra = True
+T8 = TypeVar('T8', covariant=True, contravariant=contra)  # Noncompliant
+#    ^^^^^^^
+
+cov2 = True
+contra2 = True
+T9 = TypeVar('T9', covariant=cov2, contravariant=contra2)  # Noncompliant
+#    ^^^^^^^
+
+
+T_co = TypeVar('T_co', covariant=True)
+T_contra = TypeVar('T_contra', contravariant=True)
+T_inv = TypeVar('T_inv')
+T_inv2 = TypeVar('T_inv2', covariant=False, contravariant=False)
+T_inv3 = TypeVar('T_inv3', covariant=True, contravariant=False)
+T_inv4 = TypeVar('T_inv4', covariant=False, contravariant=True)
+T_ext_co = typing_extensions.TypeVar('T_ext_co', covariant=True)
+T_ext_contra = typing_extensions.TypeVar('T_ext_contra', contravariant=True)
+
+
+def get_flag():
+    return True
+
+
+T_unk = TypeVar('T_unk', covariant=get_flag(), contravariant=True)
+T_unk2 = TypeVar('T_unk2', covariant=True, contravariant=get_flag())
+
+
+def my_func(name, covariant=False, contravariant=False):
+    pass
+
+
+my_func('X', covariant=True, contravariant=True)
+
+
+cov3 = False
+cov3 = True
+T_fn = TypeVar('T_fn', covariant=cov3, contravariant=True)
+
+cov_false = False
+T_false_name = TypeVar('T_false_name', covariant=cov_false, contravariant=True)
+
+T_num_noncompliant = TypeVar('T_num_noncompliant', covariant=1, contravariant=1)  # Noncompliant
+T_num_mixed = TypeVar('T_num_mixed', covariant=1, contravariant=True)  # Noncompliant
+
+T_num_zero_cov = TypeVar('T_num_zero_cov', covariant=0, contravariant=True)
+T_num_zero_contra = TypeVar('T_num_zero_contra', covariant=True, contravariant=0)
+T_num_zero_both = TypeVar('T_num_zero_both', covariant=0, contravariant=0)
+
+T_float_zero_cov = TypeVar('T_float_zero_cov', covariant=0.0, contravariant=True)
+T_float_zero_contra = TypeVar('T_float_zero_contra', covariant=True, contravariant=0.0)
+
+T_complex_zero_cov = TypeVar('T_complex_zero_cov', covariant=0j, contravariant=True)
+T_complex_zero_contra = TypeVar('T_complex_zero_contra', covariant=True, contravariant=0j)
+
+T_none_cov = TypeVar('T_none_cov', covariant=None, contravariant=True)
+T_none_contra = TypeVar('T_none_contra', covariant=True, contravariant=None)
+
+T_str_noncompliant = TypeVar('T_str_noncompliant', covariant="yes", contravariant=True)  # Noncompliant
+T_str_empty_cov = TypeVar('T_str_empty_cov', covariant="", contravariant=True)
+
+T_list_empty_cov = TypeVar('T_list_empty_cov', covariant=[], contravariant=True)
+T_list_empty_contra = TypeVar('T_list_empty_contra', covariant=True, contravariant=[])
+T_list_nonempty = TypeVar('T_list_nonempty', covariant=[1], contravariant=True)  # Noncompliant
+
+T_tuple_empty_cov = TypeVar('T_tuple_empty_cov', covariant=(), contravariant=True)
+T_tuple_empty_contra = TypeVar('T_tuple_empty_contra', covariant=True, contravariant=())
+T_tuple_nonempty = TypeVar('T_tuple_nonempty', covariant=(1,), contravariant=True)  # Noncompliant
+
+T_dict_empty_cov = TypeVar('T_dict_empty_cov', covariant={}, contravariant=True)
+T_dict_empty_contra = TypeVar('T_dict_empty_contra', covariant=True, contravariant={})
+T_dict_nonempty = TypeVar('T_dict_nonempty', covariant={1: 2}, contravariant=True)  # Noncompliant
+
+T_set_nonempty = TypeVar('T_set_nonempty', covariant={1, 2}, contravariant=True)  # Noncompliant
+
+T_ext_inv = typing_extensions.TypeVar('T_ext_inv', covariant=False, contravariant=False)
+
+T_alias = TV('T_alias', covariant=True, contravariant=True)  # Noncompliant
+#         ^^
+T_ext_alias = ExtTV('T_ext_alias', covariant=True, contravariant=True)  # Noncompliant
+#             ^^^^^
+
+T_str_contra_truthy = TypeVar('T_str_contra_truthy', covariant=True, contravariant="yes")  # Noncompliant
+#                     ^^^^^^^
+T_str_empty_contra = TypeVar('T_str_empty_contra', covariant=True, contravariant="")
+
+kwargs_with_covariant = {'covariant': True, 'contravariant': True}
+T_kwargs_unpacked = TypeVar('T_kwargs_unpacked', **kwargs_with_covariant)