GraalVM Reachability Metadata

Forge is an automation system located in the forge/ directory designed to resolve GitHub issues in the oracle/graalvm-reachability-metadata repository. It uses LLM-based agents to generate or repair library tests and GraalVM reachability metadata, aiming to increase library coverage and shorten the time from issue report to shipped metadata.

Supported Issue-Resolution Queues

Forge automates the following workflows based on specific GitHub labels:

1. New library support (library-new-request): Generates a JUnit (or Kotlin/Scala) test suite and produces reachability metadata for previously unsupported libraries.
2. Coverage improvement (library-update-request): Increases dynamic-access coverage for existing libraries.
3. Code coverage improvement: A planned workflow that uses GraalVM PGO runtime profiles to broaden ordinary API and execution coverage (distinct from dynamic-access coverage).
4. Java compilation fixes (fails-javac-compile): Repairs test sources that fail to compile after a library version bump.
5. Java runtime fixes (fails-java-run): Repairs JVM-mode test failures caused by library version updates.
6. Native-image runtime fixes (fails-native-image-run): Updates reachability metadata to ensure nativeTest passes against new library versions.

Note: Forge only handles tasks that result in reachability metadata or supporting tests for the reachability repository.

The repository is composed of several specialized components that manage the lifecycle of metadata:

To ensure quality, compare the dynamic-access coverage between the old and new versions using stats.json files.

Comparison Rules

1. Use Percentages Only: Compare dynamicAccess.coverageRatio or the percentage reported in the PR description. You may also compare the dynamicAccess.breakdown for specific types (reflection, resources, proxies, serialization, JNI).
2. Ignore Absolute Counts: Do not treat changes in absolute coveredCalls or totalCalls as regressions. Only use these numbers to calculate the percentage.
3. The 20% Rule: A coverage percentage drop of more than 20 percentage points is a blocking issue. A drop of 20 points or less is acceptable.
4. Do Not Second-Guess: Do not use user-code-filter.json, agent configuration, or metadata contents to argue against the reported stats. Use the values as reported in the stats.json files.

If stats are missing or stale, request the generateLibraryStats job or relevant CI stats before approving.

When contributing metadata, you must adhere to these strict formatting and structural rules:

• Metadata-only bundles: Files must contain only JSON entries for GraalVM's manual-configuration. Build-time tweaks like native-image.properties are forbidden.
• Conditional registration: Every entry must use a condition with the key typeReached. The older typeReachable is invalid and will be rejected by checkMetadataFiles.
• Allowed-package conditions: The typeReached condition must reference a class within the artifact's allowed-packages.
• No test-only entries: Metadata describing types from a test suite must not be shipped. Use splitTestOnlyMetadata to move these to src/test/resources/META-INF/native-image/reachability-metadata.json.
• Index coverage: Each metadata/<group>/<artifact>/ directory must include a valid index.json enumerating metadata versions and tested library versions.
• Single latest entry: Exactly one entry in a non-empty index.json must have latest: true.

{
  "condition": {
    "typeReached": "com.example.MyClass"
  }
}

The metadata/ directory contains the curated GraalVM reachability metadata that native-build-tools resolves and passes to native-image. The metadata is purely additive: it fills in registrations that native-image would otherwise miss and must never change how a consumer's code runs.

Directory Layout

• metadata/<groupId>/<artifactId>/index.json: A JSON array for each supported artifact. It defines how native-build-tools selects a metadata version using fields like tested-versions, allowed-packages, latest, requires, and language.
• metadata/<groupId>/<artifactId>/<metadata-version>/reachability-metadata.json: The actual file loaded by native-image. It contains reflection, jni, resources, bundles, serialization, and foreignCalls entries in a single-file format. Note: Legacy split-config files (e.g., reflect-config.json) are not used here.
• metadata/library-and-framework-list.json: The master list of all supported libraries and their test_level.
• metadata/schemas/: Vendored JSON schemas used for validation.

When a test exercises behavior that fundamentally relies on open-ended dynamic class loading that native-image cannot support (such as loading classes, JARs, or generated bytecode discovered only after build), you must use a specific error handling pattern.

Acceptable Pattern: Use the NativeImageSupport.isUnsupportedFeatureError(e) catch pattern from org.graalvm.internal.tck.

Rejected Patterns:

• Raw native-only skips.
• Bare catch (Error) blocks.
• Using the isUnsupportedFeatureError pattern for ordinary reflection, resources, serialization, dynamic proxies, JNI, or missing reachability metadata.

try {
    // code that triggers unsupported dynamic loading
} catch (Error e) {
    if (org.graalvm.internal.tck.NativeImageSupport.isUnsupportedFeatureError(e)) {
        // Acceptable way to handle truly unsupported dynamic features
    } else {
        throw e;
    }
}