Add completion candidates

Author: HT154

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

@@ -1157,9 +1157,16 @@ Like with Pkl's own CLI, <<command-shell-completion, shell completions>> can be
 ./my-tool.pkl shell-completion zsh
 ----
 
-==== Defining Completion Candidates
+==== Customizing Completion Candidates
 
-TODO
+`@Flag` and `@Argument` annotations may specify the `completionCandidates` to improve generated shell completions.
+
+Valid values include:
+
+* A `Listing<String>` of literal string values to offer for completion.
+* The literal string `"path"`, which offers local file paths for completion.
+
+Options with a string literal union type implicitly offer the members of the union as completion candidates.
 
 === Flag name ambiguities
 

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

@@ -15,6 +15,7 @@
  */
 package org.pkl.cli
 
+import com.github.ajalt.clikt.completion.CompletionCandidates
 import com.github.ajalt.clikt.completion.CompletionCommand
 import com.github.ajalt.clikt.core.*
 import com.github.ajalt.clikt.parameters.arguments.*
@@ -36,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.PklBugException
 import org.pkl.core.PklException
 import org.pkl.core.util.IoUtils
 
@@ -153,6 +155,7 @@ constructor(
                   help = opt.helpText ?: "",
                   metavar = opt.metavar,
                   hidden = opt.hidden,
+                  completionCandidates = opt.completionCandidates?.toClikt(),
                 )
                 .convert {
                   try {
@@ -251,3 +254,10 @@ constructor(
     }
   }
 }
+
+fun CommandSpec.CompletionCandidates.toClikt(): CompletionCandidates =
+  when (this) {
+    CommandSpec.CompletionCandidates.PATH -> CompletionCandidates.Path
+    is CommandSpec.CompletionCandidates.Fixed -> CompletionCandidates.Fixed(values)
+    else -> throw PklBugException.unreachableCode()
+  }

pkl-cli/src/test/kotlin/org/pkl/cli/CliCommandRunnerTest.kt

@@ -17,7 +17,7 @@ package org.pkl.cli
 
 import com.github.ajalt.clikt.core.CliktError
 import com.github.ajalt.clikt.core.MissingOption
-import com.github.ajalt.clikt.core.PrintHelpMessage
+import com.github.ajalt.clikt.core.PrintCompletionMessage
 import com.github.tomakehurst.wiremock.junit5.WireMockTest
 import java.io.ByteArrayOutputStream
 import java.net.URI
@@ -1093,4 +1093,46 @@ class CliCommandRunnerTest {
           .trimIndent()
       )
   }
+
+  @Test
+  fun `completion candidates`() {
+    val moduleUri =
+      writePklFile(
+        "cmd.pkl",
+        renderOptions +
+          """
+      class Options {
+        none: String?
+        enum: *"a" | "b" | "c"
+        @Flag { completionCandidates = "path" }
+        path: String?
+        @Flag { completionCandidates { "foo"; "bar"; "baz" } }
+        explicit: String?
+      }
+    """
+            .trimIndent(),
+      )
+    val exc =
+      assertThrows<PrintCompletionMessage> {
+        runToStdout(
+          CliBaseOptions(sourceModules = listOf(moduleUri)),
+          listOf("shell-completion", "bash"),
+        )
+      }
+    assertThat(exc.message)
+      .contains(
+        """
+    "--none")
+      ;;
+    "--enum")
+      COMPREPLY=($(compgen -W 'a b c' -- "${'$'}{word}"))
+      ;;
+    "--path")
+       __complete_files "${'$'}{word}"
+      ;;
+    "--explicit")
+      COMPREPLY=($(compgen -W 'bar baz foo' -- "${'$'}{word}"))
+      ;;"""
+      )
+  }
 }

pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/extensions.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-core/src/main/java/org/pkl/core/CommandSpec.java

@@ -18,6 +18,7 @@
 import java.net.URI;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 import org.pkl.core.util.Nullable;
@@ -65,12 +66,31 @@ public static BadValue invalidChoice(String value, String choice) {
     }
   }
 
