SONARPY-1583: Add explanatory comments for injection of SonarLintCache

sonar-python-plugin/src/main/java/org/sonar/plugins/python/PythonPlugin.java

@@ -27,6 +27,7 @@
 import org.sonar.api.SonarRuntime;
 import org.sonar.api.config.PropertyDefinition;
 import org.sonar.api.resources.Qualifiers;
+import org.sonar.plugins.python.api.SonarLintCache;
 import org.sonar.plugins.python.bandit.BanditRulesDefinition;
 import org.sonar.plugins.python.bandit.BanditSensor;
 import org.sonar.plugins.python.coverage.PythonCoverageSensor;
@@ -41,7 +42,6 @@
 import org.sonar.plugins.python.ruff.RuffSensor;
 import org.sonar.plugins.python.warnings.AnalysisWarningsWrapper;
 import org.sonar.plugins.python.xunit.PythonXUnitSensor;
-import org.sonar.plugins.python.api.SonarLintCache;
 
 public class PythonPlugin implements Plugin {
 
@@ -71,7 +71,6 @@ public void define(Context context) {
         .defaultValue("py")
         .build(),
 
-
       Python.class,
 
       PythonProfile.class,
@@ -221,6 +220,16 @@ static class SonarLintPluginAPIManager {
 
     public void addSonarlintPythonIndexer(Context context, SonarLintPluginAPIVersion sonarLintPluginAPIVersion) {
       if (sonarLintPluginAPIVersion.isDependencyAvailable()) {
+        // Only SonarLintPythonIndexer has the ModuleFileListener dependency.
+        // However, SonarLintCache can only be used with SonarLintPythonIndexer present at the moment.
+        // Hence, we also add it here, even if it technically does not share the dependency.
+        //
+        // Furthermore, with recent versions of SonarLint, the ModuleFileListener dependency should always be available.
+        //
+        // Attention:
+        // The constructors of PythonSensor currently expect both, SonarLintCache and SonarLintPythonIndexer, to always be available at the
+        // same time for injection.
+        // Thus, some care is required when making changes to the addExtension calls here.
         context.addExtension(SonarLintCache.class);
         context.addExtension(SonarLintPythonIndexer.class);
       } else {

sonar-python-plugin/src/main/java/org/sonar/plugins/python/PythonSensor.java

@@ -67,31 +67,33 @@ public final class PythonSensor implements Sensor {
   private final SonarLintCache sonarLintCache;
   private final AnalysisWarningsWrapper analysisWarnings;
   private static final Logger LOG = LoggerFactory.getLogger(PythonSensor.class);
-  static final String UNSET_VERSION_WARNING =
-    "Your code is analyzed as compatible with all Python 3 versions by default." +
+  static final String UNSET_VERSION_WARNING = "Your code is analyzed as compatible with all Python 3 versions by default." +
     " You can get a more precise analysis by setting the exact Python version in your configuration via the parameter \"sonar.python.version\"";
 
   /**
    * Constructor to be used by pico if neither PythonCustomRuleRepository nor PythonIndexer are to be found and injected.
    */
   public PythonSensor(FileLinesContextFactory fileLinesContextFactory, CheckFactory checkFactory,
-                      NoSonarFilter noSonarFilter, AnalysisWarningsWrapper analysisWarnings) {
+    NoSonarFilter noSonarFilter, AnalysisWarningsWrapper analysisWarnings) {
     this(fileLinesContextFactory, checkFactory, noSonarFilter, null, null, null, analysisWarnings);
   }
 
   public PythonSensor(FileLinesContextFactory fileLinesContextFactory, CheckFactory checkFactory, NoSonarFilter noSonarFilter,
-                      PythonCustomRuleRepository[] customRuleRepositories, AnalysisWarningsWrapper analysisWarnings) {
+    PythonCustomRuleRepository[] customRuleRepositories, AnalysisWarningsWrapper analysisWarnings) {
     this(fileLinesContextFactory, checkFactory, noSonarFilter, customRuleRepositories, null, null, analysisWarnings);
   }
 
   public PythonSensor(FileLinesContextFactory fileLinesContextFactory, CheckFactory checkFactory, NoSonarFilter noSonarFilter,
-                      PythonIndexer indexer, SonarLintCache sonarLintCache, AnalysisWarningsWrapper analysisWarnings) {
+    PythonIndexer indexer, SonarLintCache sonarLintCache, AnalysisWarningsWrapper analysisWarnings) {
+    // ^^ This constructor implicitly assumes that a PythonIndexer and a SonarLintCache are always available at the same time.
+    // In practice, this is currently the case, since both are provided by PythonPlugin under the same conditions.
+    // See also PythonPlugin::SonarLintPluginAPIManager::addSonarlintPythonIndexer.
     this(fileLinesContextFactory, checkFactory, noSonarFilter, null, indexer, sonarLintCache, analysisWarnings);
   }
 
   public PythonSensor(FileLinesContextFactory fileLinesContextFactory, CheckFactory checkFactory, NoSonarFilter noSonarFilter,
-                      @Nullable PythonCustomRuleRepository[] customRuleRepositories, @Nullable PythonIndexer indexer,
-                      @Nullable SonarLintCache sonarLintCache, AnalysisWarningsWrapper analysisWarnings) {
+    @Nullable PythonCustomRuleRepository[] customRuleRepositories, @Nullable PythonIndexer indexer,
+    @Nullable SonarLintCache sonarLintCache, AnalysisWarningsWrapper analysisWarnings) {
     this.checks = new PythonChecks(checkFactory)
       .addChecks(CheckList.REPOSITORY_KEY, CheckList.getChecks())
       .addCustomChecks(customRuleRepositories);

sonar-python-plugin/src/main/java/org/sonar/plugins/python/indexer/SonarLintPythonIndexer.java

@@ -83,6 +83,9 @@ public void buildOnce(SensorContext context) {
   @Override
   public void setSonarLintCache(@Nullable SonarLintCache sonarLintCache) {
     if (sonarLintCache != null) {
+      // ^This null check is defensive.
+      // In practice, a SonarLintCache instance should always be available when a SonarLintPythonIndexer is available.
+      // See also PythonPlugin::SonarLintPluginAPIManager::addSonarlintPythonIndexer.
       this.cacheContext = new CacheContextImpl(true, new PythonWriteCacheImpl(sonarLintCache), new PythonReadCacheImpl(sonarLintCache));
     }
   }