This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-dependency-plugin.git
commit af1a7603b87d69f04dca399aa93152686d16d749 Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sat Nov 14 13:01:47 2026 +0100 Correct requireExplicitDependencies docs and check undeclared items before version lookup A versionless item that no dependency declares used to fail in the version lookup with "Unable to find artifact version" instead of the violation list. An item range no longer matches a declared version, because the goal resolves the range to the highest available version, which may not be the declared one. --- .../child-b/pom.xml | 7 ++++ .../require-explicit-dependencies-copy-pom/pom.xml | 2 +- .../verify.groovy | 4 +-- .../AbstractFromConfigurationMojo.java | 39 +++++++++++++++------- .../ExplicitDependencyMatcher.java | 28 ++++++++++++---- src/site/markdown/usage.md.vm | 4 +-- .../ExplicitDependencyMatcherTest.java | 27 ++++++++++++--- .../TestRequireExplicitDependencies.java | 14 ++++++++ 8 files changed, 98 insertions(+), 27 deletions(-) diff --git a/src/it/projects/require-explicit-dependencies-copy-pom/child-b/pom.xml b/src/it/projects/require-explicit-dependencies-copy-pom/child-b/pom.xml index ae297181..595da2ed 100644 --- a/src/it/projects/require-explicit-dependencies-copy-pom/child-b/pom.xml +++ b/src/it/projects/require-explicit-dependencies-copy-pom/child-b/pom.xml @@ -46,6 +46,13 @@ <artifactId>child-a</artifactId> <version>1.0-SNAPSHOT</version> <type>pom</type> + <scope>provided</scope> + <exclusions> + <exclusion> + <groupId>*</groupId> + <artifactId>*</artifactId> + </exclusion> + </exclusions> </dependency> </dependencies> diff --git a/src/it/projects/require-explicit-dependencies-copy-pom/pom.xml b/src/it/projects/require-explicit-dependencies-copy-pom/pom.xml index da86ae30..052458ff 100644 --- a/src/it/projects/require-explicit-dependencies-copy-pom/pom.xml +++ b/src/it/projects/require-explicit-dependencies-copy-pom/pom.xml @@ -35,7 +35,7 @@ <name>Require explicit dependencies (pom declaration)</name> <description> - Test dependency:unpack with requireExplicitDependencies + Test dependency:copy with requireExplicitDependencies </description> <properties> diff --git a/src/it/projects/require-explicit-dependencies-copy-pom/verify.groovy b/src/it/projects/require-explicit-dependencies-copy-pom/verify.groovy index aac47286..a3e713b3 100644 --- a/src/it/projects/require-explicit-dependencies-copy-pom/verify.groovy +++ b/src/it/projects/require-explicit-dependencies-copy-pom/verify.groovy @@ -17,7 +17,7 @@ * under the License. */ -File unpacked = new File( basedir, "child-b/target/dependency/child-a-1.0-SNAPSHOT.jar" ) -assert unpacked.isFile() : "Missing file " + unpacked +File copied = new File( basedir, "child-b/target/dependency/child-a-1.0-SNAPSHOT.jar" ) +assert copied.isFile() : "Missing file " + copied return true; diff --git a/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/AbstractFromConfigurationMojo.java b/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/AbstractFromConfigurationMojo.java index 109e1cf2..382c2035 100644 --- a/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/AbstractFromConfigurationMojo.java +++ b/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/AbstractFromConfigurationMojo.java @@ -145,13 +145,25 @@ public abstract class AbstractFromConfigurationMojo extends AbstractDependencyMo * Fail if an item of {@code artifactItems} (or the {@code artifact} configured in the POM) is not declared as a * dependency of the project, or is declared with a different version. Maven orders the reactor by the declared * dependencies, not by plugin configuration, so an undeclared item that is built by another module of the reactor - * may be missing or stale. Declare such an item as a dependency, for example with scope {@code provided} or - * {@code test}. A dependency of type {@code pom} with the same groupId, artifactId and version also satisfies the - * check for any type and classifier, and keeps the artifact off the classpath, but then the artifact is not - * visible in {@code dependency:tree} or SBOMs either. Items match on groupId, artifactId, extension and - * classifier, where {@code test-jar} equals {@code jar} with the classifier {@code tests}. A version range - * matches a version it contains. The check does not apply to a goal invoked from the command line, such as - * {@code mvn dependency:copy -Dartifact=...}. + * may be missing or stale. Declare such an item as a dependency with scope {@code provided} or {@code test}. + * <p> + * A dependency of type {@code pom} with the same groupId, artifactId and version also satisfies the check for + * any type and classifier. Such a declaration adds the transitive dependencies of the module to the classpath + * (with the declared scope, {@code compile} by default) and shows as {@code g:a:pom:v} in + * {@code dependency:tree}. Use scope {@code provided} or {@code test} and, to avoid the transitive dependencies, + * an exclusion of {@code *:*}. + * </p> + * <p> + * Items match on groupId, artifactId, extension and classifier, where {@code test-jar} equals {@code jar} with + * the classifier {@code tests}. An item without a version matches a declaration of any version. A version + * range in the declaration matches an item version it contains; a version range in an item matches only an + * identical declaration, as the goal resolves it to the highest available version. + * </p> + * <p> + * The check does not apply when the goal is invoked directly from the command line, such as + * {@code mvn dependency:copy}. An execution that is bound to the lifecycle is checked, even when the property is + * given on the command line. + * </p> * * @since 3.12.0 */ @@ -195,7 +207,8 @@ public abstract class AbstractFromConfigurationMojo extends AbstractDependencyMo /** * Fails if {@link #requireExplicitDependencies} is set and an item is not declared as a dependency. Must run - * after {@link #verifyRequirements()} and before anything is resolved. + * after {@link #verifyRequirements()}. Nothing is resolved for an item whose groupId and artifactId are not + * declared at all; a missing version of any other item is looked up first. * * @throws MojoFailureException if an item is not declared * @throws MojoExecutionException if a missing version cannot be determined @@ -208,14 +221,16 @@ public abstract class AbstractFromConfigurationMojo extends AbstractDependencyMo getLog().warn("requireExplicitDependencies is ignored when the goal is invoked from the command line"); return; } + ExplicitDependencyMatcher matcher = new ExplicitDependencyMatcher( + artifactHandlerManager, getProject().getDependencies()); for (ArtifactItem item : artifactItems) { - if (item.getVersion() == null || item.getVersion().isEmpty()) { + // An item that is not declared in any variant is a violation anyway; the version lookup would only fail + // with "Unable to find artifact version" instead of listing it. + if ((item.getVersion() == null || item.getVersion().isEmpty()) && matcher.isDeclaredInAnyVariant(item)) { fillMissingArtifactVersion(item); } } - List<String> violations = new ExplicitDependencyMatcher( - artifactHandlerManager, getProject().getDependencies()) - .findViolations(artifactItems); + List<String> violations = matcher.findViolations(artifactItems); if (!violations.isEmpty()) { throw new MojoFailureException("requireExplicitDependencies is set, but artifactItems must be " + "declared as dependencies of the project, so that Maven orders the reactor by them:" diff --git a/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcher.java b/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcher.java index 65644f8e..c5166b70 100644 --- a/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcher.java +++ b/src/main/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcher.java @@ -36,8 +36,10 @@ import org.apache.maven.model.Dependency; * Items and dependencies are compared on groupId, artifactId, extension and classifier. The type is translated with * the artifact handler, so {@code type=test-jar} equals {@code type=jar} with {@code classifier=tests}. The type * defaults to {@code jar} and an empty classifier is no classifier. A declared dependency of type {@code pom} - * matches every type and classifier. An item without a version matches regardless of the declared version, and a - * version range matches a version it contains. + * matches every type and classifier. An item without a version matches regardless of the declared version. A declared + * version range matches an item version it contains; an item version range is only matched by an identical + * declaration, because the goal resolves such a range to the highest available version, which may not be the + * declared one. */ final class ExplicitDependencyMatcher { private final ArtifactHandlerManager artifactHandlerManager; @@ -96,14 +98,28 @@ final class ExplicitDependencyMatcher { + version; } + /** + * Returns whether the project declares a dependency with the groupId and artifactId of the item, of any type, + * classifier and version. + * + * @param item the item to look up + * @return {@code true} if there is such a dependency + */ + boolean isDeclaredInAnyVariant(ArtifactItem item) { + for (Dependency dependency : declared) { + if (Objects.equals(item.getGroupId(), dependency.getGroupId()) + && Objects.equals(item.getArtifactId(), dependency.getArtifactId())) { + return true; + } + } + return false; + } + static boolean versionsMatch(String itemVersion, String declaredVersion) { if (itemVersion.equals(declaredVersion)) { return true; } - if (declaredVersion == null) { - return false; - } - return contains(declaredVersion, itemVersion) || contains(itemVersion, declaredVersion); + return declaredVersion != null && contains(declaredVersion, itemVersion); } private static boolean contains(String rangeSpec, String version) { diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index b11afec0..43050050 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -38,7 +38,7 @@ This goal is meant to be bound to a lifecycle phase and configured in your `pom. The artifact version is optional. If not set, the plugin will attempt to resolve it from the project dependencies and then the dependencyManagement section. -Set `requireExplicitDependencies` (`-Dmdep.requireExplicitDependencies=true`) to fail the build when an artifact item is not declared in the `dependencies` of the project, or is declared with another version. Maven orders the modules of a reactor build by the declared dependencies, not by plugin configuration, so an undeclared item built by another module can be missing or stale. A dependency of type `pom` with the same groupId, artifactId and version satisfies the check for any type and [...] +Set `requireExplicitDependencies` (`-Dmdep.requireExplicitDependencies=true`) to fail the build when an artifact item is not declared in the `dependencies` of the project, or is declared with another version. Maven orders the modules of a reactor build by the declared dependencies, not by plugin configuration, so an undeclared item built by another module can be missing or stale. Declare the item with scope `provided` or `test`. A dependency of type `pom` with the same groupId, artifactI [...] See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwriting is handled. @@ -196,7 +196,7 @@ See the [Overwrite Rules](#Overwrite_Rules) section for rules about how overwrit The artifact version is optional. If not set, the plugin will attempt to resolve it from the project dependencies and then the dependencyManagement section. -Set `requireExplicitDependencies` (`-Dmdep.requireExplicitDependencies=true`) to fail the build when an artifact item is not declared in the `dependencies` of the project, or is declared with another version. Maven orders the modules of a reactor build by the declared dependencies, not by plugin configuration, so an undeclared item built by another module can be missing or stale. A dependency of type `pom` with the same groupId, artifactId and version satisfies the check for any type and [...] +Set `requireExplicitDependencies` (`-Dmdep.requireExplicitDependencies=true`) to fail the build when an artifact item is not declared in the `dependencies` of the project, or is declared with another version. Maven orders the modules of a reactor build by the declared dependencies, not by plugin configuration, so an undeclared item built by another module can be missing or stale. Declare the item with scope `provided` or `test`. A dependency of type `pom` with the same groupId, artifactI [...] Configure the plugin something like this if you intend to bind it to execute along with your build: diff --git a/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcherTest.java b/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcherTest.java index 211f0012..61831969 100644 --- a/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcherTest.java +++ b/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/ExplicitDependencyMatcherTest.java @@ -184,21 +184,40 @@ class ExplicitDependencyMatcherTest { } @Test - void rangeMatchesContainedVersionInBothDirections() { + void declaredRangeMatchesAContainedItemVersion() { assertTrue( check(Collections.singletonList(dependency("a", "[1.0,2.0)", null, null)), item("a", "1.5", null, null)) .isEmpty()); - assertTrue( - check(Collections.singletonList(dependency("a", "1.5", null, null)), item("a", "[1.0,2.0)", null, null)) - .isEmpty()); assertEquals( 1, check(Collections.singletonList(dependency("a", "[1.0,2.0)", null, null)), item("a", "2.0", null, null)) .size()); + } + + @Test + void itemRangeMatchesOnlyAnIdenticalDeclaration() { + // the goal resolves the range to the highest available version, which may not be the declared one + assertEquals( + 1, + check(Collections.singletonList(dependency("a", "1.5", null, null)), item("a", "[1.0,2.0)", null, null)) + .size()); assertEquals( 1, check(Collections.singletonList(dependency("a", "2.0", null, null)), item("a", "[1.0,2.0)", null, null)) .size()); + assertTrue(check( + Collections.singletonList(dependency("a", "[1.0,2.0)", null, null)), + item("a", "[1.0,2.0)", null, null)) + .isEmpty()); + } + + @Test + void detectsAnyVariantOfAnItem() { + ExplicitDependencyMatcher matcher = new ExplicitDependencyMatcher( + handlers, Collections.singletonList(dependency("a", "1.0", "zip", "resources"))); + + assertTrue(matcher.isDeclaredInAnyVariant(item("a", null, "jar", null))); + assertTrue(!matcher.isDeclaredInAnyVariant(item("b", null, "jar", null))); } @Test diff --git a/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/TestRequireExplicitDependencies.java b/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/TestRequireExplicitDependencies.java index e3e12926..ffb5b1b7 100644 --- a/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/TestRequireExplicitDependencies.java +++ b/src/test/java/org/apache/maven/plugins/dependency/fromConfiguration/TestRequireExplicitDependencies.java @@ -136,4 +136,18 @@ class TestRequireExplicitDependencies { assertTrue(e.getMessage().contains("is declared as a dependency with version 1.0, not 2.0"), e.getMessage()); } + + @Test + @InjectMojo(goal = "copy") + @MojoParameter(name = "requireExplicitDependencies", value = "true") + void listsAVersionlessItemThatIsNotDeclaredWithoutLookingUpItsVersion(CopyMojo mojo) throws Exception { + setSource(mojo, lifecycleExecution()); + mojo.getProject().setDependencies(Collections.singletonList(dependency("a", "1.0", "jar", null))); + mojo.setArtifactItems(Collections.singletonList(item("undeclared", null, "jar", null))); + + MojoFailureException e = assertThrows(MojoFailureException.class, mojo::execute); + + assertTrue(e.getMessage().contains("g:undeclared"), e.getMessage()); + assertTrue(e.getMessage().contains("is not declared as a dependency of the project"), e.getMessage()); + } }
