Number versions MAJOR.MINOR.PATCH in the version toolfix/version-tool-semver

Progmasoft repositories use Semantic Versioning since 2026-11-12, but
//tools:version still knew the four-number counters: given 0.4.0 it
wrote 0.4.0.0 everywhere, and --next stepped the fourth number.

- A Version is three numbers; ParseVersion takes exactly three, without
  leading zeros, and FormatVersion writes three.
- --next is the next patch release. It also follows a four-number
  version as the rule says: the fourth number goes and the patch rises,
  so 0.3.0.2 is followed by 0.3.1.
- ReleaseNotesOf finds a section by the version it was published as.
  Its fallback for "D = 0" read the fourth element of what is now a
  three-element array; it is gone.
- Tests for the new parsing, NextPatch and release-note lookup;
  docs/contributing.md and the tool's usage say what the tool does.

Claude-Session: https://claude.ai/code/session_01Ji7xZMYjc4zankoc7hGBE1

5 files changed, 87 insertions, 87 deletions

diff --git a/docs/contributing.md b/docs/contributing.md
index ac736ffd..4edecee2 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -66,7 +66,7 @@ The tools in `tools/` are C++17 and run through Bazel, with arguments after
 | `//tools:amalgamate` | writes the single-file distribution; `-- --check` only compares it |
 | `//tools:check` | runs the repository checks |
 | `//tools:third_party` | `-- --check` compares `third_party/` with the archives `MODULE.bazel` pins, `-- --update` writes it |
-| `//tools:version` | prints the version; `-- --next` or `-- <version>` moves every place that states it, and the distribution |
+| `//tools:version` | prints the version; `-- <version>` (`MAJOR.MINOR.PATCH`) or `-- --next` (the next patch release) moves every place that states it, and the distribution |
 | `//tools:release_notes` | prints a section of the release notes, of `-- <version>` or the current one |
 | `//tools:repo_info` | reports the checkout and the tools on `PATH`; `-- --json` writes it as JSON |
 
diff --git a/tools/Tools.tests.cpp b/tools/Tools.tests.cpp
index 90e9b129..980d9e7a 100644
--- a/tools/Tools.tests.cpp
+++ b/tools/Tools.tests.cpp
@@ -13,28 +13,32 @@
 using namespace Progmasoft::Catch3::Tools;
 using Catch::Matchers::ContainsSubstring;
 
-TEST_CASE("Versions have three or four numbers", "[tools]")
+TEST_CASE("Versions are MAJOR.MINOR.PATCH", "[tools]")
 {
-    CHECK(ParseVersion("0.3.0") == Version{ 0, 3, 0, 0 });
-    CHECK(ParseVersion("0.3.0.2") == Version{ 0, 3, 0, 2 });
+    CHECK(ParseVersion("0.4.0") == Version{ 0, 4, 0 });
+    CHECK(ParseVersion("10.20.30") == Version{ 10, 20, 30 });
+    CHECK(FormatVersion(Version{ 0, 4, 0 }) == "0.4.0");
     for (const char *wrong :
-         { "0.3", "0.3.0.2.1", "01.3.0", "0.3.0.", "a.3.0", "", "0.3.0-rc" })
+         { "0.3", "0.3.0.2", "01.3.0", "0.3.0.", "a.3.0", "", "0.3.0-rc" })
     {
         INFO(wrong);
         CHECK_FALSE(ParseVersion(wrong));
     }
 }
 
-TEST_CASE("The next version counts releases", "[tools]")
+TEST_CASE("The next patch release follows a SemVer or a four-number version",
+          "[tools]")
 {
     const auto next = [](const char *version) {
-        return FormatVersion(NextVersion(*ParseVersion(version)));
+        const auto parsed = NextPatch(version);
+        return parsed ? FormatVersion(*parsed) : std::string{ "none" };
     };
-    CHECK(next("0.3.0") == "0.3.0.1");
-    CHECK(next("0.4.0.8") == "0.4.0.9");
-    CHECK(next("0.4.0.9") == "0.4.1.0");
-    CHECK(next("0.4.9.9") == "0.5.0.0");
-    CHECK(next("0.19.9.9") == "1.0.0.0");
+    CHECK(next("0.4.0") == "0.4.1");
+    CHECK(next("1.2.9") == "1.2.10");
+    // After the four-number versions: the fourth number goes.
+    CHECK(next("0.3.0.2") == "0.3.1");
+    CHECK(next("0.3") == "none");
+    CHECK(next("0.3.0.2.1") == "none");
 }
 
 TEST_CASE("A version site is read and written in place", "[tools]")
