refactor: improve output of -Xshow-phases

This change improves the usability and the display of the current
-Xshow-phases flag. Currently when this is used you just get a big
flattened list like so:

```
❯ scala3-compiler -Xshow-phases
parser
typer
inlinedPositions
sbt-deps
extractSemanticDB
posttyper
prepjsinterop
sbt-api
SetRootTree
pickler
inlining
postInlining
staging
pickleQuotes
{firstTransform, checkReentrant, elimPackagePrefixes, cookComments, checkStatic, checkLoopingImplicits, betaReduce, inlineVals, expandSAMs}
initChecker
{elimRepeated, protectedAccessors, extmethods, uncacheGivenAliases, byNameClosures, hoistSuperArgs, specializeApplyMethods, refchecks, tryCatchPatterns, patternMatcher}
{elimOpaque, explicitJSClasses, explicitOuter, explicitSelf, elimByName, stringInterpolatorOpt}
{pruneErasedDefs, uninitializedDefs, inlinePatterns, vcInlineMethods, seqLiterals, intercepted, getters, specializeFunctions, liftTry, collectNullableFields, elimOuterSelect, resolveSuper, functionXXLForwarders, paramForwarding, genericTuples, letOverApply, arrayConstructors}
erasure
{elimErasedValueType, pureStats, vcElideAllocations, arrayApply, addLocalJSFakeNews, elimPolyFunction, tailrec, completeJavaEnums, mixin, lazyVals, memoize, nonLocalReturns, capturedVars}
{constructors, instrumentation}
{lambdaLift, elimStaticThis, countOuterAccesses}
{dropOuterAccessors, checkNoSuperThis, flatten, transformWildcards, moveStatic, expandPrivate, restoreScopes, selectStatic, junitBootstrappers, Collect entry points, collectSuperCalls, repeatableAnnotations}
genSJSIR
genBCode
```
This changes mimics the Scala 2 compiler and provides a more structured
output that also contains the description of the phase:

