[MNG-7038] Introduce public properties to point to to the root and top directory of (multi-module) project

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

@@ -86,8 +86,45 @@ default String getId() {
         return getModel().getId();
     }
 
+    /**
+     * @deprecated use {@link #isTopProject()} instead
+     */
+    @Deprecated
     boolean isExecutionRoot();
 
+    /**
+     * Returns a boolean indicating if the project is the top level project for
+     * this reactor build.  The top level project may be different from the
+     * {@code rootDirectory}, especially if a subtree of the project is being
+     * built, either because Maven has been launched in a subdirectory or using
+     * a {@code -f} option.
+     *
+     * @return {@code true} if the project is the top level project for this build
+     */
+    boolean isTopProject();
+
+    /**
+     * Returns a boolean indicating if the project is a root project,
+     * meaning that the {@link #getRootDirectory()} and {@link #getBasedir()}
+     * points to the same directory, and that either {@link Model#isRoot()}
+     * is {@code true} or that {@code basedir} contains a {@code .mvn} child
+     * directory.
+     *
+     * @return {@code true} if the project is the root project
+     * @see Model#isRoot()
+     */
+    boolean isRootProject();
+
+    /**
+     * Gets the root directory of the project, which is the parent directory
+     * containing the {@code .mvn} directory or flagged with {@code root="true"}.
+     *
+     * @throws IllegalStateException if the root directory could not be found
+     * @see Session#getRootDirectory()
+     */
+    @Nonnull
+    Path getRootDirectory();
+
     @Nonnull
     Optional<Project> getParent();
 

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

