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

routers/common/compare_test.go

@@ -6,6 +6,8 @@ package common
 import (
 	"testing"
 
+	"gitea.dev/modules/util"
+
 	"github.com/stretchr/testify/assert"
 )
 
@@ -97,9 +99,56 @@ func TestCompareRouterReq(t *testing.T) {
 				HeadOriRef:       "develop",
 			},
 		},
+		{
+			input: "main...develop^",
+			CompareRouterReq: &CompareRouterReq{
+				BaseOriRef:       "main",
+				CompareSeparator: "...",
+				HeadOriRef:       "develop",
+				HeadOriRefSuffix: "^",
+			},
+		},
+		{
+			input: "main~2...develop",
+			CompareRouterReq: &CompareRouterReq{
+				BaseOriRef:       "main",
+				BaseOriRefSuffix: "~2",
+				CompareSeparator: "...",
+				HeadOriRef:       "develop",
+			},
+		},
+		{
+			input: "main...lunny/forked_repo:develop~3",
+			CompareRouterReq: &CompareRouterReq{
+				BaseOriRef:       "main",
+				CompareSeparator: "...",
+				HeadOwner:        "lunny",
+				HeadRepoName:     "forked_repo",
+				HeadOriRef:       "develop",
+				HeadOriRefSuffix: "~3",
+			},
+		},
+		{
+			input: "develop^",
+			CompareRouterReq: &CompareRouterReq{
+				CompareSeparator: "...",
+				HeadOriRef:       "develop",
+				HeadOriRefSuffix: "^",
+			},
+		},
 	}
 
 	for _, c := range cases {
 		assert.Equal(t, c.CompareRouterReq, ParseCompareRouterParam(c.input), "input: %s", c.input)
 	}
 }
+
+func TestResolveRefWithSuffix(t *testing.T) {
+	// The ^{...}, @{...} and :path forms address non-commit objects or reflog state, so they are
+	// rejected before any repository access and a nil repo is fine here.
+	for _, refSuffix := range []string{"^{/Add}", "^{commit}", "@{upstream}", "~1:path"} {
+		ref, err := ResolveRefWithSuffix(nil, "branch", refSuffix)
+		assert.ErrorIs(t, err, util.ErrInvalidArgument, "suffix %q", refSuffix)
+		assert.Empty(t, ref, "suffix %q", refSuffix)
+	}
+}