SONARPY-3965 Rule S8495 Functions should return tuples of consistent length (#1004)

GitOrigin-RevId: 115e703b35e94fc608f157b4cb91395814afab84

Author: sonar-nigel[bot]

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

@@ -0,0 +1,114 @@
+/*
+ * 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 java.util.ArrayList;
+import java.util.List;
+import java.util.OptionalInt;
+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.Expression;
+import org.sonar.plugins.python.api.tree.FunctionDef;
+import org.sonar.plugins.python.api.tree.ReturnStatement;
+import org.sonar.plugins.python.api.tree.Tree;
+import org.sonar.plugins.python.api.tree.Tuple;
+
+@Rule(key = "S8495")
+public class InconsistentTupleReturnCheck extends PythonSubscriptionCheck {
+
+  private static final String MESSAGE = "Refactor this function to always return tuples of the same length.";
+  private static final String SECONDARY_MESSAGE = "Returns a %d-tuple.";
+
+  @Override
+  public void initialize(Context context) {
+    context.registerSyntaxNodeConsumer(Tree.Kind.FUNCDEF, InconsistentTupleReturnCheck::checkFunction);
+  }
+
+  private static void checkFunction(SubscriptionContext ctx) {
+    FunctionDef functionDef = (FunctionDef) ctx.syntaxNode();
+
+    ReturnCheckUtils.ReturnStmtCollector collector = ReturnCheckUtils.ReturnStmtCollector.collect(functionDef);
+
+    if (collector.containsYield()) {
+      return;
+    }
+
+    List<ReturnStatement> returnStmts = collector.getReturnStmts();
+
+    List<ReturnWithLength> tupleReturns = new ArrayList<>();
+    for (ReturnStatement returnStmt : returnStmts) {
+      OptionalInt length = getTupleLengthIfTupleReturn(returnStmt);
+      if (length.isPresent()) {
+        tupleReturns.add(new ReturnWithLength(returnStmt, length.getAsInt()));
+      }
+    }
+
+    if (tupleReturns.size() < 2) {
+      return;
+    }
+
+    int firstLength = tupleReturns.get(0).length;
+    boolean allSame = tupleReturns.stream().allMatch(r -> r.length == firstLength);
+    if (allSame) {
+      return;
+    }
+
+    PreciseIssue issue = ctx.addIssue(functionDef.name(), MESSAGE);
+    for (ReturnWithLength tupleReturn : tupleReturns) {
+      issue.secondary(tupleReturn.returnStmt, String.format(SECONDARY_MESSAGE, tupleReturn.length));
+    }
+  }
+
+  private static boolean containsUnpacking(List<Expression> exprs) {
+    return exprs.stream().anyMatch(e -> e.is(Tree.Kind.UNPACKING_EXPR));
+  }
+
+  private static OptionalInt getTupleLengthIfTupleReturn(ReturnStatement returnStmt) {
+    List<Expression> expressions = returnStmt.expressions();
+    if (expressions.isEmpty()) {
+      return OptionalInt.empty();
+    }
+    if (expressions.size() > 1) {
+      // Implicit tuple: return a, b — skip if any element is a star expression
+      if (containsUnpacking(expressions)) {
+        return OptionalInt.empty();
+      }
+      return OptionalInt.of(expressions.size());
+    }
+    // Single expression - check if it's an explicit tuple literal
+    Expression expr = expressions.get(0);
+    if (expr.is(Tree.Kind.TUPLE)) {
+      Tuple tuple = (Tuple) expr;
+      if (containsUnpacking(tuple.elements())) {
+        return OptionalInt.empty();
+      }
+      return OptionalInt.of(tuple.elements().size());
+    }
+    return OptionalInt.empty();
+  }
+
+  private static class ReturnWithLength {
+    final ReturnStatement returnStmt;
+    final int length;
+
+    ReturnWithLength(ReturnStatement returnStmt, int length) {
+      this.returnStmt = returnStmt;
+      this.length = length;
+    }
+  }
+}

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

@@ -280,6 +280,7 @@ public Stream<Class<?>> getChecks() {
       ImpossibleBackReferenceCheck.class,
       ImpossibleBoundariesCheck.class,
       IncompatibleOperandsCheck.class,
+      InconsistentTupleReturnCheck.class,
       InconsistentTypeHintCheck.class,
       IncorrectExceptionTypeCheck.class,
       IncorrectParameterDatetimeConstructorsCheck.class,

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

@@ -0,0 +1,49 @@
+<p>This rule raises an issue when a function returns tuples of different lengths in different code paths.</p>
+<h2>Why is this an issue?</h2>
+<p>When a function returns tuples of varying lengths, it creates an inconsistent API that is difficult to use correctly. Callers cannot reliably
+unpack the return value without checking its length first, which leads to fragile code.</p>
+<p>Consider this example:</p>
+<pre>
+def process_data(value):
+    if value &gt; 0:
+        return (value,)  # Returns a 1-tuple
+    else:
+        return (value, value * 2)  # Returns a 2-tuple
+
+result = process_data(10)
+x, y = result  # ValueError if value &gt; 0!
+</pre>
+<p>This forces callers to add defensive length-checks before unpacking, making the code fragile and harder to maintain. The function signature
+provides no indication that the return type varies, so developers must read the implementation or discover the behavior through runtime errors.</p>
+<p>Consistent return types make code more predictable, easier to test, and less likely to cause unexpected failures in production.</p>
+<h3>What is the potential impact?</h3>
+<p>Runtime errors from tuple unpacking may not surface during initial testing if certain code paths are not fully exercised, leading to production
+failures. The need for defensive length-checking also increases the maintenance burden and makes the API harder to document for new team members.</p>
+<h2>How to fix it</h2>
+<p>Make all return statements return tuples of the same length. Add placeholder values (like <code>None</code> or <code>0</code>) to shorter tuples
+to maintain consistency.</p>
+<h3>Code examples</h3>
+<h4>Noncompliant code example</h4>
+<pre data-diff-id="1" data-diff-type="noncompliant">
+def calculate_stats(numbers):
+    if not numbers:
+        return (0,)  # Noncompliant
+    total = sum(numbers)
+    average = total / len(numbers)
+    return (total, average)
+</pre>
+<h4>Compliant solution</h4>
+<pre data-diff-id="1" data-diff-type="compliant">
+def calculate_stats(numbers):
+    if not numbers:
+        return (0, 0)  # Consistent 2-tuple
+    total = sum(numbers)
+    average = total / len(numbers)
+    return (total, average)
+</pre>
+<h2>Resources</h2>
+<h3>Documentation</h3>
+<ul>
+  <li>Python Documentation - <a href="https://docs.python.org/3/tutorial/controlflow.html#more-on-defining-functions">More on Defining Functions</a></li>
+  <li>Python Documentation - <a href="https://docs.python.org/3/tutorial/datastructures.html#tuples-and-sequences">Tuples and Sequences</a></li>
+</ul>

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

@@ -0,0 +1,21 @@
+{
+  "title": "Functions should return tuples of consistent length",
+  "type": "CODE_SMELL",
+  "status": "ready",
+  "remediation": {
+    "func": "Constant\/Issue",
+    "constantCost": "5min"
+  },
+  "tags": [],
+  "defaultSeverity": "Major",
+  "ruleSpecification": "RSPEC-8495",
+  "sqKey": "S8495",
+  "scope": "Main",
+  "quickfix": "unknown",
+  "code": {
+    "impacts": {
+      "MAINTAINABILITY": "HIGH"
+    },
+    "attribute": "CONVENTIONAL"
+  }
+}

python-checks/src/test/java/org/sonar/python/checks/InconsistentTupleReturnCheckTest.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 InconsistentTupleReturnCheckTest {
+
+  @Test
+  void test() {
+    PythonCheckVerifier.verify(
+      "src/test/resources/checks/inconsistentTupleReturn.py",
+      new InconsistentTupleReturnCheck());
+  }
+}