PLUGINAPI-72 Deprecate 'status' and 'resolution' in favor of 'issueStatus'

benjamin-campomenosi-sonarsource · leo-geoffroy-sonarsource · commit 3fb805e20d2b · 2024-01-19T09:52:54.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,14 @@
 # Changelog
 
+## 10.5
+
+* Introduce `org.sonar.api.issue.IssueStatus` to simplify `status` and `resolution` on issues.
+* Deprecate `org.sonar.api.ce.measure.Issue.status()` and `org.sonar.api.ce.measure.Issue.resolution()`. Use `org.sonar.api.ce.measure.Issue.issueStatus()` method instead.
+* Deprecate `org.sonar.api.issue.Issue.status()` and `org.sonar.api.issue.Issue.resolution()`. No replacement.
+* Deprecate `STATUS_OPEN`, `STATUS_CONFIRMED`, `STATUS_REOPENED`, `STATUS_RESOLVED`, `STATUS_CLOSED`,
+  `RESOLUTION_FIXED`, `RESOLUTION_FALSE_POSITIVE`, `RESOLUTION_REMOVED`, `RESOLUTION_WONT_FIX`, use `org.sonar.api.issue.IssueStatus` enum instead
+* Deprecate `RESOLUTION_SAFE`, `RESOLUTION_ACKNOWLEDGED`, `STATUS_TO_REVIEW`, `STATUS_REVIEWED`. No replacement.
+
 ## 10.4
 
 * Add new metrics `org.sonar.api.measures.CoreMetrics.NEW_ACCEPTED_ISSUES` and `org.sonar.api.measures.CoreMetrics.HIGH_IMPACT_ACCEPTED_ISSUES`.
diff --git a/plugin-api/src/main/java/org/sonar/api/ce/measure/Issue.java b/plugin-api/src/main/java/org/sonar/api/ce/measure/Issue.java
@@ -21,6 +21,7 @@
 
 import java.util.Map;
 import javax.annotation.CheckForNull;
+import org.sonar.api.issue.IssueStatus;
 import org.sonar.api.issue.impact.Severity;
 import org.sonar.api.issue.impact.SoftwareQuality;
 import org.sonar.api.rule.RuleKey;
