Bump clikt to 5.0.3 (#947)

This bumps Clikt from version 3 to version 5, which, among other things, improves
the help text formatting with colors.

Also: 
* Add `--version` flag to pkldoc, pkl-codegen-java, pkl-codegen-kotlin
* Add help text to pkldoc, pkl-codegen-java, pkl-codegen-kotlin

pkl-commons-cli/gradle.lockfile

@@ -1,9 +1,28 @@
 # This is a Gradle generated file for dependency locking.
 # Manual edits can break the build and are not advised.
 # This file is expected to be part of source control.
-com.github.ajalt.clikt:clikt-jvm:3.5.4=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
-com.github.ajalt.clikt:clikt:3.5.4=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.clikt:clikt-core-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.clikt:clikt-core:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.clikt:clikt-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.clikt:clikt-markdown-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.clikt:clikt-markdown:5.0.3=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.clikt:clikt:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.colormath:colormath-jvm:3.6.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.colormath:colormath:3.6.0=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-core-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-core:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-ffm-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-ffm:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-graal-ffi-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-graal-ffi:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-jna-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm-jna:3.0.1=runtimeClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-markdown-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+com.github.ajalt.mordant:mordant-markdown:3.0.1=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+com.github.ajalt.mordant:mordant:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 net.bytebuddy:byte-buddy:1.15.11=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
+net.java.dev.jna:jna:5.14.0=runtimeClasspath,testRuntimeClasspath
 org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata,testJdk17CompileClasspath,testJdk17ImplementationDependenciesMetadata,testRuntimeOnlyDependenciesMetadata
 org.assertj:assertj-core:3.27.3=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.graalvm.polyglot:polyglot:24.1.2=runtimeClasspath,testRuntimeClasspath
@@ -22,18 +41,19 @@ org.jetbrains.kotlin:kotlin-daemon-client:2.0.21=kotlinBuildToolsApiClasspath
 org.jetbrains.kotlin:kotlin-daemon-embeddable:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinKlibCommonizerClasspath
 org.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.0.21=kotlinKlibCommonizerClasspath
 org.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration
-org.jetbrains.kotlin:kotlin-reflect:1.6.10=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-reflect:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinKlibCommonizerClasspath
 org.jetbrains.kotlin:kotlin-script-runtime:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17,kotlinKlibCommonizerClasspath
 org.jetbrains.kotlin:kotlin-scripting-common:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17
 org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17
 org.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17
 org.jetbrains.kotlin:kotlin-scripting-jvm:2.0.21=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17
-org.jetbrains.kotlin:kotlin-stdlib-common:2.0.21=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.jetbrains.kotlin:kotlin-stdlib-jdk7:2.0.21=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.jetbrains.kotlin:kotlin-stdlib-jdk8:2.0.21=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.jetbrains.kotlin:kotlin-stdlib:2.0.21=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17,kotlinKlibCommonizerClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.6.4=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinKlibCommonizerClasspath
 org.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinCompilerPluginClasspathTestJdk17,kotlinKlibCommonizerClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath
+org.jetbrains:markdown-jvm:0.7.3=runtimeClasspath,testRuntimeClasspath
+org.jetbrains:markdown:0.7.3=implementationDependenciesMetadata,runtimeClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
 org.junit.jupiter:junit-jupiter-api:5.11.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath,testRuntimeOnlyDependenciesMetadata
 org.junit.jupiter:junit-jupiter-api:5.8.2=testJdk17CompileClasspath,testJdk17ImplementationDependenciesMetadata,testJdk17RuntimeClasspath
 org.junit.jupiter:junit-jupiter-engine:5.11.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath,testRuntimeOnlyDependenciesMetadata

pkl-commons-cli/pkl-commons-cli.gradle.kts

@@ -21,11 +21,8 @@ plugins {
 
 dependencies {
   api(projects.pklCore)
-  api(libs.clikt) {
-    // force clikt to use our version of the kotlin stdlib
-    exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib-jdk8")
-    exclude(group = "org.jetbrains.kotlin", module = "kotlin-reflect")
-  }
+  api(libs.clikt)
+  implementation(libs.cliktMarkdown)
 
   implementation(projects.pklCommons)
   testImplementation(projects.pklCommonsTest)

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseCommand.kt

@@ -16,9 +16,15 @@
 package org.pkl.commons.cli.commands
 
 import com.github.ajalt.clikt.core.CliktCommand
+import com.github.ajalt.clikt.core.Context
 import com.github.ajalt.clikt.parameters.groups.provideDelegate
 
-abstract class BaseCommand(name: String, helpLink: String, help: String = "") :
-  CliktCommand(name = name, help = help, epilog = "For more information, visit $helpLink") {
+abstract class BaseCommand(name: String, private val helpLink: String) : CliktCommand(name = name) {
+  abstract val helpString: String
+
+  override fun help(context: Context) = helpString
+
+  final override fun helpEpilog(context: Context) = "For more information, visit $helpLink"
+
   val baseOptions: BaseOptions by BaseOptions()
 }

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseOptions.kt

@@ -103,7 +103,7 @@ class BaseOptions : OptionGroup() {
         names = arrayOf("--allowed-modules"),
         help = "URI patterns that determine which modules can be loaded and evaluated.",
       )
-      .convert("<pattern1,pattern2>") { Pattern.compile(it) }
+      .convert("pattern1,pattern2") { Pattern.compile(it) }
       .splitAll()
 
   val allowedResources: List<Pattern> by
@@ -111,7 +111,7 @@ class BaseOptions : OptionGroup() {
         names = arrayOf("--allowed-resources"),
         help = "URI patterns that determine which external resources can be read.",
       )
-      .convert("<pattern1,pattern2>") { Pattern.compile(it) }
+      .convert("pattern1,pattern2") { Pattern.compile(it) }
       .splitAll()
 
   val rootDir: Path? by
@@ -140,7 +140,7 @@ class BaseOptions : OptionGroup() {
   val properties: Map<String, String> by
     option(
         names = arrayOf("-p", "--property"),
-        metavar = "<name=value>",
+        metavar = "name=value",
         help = "External property to set (repeatable).",
       )
       .associateProps()
@@ -148,7 +148,7 @@ class BaseOptions : OptionGroup() {
   val color: Color by
     option(
         names = arrayOf("--color"),
-        metavar = "<when>",
+        metavar = "when",
         help =
           "Whether to format messages in ANSI color. Possible values of <when> are 'never', 'auto', and 'always'.",
       )
@@ -171,7 +171,7 @@ class BaseOptions : OptionGroup() {
   val envVars: Map<String, String> by
     option(
         names = arrayOf("-e", "--env-var"),
-        metavar = "<name=value>",
+        metavar = "name=value",
         help = "Environment variable to set (repeatable).",
       )
       .associate()
@@ -179,7 +179,7 @@ class BaseOptions : OptionGroup() {
   val modulePath: List<Path> by
     option(
         names = arrayOf("--module-path"),
-        metavar = "<path1${File.pathSeparator}path2>",
+        metavar = "path1${File.pathSeparator}path2",
         help =
           "Directories, ZIP archives, or JAR archives to search when resolving `modulepath:` URIs.",
       )
@@ -194,7 +194,7 @@ class BaseOptions : OptionGroup() {
   val timeout: Duration? by
     option(
         names = arrayOf("-t", "--timeout"),
-        metavar = "<number>",
+        metavar = "number",
         help = "Duration, in seconds, after which evaluation of a source module will be timed out.",
       )
       .single()
@@ -204,7 +204,7 @@ class BaseOptions : OptionGroup() {
   val caCertificates: List<Path> by
     option(
         names = arrayOf("--ca-certificates"),
-        metavar = "<path>",
+        metavar = "path",
         help = "Only trust CA certificates from the provided file(s).",
       )
       .path()
@@ -213,7 +213,7 @@ class BaseOptions : OptionGroup() {
   val proxy: URI? by
     option(
         names = arrayOf("--http-proxy"),
-        metavar = "<address>",
+        metavar = "address",
         help = "Proxy to use for HTTP(S) connections.",
       )
       .single()
@@ -229,7 +229,7 @@ class BaseOptions : OptionGroup() {
   val noProxy: List<String>? by
     option(
         names = arrayOf("--http-no-proxy"),
-        metavar = "<pattern1,pattern2>",
+        metavar = "pattern1,pattern",
         help = "Hostnames that should not be connected to via a proxy.",
       )
       .single()
@@ -238,7 +238,7 @@ class BaseOptions : OptionGroup() {
   val externalModuleReaders: Map<String, ExternalReader> by
     option(
         names = arrayOf("--external-module-reader"),
-        metavar = "<scheme>='<executable>[ <arguments>]'",
+        metavar = "<scheme>='<executable> [<arguments>]'",
         help = "External reader registrations for module URI schemes",
       )
       .parseExternalReader("=")
@@ -248,7 +248,7 @@ class BaseOptions : OptionGroup() {
   val externalResourceReaders: Map<String, ExternalReader> by
     option(
         names = arrayOf("--external-resource-reader"),
-        metavar = "<scheme>='<executable>[ <arguments>]'",
+        metavar = "<scheme>='<executable> [<arguments>]'",
         help = "External reader registrations for resource URI schemes",
       )
       .parseExternalReader("=")

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/ModulesCommand.kt

@@ -21,10 +21,10 @@ import com.github.ajalt.clikt.parameters.arguments.multiple
 import com.github.ajalt.clikt.parameters.groups.provideDelegate
 import java.net.URI
 
-abstract class ModulesCommand(name: String, helpLink: String, help: String = "") :
-  BaseCommand(name = name, help = help, helpLink = helpLink) {
+abstract class ModulesCommand(name: String, helpLink: String) :
+  BaseCommand(name = name, helpLink = helpLink) {
   open val modules: List<URI> by
-    argument(name = "<modules>", help = "Module paths or URIs to evaluate.")
+    argument(name = "modules", help = "Module paths or URIs to evaluate.")
       .convert { BaseOptions.parseModuleName(it) }
       .multiple(required = true)
 

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/OptionExtensions.kt

@@ -43,7 +43,7 @@ fun <EachT : Any, ValueT> NullableOption<EachT, ValueT>.splitAll(
     transformEach = { it },
     transformAll = { it.flatten().ifEmpty { default } },
     validator = {},
-    nvalues = 1,
-    valueSplit = Regex.fromLiteral(separator),
+    nvalues = 1..1,
+    valueSplit = { it.split(Regex.fromLiteral(separator)) },
   )
 }

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/ProjectOptions.kt

@@ -29,7 +29,7 @@ class ProjectOptions : OptionGroup() {
   val projectDir: Path? by
     option(
         names = arrayOf("--project-dir"),
-        metavar = "<path>",
+        metavar = "path",
         help =
           "The project directory to use for this command. By default, searches up from the working directory for a PklProject file.",
       )

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/TestOptions.kt

@@ -26,7 +26,7 @@ class TestOptions : OptionGroup() {
   private val junitReportDir: Path? by
     option(
         names = arrayOf("--junit-reports"),
-        metavar = "<dir>",
+        metavar = "dir",
         help = "Directory where to store JUnit reports.",
       )
       .path()

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/extensions.kt

@@ -0,0 +1,36 @@
+/*
+ * Copyright © 2024-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.commons.cli.commands
+
+import com.github.ajalt.clikt.core.BaseCliktCommand
+import com.github.ajalt.clikt.core.context
+import com.github.ajalt.clikt.core.installMordantMarkdown
+import com.github.ajalt.clikt.core.terminal
+import com.github.ajalt.clikt.parameters.options.versionOption
+import com.github.ajalt.mordant.rendering.TextStyle
+import com.github.ajalt.mordant.rendering.Theme
+import com.github.ajalt.mordant.terminal.Terminal
+import org.pkl.core.Release
+
+private val theme = Theme { styles["markdown.code.span"] = TextStyle(bold = true) }
+
+fun <T : BaseCliktCommand<T>> T.installCommonOptions() {
+  installMordantMarkdown()
+
+  versionOption(Release.current().versionInfo, names = setOf("-v", "--version"), message = { it })
+
+  context { terminal = Terminal(theme = theme) }
+}

pkl-commons-cli/src/test/kotlin/org/pkl/commons/cli/BaseCommandTest.kt

@@ -17,6 +17,7 @@ package org.pkl.commons.cli
 
 import com.github.ajalt.clikt.core.BadParameterValue
 import com.github.ajalt.clikt.core.PrintHelpMessage
+import com.github.ajalt.clikt.core.parse
 import java.io.File
 import java.nio.file.Path
 import java.util.regex.Pattern
@@ -31,12 +32,14 @@ class BaseCommandTest {
   private val cmd =
     object : BaseCommand("test", "") {
       override fun run() = Unit
+
+      override val helpString: String = ""
     }
 
   @Test
   fun `invalid timeout`() {
     val e = assertThrows<BadParameterValue> { cmd.parse(arrayOf("--timeout", "abc")) }
-    assertThat(e).hasMessageContaining("timeout")
+    assertThat(e.message).isEqualTo("abc is not a valid integer")
   }
 
   @Test

pkl-commons-cli/src/test/kotlin/org/pkl/commons/cli/CliCommandTest.kt

@@ -15,6 +15,7 @@
  */
 package org.pkl.commons.cli
 
+import com.github.ajalt.clikt.core.parse
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
 import org.pkl.commons.cli.commands.BaseCommand
@@ -32,6 +33,8 @@ class CliCommandTest {
   private val cmd =
     object : BaseCommand("test", "") {
       override fun run() = Unit
+
+      override val helpString: String = ""
     }
 
   @Test