Bring more bsp-specific targets in line with their non-bsp versions

scalalib/src/mill/scalalib/JavaModule.scala

@@ -276,9 +276,11 @@ trait JavaModule
   }
 
   /**
-   * The transitive version of `bspLocalClasspath`
+   * Same as [[transitiveLocalClasspath]], but with all dependencies on [[compile]]
+   * replaced by their non-compiling [[bspCompileClassesPath]] variants.
+   *
+   * Keep in sync with [[transitiveLocalClasspath]]
    */
-  // Keep in sync with [[transitiveLocalClasspath]]
   @internal
   def bspTransitiveLocalClasspath: T[Agg[UnresolvedPath]] = T {
     T.traverse(transitiveModuleCompileModuleDeps)(_.bspLocalClasspath)().flatten
@@ -294,9 +296,11 @@ trait JavaModule
   }
 
   /**
-   * The transitive version of `bspCompileClasspath`
+   * Same as [[transitiveCompileClasspath]], but with all dependencies on [[compile]]
+   * replaced by their non-compiling [[bspCompileClassesPath]] variants.
+   *
+   * Keep in sync with [[transitiveCompileClasspath]]
    */
-  // Keep in sync with [[transitiveCompileClasspath]]
   @internal
   def bspTransitiveCompileClasspath: T[Agg[UnresolvedPath]] = T {
     T.traverse(transitiveModuleCompileModuleDeps)(m =>
@@ -393,9 +397,11 @@ trait JavaModule
   /**
    * Compiles the current module to generate compiled classfiles/bytecode.
    *
-   * When you override this, you probably also want to override [[bspCompileClassesPath]].
+   * When you override this, you probably also want/need to override [[bspCompileClassesPath]],
+   * as that needs to point to the same compilation output path.
+   *
+   * Keep in sync with [[bspCompileClassesPath]]
    */
-  // Keep in sync with [[bspCompileClassesPath]]
   def compile: T[mill.scalalib.api.CompilationResult] = T.persistent {
     zincWorker()
       .worker()
@@ -410,8 +416,13 @@ trait JavaModule
       )
   }
 
-  /** The path to the compiled classes without forcing to actually run the target. */
-  // Keep in sync with [[compile]]
+  /**
+   * The path to the compiled classes by [[compile]] without forcing to actually run the compilation.
+   * This is safe in an BSP context, as the compilation done later will use the
+   * exact same compilation settings, so we can safely use the same path.
+   *
+   * Keep in sync with [[compile]]
+   */
   @internal
   def bspCompileClassesPath: T[UnresolvedPath] =
     if (compile.ctx.enclosing == s"${classOf[JavaModule].getName}#compile") {
@@ -432,48 +443,56 @@ trait JavaModule
 
   /**
    * The *output* classfiles/resources from this module, used for execution,
-   * excluding upstream modules and third-party dependencies
+   * excluding upstream modules and third-party dependencies, but including unmanaged dependencies.
+   *
+   * Keep in sync with [[bspLocalClasspath]]
    */
   def localClasspath: T[Seq[PathRef]] = T {
     localCompileClasspath().toSeq ++ resources() ++ Agg(compile().classes)
   }
 
   /**
-   * The local classpath without forcing to compile the module.
-   * Keep in sync with [[compile]]
+   * Same as [[localClasspath]], but with all dependencies on [[compile]]
+   * replaced by their non-compiling [[bspCompileClassesPath]] variants.
+   *
+   * Keep in sync with [[localClasspath]]
    */
   @internal
   def bspLocalClasspath: T[Agg[UnresolvedPath]] = T {
-    (compileResources() ++ resources()).map(p => UnresolvedPath.ResolvedPath(p.path)) ++
+    (localCompileClasspath() ++ resources()).map(p => UnresolvedPath.ResolvedPath(p.path)) ++
       Agg(bspCompileClassesPath())
   }
 
   /**
    * All classfiles and resources from upstream modules and dependencies
-   * necessary to compile this module
+   * necessary to compile this module.
+   *
+   * Keep in sync with [[bspCompileClasspath]]
    */
-  // Keep in sync with [[bspCompileClasspath]]
   def compileClasspath: T[Agg[PathRef]] = T {
     resolvedIvyDeps() ++ transitiveCompileClasspath() ++ localCompileClasspath()
   }
 
   /**
-   * The *input* classfiles/resources from this module, used during compilation,
-   * excluding upstream modules and third-party dependencies
+   * Same as [[compileClasspath]], but does not trigger compilation targets, if possible.
+   *
+   * Keep in sync with [[compileClasspath]]
    */
-  def localCompileClasspath: T[Agg[PathRef]] = T {
-    compileResources() ++ unmanagedClasspath()
-  }
-
-  /** Same as [[compileClasspath]], but does not trigger compilation targets, if possible. */
-  // Keep in sync with [[compileClasspath]]
   @internal
   def bspCompileClasspath: T[Agg[UnresolvedPath]] = T {
     resolvedIvyDeps().map(p => UnresolvedPath.ResolvedPath(p.path)) ++
       bspTransitiveCompileClasspath() ++
       localCompileClasspath().map(p => UnresolvedPath.ResolvedPath(p.path))
   }
 
+  /**
+   * The *input* classfiles/resources from this module, used during compilation,
+   * excluding upstream modules and third-party dependencies
+   */
+  def localCompileClasspath: T[Agg[PathRef]] = T {
+    compileResources() ++ unmanagedClasspath()
+  }
+
   /**
    * Resolved dependencies based on [[transitiveIvyDeps]] and [[transitiveCompileIvyDeps]].
    */