Treat not-for-native-image metadata as covered

[jormundur00]

Summary

Closes #883.

This change teaches list-libraries-missing-metadata to treat reachability metadata repository entries marked with "not-for-native-image": true as covered, even though those entries intentionally do not provide metadata configuration files to copy.

The motivating case is artifacts such as Netty's io.netty:netty-transport-native-io_uring. The repository can contain an index.json entry explaining that the artifact is not itself a native-image metadata target and, optionally, pointing users/tools to the replacement artifact that carries the JVM classes.

New acceptable index.json shape

Normal metadata entries still use the existing shape with metadata-version and version matching fields:

[
  {
    "tested-versions": ["3.1.2"],
    "metadata-version": "3.1.2",
    "latest": true
  }
]

Those entries resolve to an actual metadata directory and continue to return DirectoryConfiguration instances as before.

This PR adds support for a special marker-only entry:

[
  {
    "not-for-native-image": true,
    "reason": "The main JAR contains only module metadata, and platform classifier JARs carry native libraries; the JVM io_uring transport classes are published separately.",
    "replacement": "io.netty:netty-transport-classes-io_uring:4.2.1.Final"
  }
]

Supported fields for this special shape:

• not-for-native-image: required boolean marker. When true, the repository is explicitly saying this artifact should not have native-image metadata files.
• reason: optional human-readable explanation.
• replacement: optional Maven coordinates for a replacement or related artifact that should be considered instead.

The marker can also be scoped with existing index matching fields:

[
  {
    "not-for-native-image": true,
    "tested-versions": ["4.2.1.Final"],
    "reason": "Only this version is known to be a marker artifact.",
    "replacement": "io.netty:netty-transport-classes-io_uring:4.2.1.Final"
  }
]

[
  {
    "not-for-native-image": true,
    "default-for": "4\\.2\\..*",
    "reason": "All 4.2.x native transport marker artifacts are covered by the replacement classes artifact."
  }
]

[
  {
    "not-for-native-image": true,
    "latest": true,
    "reason": "Use this as the latest known marker entry when the requested version is untested."
  }
]

If no version matching field is present, the marker applies generally to that artifact.

Why this change is needed

Before this PR, MissingMetadataCommandSupport treated a dependency as supported only when:

repository.findConfigurationsFor(...)

returned a non-empty set.

That conflates two different cases:

1. The dependency has no repository entry and should be reported as missing.
2. The dependency has a repository entry saying it is intentionally not applicable to native-image metadata.

For case 2, returning a fake DirectoryConfiguration would be the wrong abstraction because metadata copy and native-image configuration paths should not copy anything. There are no config files for marker-only entries.

This PR separates the two questions:

• findConfigurationsFor(...): returns real metadata directories to copy, unchanged.
• isCoveredByRepository(...): answers whether the repository covers the artifact for reporting purposes.

The default isCoveredByRepository(...) implementation preserves existing behavior by checking whether findConfigurationsFor(...) is non-empty. FileSystemRepository overrides it to also recognize not-for-native-image entries.

Implementation details

• Added GraalVMReachabilityMetadataRepository.isCoveredByRepository(...) with default behavior based on findConfigurationsFor(...).
• Updated MissingMetadataCommandSupport to call isCoveredByRepository(...) when deciding whether to report a dependency as supported or missing.
• Added parsing for not-for-native-image in the artifact index model.
• Added VersionToConfigDirectoryIndex.isNotForNativeImage(...) so the filesystem repository can identify marker-only coverage.
• Implemented FileSystemRepository.isCoveredByRepository(...) so it checks normal metadata matches first, then falls back to marker-only coverage.
• Updated the Gradle reachability metadata service wrapper to delegate the new coverage method to the underlying repository.

Important behavior preserved: findConfigurationsFor(...) still returns no configuration for not-for-native-image marker entries. This means metadata-copy/native-image configuration materialization remains unchanged.

Testing

Ran the focused shared metadata tests and Gradle plugin compile check with JDK 17:

JAVA_HOME=/home/jovan/.sdkman/candidates/java/17.0.12-graal ./gradlew :graalvm-reachability-metadata:test --tests '*SingleModuleJsonVersionToConfigDirectoryIndexTest' --tests '*FileSystemRepositoryTest' --tests '*MissingMetadataCommandSupportTest' :native-gradle-plugin:compileJava

The test run passed and covered:

• parsing not-for-native-image index entries;
• filesystem repository coverage for marker-only entries;
• ensuring findConfigurationsFor(...) still returns no config directories for marker-only entries;
• ensuring MissingMetadataCommandSupport reports marker-only entries as supported;
• compiling the Gradle plugin wrapper that delegates isCoveredByRepository(...).

Note: the currently active Java 25 runtime fails during Gradle/Kotlin DSL initialization in this checkout, so the verification command was run with the installed JDK 17.

[vjovanov]

This should change the specification?

[jormundur00]

This should change the specification?

I would not add this to the docs, as we don't regard the look of the metadata repo index.json files here. We should probably add this to a functional spec on this repo, but as we have none at the moment, I would deffer that to a follow-up PR.