Store PklProject annotations in the project metadata (#708)

Write annotations to project metadata, and provide them to pkl-doc\

The following annotations have meaning for pkl-doc:
* `@Unlisted`: hide package from documentation site
* `@Deprecated`: add deprecated information

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

@@ -980,6 +980,92 @@ class CliProjectPackagerTest {
       )
   }
 
+  @Test
+  fun `generate annotations`(@TempDir tempDir: Path) {
+    tempDir
+      .resolve("PklProject")
+      .writeString(
+        """
+        @Unlisted
+        @Deprecated { since = "0.26.1"; message = "do not use" }
+        @ModuleInfo { minPklVersion = "0.26.0" }
+        amends "pkl:Project"
+        
+        package {
+          name = "mypackage"
+          version = "1.0.0"
+          baseUri = "package://example.com/mypackage"
+          packageZipUrl = "https://foo.com"
+        }
+      """
+          .trimIndent()
+      )
+    val packager =
+      CliProjectPackager(
+        CliBaseOptions(workingDir = tempDir),
+        listOf(tempDir),
+        CliTestOptions(),
+        ".out/%{name}@%{version}",
+        skipPublishCheck = true,
+        consoleWriter = StringWriter()
+      )
+    packager.run()
+    val expectedMetadata = tempDir.resolve(".out/mypackage@1.0.0/mypackage@1.0.0")
+    assertThat(expectedMetadata).exists()
+    assertThat(expectedMetadata)
+      .hasContent(
+        """
+      {
+        "name": "mypackage",
+        "packageUri": "package://example.com/mypackage@1.0.0",
+        "version": "1.0.0",
+        "packageZipUrl": "https://foo.com",
+        "packageZipChecksums": {
+          "sha256": "8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85"
+        },
+        "dependencies": {},
+        "authors": [],
+        "annotations": [
+          {
+            "type": "PObject",
+            "classInfo": {
+              "moduleName": "pkl.base",
+              "class": "Unlisted",
+              "moduleUri": "pkl:base"
+            },
+            "properties": {}
+          },
+          {
+            "type": "PObject",
+            "classInfo": {
+              "moduleName": "pkl.base",
+              "class": "Deprecated",
+              "moduleUri": "pkl:base"
+            },
+            "properties": {
+              "since": "0.26.1",
+              "message": "do not use",
+              "replaceWith": null
+            }
+          },
+          {
+            "type": "PObject",
+            "classInfo": {
+              "moduleName": "pkl.base",
+              "class": "ModuleInfo",
+              "moduleUri": "pkl:base"
+            },
+            "properties": {
+              "minPklVersion": "0.26.0"
+            }
+          }
+        ]
+      }
+    """
+          .trimIndent()
+      )
+  }
+
   private fun Path.zipFilePaths(): List<String> {
     return FileSystems.newFileSystem(URI("jar:${toUri()}"), emptyMap<String, String>()).use { fs ->
       Files.walk(fs.getPath("/")).map(IoUtils::toNormalizedPathString).collect(Collectors.toList())

pkl-commons-test/src/main/files/packages/deprecated@1.0.0/deprecated@1.0.0.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "packageUri": "package://localhost:0/deprecated@1.0.0",
+  "name": "deprecated",
+  "version": "1.0.0",
+  "packageZipUrl": "https://localhost:0/deprecated@1.0.0/deprecated@1.0.0.zip",
+  "dependencies": {},
+  "packageZipChecksums": {
+    "sha256": "$computedChecksum"
+  },
+  "sourceCode": "https://example.com/deprecated",
+  "documentation": "https://example.com/deprecated-docs",
+  "license": "UNLICENSED",
+  "authors": [
+    "deprecated@example.com"
+  ],
+  "issueTracker": "https://example.com/deprecated/issues",
+  "annotations": [
+    {
+      "type": "PObject",
+      "classInfo": {
+        "moduleName": "pkl.base",
+        "class": "Deprecated",
+        "moduleUri": "pkl:base"
+      },
+      "properties": {
+        "since": "1.0.0",
+        "message": "don't use",
+        "replaceWith": null
+      }
+    }
+  ]
+}

pkl-commons-test/src/main/files/packages/deprecated@1.0.0/package/deprecated.pkl

@@ -0,0 +1,9 @@
+/// A module from a deprecated package
+module deprecated.deprecated
+
+/// Old foo
+@Deprecated { replaceWith = "bar" }
+foo: Int = 1
+
+/// New bar
+bar: Int = 2

pkl-commons-test/src/main/files/packages/unlisted@1.0.0/package/unlisted.pkl

@@ -0,0 +1,5 @@
+/// No docs are actually generated for this module
+module unlisted.unlisted
+
+/// 1
+foo: Int = 1

pkl-commons-test/src/main/files/packages/unlisted@1.0.0/unlisted@1.0.0.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "packageUri": "package://localhost:0/unlisted@1.0.0",
+  "name": "unlisted",
+  "version": "1.0.0",
+  "packageZipUrl": "https://localhost:0/unlisted@1.0.0/unlisted@1.0.0.zip",
+  "dependencies": {},
+  "packageZipChecksums": {
+    "sha256": "$computedChecksum"
+  },
+  "sourceCode": "https://example.com/unlisted",
+  "documentation": "https://example.com/unlisted-docs",
+  "license": "UNLICENSED",
+  "authors": [
+    "unlisted@example.com"
+  ],
+  "issueTracker": "https://example.com/unlisted/issues",
+  "annotations": [
+    {
+      "type": "PObject",
+      "classInfo": {
+        "moduleName": "pkl.base",
+        "class": "Unlisted",
+        "moduleUri": "pkl:base"
+      },
+      "properties": {}
+    }
+  ]
+}

pkl-core/src/main/java/org/pkl/core/packages/DependencyMetadata.java

@@ -19,12 +19,25 @@ import java.io.IOException;
 import java.io.OutputStream;
 import java.io.OutputStreamWriter;
 import java.net.URI;
