Support modulepath imports

src/main/kotlin/org/pkl/lsp/Project.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.
@@ -55,6 +55,8 @@ class Project(private val server: PklLspServer) {
 
   val pklParser: PklParser by lazy { PklParser(this) }
 
+  val modulepathResolver: ModulepathResolver by lazy { ModulepathResolver(this) }
+
   fun initialize(): CompletableFuture<*> {
     return CompletableFuture.allOf(*myComponents.map { it.initialize() }.toTypedArray())
   }

src/main/kotlin/org/pkl/lsp/ast/PklModuleUri.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.
@@ -18,11 +18,7 @@ package org.pkl.lsp.ast
 import io.github.treesitter.jtreesitter.Node
 import java.nio.file.Path
 import org.pkl.lsp.*
-import org.pkl.lsp.FsFile
-import org.pkl.lsp.HttpsFile
-import org.pkl.lsp.JarFile
 import org.pkl.lsp.LspUtil.firstInstanceOf
-import org.pkl.lsp.VirtualFile
 import org.pkl.lsp.packages.dto.PackageUri
 import org.pkl.lsp.packages.dto.PklProject
 import org.pkl.lsp.util.CachedValue
@@ -125,6 +121,7 @@ class PklModuleUriImpl(project: Project, override val parent: PklNode, override
               ?.resolve(targetUri.fragment)
           vfile?.getModule()?.get()
         }
+        "modulepath" -> project.modulepathResolver.resolve(targetUri.path, context)
         // targetUri is a relative URI
         null -> {
           when {

src/main/kotlin/org/pkl/lsp/completion/ModuleUriCompletionProvider.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.
@@ -37,13 +37,15 @@ class ModuleUriCompletionProvider(project: Project, private val packageUriOnly:
     private const val FILE_SCHEME = "file:///"
     private const val HTTPS_SCHEME = "https://"
     private const val PACKAGE_SCHEME = "package://"
+    private const val MODULEPATH_SCHEME = "modulepath:/"
 
     private val SCHEME_ELEMENTS =
       listOf(
         CompletionItem(PKL_SCHEME),
         CompletionItem(FILE_SCHEME),
         CompletionItem(HTTPS_SCHEME),
         CompletionItem(PACKAGE_SCHEME),
+        CompletionItem(MODULEPATH_SCHEME),
       )
 
     private val GLOBBABLE_SCHEME_ELEMENTS =
@@ -183,6 +185,21 @@ class ModuleUriCompletionProvider(project: Project, private val packageUriOnly:
           }
         }
       }
+      targetUri.startsWith(MODULEPATH_SCHEME) -> {
+        val context = sourceModule.virtualFile.pklProject
+        val roots =
+          project.modulepathResolver.paths(context).mapNotNull(project.virtualFileManager::get)
+        completeHierarchicalUri(
+          roots,
+          ".",
+          targetUri.substring(12),
+          collector,
+          isGlobImport = isGlobImport,
+          isAbsoluteUri = true,
+          stringCharsNode = stringChars,
+          targetUri = targetUri,
+        )
+      }
       targetUri.startsWith("@") && !packageUriOnly -> {
         val dependencies = sourceModule.dependencies(null) ?: return
         if (!targetUri.contains('/')) {

src/main/kotlin/org/pkl/lsp/packages/dto/PklProject.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 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.
@@ -49,7 +49,11 @@ data class PklProject(val metadata: DerivedProjectMetadata, val projectDeps: Pro
       val evaluatorSettings: EvaluatorSettings?,
     )
 
-    @Serializable data class EvaluatorSettings(val moduleCacheDir: String? = null)
+    @Serializable
+    data class EvaluatorSettings(
+      val moduleCacheDir: String? = null,
+      val modulePath: List<String>? = null,
+    )
 
     @Serializable
     data class ProjectDeps(

src/main/kotlin/org/pkl/lsp/services/ModulepathResolver.kt

@@ -0,0 +1,49 @@
+/*
+ * 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.
+ * 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.lsp.services
+
+import java.nio.file.Files
+import java.nio.file.Path
+import org.pkl.lsp.Component
+import org.pkl.lsp.Project
+import org.pkl.lsp.ast.PklModule
+import org.pkl.lsp.packages.dto.PklProject
+
+class ModulepathResolver(project: Project) : Component(project) {
+  fun resolve(path: String, context: PklProject?): PklModule? {
+    val path = path.trimStart('/')
+    val file =
+      project.settingsManager.settings.modulepath
+        .map { it.resolve(path) }
+        .firstOrNull(Files::exists)
+        ?: context
+          ?.metadata
+          ?.evaluatorSettings
+          ?.modulePath
+          ?.map { context.projectDir.resolve(it, path) }
+          ?.firstOrNull(Files::exists)
+        ?: return null
+    return project.virtualFileManager.get(file)?.getModule()?.get()
+  }
+
+  fun paths(context: PklProject?): List<Path> {
+    val fromSettings = project.settingsManager.settings.modulepath
+    val fromProject =
+      context?.metadata?.evaluatorSettings?.modulePath?.map(context.projectDir::resolve)
+        ?: return fromSettings
+    return fromSettings + fromProject
+  }
+}

src/main/kotlin/org/pkl/lsp/services/SettingsManager.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.
@@ -17,6 +17,7 @@ package org.pkl.lsp.services
 
 import com.google.gson.JsonElement
 import com.google.gson.JsonPrimitive
+import java.nio.file.Files
 import java.nio.file.Path
 import java.util.concurrent.CompletableFuture
 import kotlin.io.path.isExecutable
@@ -30,6 +31,7 @@ import org.pkl.lsp.messages.ActionableNotification
 data class WorkspaceSettings(
   var pklCliPath: Path? = null,
   var grammarVersion: GrammarVersion? = null,
+  var modulepath: List<Path> = listOf(),
 )
 
 class SettingsManager(project: Project) : Component(project) {
@@ -77,6 +79,24 @@ class SettingsManager(project: Project) : Component(project) {
     }
   }
 
+  private fun resolveModulepath(value: JsonElement): List<Path> {
+    if (value.isJsonNull) return listOf()
+    if (!value.isJsonArray) {
+      logger.warn("Got non-array value for configuration: pkl.modulepath. Value: $value")
+      return listOf()
+    }
+    return buildList {
+      for (path in value.asJsonArray) {
+        val decodedPath = decodeString(path, "pkl.modulepath")
+        if (path != null) {
+          val entry = Path.of(path.asString)
+          if (!Files.exists(entry)) logger.warn("Entry in pkl.modulepath does not exist: $entry")
+          add(entry)
+        }
+      }
+    }
+  }
+
   private fun loadSettings(): CompletableFuture<Unit> {
     logger.log("Fetching configuration")
     val params =
@@ -90,14 +110,21 @@ class SettingsManager(project: Project) : Component(project) {
             scopeUri = "Pkl"
             section = "pkl.formatter.grammarVersion"
           },
+          ConfigurationItem().apply {
+            scopeUri = "Pkl"
+            section = "pkl.modulepath"
+          },
         )
       )
     return project.languageClient
       .configuration(params)
-      .thenApply { (cliPath, grammarVersion) ->
-        logger.log("Got configuration: cliPath = $cliPath, grammarVersion = $grammarVersion")
+      .thenApply { (cliPath, grammarVersion, modulepath) ->
+        logger.log(
+          "Got configuration: cliPath = $cliPath, grammarVersion = $grammarVersion, modulepath = $modulepath"
+        )
         settings.pklCliPath = resolvePklCliPath(cliPath as JsonElement)
         settings.grammarVersion = resolveGrammarVersion(grammarVersion as JsonElement)
+        settings.modulepath = resolveModulepath(modulepath as JsonElement)
       }
       .exceptionally { logger.error("Failed to fetch settings: ${it.cause}") }
       .whenComplete { _, _ -> logger.log("Settings changed to $settings") }

src/main/kotlin/org/pkl/lsp/type/InferResourceType.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.
@@ -48,6 +48,7 @@ fun inferResourceType(
     stringChars.startsWith("file:", ignoreCase = true) -> base.resourceType
     stringChars.startsWith("http:", ignoreCase = true) -> base.resourceType
     stringChars.startsWith("https:", ignoreCase = true) -> base.resourceType
+    stringChars.startsWith("modulepath:", ignoreCase = true) -> base.resourceType
     !stringChars.contains(":") -> base.resourceType
     else ->
       // bail out

src/test/kotlin/org/pkl/lsp/CompletionFeatureTest.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.
@@ -24,22 +24,31 @@ class CompletionFeatureTest : LspTestBase() {
     createPklFile("amends \"<caret>\"")
     val completions = getCompletions()
     assertThat(completions.map { it.label })
-      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "main.pkl"))
+      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "modulepath:/", "main.pkl"))
   }
 
   @Test
   fun `complete import`() {
     createPklFile("import \"<caret>\"")
     val completions = getCompletions()
     assertThat(completions.map { it.label })
-      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "main.pkl"))
+      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "modulepath:/", "main.pkl"))
   }
 
   @Test
   fun `complete import expression`() {
     createPklFile("res = import(\"<caret>\")")
     val completions = getCompletions()
     assertThat(completions.map { it.label })
-      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "main.pkl"))
+      .isEqualTo(listOf("pkl:", "file:///", "https://", "package://", "modulepath:/", "main.pkl"))
+  }
+
+  @Test
+  fun `complete modulepath import`() {
+    fakeProject.settingsManager.settings.modulepath = listOf(testProjectDir.resolve("lib"))
+    createPklFile("lib/target.pkl", "")
+    createPklFile("import \"modulepath:/<caret>\"")
+    val completions = getCompletions()
+    assertThat(completions.map { it.label }).isEqualTo(listOf("target.pkl"))
   }
 }