Add common utils CI gate

Author: jvukicev

.github/workflows/test-common-utils.yml

@@ -0,0 +1,52 @@
+# Pull request common utilities gate: checkstyle and unit tests for shared build-tool-neutral code.
+# §AR-repository-ci.1.7; §common/E2E-common-tests.2.1
+name: "Test common-utils"
+
+on:
+  pull_request:
+    paths:
+      - 'common/utils/**'
+      - 'build-logic/common-plugins/**'
+      - 'build-logic/settings-plugins/**'
+      - 'build-logic/utils-plugins/**'
+      - 'config/checkstyle.xml'
+      - '.github/actions/**'
+      - '.github/workflows/test-common-utils.yml'
+      - 'gradle/libs.versions.toml'
+      - 'settings.gradle.kts'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "workflow = ${{ github.workflow }}, ref = ${{ github.event.ref }}, pr = ${{ github.event.pull_request.id }}"
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.repository != 'graalvm/native-build-tools' }}
+
+jobs:
+  test-common-utils:
+    name: "Test common-utils"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        java-version: [ 17.0.12 ]
+        os: [ ubuntu-22.04 ]
+    steps:
+      - name: "☁️ Checkout repository"
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: "🔧 Prepare environment"
+        uses: ./.github/actions/prepare-environment
+        with:
+          java-version: ${{ matrix.java-version }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: "❓ Checkstyle"
+        run: ./gradlew :utils:checkstyleMain :utils:checkstyleTest
+      - name: "❓ Common utilities test"
+        run: ./gradlew :utils:test
+      - name: "📜 Upload tests results"
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: tests-results-${{ strategy.job-index }}-${{ matrix.java-version }}-${{ matrix.os }}
+          path: common/utils/build/reports/tests/

common/docs/e2e.md

@@ -18,7 +18,8 @@ repository check is:
 For focused common validation, run the relevant included build task, such as `:utils:test`,
 `:graalvm-reachability-metadata:test`, or `:junit-platform-native:test` from the common build
 context. Use the repository CI workflows in [§root/AR-repository-ci.1.5](../../docs/spec/architecture/ci.md#15-reachability-metadata-library-pr-workflow) and
-[§root/AR-repository-ci.1.6](../../docs/spec/architecture/ci.md#16-junit-native-support-pr-workflow) as the merge-gate equivalents.
+[§root/AR-repository-ci.1.6](../../docs/spec/architecture/ci.md#16-junit-native-support-pr-workflow), and
+[§root/AR-repository-ci.1.7](../../docs/spec/architecture/ci.md#17-common-utilities-pr-workflow) as the merge-gate equivalents.
 
 ## 2. Scenario Coverage
 
@@ -50,9 +51,13 @@ compatibility-mode support. This protects [§root/FS-native-tests.3](../../docs/
 
 ## 3. CI coverage
 
+`test-common-utils.yml` validates the shared utility module with checkstyle and unit tests.
 `test-graalvm-metadata.yml` validates the reachability metadata library with checkstyle and unit
 tests. `test-junit-platform-native.yml` validates the JUnit native support module with checkstyle,
 JVM tests, and native tests. Product plugin CI also exercises common behavior through Gradle and
 Maven functional-test matrices. These workflow gates are specified by
-[§root/AR-repository-ci.1.5](../../docs/spec/architecture/ci.md#15-reachability-metadata-library-pr-workflow), [§root/AR-repository-ci.1.6](../../docs/spec/architecture/ci.md#16-junit-native-support-pr-workflow),
-[§root/AR-repository-ci.1.3](../../docs/spec/architecture/ci.md#13-gradle-plugin-pr-workflow), and [§root/AR-repository-ci.1.4](../../docs/spec/architecture/ci.md#14-maven-plugin-pr-workflow).
+[§root/AR-repository-ci.1.7](../../docs/spec/architecture/ci.md#17-common-utilities-pr-workflow),
+[§root/AR-repository-ci.1.5](../../docs/spec/architecture/ci.md#15-reachability-metadata-library-pr-workflow),
+[§root/AR-repository-ci.1.6](../../docs/spec/architecture/ci.md#16-junit-native-support-pr-workflow),
+[§root/AR-repository-ci.1.3](../../docs/spec/architecture/ci.md#13-gradle-plugin-pr-workflow), and
+[§root/AR-repository-ci.1.4](../../docs/spec/architecture/ci.md#14-maven-plugin-pr-workflow).

common/utils/src/test/java/org/graalvm/buildtools/utils/FileUtilsTest.java

@@ -46,27 +46,37 @@
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ValueSource;
 
+import java.io.ByteArrayInputStream;
 import java.io.File;
 import java.io.IOException;
+import java.io.InputStream;
+import java.net.HttpURLConnection;
 import java.net.URL;
+import java.net.URLConnection;
+import java.net.URLStreamHandler;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 import java.util.stream.Stream;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+// Protects common utility verification for download and extraction behavior. §FS-common-libraries.8.
 class FileUtilsTest {
 
     @Test
     @DisplayName("It can download a file from a URL that exists")
     void testDownloadOk(@TempDir Path tempDir) throws IOException {
-        URL url = new URL("https://github.com/graalvm/native-build-tools/archive/refs/heads/master.zip");
+        URL url = url("https://example.test/archive/master.zip", ok("archive payload")
+                .header("Content-Disposition", "attachment; filename=native-build-tools-master.zip"));
         List<String> errorLogs = new ArrayList<>();
 
         Optional<Path> download = FileUtils.download(url, tempDir, errorLogs::add);
@@ -80,7 +90,7 @@ void testDownloadOk(@TempDir Path tempDir) throws IOException {
     @Test
     @DisplayName("It doesn't blow up with a URL that isn't a file download")
     void testDownloadNoFile(@TempDir Path tempDir) throws IOException {
-        URL url = new URL("https://httpbin.org/html");
+        URL url = url("https://example.test/html", ok("<html></html>"));
         List<String> errorLogs = new ArrayList<>();
 
         Optional<Path> download = FileUtils.download(url, tempDir, errorLogs::add);
@@ -94,7 +104,7 @@ void testDownloadNoFile(@TempDir Path tempDir) throws IOException {
     @Test
     @DisplayName("It doesn't blow up with a URL that does not exist")
     void testDownloadNotFound(@TempDir Path tempDir) throws IOException {
-        URL url = new URL("https://google.com/notfound");
+        URL url = url("https://example.test/notfound", response(HttpURLConnection.HTTP_NOT_FOUND, "Not Found"));
         List<String> errorLogs = new ArrayList<>();
 
         Optional<Path> download = FileUtils.download(url, tempDir, errorLogs::add);
@@ -107,7 +117,12 @@ void testDownloadNotFound(@TempDir Path tempDir) throws IOException {
     @Test
     @DisplayName("It doesn't blow up with connection timeouts")
     void testDownloadTimeout(@TempDir Path tempDir) throws IOException {
-        URL url = new URL("https://httpbin.org/delay/10");
+        URL url = url("https://example.test/delay", new TestHttpURLConnection("https://example.test/delay") {
+            @Override
+            public int getResponseCode() throws IOException {
+                throw new IOException("Read timed out");
+            }
+        });
         List<String> errorLogs = new ArrayList<>();
 
         Optional<Path> download = FileUtils.download(url, tempDir, errorLogs::add);
@@ -173,4 +188,76 @@ void testExtractNonZip(String format, @TempDir Path tempDir) {
         assertEquals("Unsupported archive format: src/test/resources/graalvm-reachability-metadata." + format + ". Only ZIP files are supported", errorLogs.get(0));
     }
 
+    private static URL url(String spec, HttpURLConnection connection) throws IOException {
+        return new URL(null, spec, new URLStreamHandler() {
+            @Override
+            protected URLConnection openConnection(URL url) {
+                return connection;
+            }
+        });
+    }
+
+    private static TestHttpURLConnection ok(String body) {
+        return response(HttpURLConnection.HTTP_OK, "OK").body(body);
+    }
+
+    private static TestHttpURLConnection response(int responseCode, String responseMessage) {
+        return new TestHttpURLConnection("https://example.test", responseCode, responseMessage);
+    }
+
+    private static class TestHttpURLConnection extends HttpURLConnection {
+        private final Map<String, String> headers = new HashMap<>();
+        private byte[] body = new byte[0];
+
+        TestHttpURLConnection(String spec) {
+            this(spec, HTTP_OK, "OK");
+        }
+
+        TestHttpURLConnection(String spec, int responseCode, String responseMessage) {
+            super(toUrl(spec));
+            this.responseCode = responseCode;
+            this.responseMessage = responseMessage;
+        }
+
+        TestHttpURLConnection header(String name, String value) {
+            headers.put(name, value);
+            return this;
+        }
+
+        TestHttpURLConnection body(String body) {
+            this.body = body.getBytes(StandardCharsets.UTF_8);
+            return this;
+        }
+
+        @Override
+        public String getHeaderField(String name) {
+            return headers.get(name);
+        }
+
+        @Override
+        public InputStream getInputStream() {
+            return new ByteArrayInputStream(body);
+        }
+
+        @Override
+        public void disconnect() {
+        }
+
+        @Override
+        public boolean usingProxy() {
+            return false;
+        }
+
+        @Override
+        public void connect() {
+        }
+
+        private static URL toUrl(String spec) {
+            try {
+                return new URL(spec);
+            } catch (IOException e) {
+                throw new IllegalArgumentException(e);
+            }
+        }
+    }
 }

common/utils/src/test/java/org/graalvm/buildtools/utils/SchemaValidationUtilsTest.java

@@ -58,7 +58,7 @@ class SchemaValidationUtilsTest {
 
     @Test
     @DisplayName("validateSchemas succeeds when required schemas with exact majors are present")
-    void validateSchemas_successExactMajors(@TempDir Path tempDir) throws IOException {
+    void validateSchemasSuccessExactMajors(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-success");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -73,15 +73,15 @@ void validateSchemas_successExactMajors(@TempDir Path tempDir) throws IOExceptio
 
     @Test
     @DisplayName("validateSchemas fails when 'schemas' directory is missing")
-    void validateSchemas_missingSchemasDir(@TempDir Path tempDir) {
+    void validateSchemasMissingSchemasDir(@TempDir Path tempDir) {
         Path repoRoot = tempDir.resolve("repo-missing");
         // Do not create 'schemas' directory
         assertThrows(IllegalStateException.class, () -> SchemaValidationUtils.validateSchemas(repoRoot));
     }
 
     @Test
     @DisplayName("validateSchemas fails when repository provides an older required major")
-    void validateSchemas_metadataTooOld(@TempDir Path tempDir) throws IOException {
+    void validateSchemasMetadataTooOld(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-too-old");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -95,7 +95,7 @@ void validateSchemas_metadataTooOld(@TempDir Path tempDir) throws IOException {
 
     @Test
     @DisplayName("validateSchemas fails when repository provides a newer required major")
-    void validateSchemas_toolsTooOld(@TempDir Path tempDir) throws IOException {
+    void validateSchemasToolsTooOld(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-tools-too-old");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -109,7 +109,7 @@ void validateSchemas_toolsTooOld(@TempDir Path tempDir) throws IOException {
 
     @Test
     @DisplayName("validateSchemas fails when more schema files than supported are present (excluding reachability)")
-    void validateSchemas_tooManySchemasExcludingReachability(@TempDir Path tempDir) throws IOException {
+    void validateSchemasTooManySchemasExcludingReachability(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-too-many");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -126,7 +126,7 @@ void validateSchemas_tooManySchemasExcludingReachability(@TempDir Path tempDir)
 
     @Test
     @DisplayName("validateReachabilityMetadataSchema does nothing when neither side provides the schema")
-    void validateReachabilitySchema_neitherSideProvided(@TempDir Path tempDir) throws IOException {
+    void validateReachabilitySchemaNeitherSideProvided(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-none");
         Files.createDirectories(repoRoot.resolve("schemas"));
 
@@ -138,7 +138,7 @@ void validateReachabilitySchema_neitherSideProvided(@TempDir Path tempDir) throw
 
     @Test
     @DisplayName("validateReachabilityMetadataSchema fails when repository provides schema but GraalVM does not")
-    void validateReachabilitySchema_repoOnly(@TempDir Path tempDir) throws IOException {
+    void validateReachabilitySchemaRepoOnly(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-only");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -180,7 +180,7 @@ void validateReachabilitySchemaRepoOnlyOnMacOsX64Jdk21(@TempDir Path tempDir) th
 
     @Test
     @DisplayName("validateReachabilityMetadataSchema warns when GraalVM provides schema but repository does not")
-    void validateReachabilitySchema_graalOnly(@TempDir Path tempDir) throws IOException {
+    void validateReachabilitySchemaGraalOnly(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-no-schema");
         Files.createDirectories(repoRoot.resolve("schemas"));
         // No reachability schema file in repo
@@ -193,7 +193,7 @@ void validateReachabilitySchema_graalOnly(@TempDir Path tempDir) throws IOExcept
 
     @Test
     @DisplayName("validateReachabilityMetadataSchema succeeds when versions match")
-    void validateReachabilitySchema_match_ok(@TempDir Path tempDir) throws IOException {
+    void validateReachabilitySchemaMatchOk(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-match");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);
@@ -206,7 +206,7 @@ void validateReachabilitySchema_match_ok(@TempDir Path tempDir) throws IOExcepti
 
     @Test
     @DisplayName("validateReachabilityMetadataSchema fails when versions mismatch")
-    void validateReachabilitySchema_mismatch(@TempDir Path tempDir) throws IOException {
+    void validateReachabilitySchemaMismatch(@TempDir Path tempDir) throws IOException {
         Path repoRoot = tempDir.resolve("repo-mismatch");
         Path schemas = repoRoot.resolve("schemas");
         Files.createDirectories(schemas);

docs/spec/architecture/ci.md

@@ -17,6 +17,7 @@ tests prepare both a build JDK and a GraalVM test JDK through [§AR-repository-c
 | `test-native-maven-plugin.yml` | Maven plugin, samples, common modules, workflow/action changes, and shared version catalog changes. | Maven functional tests plus GraalVM dev-build functional tests. [§AR-repository-ci.1.4](ci.md#14-maven-plugin-pr-workflow) |
 | `test-graalvm-metadata.yml` | Reachability metadata common module and relevant workflow/action changes. | Checkstyle and unit tests for the metadata repository library. [§AR-repository-ci.1.5](ci.md#15-reachability-metadata-library-pr-workflow) |
 | `test-junit-platform-native.yml` | JUnit native support and relevant workflow/action changes. | Checkstyle, JVM tests, and native tests for `common/junit-platform-native`. [§AR-repository-ci.1.6](ci.md#16-junit-native-support-pr-workflow) |
+| `test-common-utils.yml` | Common utilities, relevant shared build setup, and relevant workflow/action changes. | Checkstyle and unit tests for `common/utils`. [§AR-repository-ci.1.7](ci.md#17-common-utilities-pr-workflow) |
 
 ### 1.1 Grund validation workflow
 
@@ -62,6 +63,15 @@ unit tests. It protects the repository query and missing-metadata behavior speci
 tests, and native tests. It protects the shared native-test runtime behavior specified by
 [§FS-native-tests.3](../functional/native-tests.md#3-native-launcher-and-feature).
 
+### 1.7 Common utilities PR workflow
+
+`test-common-utils.yml` validates `common/utils` with checkstyle and unit tests. It protects the
+shared utility behavior specified by [§common/FS-common-libraries.1](../../../common/docs/functional-spec.md#1-shared-native-image-utilities),
+[§common/FS-common-libraries.2](../../../common/docs/functional-spec.md#2-resource-configuration),
+[§common/FS-common-libraries.3](../../../common/docs/functional-spec.md#3-native-image-tracing-agent),
+[§common/FS-common-libraries.4](../../../common/docs/functional-spec.md#4-agent-metadata-post-processing), and
+[§common/FS-common-libraries.7](../../../common/docs/functional-spec.md#7-schema-validation).
+
 ## 2. Publication workflows
 
 | Workflow | Scope | Required evidence |