Add analyze imports libs (SPICE-0001) (#695)

This adds a new feature to build a dependency graph of Pkl programs, following the SPICE outlined in https://github.com/apple/pkl-evolution/pull/2.

It adds:
* CLI command `pkl analyze imports`
* Java API `org.pkl.core.Analyzer`
* Pkl stdlib module `pkl:analyze`
* pkl-gradle extension `analyze`

In addition, it also changes the Gradle plugin such that `transitiveModules` is by default computed from the import graph.

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

@@ -102,7 +102,6 @@ pkl {
   evaluators {
     evalPkl {
       sourceModules.add(file("module1.pkl"))
-      transitiveModules.from file("module2.pkl")
       outputFile = layout.buildDirectory.file("module1.yaml")
       outputFormat = "yaml"
     }
@@ -118,7 +117,6 @@ pkl {
   evaluators {
     register("evalPkl") {
       sourceModules.add(file("module1.pkl"))
-      transitiveModules.from(file("module2.pkl"))
       outputFile.set(layout.buildDirectory.file("module1.yaml"))
       outputFormat.set("yaml")
     }
@@ -127,9 +125,6 @@ pkl {
 ----
 ====
 
-To guarantee correct Gradle up-to-date behavior, 
-`transitiveModules` needs to contain all module files transitively referenced by `sourceModules`.
-
 For each declared evaluator, the Pkl plugin creates an equally named task.
 Hence the above evaluator can be run with:
 
@@ -691,3 +686,61 @@ The project directories to create packages for.
 Common properties:
 
 include::../partials/gradle-common-properties.adoc[]
+
+[[analyze-imports]]
+== Analyze Imports
+
+This feature is the Gradle analogy for the xref:pkl-cli:index.adoc#command-analyze-imports[analyze imports] command in the CLI. It builds a graph of imports of the provided source modules.
+
+=== Usage
+
+[tabs]
+====
+build.gradle::
++
+[source,groovy]
+----
+pkl {
+  analyzers {
+    imports {
+      appConfig {
+        sourceModules.add(file("src/main/resources/appConfig.pkl"))
+      }
+    }
+  }
+}
+----
+
+build.gradle.kts::
++
+[source,kotlin]
+----
+pkl {
+  analyzers {
+    imports {
+      register("appConfig") {
+        sourceModules.add(file("src/main/resources/appConfig.pkl"))
+      }
+    }
+  }
+}
+----
+====
+
+=== Configuration Options
+
+.outputFormat: Property<String>
+[%collapsible]
+====
+Same meaning as <<output-format,outputFormat>> in <<module-evaluation>>.
+====
+
+.outputFile: RegularFileProperty<String>
+[%collapsible]
+====
+Same meaning as <<output-file,outputFile>> in <<module-evaluation>>.
+====
+
+Common properties:
+
+include::../partials/gradle-modules-properties.adoc[]

docs/modules/pkl-gradle/partials/gradle-common-properties.adoc

@@ -7,7 +7,6 @@ URI patterns that determine which modules can be loaded and evaluated.
 Patterns are matched against the beginning of module URIs.
 (File paths have been converted to `file:` URLs at this stage.)
 At least one pattern needs to match for a module to be loadable.
-Both source modules and transitive modules are subject to this check.
 ====
 
 .allowedResources: ListProperty<String>

docs/modules/pkl-gradle/partials/gradle-modules-properties.adoc

@@ -20,11 +20,17 @@ This property accepts the following types to represent a module:
 .transitiveModules: ConfigurableFileCollection
 [%collapsible]
 ====
-Default: `files()` (empty collection) +
+Default: [computed by pkl-gradle] +
 Example 1: `transitiveModules.from files("module1.pkl", "module2.pkl")` +
 Example 2: `+transitiveModules.from fileTree("config").include("**/*.pkl")+` +
+
 File paths of modules that are directly or indirectly used by source modules.
-Setting this option enables correct Gradle up-to-date checks, which ensures that your Pkl tasks are executed if any of the transitive files are modified; it does not affect evaluation otherwise.
+
+This property, along with `sourceModules`, is the set of input files used to determine whether this task is up-to-date or not.
+
+By default, Pkl computes this property by analyzing the imports of the source modules.
+Setting this property explicitly causes Pkl to skip the analyze imports step.
+
 Including source modules in `transitiveModules` is permitted but not required.
 Relative paths are resolved against the project directory.
 ====