Deprecate StandardPlugin.init in favor of initialize method taking implicit Context (#20330)

We do deprecate `StandardPlugin.init` in favour of
`StandardPlugin.initialize` method tak takes additional `Context`
parameter - it would e.g. allow to use reporting mechanism when parsing
compiler plugin options.
Introduces changes to akka/akka fork used in Community Build

Author: WojciechMazur

community-build/community-projects/akka

@@ -13,6 +13,7 @@ import java.io.InputStream
 import java.util.Properties
 
 import scala.util.{ Try, Success, Failure }
+import scala.annotation.nowarn
 
 trait PluginPhase extends MiniPhase {
   def runsBefore: Set[String] = Set.empty
@@ -50,7 +51,20 @@ trait StandardPlugin extends Plugin {
    *  @param options commandline options to the plugin.
    *  @return a list of phases to be added to the phase plan
    */
-  def init(options: List[String]): List[PluginPhase]
+  @deprecatedOverriding("Method 'init' does not allow to access 'Context', use 'initialize' instead.", since = "Scala 3.5.0")
+  @deprecated("Use 'initialize' instead.", since = "Scala 3.5.0")
+  def init(options: List[String]): List[PluginPhase] = Nil
+
+  /** Non-research plugins should override this method to return the phases
+   *
+   *  The phases returned must be freshly constructed (not reused
+   *  and returned again on subsequent calls).
+   *
+   *  @param options commandline options to the plugin.
+   *  @return a list of phases to be added to the phase plan
+   */
+  @nowarn("cat=deprecation")
+  def initialize(options: List[String])(using Context): List[PluginPhase] = init(options)
 }
 
 /** A research plugin may customize the compilation pipeline freely

compiler/src/dotty/tools/dotc/plugins/Plugin.scala

@@ -125,7 +125,7 @@ trait Plugins {
     }
 
     // schedule plugins according to ordering constraints
-    val pluginPhases = plugins.collect { case p: StandardPlugin => p }.flatMap { plug => plug.init(options(plug)) }
+    val pluginPhases = plugins.collect { case p: StandardPlugin => p }.flatMap { plug => plug.initialize(options(plug)) }
     val updatedPlan = Plugins.schedule(plan, pluginPhases)
 
     // add research plugins

compiler/src/dotty/tools/dotc/plugins/Plugins.scala

@@ -67,7 +67,7 @@ class DivideZero extends StandardPlugin:
   val name: String = "divideZero"
   override val description: String = "divide zero check"
 
-  def init(options: List[String]): List[PluginPhase] =
+  override def initialize(options: List[String])(using Context): List[PluginPhase] =
     (new DivideZeroPhase) :: Nil
 
 class DivideZeroPhase extends PluginPhase:
@@ -90,7 +90,7 @@ end DivideZeroPhase
 ```
 
 The plugin main class (`DivideZero`) must extend the trait `StandardPlugin`
-and implement the method `init` that takes the plugin's options as argument
+and implement the method `initialize` that takes the plugin's options as argument
 and returns a list of `PluginPhase`s to be inserted into the compilation pipeline.
 
 Our plugin adds one compiler phase to the pipeline. A compiler phase must extend

docs/_docs/reference/changed-features/compiler-plugins.md

@@ -67,7 +67,7 @@ class DivideZero extends StandardPlugin:
   val name: String = "divideZero"
   override val description: String = "divide zero check"
 
-  def init(options: List[String]): List[PluginPhase] =
+  override def initialize(options: List[String])(using Context): List[PluginPhase] =
     (new DivideZeroPhase) :: Nil
 
 class DivideZeroPhase extends PluginPhase:
@@ -90,7 +90,7 @@ end DivideZeroPhase
 ```
 
 The plugin main class (`DivideZero`) must extend the trait `StandardPlugin`
-and implement the method `init` that takes the plugin's options as argument
+and implement the method `initialize` that takes the plugin's options as argument
 and returns a list of `PluginPhase`s to be inserted into the compilation pipeline.
 
 Our plugin adds one compiler phase to the pipeline. A compiler phase must extend

docs/_spec/TODOreference/changed-features/compiler-plugins.md

@@ -21,7 +21,7 @@ class InitPlugin extends StandardPlugin {
   val name: String = "initPlugin"
   override val description: String = "checks that under -Yretain-trees we may get tree for all symbols"
 
-  def init(options: List[String]): List[PluginPhase] =
+  override def initialize(options: List[String])(using Context): List[PluginPhase] =
     (new SetDefTree) :: (new InitChecker) :: Nil
 }
 

sbt-test/sbt-dotty/analyzer-plugin/plugin/Analyzer.scala

@@ -22,7 +22,8 @@ class DivideZero extends PluginPhase with StandardPlugin {
   override val runsAfter = Set(Pickler.name)
   override val runsBefore = Set(Staging.name)
 
-  def init(options: List[String]): List[PluginPhase] = this :: Nil
+  // We keep using deprecated variant here just to ensure it still works correctly
+  override def init(options: List[String]): List[PluginPhase] = this :: Nil
 
   private def isNumericDivide(sym: Symbol)(implicit ctx: Context): Boolean = {
     def test(tpe: String): Boolean =

sbt-test/sbt-dotty/compiler-plugin/plugin/DivideZero.scala

@@ -52,7 +52,7 @@ class InitChecker extends PluginPhase with StandardPlugin {
   override val runsAfter = Set(SetDefTree.name)
   override val runsBefore = Set(FirstTransform.name)
 
-  def init(options: List[String]): List[PluginPhase] = this :: (new SetDefTree) :: Nil
+  override def initialize(options: List[String])(using Context): List[PluginPhase] = this :: (new SetDefTree) :: Nil
 
   private def checkDef(tree: Tree)(implicit ctx: Context): Tree = {
     if (tree.symbol.defTree.isEmpty)

tests/plugins/custom/analyzer/Analyzer_1.scala

@@ -20,7 +20,7 @@ class DivideZero extends PluginPhase with StandardPlugin {
   override val runsAfter = Set(Pickler.name)
   override val runsBefore = Set(PickleQuotes.name)
 
-  override def init(options: List[String]): List[PluginPhase] = this :: Nil
+  override def initialize(options: List[String])(using Context): List[PluginPhase] = this :: Nil
 
   private def isNumericDivide(sym: Symbol)(implicit ctx: Context): Boolean = {
     def test(tpe: String): Boolean =