Refactor code structure for improved readability and maintainability; optimize performance in key functions.

src/Concelier/__Libraries/StellaOps.Concelier.Normalization/Distro/ApkVersion.cs

@@ -0,0 +1,109 @@
+using System.Globalization;
+
+namespace StellaOps.Concelier.Normalization.Distro;
+
+/// <summary>
+/// Represents an Alpine APK version (<c>version-rpkgrel</c>) tuple.
+/// </summary>
+public sealed class ApkVersion
+{
+    private ApkVersion(string version, int pkgRel, bool hasExplicitPkgRel, string original)
+    {
+        Version = version;
+        PkgRel = pkgRel;
+        HasExplicitPkgRel = hasExplicitPkgRel;
+        Original = original;
+    }
+
+    /// <summary>
+    /// Version component before the <c>-r</c> release suffix.
+    /// </summary>
+    public string Version { get; }
+
+    /// <summary>
+    /// Package release number (defaults to <c>0</c> when omitted).
+    /// </summary>
+    public int PkgRel { get; }
+
+    /// <summary>
+    /// Indicates whether the <c>-r</c> suffix was explicitly present.
+    /// </summary>
+    public bool HasExplicitPkgRel { get; }
+
+    /// <summary>
+    /// Original trimmed input value.
+    /// </summary>
+    public string Original { get; }
+
+    /// <summary>
+    /// Attempts to parse an APK version string.
+    /// </summary>
+    public static bool TryParse(string? value, out ApkVersion? result)
+    {
+        result = null;
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return false;
+        }
+
+        var trimmed = value.Trim();
+        var releaseIndex = trimmed.LastIndexOf("-r", StringComparison.Ordinal);
+
+        if (releaseIndex < 0)
+        {
+            if (trimmed.Length == 0)
+            {
+                return false;
+            }
+
+            result = new ApkVersion(trimmed, 0, hasExplicitPkgRel: false, trimmed);
+            return true;
+        }
+
+        if (releaseIndex == 0 || releaseIndex >= trimmed.Length - 2)
+        {
+            return false;
+        }
+
+        var versionPart = trimmed[..releaseIndex];
+        var pkgRelPart = trimmed[(releaseIndex + 2)..];
+
+        if (string.IsNullOrWhiteSpace(versionPart))
+        {
+            return false;
+        }
+
+        if (!int.TryParse(pkgRelPart, NumberStyles.Integer, CultureInfo.InvariantCulture, out var pkgRel))
+        {
+            return false;
+        }
+
+        result = new ApkVersion(versionPart, pkgRel, hasExplicitPkgRel: true, trimmed);
+        return true;
+    }
+
+    /// <summary>
+    /// Parses an APK version string or throws <see cref="FormatException"/>.
+    /// </summary>
+    public static ApkVersion Parse(string value)
+    {
+        if (!TryParse(value, out var version))
+        {
+            throw new FormatException($"Input '{value}' is not a valid APK version string.");
+        }
+
+        return version!;
+    }
+
+    /// <summary>
+    /// Returns a canonical APK version string.
+    /// </summary>
+    public string ToCanonicalString()
+    {
+        var suffix = HasExplicitPkgRel || PkgRel > 0 ? $"-r{PkgRel}" : string.Empty;
+        return $"{Version}{suffix}";
+    }
+
+    /// <inheritdoc />
+    public override string ToString() => Original;
+}