SONARJAVA-5537 S7476: remove FPs and reduce noise (#5158)

Author: erwan-serandour

its/autoscan/src/test/resources/autoscan/diffs/diff_S7476.json

@@ -3,4 +3,4 @@
   "hasTruePositives": true,
   "falseNegatives": 0,
   "falsePositives": 0
-}
+}

its/ruling/src/test/resources/guava/java-S7476.json

@@ -1,6 +1,11 @@
+///////////////////////////////////////////////////////////////////////////////////////////////
+//
+// this a license header, we don't raise on it as it will not generate javadoc
+//
+///////////////////////////////////////////////////////////////////////////////////////////////
 package checks;
 
-public class CommentsMustStartWithCorrectNumberOfSlashesCheckAfterJava23 {
+public class CommentsMustStartWithCorrectNumberOfSlashesCheckJava23 {
   // This is a comment
   public void twoSlashes() {}
   /// javadoc using markdown
@@ -44,9 +49,9 @@ public void javadoc(String input){
   // Noncompliant@+3
   // Noncompliant@+4
   /// This is a javadoc
-	//// invalid
-  ///
   //// invalid
+  ///
+  ///// invalid
 //^^^^
   public void markdownJavadoc() {
   }

…rectNumberOfSlashesCheckAfterJava23.java …thCorrectNumberOfSlashesCheckJava23.javajava-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckAfterJava23.java renamed to java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckJava23.java java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckAfterJava23.java renamed to java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckJava23.java

@@ -1,6 +1,18 @@
+///////////////////////////////////////////////////////////////////////////////////////////////
+//
+// this a license header, we don't raise on it as it will not generate javadoc
+//
+///////////////////////////////////////////////////////////////////////////////////////////////
 package checks;
 
-public class CommentsMustStartWithCorrectNumberOfSlashesCheckBeforeJava23 {
+
+// Noncompliant@+1
+/// don't use three slashes
+import java.util.List;
+
+// Noncompliant@+1
+/// This is a comment, but will be javadoc in java 23
+public class CommentsMustStartWithCorrectNumberOfSlashesCheckSample {
 
   // This is a comment
   public void twoSlashes() {}
@@ -13,6 +25,11 @@ public void threeSlashes() {}
 //^^^
   public void fourSlashes() {}
 
+  public void insideMethod() {
+    // Noncompliant@+1
+    ///This is a comment
+  }
+
 
   // //
   public void twoTimeTwoSlashes() {}

…ectNumberOfSlashesCheckBeforeJava23.java …thCorrectNumberOfSlashesCheckSample.javajava-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckBeforeJava23.java renamed to java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckSample.java java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckBeforeJava23.java renamed to java-checks-test-sources/default/src/main/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheckSample.java

@@ -17,19 +17,43 @@
 package org.sonar.java.checks;
 
 import java.util.List;
+import java.util.Optional;
 import org.sonar.check.Rule;
 import org.sonar.java.model.DefaultModuleScannerContext;
 import org.sonar.java.reporting.AnalyzerMessage;
 import org.sonar.plugins.java.api.IssuableSubscriptionVisitor;
+import org.sonar.plugins.java.api.JavaFileScannerContext;
+import org.sonar.plugins.java.api.JavaVersion;
+import org.sonar.plugins.java.api.JavaVersionAwareVisitor;
+import org.sonar.plugins.java.api.location.Position;
+import org.sonar.plugins.java.api.location.Range;
+import org.sonar.plugins.java.api.tree.SyntaxToken;
 import org.sonar.plugins.java.api.tree.SyntaxTrivia;
 import org.sonar.plugins.java.api.tree.Tree;
 
 @Rule(key = "S7476")
-public class CommentsMustStartWithCorrectNumberOfSlashesCheck extends IssuableSubscriptionVisitor {
+public class CommentsMustStartWithCorrectNumberOfSlashesCheck extends IssuableSubscriptionVisitor implements JavaVersionAwareVisitor {
   private static final String BEFORE_JAVA_23 = "A single-line comment should start with exactly two slashes, no more.";
-  private static final String AFTER_JAVA_23 = "Markdown documentation should start with exactly three slashes, no more.";
+  private static final String JAVA_23 = "Markdown documentation should start with exactly three slashes, no more.";
   private static final String INCORRECT_SLASHES_BEFORE_JAVA_23 = "///";
-  private static final String INCORRECT_SLASHES_AFTER_JAVA_23 = "////";
+  private static final String INCORRECT_SLASHES_JAVA_23 = "////";
+  private static final Position FILE_START = Position.at(Position.FIRST_LINE, Position.FIRST_COLUMN);
+  private Position compilationUnitFirstTokenPosition = FILE_START;
+
+  @Override
+  public void setContext(JavaFileScannerContext context) {
+    super.setContext(context);
+    compilationUnitFirstTokenPosition = Optional.ofNullable(context.getTree())
+      .map(Tree::firstToken)
+      .map(SyntaxToken::range)
+      .map(Range::start).orElse(FILE_START);
+  }
+
+  @Override
+  public void leaveFile(JavaFileScannerContext context) {
+    compilationUnitFirstTokenPosition = FILE_START;
+    super.leaveFile(context);
+  }
 
   @Override
   public List<Tree.Kind> nodesToVisit() {
@@ -38,6 +62,9 @@ public List<Tree.Kind> nodesToVisit() {
 
   @Override
   public void visitTrivia(SyntaxTrivia syntaxTrivia) {
+    if (isHeader(syntaxTrivia)) {
+      return;
+    }
     if (syntaxTrivia.isComment(SyntaxTrivia.CommentKind.LINE) && syntaxTrivia.comment().startsWith(INCORRECT_SLASHES_BEFORE_JAVA_23)) {
       var span = LineSpan.fromComment(syntaxTrivia, 0, 0, INCORRECT_SLASHES_BEFORE_JAVA_23.length());
       reportIssue(span, BEFORE_JAVA_23);
@@ -48,17 +75,26 @@ public void visitTrivia(SyntaxTrivia syntaxTrivia) {
       for (int idx = 0; idx < lines.length; idx++) {
         String line = lines[idx];
 
-        if (line.trim().startsWith(INCORRECT_SLASHES_AFTER_JAVA_23)) {
-          int startPos = line.indexOf(INCORRECT_SLASHES_AFTER_JAVA_23);
-          var span = LineSpan.fromComment(syntaxTrivia, idx, startPos, startPos + INCORRECT_SLASHES_AFTER_JAVA_23.length());
-          reportIssue(span, AFTER_JAVA_23);
+        if (line.trim().startsWith(INCORRECT_SLASHES_JAVA_23)) {
+          int startPos = line.indexOf(INCORRECT_SLASHES_JAVA_23);
+          var span = LineSpan.fromComment(syntaxTrivia, idx, startPos, startPos + INCORRECT_SLASHES_JAVA_23.length());
+          reportIssue(span, JAVA_23);
         }
       }
     }
   }
 
+  @Override
+  public boolean isCompatibleWithJavaVersion(JavaVersion version) {
+    return version.isJava17Compatible();
+  }
+
+  private boolean isHeader(SyntaxTrivia syntaxTrivia) {
+    return syntaxTrivia.range().start().isBefore(compilationUnitFirstTokenPosition);
+  }
+
   private void reportIssue(LineSpan span, String message) {
-    ((DefaultModuleScannerContext) this.context).reportIssue(issueSingleLine(span,message));
+    ((DefaultModuleScannerContext) this.context).reportIssue(issueSingleLine(span, message));
   }
 
   private AnalyzerMessage issueSingleLine(LineSpan span, String message) {

java-checks/src/main/java/org/sonar/java/checks/CommentsMustStartWithCorrectNumberOfSlashesCheck.java

@@ -18,27 +18,38 @@
 
 import org.junit.jupiter.api.Test;
 import org.sonar.java.checks.verifier.CheckVerifier;
+import org.sonar.plugins.java.api.JavaFileScanner;
 
 import static org.sonar.java.checks.verifier.TestUtils.mainCodeSourcesPath;
 
 class CommentsMustStartWithCorrectNumberOfSlashesCheckTest {
+  private static final JavaFileScanner check = new CommentsMustStartWithCorrectNumberOfSlashesCheck();
+
+  @Test
+  void test_before_java17() {
+    CheckVerifier.newVerifier()
+      .onFile(mainCodeSourcesPath("checks/CommentsMustStartWithCorrectNumberOfSlashesCheckSample.java"))
+      .withCheck(check)
+      .withJavaVersion(16)
+      .verifyNoIssues();
+  }
 
   @Test
   void test_before_java23() {
     CheckVerifier.newVerifier()
-      .onFile(mainCodeSourcesPath("checks/CommentsMustStartWithCorrectNumberOfSlashesCheckBeforeJava23.java"))
-      .withCheck(new CommentsMustStartWithCorrectNumberOfSlashesCheck())
+      .onFile(mainCodeSourcesPath("checks/CommentsMustStartWithCorrectNumberOfSlashesCheckSample.java"))
+      .withCheck(check)
       .withJavaVersion(22)
       .verifyIssues();
   }
 
   @Test
-  void test_after_java23() {
+  void test_java23() {
     CheckVerifier.newVerifier()
-      .onFile(mainCodeSourcesPath("checks/CommentsMustStartWithCorrectNumberOfSlashesCheckAfterJava23.java"))
-      .withCheck(new CommentsMustStartWithCorrectNumberOfSlashesCheck())
+      .onFile(mainCodeSourcesPath("checks/CommentsMustStartWithCorrectNumberOfSlashesCheckJava23.java"))
+      .withCheck(check)
       .withJavaVersion(23)
       .verifyIssues();
   }
-  
+
 }