Recognize bounded JAX-RS roles and unversioned common modules

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: trask

.github/scripts/check-package-names.sh

@@ -64,23 +64,24 @@ check_source_set() {
     fi
 
     if [[ "$source_set" == "javaagent" ]]; then
-      # advice and injected helper packages that must live under the instrumented library's own
-      # namespace, so that they can reach package-private library types and members
+      # advice and injected helper packages that must share a namespace with package-private
+      # library types and members, including library instrumentation helpers
       case "$dir" in
         instrumentation/apache-dbcp-2.0/javaagent/src/main/java/org/apache/commons/dbcp2) continue ;;
         instrumentation/clickhouse/clickhouse-client-v1-0.5/javaagent/src/main/java/com/clickhouse/client | instrumentation/clickhouse/clickhouse-client-v1-0.5/javaagent/src/main/java/com/clickhouse/client/*) continue ;;
         instrumentation/finagle-http-23.11/javaagent/src/main/java/com/twitter/finagle | instrumentation/finagle-http-23.11/javaagent/src/main/java/com/twitter/finagle/*) continue ;;
         instrumentation/finagle-http-23.11/javaagent/src/main/java/io/netty/channel | instrumentation/finagle-http-23.11/javaagent/src/main/java/io/netty/channel/*) continue ;;
         instrumentation/hbase/hbase-client-common-1.0/javaagent/src/main/java/org/apache/hadoop/hbase/ipc) continue ;;
+        instrumentation/jedis/jedis-3.0/javaagent/src/main/java/redis/clients/jedis) continue ;;
         instrumentation/jedis/jedis-4.0/javaagent/src/main/java/redis/clients/jedis) continue ;;
         instrumentation/reactor/reactor-netty/reactor-netty-1.0/javaagent/src/main/java/reactor/netty/http/client | instrumentation/reactor/reactor-netty/reactor-netty-1.0/javaagent/src/main/java/reactor/netty/http/client/*) continue ;;
         instrumentation/redisson/redisson-3.0/javaagent/src/main/java/org/redisson/config) continue ;;
         instrumentation/redisson/redisson-3.17/javaagent/src/main/java/org/redisson/config) continue ;;
-        instrumentation/spring/spring-boot-resources/javaagent/src/main/java/io/opentelemetry/instrumentation/spring/resources) continue ;;
+        instrumentation/rocketmq/rocketmq-client-4.8/javaagent/src/main/java/io/opentelemetry/instrumentation/rocketmqclient/v4_8) continue ;;
         instrumentation/spring/spring-webmvc/spring-webmvc-3.1/javaagent/src/main/java/org/springframework/web/servlet/v3_1 | instrumentation/spring/spring-webmvc/spring-webmvc-3.1/javaagent/src/main/java/org/springframework/web/servlet/v3_1/*) continue ;;
         instrumentation/spring/spring-webmvc/spring-webmvc-6.0/javaagent/src/main/java/org/springframework/web/servlet/v6_0 | instrumentation/spring/spring-webmvc/spring-webmvc-6.0/javaagent/src/main/java/org/springframework/web/servlet/v6_0/*) continue ;;
         instrumentation/tomcat/tomcat-dbcp-8.0/javaagent/src/main/java/org/apache/tomcat/dbcp/dbcp2) continue ;;
-        instrumentation/vertx/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl | instrumentation/vertx/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl/*) continue ;;
+        instrumentation/vertx/vertx-redis-client/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl | instrumentation/vertx/vertx-redis-client/vertx-redis-client-4.0/javaagent/src/main/java/io/vertx/redis/client/impl/*) continue ;;
         instrumentation/vertx/vertx-sql-client/vertx-sql-client-common-4.0/javaagent/src/main/java/io/vertx/sqlclient/impl | instrumentation/vertx/vertx-sql-client/vertx-sql-client-common-4.0/javaagent/src/main/java/io/vertx/sqlclient/impl/*) continue ;;
       esac
 
@@ -95,28 +96,27 @@ check_source_set() {
         instrumentation/opentelemetry-instrumentation-api/opentelemetry-instrumentation-api-1.14/javaagent/*) continue ;;
       esac
 
-      # historical javaagent modules that do not follow the module-name <-> package-name convention
+      # javaagent modules with package layouts that differ from their module names
       case "$dir" in
         instrumentation/hbase/hbase-client-common-1.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/hbase/client/common) continue ;;
         instrumentation/java-http-client/javaagent/*) continue ;;
         instrumentation/java-http-server/javaagent/*) continue ;;
         instrumentation/java-util-logging/javaagent/*) continue ;;
+        instrumentation/jaxrs/jaxrs-1.0-annotations/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/jaxrs/v1_0) continue ;;
       esac
     fi
 
-    # modules whose name does not end with a version digit, either because they have no base
-    # version (e.g. jdbc, netty-common) or because the version is embedded mid-name (e.g.
-    # jaxrs-2.0-annotations); package layout is still derived from the module name below
-    if [[ ! "$module_name" =~ [0-9]$ ]]; then
+    # JAX-RS roles may follow a major.minor version. Unversioned common modules may
+    # have a javax/jakarta variant, but no numeric version token in their prefix.
+    # These rules allow module names; package layout is still checked below.
+    if [[ ! "$module_name" =~ [0-9]$
+      && ! "$module_name" =~ ^jaxrs-[0-9]+\.[0-9]+-(annotations|common)$
+      && ! "$module_name" =~ ^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*-common(-(javax|jakarta))?$ ]]; then
       case "$source_set:$module_name" in
         # library:
         library:jdbc) ;;
-        library:lettuce-common) ;;
-        library:netty-common) ;;
         library:resources) ;;
         library:runtime-telemetry) ;;
-        library:servlet-common) ;;
-        library:servlet-common-javax) ;;
         # javaagent:
         javaagent:executors) ;;
         javaagent:external-annotations) ;;
@@ -126,20 +126,11 @@ check_source_set() {
         javaagent:internal-lambda) ;;
         javaagent:internal-reflection) ;;
         javaagent:internal-url-class-loader) ;;
-        javaagent:jaxrs-2.0-annotations) ;;
-        javaagent:jaxrs-2.0-common) ;;
-        javaagent:jaxrs-3.0-annotations) ;;
-        javaagent:jaxrs-3.0-common) ;;
-        javaagent:jaxrs-common) ;;
         javaagent:jdbc) ;;
-        javaagent:jsf-common-jakarta) ;;
-        javaagent:jsf-common-javax) ;;
         javaagent:methods) ;;
         javaagent:rmi) ;;
         javaagent:runtime-telemetry) ;;
-        javaagent:servlet-common) ;;
         javaagent:spring-boot-resources) ;;
-        javaagent:spring-cloud-gateway-common) ;;
         *)
           echo "module name doesn't have a base version: $dir"
           exit 1

.github/scripts/test-check-package-names.sh

@@ -0,0 +1,74 @@
+#!/bin/bash -e
+
+set -o pipefail
+
+checker_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/check-package-names.sh"
+fixture_dir=$(mktemp -d)
+trap 'rm -rf "$fixture_dir"' EXIT
+
+check_case() {
+  local module_name="$1"
+  local package_name="$2"
+  local expected_error="$3"
+  local output
+
+  rm -rf "$fixture_dir/instrumentation"
+  local source_dir="$fixture_dir/instrumentation/$module_name/$source_set/src/main/java/$expected_prefix/$package_name"
+  mkdir -p "$source_dir"
+  touch "$source_dir/Test.java"
+
+  if output=$(cd "$fixture_dir" && bash -e "$checker_script" 2>&1); then
+    if [[ -n "$expected_error" ]]; then
+      echo "ERROR: unexpectedly accepted $source_set:$module_name/$package_name"
+      exit 1
+    fi
+  elif [[ -z "$expected_error" || "$output" != "$expected_error"* ]]; then
+    echo "ERROR: unexpected failure for $source_set:$module_name/$package_name"
+    echo "$output"
+    exit 1
+  fi
+}
+
+for source_set in library javaagent; do
+  if [[ "$source_set" == "library" ]]; then
+    expected_prefix=io/opentelemetry/instrumentation
+  else
+    expected_prefix=io/opentelemetry/javaagent/instrumentation
+  fi
+
+  while read -r module_name package_name; do
+    check_case "$module_name" "$package_name" ""
+    check_case "$module_name" wrong/package "ERROR:"
+  done <<'EOF'
+jaxrs-1.0-annotations jaxrs/v1_0/annotations
+jaxrs-2.0-annotations jaxrs/v2_0/annotations
+jaxrs-3.0-annotations jaxrs/v3_0/annotations
+jaxrs-2.0-common jaxrs/v2_0/common
+jaxrs-3.0-common jaxrs/v3_0/common
+jaxrs-common jaxrs/common
+jedis-common jedis/common
+lettuce-common lettuce/common
+netty-common netty/common
+servlet-common servlet/common
+spring-cloud-gateway-common spring/cloud/gateway/common
+servlet-common-javax servlet/common/javax
+jsf-common-javax jsf/common/javax
+jsf-common-jakarta jsf/common/jakarta
+EOF
+
+  for module_name in \
+    jaxrs-2-annotations jaxrs-2.0.1-annotations jaxrs-2.0-other \
+    jaxrs-2-common jaxrs-2.0.1-common jaxrs-2.0-common-javax \
+    other-2.0-annotations other-2.0-common other-2-common \
+    other-common-variant other-common-javax-extra other-common-jakarta-extra; do
+    check_case "$module_name" wrong/package "module name doesn't have a base version:"
+  done
+
+  check_case jaxrs-2.0-annotations jaxrs/v2_0 "ERROR:"
+  check_case jaxrs-2.0-annotations jaxrs/v2_0/annotationsExtra "ERROR:"
+  check_case jaxrs-2.0-common jaxrs/v2_0/commonExtra "ERROR:"
+  check_case servlet-common-javax servlet/common/jakarta "ERROR:"
+  check_case jsf-common-jakarta jsf/common/javax "ERROR:"
+done
+
+echo "Package-name rule tests passed"

.github/workflows/build-common.yml

@@ -192,7 +192,9 @@ jobs:
 
       - name: Check package names
         if: ${{ !cancelled() && steps.checkout.outcome == 'success' }}
-        run: .github/scripts/check-package-names.sh
+        run: |
+          .github/scripts/check-package-names.sh
+          bash -e .github/scripts/test-check-package-names.sh
 
   # kept on ubuntu-latest: `gh aw validate` checks container images with `docker pull` and silently
   # skips that when no Docker daemon is available, as on ubuntu-slim

package-name-exceptions-plan.md

@@ -26,6 +26,14 @@ Updated on 2026-09-19 after #20070 added Redisson package-private configuration
 
 Continue reducing package-name checker exceptions in reviewable PRs. Prefer changes where the current package name is only a historical abbreviation and the rename has a small blast radius. Use up to about 40 changed files per package-cleanup PR, while still submitting only four PRs at a time.
 
+## Module-name rules
+
+The checker accepts `jaxrs-<major.minor>-annotations` and `jaxrs-<major.minor>-common` without individual allowlist entries. Other roles, other libraries with a version before the role, and patch-level versions before these roles are not covered by this rule.
+
+Unversioned shared modules may end in `-common`, `-common-javax`, or `-common-jakarta`. The prefix consists of dash-separated tokens starting with a lowercase letter and containing lowercase letters or digits, so this rule does not allow embedded numeric version tokens. Other variant suffixes still require an explicit decision.
+
+Both rules only allow the module name. Expected package names are still derived and checked, subject to the existing package-specific exceptions. Whether a common module needs a minimum dependency version remains a separate module-naming review.
+
 ## Quick Audit Summary
 
 The remaining exceptions fall into four buckets:
@@ -109,7 +117,7 @@ The `servlet-common` library internal package was moved upstream as:
 - #18855: `io.opentelemetry.instrumentation.servlet.internal` -> `io.opentelemetry.instrumentation.servlet.common.internal`.
 
 `external-annotations` still remains in the unversioned-module allowlist as `javaagent:external-annotations`; that is a separate module-name exception, not a historical package exception.
-`spring-boot-resources` keeps a narrow deprecated compatibility-package exception for `io.opentelemetry.instrumentation.spring.resources`; the replacement javaagent package is already present under `io.opentelemetry.javaagent.instrumentation.spring.boot.resources`.
+The deprecated `spring-boot-resources` compatibility wrappers were removed in #20806, so their package exception is no longer needed.
 
 ## PR Creation Notes