+import java.net.URISyntaxException;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
+import java.util.Set;
+import java.util.regex.Pattern;
+import org.pkl.core.DataSize;
+import org.pkl.core.DataSizeUnit;
+import org.pkl.core.Duration;
+import org.pkl.core.DurationUnit;
+import org.pkl.core.PClassInfo;
+import org.pkl.core.PNull;
+import org.pkl.core.PObject;
+import org.pkl.core.Pair;
+import org.pkl.core.PklException;
 import org.pkl.core.Version;
 import org.pkl.core.packages.Dependency.RemoteDependency;
 import org.pkl.core.util.Nullable;
@@ -33,6 +46,7 @@ import org.pkl.core.util.json.Json.FormatException;
 import org.pkl.core.util.json.Json.JsArray;
 import org.pkl.core.util.json.Json.JsObject;
 import org.pkl.core.util.json.Json.JsonParseException;
+import org.pkl.core.util.json.Json.MissingFieldException;
 import org.pkl.core.util.json.JsonWriter;
 
 /**
@@ -63,7 +77,25 @@ import org.pkl.core.util.json.JsonWriter;
  *             "sha256": "abc123"
  *           }
  *         }
- *       }
+ *       },
+ *       "annotations": [
+ *         {
+ *           "moduleName": "pkl.base",
+ *           "class": "Unlisted",
+ *           "moduleUri": "pkl:base",
+ *           "properties": {}
+ *         },
+ *         {
+ *           "moduleName": "pkl.base",
+ *           "class": "Deprecated",
+ *           "moduleUri": "pkl:base",
+ *           "properties": {
+ *             "since": "0.26.1",
+ *             "message": "don't use",
+ *             "replaceWith": null
+ *           }
+ *         }
+ *       ]
  *     }
  *   </code>
  * </pre>
@@ -88,6 +120,8 @@ public final class DependencyMetadata {
     var authors = parsed.getNullable("authors", DependencyMetadata::parseAuthors);
     var issueTracker = parsed.getURIOrNull("issueTracker");
     var description = parsed.getStringOrNull("description");
+    var annotations = parsed.getNullable("annotations", DependencyMetadata::parseAnnotations);
+    if (annotations == null) annotations = List.of();
     return new DependencyMetadata(
         name,
         packageUri,
@@ -102,7 +136,8 @@ public final class DependencyMetadata {
         licenseText,
         authors,
         issueTracker,
-        description);
+        description,
+        annotations);
   }
 
   private static Map<String, RemoteDependency> parseDependencies(Object deps)
@@ -128,6 +163,122 @@ public final class DependencyMetadata {
     return ret;
   }
 
+  private static List<PObject> parseAnnotations(Object ann)
+      throws JsonParseException, URISyntaxException {
+    if (!(ann instanceof JsArray arr)) {
+      throw new FormatException("array", ann.getClass());
+    }
+    var annotations = new ArrayList<PObject>(arr.size());
+    for (var annotation : arr) {
+      var obj = parsePObject(annotation);
+      if (!(obj instanceof PObject pObject)) {
+        throw new PklException("Could not read annotation. Invalid object: " + obj);
+      }
+      annotations.add(pObject);
+    }
+    return annotations;
+  }
+
+  private static Object parsePObject(@Nullable Object obj)
+      throws JsonParseException, URISyntaxException {
+    if (obj == null) {
+      return PNull.getInstance();
+    } else if (obj instanceof String string) {
+      return string;
+    } else if (obj instanceof Boolean bool) {
+      return bool;
+    } else if (obj instanceof Integer integer) {
+      return integer.longValue();
+    } else if (obj instanceof Long aLong) {
+      return aLong;
+    } else if (obj instanceof Float aFloat) {
+      return aFloat.doubleValue();
+    } else if (obj instanceof Double aDouble) {
+      return aDouble;
+    } else if (obj instanceof JsArray array) {
+      var list = new ArrayList<>(array.size());
+      for (var element : array) {
+        list.add(parsePObject(element));
+      }
+      return list;
+    } else if (obj instanceof JsObject jsObj) {
+      var type = jsObj.getString("type");
+      switch (type) {
+        case "Set" -> {
+          var value = jsObj.getArray("value");
+          var set = new HashSet<>(value.size());
+          for (var element : value) {
+            set.add(parsePObject(element));
+          }
+          return set;
+        }
+        case "Map" -> {
+          var value = jsObj.getArray("value");
+          var map = new HashMap<>();
+          for (var kv : value) {
+            var kvObj = (JsObject) kv;
+            map.put(parsePObject(kvObj.get("key")), parsePObject(kvObj.get("value")));
+          }
+          return map;
+        }
+        case "PObject" -> {
+          var classInfoObj = jsObj.getObject("classInfo");
+          var moduleName = classInfoObj.getString("moduleName");
+          var className = classInfoObj.getString("class");
+          var moduleUri = classInfoObj.getString("moduleUri");
+          var props = jsObj.getObject("properties");
+          var classInfo = PClassInfo.get(moduleName, className, new URI(moduleUri));
+          var properties = new HashMap<String, Object>();
+          for (var kv : props.entrySet()) {
+            properties.put(kv.getKey(), parsePObject(kv.getValue()));
+          }
+          return new PObject(classInfo, properties);
+        }
+        case "Pattern" -> {
+          var value = jsObj.getString("value");
+          return Pattern.compile(value);
+        }
+        case "DataSize" -> {
+          var symbol = jsObj.getString("unit");
+          var value = jsObj.get("value");
+          if (value == null) {
+            throw new MissingFieldException(jsObj, "value");
+          }
+          var unit = DataSizeUnit.parse(symbol);
+          if (unit == null) {
+            throw new PklException("Invalid DataSize unit symbol: " + symbol);
+          }
+          if (!(value instanceof Double num)) {
+            throw new FormatException("double", value.getClass());
+          }
+          return new DataSize(num, unit);
+        }
+        case "Duration" -> {
+          var symbol = jsObj.getString("unit");
+          var value = jsObj.get("value");
+          if (value == null) {
+            throw new MissingFieldException(jsObj, "value");
+          }
+          var unit = DurationUnit.parse(symbol);
+          if (unit == null) {
+            throw new PklException("Invalid Duration unit symbol: " + symbol);
+          }
+          if (!(value instanceof Double num)) {
+            throw new FormatException("double", value.getClass());
+          }
+          return new Duration(num, unit);
+        }
+        case "Pair" -> {
+          var first = parsePObject(jsObj.get("first"));
+          var second = parsePObject(jsObj.get("second"));
+          return new Pair<>(first, second);
+        }
+      }
+    }
+    // should never be reached
+    throw new PklException("Could not read annotation. Invalid object type: " + obj.getClass());
+  }
+
   public static Checksums parseChecksums(Object obj) throws JsonParseException {
     if (!(obj instanceof JsObject jsObj)) {
       throw new FormatException("object", obj.getClass());
@@ -164,6 +315,7 @@ public final class DependencyMetadata {
   private final @Nullable List<String> authors;
   private final @Nullable URI issueTracker;
   private final @Nullable String description;
+  private final List<PObject> annotations;
 
   public DependencyMetadata(
       String name,
@@ -179,7 +331,8 @@ public final class DependencyMetadata {
       @Nullable String licenseText,
       @Nullable List<String> authors,
       @Nullable URI issueTracker,
-      @Nullable String description) {
+      @Nullable String description,
+      List<PObject> annotations) {
     this.name = name;
     this.packageUri = packageUri;
     this.version = version;
@@ -194,6 +347,7 @@ public final class DependencyMetadata {
     this.authors = authors;
     this.issueTracker = issueTracker;
     this.description = description;
+    this.annotations = annotations;
   }
 
   public String getName() {
@@ -250,6 +404,10 @@ public final class DependencyMetadata {
     return description;
   }
 
+  public List<PObject> getAnnotations() {
+    return annotations;
+  }
+
   /** Serializes project dependencies to JSON, and writes it to the provided output stream. */
   public void writeTo(OutputStream out) throws IOException {
     new DependencyMetadataWriter(out, this).write();
@@ -277,7 +435,8 @@ public final class DependencyMetadata {
         && Objects.equals(licenseText, that.licenseText)
         && Objects.equals(authors, that.authors)
         && Objects.equals(issueTracker, that.issueTracker)
-        && Objects.equals(description, that.description);
+        && Objects.equals(description, that.description)
+        && Objects.equals(annotations, that.annotations);
   }
 
   @Override
@@ -296,7 +455,8 @@ public final class DependencyMetadata {
         licenseText,
         authors,
         issueTracker,
-        description);
+        description,
+        annotations);
   }
 
   @Override
