Add listLibrariesMissingMetadata task/goal for Gradle and Maven (#877)

* Introduce listMissingMetadataLibs gradle task and maven goal

* Never cache gradle listMissingMetadataLibs task

* Attempt to fetch gh authentication when it's present

* Remove brittle, hard-coded tests

* Move from testing fork ticket opening, to actual upstream oracle repo

* Fix checkstyle in listMissingMetadataLibs task

* Rename listMissingMetadataLibs to listLibrariesMissingMetadata

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add unit tests for direct-runtime dependency selection

- ListLibrariesMissingMetadataTest covers the Gradle path: only direct
  external module dependencies survive, project components and
  unresolved entries are filtered, transitive children are not walked.
- ListLibrariesMissingMetadataMojoTest covers the Maven path:
  isDirectRuntimeDependency accepts compile/runtime/null scope at
  trail length 2, rejects test/provided, transitive trails, missing
  trail, and project-only trails.

Both tests run as plain Spock unit tests and require no GitHub access,
so they cover the dependency-selection contract without the brittle
live-metadata-repo dependency that the earlier functional tests had.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Group listLibrariesMissingMetadata console output and surface createIssues=true

The old output interleaved each missing library's coordinates with a
long, heavily URL-encoded prefilled issue link, then trailed a dense
seven-counter summary line. The call-to-action for filing issues
automatically (createIssues=true) was only reachable by reading the
docs.

The new rendering:
- Groups results by status: "Already requested" (existing open
  issues), "Requested support for N libraries" (when createIssues
  succeeded), and a manual "Or request support manually" section
  for the remaining ones. Errors get their own block at the end.
- Places a prominent call-to-action above the manual list that
  shows the exact re-run command tailored to the build tool
  (`-PcreateIssues=true` / `-DcreateIssues=true`) and the token
  resolution order on the next line.
- Collapses prefilled issue URLs into numbered footnotes ([1],
  [E1], [C1]) so library names line up vertically instead of
  drowning in 200-character URLs.
- Trims `&maven_coordinates=...` from the prefilled URL (the title
  already carries the GAV) and keeps colons readable in the title
  query value.
- Appends `Full report: <path>` as a one-line footer when the
  plugins pass in the report-file path via the new
  renderConsoleOutput(reportFilePath) overload.
- For all-supported runs, collapses to a single sentence.

Tests in MissingMetadataCommandSupportTest are updated to assert on
the new grouped output (headline, CTA, token sources, footnote
indices) and on the trimmed prefilled URL shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Fix missing metadata forced version and GitHub host resolution

* Fix ASCII-only checkstyle violation in metadata test

* Restore prefilled coordinates in metadata issue links

* Add schema for missing metadata reports

* Clarify missing metadata tip on docs landing page

* Fail listLibrariesMissingMetadata when issue creation fails

---------

Co-authored-by: Vojin Jovanovic <vojin.jovanovic@oracle.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

common/graalvm-reachability-metadata/src/main/java/org/graalvm/reachability/MissingMetadataCommandSupport.java

@@ -235,7 +235,17 @@ You can find an extensive list of libraries and frameworks from the Java ecosyst
 However, it may happen, that your native image crashes at run time with a missing class or resource.
 To address this, start by checking if any required configuration is missing.
 
-The best way to detect missing metadata is by running your native tests.
+Run this first to see which direct dependencies are not supported by the reachability metadata repository:
+
+[source,bash, role="multi-language-sample"]
+----
+./gradlew listLibrariesMissingMetadata
+----
+
+The task prints missing direct runtime dependencies, reuses existing reachability-metadata issues when it can, and writes a JSON report to _build/reports/native/list-libraries-missing-metadata.json_.
+If you want the task to create GitHub issues automatically instead of printing links, run `./gradlew listLibrariesMissingMetadata -PcreateIssues=true`.
+
+If the command reports missing libraries, fix those first.
 Alternatively, you can **identify missing configuration manually** using the following method.
 
 - Pass the `--exact-reachability-metadata` option to the `native-image` tool inside `graalvmNative` block of your _build.gradle_, as shown below:
@@ -443,4 +453,4 @@ All the monitoring and debugging tools https://www.graalvm.org/reference-manual/
 
 === Learn more
 
-To continue learning, refer to the <<gradle-plugin.adoc#,Gradle plugin documentation>>.
+To continue learning, refer to the <<gradle-plugin.adoc#,Gradle plugin documentation>>.

common/graalvm-reachability-metadata/src/test/java/org/graalvm/reachability/MissingMetadataCommandSupportTest.java

@@ -333,7 +333,17 @@ You can find an extensive list of libraries and frameworks from the Java ecosyst
 However, it may happen, that your native image crashes at run time with a missing class or resource.
 To address this, start by checking if any required configuration is missing.
 
-The best way to detect missing metadata is by running your native tests.
+Run this first to see which direct dependencies are not supported by the reachability metadata repository:
+
+[source,bash, role="multi-language-sample"]
+----
+./mvnw native:list-libraries-missing-metadata
+----
+
+The goal prints missing direct runtime dependencies, reuses existing reachability-metadata issues when it can, and writes a JSON report to _target/native/list-libraries-missing-metadata.json_.
+If you want the goal to create GitHub issues automatically instead of printing links, run `./mvnw -DcreateIssues=true native:list-libraries-missing-metadata`.
+
+If the command reports missing libraries, fix those first.
 Alternatively, you can **identify missing configuration manually** using the following method.
 
 - Pass the `--exact-reachability-metadata` option to the `native-image` tool in _pom.xml_, as shown below:

docs/src/docs/asciidoc/end-to-end-gradle-guide.adoc

@@ -825,6 +825,44 @@ include::../snippets/gradle/groovy/build.gradle[tags=specify-metadata-version-fo
 include::../snippets/gradle/kotlin/build.gradle.kts[tags=specify-metadata-version-for-library]
 ----
 
+[[gradle-list-libraries-missing-metadata]]
+=== Checking Missing Metadata Support
+
+Run this first to see which direct dependencies are not supported by the reachability metadata repository.
+
+[source,bash, role="multi-language-sample"]
+----
+./gradlew listLibrariesMissingMetadata
+----
+
+By default, the task:
+
+- Scans direct external runtime dependencies from the main runtime classpath
+- Uses the configured metadata repository as the source of truth
+- Prints existing reachability-metadata issues when they already exist
+- Prints prefilled issue links when a dependency is missing metadata support
+- Writes a JSON report to _build/reports/native/list-libraries-missing-metadata.json_
+
+The JSON report includes a `$schema` field pointing to _schemas/list-libraries-missing-metadata-schema-v1.0.0.json_ in this repository.
+
+To create issues automatically instead of printing links, opt in explicitly:
+
+[source,bash, role="multi-language-sample"]
+----
+./gradlew listLibrariesMissingMetadata -PcreateIssues=true
+----
+
+You can also override the GitHub integration inputs with Gradle properties such as `targetRepository`, `githubApiUrl`, `githubToken`, and `reportFile`.
+
+The GitHub token used for issue lookup and creation is resolved in this order:
+
+1. The `-PgithubToken=...` Gradle property
+2. The `GITHUB_TOKEN` environment variable
+3. The `GH_TOKEN` environment variable
+4. `gh auth token`, when the GitHub CLI is installed and authenticated (subprocess capped at 5 seconds; non-zero exit is treated as no token)
+
+In default list mode the task tolerates a missing token: it can still query public issues, and emits a single warning if the GitHub API rejects the lookup. With `-PcreateIssues=true`, a token is required.
+
 === Including Metadata Repository Files
 
 By default, reachability metadata is used only when your native image is being generated.

docs/src/docs/asciidoc/end-to-end-maven-guide.adoc

@@ -7,6 +7,14 @@ Currently, you can build your native applications using our Gradle or Maven plug
 Each plugin takes metadata for available libraries from the https://github.com/oracle/graalvm-reachability-metadata[GraalVM reachability metadata repository]
 to provide better experience during the development of your native project.
 
+[TIP]
+====
+Check library support first.
+Run `./gradlew listLibrariesMissingMetadata` or `./mvnw native:list-libraries-missing-metadata`
+before troubleshooting metadata manually so you can see which direct dependencies are unsupported
+by the reachability metadata repository.
+====
+
 If you are using alternative build systems, see <<alternative-build-systems.adoc#,Useful Hints for Alternative Build Systems>>.
 
 [discrete]

docs/src/docs/asciidoc/gradle-plugin.adoc

@@ -842,6 +842,44 @@ This may be interesting if there is no specific metadata available for the parti
 include::../../../../samples/native-config-integration/pom.xml[tag=metadata-force-version]
 ----
 
+[[maven-list-libraries-missing-metadata]]
+=== Checking Missing Metadata Support
+
+Run this first to see which direct dependencies are not supported by the reachability metadata repository.
+
+[source,bash, role="multi-language-sample"]
+----
+./mvnw native:list-libraries-missing-metadata
+----
+
+By default, the goal:
+
+- Scans direct external runtime dependencies
+- Uses the configured metadata repository as the source of truth
+- Prints existing reachability-metadata issues when they already exist
+- Prints prefilled issue links when a dependency is missing metadata support
+- Writes a JSON report to _target/native/list-libraries-missing-metadata.json_
+
+The JSON report includes a `$schema` field pointing to _schemas/list-libraries-missing-metadata-schema-v1.0.0.json_ in this repository.
+
+To create issues automatically instead of printing links, opt in explicitly:
+
+[source,bash, role="multi-language-sample"]
+----
+./mvnw -DcreateIssues=true -DgithubToken=... native:list-libraries-missing-metadata
+----
+
+You can also override the GitHub integration inputs with `targetRepository`, `githubApiUrl`, `githubToken`, and `reportFile`.
+
+The GitHub token used for issue lookup and creation is resolved in this order:
+
+1. The `-DgithubToken=...` system property
+2. The `GITHUB_TOKEN` environment variable
+3. The `GH_TOKEN` environment variable
+4. `gh auth token`, when the GitHub CLI is installed and authenticated (subprocess capped at 5 seconds; non-zero exit is treated as no token)
+
+In default list mode the goal tolerates a missing token: it can still query public issues, and emits a single warning if the GitHub API rejects the lookup. With `-DcreateIssues=true`, a token is required.
+
 === Adding Metadata Repository Files
 
 By default, reachability metadata is used only when your native image is being generated.

docs/src/docs/asciidoc/index.adoc

@@ -61,6 +61,7 @@
 import org.graalvm.buildtools.gradle.tasks.CollectReachabilityMetadata;
 import org.graalvm.buildtools.gradle.tasks.GenerateDynamicAccessMetadata;
 import org.graalvm.buildtools.gradle.tasks.GenerateResourcesConfigFile;
+import org.graalvm.buildtools.gradle.tasks.ListLibrariesMissingMetadata;
 import org.graalvm.buildtools.gradle.tasks.MetadataCopyTask;
 import org.graalvm.buildtools.gradle.tasks.NativeRunTask;
 import org.graalvm.buildtools.gradle.tasks.UseLayerOptions;
@@ -71,6 +72,7 @@
 import org.graalvm.buildtools.utils.JUnitUtils;
 import org.graalvm.buildtools.utils.SharedConstants;
 import org.graalvm.reachability.DirectoryConfiguration;
+import org.graalvm.reachability.MissingMetadataCommandSupport;
 import org.gradle.api.Action;
 import org.gradle.api.NamedDomainObjectContainer;
 import org.gradle.api.Plugin;
@@ -326,6 +328,35 @@ private void configureJavaProject(Project project, Provider<NativeImageService>
             task.getModuleToConfigVersion().convention(metadataRepositoryExtension.getModuleToConfigVersion());
             task.getInto().convention(project.getLayout().getBuildDirectory().dir("native-reachability-metadata"));
         });
+        project.getTasks().register("listLibrariesMissingMetadata", ListLibrariesMissingMetadata.class, task -> {
+            task.setGroup(LifecycleBasePlugin.BUILD_GROUP);
+            task.setDescription("Lists direct runtime dependencies that do not have reachability metadata support");
+            task.setClasspath(project.getConfigurations().getByName(JavaPlugin.RUNTIME_CLASSPATH_CONFIGURATION_NAME));
+            Provider<GraalVMReachabilityMetadataService> reachabilityMetadataService = graalVMReachabilityMetadataService(
+                project, metadataRepositoryExtension);
+            task.getMetadataService().set(reachabilityMetadataService);
+            task.usesService(reachabilityMetadataService);
+            task.getMetadataRepositoryEnabled().convention(metadataRepositoryExtension.getEnabled());
+            task.getMetadataRepositoryUri().convention(metadataRepositoryExtension.getUri().map(URI::toString));
+            task.getCreateIssues().convention(project.getProviders().gradleProperty("createIssues").map(Boolean::parseBoolean).orElse(false));
+            task.getGithubToken().convention(project.getProviders().gradleProperty("githubToken"));
+            task.getTargetRepository().convention(
+                project.getProviders().gradleProperty("targetRepository")
+                    .orElse(MissingMetadataCommandSupport.DEFAULT_TARGET_REPOSITORY)
+            );
+            task.getGithubApiUrl().convention(
+                project.getProviders().gradleProperty("githubApiUrl")
+                    .orElse(MissingMetadataCommandSupport.DEFAULT_GITHUB_API_URL)
+            );
+            task.getProjectName().convention(project.getName());
+            task.getExcludedModules().convention(metadataRepositoryExtension.getExcludedModules());
+            task.getModuleToConfigVersion().convention(metadataRepositoryExtension.getModuleToConfigVersion());
+            task.getReportFile().convention(
+                project.getProviders().gradleProperty("reportFile")
+                    .map(path -> project.getLayout().getProjectDirectory().file(path))
+                    .orElse(project.getLayout().getBuildDirectory().file("reports/native/list-libraries-missing-metadata.json"))
+            );
+        });
     }
 
     private void configureAutomaticTaskCreation(Project project,

docs/src/docs/asciidoc/maven-plugin.adoc

@@ -0,0 +1,174 @@
+/*
+ * Copyright (c) 2026, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.buildtools.gradle.tasks;
+
+import org.graalvm.buildtools.gradle.internal.GraalVMReachabilityMetadataService;
+import org.graalvm.reachability.MissingMetadataCommandSupport;
+import org.gradle.api.DefaultTask;
+import org.gradle.api.GradleException;
+import org.gradle.api.artifacts.Configuration;
+import org.gradle.api.artifacts.ModuleVersionIdentifier;
+import org.gradle.api.artifacts.component.ModuleComponentIdentifier;
+import org.gradle.api.artifacts.result.DependencyResult;
+import org.gradle.api.artifacts.result.ResolvedComponentResult;
+import org.gradle.api.artifacts.result.ResolvedDependencyResult;
+import org.gradle.api.file.RegularFileProperty;
+import org.gradle.api.provider.MapProperty;
+import org.gradle.api.provider.Property;
+import org.gradle.api.provider.SetProperty;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.Internal;
+import org.gradle.api.tasks.Optional;
+import org.gradle.api.tasks.OutputFile;
+import org.gradle.api.tasks.TaskAction;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+public abstract class ListLibrariesMissingMetadata extends DefaultTask {
+    public ListLibrariesMissingMetadata() {
+        getOutputs().upToDateWhen(task -> false);
+    }
+
+    public void setClasspath(Configuration classpath) {
+        getRootComponent().set(classpath.getIncoming().getResolutionResult().getRootComponent());
+    }
+
+    @Internal
+    protected abstract Property<ResolvedComponentResult> getRootComponent();
+
+    @Internal
+    public abstract Property<GraalVMReachabilityMetadataService> getMetadataService();
+
+    @Input
+    public abstract Property<Boolean> getMetadataRepositoryEnabled();
+
+    @Input
+    @Optional
+    public abstract Property<String> getMetadataRepositoryUri();
+
+    @Input
+    public abstract Property<Boolean> getCreateIssues();
+
+    @Internal
+    public abstract Property<String> getGithubToken();
+
+    @Input
+    public abstract Property<String> getTargetRepository();
+
+    @Input
+    public abstract Property<String> getGithubApiUrl();
+
+    @Input
+    public abstract Property<String> getProjectName();
+
+    @Input
+    @Optional
+    public abstract SetProperty<String> getExcludedModules();
+
+    @Input
+    @Optional
+    public abstract MapProperty<String, String> getModuleToConfigVersion();
+
+    @OutputFile
+    public abstract RegularFileProperty getReportFile();
+
+    @TaskAction
+    void listLibrariesMissingMetadata() throws IOException {
+        if (!Boolean.TRUE.equals(getMetadataRepositoryEnabled().get())) {
+            throw new GradleException("GraalVM reachability metadata repository is disabled.");
+        }
+        if (!getRootComponent().isPresent()) {
+            throw new GradleException("Runtime classpath resolution result is unavailable.");
+        }
+        GraalVMReachabilityMetadataService service = getMetadataService().get();
+        List<MissingMetadataCommandSupport.DependencyCoordinate> dependencies = directExternalRuntimeDependencies(getRootComponent().get());
+        MissingMetadataCommandSupport.Report report = MissingMetadataCommandSupport.run(
+            dependencies,
+            service,
+            getExcludedModules().getOrElse(Collections.emptySet()),
+            getModuleToConfigVersion().getOrElse(Collections.emptyMap()),
+            new MissingMetadataCommandSupport.Options(
+                "gradle",
+                getProjectName().get(),
+                getMetadataRepositoryUri().getOrNull(),
+                Boolean.TRUE.equals(getCreateIssues().getOrElse(false)),
+                getGithubToken().getOrNull(),
+                getTargetRepository().get(),
+                getGithubApiUrl().get(),
+                null,
+                message -> getLogger().warn(message)
+            )
+        );
+        String reportFilePath = getReportFile().get().getAsFile().getAbsolutePath();
+        writeReport(report.toJsonString());
+        getLogger().lifecycle(report.renderConsoleOutput(reportFilePath));
+    }
+
+    static List<MissingMetadataCommandSupport.DependencyCoordinate> directExternalRuntimeDependencies(ResolvedComponentResult rootComponent) {
+        List<MissingMetadataCommandSupport.DependencyCoordinate> dependencies = new ArrayList<>();
+        for (DependencyResult dependency : rootComponent.getDependencies()) {
+            if (dependency instanceof ResolvedDependencyResult) {
+                ResolvedComponentResult selected = ((ResolvedDependencyResult) dependency).getSelected();
+                if (selected.getId() instanceof ModuleComponentIdentifier) {
+                    ModuleVersionIdentifier moduleVersion = selected.getModuleVersion();
+                    dependencies.add(new MissingMetadataCommandSupport.DependencyCoordinate(
+                        moduleVersion.getGroup(),
+                        moduleVersion.getName(),
+                        moduleVersion.getVersion()
+                    ));
+                }
+            }
+        }
+        return dependencies;
+    }
+
+    private void writeReport(String reportJson) throws IOException {
+        if (getReportFile().get().getAsFile().getParentFile() != null) {
+            Files.createDirectories(getReportFile().get().getAsFile().getParentFile().toPath());
+        }
+        Files.writeString(getReportFile().get().getAsFile().toPath(), reportJson, StandardCharsets.UTF_8);
+    }
+}