SONARPY-3680 Added type matcher for any match in a union type (#792)

GitOrigin-RevId: d3df08f82830007ba7246f978b2b0dee6a9e707a

Author: joke1196

.claude/skills/type-matchers/SKILL.md

@@ -202,6 +202,49 @@ Checks if the type has a specific TypeSource (e.g., EXACT, INFERRED, STUBBED).
 TypeMatchers.hasTypeSource(TypeSource.EXACT)
 ```
 
+### Union Type Matching
+
+#### `isAnyTypeInUnionSatisfying(TypeMatcher matcher)`
+Checks if **any** candidate in a UnionType satisfies the given matcher. Returns FALSE if the type is not a UnionType.
+
+**Important:** This matcher has **different semantics** than regular TypeMatchers for unions:
+- Regular matchers require **ALL** union candidates to match
+- This matcher requires **ANY** union candidate to match (OR logic)
+
+```java
+// Check if any type in Union[int, str, list] is a string
+InternalTypeMatchers.isAnyTypeInUnionSatisfying(
+  TypeMatchers.isType("builtins.str")
+)  // Returns TRUE
+```
+
+**Entry Point:** `org.sonar.python.types.v2.matchers.InternalTypeMatchers`
+
+**Behavior:**
+- Returns `TRUE` if at least one candidate satisfies the matcher
+- Returns `FALSE` if all candidates fail to satisfy the matcher
+- Returns `UNKNOWN` if no candidates match but at least one returns UNKNOWN
+- Returns `FALSE` for non-union types
+- Returns `UNKNOWN` for UnknownType
+
+**Use Case:** This is useful when you need to check if a union contains a specific type, such as checking if `Union[int, str, None]` contains `None`.
+
+**Example:**
+```java
+import org.sonar.python.types.v2.matchers.InternalTypeMatchers;
+
+// Check if a union contains None
+private static final TypeMatcher CONTAINS_NONE =
+  InternalTypeMatchers.isAnyTypeInUnionSatisfying(
+    TypeMatchers.isType("builtins.NoneType")
+  );
+
+// Usage
+if (CONTAINS_NONE.isTrueFor(expression, ctx)) {
+  // The type is a union that includes None
+}
+```
+
 ## Common Patterns
 
 ### Checking for List or Tuple of Specific Type
@@ -238,6 +281,17 @@ TypeMatchers.all(
 )
 ```
 
+### Checking if a Union Contains a Specific Type
+
+```java
+import org.sonar.python.types.v2.matchers.InternalTypeMatchers;
+
+// Check if Union[int, str, None] contains None
+InternalTypeMatchers.isAnyTypeInUnionSatisfying(
+  TypeMatchers.isType("builtins.NoneType")
+)
+```
+
 ## TypeMatcher Interface
 
 The `TypeMatcher` interface provides two methods for evaluating expressions:
@@ -351,4 +405,4 @@ if (matcher.isTrueFor(expression, ctx)) {
 
 ## Summary
 
-The TypeMatchers API provides a robust, composable way to match types in the Python plugin. Always prefer it over deprecated APIs, use type equality over FQN matching, and remember to explicitly handle ObjectTypes with `isObjectSatisfying()`.
+The TypeMatchers API provides a robust, composable way to match types in the Python plugin. Always prefer it over deprecated APIs, use type equality over FQN matching, and remember to explicitly handle ObjectTypes with `isObjectSatisfying()`.

python-frontend/src/main/java/org/sonar/plugins/python/api/types/v2/matchers/TypeMatcher.java

@@ -22,7 +22,7 @@
 import org.sonar.plugins.python.api.tree.Expression;
 
 @Beta
-public sealed interface TypeMatcher permits TypeMatcherImpl {
+public interface TypeMatcher {
   @Beta
   TriBool evaluateFor(Expression expr, SubscriptionContext ctx);
 

python-frontend/src/main/java/org/sonar/plugins/python/api/types/v2/matchers/TypeMatchers.java

@@ -30,6 +30,7 @@
 import org.sonar.python.types.v2.matchers.IsObjectSatisfyingPredicate;
 import org.sonar.python.types.v2.matchers.IsTypeOrSuperTypeSatisfyingPredicate;
 import org.sonar.python.types.v2.matchers.IsTypePredicate;
+import org.sonar.python.types.v2.matchers.TypeMatcherImpl;
 import org.sonar.python.types.v2.matchers.TypePredicate;
 import org.sonar.python.types.v2.matchers.TypeSourcePredicate;
 

python-frontend/src/main/java/org/sonar/python/types/v2/matchers/InternalTypeMatchers.java

@@ -0,0 +1,38 @@
+/*
+ * 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.types.v2.matchers;
+
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
+
+
+public final class InternalTypeMatchers {
+
+  private InternalTypeMatchers() {
+  }
+
+  public static TypeMatcher isAnyTypeInUnionSatisfying(TypeMatcher matcher) {
+    TypePredicate predicate = getTypePredicate(matcher);
+    return new TypeMatcherImpl(new IsAnyTypeInUnionSatisfying(predicate));
+  }
+
+  private static TypePredicate getTypePredicate(TypeMatcher matcher) {
+    if (matcher instanceof TypeMatcherImpl typeMatcherImpl) {
+      return typeMatcherImpl.predicate();
+    }
+    throw new IllegalArgumentException("Unsupported type matcher: " + matcher.getClass().getName());
+  }
+}

python-frontend/src/main/java/org/sonar/python/types/v2/matchers/IsAnyTypeInUnionSatisfying.java

@@ -0,0 +1,54 @@
+/*
+ * 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.types.v2.matchers;
+
+import org.sonar.plugins.python.api.TriBool;
+import org.sonar.plugins.python.api.types.v2.PythonType;
+import org.sonar.plugins.python.api.types.v2.UnionType;
+import org.sonar.plugins.python.api.types.v2.UnknownType;
+
+public class IsAnyTypeInUnionSatisfying implements TypePredicate {
+  private final TypePredicate wrappedPredicate;
+
+  public IsAnyTypeInUnionSatisfying(TypePredicate wrappedPredicate) {
+    this.wrappedPredicate = wrappedPredicate;
+  }
+
+  @Override
+  public TriBool check(PythonType type, TypePredicateContext ctx) {
+    if (type instanceof UnknownType) {
+      return TriBool.UNKNOWN;
+    }
+    
+    if (!(type instanceof UnionType unionType)) {
+      return TriBool.FALSE;
+    }
+    
+    boolean hasUnknown = false;
+    for (PythonType candidate : unionType.candidates()) {
+      TriBool result = wrappedPredicate.check(candidate, ctx);
+      if (result == TriBool.TRUE) {
+        return TriBool.TRUE;
+      }
+      if (result == TriBool.UNKNOWN) {
+        hasUnknown = true;
+      }
+    }
+    
+    return hasUnknown ? TriBool.UNKNOWN : TriBool.FALSE;
+  }
+}

…i/types/v2/matchers/TypeMatcherImpl.java …n/types/v2/matchers/TypeMatcherImpl.javapython-frontend/src/main/java/org/sonar/plugins/python/api/types/v2/matchers/TypeMatcherImpl.java renamed to python-frontend/src/main/java/org/sonar/python/types/v2/matchers/TypeMatcherImpl.java python-frontend/src/main/java/org/sonar/plugins/python/api/types/v2/matchers/TypeMatcherImpl.java renamed to python-frontend/src/main/java/org/sonar/python/types/v2/matchers/TypeMatcherImpl.java

@@ -14,20 +14,17 @@
  * 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.plugins.python.api.types.v2.matchers;
+package org.sonar.python.types.v2.matchers;
 
 import org.sonar.api.Beta;
 import org.sonar.plugins.python.api.SubscriptionContext;
 import org.sonar.plugins.python.api.TriBool;
 import org.sonar.plugins.python.api.tree.Expression;
 import org.sonar.plugins.python.api.types.v2.PythonType;
-import org.sonar.python.types.v2.matchers.TypePredicate;
-import org.sonar.python.types.v2.matchers.TypePredicateContext;
-import org.sonar.python.types.v2.matchers.TypePredicateUtils;
+import org.sonar.plugins.python.api.types.v2.matchers.TypeMatcher;
 
-// This record is package-private
 @Beta
-record TypeMatcherImpl(TypePredicate predicate) implements TypeMatcher {
+public record TypeMatcherImpl(TypePredicate predicate) implements TypeMatcher {
 
   @Override
   public TriBool evaluateFor(Expression expr, SubscriptionContext ctx) {
@@ -41,4 +38,4 @@ public boolean isTrueFor(Expression expr, SubscriptionContext ctx) {
     return evaluateFor(expr, ctx).isTrue();
   }
 
-}
+}

python-frontend/src/main/java/org/sonar/python/types/v2/matchers/TypePredicateUtils.java

@@ -26,6 +26,9 @@ private TypePredicateUtils() {
   }
 
   public static TriBool evaluate(TypePredicate predicate, PythonType type, TypePredicateContext ctx) {
+    if(predicate.check(type, ctx).isTrue()){
+      return TriBool.TRUE;
+    }
     Set<PythonType> candidates = extractCandidates(type);
 
     TriBool result = TriBool.TRUE;

python-frontend/src/test/java/org/sonar/plugins/python/api/types/v2/matchers/MatchersTestUtils.java

@@ -20,6 +20,7 @@
 import org.sonar.plugins.python.api.TriBool;
 import org.sonar.plugins.python.api.types.v2.PythonType;
 import org.sonar.python.types.v2.matchers.TypePredicate;
+import org.sonar.python.types.v2.matchers.TypeMatcherImpl;
 import org.sonar.python.types.v2.matchers.TypePredicateContext;
 
 import static org.mockito.ArgumentMatchers.any;

python-frontend/src/test/java/org/sonar/plugins/python/api/types/v2/matchers/TypeMatcherImplTest.java

@@ -32,6 +32,7 @@
 import org.sonar.plugins.python.api.types.v2.UnknownType;
 import org.sonar.python.semantic.v2.TestProject;
 import org.sonar.python.semantic.v2.typetable.TypeTable;
+import org.sonar.python.types.v2.matchers.InternalTypeMatchers;
 import org.sonar.python.types.v2.matchers.TypePredicate;
 import org.sonar.python.types.v2.matchers.TypePredicateContext;
 
@@ -94,6 +95,7 @@ void prepare() {
     unionOfFunctionExpr = Mockito.mock(Expression.class);
     unionOfObjectExpr = Mockito.mock(Expression.class);
 
+
     Mockito.when(unknownExpr.typeV2()).thenReturn(unknownType);
     Mockito.when(objectExpr.typeV2()).thenReturn(objectType);
     Mockito.when(functionExpr.typeV2()).thenReturn(functionType);
@@ -202,5 +204,26 @@ def __init__(self):
     assertThat(TypeMatchers.isObjectOfType("my_file.A").evaluateFor(unknownTypeExpression, ctx)).isEqualTo(TriBool.UNKNOWN);
     assertThat(TypeMatchers.isObjectOfType("my_file.B").evaluateFor(knownTypeExpression, ctx)).isEqualTo(TriBool.UNKNOWN);
   }
-}
 
+  @Test
+  void testIsAnyTypeInUnionSatisfying() {
+    var project = new TestProject();
+    project.addModule("my_file.py", """
+      class A :
+        def __init__(self):
+         pass
+      """);
+    Expression unionTypeExpression = project.lastExpression("""
+      from my_file import A
+      def foo(param: int | A | str):
+        param
+      """);
+
+    SubscriptionContext ctx = Mockito.mock(SubscriptionContext.class);
+    Mockito.when(ctx.typeTable()).thenReturn(project.projectLevelTypeTable());
+
+    assertThat(unionTypeExpression.typeV2()).isInstanceOf(UnionType.class);
+    assertThat(InternalTypeMatchers.isAnyTypeInUnionSatisfying(TypeMatchers.isObjectOfType("my_file.A")).isTrueFor(unionTypeExpression, ctx)).isTrue();
+
+  }
+}

python-frontend/src/test/java/org/sonar/python/types/v2/matchers/IsAnyTypeInUnionSatisfyingTest.java

@@ -0,0 +1,100 @@
+/*
+ * 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.types.v2.matchers;
+
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.mockito.Mockito;
+import org.sonar.plugins.python.api.TriBool;
+import org.sonar.plugins.python.api.types.v2.PythonType;
+import org.sonar.plugins.python.api.types.v2.UnionType;
+import org.sonar.plugins.python.api.types.v2.UnknownType;
+import org.sonar.plugins.python.api.types.v2.matchers.MatchersTestUtils;
+import org.sonar.python.semantic.v2.typetable.TypeTable;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class IsAnyTypeInUnionSatisfyingTest {
+
+  @Test
+  void testUnionTypeWithOneMatchingCandidate() {
+    PythonType candidate1 = Mockito.mock(PythonType.class);
+    PythonType candidate2 = Mockito.mock(PythonType.class);
+    UnionType unionType = (UnionType) UnionType.or(candidate1, candidate2);
+
+    TypePredicate wrappedPredicate = MatchersTestUtils.mockPredicateReturning(candidate1, TriBool.TRUE);
+    Mockito.when(wrappedPredicate.check(Mockito.eq(candidate2), Mockito.any())).thenReturn(TriBool.FALSE);
+
+    TriBool result = checkType(unionType, wrappedPredicate);
+    assertThat(result).isEqualTo(TriBool.TRUE);
+  }
+
+  @Test
+  void testUnionTypeWithAllNonMatchingCandidates() {
+    PythonType candidate1 = Mockito.mock(PythonType.class);
+    PythonType candidate2 = Mockito.mock(PythonType.class);
+    UnionType unionType = (UnionType) UnionType.or(candidate1, candidate2);
+
+    TypePredicate wrappedPredicate = MatchersTestUtils.mockPredicateReturning(candidate1, TriBool.FALSE);
+    Mockito.when(wrappedPredicate.check(Mockito.eq(candidate2), Mockito.any())).thenReturn(TriBool.FALSE);
+
+    TriBool result = checkType(unionType, wrappedPredicate);
+    assertThat(result).isEqualTo(TriBool.FALSE);
+  }
+
+  @Test
+  void testUnionTypeWithUnknownCandidate() {
+    PythonType candidate1 = Mockito.mock(PythonType.class);
+    PythonType candidate2 = Mockito.mock(PythonType.class);
+    UnionType unionType = (UnionType) UnionType.or(candidate1, candidate2);
+
+    TypePredicate wrappedPredicate = MatchersTestUtils.mockPredicateReturning(candidate1, TriBool.FALSE);
+    Mockito.when(wrappedPredicate.check(Mockito.eq(candidate2), Mockito.any())).thenReturn(TriBool.UNKNOWN);
+
+    TriBool result = checkType(unionType, wrappedPredicate);
+    assertThat(result).isEqualTo(TriBool.UNKNOWN);
+  }
+
+
+  @ParameterizedTest
+  @MethodSource("nonUnionTypesWithExpectedResults")
+  void testNonUnionTypeDoesNotDelegateToWrappedPredicate(PythonType nonUnionType, TriBool expectedResult) {
+    TypePredicate wrappedPredicate = Mockito.mock(TypePredicate.class);
+
+    TriBool result = checkType(nonUnionType, wrappedPredicate);
+
+    assertThat(result).isEqualTo(expectedResult);
+    Mockito.verifyNoInteractions(wrappedPredicate);
+  }
+
+  static Stream<Arguments> nonUnionTypesWithExpectedResults() {
+    return Stream.of(
+      Arguments.of(PythonType.UNKNOWN, TriBool.UNKNOWN),
+      Arguments.of(new UnknownType.UnresolvedImportType("some.module"), TriBool.UNKNOWN),
+      Arguments.of(Mockito.mock(PythonType.class), TriBool.FALSE)
+    );
+  }
+
+  private static TriBool checkType(PythonType type, TypePredicate wrappedPredicate) {
+    IsAnyTypeInUnionSatisfying predicate = new IsAnyTypeInUnionSatisfying(wrappedPredicate);
+    TypePredicateContext ctx = TypePredicateContext.of(Mockito.mock(TypeTable.class));
+    return predicate.check(type, ctx);
+  }
+}