@@ -57,12 +61,14 @@ TEST_CASE("Release notes are found by their heading", "[tools]")
     CHECK_FALSE(ReleaseNotesOf(notes, "0.3"));
 }
 
-TEST_CASE("A release with D = 0 may be headed by three numbers", "[tools]")
+TEST_CASE("A release is found by the version it was published as", "[tools]")
 {
-    const std::string notes = "# Notes\n\n## 0.4.0\n\nThree.\n";
+    const std::string notes
+        = "# Notes\n\n## 0.4.0\n\nThree.\n\n\n## 0.3.0.2\n\nFour.\n";
     CHECK(ReleaseNotesOf(notes, "0.4.0") == "Three.\n");
-    CHECK(ReleaseNotesOf(notes, "0.4.0.0") == "Three.\n");
-    CHECK_FALSE(ReleaseNotesOf(notes, "0.4.0.1"));
+    CHECK(ReleaseNotesOf(notes, "0.3.0.2") == "Four.\n");
+    CHECK_FALSE(ReleaseNotesOf(notes, "0.4.0.0"));
+    CHECK_FALSE(ReleaseNotesOf(notes, "0.3.0"));
 }
 
 TEST_CASE("Git that could not say is not a clean checkout", "[tools]")
diff --git a/tools/VersionMain.cpp b/tools/VersionMain.cpp
index 6f1c13cb..2c9c5456 100644
--- a/tools/VersionMain.cpp
+++ b/tools/VersionMain.cpp
@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: MPL-2.0 WITH AdditionRef-Progmasoft-Exception-2.0
 
 // bazelisk run //tools:version                  prints the current version
-// bazelisk run //tools:version -- --next        moves to the next version
-// bazelisk run //tools:version -- 0.3.1.0       moves to that version
+// bazelisk run //tools:version -- --next        moves to the next patch release
+// bazelisk run //tools:version -- 0.4.0         moves to that version
 //
 // Moving writes every place that states the version, and the amalgamation.
 
@@ -44,16 +44,19 @@ main(int argc, char **argv)
         return 0;
     }
     const std::string_view argument{ argv[1] };
-    const auto parsed = ParseVersion(
-        argument == "--next" ? *current : std::string{ argument });
+    const auto parsed
+        = argument == "--next" ? NextPatch(*current) : ParseVersion(argument);
     if (!parsed)
     {
-        std::cerr << "not a version of three or four numbers: " << argument
+        std::cerr << (argument == "--next"
+                          ? "the current version is not a release version: "
+                                + *current
+                          : "not a version MAJOR.MINOR.PATCH: "
+                                + std::string{ argument })
                   << '\n';
         return 2;
     }
-    const auto version
-        = FormatVersion(argument == "--next" ? NextVersion(*parsed) : *parsed);
+    const auto version = FormatVersion(*parsed);
     // The sources have to make a distribution before anything is changed.
     (void)GenerateAmalgamation(*root, problems);
     if (problems.empty())
diff --git a/tools/Versions.cpp b/tools/Versions.cpp
index abc6d5b3..acc0fb4e 100644
--- a/tools/Versions.cpp
+++ b/tools/Versions.cpp
@@ -17,72 +17,67 @@ namespace Progmasoft::Catch3::Tools
             = "src/Progmasoft/Catch3/Version.hpp";
     } // namespace
 