@@ -40,15 +41,27 @@ public interface Issue {
 
   /**
    * Available list of status can be found in {@link org.sonar.api.issue.Issue#STATUSES}
+   *
+   * @deprecated since 10.4 in favor of {@link Issue#issueStatus()}
    */
+  @Deprecated(since = "10.4")
   String status();
 
   /**
    * Available list of resolutions can be found in {@link org.sonar.api.issue.Issue#RESOLUTIONS}
+   *
+   * @deprecated since 10.4 in favor of {@link Issue#issueStatus()}
    */
   @CheckForNull
+  @Deprecated(since = "10.4")
   String resolution();
 
+  /**
+   * @since 10.4
+   * Available list of status can be found in {@link IssueStatus#values()}
+   */
+  IssueStatus issueStatus();
+
   /**
    * See constants in {@link org.sonar.api.rule.Severity}.
    * @deprecated since 10.1, use {@link #impacts()} instead
diff --git a/plugin-api/src/main/java/org/sonar/api/issue/Issue.java b/plugin-api/src/main/java/org/sonar/api/issue/Issue.java
@@ -46,69 +46,114 @@ public interface Issue extends Serializable {
 
   /**
    * Default status when creating an issue.
+   *
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
    */
+  @Deprecated(since = "10.4")
   String STATUS_OPEN = "OPEN";
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String STATUS_CONFIRMED = "CONFIRMED";
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String STATUS_REOPENED = "REOPENED";
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String STATUS_RESOLVED = "RESOLVED";
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
   String STATUS_CLOSED = "CLOSED";
-
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String RESOLUTION_FIXED = "FIXED";
 
   /**
    * Resolution when issue is flagged as false positive.
    */
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String RESOLUTION_FALSE_POSITIVE = "FALSE-POSITIVE";
 
   /**
    * Resolution when rule has been uninstalled or disabled in the Quality profile.
-    */
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   String RESOLUTION_REMOVED = "REMOVED";
 
   /**
    * Issue is irrelevant in the context and was muted by user.
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
    * @since 5.1
    */
+  @Deprecated(since = "10.4")
   String RESOLUTION_WONT_FIX = "WONTFIX";
 
   /**
    * Security Hotspot has been reviewed and resolved as safe.
+   * @deprecated since 10.4 as Security Hotspot are deprecated.
    * @since 8.1
    */
+  @Deprecated(since = "10.4")
   String RESOLUTION_SAFE = "SAFE";
 
   /**
    * Security Hotspot has been reviewed and acknowledged that it poses a risk.
+   * @deprecated since 10.4 as Security Hotspot are deprecated.
    * @since 9.4
    */
+  @Deprecated(since = "10.4")
   String RESOLUTION_ACKNOWLEDGED = "ACKNOWLEDGED";
 
+  /**
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
+   */
+  @Deprecated(since = "10.4")
   List<String> RESOLUTIONS = List.of(RESOLUTION_FALSE_POSITIVE, RESOLUTION_WONT_FIX, RESOLUTION_FIXED,
     RESOLUTION_REMOVED);
 
+  /**
+   * @deprecated since 10.4 as Security Hotspot are deprecated
+   */
+  @Deprecated(since = "10.4")
   List<String> SECURITY_HOTSPOT_RESOLUTIONS = List.of(RESOLUTION_FIXED, RESOLUTION_SAFE, RESOLUTION_ACKNOWLEDGED);
 
   /**
-   * @since 7.8
+   * @deprecated since 10.4 as Security Hotspot are deprecated
    */
+  @Deprecated(since = "10.4")
   String STATUS_TO_REVIEW = "TO_REVIEW";
 
   /**
    * @deprecated since 8.1, status has been mapped as `TO_REVIEW`
    */
-  @Deprecated
+  @Deprecated(since = "8.1")
   String STATUS_IN_REVIEW = "IN_REVIEW";
 
   /**
-   * @since 7.8
+   * @deprecated since 10.4 as Security Hotspot are deprecated
    */
+  @Deprecated(since = "10.4")
   String STATUS_REVIEWED = "REVIEWED";
 
   /**
    * Return all available statuses
    *
    * @since 4.4
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
    */
+  @Deprecated(since = "10.4")
   List<String> STATUSES = List.of(STATUS_OPEN, STATUS_CONFIRMED, STATUS_REOPENED, STATUS_RESOLVED, STATUS_CLOSED,
     STATUS_TO_REVIEW, STATUS_REVIEWED);
 
@@ -161,13 +206,17 @@ public interface Issue extends Serializable {
 
   /**
    * See constant values in {@link Issue}.
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
    */
+  @Deprecated(since = "10.4")
   String status();
 
   /**
    * The type of resolution, or null if the issue is not resolved. See constant values in {@link Issue}.
+   * @deprecated since 10.4 in favor of {@link IssueStatus}
    */
   @CheckForNull
+  @Deprecated(since = "10.4")
   String resolution();
 
   /**
@@ -212,13 +261,15 @@ public interface Issue extends Serializable {
 
   /**
    * During a scan return if the current issue is a new one.
+   *
    * @return always false on server side
    * @since 4.0
    */
   boolean isNew();
 
   /**
    * During a scan returns true if the issue is copied from another branch.
+   *
    * @since 6.6
    */
   boolean isCopied();
diff --git a/plugin-api/src/main/java/org/sonar/api/issue/IssueStatus.java b/plugin-api/src/main/java/org/sonar/api/issue/IssueStatus.java
@@ -0,0 +1,86 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * 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 GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.api.issue;
+
+import javax.annotation.CheckForNull;
+import javax.annotation.Nullable;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * @since 10.4
+ */
+public enum IssueStatus {
+
+
+  OPEN,
+
+  @Deprecated(since = "10.4")
+  /**
+   * @deprecated use {@link IssueStatus#ACCEPTED} instead
+   */
+  CONFIRMED,
+  FALSE_POSITIVE,
+  ACCEPTED,
+  FIXED;
+
+  private static final Logger LOGGER = LoggerFactory.getLogger(IssueStatus.class);
+
+  @CheckForNull
+  public static IssueStatus of(@Nullable String status, @Nullable String resolution) {
+
+    //null status is not supposed to happen, but since it is nullable in products, we want the mapping to be resilient.
+    if (status == null) {
+      LOGGER.warn("Missing status, falling back to {}", IssueStatus.OPEN);
+      return IssueStatus.OPEN;
+    }
+
+    switch (status) {
+      case Issue.STATUS_OPEN:
+      case Issue.STATUS_REOPENED:
+        return IssueStatus.OPEN;
+      case Issue.STATUS_CONFIRMED:
+        return IssueStatus.CONFIRMED;
+      case Issue.STATUS_CLOSED:
+        return IssueStatus.FIXED;
+      // Security hotspot should not return issue status as they are deprecated.
+      case Issue.STATUS_REVIEWED:
+      case Issue.STATUS_TO_REVIEW:
+        return null;
+      default:
+    }
+    if (Issue.STATUS_RESOLVED.equals(status) && resolution != null) {
+      switch (resolution) {
+        case Issue.RESOLUTION_FALSE_POSITIVE:
+          return IssueStatus.FALSE_POSITIVE;
+        case Issue.RESOLUTION_WONT_FIX:
+          return IssueStatus.ACCEPTED;
+        case Issue.RESOLUTION_FIXED:
+          return IssueStatus.FIXED;
+        default:
+      }
+    }
+
+
+    LOGGER.warn("Can't find mapped issue status for status '{}' and resolution '{}'", status, resolution);
+    return null;
+  }
+}
+
diff --git a/plugin-api/src/test/java/org/sonar/api/issue/IssueStatusTest.java b/plugin-api/src/test/java/org/sonar/api/issue/IssueStatusTest.java
@@ -0,0 +1,81 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * 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 GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.api.issue;
+
+import org.junit.Rule;
+import org.junit.Test;
+import org.sonar.api.testfixtures.log.LogAndArguments;
+import org.sonar.api.testfixtures.log.LogTester;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class IssueStatusTest {
+  @Rule
+  public LogTester logTester = new LogTester();
+
+  @Test
+  public void of_shouldMapToCorrectIssueStatus() {
+    assertThat(IssueStatus.of(Issue.STATUS_RESOLVED, Issue.RESOLUTION_FIXED))
+      .isEqualTo(IssueStatus.FIXED);
+
+    assertThat(IssueStatus.of(Issue.STATUS_CONFIRMED, null))
+      .isEqualTo(IssueStatus.CONFIRMED);
+
+    assertThat(IssueStatus.of(Issue.STATUS_RESOLVED, Issue.RESOLUTION_FALSE_POSITIVE))
+      .isEqualTo(IssueStatus.FALSE_POSITIVE);
+
+    assertThat(IssueStatus.of(Issue.STATUS_RESOLVED, Issue.RESOLUTION_WONT_FIX))
+      .isEqualTo(IssueStatus.ACCEPTED);
+
+    assertThat(IssueStatus.of(Issue.STATUS_REOPENED, null))
+      .isEqualTo(IssueStatus.OPEN);
+
+    assertThat(IssueStatus.of(Issue.STATUS_CLOSED, null))
+      .isEqualTo(IssueStatus.FIXED);
+  }
+
+  @Test
+  public void of_shouldReturnNull_whenStatusBelongsToHotspot() {
+    assertThat(IssueStatus.of(Issue.STATUS_TO_REVIEW, null))
+      .isNull();
+
+    assertThat(IssueStatus.of(Issue.STATUS_REVIEWED, Issue.RESOLUTION_SAFE))
+      .isNull();
+
+    assertThat(IssueStatus.of(Issue.STATUS_REVIEWED, Issue.RESOLUTION_ACKNOWLEDGED))
+      .isNull();
+  }
+
+  @Test
+  public void of_shouldLogWarning_whenUnknownMapping() {
+    assertThat(IssueStatus.of(Issue.STATUS_RESOLVED, null)).isNull();
+    assertThat(logTester.getLogs()).extracting(LogAndArguments::getFormattedMsg).contains("Can't find mapped issue status for status 'RESOLVED' and resolution 'null'");
+
+    assertThat(IssueStatus.of(Issue.STATUS_RESOLVED, Issue.RESOLUTION_SAFE)).isNull();
+    assertThat(logTester.getLogs()).extracting(LogAndArguments::getFormattedMsg).contains("Can't find mapped issue status for status 'RESOLVED' and resolution 'SAFE'");
+  }
+
+  @Test
+  public void of_shouldLogWarning_whenStatusIsNull() {
+    assertThat(IssueStatus.of(null, null)).isEqualTo(IssueStatus.OPEN);
+    assertThat(logTester.getLogs()).extracting(LogAndArguments::getFormattedMsg).contains("Missing status, falling back to OPEN");
+  }
+
+}
diff --git a/test-fixtures/src/main/java/org/sonar/api/testfixtures/measure/TestIssue.java b/test-fixtures/src/main/java/org/sonar/api/testfixtures/measure/TestIssue.java
diff --git a/test-fixtures/src/test/java/org/sonar/api/testfixtures/measure/TestIssueTest.java b/test-fixtures/src/test/java/org/sonar/api/testfixtures/measure/TestIssueTest.java