@@ -339,6 +499,8 @@ public final class DependencyMetadata {
         + '\''
         + ", description="
         + description
+        + ", annotations="
+        + annotations
         + '}';
   }
 
@@ -423,8 +585,125 @@ public final class DependencyMetadata {
       if (dependencyMetadata.description != null) {
         jsonWriter.name("description").value(dependencyMetadata.description);
       }
+      if (!dependencyMetadata.annotations.isEmpty()) {
+        jsonWriter.name("annotations");
+        writeAnnotations();
+      }
       jsonWriter.endObject();
       jsonWriter.close();
     }
+
+    private void writeAnnotations() throws IOException {
+      jsonWriter.beginArray();
+      for (var annotation : dependencyMetadata.annotations) {
+        writePObject(annotation);
+      }
+      jsonWriter.endArray();
+    }
+
+    private void writePClassInfo(PClassInfo<?> pClassInfo) throws IOException {
+      jsonWriter.beginObject();
+      jsonWriter.name("moduleName").value(pClassInfo.getModuleName());
+      jsonWriter.name("class").value(pClassInfo.getSimpleName());
+      jsonWriter.name("moduleUri").value(pClassInfo.getModuleUri().toString());
+      jsonWriter.endObject();
+    }
+
+    private void writePObject(PObject object) throws IOException {
+      jsonWriter.beginObject();
+      jsonWriter.name("type").value("PObject");
+      jsonWriter.name("classInfo");
+      writePClassInfo(object.getClassInfo());
+      jsonWriter.name("properties");
+      jsonWriter.beginObject();
+      for (var kv : object.getProperties().entrySet()) {
+        jsonWriter.name(kv.getKey());
+        writeGenericObject(kv.getValue());
+      }
+      jsonWriter.endObject();
+      jsonWriter.endObject();
+    }
+
+    private void writeGenericObject(Object value) throws IOException {
+      if (value instanceof PNull) {
+        jsonWriter.nullValue();
+      } else if (value instanceof PObject pObject) {
+        writePObject(pObject);
+      } else if (value instanceof String string) {
+        jsonWriter.value(string);
+      } else if (value instanceof Boolean bool) {
+        jsonWriter.value(bool);
+      } else if (value instanceof Integer num) {
+        jsonWriter.value(num);
+      } else if (value instanceof Long num) {
+        jsonWriter.value(num);
+      } else if (value instanceof Float num) {
+        jsonWriter.value(num);
+      } else if (value instanceof Double num) {
+        jsonWriter.value(num);
+      } else if (value instanceof List<?> list) {
+        jsonWriter.beginArray();
+        for (var v : list) {
+          writeGenericObject(v);
+        }
+        jsonWriter.endArray();
+      } else if (value instanceof Set<?> set) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("Set");
+        jsonWriter.name("value");
+        jsonWriter.beginArray();
+        for (var v : set) {
+          writeGenericObject(v);
+        }
+        jsonWriter.endArray();
+        jsonWriter.endObject();
+      } else if (value instanceof Map<?, ?> map) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("Map");
+        jsonWriter.name("value");
+        jsonWriter.beginArray();
+        for (var kv : map.entrySet()) {
+          jsonWriter.beginObject();
+          jsonWriter.name("key");
+          writeGenericObject(kv.getKey());
+          jsonWriter.name("value");
+          writeGenericObject(kv.getValue());
+          jsonWriter.endObject();
+        }
+        jsonWriter.endArray();
+        jsonWriter.endObject();
+      } else if (value instanceof Pattern pattern) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("Pattern");
+        jsonWriter.name("value").value(pattern.pattern());
+        jsonWriter.endObject();
+      } else if (value instanceof DataSize dataSize) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("DataSize");
+        jsonWriter.name("unit").value(dataSize.getUnit().getSymbol());
+        jsonWriter.name("value").value(dataSize.getValue());
+        jsonWriter.endObject();
+      } else if (value instanceof Duration duration) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("Duration");
+        jsonWriter.name("unit").value(duration.getUnit().getSymbol());
+        jsonWriter.name("value").value(duration.getValue());
+        jsonWriter.endObject();
+      } else if (value instanceof Pair<?, ?> pair) {
+        jsonWriter.beginObject();
+        jsonWriter.name("type").value("Pair");
+        jsonWriter.name("first");
+        writeGenericObject(pair.getFirst());
+        jsonWriter.name("second");
+        writeGenericObject(pair.getSecond());
+        jsonWriter.endObject();
+      } else {
+        // PClass and TypeAlias are not supported
+        throw new PklException(
+            "Error serializing annotation for PklProject:\n:"
+                + "  cannot render value with unexpected type: "
+                + value.getClass());
+      }
+    }
   }
 }

