SONARPY-3991 Rule S8514 Dataclass attributes should use type annotations (#1017)

GitOrigin-RevId: 3535711f601fecbb4368b28f8f07e1632c74d2a5

Author: sonar-nigel[bot]

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

@@ -0,0 +1,70 @@
+/*
+ * 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.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 = "S8514")
+public class DataclassFieldDefinitionCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE_MISSING_ANNOTATION = "Add a type annotation to this dataclass attribute.";
+
+  private static final TypeMatcher IS_DATACLASS = TypeMatchers.isType("dataclasses.dataclass");
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.CLASSDEF, DataclassFieldDefinitionCheck::checkClassDef);
+  }
+
+  private static void checkClassDef(SubscriptionContext ctx) {
+    ClassDef classDef = (ClassDef) ctx.syntaxNode();
+
+    if (!isDataclass(classDef, ctx)) {
+      return;
+    }
+
+    classDef.body().statements().forEach(statement -> checkStatement(ctx, statement));
+  }
+
+  private static boolean isDataclass(ClassDef classDef, SubscriptionContext ctx) {
+    return classDef.decorators().stream().anyMatch(decorator -> isDataclassDecorator(decorator, ctx));
+  }
+
+  private static boolean isDataclassDecorator(Decorator decorator, SubscriptionContext ctx) {
+    Expression expression = decorator.expression();
+    if (expression instanceof CallExpression callExpr) {
+      return IS_DATACLASS.isTrueFor(callExpr.callee(), ctx);
+    }
+    return IS_DATACLASS.isTrueFor(expression, ctx);
+  }
+
+  private static void checkStatement(SubscriptionContext ctx, Tree statement) {
+    if (statement instanceof AssignmentStatement assignmentStatement) {
+      ctx.addIssue(assignmentStatement, MESSAGE_MISSING_ANNOTATION);
+    }
+  }
+}

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

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

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

@@ -0,0 +1,42 @@
+<p>This rule raises an issue when a dataclass contains attributes without type annotations.</p>
+<h2>Why is this an issue?</h2>
+<p>The <code>@dataclass</code> decorator only processes attributes that have type annotations. Attributes without annotations are silently excluded
+from dataclass processing and become regular class variables instead of instance attributes. This means:</p>
+<ul>
+  <li>they are not included in the generated <code>\__init__</code> method</li>
+  <li>they are not part of <code>\__repr__</code> or <code>\__eq__</code></li>
+  <li>they behave as class variables, not instance variables</li>
+</ul>
+<h3>What is the potential impact?</h3>
+<p>Unannotated attributes are silently excluded from initialization, <code>\__repr__</code>, and <code>\__eq__</code>, making them invisible to the
+dataclass contract. These bugs are difficult to trace because the class appears to work normally, but the affected attributes do not participate in
+any of the generated methods.</p>
+<h2>How to fix it</h2>
+<p>Add type annotations to all attributes that should be dataclass fields. If you intend an attribute to be a class variable shared across instances,
+move it outside the dataclass or document this intention clearly.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+    timeout = 30  # Noncompliant: missing type annotation
+    retries = 3   # Noncompliant: missing type annotation
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+    timeout: int = 30
+    retries: int = 3
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li>Python Documentation - <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses — Data Classes</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/S8514.json

@@ -0,0 +1,25 @@
+{
+  "title": "Dataclass attributes should use type annotations",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [
+    "pitfall",
+    "confusing"
+  ],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-8514",
+  "sqKey": "S8514",
+  "scope": "All",
+  "quickfix": "targeted",
+  "code": {
+    "impacts": {
+      "RELIABILITY": "HIGH",
+      "MAINTAINABILITY": "MEDIUM"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}

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

@@ -339,6 +339,7 @@
     "S8505",
     "S8507",
     "S8513",
+    "S8514",
     "S8516",
     "S8517",
     "S8519",

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

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

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

@@ -0,0 +1,195 @@
+from dataclasses import dataclass, field, InitVar
+from datetime import datetime
+from typing import ClassVar, Optional
+
+
+# =======================
+# Issues
+# =======================
+
+@dataclass
+class SingleUnannotatedAttribute:
+    timeout = 30  # Noncompliant {{Add a type annotation to this dataclass attribute.}}
+#   ^^^^^^^^^^^^
+
+
+@dataclass
+class MultipleUnannotatedAttributes:
+    timeout = 30   # Noncompliant {{Add a type annotation to this dataclass attribute.}}
+#   ^^^^^^^^^^^^
+    retries = 3    # Noncompliant {{Add a type annotation to this dataclass attribute.}}
+#   ^^^^^^^^^^^
+
+
+@dataclass
+class MixedAnnotatedAndUnannotated:
+    name: str = "default"
+    timeout = 30  # Noncompliant
+#   ^^^^^^^^^^^^
+
+
+@dataclass(frozen=True)
+class FrozenDataclassUnannotated:
+    timeout = 30  # Noncompliant
+
+
+@dataclass
+class MultipleViolations:
+    unannotated = 42                       # Noncompliant
+    other = "value"                        # Noncompliant
+
+
+import dataclasses
+
+@dataclasses.dataclass
+class QualifiedDecoratorNoncompliant:
+    unannotated = 42  # Noncompliant
+
+
+@dataclass
+class ChildDataclassWithViolation:
+    unannotated = 99  # Noncompliant
+    extra: int = 0
+
+
+def outer_function():
+    # FN: type inference resolves `@dataclass` to Unknown when the decorated class is nested in a function
+    @dataclass
+    class InnerDataclass:
+        value = 10
+        name: str = ""
+
+
+# =======================
+# Compliant
+# =======================
+
+class RegularClassWithUnannotatedAttrs:
+    timeout = 30
+    retries = 3
+
+
+@dataclass
+class ImmutableScalarDefaults:
+    count: int = 0
+    name: str = ""
+    flag: bool = False
+    ratio: float = 1.0
+
+
+@dataclass
+class NoneDefault:
+    opt: Optional[str] = None
+
+
+@dataclass
+class MutableDefaultsAreNotFlagged:
+    members: list = []
+    config: dict = {}
+    tags: set = {1, 2}
+
+
+@dataclass
+class CallDefaultsAreNotFlagged:
+    items: list = list()
+    config: dict = dict()
+    buffer: bytearray = bytearray()
+    created_at: datetime = datetime.now()
+    allowed: frozenset = frozenset([1, 2, 3])
+    tags: set = set()
+
+
+@dataclass
+class FieldDefaultFactoryCompliant:
+    members: list = field(default_factory=list)
+    config: dict = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class FieldDefaultCompliant:
+    count: int = field(default=0)
+    name: str = field(default="hello")
+    derived: int = field(init=False, default=0)
+
+
+@dataclass
+class ClassVarAnnotations:
+    count: ClassVar[int] = 5
+    items: ClassVar[list] = []
+    metadata: ClassVar[dict] = {}
+
+
+@dataclass
+class ClassVarBareForm:
+    count: ClassVar = 0
+
+
+@dataclass
+class InitVarAnnotations:
+    init_value: InitVar[int] = 1
+    init_param: InitVar[str] = "default"
+
+
+@dataclass
+class NoDefaultAnnotatedFields:
+    x: float
+    y: int
+    name: str
+
+
+@dataclass
+class OptionalWithNoneDefault:
+    label: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class FrozenDataclassCompliant:
+    name: str = ""
+    items: list = field(default_factory=list)
+
+
+@dataclasses.dataclass
+class QualifiedDecoratorCompliant:
+    name: str = ""
+    count: int = 0
+
+
+def make_default_list():
+    return []
+
+@dataclass
+class CustomFactoryCompliant:
+    items: list = field(default_factory=make_default_list)
+
+
+@dataclass
+class TupleLiteralDefault:
+    coords: tuple = (0, 0)
+
+
+@dataclass
+class NestedCallDefault:
+    value: str = str(object())
+
+
+@dataclass
+class EmptyDataclass:
+    pass
+
+
+@dataclass
+class DataclassWithOnlyMethods:
+    name: str
+
+    def get_name(self) -> str:
+        return self.name
+
+
+@dataclass
+class ParentDataclass:
+    name: str = ""
+
+
+class NonDataclassChild(ParentDataclass):
+    unannotated = 99