Add dependency insertion ordering auto-detection (#286)

addAligned() now detects whether the project's <dependencies> container
follows an ordering convention and inserts new dependencies at the correct
position, transparently to callers.

New AlignOptions.InsertionOrdering enum: NONE, ALPHA, SCOPE, SCOPE_THEN_ALPHA.
Follows the existing nullable-field convention (null = auto-detect), consistent
with VersionStyle, VersionSource, and PropertyNamingConvention.

Detection (detectInsertionOrdering): analyses consecutive dependency pairs with
a 75% threshold heuristic. Priority: SCOPE_THEN_ALPHA > SCOPE > ALPHA > NONE.
Fewer than 3 deps returns NONE (signal too weak). SCOPE and SCOPE_THEN_ALPHA
require actual scope variation; an all-same-scope alpha list returns ALPHA.
Plugged into detectConventions(), which returns null (not NONE) for the
insertionOrdering field when the direct-deps container is absent or too small,
so callers relying on auto-detection are not inadvertently blocked.

Canonical scope order: compile, provided, runtime, system, test, import.
Null or empty scope is normalised to compile (DEFAULT_SCOPE constant).

addAligned(Coordinates, AlignOptions) resolves the effective ordering (explicit
option wins, else auto-detect from the appropriate container) and inserts at the
anchor position computed by findInsertionAnchor(). ensureManagedDependency()
applies the same logic, independently detecting ordering from the managed
container — managed-only POMs with no direct <dependencies> are handled
correctly.

New InsertionOrderingTest (17 tests) covers detection and insertion for ALPHA,
SCOPE, SCOPE_THEN_ALPHA, weak-signal (< 3 deps), empty container, inconsistent
order, managed-only POM, null/empty scope, and explicit NONE override.
No existing public method signatures changed; all 340 existing tests pass.

Author: gnodet

maven/src/main/java/eu/maveniverse/domtrip/maven/AlignOptions.java

@@ -73,6 +73,22 @@ public enum VersionSource {
         PROPERTY
     }
 
+    /**
+     * Ordering convention for dependency insertion.
+     *
+     * @since 1.7.0
+     */
+    public enum InsertionOrdering {
+        /** No ordering detected or enforced — insert at end. */
+        NONE,
+        /** Dependencies ordered alphabetically by groupId:artifactId. */
+        ALPHA,
+        /** Dependencies ordered by Maven scope (compile, provided, runtime, system, test, import). */
+        SCOPE,
+        /** Dependencies ordered by scope first, then alphabetically within each scope group. */
+        SCOPE_THEN_ALPHA
+    }
+
     /**
      * Naming convention for version properties.
      *
@@ -92,6 +108,7 @@ public enum PropertyNamingConvention {
     private final VersionStyle versionStyle;
     private final VersionSource versionSource;
     private final PropertyNamingConvention namingConvention;
+    private final InsertionOrdering insertionOrdering;
     private final Function<Coordinates, String> propertyNameGenerator;
     private final String propertyName;
     private final String scope;
@@ -105,6 +122,7 @@ public enum PropertyNamingConvention {
      * @param versionStyle         placement of dependency versions (inline vs managed); {@code null} means auto-detect
      * @param versionSource        whether versions are literal or property references; {@code null} means auto-detect
      * @param namingConvention     property naming convention to use; {@code null} means auto-detect
+     * @param insertionOrdering    ordering convention for dependency insertion; {@code null} means auto-detect
      * @param propertyNameGenerator optional custom generator for property names; {@code null} to use convention-based generation
      * @param propertyName         explicit property name override; {@code null} to allow auto-generation
      * @param scope                Maven dependency scope override; {@code null} to use the default scope
@@ -113,12 +131,14 @@ private AlignOptions(
             VersionStyle versionStyle,
             VersionSource versionSource,
             PropertyNamingConvention namingConvention,
+            InsertionOrdering insertionOrdering,
             Function<Coordinates, String> propertyNameGenerator,
             String propertyName,
             String scope) {
         this.versionStyle = versionStyle;
         this.versionSource = versionSource;
         this.namingConvention = namingConvention;
+        this.insertionOrdering = insertionOrdering;
         this.propertyNameGenerator = propertyNameGenerator;
         this.propertyName = propertyName;
         this.scope = scope;
@@ -131,7 +151,7 @@ private AlignOptions(
      * @since 1.1.0
      */
     public static AlignOptions defaults() {
-        return new AlignOptions(null, null, null, null, null, null);
+        return new AlignOptions(null, null, null, null, null, null, null);
     }
 
     /**
@@ -174,6 +194,16 @@ public PropertyNamingConvention namingConvention() {
         return namingConvention;
     }
 
+    /**
+     * The insertion ordering convention to use, or null to indicate auto-detection.
+     *
+     * @return the insertion ordering override, or {@code null} if it should be auto-detected
+     * @since 1.7.0
+     */
+    public InsertionOrdering insertionOrdering() {
+        return insertionOrdering;
+    }
+
     /**
      * Custom function that generates property names from dependency coordinates, or null to use convention-based generation.
      *
@@ -278,6 +308,7 @@ public static final class Builder {
         private VersionStyle versionStyle;
         private VersionSource versionSource;
         private PropertyNamingConvention namingConvention;
+        private InsertionOrdering insertionOrdering;
         private Function<Coordinates, String> propertyNameGenerator;
         private String propertyName;
         private String scope;
@@ -320,6 +351,18 @@ public Builder namingConvention(PropertyNamingConvention namingConvention) {
             return this;
         }
 
+        /**
+         * Sets the insertion ordering convention override.
+         *
+         * @param insertionOrdering the ordering convention (null for auto-detection)
+         * @return this builder
+         * @since 1.7.0
+         */
+        public Builder insertionOrdering(InsertionOrdering insertionOrdering) {
+            this.insertionOrdering = insertionOrdering;
+            return this;
+        }
+
         /**
          * Set a custom function that generates property names from dependency coordinates.
          *
@@ -372,7 +415,13 @@ public Builder scope(String scope) {
          */
         public AlignOptions build() {
             return new AlignOptions(
-                    versionStyle, versionSource, namingConvention, propertyNameGenerator, propertyName, scope);
+                    versionStyle,
+                    versionSource,
+                    namingConvention,
+                    insertionOrdering,
+                    propertyNameGenerator,
+                    propertyName,
+                    scope);
         }
     }
 }