From bbb9a7101a1b6a6caa5402bf7bcc7de70428abd0 Mon Sep 17 00:00:00 2001
From: Piotr Chabelski <ged.subfan@gmail.com>
Date: Tue, 26 Mar 2024 16:06:32 +0100
Subject: [PATCH] Ensure external help options are mentioned in short help
 where available (#2808)

---
 .../commands/ScalaCommandWithCustomHelp.scala | 11 +++++++++-
 .../shared/AllExternalHelpOptions.scala       | 22 +++++++++++++++++++
 .../commands/shared/ScalacExtraOptions.scala  |  4 ++++
 .../scala/cli/integration/HelpTests.scala     |  9 ++++++++
 4 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 modules/cli/src/main/scala/scala/cli/commands/shared/AllExternalHelpOptions.scala

diff --git a/modules/cli/src/main/scala/scala/cli/commands/ScalaCommandWithCustomHelp.scala b/modules/cli/src/main/scala/scala/cli/commands/ScalaCommandWithCustomHelp.scala
index 71e9b33c9a..88f9dbbd42 100644
--- a/modules/cli/src/main/scala/scala/cli/commands/ScalaCommandWithCustomHelp.scala
+++ b/modules/cli/src/main/scala/scala/cli/commands/ScalaCommandWithCustomHelp.scala
@@ -5,7 +5,12 @@ import caseapp.core.help.{Help, HelpCompanion, RuntimeCommandsHelp}
 import caseapp.core.parser.Parser
 
 import scala.cli.commands.default.{DefaultOptions, LegacyScalaOptions}
-import scala.cli.commands.shared.{HasGlobalOptions, ScalaCliHelp}
+import scala.cli.commands.shared.{
+  AllExternalHelpOptions,
+  HasGlobalOptions,
+  HelpGroupOptions,
+  ScalaCliHelp
+}
 import scala.cli.commands.util.HelpUtils.*
 import scala.cli.launcher.LauncherOptions
 
@@ -25,6 +30,8 @@ abstract class ScalaCommandWithCustomHelp[T <: HasGlobalOptions](
     val helpString            = actualHelp.help(helpFormat, showHidden)
     val launcherHelpString    = launcherHelp.optionsHelp(helpFormat, showHidden)
     val legacyScalaHelpString = legacyScalaHelp.optionsHelp(helpFormat, showHidden)
+    val allExternalHelp       = HelpCompanion.deriveHelp[AllExternalHelpOptions]
+    val allExternalHelpString = allExternalHelp.optionsHelp(helpFormat, showHidden)
     val legacyScalaHelpStringWithPadding =
       if legacyScalaHelpString.nonEmpty then
         s"""
@@ -34,6 +41,8 @@ abstract class ScalaCommandWithCustomHelp[T <: HasGlobalOptions](
     s"""$helpString
        |
        |$launcherHelpString
+       |
+       |$allExternalHelpString
        |$legacyScalaHelpStringWithPadding""".stripMargin
   }
 
diff --git a/modules/cli/src/main/scala/scala/cli/commands/shared/AllExternalHelpOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/shared/AllExternalHelpOptions.scala
new file mode 100644
index 0000000000..66dc531c7e
--- /dev/null
+++ b/modules/cli/src/main/scala/scala/cli/commands/shared/AllExternalHelpOptions.scala
@@ -0,0 +1,22 @@
+package scala.cli.commands.shared
+
+import caseapp.core.Scala3Helpers.*
+import caseapp.core.help.{Help, HelpFormat}
+import caseapp.{Help, *}
+import com.github.plokhotnyuk.jsoniter_scala.core.*
+import com.github.plokhotnyuk.jsoniter_scala.macros.*
+
+@HelpMessage("Print help message")
+// this is an aggregate for all external and internal help options
+case class AllExternalHelpOptions(
+  @Recurse
+  scalacExtra: ScalacExtraOptions = ScalacExtraOptions(),
+  @Recurse
+  helpGroups: HelpGroupOptions = HelpGroupOptions()
+)
+
+object AllExternalHelpOptions {
+  implicit lazy val parser: Parser[AllExternalHelpOptions]            = Parser.derive
+  implicit lazy val help: Help[AllExternalHelpOptions]                = Help.derive
+  implicit lazy val jsonCodec: JsonValueCodec[AllExternalHelpOptions] = JsonCodecMaker.make
+}
diff --git a/modules/cli/src/main/scala/scala/cli/commands/shared/ScalacExtraOptions.scala b/modules/cli/src/main/scala/scala/cli/commands/shared/ScalacExtraOptions.scala
index 4cac594505..5d53ff6ce4 100644
--- a/modules/cli/src/main/scala/scala/cli/commands/shared/ScalacExtraOptions.scala
+++ b/modules/cli/src/main/scala/scala/cli/commands/shared/ScalacExtraOptions.scala
@@ -4,6 +4,8 @@ import caseapp.*
 import com.github.plokhotnyuk.jsoniter_scala.core.*
 import com.github.plokhotnyuk.jsoniter_scala.macros.*
 
+import scala.cli.commands.tags
+
 /** Scala CLI options which aren't strictly scalac options, but directly involve the Scala compiler
   * in some way.
   */
@@ -12,11 +14,13 @@ final case class ScalacExtraOptions(
   @Group(HelpGroup.Scala.toString)
   @HelpMessage("Show help for scalac. This is an alias for --scalac-option -help")
   @Name("helpScalac")
+  @Tag(tags.inShortHelp)
     scalacHelp: Boolean = false,
 
   @Group(HelpGroup.Scala.toString)
   @HelpMessage("Turn verbosity on for scalac. This is an alias for --scalac-option -verbose")
   @Name("verboseScalac")
+  @Tag(tags.inShortHelp)
     scalacVerbose: Boolean = false,
 )
 // format: on
diff --git a/modules/integration/src/test/scala/scala/cli/integration/HelpTests.scala b/modules/integration/src/test/scala/scala/cli/integration/HelpTests.scala
index 8edc1d016d..35c8e52066 100644
--- a/modules/integration/src/test/scala/scala/cli/integration/HelpTests.scala
+++ b/modules/integration/src/test/scala/scala/cli/integration/HelpTests.scala
@@ -29,6 +29,15 @@ class HelpTests extends ScalaCliSuite {
     test(s"$helpOptionsString output does not include legacy scala runner options") {
       expect(!helpOutput.contains("Legacy Scala runner options"))
     }
+
+    test(s"$helpOptionsString output includes external help options") {
+      expect(helpOutput.contains("--scalac-help"))
+      expect(helpOutput.contains("--help-js"))
+      expect(helpOutput.contains("--help-native"))
+      expect(helpOutput.contains("--help-doc"))
+      expect(helpOutput.contains("--help-repl"))
+      expect(helpOutput.contains("--help-fmt"))
+    }
   }
 
   for (fullHelpOptions <- HelpTests.fullHelpVariants) {