add support for semver 2.0 build metadata, update for SDV 1.4.0.1

5 files changed, 86 insertions, 35 deletions

diff --git a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
index c91ec27f..48afcaa2 100644
--- a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
+++ b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs
@@ -25,44 +25,50 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.2.3-some-tag.4", ExpectedResult = "1.2.3-some-tag.4")]
         [TestCase("1.2.3-SoME-tAg.4", ExpectedResult = "1.2.3-SoME-tAg.4")]
         [TestCase("1.2.3-some-tag.4      ", ExpectedResult = "1.2.3-some-tag.4")]
+        [TestCase("1.2.3-some-tag.4+build.004", ExpectedResult = "1.2.3-some-tag.4+build.004")]
+        [TestCase("1.2+3.4.5-build.004", ExpectedResult = "1.2.0+3.4.5-build.004")]
         public string Constructor_FromString(string input)
         {
             return new SemanticVersion(input).ToString();
         }
 
         [Test(Description = "Assert that the constructor sets the expected values for all valid versions when constructed from the individual numbers.")]
-        [TestCase(1, 0, 0, null, ExpectedResult = "1.0.0")]
-        [TestCase(3000, 4000, 5000, null, ExpectedResult = "3000.4000.5000")]
-        [TestCase(1, 2, 3, "", ExpectedResult = "1.2.3")]
-        [TestCase(1, 2, 3, "    ", ExpectedResult = "1.2.3")]
-        [TestCase(1, 2, 3, "0", ExpectedResult = "1.2.3-0")]
-        [TestCase(1, 2, 3, "some-tag.4", ExpectedResult = "1.2.3-some-tag.4")]
-        [TestCase(1, 2, 3, "sOMe-TaG.4", ExpectedResult = "1.2.3-sOMe-TaG.4")]
-        [TestCase(1, 2, 3, "some-tag.4   ", ExpectedResult = "1.2.3-some-tag.4")]
-        public string Constructor_FromParts(int major, int minor, int patch, string tag)
+        [TestCase(1, 0, 0, null, null, ExpectedResult = "1.0.0")]
+        [TestCase(3000, 4000, 5000, null, null, ExpectedResult = "3000.4000.5000")]
+        [TestCase(1, 2, 3, "", null, ExpectedResult = "1.2.3")]
+        [TestCase(1, 2, 3, "    ", null, ExpectedResult = "1.2.3")]
+        [TestCase(1, 2, 3, "0", null, ExpectedResult = "1.2.3-0")]
+        [TestCase(1, 2, 3, "some-tag.4", null, ExpectedResult = "1.2.3-some-tag.4")]
+        [TestCase(1, 2, 3, "sOMe-TaG.4", null, ExpectedResult = "1.2.3-sOMe-TaG.4")]
+        [TestCase(1, 2, 3, "some-tag.4   ", null, ExpectedResult = "1.2.3-some-tag.4")]
+        [TestCase(1, 2, 3, "some-tag.4   ", "build.004", ExpectedResult = "1.2.3-some-tag.4+build.004")]
+        [TestCase(1, 2, 0, null, "3.4.5-build.004", ExpectedResult = "1.2.0+3.4.5-build.004")]
+        public string Constructor_FromParts(int major, int minor, int patch, string prerelease, string build)
         {
             // act
-            ISemanticVersion version = new SemanticVersion(major, minor, patch, tag);
+            ISemanticVersion version = new SemanticVersion(major, minor, patch, prerelease, build);
 
             // assert
             Assert.AreEqual(major, version.MajorVersion, "The major version doesn't match the given value.");
             Assert.AreEqual(minor, version.MinorVersion, "The minor version doesn't match the given value.");
             Assert.AreEqual(patch, version.PatchVersion, "The patch version doesn't match the given value.");
-            Assert.AreEqual(string.IsNullOrWhiteSpace(tag) ? null : tag.Trim(), version.PrereleaseTag, "The tag doesn't match the given value.");
+            Assert.AreEqual(string.IsNullOrWhiteSpace(prerelease) ? null : prerelease.Trim(), version.PrereleaseTag, "The prerelease tag doesn't match the given value.");
+            Assert.AreEqual(string.IsNullOrWhiteSpace(build) ? null : build.Trim(), version.BuildMetadata, "The build metadata doesn't match the given value.");
             return version.ToString();
         }
 
         [Test(Description = "Assert that the constructor throws the expected exception for invalid versions when constructed from the individual numbers.")]