@@ -84,9 +84,34 @@ public interface Session {
     @Nonnull
     Instant getStartTime();
 
+    /**
+     * Gets the directory of the topmost project being built, usually the current directory or the
+     * directory pointed at by the {@code -f/--file} command line argument.
+     */
+    @Nonnull
+    Path getTopDirectory();
+
+    /**
+     * Gets the root directory of the session, which is the root directory for the top directory project.
+     *
+     * @throws IllegalStateException if the root directory could not be found
+     * @see #getTopDirectory()
+     * @see Project#getRootDirectory()
+     */
     @Nonnull
+    Path getRootDirectory();
+
+    /**
+     * @deprecated use {@link #getRootDirectory()} instead
+     */
+    @Nonnull
+    @Deprecated
     Path getMultiModuleProjectDirectory();
 
+    /**
+     * @deprecated use {@link #getTopDirectory()} instead
+     */
+    @Deprecated
     @Nonnull
     Path getExecutionRootDirectory();
 
@@ -97,8 +122,8 @@ public interface Session {
      * Returns the plugin context for mojo being executed and the specified
      * {@link Project}, never returns {@code null} as if context not present, creates it.
      *
-     * <strong>Implementation note:</strong> while this method return type is {@link Map}, the returned map instance
-     * implements {@link java.util.concurrent.ConcurrentMap} as well.
+     * <strong>Implementation note:</strong> while this method return type is {@link Map}, the
+     * returned map instance implements {@link java.util.concurrent.ConcurrentMap} as well.
      *
      * @throws org.apache.maven.api.services.MavenException if not called from the within a mojo execution
      */

api/maven-api-model/src/main/mdo/maven.mdo

@@ -212,6 +212,19 @@
           </description>
           <type>String</type>
         </field>
+        <field xml.attribute="true" xml.tagName="root">
+          <name>root</name>
+          <version>4.0.0+</version>
+          <description>
+            <![CDATA[
+            Indicates that this project is the root project, located in the upper directory of the source tree.
+            This is the directory which may contain the .mvn directory.
+            <br><b>Since</b>: Maven 4.0.0
+            ]]>
+          </description>
+          <type>boolean</type>
+          <defaultValue>false</defaultValue>
+        </field>
         <field>
           <name>inceptionYear</name>
           <version>3.0.0+</version>

maven-compat/src/test/java/org/apache/maven/project/TestProjectBuilder.java

@@ -29,6 +29,7 @@
 import org.apache.maven.bridge.MavenRepositorySystem;
 import org.apache.maven.model.building.ModelBuilder;
 import org.apache.maven.model.building.ModelProcessor;
+import org.apache.maven.model.root.RootLocator;
 import org.apache.maven.repository.internal.ModelCacheFactory;
 import org.eclipse.aether.RepositorySystem;
 import org.eclipse.aether.impl.RemoteRepositoryManager;
@@ -45,7 +46,8 @@ public TestProjectBuilder(
             RepositorySystem repoSystem,
             RemoteRepositoryManager repositoryManager,
             ProjectDependenciesResolver dependencyResolver,
-            ModelCacheFactory modelCacheFactory) {
+            ModelCacheFactory modelCacheFactory,
+            RootLocator rootLocator) {
         super(
                 modelBuilder,
                 modelProcessor,
@@ -54,7 +56,8 @@ public TestProjectBuilder(
                 repoSystem,
                 repositoryManager,
                 dependencyResolver,
-                modelCacheFactory);
+                modelCacheFactory,
+                rootLocator);
     }
 
     @Override

maven-core/src/main/java/org/apache/maven/execution/DefaultMavenExecutionRequest.java

@@ -19,6 +19,7 @@
 package org.apache.maven.execution;
 
 import java.io.File;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.HashMap;
@@ -30,6 +31,7 @@
 import org.apache.maven.artifact.repository.ArtifactRepository;
 import org.apache.maven.eventspy.internal.EventSpyDispatcher;
 import org.apache.maven.model.Profile;
+import org.apache.maven.model.root.RootLocator;
 import org.apache.maven.project.DefaultProjectBuildingRequest;
 import org.apache.maven.project.ProjectBuildingRequest;
 import org.apache.maven.properties.internal.SystemProperties;
@@ -102,6 +104,10 @@ public class DefaultMavenExecutionRequest implements MavenExecutionRequest {
 
     private File basedir;
 
+    private Path rootDirectory;
+
+    private Path topDirectory;
+
     private List<String> goals;
 
     private boolean useReactor = false;
@@ -1051,16 +1057,43 @@ public MavenExecutionRequest setToolchains(Map<String, List<ToolchainModel>> too
         return this;
     }
 
+    @Deprecated
     @Override
     public void setMultiModuleProjectDirectory(File directory) {
         this.multiModuleProjectDirectory = directory;
     }
 
+    @Deprecated
     @Override
     public File getMultiModuleProjectDirectory() {
         return multiModuleProjectDirectory;
     }
 
+    @Override
+    public Path getRootDirectory() {
+        if (rootDirectory == null) {
+            throw new IllegalStateException(RootLocator.UNABLE_TO_FIND_ROOT_PROJECT_MESSAGE);
+        }
+        return rootDirectory;
+    }
+
+    @Override
+    public MavenExecutionRequest setRootDirectory(Path rootDirectory) {
+        this.rootDirectory = rootDirectory;
+        return this;
+    }
+
+    @Override
+    public Path getTopDirectory() {
+        return topDirectory;
+    }
+
+    @Override
+    public MavenExecutionRequest setTopDirectory(Path topDirectory) {
+        this.topDirectory = topDirectory;
+        return this;
+    }
+
     @Override
     public MavenExecutionRequest setEventSpyDispatcher(EventSpyDispatcher eventSpyDispatcher) {
         this.eventSpyDispatcher = eventSpyDispatcher;

maven-core/src/main/java/org/apache/maven/execution/MavenExecutionRequest.java

@@ -19,6 +19,7 @@
 package org.apache.maven.execution;
 
 import java.io.File;
+import java.nio.file.Path;
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
@@ -91,8 +92,17 @@ public interface MavenExecutionRequest {
     // ----------------------------------------------------------------------
 
     // Base directory
+
+    /**
+     * @deprecated use {@link #setTopDirectory(Path)} instead
+     */
+    @Deprecated
     MavenExecutionRequest setBaseDirectory(File basedir);
 
+    /**
+     * @deprecated use {@link #getTopDirectory()} instead
+     */
+    @Deprecated
     String getBaseDirectory();
 
     // Timing (remove this)
@@ -494,14 +504,51 @@ public interface MavenExecutionRequest {
 
     /**
      * @since 3.3.0
+     * @deprecated use {@link #setRootDirectory(Path)} instead
      */
+    @Deprecated
     void setMultiModuleProjectDirectory(File file);
 
     /**
      * @since 3.3.0
+     * @deprecated use {@link #getRootDirectory()} instead
      */
+    @Deprecated
     File getMultiModuleProjectDirectory();
 
+    /**
+     * Sets the top directory of the project.
+     *
+     * @since 4.0.0
+     */
+    MavenExecutionRequest setTopDirectory(Path topDirectory);
+
+    /**
+     * Gets the directory of the topmost project being built, usually the current directory or the
+     * directory pointed at by the {@code -f/--file} command line argument.
+     *
+     * @since 4.0.0
+     */
+    Path getTopDirectory();
+
+    /**
+     * Sets the root directory of the project.
+     *
+     * @since 4.0.0
+     */
+    MavenExecutionRequest setRootDirectory(Path rootDirectory);
+
+    /**
+     * Gets the root directory of the top project, which is the parent directory containing the {@code .mvn}
+     * directory or a {@code pom.xml} file with the {@code root="true"} attribute.
+     * If there's no such directory, an {@code IllegalStateException} will be thrown.
+     *
+     * @throws IllegalStateException if the root directory could not be found
+     * @see #getTopDirectory()
+     * @since 4.0.0
+     */
+    Path getRootDirectory();
+
     /**
      * @since 3.3.0
      */

maven-core/src/main/java/org/apache/maven/execution/MavenSession.java

@@ -19,6 +19,7 @@
 package org.apache.maven.execution;
 
 import java.io.File;
+import java.nio.file.Path;
 import java.util.Arrays;
 import java.util.Date;
 import java.util.List;
@@ -141,10 +142,30 @@ public List<MavenProject> getProjects() {
         return projects;
     }
 
+    /**
+     * @deprecated use {@link #getTopDirectory()} ()}
+     */
+    @Deprecated
     public String getExecutionRootDirectory() {
         return request.getBaseDirectory();
     }
 
+    /**
+     * @see MavenExecutionRequest#getTopDirectory()
+     * @since 4.0.0
+     */
+    public Path getTopDirectory() {
+        return request.getTopDirectory();
+    }
+
+    /**
+     * @see MavenExecutionRequest#getRootDirectory()
+     * @since 4.0.0
+     */
+    public Path getRootDirectory() {
+        return request.getRootDirectory();
+    }
+
     public MavenExecutionRequest getRequest() {
         return request;
     }

maven-core/src/main/java/org/apache/maven/internal/impl/DefaultProject.java

@@ -129,6 +129,22 @@ public boolean isExecutionRoot() {
         return project.isExecutionRoot();
     }
 
+    @Override
+    public boolean isTopProject() {
+        return getBasedir().isPresent()
+                && getBasedir().get().equals(getSession().getTopDirectory());
+    }
+
+    @Override
+    public boolean isRootProject() {
+        return getBasedir().isPresent() && getBasedir().get().equals(getRootDirectory());
+    }
+
+    @Override
+    public Path getRootDirectory() {
+        return project.getRootDirectory();
+    }
+
     @Override
     public Optional<Project> getParent() {
         MavenProject parent = project.getParent();

maven-core/src/main/java/org/apache/maven/internal/impl/DefaultSession.java

@@ -19,7 +19,6 @@
 package org.apache.maven.internal.impl;
 
 import java.nio.file.Path;
-import java.nio.file.Paths;
 import java.time.Instant;
 import java.util.Collections;
 import java.util.HashMap;
@@ -150,7 +149,17 @@ public Path getMultiModuleProjectDirectory() {
     @Nonnull
     @Override
     public Path getExecutionRootDirectory() {
-        return Paths.get(mavenSession.getRequest().getBaseDirectory());
+        return getTopDirectory();
+    }
+
+    @Override
+    public Path getRootDirectory() {
+        return mavenSession.getRequest().getRootDirectory();
+    }
+
+    @Override
+    public Path getTopDirectory() {
+        return mavenSession.getRequest().getTopDirectory();
     }
 
     @Nonnull

maven-core/src/main/java/org/apache/maven/internal/transformation/ConsumerPomArtifactTransformer.java

@@ -74,6 +74,9 @@ public void injectTransformedArtifacts(MavenProject project, RepositorySystemSes
                 generatedFile = Files.createTempFile(buildDir, CONSUMER_POM_CLASSIFIER, "pom");
             }
             project.addAttachedArtifact(new ConsumerPomArtifact(project, generatedFile, session));
+        } else if (project.getModel().isRoot()) {
+            throw new IllegalStateException(
+                    "The use of the root attribute on the model requires the buildconsumer feature to be active");
         }
     }