fix(release): wire rest.rst example versions into bump/verify; fail on unparseable version

The gateway-version literals in docs/api/rest.rst example responses (root `/`
and version-info `vendor_info`) were bumped by hand and were not covered by
`release.sh bump`/`verify`, so a future release would leave them stale and
`verify` would not catch it. Bump and verify them now, anchored on the adjacent
`name` keys so the SOVD API `"version": "1.0.0"` is never rewritten or checked.

Also harden the no-arg `verify` consistency path: a version pattern that fails
to match falls through as `unknown`, and an all-`unknown` run would collapse to
a single unique value and false-pass. Treat any `unknown` as a hard failure.

Author: bburda

scripts/release.sh

@@ -35,6 +35,7 @@ CONF_PY="${REPO_ROOT}/docs/conf.py"
 DOCS_PYPROJECT="${REPO_ROOT}/docs/pyproject.toml"
 DOXYFILE="${REPO_ROOT}/docs/Doxyfile"
 QUALITY_DECL="${REPO_ROOT}/QUALITY_DECLARATION.md"
+REST_RST="${REPO_ROOT}/docs/api/rest.rst"
 
 usage() {
     echo "Usage: $0 {bump <version>|verify [<version>]}"
@@ -126,6 +127,20 @@ cmd_bump() {
         echo "  QUALITY_DECLARATION.md: -> ${target_version}"
     fi
 
+    # Update the gateway-version literals in docs/api/rest.rst example responses.
+    # Each is anchored on its adjacent "name" key so the SOVD API "version":
+    # "1.0.0" (which has neither anchor) is never rewritten:
+    #   - root "/" response:       "name": "ROS 2 Medkit Gateway" then "version"
+    #   - version-info vendor_info: "version" then "name": "ros2_medkit"
+    if [ -f "$REST_RST" ]; then
+        REST_TARGET="$target_version" perl -0pi -e '
+            my $v = $ENV{REST_TARGET};
+            s/("name": "ROS 2 Medkit Gateway",\s*\n\s*"version": ")\d+\.\d+\.\d+(")/$1$v$2/g;
+            s/("version": ")\d+\.\d+\.\d+(",\s*\n\s*"name": "ros2_medkit")/$1$v$2/g;
+        ' "$REST_RST"
+        echo "  docs/api/rest.rst example versions: -> ${target_version}"
+    fi
+
     echo ""
     echo "Bumped ${count} packages + version.hpp + docs to ${target_version}."
     echo ""
@@ -222,8 +237,38 @@ cmd_verify() {
         versions_seen+=("$qd_version")
     fi
 
+    # Check docs/api/rest.rst example-response versions (gateway version only;
+    # the SOVD API "version": "1.0.0" is excluded via the same name anchors as
+    # the bump path, so it is neither rewritten nor verified here).
+    if [ -f "$REST_RST" ]; then
+        local rest_versions
+        rest_versions=$(perl -0ne '
+            while (/"name": "ROS 2 Medkit Gateway",\s*\n\s*"version": "(\d+\.\d+\.\d+)"/g) { print "$1\n" }
+            while (/"version": "(\d+\.\d+\.\d+)",\s*\n\s*"name": "ros2_medkit"/g) { print "$1\n" }
+        ' "$REST_RST")
+        [ -n "$rest_versions" ] || rest_versions="unknown"
+        while IFS= read -r rest_version; do
+            if [ -n "$expected_version" ] && [ "$rest_version" != "$expected_version" ]; then
+                echo "  MISMATCH: docs/api/rest.rst example version is ${rest_version}, expected ${expected_version}"
+                all_ok=false
+            else
+                echo "  OK: docs/api/rest.rst example version = ${rest_version}"
+            fi
+            versions_seen+=("$rest_version")
+        done <<< "$rest_versions"
+    fi
+
     # Check consistency if no expected version given
     if [ -z "$expected_version" ]; then
+        # An "unknown" means a version pattern failed to match in some file.
+        # Without this guard an all-"unknown" run collapses to one unique value
+        # and would false-pass the consistency check below.
+        if printf '%s\n' "${versions_seen[@]}" | grep -qx "unknown"; then
+            echo ""
+            echo "ERROR: could not parse a version from one or more files (got 'unknown')."
+            all_ok=false
+        fi
+
         local unique_versions
         unique_versions=$(printf '%s\n' "${versions_seen[@]}" | sort -u)
         local unique_count