-        [TestCase(0, 0, 0, null)]
-        [TestCase(-1, 0, 0, null)]
-        [TestCase(0, -1, 0, null)]
-        [TestCase(0, 0, -1, null)]
-        [TestCase(1, 0, 0, "-tag")]
-        [TestCase(1, 0, 0, "tag spaces")]
-        [TestCase(1, 0, 0, "tag~")]
-        public void Constructor_FromParts_WithInvalidValues(int major, int minor, int patch, string tag)
+        [TestCase(0, 0, 0, null, null)]
+        [TestCase(-1, 0, 0, null, null)]
+        [TestCase(0, -1, 0, null, null)]
+        [TestCase(0, 0, -1, null, null)]
+        [TestCase(1, 0, 0, "-tag", null)]
+        [TestCase(1, 0, 0, "tag spaces", null)]
+        [TestCase(1, 0, 0, "tag~", null)]
+        [TestCase(1, 0, 0, null, "build~")]
+        public void Constructor_FromParts_WithInvalidValues(int major, int minor, int patch, string prerelease, string build)
         {
-            this.AssertAndLogException<FormatException>(() => new SemanticVersion(major, minor, patch, tag));
+            this.AssertAndLogException<FormatException>(() => new SemanticVersion(major, minor, patch, prerelease, build));
         }
 
         [Test(Description = "Assert that the constructor sets the expected values for all valid versions when constructed from an assembly version.")]
@@ -98,6 +104,7 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.2.3--some-tag")]
         [TestCase("1.2.3-some-tag...")]
         [TestCase("1.2.3-some-tag...4")]
+        [TestCase("1.2.3-some-tag.4+build...4")]
         [TestCase("apple")]
         [TestCase("-apple")]
         [TestCase("-5")]
@@ -119,6 +126,8 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta", "1.0-beta", ExpectedResult = 0)]
         [TestCase("1.0-beta.10", "1.0-beta.10", ExpectedResult = 0)]
         [TestCase("1.0-beta", "1.0-beta   ", ExpectedResult = 0)]
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.001", ExpectedResult = 0)]
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.006", ExpectedResult = 0)] // build metadata must not affect precedence
 
         // less than
         [TestCase("0.5.7", "0.5.8", ExpectedResult = -1)]
@@ -156,6 +165,8 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta", "1.0-beta", ExpectedResult = false)]
         [TestCase("1.0-beta.10", "1.0-beta.10", ExpectedResult = false)]
         [TestCase("1.0-beta", "1.0-beta   ", ExpectedResult = false)]
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.001", ExpectedResult = false)] // build metadata must not affect precedence
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.006", ExpectedResult = false)] // build metadata must not affect precedence
 
         // less than
         [TestCase("0.5.7", "0.5.8", ExpectedResult = true)]
@@ -192,6 +203,8 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.0-beta", "1.0-beta", ExpectedResult = false)]
         [TestCase("1.0-beta.10", "1.0-beta.10", ExpectedResult = false)]
         [TestCase("1.0-beta", "1.0-beta   ", ExpectedResult = false)]
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.001", ExpectedResult = false)] // build metadata must not affect precedence
+        [TestCase("1.0-beta+build.001", "1.0-beta+build.006", ExpectedResult = false)] // build metadata must not affect precedence
 
         // less than
         [TestCase("0.5.7", "0.5.8", ExpectedResult = false)]
