Merge 1.0-M1 branch to master

.github/actions/setup-native-build-tools/action.yml

@@ -6,7 +6,7 @@ inputs:
   enabled-by-default:
     description: "Whether to enable this setup step even if no same-named branch is found."
     required: false
-    default: "false"
+    default: "true" # TODO: Revert to "false" once the 0.11.5 release of NBT is on the central maven repository
   java-version:
     description: "Java version to use when building native-build-tools"
     required: false

.github/workflows/index-file-validation.yml

@@ -20,7 +20,6 @@ jobs:
         uses: ./.github/actions/detect-file-changes
         with:
           file-patterns: |
-            - 'metadata/index.json'
             - 'metadata/*/*/index.json'
 
       - name: "🔧 Setup Java"

build.gradle

@@ -44,6 +44,7 @@ spotless {
                 .version("2.9.0")
     }
     String[] noHeaderDirs = [
+            'native-build-tools/**', // external repository
             'docs/**',     // only .md files
             'metadata/**', // only .json files
             '**/build/**', // not relevant

docs/CONTRIBUTING.md

@@ -88,132 +88,58 @@ It's expected that they fail, because the scaffold task only generated a stub wh
 
 ### Metadata structure
 
-Metadata lives in a folder structure in the `metadata` directory in root of this repository.
-Per convention, it should be like this: `org.example:library` metadata should be located
-at `metadata/org.example/library`.
-Every metadata has an entry in the `metadata/index.json`. For example:
+Metadata lives in a folder structure in the `metadata` directory at the root of this repository. Per convention, metadata for `org.example:library` is located at `metadata/org.example/library`.
 
-```json
-[
-  ...
-  {
-    "directory": "org.example/library",
-    "module": "org.example:library"
-  },
-  {
-    "module": "org.example:dependant-library",
-    "requires": [
-      "org.example:library"
-    ],
-    "allowed-packages": [
-       "org.package.name"
-     ]
-  }
-]
-```
+Each artifact directory **must** include an `index.json` file (at `metadata/<groupId>/<artifactId>/index.json`). This file is a JSON array of objects where each entry describes a specific metadata release.
+
+#### Index Entry Fields
 
-**Note:** `dependant-library` can feature its own metadata as well if `directory` key is specified.
+**Required Keys:**
+* `metadata-version`: Specifies the subdirectory where the GraalVM configuration files (e.g., `reflect-config.json`) reside.
+* `tested-versions`: An array of library versions verified to work with this specific metadata.
+* `allowed-packages`: An array of package prefixes. The TCK ensures that configuration entries (like reflection targets) belong strictly to these packages.
 
-**Note:** `allowed-packages` describes which packages are expected to contain metadata entries. This way you can prevent metadata from other libraries to be
-pulled into your config files
+**Optional Keys:**
+* `latest`: Boolean. If `true`, this is the default metadata version for the artifact.
+* `requires`: An array of `groupId:artifactId` coordinates for libraries this metadata depends on.
+* `default-for`: A Java-format regex used to match library versions if no exact match exists in `tested-versions` (e.g., `"0\\.0\\..*"`).
+* `test-version`: Defines the subdirectory in `tests/src` containing the test code. Use this to share a single test suite across multiple metadata versions.
+* `skipped-versions`: An array of objects (with `version` and `reason`) to explicitly exclude library versions known to be broken or incompatible.
+* `override`: Boolean. If `true`, excludes outdated builtin GraalVM metadata.
 
-Every library metadata has another `index.json` file.
-In aforementioned case that would be `metadata/org.example/library/index.json`.
-It should contain the following entries:
+#### Comprehensive Example
 
 ```json
 [
   {
-    "metadata-version": "0.0.1",
-    "module": "org.example:library",
-    "tested-versions": [
-      "0.0.1",
-      "0.0.2"
-    ]
-  },
-  {
-    "latest": true,
+    "allowed-packages": ["org.example.library"],
     "metadata-version": "1.0.0",
-    "module": "org.example:library",
     "tested-versions": [
       "1.0.0",
-      "1.1.0-M1",
-      "1.1.0"
+      "1.0.1"
+    ],
+    "skipped-versions": [
+      {
+        "version": "1.0.5",
+        "reason": "Integrated reflect-config.json does not parse."
+      }
     ]
   },
-  ...
+  {
+     "latest": true,
+     "override": true,
+     "allowed-packages": ["org.example.library"],
+     "metadata-version": "1.1.0",
+     "test-version": "1.0.0",
+     "tested-versions": [
+       "1.1.0",
+       "1.1.1"
+    ],
+     "requires": ["org.slf4j:slf4j-api"]
+  }
 ]
 ```
 
-The `metadata-version` key specifies the subdirectory where metadata for tested versions "lives".
-The `override` flag allows to express the intent to exclude outdated builtin metadata when set to `true`.
-So, the metadata for `org.example:library:0.0.1` and `org.example:library:0.0.2` is located
-at `metadata/org.example/library/0.0.1`.
-
-For entries without `"latest": true`, it is recommended to define the optional `default-for` key with a value containing
-a regexp (Java format) matching the version pattern. For example, for the example above, the first entry could be:
-
-```json
-{
-   "metadata-version": "0.0.1",
-   "module": "org.example:library",
-   "tested-versions": [
-      "0.0.1",
-      "0.0.2"
-   ],
-   "default-for": "0\\.0\\..*"
-}
-```
-
-The optional `test-version` key can be used to explicitly define the subdirectory containing 
-the test code for a library version. This is useful when multiple versions of a library's metadata 
-share the same tests, allowing for code reuse and preventing test code duplication. 
-An example of the library above using this field:
-
-```json
-{
-  "metadata-version": "1.1.0",
-  "module": "org.example:library",
-  "test-version": "1.0.0",
-  "tested-versions": [
-    "1.1.0",
-    "1.1.1",
-    "1.1.2"
-  ]
-}
-```
-
-The optional `skipped-versions` key can be used to explicitly exclude specific
-library versions from being considered as supported metadata. A skipped version
-should include both the version and the reason it is excluded. This is useful
-when a version exists in Maven but is known to be broken, incompatible, or
-should be omitted from testing for any other reason. An example of the library
-above using this field:
-
-```json
-{
-  "metadata-version": "1.0.0",
-  "module": "org.example:library",
-  "tested-versions": [
-    "1.0.0",
-    "1.1.0"
-  ],
-  "skipped-versions": [
-    {
-      "version": "1.0.5",
-      "reason": "Known incompatible API change."
-    },
-    {
-      "version": "1.0.7",
-      "reason": "Integrated reflect-config.json does not parse."
-    }
-  ]
-}
-```
-
-You can also list each supported version is listed in `tested-versions`, as that value is used in build tools to match
-metadata to a specific library, but this is more likely to break when new versions are released.
-
 ### Format Metadata Files
 
 Metadata must be correctly formatted.

docs/DEVELOPING.md

@@ -137,7 +137,7 @@ Examples:
 ### Fix failing tasks
 
 Use this when a library's new version causes native-image run test failures. The task will:
-- Update the module's metadata index.json to mark the new version as latest
+- Update the artifact's metadata index.json to mark the new version as latest
 - Ensure the tests project has an agent block and a user-code-filter.json if missing
 - Run the agent to collect metadata, then re-run tests (with a retry if needed)
 

docs/REVIEWING.md

@@ -60,5 +60,5 @@ All metadata files **must** be covered by the tests. Every metadata file should:
 * not have entries that describes classes that serve only for tests 
 
 There are various tools that could help checking the content of all json files we are collecting.
-To run these checks automatically, top-level metadata index file must contain `allowed-packages` properly set ([see this](CONTRIBUTING.md#metadata-structure)).
+To run these checks automatically, the artifact-level index file at `metadata/<groupId>/<artifactId>/index.json` must include `allowed-packages` properly set ([see this](CONTRIBUTING.md#metadata-structure)).
 If this field is properly configured, our GitHub workflows will automatically check `typeReachable` and origin of all entries in all config files.

metadata/berkeleydb/je/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages" : [
+      "com.sleepycat"
+    ],
     "metadata-version": "3.2.76",
-    "module": "berkeleydb:je",
     "tested-versions": [
       "3.2.76"
     ]

metadata/ch.qos.logback.contrib/logback-jackson/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
     "metadata-version": "0.1.5",
-    "module": "ch.qos.logback.contrib:logback-jackson",
     "tested-versions": [
       "0.1.5"
     ]

metadata/ch.qos.logback.contrib/logback-json-classic/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
     "metadata-version": "0.1.5",
-    "module": "ch.qos.logback.contrib:logback-json-classic",
     "tested-versions": [
       "0.1.5"
     ]

metadata/ch.qos.logback/logback-classic/index.json

@@ -1,7 +1,9 @@
 [
   {
     "latest" : true,
-    "module" : "ch.qos.logback:logback-classic",
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
     "metadata-version" : "1.5.7",
     "test-version" : "1.4.1",
     "tested-versions" : [
@@ -14,10 +16,12 @@
     ]
   },
   {
-    "module" : "ch.qos.logback:logback-classic",
-    "metadata-version" : "1.4.9",
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
+    "metadata-version": "1.4.9",
     "test-version": "1.4.1",
-    "tested-versions" : [
+    "tested-versions": [
       "1.4.9",
       "1.4.10",
       "1.4.11",
@@ -34,18 +38,22 @@
     ]
   },
   {
-    "module" : "ch.qos.logback:logback-classic",
-    "default-for" : "1\\.4\\.[0-8]",
-    "metadata-version" : "1.4.1",
-    "tested-versions" : [
+    "default-for": "1\\.4\\.[0-8]",
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
+    "metadata-version": "1.4.1",
+    "tested-versions": [
       "1.4.1"
     ]
   },
   {
-    "module" : "ch.qos.logback:logback-classic",
-    "default-for" : "1\\.[0-3]\\..*",
-    "metadata-version" : "1.2.11",
-    "tested-versions" : [
+    "default-for": "1\\.[0-3]\\..*",
+    "allowed-packages": [
+      "ch.qos.logback"
+    ],
+    "metadata-version": "1.2.11",
+    "tested-versions": [
       "1.2.11"
     ]
   }

metadata/com.atomikos/transactions/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages" : [
+      "com.atomikos"
+    ],
     "metadata-version": "6.0.0",
-    "module": "com.atomikos:transactions",
     "tested-versions": [
       "6.0.0"
     ]

metadata/com.ecwid.consul/consul-api/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages": [
+      "com.ecwid"
+    ],
     "metadata-version": "1.4.5",
-    "module": "com.ecwid.consul:consul-api",
     "tested-versions": [
       "1.4.5"
     ]

metadata/com.fasterxml.jackson.core/jackson-databind/index.json

@@ -1,9 +1,14 @@
 [
   {
-    "latest" : true,
-    "module" : "com.fasterxml.jackson.core:jackson-databind",
-    "metadata-version" : "2.15.2",
-    "tested-versions" : [
+    "latest": true,
+    "allowed-packages": [
+      "com.fasterxml.jackson",
+      "java.sql",
+      "javax.xml",
+      "org.w3c.dom"
+    ],
+    "metadata-version": "2.15.2",
+    "tested-versions": [
       "2.15.2",
       "2.15.4",
       "2.16.0",

metadata/com.github.ben-manes.caffeine/caffeine/index.json

@@ -1,9 +1,11 @@
 [
   {
-    "latest" : true,
-    "module" : "com.github.ben-manes.caffeine:caffeine",
-    "metadata-version" : "3.1.2",
-    "tested-versions" : [
+    "latest": true,
+    "allowed-packages": [
+      "com.github.benmanes.caffeine"
+    ],
+    "metadata-version": "3.1.2",
+    "tested-versions": [
       "3.1.2",
       "3.1.3",
       "3.1.4",
@@ -18,9 +20,11 @@
     ]
   },
   {
-    "module" : "com.github.ben-manes.caffeine:caffeine",
-    "metadata-version" : "2.9.3",
-    "tested-versions" : [
+    "allowed-packages": [
+      "com.github.benmanes.caffeine"
+    ],
+    "metadata-version": "2.9.3",
+    "tested-versions": [
       "2.9.3"
     ]
   }

metadata/com.github.luben/zstd-jni/index.json

@@ -1,8 +1,10 @@
 [
   {
     "latest": true,
+    "allowed-packages": [
+      "com.github.luben"
+    ],
     "metadata-version": "1.5.2-5",
-    "module": "com.github.luben:zstd-jni",
     "tested-versions": [
       "1.5.2-5"
     ]