[Semester Project] Add new front-end phase for unused entities and add support for unused imports (#16157)

This PR, related to my **semester project** #15503 on adding **dotty's
linter features**, adds the following:

- [x] Add the `CheckUnused` front-end phase, which will check the the
tree produced by the typer, for unused entites (imports, local defs,
...)
- [x] Emit warning for `-Wunused:imports` including **given imports**
and **wildcard imports**
- [x] Emit warning for `-Wunused:locals`
- [x] Emit warning for `-Wunused:privates`
- [x] Emit warning for `-Wunused:params`
- ~~Emit warning for `-Wunused:patvars`~~
- [x] Emit warning for `-Wunused:unsafe-warn-patvars`
- [x] Emit warning for `-Wunused:linted`
- [x] Add a simple _fatal-warning_ compilation-test suit
- [x] _Fixes for the warning format_
- [x] Better help in CLI for `-Wunused`
- [x] Add `-Wunused:givens` alias to `-Wunused:implicits`

Here are a few examples:
#### Unused Imports
```scala
object Foo {
  import collection.mutable.{Set, Map}

  def main(args: Array[String]) =
    val bar = Set("this","set","is","used")
    println(s"Hello World: $bar")
}
``` 
```
sbt:scala3> scalac -Wunused:imports ../Foo.scala
[...]
-- Warning: ../scratch_files/Hello.scala:2:34 ----------------------------------
2 |  import collection.mutable.{Set, Map}
  |                                  ^^^
  |                                  unused import
1 warning found
```
#### Unused local definitions
```scala
class Foo {
  def bar =
    val a = 1
    2 + 2
}
``` 
```
sbt:scala3> scalac -Wunused:locals ../Foo.scala
[...]
-- Warning: ../scratch_files/MyHello.scala:3:8 ---------------------------------
3 |    val a = 1
  |    ^^^^^^^^^
  |    unused local definition
1 warning found
```
#### Unused private members
```scala
class Foo {
  private def a = 1
  private def b = 2

  def doSomething = b
}
``` 
```
sbt:scala3> scalac -Wunused:privates ../Foo.scala
[...]
-- Warning: ../scratch_files/MyHello.scala:2:14 --------------------------------
2 |  private def a = 1
  |  ^^^^^^^^^^^^^^^^^
  |  unused private member
1 warning found
```
#### Unused parameters
```scala
def foo(a: String)(using Int) = bar
``` 
```
sbt:scala3> scalac -Wunused:params ../scratch_files/Foo.scala
[...]
-- Warning: ../scratch_files/MyHello.scala:1:8 ---------------------------------
1 |def foo(a: String)(using Int) = bar
  |        ^
  |        unused explicit parameter
-- Warning: ../scratch_files/MyHello.scala:1:25 --------------------------------
1 |def foo(a: String)(using Int) = bar
  |                         ^
  |                         unused implicit parameter
2 warnings found
```
#### Unused pattern variables
```scala
def foo(a: List[Int]) = a match
    case head :: tail => ???
    case Nil => ???
``` 
```
sbt:scala3> scalac -Wunused:unsafe-warn-patvars ../scratch_files/Foo.scala
[...]
-- Warning: ../scratch_files/MyHello.scala:2:9 ---------------------------------
2 |    case head :: tail => ???
  |         ^^^^
  |         unused pattern variable
-- Warning: ../scratch_files/MyHello.scala:2:17 --------------------------------
2 |    case head :: tail => ???
  |                 ^^^^
  |                 unused pattern variable
2 warnings found
```

Please check the [test
file](tests/neg-custom-args/fatal-warnings/i15503/i15503a.scala) for the
handled cases.

@odersky
@anatoliykmetyuk

Author: szymon-rd

compiler/src/dotty/tools/dotc/Compiler.scala

@@ -35,6 +35,7 @@ class Compiler {
   protected def frontendPhases: List[List[Phase]] =
     List(new Parser) ::             // Compiler frontend: scanner, parser
     List(new TyperPhase) ::         // Compiler frontend: namer, typer
+    List(new CheckUnused) ::        // Check for unused elements
     List(new YCheckPositions) ::    // YCheck positions
     List(new sbt.ExtractDependencies) :: // Sends information on classes' dependencies to sbt via callbacks
     List(new semanticdb.ExtractSemanticDB) :: // Extract info into .semanticdb files

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

@@ -60,7 +60,7 @@ trait CliCommand:
       def defaultValue = s.default match
         case _: Int | _: String => s.default.toString
         case _ => ""
-      val info = List(shortHelp(s), if defaultValue.nonEmpty then s"Default $defaultValue" else "", if s.legalChoices.nonEmpty then s"Choices ${s.legalChoices}" else "")
+      val info = List(shortHelp(s), if defaultValue.nonEmpty then s"Default $defaultValue" else "", if s.legalChoices.nonEmpty then s"Choices : ${s.legalChoices}" else "")
       (s.name, info.filter(_.nonEmpty).mkString("\n"))
     end help
 

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

@@ -155,20 +155,70 @@ private sealed trait VerboseSettings:
  */
 private sealed trait WarningSettings:
   self: SettingGroup =>
+  import Setting.ChoiceWithHelp
+
   val Whelp: Setting[Boolean] = BooleanSetting("-W", "Print a synopsis of warning options.")
   val XfatalWarnings: Setting[Boolean] = BooleanSetting("-Werror", "Fail the compilation if there are any warnings.", aliases = List("-Xfatal-warnings"))
 
-  val Wunused: Setting[List[String]] = MultiChoiceSetting(
+  val Wunused: Setting[List[ChoiceWithHelp[String]]] = MultiChoiceHelpSetting(
     name = "-Wunused",
     helpArg = "warning",
     descr = "Enable or disable specific `unused` warnings",
-    choices = List("nowarn", "all"),
+    choices = List(
+      ChoiceWithHelp("nowarn", ""),
+      ChoiceWithHelp("all",""),
+      ChoiceWithHelp(
+        name = "imports",
+        description = "Warn if an import selector is not referenced.\n" +
+        "NOTE : overrided by -Wunused:strict-no-implicit-warn"),
+        ChoiceWithHelp("privates","Warn if a private member is unused"),
+        ChoiceWithHelp("locals","Warn if a local definition is unused"),
+        ChoiceWithHelp("explicits","Warn if an explicit parameter is unused"),
+        ChoiceWithHelp("implicits","Warn if an implicit parameter is unused"),
+        ChoiceWithHelp("params","Enable -Wunused:explicits,implicits"),
+        ChoiceWithHelp("linted","Enable -Wunused:imports,privates,locals,implicits"),
+        ChoiceWithHelp(
+          name = "strict-no-implicit-warn",
+          description = "Same as -Wunused:import, only for imports of explicit named members.\n" +
+          "NOTE : This overrides -Wunused:imports and NOT set by -Wunused:all"
+        ),
+        // ChoiceWithHelp("patvars","Warn if a variable bound in a pattern is unused"),
+        ChoiceWithHelp(
+          name = "unsafe-warn-patvars",
+          description = "(UNSAFE) Warn if a variable bound in a pattern is unused.\n" +
+          "This warning can generate false positive, as warning cannot be\n" +
+          "suppressed yet."
+        )
+    ),
     default = Nil
   )
   object WunusedHas:
+    def isChoiceSet(s: String)(using Context) = Wunused.value.pipe(us => us.contains(s))
     def allOr(s: String)(using Context) = Wunused.value.pipe(us => us.contains("all") || us.contains(s))
     def nowarn(using Context) = allOr("nowarn")
 
+    // overrided by strict-no-implicit-warn
+    def imports(using Context) =
+      (allOr("imports") || allOr("linted")) && !(strictNoImplicitWarn)
+    def locals(using Context) =
+      allOr("locals") || allOr("linted")
+    /** -Wunused:explicits OR -Wunused:params */
+    def explicits(using Context) =
+      allOr("explicits") || allOr("params")
+    /** -Wunused:implicits OR -Wunused:params */
+    def implicits(using Context) =
+      allOr("implicits") || allOr("params") || allOr("linted")
+    def params(using Context) = allOr("params")
+    def privates(using Context) =
+      allOr("privates") || allOr("linted")
+    def patvars(using Context) =
+      isChoiceSet("unsafe-warn-patvars") // not with "all"
+      // allOr("patvars") // todo : rename once fixed
+    def linted(using Context) =
+      allOr("linted")
+    def strictNoImplicitWarn(using Context) =
+      isChoiceSet("strict-no-implicit-warn")
+
   val Wconf: Setting[List[String]] = MultiStringSetting(
     "-Wconf",
     "patterns",

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

@@ -11,6 +11,7 @@ import annotation.tailrec
 import collection.mutable.ArrayBuffer
 import reflect.ClassTag
 import scala.util.{Success, Failure}
+import dotty.tools.dotc.config.Settings.Setting.ChoiceWithHelp
 
 object Settings:
 
@@ -189,6 +190,19 @@ object Settings:
       def update(x: T)(using Context): SettingsState = setting.updateIn(ctx.settingsState, x)
       def isDefault(using Context): Boolean = setting.isDefaultIn(ctx.settingsState)
 
+    /**
+     * A choice with help description.
+     *
+     * NOTE : `equals` and `toString` have special behaviors
+     */
+    case class ChoiceWithHelp[T](name: T, description: String):
+      override def equals(x: Any): Boolean = x match
+        case s:String => s == name.toString()
+        case _ => false
+      override def toString(): String =
+        s"\n- $name${if description.isEmpty() then "" else s" :\n\t${description.replace("\n","\n\t")}"}"
+  end Setting
+
   class SettingGroup {
 
     private val _allSettings = new ArrayBuffer[Setting[?]]
@@ -270,6 +284,9 @@ object Settings:
     def MultiChoiceSetting(name: String, helpArg: String, descr: String, choices: List[String], default: List[String], aliases: List[String] = Nil): Setting[List[String]] =
       publish(Setting(name, descr, default, helpArg, Some(choices), aliases = aliases))
 
+    def MultiChoiceHelpSetting(name: String, helpArg: String, descr: String, choices: List[ChoiceWithHelp[String]], default: List[ChoiceWithHelp[String]], aliases: List[String] = Nil): Setting[List[ChoiceWithHelp[String]]] =
+      publish(Setting(name, descr, default, helpArg, Some(choices), aliases = aliases))
+
     def IntSetting(name: String, descr: String, default: Int, aliases: List[String] = Nil): Setting[Int] =
       publish(Setting(name, descr, default, aliases = aliases))
 

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -1001,6 +1001,7 @@ class Definitions {
   @tu lazy val MappedAlternativeAnnot: ClassSymbol = requiredClass("scala.annotation.internal.MappedAlternative")
   @tu lazy val MigrationAnnot: ClassSymbol = requiredClass("scala.annotation.migration")
   @tu lazy val NowarnAnnot: ClassSymbol = requiredClass("scala.annotation.nowarn")
+  @tu lazy val UnusedAnnot: ClassSymbol = requiredClass("scala.annotation.unused")
   @tu lazy val TransparentTraitAnnot: ClassSymbol = requiredClass("scala.annotation.transparentTrait")
   @tu lazy val NativeAnnot: ClassSymbol = requiredClass("scala.native")
   @tu lazy val RepeatedAnnot: ClassSymbol = requiredClass("scala.annotation.internal.Repeated")