Shorter options help (#1872)

* NIT Refactor SpecificationLevel

* Bump `case-app` to `2.1.0-M24` & `scala-cli-signing` to `0.1.16`

* Limit short `--help` options to just `MUST` & `IMPORTANT` tags

* Shorten the basic help message for the `run` sub-command

* Shorten the basic help message for the `version` sub-command

* Tweak the help output for the `update` sub-command

* Tweak the help output for the `uninstall completions` sub-command

* Tweak the help output for the `test` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `shebang` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `setup-ide` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `repl` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `publish` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `publish setup` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Tweak the help output for the `publish local` sub-command
  - shorten the help message
  - tweak which options are included in the short help
  - misc tweaks

* Hide non-publishing-specific options in the short help output for `publish`, `publish local` and `publish setup` sub-commands

* Tweak the short help output for the `package` sub-command

* Tweak the short help output for the `install-home` sub-command

* Tweak the short help output for the `install completions` sub-command

* Tweak the short help output for the `github secret list` & `github secret create` sub-commands

* Tweak the short help output for the `fmt` sub-command

* Tweak the short help output for the `export` sub-command

* Tweak the short help output for the `doc` sub-command

* Tweak the short help output for the `dependency-update` sub-command

* Tweak the short help output for the `config` sub-command

* Tweak the short help output for the `compile` sub-command

* Tweak the short help output for the `clean` sub-command

* Tweak the short help output for the `bsp` sub-command

* Tweak the short help output for the `bloop` sub-command

* Put the `Help` help group at the end of sorted groups

* Adjust help-relevant tests

* Adjust `--help-js` and `--help-native`

* Apply review comments
- temporarily remove console-specific characters from help messages to fix the reference doc website
- remove redundant tags for options already tagged as `SpecificationLevel.MUST`
- rename `tags.important` to `tags.inShortHelp`

* Ensure all launcher options are properly tagged

* Ensure all `export` options are properly tagged

* Fix integration tests after tied with `--power` mode after relevant tags changed

Author: Gedochao

modules/cli/src/main/scala/scala/cli/commands/bloop/BloopOptions.scala

@@ -6,13 +6,7 @@ import scala.cli.commands.shared.{CoursierOptions, HasLoggingOptions, HelpMessag
 import scala.cli.commands.tags
 
 // format: off
-@HelpMessage(
-  s"""Interact with Bloop (the build server) or check its status.
-     |
-     |This sub-command allows to check the current status of Bloop.
-     |If Bloop isn't currently running, it will be started.
-     |
-     |${HelpMessages.bloopInfo}""".stripMargin)
+@HelpMessage(BloopOptions.helpMessage, "", BloopOptions.detailedHelpMessage)
 final case class BloopOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -39,4 +33,12 @@ final case class BloopOptions(
 object BloopOptions {
   implicit lazy val parser: Parser[BloopOptions] = Parser.derive
   implicit lazy val help: Help[BloopOptions]   = Help.derive
+  val helpMessage: String = "Interact with Bloop (the build server) or check its status."
+  val detailedHelpMessage: String =
+    s"""$helpMessage
+       |
+       |This sub-command allows to check the current status of Bloop.
+       |If Bloop isn't currently running, it will be started.
+       |
+       |${HelpMessages.bloopInfo}""".stripMargin
 }

modules/cli/src/main/scala/scala/cli/commands/bsp/BspOptions.scala

@@ -7,16 +7,7 @@ import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
 import scala.cli.commands.tags
 
 // format: off
-@HelpMessage(
-  s"""Start BSP server.
-     |
-     |BSP stands for Build Server Protocol.
-     |For more information refer to https://build-server-protocol.github.io/
-     |
-     |This sub-command is not designed to be used by a human.
-     |It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported.
-     |
-     |${HelpMessages.docsWebsiteReference}""".stripMargin)
+@HelpMessage(BspOptions.helpMessage, "", BspOptions.detailedHelpMessage)
 final case class BspOptions(
   // FIXME There might be too many options in SharedOptions for the bsp command…
   @Recurse
@@ -34,4 +25,21 @@ final case class BspOptions(
 object BspOptions {
   implicit lazy val parser: Parser[BspOptions] = Parser.derive
   implicit lazy val help: Help[BspOptions]     = Help.derive
+  val cmdName                                  = "bsp"
+  private val helpHeader                       = "Start BSP server."
+  val helpMessage: String =
+    s"""$helpHeader
+       |
+       |${HelpMessages.commandFullHelpReference(cmdName)}
+       |${HelpMessages.docsWebsiteReference}""".stripMargin
+  val detailedHelpMessage: String =
+    s"""$helpHeader
+       |
+       |BSP stands for Build Server Protocol.
+       |For more information refer to https://build-server-protocol.github.io/
+       |
+       |This sub-command is not designed to be used by a human.
+       |It is normally supposed to be invoked by your IDE when a $fullRunnerName project is imported.
+       |
+       |${HelpMessages.docsWebsiteReference}""".stripMargin
 }

modules/cli/src/main/scala/scala/cli/commands/clean/CleanOptions.scala

@@ -12,12 +12,7 @@ import scala.cli.commands.shared.{
 }
 
 // format: off
-@HelpMessage(
-  s"""Clean the workspace.
-    |
-    |Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned.
-    |
-    |${HelpMessages.commandDocWebsiteReference("clean")}""".stripMargin)
+@HelpMessage(CleanOptions.helpMessage, "", CleanOptions.detailedHelpMessage)
 final case class CleanOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -31,4 +26,13 @@ final case class CleanOptions(
 object CleanOptions {
   implicit lazy val parser: Parser[CleanOptions] = Parser.derive
   implicit lazy val help: Help[CleanOptions]     = Help.derive
+  val cmdName                                    = "clean"
+  private val helpHeader                         = "Clean the workspace."
+  val helpMessage: String = HelpMessages.shortHelpMessage(cmdName, helpHeader)
+  val detailedHelpMessage: String =
+    s"""$helpHeader
+       |
+       |Passed inputs will establish the $fullRunnerName project, for which the workspace will be cleaned.
+       |
+       |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
 }

modules/cli/src/main/scala/scala/cli/commands/compile/Compile.scala

@@ -1,6 +1,7 @@
 package scala.cli.commands.compile
 
 import caseapp.*
+import caseapp.core.help.HelpFormat
 
 import java.io.File
 
@@ -14,13 +15,18 @@ import scala.cli.commands.update.Update
 import scala.cli.commands.util.BuildCommandHelpers
 import scala.cli.commands.{CommandUtils, ScalaCommand, WatchUtil}
 import scala.cli.config.{ConfigDb, Keys}
+import scala.cli.util.ArgHelpers.*
 
 object Compile extends ScalaCommand[CompileOptions] with BuildCommandHelpers {
   override def group = "Main"
 
   override def sharedOptions(options: CompileOptions): Option[SharedOptions] = Some(options.shared)
 
   override def scalaSpecificationLevel = SpecificationLevel.MUST
+  val primaryHelpGroups: Seq[String] =
+    Seq("Compilation", "Scala", "Java", "Watch", "Compilation server")
+
+  override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroups(primaryHelpGroups)
 
   override def runCommand(options: CompileOptions, args: RemainingArgs, logger: Logger): Unit = {
     val buildOptions = buildOptionsOrExit(options)

modules/cli/src/main/scala/scala/cli/commands/compile/CompileOptions.scala

@@ -12,16 +12,7 @@ import scala.cli.commands.shared.{
 }
 import scala.cli.commands.tags
 
-@HelpMessage({
-  val cmdName = "compile"
-  s"""Compile Scala code.
-     |
-     |${HelpMessages.commandConfigurations(cmdName)}
-     |
-     |${HelpMessages.acceptedInputs}
-     |
-     |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
-})
+@HelpMessage(CompileOptions.helpMessage, "", CompileOptions.detailedHelpMessage)
 // format: off
 final case class CompileOptions(
   @Recurse
@@ -31,19 +22,34 @@ final case class CompileOptions(
   @Recurse
     cross: CrossOptions = CrossOptions(),
 
+  @Group("Compilation")
   @Name("p")
   @Name("printClasspath")
   @HelpMessage("Print the resulting class path")
   @Tag(tags.should)
+  @Tag(tags.inShortHelp)
     printClassPath: Boolean = false,
 
+  @Group("Compilation")
   @HelpMessage("Compile test scope")
   @Tag(tags.should)
+  @Tag(tags.inShortHelp)
     test: Boolean = false
 ) extends HasSharedOptions
   // format: on
 
 object CompileOptions {
   implicit lazy val parser: Parser[CompileOptions] = Parser.derive
   implicit lazy val help: Help[CompileOptions]     = Help.derive
+  val cmdName                                      = "compile"
+  private val helpHeader                           = "Compile Scala code."
+  val helpMessage: String = HelpMessages.shortHelpMessage(cmdName, helpHeader)
+  val detailedHelpMessage: String =
+    s"""$helpHeader
+       |
+       |${HelpMessages.commandConfigurations(cmdName)}
+       |
+       |${HelpMessages.acceptedInputs}
+       |
+       |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
 }

modules/cli/src/main/scala/scala/cli/commands/config/Config.scala

@@ -1,6 +1,7 @@
 package scala.cli.commands.config
 
 import caseapp.core.RemainingArgs
+import caseapp.core.help.HelpFormat
 import coursier.cache.ArchiveCache
 
 import java.util.Base64
@@ -20,11 +21,14 @@ import scala.cli.config.{
   RepositoryCredentials,
   Secret
 }
-
+import scala.cli.util.ArgHelpers.*
 object Config extends ScalaCommand[ConfigOptions] {
-  override def hidden                  = true
   override def scalaSpecificationLevel = SpecificationLevel.MUST
 
+  override def helpFormat: HelpFormat = super.helpFormat
+    .copy(hiddenGroups = Some(Seq("Java")))
+    .withPrimaryGroup("Config")
+
   override def runCommand(options: ConfigOptions, args: RemainingArgs, logger: Logger): Unit = {
     val directories = Directories.directories
 

modules/cli/src/main/scala/scala/cli/commands/config/ConfigOptions.scala

@@ -14,15 +14,7 @@ import scala.cli.commands.shared.{
 import scala.cli.commands.tags
 
 // format: off
-@HelpMessage(
-  s"""Configure global settings for $fullRunnerName.
-     |
-     |Syntax:
-     |  $progName config key value
-     |For example, to globally set the interactive mode:
-     |  $progName config interactive true
-     |
-     |${HelpMessages.commandDocWebsiteReference("misc/config")}""".stripMargin)
+@HelpMessage(ConfigOptions.helpMessage, "", ConfigOptions.detailedHelpMessage)
 final case class ConfigOptions(
   @Recurse
     logging: LoggingOptions = LoggingOptions(),
@@ -37,46 +29,75 @@ final case class ConfigOptions(
   @HelpMessage("Dump config DB as JSON")
   @Hidden
   @Tag(tags.implementation)
+  @Tag(tags.inShortHelp)
     dump: Boolean = false,
   @Group("Config")
   @HelpMessage("Create PGP key in config")
+  @Tag(tags.inShortHelp)
+  @Tag(tags.restricted)
     createPgpKey: Boolean = false,
   @Group("Config")
   @HelpMessage("Email to use to create PGP key in config")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     email: Option[String] = None,
   @Group("Config")
   @HelpMessage("If the entry is a password, print the password value rather than how to get the password")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     password: Boolean = false,
   @Group("Config")
   @HelpMessage("If the entry is a password, save the password value rather than how to get the password")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     passwordValue: Boolean = false,
   @Group("Config")
   @HelpMessage("Remove an entry from config")
+  @Tag(tags.inShortHelp)
+  @Tag(tags.should)
   @ExtraName("remove")
     unset: Boolean = false,
   @Group("Config")
   @HelpMessage("For repository.credentials and publish.credentials, whether these credentials should be HTTPS only (default: true)")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     httpsOnly: Option[Boolean] = None,
   @Group("Config")
   @HelpMessage("For repository.credentials, whether to use these credentials automatically based on the host")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     matchHost: Option[Boolean] = None,
   @Group("Config")
   @HelpMessage("For repository.credentials, whether to use these credentials are optional")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     optional: Option[Boolean] = None,
   @Group("Config")
   @HelpMessage("For repository.credentials, whether to use these credentials should be passed upon redirection")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     passOnRedirect: Option[Boolean] = None
 ) extends HasLoggingOptions
 // format: on
 
 object ConfigOptions {
   implicit lazy val parser: Parser[ConfigOptions] = Parser.derive
   implicit lazy val help: Help[ConfigOptions]     = Help.derive
+  private val helpHeader: String = s"Configure global settings for $fullRunnerName."
+  private val cmdName            = "config"
+  private val websiteSuffix      = s"misc/$cmdName"
+  val helpMessage: String =
+    s"""$helpHeader
+       |
+       |${HelpMessages.commandFullHelpReference(cmdName)}
+       |${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
+  val detailedHelpMessage: String =
+    s"""$helpHeader
+       |
+       |Syntax:
+       |  $progName $cmdName key value
+       |For example, to globally set the interactive mode:
+       |  $progName $cmdName interactive true
+       |
+       |${HelpMessages.commandDocWebsiteReference(websiteSuffix)}""".stripMargin
 }

modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdate.scala

@@ -1,6 +1,7 @@
 package scala.cli.commands.dependencyupdate
 
 import caseapp.*
+import caseapp.core.help.HelpFormat
 
 import scala.build.actionable.ActionableDependencyHandler
 import scala.build.actionable.ActionableDiagnostic.ActionableDependencyUpdateDiagnostic
@@ -10,10 +11,12 @@ import scala.build.{CrossSources, Logger, Position, Sources}
 import scala.cli.CurrentParams
 import scala.cli.commands.ScalaCommand
 import scala.cli.commands.shared.SharedOptions
+import scala.cli.util.ArgHelpers.*
 
 object DependencyUpdate extends ScalaCommand[DependencyUpdateOptions] {
   override def group                   = "Main"
   override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
+  override def helpFormat: HelpFormat  = super.helpFormat.withPrimaryGroup("Dependency")
   override def sharedOptions(options: DependencyUpdateOptions): Option[SharedOptions] =
     Some(options.shared)
   override def runCommand(

modules/cli/src/main/scala/scala/cli/commands/dependencyupdate/DependencyUpdateOptions.scala

@@ -11,9 +11,10 @@ import scala.cli.commands.tags
 final case class DependencyUpdateOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
-  @Group("DependencyUpdate")
+  @Group("Dependency")
   @HelpMessage("Update all dependencies if a newer version was released")
   @Tag(tags.restricted)
+  @Tag(tags.inShortHelp)
     all: Boolean = false,
 ) extends HasSharedOptions
   // format: on

modules/cli/src/main/scala/scala/cli/commands/doc/Doc.scala

@@ -1,6 +1,7 @@
 package scala.cli.commands.doc
 
 import caseapp.*
+import caseapp.core.help.HelpFormat
 import dependency.*
 
 import java.io.File
@@ -18,13 +19,16 @@ import scala.cli.commands.shared.SharedOptions
 import scala.cli.commands.{CommandUtils, ScalaCommand}
 import scala.cli.config.{ConfigDb, Keys}
 import scala.cli.errors.ScaladocGenerationFailedError
+import scala.cli.util.ArgHelpers.*
 import scala.util.Properties
 
 object Doc extends ScalaCommand[DocOptions] {
   override def group = "Main"
 
   override def sharedOptions(options: DocOptions): Option[SharedOptions] = Some(options.shared)
 
+  override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroup("Doc")
+
   override def scalaSpecificationLevel = SpecificationLevel.MUST
 
   override def runCommand(options: DocOptions, args: RemainingArgs, logger: Logger): Unit = {

modules/cli/src/main/scala/scala/cli/commands/doc/DocOptions.scala

@@ -8,15 +8,7 @@ import scala.cli.commands.shared.{HasSharedOptions, HelpMessages, SharedOptions}
 import scala.cli.commands.tags
 
 // format: off
-@HelpMessage(
-  message =
-    s"""Generate Scaladoc documentation.
-       |
-       |${HelpMessages.acceptedInputs}
-       |
-       |${HelpMessages.commandDocWebsiteReference("doc")}""".stripMargin,
-  messageMd = s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`."
-)
+@HelpMessage(DocOptions.helpMessage, DocOptions.messageMd, DocOptions.detailedHelpMessage)
 final case class DocOptions(
   @Recurse
     shared: SharedOptions = SharedOptions(),
@@ -41,4 +33,15 @@ final case class DocOptions(
 object DocOptions {
   implicit lazy val parser: Parser[DocOptions] = Parser.derive
   implicit lazy val help: Help[DocOptions]     = Help.derive
+  val cmdName                                  = "doc"
+  private val helpHeader                       = "Generate Scaladoc documentation."
+  val helpMessage: String                      = HelpMessages.shortHelpMessage(cmdName, helpHeader)
+  val detailedHelpMessage: String =
+    s"""Generate Scaladoc documentation.
+       |
+       |${HelpMessages.acceptedInputs}
+       |
+       |${HelpMessages.commandDocWebsiteReference(cmdName)}""".stripMargin
+  val messageMd =
+    s"By default, $fullRunnerName sets common `scaladoc` options and this mechanism can be disabled by using `--default-scaladoc-opts:false`."
 }