Implementation note (PR #877, merged design): the command is named listLibrariesMissingMetadata (Gradle task) / native:list-libraries-missing-metadata (Maven goal). Token resolution adds a fourth fallback: gh auth token after the env vars. Console output is grouped by status (already requested / created / needs request / errors) with a prominent createIssues=true call-to-action and footnote-style URLs, rather than the flat list shown in this design doc. Default report file: list-libraries-missing-metadata.json.

Summary

Add a new standalone command to both Native Build Tools plugins that scans the project's direct external runtime dependencies, detects libraries that have no matching reachability metadata in the configured metadata repository, and by default lists the missing libraries with links to open library-new-request issues in oracle/graalvm-reachability-metadata.

This command should be documented as the primary user entry point for metadata support checks: every user should run listLibrariesMissingMetadata first to see what is not supported before switching to tracing-agent workflows or manual metadata troubleshooting.

Automatic issue creation remains in scope, but only as explicit opt-in:

A library is considered missing when querying the metadata repository for group:artifact:version with the existing useLatestConfigWhenVersionIsUntested behavior still returns no configuration.

Key Changes

New Commands

• Gradle task: listLibrariesMissingMetadata
• Maven goal: native:list-libraries-missing-metadata

Metadata Repository Integration

• Use the existing metadata repository resolution/configuration already used by both plugins
• Reuse current metadata repository URI/version/local-path settings
• Fail fast if the metadata repository is disabled or cannot be resolved
• Use repository lookup as the source of truth, not library-and-framework-list.json

Candidate Selection

Direct external runtime dependencies only:

Excluded: Project components, file dependencies, test-only dependencies, and metadata-repository excluded modules.

Shared Detection/Reporting Logic

Add shared detection/reporting logic in common code used by both plugins:

• Input: direct dependency coordinates, metadata repository accessor, excluded-module config, GitHub settings, createIssues flag
• Output: structured per-library results with statuses:
  • supported
  • missing
  • existing_open_issue
  • new_issue_link_generated
  • created_issue
  • error

Default Behavior (List-Only)

For each missing dependency, print:

• group:artifact:version
• Whether an open metadata-repo issue already exists
• Either the existing issue URL or a prefilled "open new issue" URL

Do not create issues unless explicitly enabled.

Opt-In Automatic Issue Creation

When createIssues=true:

1. Search for existing open issues first
2. Create only missing ones

GitHub Integration

Implement GitHub lookup and optional issue creation with direct HTTP/REST calls from Java:

• Search open issues in the target repo and parse existing library-new-request requests from issue title/body
• Treat any open issue for the same group:artifact as an existing request and skip creation
• Use metadata-repo issue conventions:

Issue Format:

Title: Support for group:artifact:version

Body:
### Full Maven coordinates

group:artifact:version

_This issue was created by automation._

Label: library-new-request

Prefilled Issue Links (Default Mode)

• Use the metadata repo's 01_support_new_library.yml issue template
• Prefill title and Maven coordinates
• If an open issue already exists for the same group:artifact, print that issue URL instead

Command Options

Default report file locations:

Token Handling

• List-only mode should work without a token if issue lookup is disabled or unauthenticated access is sufficient
• If issue lookup or issue creation needs authentication, token lookup order:

Output

Emit both console output and a deterministic JSON report:

• Console output is human-readable and short
• JSON report is stable and testable

Documentation Placement

Make listLibrariesMissingMetadata the key support-check command in the docs, not just a reference task/goal.

Top-Level Docs Intro

File: docs/src/docs/asciidoc/index.adoc

Add a short "Check library support first" callout near the top-level docs intro:

• Purpose: Establish the user flow early
• Message: Before troubleshooting missing metadata manually, run listLibrariesMissingMetadata to see which direct dependencies are unsupported

Troubleshoot Missing Configuration Sections

Add a new first step in the "Troubleshoot Missing Configuration" sections:

Positioning: This becomes Step 0 / first recommendation before --exact-reachability-metadata, runtime warning flags, or tracing-agent instructions.

Plugin Reference Sections

Add a dedicated reference section in both plugin manuals close to the metadata-repository material:

Content:

• What the command does
• Default list mode
• Optional createIssues=true
• Report file location
• Example output

Consistent Wording

"Run this first to see which direct dependencies are not supported by the reachability metadata repository."

Report Format

JSON Report (Default List Mode)

{
  "command": "listLibrariesMissingMetadata",
  "mode": "list",
  "targetRepository": "oracle/graalvm-reachability-metadata",
  "metadataRepositoryUri": "https://github.com/oracle/graalvm-reachability-metadata/releases/download/0.3.20/graalvm-reachability-metadata-0.3.20.zip",
  "scannedAt": "2026-04-08T14:32:11Z",
  "project": {
    "buildTool": "gradle",
    "name": "demo-app"
  },
  "summary": {
    "scanned": 6,
    "supported": 3,
    "missing": 3,
    "existingOpenIssue": 1,
    "newIssueLinks": 2,
    "createdIssues": 0,
    "errors": 0
  },
  "results": [
    {
      "coordinates": "org.springframework:spring-core:6.2.1",
      "scope": "direct-runtime",
      "status": "supported"
    },
    {
      "coordinates": "com.fasterxml.jackson.core:jackson-databind:2.18.2",
      "scope": "direct-runtime",
      "status": "supported"
    },
    {
      "coordinates": "org.example:custom-sdk:1.4.0",
      "scope": "direct-runtime",
      "status": "missing",
      "issueStatus": "new_issue_link_generated",
      "issueUrl": "https://github.com/oracle/graalvm-reachability-metadata/issues/new?template=01_support_new_library.yml&title=Support%20for%20org.example%3Acustom-sdk%3A1.4.0&maven_coordinates=org.example%3Acustom-sdk%3A1.4.0"
    },
    {
      "coordinates": "io.acme:acme-client:3.1.0",
      "scope": "direct-runtime",
      "status": "missing",
      "issueStatus": "existing_open_issue",
      "issueUrl": "https://github.com/oracle/graalvm-reachability-metadata/issues/4123",
      "issueNumber": 4123
    },
    {
      "coordinates": "dev.sample:sample-cache:0.9.7",
      "scope": "direct-runtime",
      "status": "missing",
      "issueStatus": "new_issue_link_generated",
      "issueUrl": "https://github.com/oracle/graalvm-reachability-metadata/issues/new?template=01_support_new_library.yml&title=Support%20for%20dev.sample%3Asample-cache%3A0.9.7&maven_coordinates=dev.sample%3Asample-cache%3A0.9.7"
    },
    {
      "coordinates": "org.slf4j:slf4j-api:2.0.16",
      "scope": "direct-runtime",
      "status": "supported"
    }
  ]
}

Console Output

Missing metadata libraries:
Missing metadata libraries: 3 of 6 scanned (1 already requested).

Already requested (no action needed):
  - io.acme:acme-client:3.1.0  -> existing request [E1]

To request support for the remaining 2 libraries automatically, re-run with createIssues=true:

    ./gradlew listLibrariesMissingMetadata -PcreateIssues=true -PgithubToken=<token>

  Token sources tried in order:
    -PgithubToken=...  ->  $GITHUB_TOKEN  ->  $GH_TOKEN  ->  `gh auth token`

Or request support manually, one library at a time:
  - dev.sample:sample-cache:0.9.7  -> request support [1]
  - org.example:custom-sdk:1.4.0   -> request support [2]

  [E1] https://github.com/oracle/graalvm-reachability-metadata/issues/4123
  [1]  https://github.com/oracle/graalvm-reachability-metadata/issues/new?template=01_support_new_library.yml&title=Support+for+dev.sample:sample-cache:0.9.7
  [2]  https://github.com/oracle/graalvm-reachability-metadata/issues/new?template=01_support_new_library.yml&title=Support+for+org.example:custom-sdk:1.4.0

Full report: build/reports/native/list-libraries-missing-metadata.json

Test Plan

Shared Unit Tests

• Repository query classifies supported vs missing correctly
• Existing issue parsing works from both issue title and standardized body
• Duplicate suppression works at group:artifact level
• Prefilled issue-link generation is stable and URL-encoded correctly
• Issue payload generation for createIssues=true matches metadata-repo conventions
• Report serialization matches the agreed schema

Gradle Functional Tests

• Default mode lists unsupported direct dependencies and writes the JSON report
• Default mode does not create issues
• createIssues=true creates issues only for missing direct dependencies
• Existing open issue is reused and no new issue is created
• Supported libraries are omitted from the missing list
• Transitive-only unsupported dependencies are ignored
• Token/auth failure is handled cleanly when creation is requested

Maven Functional Tests

• Same behavior as Gradle using a stub GitHub API endpoint

Documentation Checks

• End-to-end guides present this as the first troubleshooting step
• Plugin manuals contain a dedicated section for the command
• Top-level docs mention the command in the primary user flow
• Examples for list mode and createIssues=true are included

Assumptions and Defaults