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());
+    }
 }

Reply via email to