pkl-core/src/main/java/org/pkl/core/project/Project.java

@@ -65,6 +65,7 @@ public final class Project {
   private final URI projectBaseUri;
   private final List<URI> tests;
   private final Map<String, Project> localProjectDependencies;
+  private final List<PObject> annotations;
 
   /**
    * Loads Project data from the given {@link Path}.
@@ -256,6 +257,11 @@ public final class Project {
     return new RemoteDependency(packageUri, checksums);
   }
 
+  @SuppressWarnings("unchecked")
+  private static List<PObject> parseAnnotations(PObject module) {
+    return (List<PObject>) getProperty(module, "annotations");
+  }
+
   public static Project parseProject(PObject module) throws URISyntaxException {
     var pkgObj = getNullableProperty(module, "package");
     var projectFileUri = URI.create((String) module.getProperty("projectFileUri"));
@@ -279,6 +285,7 @@ public final class Project {
             .map((it) -> projectBaseUri.resolve(it).normalize())
             .collect(Collectors.toList());
     var localProjectDependencies = parseLocalProjectDependencies(module);
+    var annotations = parseAnnotations(module);
     return new Project(
         pkg,
         dependencies,
@@ -286,7 +293,8 @@ public final class Project {
         projectFileUri,
         projectBaseUri,
         tests,
-        localProjectDependencies);
+        localProjectDependencies,
+        annotations);
   }
 
   private static Map<String, Project> parseLocalProjectDependencies(PObject module)
@@ -399,7 +407,8 @@ public final class Project {
       URI projectFileUri,
       URI projectBaseUri,
       List<URI> tests,
-      Map<String, Project> localProjectDependencies) {
+      Map<String, Project> localProjectDependencies,
+      List<PObject> annotations) {
     this.pkg = pkg;
     this.dependencies = dependencies;
     this.evaluatorSettings = evaluatorSettings;
@@ -407,6 +416,7 @@ public final class Project {
     this.projectBaseUri = projectBaseUri;
     this.tests = tests;
     this.localProjectDependencies = localProjectDependencies;
+    this.annotations = annotations;
   }
 
   public @Nullable Package getPackage() {
@@ -453,12 +463,13 @@ public final class Project {
         && dependencies.equals(project.dependencies)
         && evaluatorSettings.equals(project.evaluatorSettings)
         && projectFileUri.equals(project.projectFileUri)
-        && tests.equals(project.tests);
+        && tests.equals(project.tests)
+        && annotations.equals(project.annotations);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(pkg, dependencies, evaluatorSettings, projectFileUri, tests);
+    return Objects.hash(pkg, dependencies, evaluatorSettings, projectFileUri, tests, annotations);
   }
 
   public DeclaredDependencies getDependencies() {
@@ -478,6 +489,10 @@ public final class Project {
     return Path.of(projectBaseUri);
   }
 
+  public List<PObject> getAnnotations() {
+    return annotations;
+  }
+
   @Deprecated(forRemoval = true)
   public static class EvaluatorSettings {
     private final PklEvaluatorSettings delegate;

pkl-core/src/main/java/org/pkl/core/project/ProjectPackager.java

@@ -288,7 +288,8 @@ public final class ProjectPackager {
         pkg.getLicenseText(),
         pkg.getAuthors(),
         pkg.getIssueTracker(),
-        pkg.getDescription());
+        pkg.getDescription(),
+        project.getAnnotations());
   }
 
   private DigestOutputStream newDigestOutputStream(OutputStream outputStream) {

pkl-core/src/test/kotlin/org/pkl/core/packages/DependencyMetadataTest.kt

@@ -18,9 +18,10 @@ package org.pkl.core.packages
 import java.io.ByteArrayOutputStream
 import java.net.URI
 import java.nio.charset.StandardCharsets
+import java.util.regex.Pattern
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
-import org.pkl.core.Version
+import org.pkl.core.*
 
 class DependencyMetadataTest {
   private val dependencyMetadata =
@@ -44,9 +45,28 @@ class DependencyMetadataTest {
       "The MIT License, you know it",
       listOf("birdy@bird.com"),
       URI("https://example.com/issues"),
-      "Some package description"
+      "Some package description",
+      listOf(
+        PObject(PClassInfo.Unlisted, mapOf()),
+        PObject(PClassInfo.Deprecated, mapOf("since" to "0.26.1", "message" to "don't use")),
+        PObject(
+          PClassInfo.get("myModule", "MyAnnotation", URI("pkl:fake")),
+          mapOf(
+            "string" to "bar",
+            "boolean" to true,
+            "long" to 1L,
+            "double" to 1.66,
+            "null" to PNull.getInstance(),
+            "list" to listOf("a", "b"),
+            "set" to setOf("a", "b"),
+            "map" to mapOf(true to "t", false to "f"),
+            "dataSize" to DataSize(1.5, DataSizeUnit.GIGABYTES),
+            "duration" to Duration(2.9, DurationUnit.HOURS),
+            "pair" to Pair(1L, "1")
+          )
+        )
+      ),
     )
-
   private val dependencyMetadataStr =
     """
      {
@@ -74,7 +94,84 @@ class DependencyMetadataTest {
          "birdy@bird.com"
        ],
        "issueTracker": "https://example.com/issues",
-       "description": "Some package description"
+       "description": "Some package description",
+       "annotations": [
+         {
+           "type": "PObject",
+           "classInfo": {
+             "moduleName": "pkl.base",
+             "class": "Unlisted",
+             "moduleUri": "pkl:base"
+           },
+           "properties": {}
+         },
+         {
+           "type": "PObject",
+           "classInfo": {
+             "moduleName": "pkl.base",
+             "class": "Deprecated",
+             "moduleUri": "pkl:base"
+           },
+           "properties": {
+             "since": "0.26.1",
+             "message": "don't use"
+           }
+         },
+         {
+           "type": "PObject",
+           "classInfo": {
+             "moduleName": "myModule",
+             "class": "MyAnnotation",
+             "moduleUri": "pkl:fake"
+           },
+           "properties": {
+             "string": "bar",
+             "boolean": true,
+             "long": 1,
+             "double": 1.66,
+             "null": null,
+             "list": [
+               "a",
+               "b"
+             ],
+             "set": {
+               "type": "Set",
+               "value": [
+                 "a",
+                 "b"
+               ]
+             },
+             "map": {
+               "type": "Map",
+               "value": [
+                 {
+                   "key": true,
+                   "value": "t"
+                 },
+                 {
+                   "key": false,
+                   "value": "f"
+                 }
+               ]
+             },
+             "dataSize": {
+               "type": "DataSize",
+               "unit": "gb",
+               "value": 1.5
+             },
+             "duration": {
+               "type": "Duration",
+               "unit": "h",
+               "value": 2.9
+             },
+             "pair": {
+               "type": "Pair",
+               "first": 1,
+               "second": "1"
+             }
+           }
+         }
+       ]
      }
     """
       .trimIndent()
@@ -85,6 +182,87 @@ class DependencyMetadataTest {
     assertThat(parsed).isEqualTo(dependencyMetadata)
   }
 
+  /** Patterns cannot be compared with [equals], so we have to test them separately. */
+  @Test
+  fun testPatternSerialization() {
+    val dependencyMetadata =
+      DependencyMetadata(
+        "my-proj-name",
+        PackageUri("package://example.com/my-proj-name@0.10.0"),
+        Version.parse("0.10.0"),
+        URI("https://example.com/foo/bar@0.5.3.zip"),
+        Checksums("abc123"),
+        mapOf(),
+        "https://example.com/my/source/0.5.3/blob%{path}#L%{line}-L%{endLine}",
+        URI("https://example.com/my/source"),
+        URI("https://example.com/my/docs"),
+        "MIT",
+        "The MIT License, you know it",
+        listOf("birdy@bird.com"),
+        URI("https://example.com/issues"),
+        "Some package description",
+        listOf(
+          PObject(
+            PClassInfo.get("myModule", "MyAnnotation", URI("pkl:fake")),
+            mapOf("pattern" to Regex(".*").toPattern())
+          )
+        ),
+      )
+    val dependencyMetadataStr =
+      """
+     {
+       "name": "my-proj-name",
+       "packageUri": "package://example.com/my-proj-name@0.10.0",
+       "version": "0.10.0",
+       "packageZipUrl": "https://example.com/foo/bar@0.5.3.zip",
+       "packageZipChecksums": {
+         "sha256": "abc123"
+       },
+       "dependencies": {},
+       "sourceCodeUrlScheme": "https://example.com/my/source/0.5.3/blob%{path}#L%{line}-L%{endLine}",
+       "sourceCode": "https://example.com/my/source",
+       "documentation": "https://example.com/my/docs",
+       "license": "MIT",
+       "licenseText": "The MIT License, you know it",
+       "authors": [
+         "birdy@bird.com"
+       ],
+       "issueTracker": "https://example.com/issues",
+       "description": "Some package description",
+       "annotations": [
+         {
+           "type": "PObject",
+           "classInfo": {
+             "moduleName": "myModule",
+             "class": "MyAnnotation",
+             "moduleUri": "pkl:fake"
+           },
+           "properties": {
+             "pattern": {
+               "type": "Pattern",
+               "value": ".*"
+             }
+           }
+         }
+       ]
+     }
+    """
+        .trimIndent()
+
+    val parsed = DependencyMetadata.parse(dependencyMetadataStr)
+    val expectedPattern = dependencyMetadata.annotations[0]["pattern"] as Pattern
+    val actualPattern = parsed.annotations[0]["pattern"]
+    assertThat(actualPattern).isInstanceOf(Pattern::class.java)
+    actualPattern as Pattern
+    assertThat(expectedPattern.pattern()).isEqualTo(actualPattern.pattern())
+
+    val str =
+      ByteArrayOutputStream()
+        .apply { dependencyMetadata.writeTo(this) }
+        .toString(StandardCharsets.UTF_8)
+    assertThat(str).isEqualTo(dependencyMetadataStr)
+  }
+
   @Test
   fun writeTo() {
     val str =

pkl-core/src/test/kotlin/org/pkl/core/project/ProjectTest.kt

@@ -72,8 +72,20 @@ class ProjectTest {
         path,
         null
       )
+    val expectedAnnotations =
+      listOf(
+        PObject(
+          PClassInfo.Deprecated,
+          mapOf("since" to "1.2", "message" to "do not use", "replaceWith" to "somethingElse")
+        ),
+        PObject(PClassInfo.Unlisted, mapOf()),
+        PObject(PClassInfo.ModuleInfo, mapOf("minPklVersion" to "0.26.0")),
+      )
     projectPath.writeString(
       """
+      @Deprecated { since = "1.2"; message = "do not use"; replaceWith = "somethingElse" }
+      @Unlisted
+      @ModuleInfo { minPklVersion = "0.26.0" }
       amends "pkl:Project"
 
       evaluatorSettings {
@@ -138,6 +150,7 @@ class ProjectTest {
     val project = Project.loadFromPath(projectPath)
     assertThat(project.`package`).isEqualTo(expectedPackage)
     assertThat(project.evaluatorSettings).isEqualTo(expectedSettings)
+    assertThat(project.annotations).isEqualTo(expectedAnnotations)
     assertThat(project.tests)
       .isEqualTo(listOf(path.resolve("test1.pkl"), path.resolve("test2.pkl")))
   }

pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt

@@ -108,7 +108,8 @@ class CliDocGenerator(private val options: CliDocGeneratorOptions) : CliCommand(
       overview = metadata.description,
       extraAttributes = mapOf("Checksum" to checksum.sha256),
       sourceCode = metadata.sourceCode,
-      sourceCodeUrlScheme = metadata.sourceCodeUrlScheme
+      sourceCodeUrlScheme = metadata.sourceCodeUrlScheme,
+      annotations = metadata.annotations,
     )
   }
 

pkl-doc/src/test/files/DocGeneratorTest/output/data/localhost(3a)0/deprecated/1.0.0/deprecated/index.js

@@ -0,0 +1 @@
+runtimeData.links('known-versions','[{"text":"1.0.0","classes":"current-version"}]');

pkl-doc/src/test/files/DocGeneratorTest/output/data/localhost(3a)0/deprecated/1.0.0/index.js

@@ -0,0 +1 @@
+runtimeData.links('known-versions','[{"text":"1.0.0","classes":"current-version"}]');

pkl-doc/src/test/files/DocGeneratorTest/output/index.html

@@ -118,6 +118,18 @@ age: Int
               </div>
             </div>
           </li>
+          <li>
+            <div id="localhost:0%2Fdeprecated" class="anchor"> </div>
+            <div class="member with-page-link"><a class="member-selflink material-icons" href="#localhost:0%2Fdeprecated">link</a>
+              <div class="member-left">
+                <div class="member-modifiers member-deprecated">package </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature member-deprecated"><a class="name-decl" href="./localhost(3a)0/deprecated/current/index.html">localhost:0/deprecated</a></div>
+                <div class="doc-comment">Deprecated: don't use</div>
+              </div>
+            </div>
+          </li>
           <li>
             <div id="localhost:0%2Ffruit" class="anchor"> </div>
             <div class="member with-page-link"><a class="member-selflink material-icons" href="#localhost:0%2Ffruit">link</a>

pkl-doc/src/test/files/DocGeneratorTest/output/localhost(3a)0/deprecated/1.0.0/deprecated/index.html

@@ -0,0 +1,219 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>deprecated (localhost:0/deprecated:1.0.0) • Docsite Title</title>
+    <script src="../../../../scripts/pkldoc.js" defer="defer"></script>
+    <script src="../../../../scripts/scroll-into-view.min.js" defer="defer"></script>
+    <script src="../../../../data/localhost(3a)0/deprecated/1.0.0/deprecated/index.js" defer="defer"></script>
+    <link href="../../../../styles/pkldoc.css" media="screen" type="text/css" rel="stylesheet">
+    <link rel="icon" type="image/svg+xml" href="../../../../images/favicon.svg">
+    <link rel="apple-touch-icon" sizes="180x180" href="../../../../images/apple-touch-icon.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="../../../../images/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="../../../../images/favicon-16x16.png">
+    <meta charset="UTF-8">
+  </head>
+  <body onload="onLoad()">
+    <header>
+      <div id="doc-title"><a href="../../../../index.html">Docsite Title</a></div>
+      <div id="search"><i id="search-icon" class="material-icons">search</i><input id="search-input" type="search" placeholder="Click or press 'S' to search this package" autocomplete="off" data-package-name="localhost:0/deprecated" data-package-version="1.0.0" data-package-url-prefix="../" data-module-name="deprecated.deprecated" data-root-url-prefix="../../../../"></div>
+    </header>
+    <main><a class="declaration-parent-link" href="../../../../index.html">Docsite Title</a> &gt; <a class="declaration-parent-link" href="../index.html">localhost:0/deprecated</a>
+      <h1 id="declaration-title">deprecated.deprecated<span id="declaration-version">1.0.0</span></h1>
+      <ul class="member-group-links">
+        <li><a href="#_properties">Properties</a></li>
+        <li><a href="#_methods">Methods</a></li>
+      </ul>
+      <div id="_overview" class="anchor"> </div>
+      <div id="_declaration" class="member">
+        <div class="member-signature">module <span class="name-decl">deprecated.deprecated</span></div>
+        <div class="doc-comment"><p>A module from a deprecated package</p></div>
+        <dl class="member-info">
+          <dt class="">Module URI:</dt>
+          <dd><span class="import-uri">package://localhost:0/deprecated@1.0.0#/deprecated.pkl</span><i class="copy-uri-button material-icons">content_copy</i></dd>
+          <dt class="runtime-data hidden">Known subtypes:</dt>
+          <dd id="known-subtypes" class="runtime-data hidden"></dd>
+          <dt class="runtime-data hidden">Known usages:</dt>
+          <dd id="known-usages" class="runtime-data hidden"></dd>
+          <dt class="runtime-data hidden">All versions:</dt>
+          <dd id="known-versions" class="runtime-data hidden"></dd>
+        </dl>
+      </div>
+      <div class="member-group">
+        <div id="_properties" class="anchor"> </div>
+        <h2 class="member-group-title">Properties<span class="toggle-inherited-members">(<span class="toggle-inherited-members-link button-link">show inherited</span>)</span></h2>
+        <ul>
+          <li>
+            <div id="output" class="anchor"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#output">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">hidden </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">output</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/ModuleOutput.html" class="name-ref">ModuleOutput</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>The output of this module.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>Defaults to all module properties rendered as either Pcf or the format specified on the command line.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="foo" class="anchor"> </div>
+            <div class="member with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#foo">link</a>
+              <div class="member-left">
+                <div class="member-modifiers member-deprecated"></div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature member-deprecated"><span class="name-decl">foo</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html" class="name-ref">Int</a></div>
+                <div class="doc-comment">Deprecated. Replace with: <code>bar</code></div>
+                <div class="doc-comment expandable hidden collapsed"><p>Old foo</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="bar" class="anchor"> </div>
+            <div class="member"><a class="member-selflink material-icons" href="#bar">link</a>
+              <div class="member-left">
+                <div class="member-modifiers"></div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">bar</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html" class="name-ref">Int</a></div>
+                <div class="doc-comment"><p>New bar</p></div>
+              </div>
+            </div>
+          </li>
+        </ul>
+      </div>
+      <div class="member-group">
+        <div id="_methods" class="anchor"> </div>
+        <h2 class="member-group-title">Methods<span class="toggle-inherited-members">(<span class="toggle-inherited-members-link button-link">show inherited</span>)</span></h2>
+        <ul>
+          <li>
+            <div id="getClass()" class="anchor"> </div>
+            <div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#getClass()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">getClass</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Class.html" class="name-ref">Class</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns the class of <code>this</code>.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="toString()" class="anchor"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#toString()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">toString</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns a string representation of <code>this</code>.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>This method is used to convert the values of string interpolation expressions to strings.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="ifNonNull()" class="anchor"> </div>
+            <div id="ifNonNull().Result" class="anchor-param1"> </div>
+            <div id="ifNonNull().transform" class="anchor-param2"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#ifNonNull()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">ifNonNull</span>&lt;<a class="param1">Result</a>&gt;(<span class="param2">transform</span>: (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html#NonNull" class="name-ref">NonNull</a>) -&gt; <a href="index.html#ifNonNull().Result" class="name-ref">Result</a>): <a href="index.html#ifNonNull().Result" class="name-ref">Result</a>?<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns <code>this |&gt; transform</code> if <code>this</code> is non-null, and <code>null</code> otherwise.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>This method is the complement of the <code>??</code> operator and the equivalent of an <code>Option</code> type's <code>map</code> and <code>flatMap</code> methods.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="hasProperty()" class="anchor"> </div>
+            <div id="hasProperty().name" class="anchor-param1"> </div>
+            <div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#hasProperty()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">hasProperty</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Boolean.html" class="name-ref">Boolean</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Tells if this object has a property with the given <code>name</code>.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="getProperty()" class="anchor"> </div>
+            <div id="getProperty().name" class="anchor-param1"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#getProperty()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">getProperty</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): unknown<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns the value of the property with the given <code>name</code>.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>Throws if a property with this name does not exist.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="getPropertyOrNull()" class="anchor"> </div>
+            <div id="getPropertyOrNull().name" class="anchor-param1"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#getPropertyOrNull()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">getPropertyOrNull</span>(<span class="param1">name</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>): unknown?<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns the value of the property with the given <code>name</code>.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>Returns <code>null</code> if a property with this name does not exist.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="toDynamic()" class="anchor"> </div>
+            <div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#toDynamic()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">toDynamic</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Dynamic.html" class="name-ref">Dynamic</a><span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Converts this object to a <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Dynamic.html"><code>Dynamic</code></a> object.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="toMap()" class="anchor"> </div>
+            <div class="member inherited expandable hidden collapsed"><a class="member-selflink material-icons" href="#toMap()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">toMap</span>(): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Map.html" class="name-ref">Map</a>&lt;<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>, unknown&gt;<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Converts this object to a <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Map.html"><code>Map</code></a>.</p></div>
+              </div>
+            </div>
+          </li>
+          <li>
+            <div id="relativePathTo()" class="anchor"> </div>
+            <div id="relativePathTo().other" class="anchor-param1"> </div>
+            <div class="member inherited expandable hidden collapsed with-expandable-docs"><i class="material-icons expandable-docs-icon">expand_more</i><a class="member-selflink material-icons" href="#relativePathTo()">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">function </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><span class="name-decl">relativePathTo</span>(<span class="param1">other</span>: <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Module.html" class="name-ref">Module</a>): <a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/List.html" class="name-ref">List</a>&lt;<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/String.html" class="name-ref">String</a>&gt;<span class="context"> (<a href="https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/index.html" class="name-ref">pkl.base</a>)</span><a class="member-source-link" href="https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L123-L456">Source</a></div>
+                <div class="doc-comment"><p>Returns the relative, descendent directory path between this module and <code>other</code>.</p></div>
+                <div class="doc-comment expandable hidden collapsed"><p>Throws if no such path exists.</p>
+<p>For example, if module <code>mod1</code> has path <code>/dir1/mod1.pkl</code>, and module <code>mod2</code> has path <code>/dir1/dir2/dir3/mod2.pkl</code>,
+then <code>mod1.relativePathTo(mod2)</code> will return <code>List(&quot;dir2&quot;, &quot;dir3&quot;)</code>.</p>
+<p>A common use case is to compute the directory path between a template located at the root of a hierarchy
+(say <code>rootModule.pkl</code>) and the currently evaluated module (accessible via the <code>module</code> keyword):</p>
+<pre><code>import &quot;rootModule.pkl&quot; // self-import
+path = rootModule.relativePathTo(module)
+</code></pre></div>
+              </div>
+            </div>
+          </li>
+        </ul>
+      </div>
+    </main>
+  </body>
+</html>

pkl-doc/src/test/files/DocGeneratorTest/output/localhost(3a)0/deprecated/1.0.0/index.html

@@ -0,0 +1,68 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>localhost:0/deprecated (1.0.0) • Docsite Title</title>
+    <script src="../../../scripts/pkldoc.js" defer="defer"></script>
+    <script src="../../../scripts/scroll-into-view.min.js" defer="defer"></script>
+    <script src="../../../data/localhost(3a)0/deprecated/1.0.0/index.js" defer="defer"></script>
+    <link href="../../../styles/pkldoc.css" media="screen" type="text/css" rel="stylesheet">
+    <link rel="icon" type="image/svg+xml" href="../../../images/favicon.svg">
+    <link rel="apple-touch-icon" sizes="180x180" href="../../../images/apple-touch-icon.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="../../../images/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="../../../images/favicon-16x16.png">
+    <meta charset="UTF-8">
+  </head>
+  <body onload="onLoad()">
+    <header>
+      <div id="doc-title"><a href="../../../index.html">Docsite Title</a></div>
+      <div id="search"><i id="search-icon" class="material-icons">search</i><input id="search-input" type="search" placeholder="Click or press 'S' to search this package" autocomplete="off" data-package-name="localhost:0/deprecated" data-package-version="1.0.0" data-package-url-prefix="" data-root-url-prefix="../../../"></div>
+    </header>
+    <main><a class="declaration-parent-link" href="../../../index.html">Docsite Title</a>
+      <h1 id="declaration-title">localhost:0/deprecated<span id="declaration-version">1.0.0</span></h1>
+      <ul class="member-group-links">
+        <li><a href="#_modules">Modules</a></li>
+      </ul>
+      <div id="_overview" class="anchor"> </div>
+      <div id="_declaration" class="member">
+        <div class="member-signature">package <span class="name-decl">localhost:0/deprecated</span></div>
+        <div class="doc-comment">Deprecated: don't use</div>
+        <dl class="member-info">
+          <dt class="">URI:</dt>
+          <dd><span class="import-uri">package://localhost:0/deprecated@1.0.0</span><i class="copy-uri-button material-icons">content_copy</i></dd>
+          <dt class="">Authors:</dt>
+          <dd>deprecated@example.com</dd>
+          <dt class="">Version:</dt>
+          <dd>1.0.0</dd>
+          <dt class="">Source code:</dt>
+          <dd><a href="https://example.com/deprecated">https://example.com/deprecated</a></dd>
+          <dt class="">Issue tracker:</dt>
+          <dd><a href="https://example.com/deprecated/issues">https://example.com/deprecated/issues</a></dd>
+          <dt class="">Checksum:</dt>
+          <dd>7589f1b802d6b5b93c468fb6399d2235d44d83f27409da2b036455ccb6e07ce5</dd>
+          <dt class="runtime-data hidden">Known usages:</dt>
+          <dd id="known-usages" class="runtime-data hidden"></dd>
+          <dt class="runtime-data hidden">All versions:</dt>
+          <dd id="known-versions" class="runtime-data hidden"></dd>
+        </dl>
+      </div>
+      <div class="member-group">
+        <div id="_modules" class="anchor"> </div>
+        <h2 class="member-group-title">Modules</h2>
+        <ul>
+          <li>
+            <div id="deprecated.deprecated" class="anchor"> </div>
+            <div class="member with-page-link"><a class="member-selflink material-icons" href="#deprecated.deprecated">link</a>
+              <div class="member-left">
+                <div class="member-modifiers">module </div>
+              </div>
+              <div class="member-main">
+                <div class="member-signature"><a class="name-decl" href="./deprecated/index.html">deprecated.deprecated</a></div>
+                <div class="doc-comment"><p>A module from a deprecated package</p></div>
+              </div>
+            </div>
+          </li>
+        </ul>
+      </div>
+    </main>
+  </body>
+</html>

pkl-doc/src/test/files/DocGeneratorTest/output/localhost(3a)0/deprecated/1.0.0/package-data.json

@@ -0,0 +1 @@
+{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0"},"deprecation":"don't use","sourceCode":"https://example.com/deprecated","sourceCodeUrlScheme":null,"dependencies":[{"ref":{"pkg":"pkl","pkgUri":null,"version":"0.24.0"}}],"modules":[{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0","module":"deprecated"},"summary":"A module from a deprecated package","moduleClass":{"ref":{"pkg":"localhost:0/deprecated","pkgUri":"package://localhost:0/deprecated@1.0.0","version":"1.0.0","module":"deprecated","type":"ModuleClass"},"superclasses":[{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Module"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Typed"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Object"},{"pkg":"pkl","pkgUri":null,"version":"0.24.0","module":"base","type":"Any"}]}}]}

pkl-doc/src/test/files/DocGeneratorTest/output/localhost(3a)0/deprecated/1.0.0/search-index.js

@@ -0,0 +1 @@
+searchData='[{"name":"deprecated.deprecated","kind":1,"url":"deprecated/index.html"},{"name":"foo","kind":5,"url":"deprecated/index.html#foo","sig":": Int","parId":0,"deprecated":true},{"name":"bar","kind":5,"url":"deprecated/index.html#bar","sig":": Int","parId":0}]';

pkl-doc/src/test/files/DocGeneratorTest/output/localhost(3a)0/deprecated/current

@@ -0,0 +1 @@
+1.0.0

pkl-doc/src/test/kotlin/org/pkl/doc/CliDocGeneratorTest.kt

@@ -123,7 +123,9 @@ class CliDocGeneratorTest {
                   package1PackageModule,
                   package2PackageModule,
                   URI("package://localhost:0/birds@0.5.0"),
-                  URI("package://localhost:0/fruit@1.1.0")
+                  URI("package://localhost:0/fruit@1.1.0"),
+                  URI("package://localhost:0/unlisted@1.0.0"),
+                  URI("package://localhost:0/deprecated@1.0.0"),
                 ) + package1InputModules + package2InputModules,
               moduleCacheDir = cacheDir
             ),

stdlib/Project.pkl

@@ -436,3 +436,7 @@ typealias CommonSpdxLicenseIdentifier =
   |"UPL-1.0"
   |"BSL-1.0"
   |"Unlicense"
+
+@Unlisted
+@Since { version = "0.27.0" }
+fixed annotations: List<Annotation> = reflect.moduleOf(this).annotations