CLP-1018 Represent class decorators with semantic type metadata

Preserve ordered decorator expression types and optional factory callee types through inference, lazy resolution, descriptors, and serialization. Derive the conservative V1 identity projection from this metadata and classify known runtime effects centrally.

Cover aliases, factories, unions, unknown decorators, enclosing scopes, cache round trips, and affected checks. Extend the existing arithmetic and subscription fixtures with class-preserving decorator scenarios.

GitOrigin-RevId: ce41b040fa717025dd84a8cf4bc25e20d6218cdb

Author: guillaume-dequenne

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

@@ -87,7 +87,7 @@ private static class ItemOperationsTypeCheck extends ItemOperationsType {
 
     @Override
     public boolean isValidSubscription(Expression subscriptionObject, String requiredMethod, @Nullable String classRequiredMethod,
-                                       Map<LocationInFile, String> secondaries) {
+                                       Map<LocationInFile, String> secondaries, SubscriptionContext context) {
 
       InferredType type = subscriptionObject.type();
       String typeName = InferredTypes.typeName(type);

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

@@ -29,18 +29,24 @@
 import org.sonar.plugins.python.api.symbols.Symbol;
 import org.sonar.plugins.python.api.tree.BaseTreeVisitor;
 import org.sonar.plugins.python.api.tree.BinaryExpression;
+import org.sonar.plugins.python.api.tree.Expression;
 import org.sonar.plugins.python.api.tree.Token;
 import org.sonar.plugins.python.api.tree.Tree;
 import org.sonar.plugins.python.api.tree.TypeAnnotation;
 import org.sonar.plugins.python.api.tree.UnaryExpression;
 import org.sonar.plugins.python.api.types.InferredType;
+import org.sonar.plugins.python.api.types.v2.UnknownType;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
+import org.sonar.python.types.v2.matchers.InternalTypeMatchers;
 
 import static org.sonar.plugins.python.api.symbols.Symbol.Kind.AMBIGUOUS;
 import static org.sonar.plugins.python.api.symbols.Symbol.Kind.FUNCTION;
 import static org.sonar.python.types.InferredTypes.typeSymbols;
 
 public abstract class IncompatibleOperands extends PythonSubscriptionCheck {
 
+  private static final TypeMatcher KNOWN_DECORATOR_EFFECTS = InternalTypeMatchers.hasKnownClassDecoratorEffectsInHierarchy();
+
   private static final Map<String, String> UNARY_SPECIAL_METHODS_BY_OPERATOR = new HashMap<>();
   static {
     UNARY_SPECIAL_METHODS_BY_OPERATOR.put("+", "__pos__");
@@ -105,25 +111,36 @@ public void visitBinaryExpression(BinaryExpression binaryExpression) {
         // SONARPY-1666 We should only exclude types that represent ctypes
         return;
       }
-      checkOperands(binaryExpression.operator(), leftType, rightType);
+      if (canCheckBinaryOperand(binaryExpression.leftOperand(), leftType)
+        && canCheckBinaryOperand(binaryExpression.rightOperand(), rightType)) {
+        checkOperands(binaryExpression.operator(), leftType, rightType);
+      }
       super.visitBinaryExpression(binaryExpression);
     }
 
+    private boolean canCheckBinaryOperand(Expression operand, InferredType type) {
+      if (operand.typeV2() instanceof UnknownType) {
+        // Preserve the V1 check, including its decorator guard, when V2 has no type information.
+        return typeSymbols(type).stream().noneMatch(ClassSymbol::hasDecorators);
+      }
+      return KNOWN_DECORATOR_EFFECTS.isTrueFor(operand, context);
+    }
+
     @Override
     public void visitUnaryExpression(UnaryExpression unaryExpression) {
       InferredType type = unaryExpression.expression().type();
       Token operator = unaryExpression.operator();
       String memberName = UNARY_SPECIAL_METHODS_BY_OPERATOR.get(operator.value());
-      if (memberName != null && resolveMethod(type, memberName).isAbsent()) {
+      if (memberName != null
+        && (unaryExpression.expression().typeV2() instanceof UnknownType
+          || KNOWN_DECORATOR_EFFECTS.isTrueFor(unaryExpression.expression(), context))
+        && resolveMethod(type, memberName).isAbsent()) {
         context.addIssue(operator, message(operator));
       }
       super.visitUnaryExpression(unaryExpression);
     }
 
     private void checkOperands(Token operator, InferredType left, InferredType right) {
-      if (typeSymbols(left).stream().anyMatch(ClassSymbol::hasDecorators) || typeSymbols(right).stream().anyMatch(ClassSymbol::hasDecorators)) {
-        return;
-      }
       SpecialMethodNames specialMethodNames = BINARY_SPECIAL_METHODS_BY_OPERATOR.get(operator.value());
       if (specialMethodNames == null) {
         return;

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

@@ -51,18 +51,18 @@ private void checkSubscription(SubscriptionContext ctx) {
     Map<LocationInFile, String> secondaries = new HashMap<>();
     Expression subscriptionObject = subscriptionExpression.object();
     if (isWithinDelStatement(subscriptionExpression)) {
-      if (!isValidSubscription(subscriptionObject, "__delitem__", null, secondaries)) {
+      if (!isValidSubscription(subscriptionObject, "__delitem__", null, secondaries, ctx)) {
         reportIssue(subscriptionExpression, subscriptionObject, "__delitem__", ctx, secondaries);
       }
       return;
     }
     if (isWithinAssignment(subscriptionExpression)) {
-      if (!isValidSubscription(subscriptionObject, "__setitem__", null, secondaries)) {
+      if (!isValidSubscription(subscriptionObject, "__setitem__", null, secondaries, ctx)) {
         reportIssue(subscriptionExpression, subscriptionObject, "__setitem__", ctx, secondaries);
       }
       return;
     }
-    if (!isValidSubscription(subscriptionObject, "__getitem__", "__class_getitem__", secondaries)) {
+    if (!isValidSubscription(subscriptionObject, "__getitem__", "__class_getitem__", secondaries, ctx)) {
       reportIssue(subscriptionExpression, subscriptionObject, "__getitem__", ctx, secondaries);
     }
   }
@@ -97,7 +97,8 @@ private void reportIssue(SubscriptionExpression subscriptionExpression, Expressi
     secondaries.keySet().stream().filter(Objects::nonNull).forEach(location -> preciseIssue.secondary(location, secondaries.get(location)));
   }
 
-  public abstract boolean isValidSubscription(Expression subscriptionObject, String requiredMethod, @Nullable String classRequiredMethod, Map<LocationInFile, String> secondaries);
+  public abstract boolean isValidSubscription(Expression subscriptionObject, String requiredMethod, @Nullable String classRequiredMethod,
+    Map<LocationInFile, String> secondaries, SubscriptionContext context);
 
   public abstract String message(@Nullable String name, String missingMethod);
 }

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

@@ -23,6 +23,7 @@
 import javax.annotation.Nullable;
 import org.sonar.check.Rule;
 import org.sonar.plugins.python.api.LocationInFile;
+import org.sonar.plugins.python.api.SubscriptionContext;
 import org.sonar.plugins.python.api.symbols.ClassSymbol;
 import org.sonar.plugins.python.api.symbols.FunctionSymbol;
 import org.sonar.plugins.python.api.symbols.Symbol;
@@ -43,8 +44,11 @@
 import org.sonar.plugins.python.api.types.v2.FullyQualifiedNameHelper;
 import org.sonar.plugins.python.api.types.InferredType;
 import org.sonar.plugins.python.api.types.v2.ClassType;
+import org.sonar.plugins.python.api.types.v2.UnknownType;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
 import org.sonar.python.tree.TreeUtils;
 import org.sonar.python.types.InferredTypes;
+import org.sonar.python.types.v2.matchers.InternalTypeMatchers;
 
 import static org.sonar.plugins.python.api.symbols.Symbol.Kind.CLASS;
 import static org.sonar.plugins.python.api.symbols.Symbol.Kind.FUNCTION;
@@ -53,12 +57,14 @@
 @Rule(key = "S5644")
 public class ItemOperationsTypeCheck extends ItemOperationsType {
 
+  private static final TypeMatcher KNOWN_DECORATOR_EFFECTS = InternalTypeMatchers.hasKnownClassDecoratorEffectsInHierarchy();
+
   private static final Set<String> TYPING_LITERAL = Set.of("typing.Literal", "typing_extensions.Literal");
   private static final Set<String> TYPING_ANNOTATED = Set.of("typing.Annotated", "typing_extensions.Annotated");
 
   @Override
   public boolean isValidSubscription(Expression subscriptionObject, String requiredMethod, @Nullable String classRequiredMethod,
-    Map<LocationInFile, String> secondaries) {
+    Map<LocationInFile, String> secondaries, SubscriptionContext context) {
 
     if (subscriptionObject.is(Tree.Kind.GENERATOR_EXPR)) {
       return false;
@@ -75,10 +81,16 @@ public boolean isValidSubscription(Expression subscriptionObject, String require
         return true;
       }
       if (symbol.is(FUNCTION, CLASS)) {
-        return isValidSubscriptionSymbol(symbol, subscriptionObject, secondaries, requiredMethod, classRequiredMethod);
+        return isValidSubscriptionSymbol(symbol, subscriptionObject, secondaries, requiredMethod, classRequiredMethod, context);
       }
     }
 
+    // Preserve the existing V1 check when V2 has no type information at all.
+    if (!(subscriptionObject.typeV2() instanceof UnknownType)
+      && !KNOWN_DECORATOR_EFFECTS.isTrueFor(subscriptionObject, context)) {
+      return true;
+    }
+
     InferredType type = subscriptionObject.type();
     String typeName = InferredTypes.typeName(type);
     String secondaryMessage = typeName != null ? String.format(SECONDARY_MESSAGE, typeName) : DEFAULT_SECONDARY_MESSAGE;
@@ -87,10 +99,11 @@ public boolean isValidSubscription(Expression subscriptionObject, String require
   }
 
   private static boolean isValidSubscriptionSymbol(Symbol symbol, Expression subscriptionObject, Map<LocationInFile, String> secondaries, String requiredMethod,
-    @Nullable String classRequiredMethod) {
+    @Nullable String classRequiredMethod, SubscriptionContext context) {
     LocationInFile locationInFile = symbol.is(FUNCTION) ? ((FunctionSymbol) symbol).definitionLocation() : ((ClassSymbol) symbol).definitionLocation();
     secondaries.put(locationInFile, SECONDARY_MESSAGE.formatted(symbol.name()));
     return isSubscriptionInClassArg(subscriptionObject) 
+      || (symbol.is(CLASS) && !KNOWN_DECORATOR_EFFECTS.isTrueFor(subscriptionObject, context))
       || canHaveMethod(symbol, requiredMethod, classRequiredMethod) 
       || isValidGenericUsage(symbol, subscriptionObject, requiredMethod);
   }
@@ -207,7 +220,6 @@ private static boolean canHaveMethod(Symbol symbol, String requiredMethod, @Null
     }
     ClassSymbol classSymbol = (ClassSymbol) symbol;
     return classSymbol.canHaveMember(requiredMethod)
-      || (classRequiredMethod != null && classSymbol.canHaveMember(classRequiredMethod))
-      || classSymbol.hasDecorators();
+      || (classRequiredMethod != null && classSymbol.canHaveMember(classRequiredMethod));
   }
 }

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

@@ -16,6 +16,7 @@
  */
 package org.sonar.python.checks;
 
+import java.util.List;
 import org.junit.jupiter.api.Test;
 import org.sonar.python.checks.utils.PythonCheckVerifier;
 
@@ -28,7 +29,22 @@ void test_comparison() {
 
   @Test
   void test_arithmetic() {
-    PythonCheckVerifier.verify("src/test/resources/checks/incompatibleOperands/arithmetic.py", new IncompatibleOperandsCheck());
+    PythonCheckVerifier.verify(List.of(
+      "src/test/resources/checks/incompatibleOperands/arithmetic.py",
+      "src/test/resources/checks/classDecorators/importedDecorators.py"), new IncompatibleOperandsCheck());
   }
 
+  @Test
+  void instance_decorator_effects_on_unary_operations() {
+    PythonCheckVerifier.verify(List.of(
+      "src/test/resources/checks/classDecorators/instanceUnary.py",
+      "src/test/resources/checks/classDecorators/importedDecorators.py"), new IncompatibleOperandsCheck());
+  }
+
+  @Test
+  void project_function_marker_remains_conservative() {
+    PythonCheckVerifier.verifyNoIssue(List.of(
+      "src/test/resources/checks/classDecoratorFunctionImpostor/usage.py",
+      "src/test/resources/checks/classDecoratorFunctionImpostor/typing.py"), new IncompatibleOperandsCheck());
+  }
 }

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

@@ -31,12 +31,26 @@ void test_delitem() {
   void test_getitem() {
     PythonCheckVerifier.verify(List.of(
       "src/test/resources/checks/itemOperationsTypeCheck/itemOperations_getitem.py",
-      "src/test/resources/checks/itemOperationsTypeCheck/importedGeneric.py"), new ItemOperationsTypeCheck());
+      "src/test/resources/checks/itemOperationsTypeCheck/importedGeneric.py",
+      "src/test/resources/checks/classDecorators/importedDecorators.py"), new ItemOperationsTypeCheck());
   }
 
   @Test
   void test_setitem() {
     PythonCheckVerifier.verify("src/test/resources/checks/itemOperationsTypeCheck/itemOperations_setitem.py", new ItemOperationsTypeCheck());
   }
 
+  @Test
+  void instance_decorator_effects_on_item_operations() {
+    PythonCheckVerifier.verify(List.of(
+      "src/test/resources/checks/classDecorators/instanceItems.py",
+      "src/test/resources/checks/classDecorators/importedDecorators.py"), new ItemOperationsTypeCheck());
+  }
+
+  @Test
+  void project_function_marker_remains_conservative() {
+    PythonCheckVerifier.verifyNoIssue(List.of(
+      "src/test/resources/checks/classDecoratorFunctionImpostor/usage.py",
+      "src/test/resources/checks/classDecoratorFunctionImpostor/typing.py"), new ItemOperationsTypeCheck());
+  }
 }

python-checks/src/test/resources/checks/classDecoratorFunctionImpostor/typing.py

@@ -0,0 +1,5 @@
+# Project-local module shadowing typing: this function changes the class at runtime.
+def final(cls):
+    cls.__add__ = lambda self, other: 42
+    cls.__class_getitem__ = classmethod(lambda cls, key: 42)
+    return cls

python-checks/src/test/resources/checks/classDecoratorFunctionImpostor/usage.py

@@ -0,0 +1,11 @@
+from typing import final
+
+
+@final
+class C:
+    pass
+
+
+# The project decorator installs both methods; its runtime effects remain unknown.
+assert C[0] == 42
+assert C() + C() == 42

python-checks/src/test/resources/checks/classDecorators/importedDecorators.py

@@ -0,0 +1,15 @@
+def add_protocol(cls):
+    cls.__add__ = lambda self, other: 42
+    cls.__class_getitem__ = classmethod(lambda cls, index: 42)
+    cls.__getitem__ = lambda self, index: 42
+    cls.__setitem__ = lambda self, index, value: None
+    cls.__delitem__ = lambda self, index: None
+    cls.__neg__ = lambda self: 42
+    cls.__pos__ = lambda self: 42
+    cls.__invert__ = lambda self: 42
+    return cls
+
+
+@add_protocol
+class ImportedBase:
+    pass

python-checks/src/test/resources/checks/classDecorators/instanceItems.py

@@ -0,0 +1,66 @@
+from typing import final
+from importedDecorators import add_protocol, ImportedBase
+
+
+@add_protocol
+class Direct:
+    pass
+
+
+class Child(ImportedBase):
+    pass
+
+
+class Plain:
+    pass
+
+
+@final
+class Final:
+    pass
+
+
+@unknown_factory()
+class Unknown:
+    pass
+
+
+def item_operations(condition):
+    direct = Direct()
+    direct[0]
+    direct[0] = 42
+    del direct[0]
+
+    child = Child()
+    child[0]
+    child[0] = 42
+    del child[0]
+
+    plain = Plain()
+    plain[0]  # Noncompliant
+    plain[0] = 42  # Noncompliant
+    del plain[0]  # Noncompliant
+
+    marked = Final()
+    marked[0]  # Noncompliant
+    marked[0] = 42  # Noncompliant
+    del marked[0]  # Noncompliant
+
+    unknown = Unknown()
+    unknown[0]
+    unknown[0] = 42
+    del unknown[0]
+
+    mixed = Final() if condition else Child()
+    mixed[0]
+    mixed[0] = 42
+    del mixed[0]
+
+    # An unknown outer subscription must not hide an invalid inner operation.
+    direct[42[0]]  # Noncompliant
+
+
+# Constructor expressions take the same path as instance variables.
+Direct()[0]
+Child()[0]
+Final()[0]  # Noncompliant