Add test coverage

Author: HT154

buildSrc/src/main/kotlin/PklFormatterSpotless.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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.
@@ -47,20 +47,11 @@ class PklFormatterFunc(@Transient private val configuration: Configuration) :
 
   private val formatterClass by lazy { classLoader.loadClass("org.pkl.formatter.Formatter") }
 
-  private val grammarVersionClass by lazy {
-    classLoader.loadClass("org.pkl.formatter.GrammarVersion")
-  }
-
-  private val grammarVersionLatestMethod by lazy { grammarVersionClass.getMethod("latest") }
-
-  private val formatMethod by lazy {
-    formatterClass.getMethod("format", String::class.java, grammarVersionClass)
-  }
+  private val formatMethod by lazy { formatterClass.getMethod("format", String::class.java) }
 
   private val formatterInstance by lazy { formatterClass.getConstructor().newInstance() }
 
   override fun apply(input: String): String {
-    val latestGrammarVersion = grammarVersionLatestMethod(null)
-    return formatMethod(formatterInstance, input, latestGrammarVersion) as String
+    return formatMethod(formatterInstance, input) as String
   }
 }

docs/modules/pkl-cli/pages/index.adoc

@@ -974,7 +974,7 @@ False values: `false`, `f`, `0`, `no`, `n`, `off`
 |`Int8`, `Int16`, `Int32`, `UInt`, `UInt8`, `UInt16`, `UInt32`
 |Behaves like `Int` but enforces the type's bounds check
 
-|xref:language-reference:index.adoc#union-types[Union] of xref:language-reference:index.adoc#string-literal-types[string literals]
+|xref:language-reference:index.adoc#union-types[Union] of xref:language-reference:index.adoc#string-literal-types[string literals] or a xref:language-reference:index.adoc#type-aliases[type alias] to one
 |Behaves like `String` but only admits specific values.
 
 |`List<Element>`, `Set<Element>`
@@ -1033,11 +1033,11 @@ parent: `my-tool` // <1>
 
 // Regular module code...
 ----
-<1> Optional; asserts that this is a subcommand of `my-tool` and simplifies accessing parent command properties and options
+<1> Optional; asserts that this is a subcommand of `my-tool` and simplifies accessing properties and options of the parent command
 
 === Testing Commands
 
-Command module are normal Pkl modules, so they may be imported and used like any other module.
+Command modules are normal Pkl modules, so they may be imported and used like any other module.
 This is particularly helpful when testing commands, as the command's `options` and `parent` properties can be populated by test code.
 
 Testing the above command and subcommand might look like this:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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.
@@ -37,6 +37,7 @@ import org.pkl.core.CommandSpec
 import org.pkl.core.EvaluatorBuilder
 import org.pkl.core.FileOutput
 import org.pkl.core.ModuleSource.uri
+import org.pkl.core.PklException
 import org.pkl.core.util.IoUtils
 
 class CliCommandRunner
@@ -64,14 +65,20 @@ constructor(
     val evaluator = builder.build()
     evaluator.use {
       evaluator.evaluateCommand(uri(normalizedSourceModule)) { spec ->
-        val root = SynthesizedRunCommand(spec, this, options.sourceModules.first().toString())
-        root.subcommands(
-          CompletionCommand(
-            name = "shell-completion",
-            help = "Generate a completion script for the given shell",
+        try {
+          val root = SynthesizedRunCommand(spec, this, options.sourceModules.first().toString())
+          root.subcommands(
+            CompletionCommand(
+              name = "shell-completion",
+              help = "Generate a completion script for the given shell",
+            )
           )
-        )
-        root.main(args)
+          root.parse(args)
+        } catch (e: PklException) {
+          throw e
+        } catch (e: Exception) {
+          throw e.message?.let { PklException(it, e) } ?: PklException(e)
+        }
       }
     }
   }
@@ -109,7 +116,6 @@ constructor(
       checkPathSpec(pathSpec)
       val resolvedPath = outputDir.resolve(pathSpec).normalize()
       val realPath = if (resolvedPath.exists()) resolvedPath.toRealPath() else resolvedPath
-      // FIXME: should we validate against options.normalizedRootDir?
       val previousOutput = writtenFiles[realPath]
       if (previousOutput != null) {
         throw CliException(
@@ -149,39 +155,6 @@ constructor(
 
     override fun help(context: Context): String = spec.description ?: ""
 
-    override fun run() {
-      if (currentContext.invokedSubcommand is CompletionCommand) return
-
-      val opts =
-        registeredOptions()
-          .mapNotNull {
-            val opt = it as? OptionWithValues<*, *, *> ?: return@mapNotNull null
-            return@mapNotNull if (
-              it.names.contains("--help") ||
-                (opt.value as? List<*>)?.isEmpty() ?: false ||
-                (opt.value as? Map<*, *>)?.isEmpty() ?: false
-            )
-              null
-            else it.names.first().trimStart('-') to opt.value
-          }
-          .toMap() +
-          registeredArguments()
-            .mapNotNull { it as? ArgumentDelegate<*> }
-            .associateBy({ it.name }, { it.value })
-
-      val state = spec.apply.apply(opts, currentContext.obj as CommandSpec.State?)
-      currentContext.obj = state
-
-      if (currentContext.invokedSubcommand != null) return
-      if (spec.subcommands.isNotEmpty() && spec.noOp) {
-        throw PrintHelpMessage(currentContext, true, 1)
-      }
-
-      val result = state.evaluate()
-      runner.writeOutput(result.outputBytes)
-      runner.writeMultipleFileOutput(result.outputFiles)
-    }
-
     private fun registerFlag(flag: CommandSpec.Flag) {
       val names =
         if (flag.shortName == null) arrayOf("--${flag.name}")
@@ -204,12 +177,7 @@ constructor(
                   else convertValue(it.second, type.valueType, "value"),
                 )
               }
-              .multiple(
-                default =
-                  (flag.defaultValue?.let { default ->
-                    (default as Map<*, *>).entries.toList().map { Pair(it.key!!, it.value!!) }
-                  } ?: emptyList())
-              )
+              .multiple()
               .toMap()
         }
       )
@@ -227,6 +195,39 @@ constructor(
         }
       )
     }
+
+    override fun run() {
+      if (currentContext.invokedSubcommand is CompletionCommand) return
+
+      val opts =
+        registeredOptions()
+          .mapNotNull {
+            val opt = it as? OptionWithValues<*, *, *> ?: return@mapNotNull null
+            return@mapNotNull if (
+              it.names.contains("--help") ||
+                (opt.value as? List<*>)?.isEmpty() ?: false ||
+                (opt.value as? Map<*, *>)?.isEmpty() ?: false
+            )
+              null
+            else it.names.first().trimStart('-') to opt.value
+          }
+          .toMap() +
+          registeredArguments()
+            .mapNotNull { it as? ArgumentDelegate<*> }
+            .associateBy({ it.name }, { it.value })
+
+      val state = spec.apply.apply(opts, currentContext.obj as CommandSpec.State?)
+      currentContext.obj = state
+
+      if (currentContext.invokedSubcommand != null) return
+      if (spec.subcommands.isNotEmpty() && spec.noOp) {
+        throw PrintHelpMessage(currentContext, true, 1)
+      }
+
+      val result = state.evaluate()
+      runner.writeOutput(result.outputBytes)
+      runner.writeMultipleFileOutput(result.outputFiles)
+    }
   }
 }
 