@@ -279,6 +292,8 @@ namespace SMAPI.Tests.Utilities
         [TestCase("1.11")]
         [TestCase("1.2")]
         [TestCase("1.2.15")]
+        [TestCase("1.4.0.1")]
+        [TestCase("1.4.0.6")]
         public void GameVersion(string versionStr)
         {
             // act
@@ -286,7 +301,6 @@ namespace SMAPI.Tests.Utilities
 
             // assert
             Assert.AreEqual(versionStr, version.ToString(), "The game version did not round-trip to the same value.");
-            Assert.IsTrue(version.IsOlderThan(new SemanticVersion("1.2.30")), "The game version should be considered older than the later semantic versions.");
         }
 
 
diff --git a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
index 4ec87d7c..b8572d50 100644
--- a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
+++ b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs
@@ -20,6 +20,9 @@ namespace StardewModdingAPI
         /// <summary>An optional prerelease tag.</summary>
         string PrereleaseTag { get; }
 
+        /// <summary>Optional build metadata. This is ignored when determining version precedence.</summary>
+        string BuildMetadata { get; }
+
 
         /*********
         ** Accessors
diff --git a/src/SMAPI.Toolkit/SemanticVersion.cs b/src/SMAPI.Toolkit/SemanticVersion.cs
index 2ce3578e..4955dcae 100644
--- a/src/SMAPI.Toolkit/SemanticVersion.cs
+++ b/src/SMAPI.Toolkit/SemanticVersion.cs
@@ -7,8 +7,7 @@ namespace StardewModdingAPI.Toolkit
     /// <remarks>
     /// The implementation is defined by Semantic Version 2.0 (https://semver.org/), with a few deviations:
     /// - short-form "x.y" versions are supported (equivalent to "x.y.0");
-    /// - hyphens are synonymous with dots in prerelease tags (like "-unofficial.3-pathoschild");
-    /// - +build suffixes are not supported;
+    /// - hyphens are synonymous with dots in prerelease tags and build metadata (like "-unofficial.3-pathoschild");
     /// - and "-unofficial" in prerelease tags is always lower-precedence (e.g. "1.0-beta" is newer than "1.0-unofficial").
     /// </remarks>
     public class SemanticVersion : ISemanticVersion
@@ -16,11 +15,11 @@ namespace StardewModdingAPI.Toolkit
         /*********
         ** Fields
         *********/
-        /// <summary>A regex pattern matching a valid prerelease tag.</summary>
+        /// <summary>A regex pattern matching a valid prerelease or build metadata tag.</summary>
         internal const string TagPattern = @"(?>[a-z0-9]+[\-\.]?)+";
 
         /// <summary>A regex pattern matching a version within a larger string.</summary>
-        internal const string UnboundedVersionPattern = @"(?>(?<major>0|[1-9]\d*))\.(?>(?<minor>0|[1-9]\d*))(?>(?:\.(?<patch>0|[1-9]\d*))?)(?:-(?<prerelease>" + SemanticVersion.TagPattern + "))?";
+        internal const string UnboundedVersionPattern = @"(?>(?<major>0|[1-9]\d*))\.(?>(?<minor>0|[1-9]\d*))(?>(?:\.(?<patch>0|[1-9]\d*))?)(?:-(?<prerelease>" + SemanticVersion.TagPattern + "))?(?:\\+(?<buildmetadata>" + SemanticVersion.TagPattern + "))?";
 
         /// <summary>A regular expression matching a semantic version string.</summary>
         /// <remarks>This pattern is derived from the BNF documentation in the <a href="https://github.com/mojombo/semver">semver repo</a>, with deviations to support the Stardew Valley mod conventions (see remarks on <see cref="SemanticVersion"/>).</remarks>
@@ -42,6 +41,9 @@ namespace StardewModdingAPI.Toolkit
         /// <summary>An optional prerelease tag.</summary>
         public string PrereleaseTag { get; }
 