```
sbt:scala3> scala3/scalac -Xshow-phases

            phase name  description
            ----------  -----------
                parser  scan and parse sources
                 typer  type the trees
      inlinedPositions  check inlined positions
              sbt-deps  sends information on classes' dependencies to sbt
     extractSemanticDB  extract info into .semanticdb files
             posttyper  additional checks and cleanups after type checking
         prepjsinterop  additional checks and transformations for Scala.js
               sbt-api  sends a representation of the API of classes to sbt
           SetRootTree  set the rootTreeOrProvider on class symbols
               pickler  generates TASTy info
              inlining  inline and execute macros
          postInlining  add mirror support for inlined code
               staging  check staging levels and heal staged types
          pickleQuotes  turn quoted trees into explicit run-time data struct
                     {
        firstTransform  some transformations to put trees into a canonical f
        checkReentrant  check no data races involving global vars
   elimPackagePrefixes  eliminate references to package prefixes in Select n
          cookComments  cook the comments: expand variables, doc, etc.
           checkStatic  check restrictions that apply to @static members
 checkLoopingImplicits  check that implicit defs do not call themselves in a
            betaReduce  reduce closure applications
            inlineVals  check right hand-sides of an `inline val`s
            expandSAMs  expand SAM closures to anonymous classes
          elimRepeated  rewrite vararg parameters and arguments
             refchecks  checks related to abstract members and overriding
                     }
           initChecker  check initialization of objects
                     {
    crossVersionChecks  check issues related to deprecated and experimental
    protectedAccessors  add accessors for protected members
            extmethods  expand methods of value classes with extension metho
   uncacheGivenAliases  avoid caching RHS of simple parameterless given alia
            elimByName  map by-name parameters to functions
        hoistSuperArgs  hoist complex arguments of supercalls to enclosing s
      forwardDepChecks  ensure no forward references to local vals
specializeApplyMethods  adds specialized methods to FunctionN
      tryCatchPatterns  compile cases in try/catch
        patternMatcher  compile pattern matches
                     }
                     {
            elimOpaque  turn opaque into normal aliases
     explicitJSClasses  make all JS classes explicit
         explicitOuter  add accessors to outer classes from nested ones
          explicitSelf  make references to non-trivial self types explicit a
 stringInterpolatorOpt  optimize raw and s string interpolators
                     }
                     {
       pruneErasedDefs  drop erased definitions and simplify erased expressi
     uninitializedDefs  replaces `compiletime.uninitialized` by `_`
        inlinePatterns  remove placeholders of inlined patterns
       vcInlineMethods  inlines calls to value class methods
           seqLiterals  express vararg arguments as arrays
           intercepted  handling of `==`, `|=`, `getClass` methods
               getters  replace non-private vals and vars with getter defs
   specializeFunctions  specialize Function{0,1,2} by replacing super with s
               liftTry  Lifts try's that might be executed on non-empty expr
 collectNullableFields  collect fields that can be nulled out after use in l
       elimOuterSelect  expand outer selections
          resolveSuper  implement super accessors
 functionXXLForwarders  add forwarders for FunctionXXL apply methods
       paramForwarding  add forwarders for aliases of superclass parameters
         genericTuples  optimize generic operations on tuples
          letOverApply  lift blocks from receivers of applications
     arrayConstructors  intercept creation of (non-generic) arrays and intri
                     }
               erasure  rewrite types to JVM model
                     {
   elimErasedValueType  expand erased value types to their underlying implme
             pureStats  remove pure statements in blocks
    vcElideAllocations  peep-hole optimization to eliminate unnecessary valu
             etaReduce  reduce eta expansions of pure paths
            arrayApply  optimize `scala.Array.apply`
    addLocalJSFakeNews  adds fake new invocations to local JS classes in cal
      elimPolyFunction  rewrite PolyFunction subclasses to FunctionN subclas
               tailrec  rewrite tail recursion to loops
     completeJavaEnums  fill in constructors for Java enums
                 mixin  expand trait fields and trait initializers
              lazyVals  expand lazy vals
               memoize  add private fields to getters and setters
       nonLocalReturns  expand non-local returns
          capturedVars  represent vars captured by closures as heap objects
                     }
                     {
          constructors  collect initialization code in primary constructors
       instrumentation  count calls and allocations under -Yinstrument
                     }
                     {
            lambdaLift  lifts out nested functions to class scope
        elimStaticThis  replace This references to static objects by global
    countOuterAccesses  identify outer accessors that can be dropped
                     }
                     {
    dropOuterAccessors  drop unused outer accessors
      checkNoSuperThis  check that supercalls don't contain references to Th
               flatten  lift all inner classes to package scope
    transformWildcards  replace wildcards with default values
            moveStatic  move static methods from companion to the class itse
         expandPrivate  widen private definitions accessed from nested class
         restoreScopes  repair rendered invalid scopes
          selectStatic  get rid of selects that would be compiled into GetSt
    junitBootstrappers  generate JUnit-specific bootstrapper classes for Sca
  Collect entry points  collect all entry points and save them in the contex
     collectSuperCalls  find classes that are called with super
 repeatableAnnotations  aggregate repeatable annotations
                     }
              genSJSIR  generate .sjsir files for Scala.js
              genBCode  generate JVM bytecode
```

The mini-phases are still grouped and indicated by the surrounding `{}`.

There are also some small changes in all the phase files to ensure they
are all done the same way with overriding the phaseName and the
description, both provided in a companion object. The descriptions
themselves were just pulled from the comments in the code.

Author: ckipp01

compiler/src/dotty/tools/backend/jvm/CollectSuperCalls.scala

