Runner specification (#1445)

* Define specification levels

* Tag options for used in scala command

* Tag commands with specification level

* Tag directives with specification level

* Make shebang a MUST comamnd for runner

* Address review and CI problems

* Add scaladoc to levels

* Apply suggestions from code review

Co-authored-by: Piotr Chabelski <ged.subfan@gmail.com>

* scalafix

* format

* Fixes for caseapp in Scala 3

Co-authored-by: Piotr Chabelski <ged.subfan@gmail.com>

Author: romanowski

build.sc

@@ -415,7 +415,8 @@ trait Directives extends ScalaCliSbtModule with ScalaCliPublishModule with HasTe
   def moduleDeps = Seq(
     options,
     core,
-    `build-macros`
+    `build-macros`,
+    `cli-options`
   )
   def scalacOptions = T {
     super.scalacOptions() ++ asyncScalacOptions(scalaVersion())
@@ -435,6 +436,9 @@ trait Directives extends ScalaCliSbtModule with ScalaCliPublishModule with HasTe
     Deps.usingDirectives
   )
 
+  def repositoriesTask =
+    T.task(super.repositoriesTask() ++ deps.customRepositories)
+
   object test extends Tests with ScalaCliTests {
     def ivyDeps = super.ivyDeps() ++ Agg(
       Deps.pprint
@@ -515,6 +519,9 @@ trait Options extends ScalaCliSbtModule with ScalaCliPublishModule with HasTests
     Deps.jsoniterMacros
   )
 
+  def repositoriesTask =
+    T.task(super.repositoriesTask() ++ deps.customRepositories)
+
   object test extends Tests with ScalaCliTests {
     // uncomment below to debug tests in attach mode on 5005 port
     // def forkArgs = T {
@@ -595,6 +602,9 @@ trait Build extends ScalaCliSbtModule with ScalaCliPublishModule with HasTests
     Deps.zipInputStream
   ) ++ (if (scalaVersion().startsWith("3")) Agg() else Agg(Deps.shapeless))
 
+  def repositoriesTask =
+    T.task(super.repositoriesTask() ++ deps.customRepositories)
+
   object test extends Tests with ScalaCliTests {
     def ivyDeps = super.ivyDeps() ++ Agg(
       Deps.pprint,
@@ -741,7 +751,6 @@ trait Cli extends SbtModule with ProtoBuildModule with CliLaunchers
   }
   def moduleDeps = Seq(
     `build-module`,
-    `cli-options`,
     config(Scala.scala3),
     `scala3-graal`(Scala.scala3)
   )

modules/cli-options/src/main/scala/scala/cli/commands/AboutOptions.scala

@@ -13,6 +13,7 @@ final case class AboutOptions(
     logging: LoggingOptions = LoggingOptions(),
   @Hidden
   @HelpMessage(HelpMessages.passwordOption)
+  @Tag(tags.implementation)
     ghToken: Option[PasswordOption] = None
 ) extends HasLoggingOptions
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/BenchmarkingOptions.scala

@@ -5,10 +5,12 @@ import caseapp.*
 // format: off
 final case class BenchmarkingOptions(
   @Group("Benchmarking")
-  @HelpMessage("[experimental] Run JMH benchmarks")
+  @Tag(tags.experimental)
+  @HelpMessage("Run JMH benchmarks")
     jmh: Option[Boolean] = None,
   @Group("Benchmarking")
-  @HelpMessage("[experimental] Set JMH version")
+  @Tag(tags.experimental)
+  @HelpMessage("Set JMH version")
   @ValueDescription("version")
     jmhVersion: Option[String] = None
 )

modules/cli-options/src/main/scala/scala/cli/commands/CompileOptions.scala

@@ -17,10 +17,12 @@ final case class CompileOptions(
 
   @Name("p")
   @Name("printClasspath")
+  @Tag(tags.restricted)
   @HelpMessage("Print the resulting class path")
     printClassPath: Boolean = false,
 
   @HelpMessage("Compile test scope")
+  @Tag(tags.should)
     test: Boolean = false
 ) extends HasSharedOptions
   // format: on

modules/cli-options/src/main/scala/scala/cli/commands/CoursierOptions.scala

@@ -9,15 +9,18 @@ final case class CoursierOptions(
   @Group("Dependency")
   @HelpMessage("Specify a TTL for changing dependencies, such as snapshots")
   @ValueDescription("duration|Inf")
+  @Tag(tags.implementation)
   @Hidden
     ttl: Option[String] = None,
   @Group("Dependency")
   @HelpMessage("Set the coursier cache location")
   @ValueDescription("path")
+  @Tag(tags.implementation)
   @Hidden
     cache: Option[String] = None,
   @Group("Dependency")
   @HelpMessage("Enable checksum validation of artifacts downloaded by coursier")
+  @Tag(tags.implementation)
   @Hidden
     coursierValidateChecksums: Option[Boolean] = None
 )

modules/cli-options/src/main/scala/scala/cli/commands/CrossOptions.scala

@@ -4,7 +4,8 @@ import caseapp.*
 
 // format: off
 final case class CrossOptions(
-    @HelpMessage("[experimental] Run given command against all provided Scala versions and/or platforms")
+  @Tag(tags.experimental)
+  @HelpMessage("Run given command against all provided Scala versions and/or platforms")
     cross: Option[Boolean] = None
 )
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/DocOptions.scala

@@ -11,15 +11,18 @@ final case class DocOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
   @Group("Doc")
+  @Tag(tags.must)
   @HelpMessage("Set the destination path")
   @Name("o")
     output: Option[String] = None,
   @Group("Doc")
-  @HelpMessage("Overwrite the destination directory, if it exists")
+  @HelpMessage("Overwrite the destination directory, if it exists")  
+  @Tag(tags.must)
   @Name("f")
     force: Boolean = false,
   @Group("Doc")
   @HelpMessage("Control if Scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.")
+  @Tag(tags.should)
   @ExtraName("defaultScaladocOpts")
     defaultScaladocOptions: Option[Boolean] = None,
 ) extends HasSharedOptions

modules/cli-options/src/main/scala/scala/cli/commands/DoctorOptions.scala

@@ -13,6 +13,7 @@ final case class DoctorOptions(
     logging: LoggingOptions = LoggingOptions(),
   @Hidden
   @HelpMessage(HelpMessages.passwordOption)
+  @Tag(tags.implementation)
     ghToken: Option[PasswordOption] = None
 ) extends HasLoggingOptions
 // format: on

modules/cli-options/src/main/scala/scala/cli/commands/FmtOptions.scala

@@ -12,27 +12,34 @@ final case class FmtOptions(
     shared: SharedOptions = SharedOptions(),
 
   @Group("Format")
+  @Tag(tags.should)
   @HelpMessage("Check if sources are well formatted")
     check: Boolean = false,
 
   @Group("Format")
+  @Tag(tags.implementation)
   @HelpMessage("Use project filters defined in the configuration. Turned on by default, use `--respect-project-filters:false` to disable it.")
     respectProjectFilters: Boolean = true,
 
   @Group("Format")
+  @Tag(tags.implementation)
   @HelpMessage("Saves .scalafmt.conf file if it was created or overwritten")
     saveScalafmtConf: Boolean = false,
 
   @Group("Format")
+  @Tag(tags.implementation)
   @Hidden
     osArchSuffix: Option[String] = None,
   @Group("Format")
+  @Tag(tags.implementation)
   @Hidden
     scalafmtTag: Option[String] = None,
   @Group("Format")
+  @Tag(tags.implementation)
   @Hidden
     scalafmtGithubOrgName: Option[String] = None,
   @Group("Format")
+  @Tag(tags.implementation)
   @Hidden
     scalafmtExtension: Option[String] = None,
   @Group("Format")
@@ -41,22 +48,27 @@ final case class FmtOptions(
 
   @Group("Format")
   @Name("F")
+  @Tag(tags.implementation)
   @HelpMessage("Pass argument to scalafmt.")
     scalafmtArg: List[String] = Nil,
 
   @Group("Format")
   @HelpMessage("Custom path to the scalafmt configuration file.")
+  @Tag(tags.implementation)
   @Name("scalafmtConfig")
     scalafmtConf: Option[String] = None,
   @Group("Format")
   @HelpMessage("Pass configuration as a string.")
   @Name("scalafmtConfigStr")
   @Name("scalafmtConfSnippet")
     scalafmtConfStr: Option[String] = None,
+  @Tag(tags.implementation)
   @Group("Format")
   @HelpMessage("Pass a global dialect for scalafmt. This overrides whatever value is configured in the .scalafmt.conf file or inferred based on Scala version used.")
+  @Tag(tags.implementation)
   @Name("dialect")
     scalafmtDialect: Option[String] = None,
+  @Tag(tags.implementation)
   @Group("Format")
   @HelpMessage(s"Pass scalafmt version before running it (${Constants.defaultScalafmtVersion} by default). If passed, this overrides whatever value is configured in the .scalafmt.conf file.")
   @Name("fmtVersion")

modules/cli-options/src/main/scala/scala/cli/commands/HelpGroupOptions.scala

@@ -9,21 +9,26 @@ import com.github.plokhotnyuk.jsoniter_scala.macros.*
 @HelpMessage("Print help message")
 case class HelpGroupOptions(
   @HelpMessage("Show options for ScalaJS")
+  @Tag(tags.implementation)
   helpJs: Boolean = false,
   @HelpMessage("Show options for ScalaNative")
+  @Tag(tags.implementation)
   helpNative: Boolean = false,
   @HelpMessage("Show options for Scaladoc")
   @Name("scaladocHelp")
   @Name("docHelp")
   @Name("helpDoc")
+  @Tag(tags.implementation)
   helpScaladoc: Boolean = false,
   @HelpMessage("Show options for Scala REPL")
   @Name("replHelp")
+  @Tag(tags.implementation)
   helpRepl: Boolean = false,
   @HelpMessage("Show options for Scalafmt")
   @Name("scalafmtHelp")
   @Name("fmtHelp")
   @Name("helpFmt")
+  @Tag(tags.implementation)
   helpScalafmt: Boolean = false
 ) {