+        /// <summary>Optional build metadata. This is ignored when determining version precedence.</summary>
+        public string BuildMetadata { get; }
+
 
         /*********
         ** Public methods
@@ -51,12 +53,14 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="minor">The minor version incremented for backwards-compatible changes.</param>
         /// <param name="patch">The patch version for backwards-compatible fixes.</param>
         /// <param name="prereleaseTag">An optional prerelease tag.</param>
-        public SemanticVersion(int major, int minor, int patch, string prereleaseTag = null)
+        /// <param name="buildMetadata">Optional build metadata. This is ignored when determining version precedence.</param>
+        public SemanticVersion(int major, int minor, int patch, string prereleaseTag = null, string buildMetadata = null)
         {
             this.MajorVersion = major;
             this.MinorVersion = minor;
             this.PatchVersion = patch;
             this.PrereleaseTag = this.GetNormalizedTag(prereleaseTag);
+            this.BuildMetadata = this.GetNormalizedTag(buildMetadata);
 
             this.AssertValid();
         }
@@ -94,6 +98,7 @@ namespace StardewModdingAPI.Toolkit
             this.MinorVersion = match.Groups["minor"].Success ? int.Parse(match.Groups["minor"].Value) : 0;
             this.PatchVersion = match.Groups["patch"].Success ? int.Parse(match.Groups["patch"].Value) : 0;
             this.PrereleaseTag = match.Groups["prerelease"].Success ? this.GetNormalizedTag(match.Groups["prerelease"].Value) : null;
+            this.BuildMetadata = match.Groups["buildmetadata"].Success ? this.GetNormalizedTag(match.Groups["buildmetadata"].Value) : null;
 
             this.AssertValid();
         }
@@ -175,6 +180,8 @@ namespace StardewModdingAPI.Toolkit
             string version = $"{this.MajorVersion}.{this.MinorVersion}.{this.PatchVersion}";
             if (this.PrereleaseTag != null)
                 version += $"-{this.PrereleaseTag}";
+            if (this.BuildMetadata != null)
+                version += $"+{this.BuildMetadata}";
             return version;
         }
 
@@ -200,7 +207,7 @@ namespace StardewModdingAPI.Toolkit
         /*********
         ** Private methods
         *********/
-        /// <summary>Get a normalized build tag.</summary>
+        /// <summary>Get a normalized prerelease or build tag.</summary>
         /// <param name="tag">The tag to normalize.</param>
         private string GetNormalizedTag(string tag)
         {
@@ -277,12 +284,21 @@ namespace StardewModdingAPI.Toolkit
                 throw new FormatException($"{this} isn't a valid semantic version. The major, minor, and patch numbers can't be negative.");
             if (this.MajorVersion == 0 && this.MinorVersion == 0 && this.PatchVersion == 0)
                 throw new FormatException($"{this} isn't a valid semantic version. At least one of the major, minor, and patch numbers must be more than zero.");
+
             if (this.PrereleaseTag != null)
             {
                 if (this.PrereleaseTag.Trim() == "")
-                    throw new FormatException($"{this} isn't a valid semantic version. The tag cannot be a blank string (but may be omitted).");
+                    throw new FormatException($"{this} isn't a valid semantic version. The prerelease tag cannot be a blank string (but may be omitted).");
                 if (!Regex.IsMatch(this.PrereleaseTag, $"^{SemanticVersion.TagPattern}$", RegexOptions.IgnoreCase))
-                    throw new FormatException($"{this} isn't a valid semantic version. The tag is invalid.");
+                    throw new FormatException($"{this} isn't a valid semantic version. The prerelease tag is invalid.");
+            }
+
+            if (this.BuildMetadata != null)
+            {
+                if (this.BuildMetadata.Trim() == "")
+                    throw new FormatException($"{this} isn't a valid semantic version. The build metadata cannot be a blank string (but may be omitted).");
+                if (!Regex.IsMatch(this.BuildMetadata, $"^{SemanticVersion.TagPattern}$", RegexOptions.IgnoreCase))
+                    throw new FormatException($"{this} isn't a valid semantic version. The build metadata is invalid.");
             }
         }
     }