@@ -244,7 +245,7 @@ private fun <InT> NullableOption<InT, InT>.flag(flag: CommandSpec.Flag) =
           flag.type is CommandSpec.OptionType.Collection ->
             when {
               it.isEmpty() && flag.type.isRequired -> throw MissingOption(option)
-              it.isEmpty() && !flag.type.isRequired -> flag.defaultValue
+              it.isEmpty() && !flag.type.isRequired -> it
               else ->
                 if (
                   (flag.type as CommandSpec.OptionType.Collection).type ==
@@ -253,9 +254,8 @@ private fun <InT> NullableOption<InT, InT>.flag(flag: CommandSpec.Flag) =
                   it.toSet()
                 else it
             }
-          flag.defaultValue != null -> it.lastOrNull() ?: flag.defaultValue
           flag.type.isRequired -> it.lastOrNull() ?: throw MissingOption(option)
-          else -> it
+          else -> it.lastOrNull()
         }
       }
     else -> throw CliException("Unexpected collection flag value type $valueType")
@@ -300,7 +300,15 @@ fun RawOption.convert(
         } else it
       return@convert parseFunction.parse(parseArg)
     }
-  else convert { convertValue(it, type, null) }.copy(metavarGetter = { type.toString() })
+  else
+    convert {
+        convertValue(
+          it,
+          if (type is CommandSpec.OptionType.Collection) type.valueType else type,
+          null,
+        )
+      }
+      .copy(metavarGetter = { type.toString() })
 
 @Suppress("DuplicatedCode")
 fun RawArgument.convert(
@@ -321,7 +329,14 @@ fun RawArgument.convert(
         } else it
       return@convert parseFunction.parse(parseArg)
     }
-  else convert { convertValue(it, type, null) }
+  else
+    convert {
+      convertValue(
+        it,
+        if (type is CommandSpec.OptionType.Collection) type.valueType else type,
+        null,
+      )
+    }
 
 // helpers for converting primitives/enums
 
@@ -342,12 +357,12 @@ private val convertValue:
       is CommandSpec.OptionType.Primitive ->
         when (type.type) {
           CommandSpec.OptionType.Primitive.Type.NUMBER ->
-            value.toIntOrNull() ?: value.toDoubleOrNull()
+            value.toLongOrNull() ?: value.toDoubleOrNull()
           CommandSpec.OptionType.Primitive.Type.FLOAT -> value.toDoubleOrNull()
           CommandSpec.OptionType.Primitive.Type.INT -> value.toLongOrNull(this, type)
           // ranges based on org.pkl.core.stdlib.math.MathNodes
           CommandSpec.OptionType.Primitive.Type.INT8 ->
-            value.toLongOrNull(this, type, Byte.MIN_VALUE.toLong()..<Byte.MAX_VALUE)
+            value.toLongOrNull(this, type, Byte.MIN_VALUE.toLong()..Byte.MAX_VALUE)
           CommandSpec.OptionType.Primitive.Type.INT16 ->
             value.toLongOrNull(this, type, Short.MIN_VALUE.toLong()..Short.MAX_VALUE)
           CommandSpec.OptionType.Primitive.Type.INT32 ->
@@ -381,6 +396,6 @@ private val convertValue:
       is CommandSpec.OptionType.Enum ->
         if (type.choices.contains(value)) value
         else fail("invalid choice: $value. (choose from ${type.choices.joinToString()})")
-      else -> fail("unsupported ${mapPosition?.let { "map $it " }}type $type")
+      else -> fail("unsupported ${mapPosition?.let { "map $it " } ?: ""}type $type")
     } ?: fail("$value is not a valid $type")
   }

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

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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.