Merge pull request #1135 from Gedochao/improve-fmt

Tweak the `fmt` command

Author: Gedochao

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

@@ -9,9 +9,18 @@ final case class FmtOptions(
     shared: SharedOptions = SharedOptions(),
 
   @Group("Format")
-  @HelpMessage("Check that sources are well formatted")
+  @HelpMessage("Check if sources are well formatted")
     check: Boolean = false,
 
+  @Group("Format")
+  @HelpMessage("Use project filters defined in the configuration (turned on by default)")
+    respectProjectFilters: Boolean = true,
+
+  @Group("Format")
+  @HelpMessage("Show help for scalafmt. This is an alias for --scalafmt-arg -help")
+  @Name("fmtHelp")
+    scalafmtHelp: Boolean = false,
+
   @Group("Format")
   @Hidden
     osArchSuffix: Option[String] = None,
@@ -30,7 +39,6 @@ final case class FmtOptions(
 
   @Group("Format")
   @Name("F")
-  @Hidden
     scalafmtArg: List[String] = Nil,
 
   @Group("Format")

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

@@ -4,18 +4,17 @@ import caseapp._
 
 import scala.build.interactive.InteractiveFileOps
 import scala.build.internal.{Constants, CustomCodeWrapper, FetchExternalBinary, Runner}
-import scala.build.options.BuildOptions
 import scala.build.{CrossSources, Inputs, Logger, Sources}
 import scala.cli.CurrentParams
+import scala.cli.commands.util.FmtOptionsUtil._
 import scala.cli.commands.util.SharedOptionsUtil._
 import scala.cli.commands.util.VerbosityOptionsUtil._
-import scala.util.Properties
 import scala.util.control.NonFatal
 
 object Fmt extends ScalaCommand[FmtOptions] {
-  override def group                              = "Main"
-  override def sharedOptions(options: FmtOptions) = Some(options.shared)
-  override def names = List(
+  override def group: String                                             = "Main"
+  override def sharedOptions(options: FmtOptions): Option[SharedOptions] = Some(options.shared)
+  override def names: List[List[String]] = List(
     List("fmt"),
     List("format"),
     List("scalafmt")
@@ -43,7 +42,7 @@ object Fmt extends ScalaCommand[FmtOptions] {
   def readVersionFromFile(workspace: os.Path, logger: Logger): (Option[String], Boolean) = {
     case class ScalafmtVersionConfig(version: String = "")
     object ScalafmtVersionConfig {
-      lazy val default = ScalafmtVersionConfig()
+      lazy val default: ScalafmtVersionConfig = ScalafmtVersionConfig()
       implicit lazy val surface: metaconfig.generic.Surface[ScalafmtVersionConfig] =
         metaconfig.generic.deriveSurface[ScalafmtVersionConfig]
       implicit lazy val decoder: metaconfig.ConfDecoder[ScalafmtVersionConfig] =
@@ -77,26 +76,6 @@ object Fmt extends ScalaCommand[FmtOptions] {
     (versionMaybe, pathMaybe.isDefined)
   }
 
-  private implicit class FmtOptionsOps(v: FmtOptions) {
-    import v._
-    def binaryUrl(version: String): (String, Boolean) = {
-      val osArchSuffix0 = osArchSuffix.map(_.trim).filter(_.nonEmpty)
-        .getOrElse(FetchExternalBinary.platformSuffix())
-      val tag0           = scalafmtTag.getOrElse("v" + version)
-      val gitHubOrgName0 = scalafmtGithubOrgName.getOrElse("alexarchambault/scalafmt-native-image")
-      val extension0     = if (Properties.isWin) ".zip" else ".gz"
-      val url =
-        s"https://github.com/$gitHubOrgName0/releases/download/$tag0/scalafmt-$osArchSuffix0$extension0"
-      (url, !tag0.startsWith("v"))
-    }
-
-    def buildOptions: BuildOptions =
-      shared.buildOptions(ignoreErrors = false)
-
-    def scalafmtCliOptions: List[String] =
-      scalafmtArg ::: (if (check) List("--check") else Nil)
-  }
-
   def run(options: FmtOptions, args: RemainingArgs): Unit = {
     CurrentParams.verbosity = options.shared.logging.verbosity
     val interactive = options.shared.logging.verbosityOptions.interactiveInstance()

modules/cli/src/main/scala/scala/cli/commands/util/FmtOptionsUtil.scala

@@ -0,0 +1,33 @@
+package scala.cli.commands.util
+import scala.build.internal.FetchExternalBinary
+import scala.build.options.BuildOptions
+import scala.cli.commands.FmtOptions
+import scala.cli.commands.util.SharedOptionsUtil._
+import scala.util.Properties
+
+object FmtOptionsUtil {
+  implicit class FmtOptionsOps(v: FmtOptions) {
+    import v._
+    def binaryUrl(version: String): (String, Boolean) = {
+      val osArchSuffix0 = osArchSuffix.map(_.trim).filter(_.nonEmpty)
+        .getOrElse(FetchExternalBinary.platformSuffix())
+      val tag0           = scalafmtTag.getOrElse("v" + version)
+      val gitHubOrgName0 = scalafmtGithubOrgName.getOrElse("alexarchambault/scalafmt-native-image")
+      val extension0     = if (Properties.isWin) ".zip" else ".gz"
+      val url =
+        s"https://github.com/$gitHubOrgName0/releases/download/$tag0/scalafmt-$osArchSuffix0$extension0"
+      (url, !tag0.startsWith("v"))
+    }
+
+    def buildOptions: BuildOptions = shared.buildOptions()
+
+    def scalafmtCliOptions: List[String] =
+      scalafmtArg :::
+        (if (check && !scalafmtArg.contains("--check")) List("--check") else Nil) :::
+        (if (scalafmtHelp && !scalafmtArg.exists(Set("-h", "-help", "--help"))) List("--help")
+         else Nil) :::
+        (if (respectProjectFilters && !scalafmtArg.contains("--respect-project-filters"))
+           List("--respect-project-filters")
+         else Nil)
+  }
+}

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

@@ -4,14 +4,16 @@ import com.eed3si9n.expecty.Expecty.expect
 
 class FmtTests extends munit.FunSuite {
 
-  val simpleInputsUnformattedContent =
+  val emptyInputs: TestInputs = TestInputs(Seq(os.rel / ".placeholder" -> ""))
+
+  val simpleInputsUnformattedContent: String =
     """package foo
       |
       |    object Foo       extends       java.lang.Object  {
       |                     def           get()             = 2
       | }
       |""".stripMargin
-  val simpleInputs = TestInputs(
+  val simpleInputs: TestInputs = TestInputs(
     Seq(
       os.rel / ".scalafmt.conf" ->
         s"""|version = "${Constants.defaultScalafmtVersion}"
@@ -20,7 +22,7 @@ class FmtTests extends munit.FunSuite {
       os.rel / "Foo.scala" -> simpleInputsUnformattedContent
     )
   )
-  val expectedSimpleInputsFormattedContent = noCrLf {
+  val expectedSimpleInputsFormattedContent: String = noCrLf {
     """package foo
       |
       |object Foo extends java.lang.Object {
@@ -29,6 +31,19 @@ class FmtTests extends munit.FunSuite {
       |""".stripMargin
   }
 
+  val simpleInputsWithFilter: TestInputs = TestInputs(
+    Seq(
+      os.rel / ".scalafmt.conf" ->
+        s"""|version = "${Constants.defaultScalafmtVersion}"
+            |runner.dialect = scala213
+            |project.excludePaths = [ "glob:**/should/not/format/**.scala" ]
+            |""".stripMargin,
+      os.rel / "Foo.scala"                 -> expectedSimpleInputsFormattedContent,
+      os.rel / "scripts" / "SomeScript.sc" -> "println()\n",
+      os.rel / "should" / "not" / "format" / "ShouldNotFormat.scala" -> simpleInputsUnformattedContent
+    )
+  )
+
   private def noCrLf(input: String): String =
     input.replaceAll("\r\n", "\n")
 
@@ -57,4 +72,28 @@ class FmtTests extends munit.FunSuite {
     }
   }
 
+  test("filter correctly with --check") {
+    simpleInputsWithFilter.fromRoot { root =>
+      val out      = os.proc(TestUtil.cli, "fmt", ".", "--check").call(cwd = root).out.text.trim
+      val outLines = out.linesIterator.toSeq
+      expect(outLines.length == 2)
+      expect(outLines.head == "Looking for unformatted files...")
+      expect(outLines.last == "All files are formatted with scalafmt :)")
+    }
+  }
+
+  test("--scalafmt-help") {
+    emptyInputs.fromRoot { root =>
+      val out1 = os.proc(TestUtil.cli, "fmt", "--scalafmt-help").call(cwd = root).out.text.trim
+      val out2 = os.proc(TestUtil.cli, "fmt", "-F", "--help").call(cwd = root).out.text.trim
+      expect(out1.nonEmpty)
+      expect(out1 == out2)
+      val outLines       = out1.linesIterator.toSeq
+      val outVersionLine = outLines.head
+      expect(outVersionLine == s"scalafmt ${Constants.defaultScalafmtVersion}")
+      val outUsageLine = outLines.drop(1).head
+      expect(outUsageLine == "Usage: scalafmt [options] [<file>...]")
+    }
+  }
+
 }

website/docs/commands/fmt.md

@@ -3,6 +3,8 @@ title: Format
 sidebar_position: 15
 ---
 
+import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+
 Scala CLI supports formatting your code using [Scalafmt](https://scalameta.org/scalafmt/):
 
 ```bash
@@ -23,18 +25,112 @@ scala-cli fmt --check
 Scala CLI also supports dialects that are passed to the formatter.
 This value is only used if there is no `.scalafmt.conf` file.
 However, if it exists, then all configuration should be placed there.
-For a list of all possible values, consult the [official Scala Dialects documentation](https://scalameta.org/scalafmt/docs/configuration.html#scala-dialects):
+For a list of all possible values, consult
+the [official Scala Dialects documentation](https://scalameta.org/scalafmt/docs/configuration.html#scala-dialects):
 
 ```bash
 scala-cli fmt --dialect scala212
 ```
 
 ### Scalafmt version
 
-At this time, Scala CLI reads a `scalafmt` version from `.scalafmt.conf` files. If the version is missing, Scala CLI throws an error, stating that users should declare an explicit Scalafmt version. Since Scalafmt `3.5.0`, this parameter is mandatory.
+At this time, Scala CLI reads a `scalafmt` version from `.scalafmt.conf` files. If the version is missing, Scala CLI
+throws an error, stating that users should declare an explicit Scalafmt version. Since Scalafmt `3.5.0`, this parameter
+is mandatory.
 
-To configure the Scalafmt version, add the following to `.scalafmt.conf`. For example, to set the version to `3.5.0`, add the following line:
+To configure the Scalafmt version, add the following to `.scalafmt.conf`. For example, to set the version to `3.5.0`,
+add the following line:
 
 ```
 version = "3.5.0"
 ```
+
+### Scalafmt options
+
+It is possible to pass native `scalafmt` options with the `-F` (short for `--scalafmt-arg`), for example:
+
+<ChainedSnippets>
+
+```bash
+scala-cli fmt -F --version
+```
+
+```text
+scalafmt 3.5.2
+```
+
+</ChainedSnippets>
+
+For the available options please refer to `scalafmt` help, which can be viewed with the `--scalafmt-help` option (which
+is just an alias for `-F --help`):
+
+<ChainedSnippets>
+
+```bash
+scala-cli fmt --scalafmt-help
+```
+
+```text
+scalafmt 3.5.2
+Usage: scalafmt [options] [<file>...]
+
+  -h, --help               prints this usage text
+  -v, --version            print version 
+(...)
+```
+
+</ChainedSnippets>
+
+### Excluding sources
+
+Because of the way Scala CLI invokes `scalafmt` under the hood, sources are always being passed to it explicitly. This
+in turn means that regardless of how the sources were passed, `scalafmt` exclusion paths (the `project.excludePaths`)
+would be ignored. In order to prevent that from happening, the `--respect-project-filters` option is set to `true` by
+default.
+
+```text title=.scalafmt.conf
+version = 3.5.2
+runner.dialect = scala3
+project {
+  includePaths = [
+    "glob:**.scala",
+    "regex:.*\\.sc"
+  ]
+  excludePaths = [
+    "glob:**/should/not/format/**.scala"
+  ]
+}
+```
+
+<ChainedSnippets>
+
+```bash
+scala-cli fmt . --check
+```
+
+```text
+All files are formatted with scalafmt :)
+```
+
+</ChainedSnippets>
+
+You can explicitly set it to false if you want to disregard any filters configured in the `project.excludePaths` setting
+in your `.scalafmt.conf` for any reason.
+
+<ChainedSnippets>
+
+```bash
+scala-cli fmt . --check --respect-project-filters=false
+```
+
+```text
+--- a/.../should/not/format/ShouldNotFormat.scala
++++ b/.../should/not/format/ShouldNotFormat.scala
+@@ -1,3 +1,3 @@
+ class ShouldNotFormat {
+-                       println()
++  println()
+ }
+```
+
+</ChainedSnippets>

website/docs/reference/cli-options.md

@@ -456,7 +456,17 @@ Available in commands:
 
 #### `--check`
 
-Check that sources are well formatted
+Check if sources are well formatted
+
+#### `--respect-project-filters`
+
+Use project filters defined in the configuration (turned on by default)
+
+#### `--scalafmt-help`
+
+Aliases: `--fmt-help`
+
+Show help for scalafmt. This is an alias for --scalafmt-arg -help
 
 #### `--os-arch-suffix`