diff --git a/src/SMAPI/Framework/GameVersion.cs b/src/SMAPI/Framework/GameVersion.cs
index cd88895c..29cfbc39 100644
--- a/src/SMAPI/Framework/GameVersion.cs
+++ b/src/SMAPI/Framework/GameVersion.cs
@@ -52,20 +52,34 @@ namespace StardewModdingAPI.Framework
         /// <param name="gameVersion">The game version string.</param>
         private static string GetSemanticVersionString(string gameVersion)
         {
-            return GameVersion.VersionMap.TryGetValue(gameVersion, out string semanticVersion)
-                ? semanticVersion
-                : gameVersion;
+            // mapped version
+            if (GameVersion.VersionMap.TryGetValue(gameVersion, out string semanticVersion))
+                return semanticVersion;
+
+            // special case: four-part versions
+            string[] parts = gameVersion.Split('.');
+            if (parts.Length == 4)
+                return $"{parts[0]}.{parts[1]}.{parts[2]}+{parts[3]}";
+
+            return gameVersion;
         }
 
         /// <summary>Convert a semantic version string to the equivalent game version string.</summary>
         /// <param name="semanticVersion">The semantic version string.</param>
         private static string GetGameVersionString(string semanticVersion)
         {
+            // mapped versions
             foreach (var mapping in GameVersion.VersionMap)
             {
                 if (mapping.Value.Equals(semanticVersion, StringComparison.InvariantCultureIgnoreCase))
                     return mapping.Key;
             }
+
+            // special case: four-part versions
+            string[] parts = semanticVersion.Split('.', '+');
+            if (parts.Length == 4)
+                return $"{parts[0]}.{parts[1]}.{parts[2]}.{parts[3]}";
+
             return semanticVersion;
         }
     }
diff --git a/src/SMAPI/SemanticVersion.cs b/src/SMAPI/SemanticVersion.cs
index 0db41673..2a33ecef 100644
--- a/src/SMAPI/SemanticVersion.cs
+++ b/src/SMAPI/SemanticVersion.cs
@@ -28,6 +28,9 @@ namespace StardewModdingAPI
         /// <summary>An optional prerelease tag.</summary>
         public string PrereleaseTag => this.Version.PrereleaseTag;
 
+        /// <summary>Optional build metadata. This is ignored when determining version precedence.</summary>
+        public string BuildMetadata => this.Version.BuildMetadata;
+
 
         /*********
         ** Public methods
@@ -36,10 +39,11 @@ namespace StardewModdingAPI
         /// <param name="majorVersion">The major version incremented for major API changes.</param>
         /// <param name="minorVersion">The minor version incremented for backwards-compatible changes.</param>
         /// <param name="patchVersion">The patch version for backwards-compatible bug fixes.</param>
-        /// <param name="build">An optional build tag.</param>
+        /// <param name="prerelease">An optional prerelease tag.</param>
+        /// <param name="build">Optional build metadata. This is ignored when determining version precedence.</param>
         [JsonConstructor]
-        public SemanticVersion(int majorVersion, int minorVersion, int patchVersion, string build = null)
-            : this(new Toolkit.SemanticVersion(majorVersion, minorVersion, patchVersion, build)) { }
+        public SemanticVersion(int majorVersion, int minorVersion, int patchVersion, string prerelease = null, string build = null)
+            : this(new Toolkit.SemanticVersion(majorVersion, minorVersion, patchVersion, prerelease, build)) { }
 
         /// <summary>Construct an instance.</summary>
         /// <param name="version">The semantic version string.</param>