SONARPY-3900 Rule S8490 Enum classes should not be decorated with "@DataClass" (#955)

Co-authored-by: Sonar Vibe Bot <vibe-bot@sonarsource.com>
Co-authored-by: Guillaume Dequenne <guillaume.dequenne@sonarsource.com>
GitOrigin-RevId: 2ea7d69e608246c14839314a1b539e1e06db7457

Author: 3 people

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

@@ -0,0 +1,72 @@
+/*
+ * 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.CallExpression;
+import org.sonar.plugins.python.api.tree.ClassDef;
+import org.sonar.plugins.python.api.tree.Decorator;
+import org.sonar.plugins.python.api.tree.Expression;
+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;
+
+@Rule(key = "S8490")
+public class DataClassOnEnumCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Remove this \"@dataclass\" decorator; it is incompatible with Enum classes.";
+
+  private static final TypeMatcher IS_ENUM_MATCHER = TypeMatchers.any(
+    TypeMatchers.isOrExtendsType("enum.Enum"),
+    TypeMatchers.isOrExtendsType("enum.IntEnum"),
+    TypeMatchers.isOrExtendsType("enum.IntFlag"));
+  private static final TypeMatcher IS_DATACLASS_MATCHER = TypeMatchers.isType("dataclasses.dataclass");
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.CLASSDEF, DataClassOnEnumCheck::checkClassDef);
+  }
+
+  private static void checkClassDef(SubscriptionContext ctx) {
+    ClassDef classDef = (ClassDef) ctx.syntaxNode();
+
+    if (classDef.decorators().isEmpty()) {
+      return;
+    }
+
+    if (!IS_ENUM_MATCHER.isTrueFor(classDef.name(), ctx)) {
+      return;
+    }
+
+    for (Decorator decorator : classDef.decorators()) {
+      Expression decoratorExpr = getDecoratorFunctionExpression(decorator);
+      if (IS_DATACLASS_MATCHER.isTrueFor(decoratorExpr, ctx)) {
+        ctx.addIssue(decorator, MESSAGE);
+      }
+    }
+  }
+
+  private static Expression getDecoratorFunctionExpression(Decorator decorator) {
+    Expression expr = decorator.expression();
+    if (expr instanceof CallExpression callExpr) {
+      return callExpr.callee();
+    }
+    return expr;
+  }
+}

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

@@ -181,6 +181,7 @@ public Stream<Class<?>> getChecks() {
       CorsCheck.class,
       CorsMiddlewareOrderingCheck.class,
       CsrfDisabledCheck.class,
+      DataClassOnEnumCheck.class,
       DataEncryptionCheck.class,
       DbNoPasswordCheck.class,
       DeadStoreCheck.class,

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

@@ -0,0 +1,51 @@
+<p>This is an issue when a class inherits from <code>Enum</code> and is also decorated with <code>@dataclass</code>.</p>
+<h2>Why is this an issue?</h2>
+<p>The <code>@dataclass</code> decorator and <code>Enum</code> classes are incompatible and should not be used together.</p>
+<p>The <code>@dataclass</code> decorator automatically generates special methods like <code>__init__</code>, <code>__repr__</code>, and
+<code>__eq__</code> for regular classes. It modifies the class definition to add these methods based on the class attributes.</p>
+<p>However, <code>Enum</code> classes use a special metaclass called <code>EnumMeta</code> that controls how enum members are created and behave. Enum
+members are not regular instances - they are singleton constants that are created when the class is defined.</p>
+<p>When you try to combine these two features, several problems occur:</p>
+<ul>
+  <li>The <code>@dataclass</code> decorator tries to modify the class in ways that conflict with the Enum metaclass</li>
+  <li>The automatic <code>__init__</code> generation from <code>@dataclass</code> interferes with how Enum members are instantiated</li>
+  <li>At runtime, this typically results in a <code>TypeError</code> because the modifications are incompatible</li>
+</ul>
+<p>Enums are designed to represent a fixed set of named constants, while dataclasses are meant to hold data with potentially varying values. These are
+fundamentally different purposes that should not be mixed.</p>
+<h3>What is the potential impact?</h3>
+<p>This code pattern will cause a <code>TypeError</code> at runtime when Python attempts to create the class. The application will fail to start or
+the module will fail to import, preventing the code from running at all.</p>
+<p>This is a critical reliability issue that blocks normal program execution.</p>
+<h2>How to fix it</h2>
+<p>Remove the <code>@dataclass</code> decorator from the Enum class. Enums work perfectly fine without it and have their own mechanisms for defining
+members.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+from dataclasses import dataclass
+from enum import Enum
+
+@dataclass  # Noncompliant
+class Status(Enum):
+    PENDING = 1
+    APPROVED = 2
+    REJECTED = 3
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+from enum import Enum
+
+class Status(Enum):
+    PENDING = 1
+    APPROVED = 2
+    REJECTED = 3
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/enum.html">Enum</a></li>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses</a></li>
+  <li>PEP 557 - <a href="https://peps.python.org/pep-0557/">Data Classes</a></li>
+</ul>
+

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

@@ -0,0 +1,24 @@
+{
+  "title": "Enum classes should not be decorated with \"@dataclass\"",
+  "type": "BUG",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "pitfall",
+    "enum"
+  ],
+  "defaultSeverity": "Blocker",
+  "ruleSpecification": "RSPEC-8490",
+  "sqKey": "S8490",
+  "scope": "All",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "RELIABILITY": "BLOCKER"
+    },
+    "attribute": "LOGICAL"
+  }
+}

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

@@ -328,6 +328,7 @@
     "S8413",
     "S8414",
     "S8415",
+    "S8490",
     "S8494",
     "S8495",
     "S8504",

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

@@ -0,0 +1,28 @@
+/*
+ * 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 DataClassOnEnumCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify("src/test/resources/checks/dataClassOnEnum.py", new DataClassOnEnumCheck());
+  }
+}

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

@@ -0,0 +1,193 @@
+from dataclasses import dataclass
+from enum import Enum, IntEnum, Flag, IntFlag, StrEnum
+import dataclasses
+
+
+# @dataclass on Enum - Noncompliant cases
+
+@dataclass  # Noncompliant {{Remove this "@dataclass" decorator; it is incompatible with Enum classes.}}
+class Status(Enum):
+    PENDING = 1
+    APPROVED = 2
+    REJECTED = 3
+
+
+# @dataclass with arguments
+
+@dataclass(frozen=True)  # Noncompliant
+class Color(Enum):
+    RED = 1
+    GREEN = 2
+    BLUE = 3
+
+
+# Using dataclasses.dataclass qualified name
+
+@dataclasses.dataclass  # Noncompliant
+class Direction(Enum):
+    NORTH = "N"
+    SOUTH = "S"
+    EAST = "E"
+    WEST = "W"
+
+
+@dataclasses.dataclass(eq=True, order=True)  # Noncompliant
+class Priority(Enum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+
+
+# @dataclass on IntEnum and Flag (transitively extend Enum)
+
+@dataclass  # Noncompliant
+class ErrorCode(IntEnum):
+    NOT_FOUND = 404
+    SERVER_ERROR = 500
+
+
+@dataclass  # Noncompliant
+class Permission(Flag):
+    READ = 1
+    WRITE = 2
+    EXECUTE = 4
+
+
+@dataclass  # Noncompliant
+class FileMode(IntFlag):
+    READ = 4
+    WRITE = 2
+    EXECUTE = 1
+
+
+# @dataclass on StrEnum (Python 3.11+)
+
+@dataclass  # Noncompliant
+class HttpMethod(StrEnum):
+    GET = "GET"
+    POST = "POST"
+
+
+# @dataclass on an indirect Enum subclass
+
+class BaseStatus(Enum):
+    pass
+
+@dataclass  # Noncompliant
+class ExtendedStatus(BaseStatus):
+    PENDING = 1
+    ACTIVE = 2
+
+
+# @dataclass among multiple decorators
+
+def my_decorator(cls):
+    return cls
+
+@my_decorator
+@dataclass  # Noncompliant
+class State(Enum):
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+@dataclass  # Noncompliant
+@my_decorator
+class Stage(Enum):
+    START = 1
+    END = 2
+
+
+# @dataclass with multiple keyword arguments
+
+@dataclass(repr=False, eq=False)  # Noncompliant
+class Suit(Enum):
+    HEARTS = 1
+    DIAMONDS = 2
+    CLUBS = 3
+    SPADES = 4
+
+
+# @dataclass on class with multiple bases including Enum
+
+class Mixin:
+    pass
+
+@dataclass  # Noncompliant
+class Mixed(Mixin, Enum):
+    FIRST = 1
+    SECOND = 2
+
+
+# Compliant: Enum without @dataclass
+
+class CompliantStatus(Enum):
+    PENDING = 1
+    APPROVED = 2
+    REJECTED = 3
+
+
+class CompliantErrorCode(IntEnum):
+    NOT_FOUND = 404
+    SERVER_ERROR = 500
+
+
+class CompliantPermission(Flag):
+    READ = 1
+    WRITE = 2
+    EXECUTE = 4
+
+
+class CompliantHttpMethod(StrEnum):
+    GET = "GET"
+    POST = "POST"
+
+
+# Compliant: @dataclass on a plain class (not Enum)
+
+@dataclass
+class Point:
+    x: float
+    y: float
+
+
+@dataclass(frozen=True)
+class Config:
+    host: str
+    port: int
+
+
+@dataclasses.dataclass
+class Rectangle:
+    width: float
+    height: float
+
+
+# Compliant: custom (non-dataclass) decorator on an Enum
+
+@my_decorator
+class DecoratedStatus(Enum):
+    ACTIVE = 1
+    INACTIVE = 2
+
+
+# Compliant: Enum subclass without @dataclass
+
+class CompliantExtended(BaseStatus):
+    ACTIVE = 1
+    INACTIVE = 2
+
+
+# Compliant: unknown base class — cannot confirm Enum inheritance
+
+@dataclass
+class UnknownBase(UnknownParent):
+    value: int = 0
+
+
+# Compliant: unknown decorator on an Enum — not a dataclass
+
+@unknown_decorator
+class StatusWithUnknownDecorator(Enum):
+    ACTIVE = 1
+    INACTIVE = 2