Add automatic applies_to version sorting

[bmorelli25]

Summary

Adds automatic version sorting. Partially implements #1435.

Problem

Currently, users must manually ensure applies_to badges are written in the correct version order in source files. This requires manual effort and is error-prone.

Solution

This PR automatically sorts applies_to badges by version in descending order (highest version first), regardless of the order they appear in the source file.

Changes Made

Core Implementation

• Modified AppliesCollection.TryParse in src/Elastic.Documentation/AppliesTo/Applicability.cs:

  • Added automatic sorting of applicability items by version in descending order
  • Items without versions (like "all" or no version specified) are sorted last

• Created SemVersionComparer class:

  • Handles comparison of SemVersion objects for sorting
  • Treats both null and AllVersions.Instance as non-versioned items (lowest priority)
  • Uses proper null-safe comparison to avoid conflicts with SemVersion operator overloads

Test Updates

• Updated existing tests to reflect new sorting behavior:
  • Modified parses product multiple test to expect sorted order
  • Updated inline test to expect sorted order in HTML output
• Added comprehensive test coverage:
  • Basic version sorting (9.1.2, 9.0.6, 8.19.2, 8.18.6)
  • Mixed versioned and non-versioned items (ga 8.18.6, ga, ga 9.1.2, all, ga 8.19.2)
  • Patch version sorting (9.1, 9.1.1, 9.0.5)
  • Major version sorting (3.x, 5.x)

Documentation

• Added documentation to docs/syntax/applies.md explaining the automatic sorting behavior
• Included example showing before/after ordering

Related

elastic/beats#45810 (comment)

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/applies.md

[Mpdreamz]

LGTM! I removed SemVersionComparer in favor of implementing IEquatable<Applicability> on Applicability instead.

This makes the Applicability type itself more usable since we can compare them in if statements now.

[efd6]

Thanks