add automatic version sorting

Signed-off-by: bmorelli25 <[email protected]>

Author: bmorelli25

docs/syntax/applies.md

@@ -70,6 +70,10 @@ Where:
 - The [version](#version) is optional
 - You can specify multiple states by separating them with a comma. For example: `stack: preview 9.1, ga 9.4`
 
+:::{note}
+**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last.
+:::
+
 Note that a key without any value doesn't show any badge in the output.
 
 ### Lifecycle

src/Elastic.Documentation/AppliesTo/Applicability.cs

@@ -37,7 +37,10 @@ public static bool TryParse(string? value, IList<(Severity, string)> diagnostics
 		if (applications.Count == 0)
 			return false;
 
-		availability = new AppliesCollection([.. applications]);
+		// Sort by version in descending order (highest version first)
+		// Items without versions (AllVersions.Instance) are sorted last
+		var sortedApplications = applications.OrderByDescending(a => a.Version, new SemVersionComparer()).ToArray();
+		availability = new AppliesCollection(sortedApplications);
 		return true;
 	}
 
@@ -211,3 +214,26 @@ public static bool TryParse(string? value, IList<(Severity, string)> diagnostics
 		return true;
 	}
 }
+
+/// <summary>
+/// Comparer for SemVersion objects that handles AllVersions.Instance as the lowest priority
+/// </summary>
+public class SemVersionComparer : IComparer<SemVersion?>
+{
+	public int Compare(SemVersion? x, SemVersion? y)
+	{
+		// Handle null cases and AllVersions.Instance cases
+		var xIsNonVersioned = x is null || ReferenceEquals(x, AllVersions.Instance);
+		var yIsNonVersioned = y is null || ReferenceEquals(y, AllVersions.Instance);
+
+		if (xIsNonVersioned && yIsNonVersioned)
+			return 0;
+		if (xIsNonVersioned)
+			return -1; // Non-versioned items sort last
+		if (yIsNonVersioned)
+			return 1;  // Non-versioned items sort last
+
+		// Use default SemVersion comparison for actual versions
+		return x!.CompareTo(y!);
+	}
+}

tests/authoring/Applicability/AppliesToFrontMatter.fs

@@ -163,8 +163,8 @@ applies_to:
     let ``apply matches expected`` () =
         markdown |> appliesTo (ApplicableTo(
             Product=AppliesCollection([
-                Applicability.op_Explicit "preview 9.5";
-                Applicability.op_Explicit "removed 9.7"
+                Applicability.op_Explicit "removed 9.7";
+                Applicability.op_Explicit "preview 9.5"
             ] |> Array.ofList)
         ))
 
@@ -212,3 +212,69 @@ applies_to:
     [<Fact>]
     let ``does not render label`` () =
         markdown |> appliesTo (Unchecked.defaultof<ApplicableTo>)
+
+type ``sorts applies_to versions in descending order`` () =
+    static let markdown = frontMatter """
+applies_to:
+   stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6
+"""
+    [<Fact>]
+    let ``versions are sorted highest to lowest`` () =
+        let expectedVersions = [
+            Applicability.op_Explicit "ga 9.1.2"
+            Applicability.op_Explicit "ga 9.0.6"
+            Applicability.op_Explicit "ga 8.19.2"
+            Applicability.op_Explicit "ga 8.18.6"
+        ]
+        markdown |> appliesTo (ApplicableTo(
+            Stack=AppliesCollection(expectedVersions |> Array.ofList)
+        ))
+
+type ``sorts applies_to with mixed versioned and non-versioned items`` () =
+    static let markdown = frontMatter """
+applies_to:
+   stack: ga 8.18.6, ga, ga 9.1.2, all, ga 8.19.2
+"""
+    [<Fact>]
+    let ``versioned items are sorted first, non-versioned items last`` () =
+        let expectedVersions = [
+            Applicability.op_Explicit "ga 9.1.2"
+            Applicability.op_Explicit "ga 8.19.2"
+            Applicability.op_Explicit "ga 8.18.6"
+            Applicability.op_Explicit "ga"
+            Applicability.op_Explicit "all"
+        ]
+        markdown |> appliesTo (ApplicableTo(
+            Stack=AppliesCollection(expectedVersions |> Array.ofList)
+        ))
+
+type ``sorts applies_to with patch versions correctly`` () =
+    static let markdown = frontMatter """
+applies_to:
+   stack: ga 9.1, ga 9.1.1, ga 9.0.5
+"""
+    [<Fact>]
+    let ``patch versions are sorted correctly`` () =
+        let expectedVersions = [
+            Applicability.op_Explicit "ga 9.1.1"
+            Applicability.op_Explicit "ga 9.1"
+            Applicability.op_Explicit "ga 9.0.5"
+        ]
+        markdown |> appliesTo (ApplicableTo(
+            Stack=AppliesCollection(expectedVersions |> Array.ofList)
+        ))
+
+type ``sorts applies_to with major versions correctly`` () =
+    static let markdown = frontMatter """
+applies_to:
+   stack: ga 3.x, ga 5.x
+"""
+    [<Fact>]
+    let ``major versions are sorted correctly`` () =
+        let expectedVersions = [
+            Applicability.op_Explicit "ga 5.x"
+            Applicability.op_Explicit "ga 3.x"
+        ]
+        markdown |> appliesTo (ApplicableTo(
+            Stack=AppliesCollection(expectedVersions |> Array.ofList)
+        ))

tests/authoring/Inline/AppliesToRole.fs

@@ -133,7 +133,7 @@ This is an inline {applies_to}`stack: preview 9.0, ga 9.1` element.
         let directives = markdown |> converts "index.md" |> parses<AppliesToRole>
         test <@ directives.Length = 1 @>
         directives |> appliesToDirective (ApplicableTo(
-            Stack=AppliesCollection.op_Explicit "preview 9.0, ga 9.1"
+            Stack=AppliesCollection.op_Explicit "ga 9.1, preview 9.0"
         ))
 
     [<Fact>]
@@ -143,20 +143,20 @@ This is an inline {applies_to}`stack: preview 9.0, ga 9.1` element.
 	<span class="applies applies-inline">
 		<span class="applicable-info" data-tippy-content="We plan to add this functionality in a future Elastic&nbsp;Stack update. Subject to change.
 
-This functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.">
+If this functionality is unavailable or behaves differently when deployed on ECH, ECE, ECK, or a self-managed installation, it will be indicated on the page.">
 			<span class="applicable-name">Stack</span>
 			<span class="applicable-separator"></span>
-			<span class="applicable-meta applicable-meta-preview">
-				Planned
+			<span class="applicable-meta applicable-meta-ga">
+				GA planned
 			</span>
 		</span>
 		<span class="applicable-info" data-tippy-content="We plan to add this functionality in a future Elastic&nbsp;Stack update. Subject to change.
 
-If this functionality is unavailable or behaves differently when deployed on ECH, ECE, ECK, or a self-managed installation, it will be indicated on the page.">
+This functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.">
 			<span class="applicable-name">Stack</span>
 			<span class="applicable-separator"></span>
-			<span class="applicable-meta applicable-meta-ga">
-				GA planned
+			<span class="applicable-meta applicable-meta-preview">
+				Planned
 			</span>
 		</span>
 	</span>