feat(api): support ref suffixes in compare (#38148)

Compare API requests with a `^` or `~N` revision suffix (for example
`compare/main...feature^`) were rejected with `400 Unsupported
comparison syntax: ref with suffix`. The fix resolves the suffix to a
commit before comparing, so `base...head^` and `~N` work on either side,
the same as git.

Only `^`/`~N` navigation is resolved. Pull request creation still
requires plain branch refs, and the web compare page keeps rejecting
suffixes since its branch selectors need separate UI work.

Closes #33943

templates/swagger/v1_json.tmpl

@@ -8135,7 +8135,7 @@
           },
           {
             "type": "string",
-            "description": "compare two refs as `base...head` (or `base..head`); refs may be branches, tags, full or short SHAs, including branch names that contain slashes.",
+            "description": "compare two refs as `base...head` (or `base..head`); refs may be branches, tags, full or short SHAs (including branch names that contain slashes), optionally with a `^` or `~N` revision suffix.",
             "name": "basehead",
             "in": "path",
             "required": true
@@ -8155,6 +8155,9 @@
           "200": {
             "$ref": "#/responses/Compare"
           },
+          "400": {
+            "$ref": "#/responses/error"
+          },
           "404": {
             "$ref": "#/responses/notFound"
           }

templates/swagger/v1_openapi3_json.tmpl

@@ -19490,7 +19490,7 @@
             }
           },
           {
-            "description": "compare two refs as `base...head` (or `base..head`); refs may be branches, tags, full or short SHAs, including branch names that contain slashes.",
+            "description": "compare two refs as `base...head` (or `base..head`); refs may be branches, tags, full or short SHAs (including branch names that contain slashes), optionally with a `^` or `~N` revision suffix.",
             "in": "path",
             "name": "basehead",
             "required": true,
@@ -19515,6 +19515,9 @@
           "200": {
             "$ref": "#/components/responses/Compare"
           },
+          "400": {
+            "$ref": "#/components/responses/error"
+          },
           "404": {
             "$ref": "#/components/responses/notFound"
           }