[MNG-8686] Add SourceRoot.matcher(boolean) method (apache#2236)

The matcher returned by that method combines the effects of all includes and excludes.

When using the Maven syntax, escape the special characters [ ] { } \ before to delegate to the glob syntax.
Optimization: omit excludes that are unnecessary because they will never match a file accepted by includes.
This is especially useful when the default excludes are added, because there is a lot of them.

---------

Co-authored-by: VIP <8830888+Pankraz76@users.noreply.github.com>

Author: 2 people

api/maven-api-core/src/main/java/org/apache/maven/api/SourceRoot.java

@@ -19,6 +19,8 @@
 package org.apache.maven.api;
 
 import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 
@@ -45,30 +47,47 @@ default Path directory() {
     }
 
     /**
-     * {@return the list of pattern matchers for the files to include}.
+     * {@return the list of patterns for the files to include}.
      * The path separator is {@code /} on all platforms, including Windows.
-     * The patterns are used to match paths relative to the {@code directory}.
-     * The prefix before the {@code :} character, if present, is the syntax.
-     * If no syntax is specified, the default is a Maven-specific variation
-     * of the {@code "glob"} pattern.
+     * The prefix before the {@code :} character, if present and longer than 1 character, is the syntax.
+     * If no syntax is specified, or if its length is 1 character (interpreted as a Windows drive),
+     * the default is a Maven-specific variation of the {@code "glob"} pattern.
      *
      * <p>
      * The default implementation returns an empty list, which means to apply a language-dependent pattern.
      * For example, for the Java language, the pattern includes all files with the {@code .java} suffix.
+     *
+     * @see java.nio.file.FileSystem#getPathMatcher(String)
      */
     default List<String> includes() {
         return List.of();
     }
 
     /**
-     * {@return the list of pattern matchers for the files to exclude}.
+     * {@return the list of patterns for the files to exclude}.
      * The exclusions are applied after the inclusions.
      * The default implementation returns an empty list.
      */
     default List<String> excludes() {
         return List.of();
     }
 
+    /**
+     * {@return a matcher combining the include and exclude patterns}.
+     * If the user did not specify any includes, the given {@code defaultIncludes} are used.
+     * These defaults depend on the plugin.
+     * For example, the default include of the Java compiler plugin is <code>"**&sol;*.java"</code>.
+     *
+     * <p>If the user did not specify any excludes, the default is often files generated
+     * by Source Code Management (<abbr>SCM</abbr>) software or by the operating system.
+     * Examples: <code>"**&sol;.gitignore"</code>, <code>"**&sol;.DS_Store"</code>.</p>
+     *
+     * @param defaultIncludes the default includes if unspecified by the user
+     * @param useDefaultExcludes whether to add the default set of patterns to exclude,
+     *        mostly Source Code Management (<abbr>SCM</abbr>) files
+     */
+    PathMatcher matcher(Collection<String> defaultIncludes, boolean useDefaultExcludes);
+
     /**
      * {@return in which context the source files will be used}.
      * Not to be confused with dependency scope.

impl/maven-impl/src/main/java/org/apache/maven/impl/DefaultSourceRoot.java

@@ -19,6 +19,8 @@
 package org.apache.maven.impl;
 
 import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.Collection;
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
@@ -140,9 +142,9 @@ public DefaultSourceRoot(final ProjectScope scope, final Language language, fina
      * @param scope scope of source code (main or test)
      * @param language language of the source code
      * @param directory directory of the source code
-     * @param includes list of patterns for the files to include, or {@code null} if unspecified
-     * @param excludes list of patterns for the files to exclude, or {@code null} if unspecified
-     * */
+     * @param includes patterns for the files to include, or {@code null} or empty if unspecified
+     * @param excludes patterns for the files to exclude, or {@code null} or empty if nothing to exclude
+     */
     public DefaultSourceRoot(
             final ProjectScope scope,
             final Language language,
@@ -183,7 +185,7 @@ public Path directory() {
     }
 
     /**
-     * {@return the list of pattern matchers for the files to include}.
+     * {@return the patterns for the files to include}.
      */
     @Override
     @SuppressWarnings("ReturnOfCollectionOrArrayField") // Safe because unmodifiable
@@ -192,14 +194,30 @@ public List<String> includes() {
     }
 
     /**
-     * {@return the list of pattern matchers for the files to exclude}.
+     * {@return the patterns for the files to exclude}.
      */
     @Override
     @SuppressWarnings("ReturnOfCollectionOrArrayField") // Safe because unmodifiable
     public List<String> excludes() {
         return excludes;
     }
 
+    /**
+     * {@return a matcher combining the include and exclude patterns}.
+     *
+     * @param defaultIncludes the default includes if unspecified by the user
+     * @param useDefaultExcludes whether to add the default set of patterns to exclude,
+     *        mostly Source Code Management (<abbr>SCM</abbr>) files
+     */
+    @Override
+    public PathMatcher matcher(Collection<String> defaultIncludes, boolean useDefaultExcludes) {
+        Collection<String> actual = includes();
+        if (actual == null || actual.isEmpty()) {
+            actual = defaultIncludes;
+        }
+        return new PathSelector(directory(), actual, excludes(), useDefaultExcludes).simplify();
+    }
+
     /**
      * {@return in which context the source files will be used}.
      */