+  public abstract static sealed class CompletionCandidates {
+    public static final CompletionCandidates PATH = new StaticCompletionCandidates();
+
+    public static final class Fixed extends CompletionCandidates {
+      private final Set<String> values;
+
+      public Fixed(Set<String> values) {
+        this.values = values;
+      }
+
+      public Set<String> getValues() {
+        return values;
+      }
+    }
+
+    private static final class StaticCompletionCandidates extends CompletionCandidates {}
+  }
+
   public record Flag(
       String name,
       @Nullable String helpText,
       boolean showAsRequired,
       BiFunction<String, URI, Object> transformEach,
       Function<List<Object>, Object> transformAll,
+      @Nullable CompletionCandidates completionCandidates,
       @Nullable String shortName,
       String metavar,
       boolean hidden,
@@ -115,6 +135,7 @@ public record Argument(
       @Nullable String helpText,
       BiFunction<String, URI, Object> transformEach,
       Function<List<Object>, Object> transformAll,
+      @Nullable CompletionCandidates completionCandidates,
       boolean repeated)
       implements Option {
     @Override

pkl-core/src/main/java/org/pkl/core/PClassInfo.java

@@ -39,7 +39,6 @@ public final class PClassInfo<T> implements Serializable {
   public static final URI pklSemverUri = URI.create("pkl:semver");
   public static final URI pklSettingsUri = URI.create("pkl:settings");
   public static final URI pklProjectUri = URI.create("pkl:Project");
-  public static final URI pklCommandUri = URI.create("pkl:Command");
 
   public static final PClassInfo<Void> Any = pklBaseClassInfo("Any", Void.class);
   public static final PClassInfo<PNull> Null = pklBaseClassInfo("Null", PNull.class);
@@ -86,8 +85,6 @@ public final class PClassInfo<T> implements Serializable {
       new PClassInfo<>("pkl.Project", "ModuleClass", PObject.class, pklProjectUri);
   public static final PClassInfo<PObject> Settings =
       new PClassInfo<>("pkl.settings", "ModuleClass", PObject.class, pklSettingsUri);
-  public static final PClassInfo<PObject> Command =
-      new PClassInfo<>("pkl.Command", "ModuleClass", PObject.class, pklCommandUri);
 
   public static final PClassInfo<Object> Unavailable =
       new PClassInfo<>("unavailable", "unavailable", Object.class, URI.create("pkl:unavailable"));

pkl-core/src/main/java/org/pkl/core/ast/member/ClassMember.java

@@ -54,21 +54,31 @@ public final List<VmTyped> getAnnotations() {
     return annotations;
   }
 
-  /**
-   * Return all annotations starting from the declaring class and traversing up the class hierarchy
-   */
-  public final List<VmTyped> getAllAnnotations() {
-    assert name != null;
-    var allAnnotations = new ArrayList<>(annotations);
-    var clazz = getDeclaringClass().getSuperclass();
-    while (clazz != null) {
-      var prop = clazz.getProperty(name);
-      if (prop != null) {
-        allAnnotations.addAll(prop.getAnnotations());
+  public List<VmTyped> getAllAnnotations(boolean ascending) {
+    var annotations = new ArrayList<VmTyped>();
+
+    if (ascending) {
+      for (var clazz = getDeclaringClass(); clazz != null; clazz = clazz.getSuperclass()) {
+        var p = clazz.getDeclaredProperty(getName());
+        if (p != null) {
+          annotations.addAll(p.getAnnotations());
+        }
       }
-      clazz = clazz.getSuperclass();
+    } else {
+      doGetAllAnnotationsDescending(getDeclaringClass(), annotations);
+    }
+
+    return annotations;
+  }
+
+  private void doGetAllAnnotationsDescending(VmClass clazz, List<VmTyped> annotations) {
+    if (clazz.getSuperclass() != null) {
+      doGetAllAnnotationsDescending(clazz.getSuperclass(), annotations);
+    }
+    var p = clazz.getDeclaredProperty(getName());
+    if (p != null) {
+      annotations.addAll(p.getAnnotations());
     }
-    return allAnnotations;
   }
 
   /** Returns the prototype of the class that declares this member. */

pkl-core/src/main/java/org/pkl/core/ast/member/ClassProperty.java

@@ -54,33 +54,6 @@ public ClassProperty(
     this.initializer = initializer;
   }
 
-  public List<VmTyped> getAllAnnotations(boolean ascending) {
-    var annotations = new ArrayList<VmTyped>();
-
-    if (ascending) {
-      for (var clazz = getDeclaringClass(); clazz != null; clazz = clazz.getSuperclass()) {
-        var p = clazz.getDeclaredProperty(getName());
-        if (p != null) {
-          annotations.addAll(p.getAnnotations());
-        }
-      }
-    } else {
-      doGetAllAnnotationsDescending(getDeclaringClass(), annotations);
-    }
-
-    return annotations;
-  }
-
-  private void doGetAllAnnotationsDescending(VmClass clazz, List<VmTyped> annotations) {
-    if (clazz.getSuperclass() != null) {
-      doGetAllAnnotationsDescending(clazz.getSuperclass(), annotations);
-    }
-    var p = clazz.getDeclaredProperty(getName());
-    if (p != null) {
-      annotations.addAll(p.getAnnotations());
-    }
-  }
-
   public VmSet getAllModifierMirrors() {
     var mods = 0;
     for (var clazz = getDeclaringClass(); clazz != null; clazz = clazz.getSuperclass()) {

pkl-core/src/main/java/org/pkl/core/runtime/CommandModule.java

@@ -15,15 +15,14 @@
  */
 package org.pkl.core.runtime;
 
-import static org.pkl.core.PClassInfo.pklCommandUri;
-
 import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
+import java.net.URI;
 
 public final class CommandModule extends StdLibModule {
   static final VmTyped instance = VmUtils.createEmptyModule();
 
   static {
-    loadModule(pklCommandUri, instance);
+    loadModule(URI.create("pkl:Command"), instance);
   }
 
   private CommandModule() {}