PLUGINAPI-180 New API for sonar-resolve code annotations

Author: ericg138

plugin-api/src/main/java/org/sonar/api/issue/SonarResolveData.java

@@ -0,0 +1,72 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-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 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 java.util.Set;
+import javax.annotation.Nullable;
+import org.sonar.api.rule.RuleKey;
+
+/**
+ * Holds per-line annotation data parsed from {@code //sonar-resolve} comments.
+ * @since 13.5
+ */
+public final class SonarResolveData {
+
+  public enum Status {
+    ACCEPT,
+    FALSE_POSITIVE
+  }
+
+  private final Set<RuleKey> ruleKeys;
+  private final String comment;
+  private final Status status;
+
+  /**
+   * @param ruleKeys the set of rule keys targeted by the annotation
+   * @param comment  the justification comment
+   * @param status   the target status, or {@code null} to default to {@link Status#ACCEPT}
+   */
+  public SonarResolveData(Set<RuleKey> ruleKeys, String comment, @Nullable Status status) {
+    this.ruleKeys = ruleKeys;
+    this.comment = comment;
+    this.status = status != null ? status : Status.ACCEPT;
+  }
+
+  /**
+   * @return the set of rule keys targeted by the annotation
+   */
+  public Set<RuleKey> ruleKeys() {
+    return ruleKeys;
+  }
+
+  /**
+   * @return the justification comment
+   */
+  public String comment() {
+    return comment;
+  }
+
+  /**
+   * @return the target status
+   */
+  public Status status() {
+    return status;
+  }
+}

plugin-api/src/main/java/org/sonar/api/issue/SonarResolveFilter.java

@@ -0,0 +1,40 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-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 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 java.util.Map;
+import org.sonar.api.batch.fs.InputFile;
+import org.sonar.api.scanner.ScannerSide;
+
+/**
+ * Registers {@code //sonar-resolve} annotations found in source files.
+ * Can be called multiple times per file; entries are merged.
+ * @since 13.5
+ */
+@ScannerSide
+public abstract class SonarResolveFilter {
+
+  /**
+   * @param inputFile         the file containing the annotations
+   * @param annotationsByLine map of 1-based line numbers to their annotation data
+   */
+  public abstract SonarResolveFilter sonarResolveInFile(
+    InputFile inputFile, Map<Integer, SonarResolveData> annotationsByLine);
+}

plugin-api/src/test/java/org/sonar/api/issue/SonarResolveDataTest.java

@@ -0,0 +1,63 @@
+/*
+ * Sonar Plugin API
+ * Copyright (C) 2009-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 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 java.util.Set;
+import org.junit.Test;
+import org.sonar.api.rule.RuleKey;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+public class SonarResolveDataTest {
+
+  @Test
+  public void constructor_shouldStoreFields() {
+    Set<RuleKey> ruleKeys = Set.of(RuleKey.of("java", "S123"));
+    SonarResolveData data = new SonarResolveData(ruleKeys, "reason", SonarResolveData.Status.FALSE_POSITIVE);
+
+    assertThat(data.ruleKeys()).isEqualTo(ruleKeys);
+    assertThat(data.comment()).isEqualTo("reason");
+    assertThat(data.status()).isEqualTo(SonarResolveData.Status.FALSE_POSITIVE);
+  }
+
+  @Test
+  public void constructor_whenStatusIsNull_shouldDefaultToAccept() {
+    SonarResolveData data = new SonarResolveData(Set.of(RuleKey.of("java", "S123")), "reason", null);
+
+    assertThat(data.status()).isEqualTo(SonarResolveData.Status.ACCEPT);
+  }
+
+  @Test
+  public void constructor_whenStatusIsAccept_shouldKeepAccept() {
+    SonarResolveData data = new SonarResolveData(Set.of(RuleKey.of("java", "S123")), "reason", SonarResolveData.Status.ACCEPT);
+
+    assertThat(data.status()).isEqualTo(SonarResolveData.Status.ACCEPT);
+  }
+
+  @Test
+  public void constructor_shouldSupportMultipleRuleKeys() {
+    Set<RuleKey> ruleKeys = Set.of(RuleKey.of("java", "S123"), RuleKey.of("java", "S456"));
+    SonarResolveData data = new SonarResolveData(ruleKeys, "comment", null);
+
+    assertThat(data.ruleKeys()).containsExactlyInAnyOrder(
+      RuleKey.of("java", "S123"),
+      RuleKey.of("java", "S456"));
+  }
+}