Merge pull request #1915 from Gedochao/specification-level-experimental

Fix handling for `experimental` features

Author: Gedochao

modules/build/src/main/scala/scala/build/preprocessing/DirectivesProcessor.scala

@@ -33,10 +33,11 @@ object DirectivesProcessor {
       scopedDirective: ScopedDirective,
       logger: Logger
     ) =
-      if (!allowRestrictedFeatures && handler.isRestricted)
+      if (!allowRestrictedFeatures && (handler.isRestricted || handler.isExperimental))
+        val powerDirectiveType = if handler.isExperimental then "experimental" else "restricted"
         val msg =
-          """This directive is not supported.
-            |Please run it with the `--power` flag or turn this flag on globally by running `config power true`.""".stripMargin
+          s"""This directive is $powerDirectiveType.
+             |Please run it with the '--power' flag or turn this flag on globally by running 'config power true'""".stripMargin
         Left(DirectiveErrors(
           ::(msg, Nil),
           DirectiveUtil.positions(scopedDirective.directive.values, path)

modules/cli/src/main/scala/scala/cli/commands/RestrictableCommand.scala

@@ -10,6 +10,8 @@ trait RestrictableCommand[T](implicit myParser: Parser[T]) {
 
   final def isRestricted: Boolean = scalaSpecificationLevel == SpecificationLevel.RESTRICTED
 
+  final def isExperimental: Boolean = scalaSpecificationLevel == SpecificationLevel.EXPERIMENTAL
+
   /** Is that command a MUST / SHOULD / NICE TO have for the Scala runner specification? */
   def scalaSpecificationLevel: SpecificationLevel
   // To reduce imports...

modules/cli/src/main/scala/scala/cli/commands/RestrictedCommandsParser.scala

@@ -6,6 +6,7 @@ import caseapp.core.parser.Parser
 import caseapp.core.util.Formatter
 import caseapp.core.{Arg, Error}
 
+import scala.cli.ScalaCli
 import scala.cli.util.ArgHelpers.*
 
 object RestrictedCommandsParser {
@@ -33,11 +34,13 @@ object RestrictedCommandsParser {
       nameFormatter: Formatter[Name]
     ): Either[(Error, Arg, List[String]), Option[(D, Arg, List[String])]] =
       (parser.step(args, index, d, nameFormatter), args) match {
-        case (Right(Some(_, arg, _)), passedOption :: _) if !arg.isSupported =>
+        case (Right(Some(_, arg: Arg, _)), passedOption :: _) if !arg.isSupported =>
+          val powerOptionType = if arg.isExperimental then "experimental" else "restricted"
           Left((
             Error.UnrecognizedArgument(
-              s"""`$passedOption` option is not supported.
-                 |Please run it with the `--power` flag or turn this flag on globally by running `config power true`.""".stripMargin
+              s"""The '$passedOption' option is $powerOptionType.
+                 |You can run it with the '--power' flag or turn the power mode on globally by running:
+                 |  ${Console.BOLD}${ScalaCli.progName} config power true${Console.RESET}.""".stripMargin
             ),
             arg,
             Nil

modules/cli/src/main/scala/scala/cli/commands/ScalaCommand.scala

@@ -38,10 +38,11 @@ abstract class ScalaCommand[T <: HasLoggingOptions](implicit myParser: Parser[T]
 
   def sharedOptions(t: T): Option[SharedOptions] = // hello borked unused warning
     None
-  override def hasFullHelp       = true
-  override def hidden            = shouldExcludeInSip
-  protected var argvOpt          = Option.empty[Array[String]]
-  private val shouldExcludeInSip = isRestricted && !ScalaCli.allowRestrictedFeatures
+  override def hasFullHelp = true
+  override def hidden      = shouldExcludeInSip
+  protected var argvOpt    = Option.empty[Array[String]]
+  private val shouldExcludeInSip =
+    (isRestricted || isExperimental) && !ScalaCli.allowRestrictedFeatures
   override def setArgv(argv: Array[String]): Unit = {
     argvOpt = Some(argv)
   }
@@ -275,7 +276,9 @@ abstract class ScalaCommand[T <: HasLoggingOptions](implicit myParser: Parser[T]
 
   override val messages: Help[T] =
     if (shouldExcludeInSip)
-      Help[T](helpMessage = Some(HelpMessage(HelpMessages.restrictedCommandUsedInSip)))
+      Help[T](helpMessage =
+        Some(HelpMessage(HelpMessages.powerCommandUsedInSip(scalaSpecificationLevel)))
+      )
     else help
 
   /** @param options
@@ -307,7 +310,7 @@ abstract class ScalaCommand[T <: HasLoggingOptions](implicit myParser: Parser[T]
     */
   final override def run(options: T, remainingArgs: RemainingArgs): Unit = {
     if (shouldExcludeInSip)
-      System.err.println(HelpMessages.restrictedCommandUsedInSip)
+      System.err.println(HelpMessages.powerCommandUsedInSip(scalaSpecificationLevel))
       sys.exit(1)
     CurrentParams.verbosity = options.logging.verbosity
     maybePrintWarnings(options)

modules/cli/src/main/scala/scala/cli/commands/export0/Export.scala

@@ -25,7 +25,7 @@ import scala.cli.util.ArgHelpers.*
 import scala.util.Using
 
 object Export extends ScalaCommand[ExportOptions] {
-  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.EXPERIMENTAL
 
   override def helpFormat: HelpFormat =
     super.helpFormat.withPrimaryGroup(HelpGroup.BuildToolExport)

modules/cli/src/main/scala/scala/cli/commands/github/SecretCreate.scala

@@ -21,7 +21,7 @@ import scala.cli.util.ArgHelpers.*
 
 object SecretCreate extends ScalaCommand[SecretCreateOptions] {
 
-  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.EXPERIMENTAL
   override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroup(HelpGroup.Secret)
   override def names = List(
     List("github", "secret", "create"),

modules/cli/src/main/scala/scala/cli/commands/github/SecretList.scala

@@ -17,7 +17,7 @@ import scala.cli.util.ArgHelpers.*
 
 object SecretList extends ScalaCommand[SecretListOptions] {
 
-  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.EXPERIMENTAL
 
   override def helpFormat: HelpFormat = super.helpFormat.withPrimaryGroup(HelpGroup.Secret)
   override def names = List(

modules/cli/src/main/scala/scala/cli/commands/pgp/PgpCommand.scala

@@ -12,7 +12,7 @@ abstract class PgpCommand[T](implicit myParser: Parser[T], help: Help[T])
     extends Command()(myParser, help)
     with CommandHelpers with RestrictableCommand[T] {
 
-  override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel = SpecificationLevel.EXPERIMENTAL
 
   override def hidden = true
 }

modules/cli/src/main/scala/scala/cli/commands/pgp/PgpPull.scala

@@ -10,7 +10,7 @@ import scala.cli.commands.util.ScalaCliSttpBackend
 object PgpPull extends ScalaCommand[PgpPullOptions] {
 
   override def hidden                  = true
-  override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel = SpecificationLevel.EXPERIMENTAL
   override def names = List(
     List("pgp", "pull")
   )

modules/cli/src/main/scala/scala/cli/commands/pgp/PgpPush.scala

@@ -12,7 +12,7 @@ import scala.cli.internal.PgpProxyMakerSubst
 object PgpPush extends ScalaCommand[PgpPushOptions] {
 
   override def hidden                  = true
-  override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel = SpecificationLevel.EXPERIMENTAL
   override def names = List(
     List("pgp", "push")
   )

modules/cli/src/main/scala/scala/cli/commands/publish/Publish.scala

@@ -69,7 +69,7 @@ import scala.util.control.NonFatal
 
 object Publish extends ScalaCommand[PublishOptions] with BuildCommandHelpers {
 
-  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.EXPERIMENTAL
 
   import scala.cli.commands.shared.HelpGroup.*
   val primaryHelpGroups: Seq[HelpGroup] = Seq(Publishing, Signing, PGP)

modules/cli/src/main/scala/scala/cli/commands/publish/PublishLocal.scala

@@ -14,7 +14,7 @@ import scala.cli.util.ArgHelpers.*
 object PublishLocal extends ScalaCommand[PublishLocalOptions] {
 
   override def group: String           = HelpCommandGroup.Main.toString
-  override def scalaSpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel = SpecificationLevel.EXPERIMENTAL
   override def helpFormat: HelpFormat =
     super.helpFormat
       .withHiddenGroups(Publish.hiddenHelpGroups)

modules/cli/src/main/scala/scala/cli/commands/publish/PublishSetup.scala

@@ -24,7 +24,7 @@ import scala.cli.util.ArgHelpers.*
 object PublishSetup extends ScalaCommand[PublishSetupOptions] {
 
   override def group: String                               = HelpCommandGroup.Main.toString
-  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.RESTRICTED
+  override def scalaSpecificationLevel: SpecificationLevel = SpecificationLevel.EXPERIMENTAL
 
   override def helpFormat: HelpFormat =
     super.helpFormat

modules/cli/src/main/scala/scala/cli/commands/shared/HelpMessages.scala

@@ -1,6 +1,7 @@
 package scala.cli.commands.shared
 
 import scala.cli.ScalaCli
+import scala.cli.commands.SpecificationLevel
 
 object HelpMessages {
   lazy val PowerString: String = if ScalaCli.allowRestrictedFeatures then "" else "--power "
@@ -47,8 +48,11 @@ object HelpMessages {
     s"""Specific $cmdName configurations can be specified with both command line options and using directives defined in sources.
        |Command line options always take priority over using directives when a clash occurs, allowing to override configurations defined in sources.
        |Using directives can be defined in all supported input source file types.""".stripMargin
-  lazy val restrictedCommandUsedInSip: String =
-    s"""This command is restricted and requires setting the `--power` option to be used.
+  def powerCommandUsedInSip(specificationLevel: SpecificationLevel): String = {
+    val powerCommandType =
+      if specificationLevel == SpecificationLevel.EXPERIMENTAL then "experimental" else "restricted"
+    s"""This command is $powerCommandType and requires setting the '--power' launcher option to be used.
        |You can pass it explicitly or set it globally by running:
        |   ${Console.BOLD}${ScalaCli.progName} config power true${Console.RESET}""".stripMargin
+  }
 }

modules/cli/src/main/scala/scala/cli/util/ArgHelpers.scala

@@ -9,13 +9,16 @@ import scala.cli.commands.{SpecificationLevel, tags}
 
 object ArgHelpers {
   extension (arg: Arg) {
-    def isExperimentalOrRestricted: Boolean =
-      arg.tags.exists(_.name == tags.restricted) || arg.tags.exists(_.name == tags.experimental)
+    private def hasTag(tag: String): Boolean = arg.tags.exists(_.name == tag)
+    def isExperimental: Boolean              = arg.hasTag(tags.experimental)
+    def isRestricted: Boolean                = arg.hasTag(tags.restricted)
+
+    def isExperimentalOrRestricted: Boolean = arg.isRestricted || arg.isExperimental
 
     def isSupported: Boolean = allowRestrictedFeatures || !arg.isExperimentalOrRestricted
-    def isImportant: Boolean = arg.tags.exists(_.name == tags.inShortHelp)
+    def isImportant: Boolean = arg.hasTag(tags.inShortHelp)
 
-    def isMust: Boolean = arg.tags.exists(_.name == tags.must)
+    def isMust: Boolean = arg.hasTag(tags.must)
 
     def level: SpecificationLevel = arg.tags
       .flatMap(t => tags.levelFor(t.name))

modules/directives/src/main/scala/scala/build/preprocessing/directives/DirectiveHandler.scala

@@ -34,7 +34,8 @@ trait DirectiveHandler[+T] { self =>
   def scalaSpecificationLevel: SpecificationLevel
   protected def SpecificationLevel = scala.cli.commands.SpecificationLevel
 
-  final def isRestricted: Boolean = scalaSpecificationLevel == SpecificationLevel.RESTRICTED
+  final def isRestricted: Boolean   = scalaSpecificationLevel == SpecificationLevel.RESTRICTED
+  final def isExperimental: Boolean = scalaSpecificationLevel == SpecificationLevel.EXPERIMENTAL
 
   def keys: Seq[String]
 

modules/directives/src/main/scala/scala/build/preprocessing/directives/Publish.scala

@@ -22,7 +22,7 @@ import scala.cli.commands.SpecificationLevel
     |""".stripMargin
 )
 @DirectiveDescription("Set parameters for publishing")
-@DirectiveLevel(SpecificationLevel.RESTRICTED)
+@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
 // format: off
 final case class Publish(
   organization: Option[Positioned[String]] = None,

modules/directives/src/main/scala/scala/build/preprocessing/directives/PublishContextual.scala

@@ -99,7 +99,7 @@ object PublishContextual {
       |""".stripMargin
   )
   @DirectiveDescription("Set contextual parameters for publishing")
-  @DirectiveLevel(SpecificationLevel.RESTRICTED)
+  @DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
   // format: off
   final case class Local(
     computeVersion: Option[Positioned[String]] = None,

modules/directives/src/main/scala/scala/build/preprocessing/directives/RequirePlatform.scala

@@ -17,7 +17,7 @@ import scala.cli.commands.SpecificationLevel
   "//> using target.platform _platform_",
   "`//> using target.platform `_platform_"
 )
-@DirectiveLevel(SpecificationLevel.RESTRICTED)
+@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
 // format: off
 final case class RequirePlatform(
   @DirectiveName("platform")

modules/directives/src/main/scala/scala/build/preprocessing/directives/RequireScalaVersion.scala

@@ -13,7 +13,7 @@ import scala.cli.commands.SpecificationLevel
   "//> using target.scala _version_",
   "`//> using target.scala `_version_"
 )
-@DirectiveLevel(SpecificationLevel.RESTRICTED)
+@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
 final case class RequireScalaVersion(
   scala: Option[DirectiveValueParser.MaybeNumericalString] = None
 ) extends HasBuildRequirements {

modules/directives/src/main/scala/scala/build/preprocessing/directives/RequireScalaVersionBounds.scala

@@ -14,7 +14,7 @@ import scala.cli.commands.SpecificationLevel
   "//> using target.scala.>= _version_",
   "`//> using target.scala.>= `_version_"
 )
-@DirectiveLevel(SpecificationLevel.RESTRICTED)
+@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
 final case class RequireScalaVersionBounds(
   `==`: Option[DirectiveValueParser.MaybeNumericalString] = None,
   `>=`: Option[DirectiveValueParser.MaybeNumericalString] = None,

modules/directives/src/main/scala/scala/build/preprocessing/directives/RequireScope.scala

@@ -16,7 +16,7 @@ import scala.cli.commands.SpecificationLevel
   "//> using target.scope _scope_",
   "`//> using target.scope `_scope_"
 )
-@DirectiveLevel(SpecificationLevel.RESTRICTED)
+@DirectiveLevel(SpecificationLevel.EXPERIMENTAL)
 final case class RequireScope(
   scope: Option[Positioned[String]] = None
 ) extends HasBuildRequirements {

modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala

@@ -489,7 +489,9 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
     )
     val commands = scalaCli.commands
     val restrictedCommands =
-      commands.iterator.collect { case s: ScalaCommand[_] if !s.isRestricted => s }.toSeq
+      commands.iterator.collect {
+        case s: ScalaCommand[_] if !s.isRestricted && !s.isExperimental => s
+      }.toSeq
     val allArgs       = commands.flatMap(actualHelp(_).args)
     val nameFormatter = scalaCli.actualDefaultCommand.nameFormatter
 

modules/integration/src/test/scala/scala/cli/integration/RunScalaPyTestDefinitions.scala

@@ -108,7 +108,7 @@ trait RunScalaPyTestDefinitions { _: RunTestDefinitions =>
     inputs.fromRoot { root =>
 
       // Script dir shouldn't be added to PYTHONPATH if PYTHONSAFEPATH is non-empty
-      val errorRes = os.proc(TestUtil.cli, "run", extraOptions, nativeOpt, "src")
+      val errorRes = os.proc(TestUtil.cli, "--power", "run", extraOptions, nativeOpt, "src")
         .call(
           cwd = root,
           env = Map("PYTHONSAFEPATH" -> "foo"),
@@ -119,7 +119,7 @@ trait RunScalaPyTestDefinitions { _: RunTestDefinitions =>
       val errorOutput = errorRes.out.text()
       expect(errorOutput.contains("No module named 'helpers'"))
 
-      val res = os.proc(TestUtil.cli, "run", extraOptions, nativeOpt, "src")
+      val res = os.proc(TestUtil.cli, "--power", "run", extraOptions, nativeOpt, "src")
         .call(cwd = root)
       val output = res.out.trim()
       if (native)