This is an automated email from the ASF dual-hosted git repository. gnodet pushed a commit to branch implementation-scope in repository https://gitbox.apache.org/repos/asf/maven.git
commit 1603d11cfae9b2200d9418b94ce111b15b23ed5e Author: Guillaume Nodet <[email protected]> AuthorDate: Mon Nov 9 21:31:36 2026 +0100 Add api and implementation dependency scopes with context-dependent transitivity Add two new dependency scopes for modelVersion 4.2.0+: - api: transitive at both compile and runtime (like compile, with intent) - implementation: non-transitive at compile time, transitive at runtime Transitivity is modeled at the resolver level via per-resolution-scope non-transitive sets, rather than a fixed boolean on DependencyScope. This ensures correct behavior in both reactor builds and published artifacts. The isTransitive() method is removed from DependencyScope as it cannot represent context-dependent transitivity. Consumer POM maps api->compile and implementation->runtime for backward compatibility with Maven 3 consumers. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> --- .../java/org/apache/maven/api/DependencyScope.java | 51 +++++++++++++--------- .../main/java/org/apache/maven/api/PathScope.java | 21 ++++++--- .../scopes/Maven4ScopeManagerConfiguration.java | 51 ++++++++++++---------- .../impl/DefaultConsumerPomBuilder.java | 42 +++++++++++++----- .../scopes/Maven4ScopeManagerConfiguration.java | 51 ++++++++++++---------- 5 files changed, 135 insertions(+), 81 deletions(-) diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java index 311f1ec39e..449ea0d92b 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java +++ b/api/maven-api-core/src/main/java/org/apache/maven/api/DependencyScope.java @@ -46,7 +46,7 @@ public enum DependencyScope { * None. Allows you to declare dependencies (for example to alter reactor build order) but in reality dependencies * in this scope are not part of any path scope. */ - NONE("none", false), + NONE("none"), /** * Undefined. When no scope is explicitly given, UNDEFINED will be used, but its meaning will depend on @@ -54,47 +54,67 @@ public enum DependencyScope { * explicitly managed by this managed dependency, or as a real dependency, in which case, the scope * will default to {@link #COMPILE}. */ - UNDEFINED("", false), + UNDEFINED(""), /** * Compile only. */ - COMPILE_ONLY("compile-only", false), + COMPILE_ONLY("compile-only"), /** * Compile, runtime and test. */ - COMPILE("compile", true), + COMPILE("compile"), /** * Runtime and test. */ - RUNTIME("runtime", true), + RUNTIME("runtime"), /** * Provided. */ - PROVIDED("provided", false), + PROVIDED("provided"), /** * Test compile only. */ - TEST_ONLY("test-only", false), + TEST_ONLY("test-only"), /** * Test compile and test runtime. */ - TEST("test", false), + TEST("test"), /** * Test runtime. */ - TEST_RUNTIME("test-runtime", false), + TEST_RUNTIME("test-runtime"), /** * System scope. */ - SYSTEM("system", false); + SYSTEM("system"), + + /** + * API scope. Dependencies in this scope are part of the project's public API and are + * transitively visible to consumers at both compile time and runtime. + * Only available with {@code modelVersion} 4.2.0 or later. + * + * @since 4.2.0 + */ + API("api"), + + /** + * Implementation scope. Dependencies in this scope are internal implementation details: + * they are available to the project itself at compile time and runtime, but are not + * transitively visible to consumers at compile time. They remain transitively available + * at runtime. + * Only available with {@code modelVersion} 4.2.0 or later. + * + * @since 4.2.0 + */ + IMPLEMENTATION("implementation"); private static final Map<String, DependencyScope> IDS = Collections.unmodifiableMap( Stream.of(DependencyScope.values()).collect(Collectors.toMap(s -> s.id, s -> s))); @@ -111,11 +131,9 @@ public static DependencyScope forId(String id) { } private final String id; - private final boolean transitive; - DependencyScope(String id, boolean transitive) { + DependencyScope(String id) { this.id = id; - this.transitive = transitive; } /** @@ -129,13 +147,6 @@ public String id() { return id; } - /** - * {@return whether dependencies in this scope are included transitively}. - */ - public boolean isTransitive() { - return transitive; - } - /** * {@return whether this scope's {@linkplain #id() id} equals the given identifier}. * diff --git a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java index 34c9158cc6..76d159b98a 100644 --- a/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java +++ b/api/maven-api-core/src/main/java/org/apache/maven/api/PathScope.java @@ -68,10 +68,17 @@ public interface PathScope extends ExtensibleEnum { ProjectScope.MAIN, DependencyScope.COMPILE_ONLY, DependencyScope.COMPILE, - DependencyScope.PROVIDED); + DependencyScope.PROVIDED, + DependencyScope.API, + DependencyScope.IMPLEMENTATION); - PathScope MAIN_RUNTIME = - pathScope("main-runtime", ProjectScope.MAIN, DependencyScope.COMPILE, DependencyScope.RUNTIME); + PathScope MAIN_RUNTIME = pathScope( + "main-runtime", + ProjectScope.MAIN, + DependencyScope.COMPILE, + DependencyScope.RUNTIME, + DependencyScope.API, + DependencyScope.IMPLEMENTATION); PathScope TEST_COMPILE = pathScope( "test-compile", @@ -79,7 +86,9 @@ public interface PathScope extends ExtensibleEnum { DependencyScope.COMPILE, DependencyScope.PROVIDED, DependencyScope.TEST_ONLY, - DependencyScope.TEST); + DependencyScope.TEST, + DependencyScope.API, + DependencyScope.IMPLEMENTATION); PathScope TEST_RUNTIME = pathScope( "test-runtime", @@ -88,5 +97,7 @@ public interface PathScope extends ExtensibleEnum { DependencyScope.RUNTIME, DependencyScope.PROVIDED, DependencyScope.TEST, - DependencyScope.TEST_RUNTIME); + DependencyScope.TEST_RUNTIME, + DependencyScope.API, + DependencyScope.IMPLEMENTATION); } diff --git a/compat/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/scopes/Maven4ScopeManagerConfiguration.java b/compat/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/scopes/Maven4ScopeManagerConfiguration.java index a388330763..4b544c11fb 100644 --- a/compat/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/scopes/Maven4ScopeManagerConfiguration.java +++ b/compat/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/scopes/Maven4ScopeManagerConfiguration.java @@ -23,6 +23,7 @@ import java.util.Collection; import java.util.Collections; import java.util.stream.Collectors; +import java.util.stream.Stream; import org.apache.maven.api.DependencyScope; import org.apache.maven.repository.internal.artifact.MavenArtifactProperties; @@ -88,43 +89,35 @@ public BuildScopeSource getBuildScopeSource() { public Collection<org.eclipse.aether.scope.DependencyScope> buildDependencyScopes( InternalScopeManager internalScopeManager) { ArrayList<org.eclipse.aether.scope.DependencyScope> result = new ArrayList<>(); + result.add(internalScopeManager.createDependencyScope(DependencyScope.COMPILE.id(), true, all())); result.add(internalScopeManager.createDependencyScope( - DependencyScope.COMPILE.id(), DependencyScope.COMPILE.isTransitive(), all())); - result.add(internalScopeManager.createDependencyScope( - DependencyScope.RUNTIME.id(), - DependencyScope.RUNTIME.isTransitive(), - byBuildPath(CommonBuilds.BUILD_PATH_RUNTIME))); + DependencyScope.RUNTIME.id(), true, byBuildPath(CommonBuilds.BUILD_PATH_RUNTIME))); result.add(internalScopeManager.createDependencyScope( DependencyScope.PROVIDED.id(), - DependencyScope.PROVIDED.isTransitive(), + false, union( byBuildPath(CommonBuilds.BUILD_PATH_COMPILE), select(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_RUNTIME)))); result.add(internalScopeManager.createDependencyScope( - DependencyScope.TEST.id(), - DependencyScope.TEST.isTransitive(), - byProjectPath(CommonBuilds.PROJECT_PATH_TEST))); - result.add(internalScopeManager.createDependencyScope( - DependencyScope.NONE.id(), DependencyScope.NONE.isTransitive(), Collections.emptySet())); + DependencyScope.TEST.id(), false, byProjectPath(CommonBuilds.PROJECT_PATH_TEST))); + result.add( + internalScopeManager.createDependencyScope(DependencyScope.NONE.id(), false, Collections.emptySet())); result.add(internalScopeManager.createDependencyScope( DependencyScope.COMPILE_ONLY.id(), - DependencyScope.COMPILE_ONLY.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_MAIN, CommonBuilds.BUILD_PATH_COMPILE))); result.add(internalScopeManager.createDependencyScope( DependencyScope.TEST_RUNTIME.id(), - DependencyScope.TEST_RUNTIME.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_RUNTIME))); result.add(internalScopeManager.createDependencyScope( DependencyScope.TEST_ONLY.id(), - DependencyScope.TEST_ONLY.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_COMPILE))); - - // system result.add(internalScopeManager.createSystemDependencyScope( - DependencyScope.SYSTEM.id(), - DependencyScope.SYSTEM.isTransitive(), - all(), - MavenArtifactProperties.LOCAL_PATH)); + DependencyScope.SYSTEM.id(), false, all(), MavenArtifactProperties.LOCAL_PATH)); + result.add(internalScopeManager.createDependencyScope(DependencyScope.API.id(), true, all())); + result.add(internalScopeManager.createDependencyScope(DependencyScope.IMPLEMENTATION.id(), true, all())); // == sanity check if (result.size() != org.apache.maven.api.DependencyScope.values().length - 1) { // sans "undefined" @@ -141,6 +134,18 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope internalScopeManager.getDependencyScopeUniverse(); Collection<org.eclipse.aether.scope.DependencyScope> nonTransitiveDependencyScopes = allDependencyScopes.stream().filter(s -> !s.isTransitive()).collect(Collectors.toSet()); + + // implementation is non-transitive only in compile resolution scopes: + // consumers cannot compile against transitive implementation deps, but they are available at runtime + org.eclipse.aether.scope.DependencyScope implementation = internalScopeManager + .getDependencyScope(DependencyScope.IMPLEMENTATION.id()) + .orElse(null); + Collection<org.eclipse.aether.scope.DependencyScope> nonTransitiveCompileDependencyScopes = + implementation != null + ? Stream.concat(nonTransitiveDependencyScopes.stream(), Stream.of(implementation)) + .collect(Collectors.toSet()) + : nonTransitiveDependencyScopes; + org.eclipse.aether.scope.DependencyScope system = internalScopeManager .getDependencyScope(DependencyScope.SYSTEM.id()) .orElse(null); @@ -157,13 +162,13 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope InternalScopeManager.Mode.ELIMINATE, singleton(CommonBuilds.PROJECT_PATH_MAIN, CommonBuilds.BUILD_PATH_COMPILE), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_MAIN_COMPILE_PLUS_RUNTIME, InternalScopeManager.Mode.ELIMINATE, byProjectPath(CommonBuilds.PROJECT_PATH_MAIN), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_MAIN_RUNTIME, InternalScopeManager.Mode.REMOVE, @@ -181,7 +186,7 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope InternalScopeManager.Mode.ELIMINATE, select(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_COMPILE), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_TEST_RUNTIME, InternalScopeManager.Mode.ELIMINATE, diff --git a/impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/DefaultConsumerPomBuilder.java b/impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/DefaultConsumerPomBuilder.java index 67a869302a..88407286ac 100644 --- a/impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/DefaultConsumerPomBuilder.java +++ b/impl/maven-core/src/main/java/org/apache/maven/internal/transformation/impl/DefaultConsumerPomBuilder.java @@ -22,6 +22,7 @@ import javax.inject.Named; import java.util.ArrayList; +import java.util.Collection; import java.util.LinkedHashMap; import java.util.LinkedHashSet; import java.util.List; @@ -582,15 +583,16 @@ private Model buildEffectiveModel(RepositorySystemSession session, MavenProject } return dependency; }); - // Only keep transitive scopes (null/empty => COMPILE) - directDependencies.values().removeIf(DefaultConsumerPomBuilder::hasDependencyScope); + // Only keep consumer-visible scopes (null/empty => COMPILE), then map api/implementation + directDependencies.values().removeIf(DefaultConsumerPomBuilder::isNonConsumerScope); managedDependencies.keySet().removeAll(directDependencies.keySet()); model = model.withDependencyManagement( managedDependencies.isEmpty() ? null : model.getDependencyManagement().withDependencies(managedDependencies.values())) - .withDependencies(directDependencies.isEmpty() ? null : directDependencies.values()); + .withDependencies( + directDependencies.isEmpty() ? null : mapScopesForConsumerPom(directDependencies.values())); } else { // Even without dependencyManagement, filter direct dependencies to compile/runtime only Map<String, Dependency> directDependencies = model.getDependencies().stream() @@ -600,15 +602,19 @@ private Model buildEffectiveModel(RepositorySystemSession session, MavenProject Function.identity(), this::merge, LinkedHashMap::new)); - // Only keep transitive scopes - directDependencies.values().removeIf(DefaultConsumerPomBuilder::hasDependencyScope); - model = model.withDependencies(directDependencies.isEmpty() ? null : directDependencies.values()); + // Only keep consumer-visible scopes, then map api/implementation + directDependencies.values().removeIf(DefaultConsumerPomBuilder::isNonConsumerScope); + model = model.withDependencies( + directDependencies.isEmpty() ? null : mapScopesForConsumerPom(directDependencies.values())); } return model; } - private static boolean hasDependencyScope(Dependency dependency) { + private static final Set<DependencyScope> CONSUMER_POM_SCOPES = Set.of( + DependencyScope.COMPILE, DependencyScope.RUNTIME, DependencyScope.API, DependencyScope.IMPLEMENTATION); + + private static boolean isNonConsumerScope(Dependency dependency) { String scopeId = dependency.getScope(); DependencyScope scope; if (scopeId == null || scopeId.isEmpty()) { @@ -616,7 +622,23 @@ private static boolean hasDependencyScope(Dependency dependency) { } else { scope = DependencyScope.forId(scopeId); } - return scope == null || !scope.isTransitive(); + return scope == null || !CONSUMER_POM_SCOPES.contains(scope); + } + + private static Dependency mapScopeForConsumerPom(Dependency dependency) { + String scopeId = dependency.getScope(); + if (DependencyScope.API.id().equals(scopeId)) { + return dependency.withScope(DependencyScope.COMPILE.id()); + } else if (DependencyScope.IMPLEMENTATION.id().equals(scopeId)) { + return dependency.withScope(DependencyScope.RUNTIME.id()); + } + return dependency; + } + + private static List<Dependency> mapScopesForConsumerPom(Collection<Dependency> dependencies) { + return dependencies.stream() + .map(DefaultConsumerPomBuilder::mapScopeForConsumerPom) + .collect(Collectors.toList()); } private Dependency merge(Dependency dep1, Dependency dep2) { @@ -860,12 +882,12 @@ static Model inlinePackagingActivatedProfiles(Model model, String packaging) { // Merge additional dependencies into the model, deduplicating by key if (!additionalDeps.isEmpty()) { - additionalDeps.removeIf(DefaultConsumerPomBuilder::hasDependencyScope); + additionalDeps.removeIf(DefaultConsumerPomBuilder::isNonConsumerScope); Map<String, Dependency> mergedDeps = new LinkedHashMap<>(); for (Dependency dep : model.getDependencies()) { mergedDeps.put(getDependencyKey(dep), dep); } - for (Dependency dep : additionalDeps) { + for (Dependency dep : mapScopesForConsumerPom(additionalDeps)) { mergedDeps.putIfAbsent(getDependencyKey(dep), dep); } model = model.withDependencies(mergedDeps.values()); diff --git a/impl/maven-impl/src/main/java/org/apache/maven/impl/resolver/scopes/Maven4ScopeManagerConfiguration.java b/impl/maven-impl/src/main/java/org/apache/maven/impl/resolver/scopes/Maven4ScopeManagerConfiguration.java index 896b240053..1a4f4bc1d0 100644 --- a/impl/maven-impl/src/main/java/org/apache/maven/impl/resolver/scopes/Maven4ScopeManagerConfiguration.java +++ b/impl/maven-impl/src/main/java/org/apache/maven/impl/resolver/scopes/Maven4ScopeManagerConfiguration.java @@ -23,6 +23,7 @@ import java.util.Collection; import java.util.Collections; import java.util.stream.Collectors; +import java.util.stream.Stream; import org.apache.maven.api.DependencyScope; import org.apache.maven.impl.resolver.artifact.MavenArtifactProperties; @@ -86,43 +87,35 @@ public BuildScopeSource getBuildScopeSource() { public Collection<org.eclipse.aether.scope.DependencyScope> buildDependencyScopes( InternalScopeManager internalScopeManager) { ArrayList<org.eclipse.aether.scope.DependencyScope> result = new ArrayList<>(); + result.add(internalScopeManager.createDependencyScope(DependencyScope.COMPILE.id(), true, all())); result.add(internalScopeManager.createDependencyScope( - DependencyScope.COMPILE.id(), DependencyScope.COMPILE.isTransitive(), all())); - result.add(internalScopeManager.createDependencyScope( - DependencyScope.RUNTIME.id(), - DependencyScope.RUNTIME.isTransitive(), - byBuildPath(CommonBuilds.BUILD_PATH_RUNTIME))); + DependencyScope.RUNTIME.id(), true, byBuildPath(CommonBuilds.BUILD_PATH_RUNTIME))); result.add(internalScopeManager.createDependencyScope( DependencyScope.PROVIDED.id(), - DependencyScope.PROVIDED.isTransitive(), + false, union( byBuildPath(CommonBuilds.BUILD_PATH_COMPILE), select(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_RUNTIME)))); result.add(internalScopeManager.createDependencyScope( - DependencyScope.TEST.id(), - DependencyScope.TEST.isTransitive(), - byProjectPath(CommonBuilds.PROJECT_PATH_TEST))); - result.add(internalScopeManager.createDependencyScope( - DependencyScope.NONE.id(), DependencyScope.NONE.isTransitive(), Collections.emptySet())); + DependencyScope.TEST.id(), false, byProjectPath(CommonBuilds.PROJECT_PATH_TEST))); + result.add( + internalScopeManager.createDependencyScope(DependencyScope.NONE.id(), false, Collections.emptySet())); result.add(internalScopeManager.createDependencyScope( DependencyScope.COMPILE_ONLY.id(), - DependencyScope.COMPILE_ONLY.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_MAIN, CommonBuilds.BUILD_PATH_COMPILE))); result.add(internalScopeManager.createDependencyScope( DependencyScope.TEST_RUNTIME.id(), - DependencyScope.TEST_RUNTIME.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_RUNTIME))); result.add(internalScopeManager.createDependencyScope( DependencyScope.TEST_ONLY.id(), - DependencyScope.TEST_ONLY.isTransitive(), + false, singleton(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_COMPILE))); - - // system result.add(internalScopeManager.createSystemDependencyScope( - DependencyScope.SYSTEM.id(), - DependencyScope.SYSTEM.isTransitive(), - all(), - MavenArtifactProperties.LOCAL_PATH)); + DependencyScope.SYSTEM.id(), false, all(), MavenArtifactProperties.LOCAL_PATH)); + result.add(internalScopeManager.createDependencyScope(DependencyScope.API.id(), true, all())); + result.add(internalScopeManager.createDependencyScope(DependencyScope.IMPLEMENTATION.id(), true, all())); // == sanity check if (result.size() != DependencyScope.values().length - 1) { // sans "undefined" @@ -139,6 +132,18 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope internalScopeManager.getDependencyScopeUniverse(); Collection<org.eclipse.aether.scope.DependencyScope> nonTransitiveDependencyScopes = allDependencyScopes.stream().filter(s -> !s.isTransitive()).collect(Collectors.toSet()); + + // implementation is non-transitive only in compile resolution scopes: + // consumers cannot compile against transitive implementation deps, but they are available at runtime + org.eclipse.aether.scope.DependencyScope implementation = internalScopeManager + .getDependencyScope(DependencyScope.IMPLEMENTATION.id()) + .orElse(null); + Collection<org.eclipse.aether.scope.DependencyScope> nonTransitiveCompileDependencyScopes = + implementation != null + ? Stream.concat(nonTransitiveDependencyScopes.stream(), Stream.of(implementation)) + .collect(Collectors.toSet()) + : nonTransitiveDependencyScopes; + org.eclipse.aether.scope.DependencyScope system = internalScopeManager .getDependencyScope(DependencyScope.SYSTEM.id()) .orElse(null); @@ -155,13 +160,13 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope InternalScopeManager.Mode.ELIMINATE, singleton(CommonBuilds.PROJECT_PATH_MAIN, CommonBuilds.BUILD_PATH_COMPILE), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_MAIN_COMPILE_PLUS_RUNTIME, InternalScopeManager.Mode.ELIMINATE, byProjectPath(CommonBuilds.PROJECT_PATH_MAIN), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_MAIN_RUNTIME, InternalScopeManager.Mode.REMOVE, @@ -179,7 +184,7 @@ public Collection<org.eclipse.aether.scope.ResolutionScope> buildResolutionScope InternalScopeManager.Mode.ELIMINATE, select(CommonBuilds.PROJECT_PATH_TEST, CommonBuilds.BUILD_PATH_COMPILE), Collections.singletonList(system), - nonTransitiveDependencyScopes)); + nonTransitiveCompileDependencyScopes)); result.add(internalScopeManager.createResolutionScope( RS_TEST_RUNTIME, InternalScopeManager.Mode.ELIMINATE,
