Add grammar compatibility option to the formatter (#1249)

pkl-cli/src/main/kotlin/org/pkl/cli/CliFormatterApply.kt

@@ -21,12 +21,14 @@ import java.nio.file.Path
 import kotlin.io.path.writeText
 import org.pkl.commons.cli.CliBaseOptions
 import org.pkl.commons.cli.CliException
+import org.pkl.formatter.GrammarVersion
 
 class CliFormatterApply(
   cliBaseOptions: CliBaseOptions,
   paths: List<Path>,
+  grammarVersion: GrammarVersion,
   private val silent: Boolean,
-) : CliFormatterCommand(cliBaseOptions, paths) {
+) : CliFormatterCommand(cliBaseOptions, paths, grammarVersion) {
 
   override fun doRun() {
     var status = 0

pkl-cli/src/main/kotlin/org/pkl/cli/CliFormatterCheck.kt

@@ -19,9 +19,13 @@ import java.nio.file.Files
 import java.nio.file.Path
 import org.pkl.commons.cli.CliBaseOptions
 import org.pkl.commons.cli.CliException
+import org.pkl.formatter.GrammarVersion
 
-class CliFormatterCheck(cliBaseOptions: CliBaseOptions, paths: List<Path>) :
-  CliFormatterCommand(cliBaseOptions, paths) {
+class CliFormatterCheck(
+  cliBaseOptions: CliBaseOptions,
+  paths: List<Path>,
+  grammarVersion: GrammarVersion,
+) : CliFormatterCommand(cliBaseOptions, paths, grammarVersion) {
 
   override fun doRun() {
     var status = 0

pkl-cli/src/main/kotlin/org/pkl/cli/CliFormatterCommand.kt

@@ -25,6 +25,7 @@ import kotlin.io.path.walk
 import org.pkl.commons.cli.CliBaseOptions
 import org.pkl.commons.cli.CliCommand
 import org.pkl.formatter.Formatter
+import org.pkl.formatter.GrammarVersion
 import org.pkl.parser.GenericParserError
 
 abstract class CliFormatterCommand
@@ -32,11 +33,12 @@ abstract class CliFormatterCommand
 constructor(
   options: CliBaseOptions,
   protected val paths: List<Path>,
+  protected val grammarVersion: GrammarVersion,
   protected val consoleWriter: Writer = System.out.writer(),
 ) : CliCommand(options) {
   protected fun format(file: Path, contents: String): Pair<String, Int> {
     try {
-      return Formatter().format(contents) to 0
+      return Formatter().format(contents, grammarVersion) to 0
     } catch (pe: GenericParserError) {
       consoleWriter.write("Could not format `$file`: $pe")
       consoleWriter.appendLine()

pkl-cli/src/main/kotlin/org/pkl/cli/commands/FormatterCommand.kt

@@ -20,13 +20,17 @@ import com.github.ajalt.clikt.core.NoOpCliktCommand
 import com.github.ajalt.clikt.core.subcommands
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.arguments.multiple
+import com.github.ajalt.clikt.parameters.options.default
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.types.enum
 import com.github.ajalt.clikt.parameters.types.path
 import java.nio.file.Path
 import org.pkl.cli.CliFormatterApply
 import org.pkl.cli.CliFormatterCheck
+import org.pkl.cli.commands.FormatterCheckCommand.Companion.grammarVersionHelp
 import org.pkl.commons.cli.commands.BaseCommand
+import org.pkl.formatter.GrammarVersion
 
 class FormatterCommand : NoOpCliktCommand(name = "format") {
   override fun help(context: Context) = "Run commands related to formatting"
@@ -47,8 +51,25 @@ class FormatterCheckCommand : BaseCommand(name = "check", helpLink = helpLink) {
       .path(mustExist = true, canBeDir = true)
       .multiple()
 
+  val grammarVersion: GrammarVersion by
+    option(names = arrayOf("--grammar-version"), help = grammarVersionHelp)
+      .enum<GrammarVersion> { "${it.version}" }
+      .default(GrammarVersion.latest())
+
   override fun run() {
-    CliFormatterCheck(baseOptions.baseOptions(emptyList()), paths).run()
+    CliFormatterCheck(baseOptions.baseOptions(emptyList()), paths, grammarVersion).run()
+  }
+
+  companion object {
+    internal val grammarVersionHelp =
+      """
+      The grammar compatibility version to use.$NEWLINE
+      ${GrammarVersion.entries.joinToString("$NEWLINE", prefix = "  ") {
+        val default = if (it == GrammarVersion.latest()) " `(default)`" else ""
+        "`${it.version}`: ${it.versionSpan}$default"
+      }}
+      """
+        .trimIndent()
   }
 }
 
@@ -68,7 +89,12 @@ class FormatterApplyCommand : BaseCommand(name = "apply", helpLink = helpLink) {
       )
       .flag()
 
+  val grammarVersion: GrammarVersion by
+    option(names = arrayOf("--grammar-version"), help = grammarVersionHelp)
+      .enum<GrammarVersion> { "${it.version}" }
+      .default(GrammarVersion.latest())
+
   override fun run() {
-    CliFormatterApply(baseOptions.baseOptions(emptyList()), paths, silent).run()
+    CliFormatterApply(baseOptions.baseOptions(emptyList()), paths, grammarVersion, silent).run()
   }
 }

pkl-cli/src/main/kotlin/org/pkl/cli/commands/ProjectCommand.kt

@@ -33,8 +33,6 @@ import org.pkl.commons.cli.commands.BaseCommand
 import org.pkl.commons.cli.commands.TestOptions
 import org.pkl.commons.cli.commands.single
 
-private const val NEWLINE = '\u0085'
-
 class ProjectCommand : NoOpCliktCommand(name = "project") {
   override fun help(context: Context) = "Run commands related to projects"
 

pkl-cli/src/main/kotlin/org/pkl/cli/commands/Utils.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.pkl.cli.commands
+
+internal const val NEWLINE = '\u0085'