SCANGRADLE-324 Centralize Sonar property names in ScanPropertyNames (#405)

Centralize Sonar property names in ScanProperties 
Rename ScanProperties to ScanPropertyNames 
Use ScanPropertyNames constants in SonarTask 
Add VERBOSE constant to ScanPropertyNames 
Add Javadoc to ScanPropertyNames class 
Improve documentation of ProjectProperties and SonarProperties 


Co-authored-by: Claude <[email protected]>

Author: romainbrenguier

src/main/java/org/sonarqube/gradle/AndroidUtils.java

@@ -76,7 +76,7 @@
  */
 class AndroidUtils {
   private static final Logger LOGGER = Logging.getLogger(AndroidUtils.class);
-  private static final String SONAR_ANDROID_LINT_REPORT_PATHS_PROP = "sonar.androidLint.reportPaths";
+  private static final String SONAR_ANDROID_LINT_REPORT_PATHS_PROP = ScanPropertyNames.ANDROID_LINT_REPORT_PATHS;
 
   private AndroidUtils() {
   }
@@ -202,7 +202,7 @@ private static void configureTestReports(Project project, BaseVariant variant, M
       .map(d -> d.get().getAsFile())
       .filter(file -> file.isDirectory() && file.list().length > 0)
       .collect(Collectors.toList());
-    map.put("sonar.junit.reportPaths", value);
+    map.put(ScanPropertyNames.JUNIT_REPORT_PATHS, value);
   }
 
   private static DirectoryProperty getReportsDirBeforeGradle42(DeviceProviderInstrumentTestTask testTask) {
@@ -353,11 +353,11 @@ private static void populateSonarQubeProps(Map<String, Object> properties, BaseV
       : Collections.emptySet();
 
     if (isTest) {
-      appendProps(properties, "sonar.java.test.binaries", exists(destinationDirs));
+      appendProps(properties, ScanPropertyNames.JAVA_TEST_BINARIES, exists(destinationDirs));
     } else {
-      appendProps(properties, "sonar.java.binaries", exists(destinationDirs));
+      appendProps(properties, ScanPropertyNames.JAVA_BINARIES, exists(destinationDirs));
       // Populate deprecated properties for backward compatibility
-      appendProps(properties, "sonar.binaries", exists(destinationDirs));
+      appendProps(properties, ScanPropertyNames.BINARIES, exists(destinationDirs));
     }
   }
 

src/main/java/org/sonarqube/gradle/ProjectProperties.java

@@ -21,15 +21,55 @@
 
 import java.util.List;
 
+/**
+ * An immutable data transfer object that holds resolved dependency information for a Gradle project.
+ * <p>
+ * This class is used during the Gradle <strong>execution phase</strong> to transfer resolved classpath
+ * information between tasks, specifically from {@link SonarResolverTask} to {@link SonarTask}.
+ * It is an <strong>internal implementation detail</strong> and is not exposed to users.
+ *
+ * <p>
+ * <strong>Purpose:</strong>
+ * <ul>
+ * <li>Carries resolved compile and test classpaths after dependency resolution</li>
+ * <li>Supports Gradle configuration cache by being serializable/deserializable</li>
+ * <li>Ensures immutability for safe sharing between tasks</li>
+ * </ul>
+ *
+ * <p>
+ * <strong>Note:</strong> This class is for internal task-to-task communication, not for user configuration.
+ * For user-facing property configuration, see {@link SonarProperties}.
+ */
 public class ProjectProperties {
 
+  /** The Gradle project name (e.g., ":subproject" for subprojects, "" for root) */
   public final String projectName;
+
+  /** Whether this project is the root project of the analysis */
   public final Boolean isRootProject;
+
+  /** Resolved absolute paths of compile classpath dependencies */
   public final List<String> compileClasspath;
+
+  /** Resolved absolute paths of test compile classpath dependencies */
   public final List<String> testCompileClasspath;
+
+  /** Filtered main libraries (subset of compileClasspath) for SonarQube analysis */
   public final List<String> mainLibraries;
+
+  /** Filtered test libraries (subset of testCompileClasspath) for SonarQube analysis */
   public final List<String> testLibraries;
 
+  /**
+   * Creates a new immutable ProjectProperties instance.
+   *
+   * @param projectName the Gradle project name
+   * @param isRootProject whether this is the root project
+   * @param compileClasspath resolved compile classpath as absolute paths
+   * @param testCompileClasspath resolved test compile classpath as absolute paths
+   * @param mainLibraries filtered main libraries for analysis
+   * @param testLibraries filtered test libraries for analysis
+   */
   public ProjectProperties(String projectName, Boolean isRootProject, List<String> compileClasspath, List<String> testCompileClasspath,
                            List<String> mainLibraries, List<String> testLibraries) {
     this.projectName = projectName;

src/main/java/org/sonarqube/gradle/ScanProperties.java

@@ -0,0 +1,86 @@
+/*
+ * SonarQube Scanner for Gradle
+ * Copyright (C) 2015-2025 SonarSource
+ * 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  02
+ */
+package org.sonarqube.gradle;
+
+/**
+ * Constants for SonarQube scan property names.
+ */
+public final class ScanPropertyNames {
+  // General
+  public static final String SKIP = "sonar.skip";
+  public static final String GRADLE_SCAN_ALL = "sonar.gradle.scanAll";
+  public static final String VERBOSE = "sonar.verbose";
+
+  // Project structure
+  public static final String PROJECT_KEY = "sonar.projectKey";
+  public static final String MODULE_KEY = "sonar.moduleKey";
+  public static final String MODULES = "sonar.modules";
+  public static final String PROJECT_NAME = "sonar.projectName";
+  public static final String PROJECT_DESCRIPTION = "sonar.projectDescription";
+  public static final String PROJECT_VERSION = "sonar.projectVersion";
+  public static final String PROJECT_BASE_DIR = "sonar.projectBaseDir";
+  public static final String WORKING_DIRECTORY = "sonar.working.directory";
+
+  // Sources and tests
+  public static final String PROJECT_SOURCE_DIRS = "sonar.sources";
+  public static final String PROJECT_TEST_DIRS = "sonar.tests";
+  public static final String SOURCE_ENCODING = "sonar.sourceEncoding";
+
+  // Java configuration
+  public static final String JAVA_SOURCE = "sonar.java.source";
+  public static final String JAVA_TARGET = "sonar.java.target";
+  public static final String JAVA_ENABLE_PREVIEW = "sonar.java.enablePreview";
+  public static final String JAVA_JDK_HOME = "sonar.java.jdkHome";
+  public static final String JAVA_BINARIES = "sonar.java.binaries";
+  public static final String JAVA_LIBRARIES = "sonar.java.libraries";
+  public static final String JAVA_TEST_BINARIES = "sonar.java.test.binaries";
+  public static final String JAVA_TEST_LIBRARIES = "sonar.java.test.libraries";
+
+  /** Kept for backward compatibility */
+  public static final String LIBRARIES = "sonar.libraries";
+
+  // Groovy configuration
+  public static final String GROOVY_BINARIES = "sonar.groovy.binaries";
+
+  // Kotlin configuration
+  public static final String KOTLIN_GRADLE_PROJECT_ROOT = "sonar.kotlin.gradleProjectRoot";
+
+  // Test reports
+  public static final String JUNIT_REPORT_PATHS = "sonar.junit.reportPaths";
+
+  /** Kept for backward compatibility */
+  public static final String JUNIT_REPORTS_PATH = "sonar.junit.reportsPath";
+
+  /** Kept for backward compatibility */
+  public static final String SUREFIRE_REPORTS_PATH = "sonar.surefire.reportsPath";
+
+  // Coverage reports
+  public static final String JACOCO_XML_REPORT_PATHS = "sonar.coverage.jacoco.xmlReportPaths";
+
+  // Android
+  public static final String ANDROID_LINT_REPORT_PATHS = "sonar.androidLint.reportPaths";
+
+  /** Kept for backward compatibility */
+  public static final String BINARIES = "sonar.binaries";
+
+  private ScanPropertyNames() {
+    /* This is a utility class with constants */
+  }
+}

src/main/java/org/sonarqube/gradle/ScanPropertyNames.java

@@ -22,14 +22,42 @@
 import java.util.Map;
 
 /**
- * The Sonar properties for the current Gradle project that are to be passed to the Scanner.
+ * A mutable wrapper for user-facing SonarQube property configuration in Gradle build scripts.
  * <p>
- * The {@code properties} map is already populated with the defaults provided by Gradle, and can be further manipulated as necessary.
- * Before passing them on to the Scanner, property values are converted to Strings as follows:
+ * This class is part of the public API and is used during the Gradle <strong>configuration phase</strong>
+ * to allow users to configure SonarQube analysis properties via the {@code sonarqube { }} DSL block.
+ * <p>
+ * The wrapped {@code properties} map is pre-populated with defaults computed from the Gradle project model,
+ * and can be further manipulated by users through the convenience methods provided.
+ *
+ * <p>
+ * <strong>Usage Example:</strong>
+ * <pre>{@code
+ * sonarqube {
+ *     properties {
+ *         property "sonar.projectKey", "my-project"
+ *         properties([
+ *             "sonar.sources": "src",
+ *             "sonar.tests": "test"
+ *         ])
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>
+ * <strong>Property Value Conversion:</strong>
+ * Before passing properties to the Scanner, values are converted to Strings as follows:
  * <ul>
- * <li>{@code Iterable}s are recursively converted and joined into a comma-separated String.</li>
- * <li>All other values are converted to Strings by calling their {@code toString()} method.</li>
+ * <li>{@code Iterable}s are recursively converted and joined into a comma-separated String</li>
+ * <li>All other values are converted to Strings by calling their {@code toString()} method</li>
  * </ul>
+ *
+ * <p>
+ * <strong>Note:</strong> This class is used for configuration, not for transferring resolved dependency information.
+ * For that purpose, see {@link ProjectProperties}.
+ *
+ * @see SonarExtension
+ * @see ProjectProperties
  */
 public class SonarProperties {