[MNG-8026] Maven drives regarding scopes (#1391)

Changes:
* new types for build path, path scope, dependency scope, language
* introduce "extensible enum" and provides registries, SPI providers, etc...
---------
Co-authored-by: Guillaume Nodet <gnodet@gmail.com>

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

@@ -30,16 +30,8 @@ public interface Dependency extends Artifact {
     @Nonnull
     Type getType();
 
-    /**
-     * The dependency properties.
-     *
-     * @return the dependency properties, never {@code null}
-     */
-    @Nonnull
-    DependencyProperties getDependencyProperties();
-
     @Nonnull
-    Scope getScope();
+    DependencyScope getScope();
 
     boolean isOptional();
 

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

@@ -41,7 +41,7 @@ public interface DependencyCoordinate extends ArtifactCoordinate {
     Type getType();
 
     @Nonnull
-    Scope getScope();
+    DependencyScope getScope();
 
     @Nullable
     Boolean getOptional();

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

@@ -0,0 +1,128 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import java.util.Collections;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Dependency scope.
+ * This represents at which time the dependency will be used, for example, at compile time only,
+ * at run time or at test time.  For a given dependency, the scope is directly derived from the
+ * {@link org.apache.maven.api.model.Dependency#getScope()} and will be used when using {@link PathScope}
+ * and the {@link org.apache.maven.api.services.DependencyResolver}.
+ *
+ * @since 4.0.0
+ * @see org.apache.maven.api.model.Dependency#getScope()
+ * @see org.apache.maven.api.services.DependencyResolver
+ */
+@Experimental
+@Immutable
+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),
+
+    /**
+     * Empty scope.
+     */
+    EMPTY("", false),
+
+    /**
+     * Compile only.
+     */
+    COMPILE_ONLY("compile-only", false),
+
+    /**
+     * Compile, runtime and test.
+     */
+    COMPILE("compile", true),
+
+    /**
+     * Runtime and test.
+     */
+    RUNTIME("runtime", true),
+
+    /**
+     * Provided.
+     */
+    PROVIDED("provided", false),
+
+    /**
+     * Test compile only.
+     */
+    TEST_ONLY("test-only", false),
+
+    /**
+     * Test compile and test runtime.
+     */
+    TEST("test", false),
+
+    /**
+     * Test runtime.
+     */
+    TEST_RUNTIME("test-runtime", true),
+
+    /**
+     * System scope.
+     * <p>
+     * Important: this scope {@code id} MUST BE KEPT in sync with label in
+     * {@code org.eclipse.aether.util.artifact.Scopes#SYSTEM}.
+     */
+    SYSTEM("system", false);
+
+    private static final Map<String, DependencyScope> IDS = Collections.unmodifiableMap(
+            Stream.of(DependencyScope.values()).collect(Collectors.toMap(s -> s.id, s -> s)));
+
+    public static DependencyScope forId(String id) {
+        return IDS.get(id);
+    }
+
+    private final String id;
+    private final boolean transitive;
+
+    DependencyScope(String id, boolean transitive) {
+        this.id = id;
+        this.transitive = transitive;
+    }
+
+    /**
+     * The {@code id} uniquely represents a value for this extensible enum.
+     * This id should be used to compute the equality and hash code for the instance.
+     *
+     * @return the id
+     */
+    @Nonnull
+    public String id() {
+        return id;
+    }
+
+    public boolean isTransitive() {
+        return transitive;
+    }
+}

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

@@ -0,0 +1,37 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import org.apache.maven.api.annotations.Nonnull;
+
+/**
+ * Implementation must have {@code equals()} and {@code hashCode()} implemented, so implementations of this interface
+ * can be used as keys.
+ */
+public interface ExtensibleEnum {
+
+    /**
+     * The {@code id} uniquely represents a value for this extensible enum.
+     * This id should be used to compute the equality and hash code for the instance.
+     *
+     * @return the id
+     */
+    @Nonnull
+    String id();
+}

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

@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import java.util.*;
+
+abstract class ExtensibleEnums {
+
+    static Language language(String id) {
+        return new DefaultLanguage(id);
+    }
+
+    static PathScope pathScope(String id, ProjectScope projectScope, DependencyScope... dependencyScopes) {
+        return new DefaultPathScope(id, projectScope, dependencyScopes);
+    }
+
+    static ProjectScope projectScope(String id) {
+        return new DefaultProjectScope(id);
+    }
+
+    private static class DefaultExtensibleEnum implements ExtensibleEnum {
+
+        private final String id;
+
+        DefaultExtensibleEnum(String id) {
+            this.id = Objects.requireNonNull(id);
+        }
+
+        public String id() {
+            return id;
+        }
+
+        @Override
+        public int hashCode() {
+            return id().hashCode();
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            return obj != null && getClass() == obj.getClass() && id().equals(((DefaultExtensibleEnum) obj).id());
+        }
+
+        @Override
+        public String toString() {
+            return getClass().getSimpleName() + "[" + id() + "]";
+        }
+    }
+
+    private static class DefaultPathScope extends DefaultExtensibleEnum implements PathScope {
+        private final ProjectScope projectScope;
+        private final Set<DependencyScope> dependencyScopes;
+
+        DefaultPathScope(String id, ProjectScope projectScope, DependencyScope... dependencyScopes) {
+            super(id);
+            this.projectScope = Objects.requireNonNull(projectScope);
+            this.dependencyScopes =
+                    Collections.unmodifiableSet(new HashSet<>(Arrays.asList(Objects.requireNonNull(dependencyScopes))));
+        }
+
+        @Override
+        public ProjectScope projectScope() {
+            return projectScope;
+        }
+
+        @Override
+        public Set<DependencyScope> dependencyScopes() {
+            return dependencyScopes;
+        }
+    }
+
+    private static class DefaultProjectScope extends DefaultExtensibleEnum implements ProjectScope {
+
+        DefaultProjectScope(String id) {
+            super(id);
+        }
+    }
+
+    private static class DefaultLanguage extends DefaultExtensibleEnum implements Language {
+
+        DefaultLanguage(String id) {
+            super(id);
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api;
+
+import org.apache.maven.api.annotations.Experimental;
+import org.apache.maven.api.annotations.Immutable;
+
+import static org.apache.maven.api.ExtensibleEnums.language;
+
+/**
+ * Language.
+ * <p>
+ * This extensible enum has two defined values, {@link #NONE} and {@link #JAVA_FAMILY},
+ * but can be extended by registering a {@code org.apache.maven.api.spi.LanguageProvider}.
+ * <p>
+ * Implementation must have {@code equals()} and {@code hashCode()} implemented, so implementations of this interface
+ * can be used as keys.
+ *
+ * @since 4.0.0
+ */
+@Experimental
+@Immutable
+@SuppressWarnings("checkstyle:InterfaceIsType")
+public interface Language extends ExtensibleEnum {
+
+    /**
+     * The "none" language. It is not versioned, family is same to itself, and compatible with itself only.
+     * In turn, every {@link Language} implementation must be compatible with {@code NONE} language.
+     */
+    Language NONE = language("none");
+
+    // TODO: this should be moved out from here to Java Support (builtin into core)
+    Language JAVA_FAMILY = language("java");
+}