-    std::optional<Version>
-    ParseVersion(std::string_view text)
+    namespace
     {
-        Version version{};
-        std::size_t count = 0;
-        while (true)
+        /// The dot-separated numbers of `text`, at most `limit` of them, none
+        /// empty or with a leading zero; nothing for anything else.
+        std::optional<std::vector<unsigned>>
+        Numbers(std::string_view text, std::size_t limit)
         {
-            const auto dot = text.find('.');
-            const auto number = text.substr(0, dot);
-            if (count == version.size() || number.empty()
-                || (number.size() > 1 && number.front() == '0'))
+            std::vector<unsigned> numbers;
+            while (true)
             {
-                return std::nullopt;
+                const auto dot = text.find('.');
+                const auto number = text.substr(0, dot);
+                if (numbers.size() == limit || number.empty()
+                    || (number.size() > 1 && number.front() == '0'))
+                {
+                    return std::nullopt;
+                }
+                unsigned value = 0;
+                const auto *end = number.data() + number.size();
+                const auto parsed = std::from_chars(number.data(), end, value);
+                if (parsed.ec != std::errc{} || parsed.ptr != end)
+                {
+                    return std::nullopt;
+                }
+                numbers.push_back(value);
+                if (dot == std::string_view::npos)
+                {
+                    return numbers;
+                }
+                text.remove_prefix(dot + 1);
             }
-            const auto *end = number.data() + number.size();
-            const auto parsed
-                = std::from_chars(number.data(), end, version[count]);
-            if (parsed.ec != std::errc{} || parsed.ptr != end)
-            {
-                return std::nullopt;
-            }
-            ++count;
-            if (dot == std::string_view::npos)
-            {
-                break;
-            }
-            text.remove_prefix(dot + 1);
         }
-        if (count < 3)
+    } // namespace
+
+    std::optional<Version>
+    ParseVersion(std::string_view text)
+    {
+        const auto numbers = Numbers(text, 3);
+        if (!numbers || numbers->size() != 3)
         {
             return std::nullopt;
         }
-        return version;
+        return Version{ (*numbers)[0], (*numbers)[1], (*numbers)[2] };
     }
 
     std::string
     FormatVersion(const Version &version)
     {
         return std::to_string(version[0]) + "." + std::to_string(version[1])
-               + "." + std::to_string(version[2]) + "."
-               + std::to_string(version[3]);
+               + "." + std::to_string(version[2]);
     }
 
-    Version
-    NextVersion(Version version)
+    std::optional<Version>
+    NextPatch(std::string_view current)
     {
-        if (version[3] < 9)
+        const auto numbers = Numbers(current, 4);
+        if (!numbers || numbers->size() < 3)
         {
-            ++version[3];
-            return version;
-        }
-        version[3] = 0;
-        if (version[2] < 9)
-        {
-            ++version[2];
-            return version;
-        }
-        version[2] = 0;
-        if (version[1] < 19)
-        {
-            ++version[1];
-            return version;
+            return std::nullopt;
         }
-        version[1] = 0;
-        ++version[0];
-        return version;
+        return Version{ (*numbers)[0], (*numbers)[1], (*numbers)[2] + 1 };
     }
 
     const std::array<VersionSite, 5> &
@@ -211,17 +206,10 @@ namespace Progmasoft::Catch3::Tools
     std::optional<std::string>
     ReleaseNotesOf(std::string_view notes, std::string_view version)
     {
-        auto heading = "\n## " + std::string{ version } + "\n";
-        auto found = notes.find(heading);
-        // A release with D = 0 may be headed by its three numbers.
-        const auto parsed = ParseVersion(version);
-        if (found == std::string_view::npos && parsed && (*parsed)[3] == 0)
-        {
-            heading = "\n## " + std::to_string((*parsed)[0]) + "."
-                      + std::to_string((*parsed)[1]) + "."
-                      + std::to_string((*parsed)[2]) + "\n";
-            found = notes.find(heading);
-        }
+        // Every release is headed by its version as it was published: three
+        // numbers, or four for the releases before Semantic Versioning.
+        const auto heading = "\n## " + std::string{ version } + "\n";
+        const auto found = notes.find(heading);
         if (found == std::string_view::npos)
         {
             return std::nullopt;
diff --git a/tools/Versions.hpp b/tools/Versions.hpp
index 3a601a50..a1fdf4a6 100644
--- a/tools/Versions.hpp
+++ b/tools/Versions.hpp
@@ -12,19 +12,22 @@
 
 namespace Progmasoft::Catch3::Tools
 {
-    /// A.B.C.D. A version of three numbers has D = 0.
-    using Version = std::array<unsigned, 4>;
+    /// MAJOR.MINOR.PATCH, as Semantic Versioning numbers a release.
+    using Version = std::array<unsigned, 3>;
 
+    /// A version of exactly three numbers, none with a leading zero.
     [[nodiscard]] std::optional<Version>
     ParseVersion(std::string_view text);
 
     [[nodiscard]] std::string
     FormatVersion(const Version &version);
 
-    /// The version after `version`, which counts releases: D up to 9, then C
-    /// up to 9, then B up to 19, then A.
-    [[nodiscard]] Version
-    NextVersion(Version version);
+    /// The next patch release after `current`. `current` may also be one of
+    /// the four-number versions Catch3 had before Semantic Versioning: the
+    /// fourth number is dropped and the patch goes up, so 0.3.0.2 is followed
+    /// by 0.3.1.
+    [[nodiscard]] std::optional<Version>
+    NextPatch(std::string_view current);
 
     /// A place that states the version: the file, and the text around it.
     struct VersionSite final