@@ -20,7 +20,9 @@ import dotty.tools.dotc.transform.MegaPhase.MiniPhase
 class CollectSuperCalls extends MiniPhase {
   import tpd._
 
-  def phaseName: String = "collectSuperCalls"
+  override def phaseName: String = CollectSuperCalls.name
+
+  override def description: String = CollectSuperCalls.description
 
   override def transformSelect(tree: Select)(using Context): Tree = {
     tree.qualifier match {
@@ -40,3 +42,7 @@ class CollectSuperCalls extends MiniPhase {
     }
   }
 }
+
+object CollectSuperCalls:
+  val name: String = "collectSuperCalls"
+  val description: String = "find classes that are called with super"

compiler/src/dotty/tools/backend/jvm/GenBCode.scala

@@ -34,7 +34,10 @@ import StdNames._
 import dotty.tools.io._
 
 class GenBCode extends Phase {
-  def phaseName: String = GenBCode.name
+
+  override def phaseName: String = GenBCode.name
+
+  override def description: String = GenBCode.description
 
   private val superCallsMap = new MutableSymbolMap[Set[ClassSymbol]]
   def registerSuperCall(sym: Symbol, calls: ClassSymbol): Unit = {
@@ -106,6 +109,7 @@ class GenBCode extends Phase {
 
 object GenBCode {
   val name: String = "genBCode"
+  val description: String = "generate JVM bytecode"
 }
 
 class GenBCodePipeline(val int: DottyBackendInterface, val primitives: DottyPrimitives)(using Context) extends BCodeSyncAndTry {

compiler/src/dotty/tools/backend/sjs/GenSJSIR.scala

@@ -6,11 +6,18 @@ import Phases._
 
 /** Generates Scala.js IR files for the compilation unit. */
 class GenSJSIR extends Phase {
-  def phaseName: String = "genSJSIR"
+
+  override def phaseName: String = GenSJSIR.name
+
+  override def description: String = GenSJSIR.description
 
   override def isRunnable(using Context): Boolean =
     super.isRunnable && ctx.settings.scalajs.value
 
   def run(using Context): Unit =
     new JSCodeGen().run()
 }
+
+object GenSJSIR:
+  val name: String = "genSJSIR"
+  val description: String = "generate .sjsir files for Scala.js"

compiler/src/dotty/tools/dotc/config/CliCommand.scala

@@ -138,11 +138,32 @@ trait CliCommand:
   protected def yusageMessage(using settings: ConcreteSettings)(using SettingsState) =
     createUsageMsg("Possible private", shouldExplain = true, isPrivate)
 
-  protected def phasesMessage: String =
-    (new Compiler()).phases.map {
-      case List(single) => single.phaseName
-      case more => more.map(_.phaseName).mkString("{", ", ", "}")
-    }.mkString("\n")
+  /** Used for the formatted output of -Xshow-phases */
+  protected def phasesMessage(using ctx: Context): String =
+  
+    val phases = new Compiler().phases
+    val nameLimit = 25 
+    val maxCol = ctx.settings.pageWidth.value
+    val maxName = phases.flatten.map(_.phaseName.length).max
+    val width = maxName.min(nameLimit)
+    val maxDesc = maxCol - (width + 6)
+    val fmt = s"%${width}.${width}s  %.${maxDesc}s%n"
+
+    val sb = new StringBuilder
+    sb ++= fmt.format("phase name", "description")
+    sb ++= fmt.format("----------", "-----------")
+
+    phases.foreach {
+      case List(single) =>
+        sb ++= fmt.format(single.phaseName, single.description)
+      case Nil => ()
+      case more =>
+        sb ++= fmt.format(s"{", "")
+        more.foreach { mini => sb ++= fmt.format(mini.phaseName, mini.description) }
+        sb ++= fmt.format(s"}", "")
+    }
+    sb.mkString
+
 
   /** Provide usage feedback on argument summary, assuming that all settings
    *  are already applied in context.

compiler/src/dotty/tools/dotc/parsing/ParserPhase.scala

@@ -15,6 +15,7 @@ import dotty.tools.unsupported
 class Parser extends Phase {
 
   override def phaseName: String = Parser.name
+  override def description: String = Parser.description
 
   // We run TreeChecker only after type checking
   override def isCheckable: Boolean = false
@@ -58,4 +59,5 @@ class Parser extends Phase {
 
 object Parser{
   val name: String = "parser"
+  val description: String = "scan and parse sources"
 }

compiler/src/dotty/tools/dotc/sbt/ExtractAPI.scala

@@ -43,7 +43,10 @@ import scala.util.chaining.*
  *  @see ExtractDependencies
  */
 class ExtractAPI extends Phase {
-  override def phaseName: String = "sbt-api"
+
+  override def phaseName: String = ExtractAPI.name
+
+  override def description: String = ExtractAPI.description
 
   override def isRunnable(using Context): Boolean = {
     def forceRun = ctx.settings.YdumpSbtInc.value || ctx.settings.YforceSbtPhases.value
@@ -87,6 +90,10 @@ class ExtractAPI extends Phase {
   }
 }
 
+object ExtractAPI:
+  val name: String = "sbt-api"
+  val description: String = "sends a representation of the API of classes to sbt"
+
 /** Extracts full (including private members) API representation out of Symbols and Types.
  *
  *  The exact representation used for each type is not important: the only thing

compiler/src/dotty/tools/dotc/sbt/ExtractDependencies.scala

@@ -49,7 +49,9 @@ import scala.collection.{Set, mutable}
 class ExtractDependencies extends Phase {
   import ExtractDependencies._
 
-  override def phaseName: String = "sbt-deps"
+  override def phaseName: String = ExtractDependencies.name
+
+  override def description: String = ExtractDependencies.description
 
   override def isRunnable(using Context): Boolean = {
     def forceRun = ctx.settings.YdumpSbtInc.value || ctx.settings.YforceSbtPhases.value
@@ -180,6 +182,9 @@ class ExtractDependencies extends Phase {
 }
 
 object ExtractDependencies {
+  val name: String = "sbt-deps"
+  val description: String = "sends information on classes' dependencies to sbt"
+
   def classNameAsString(sym: Symbol)(using Context): String =
     sym.fullName.stripModuleClassSuffix.toString
 

compiler/src/dotty/tools/dotc/semanticdb/ExtractSemanticDB.scala

@@ -36,6 +36,8 @@ class ExtractSemanticDB extends Phase:
 
   override val phaseName: String = ExtractSemanticDB.name
 
+  override val description: String = ExtractSemanticDB.description
+
   override def isRunnable(using Context) =
     super.isRunnable && ctx.settings.Xsemanticdb.value
 
@@ -461,6 +463,7 @@ object ExtractSemanticDB:
   import java.nio.file.Paths
 
   val name: String = "extractSemanticDB"
+  val description: String = "extract info into .semanticdb files"
 
   def write(
     source: SourceFile,

compiler/src/dotty/tools/dotc/transform/ArrayApply.scala

@@ -21,7 +21,9 @@ import scala.reflect.ClassTag
 class ArrayApply extends MiniPhase {
   import tpd._
 
-  override def phaseName: String = "arrayApply"
+  override def phaseName: String = ArrayApply.name
+
+  override def description: String = ArrayApply.description
 
   override def transformApply(tree: tpd.Apply)(using Context): tpd.Tree =
     if isArrayModuleApply(tree.symbol) then
@@ -71,3 +73,7 @@ class ArrayApply extends MiniPhase {
     }
   }
 }
+
+object ArrayApply:
+  val name: String = "arrayApply"
+  val description: String = "optimize `scala.Array.apply`"

compiler/src/dotty/tools/dotc/transform/ArrayConstructors.scala

@@ -22,7 +22,9 @@ import scala.collection.immutable.::
 class ArrayConstructors extends MiniPhase {
   import ast.tpd._
 
-  override def phaseName: String = "arrayConstructors"
+  override def phaseName: String = ArrayConstructors.name
+
+  override def description: String = ArrayConstructors.description
 
   override def transformApply(tree: tpd.Apply)(using Context): tpd.Tree = {
     def expand(elemType: Type, dims: List[Tree]) =
@@ -49,3 +51,7 @@ class ArrayConstructors extends MiniPhase {
     else tree
   }
 }
+
+object ArrayConstructors:
+  val name: String = "arrayConstructors"
+  val description: String = "intercept creation of (non-generic) arrays and intrinsify"