Merge pull request 'fix(github): consolidate review.go and identity.go into reviews.go (#116)' (#119) from review-bot-issue-116 into feature/github-support

Reviewed-on: #119
Reviewed-by: Aaron Weiker <aaron@weiker.org>
Reviewed-by: security-review-bot <10+security-review-bot@noreply.gitea.weiker.me>

cmd/review-bot/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"errors"
 	"flag"
 	"fmt"
 	"log/slog"
@@ -85,16 +84,9 @@ func main() {
 	aicoreAPIURL := flag.String("aicore-api-url", envOrDefault("AICORE_API_URL", ""), "SAP AI Core API URL (for provider=aicore)")
 	aicoreResourceGroup := flag.String("aicore-resource-group", envOrDefault("AICORE_RESOURCE_GROUP", "default"), "SAP AI Core resource group (for provider=aicore)")
 
-	// Register --gitea-url as a backward-compatible alias for --vcs-url.
-	// StringVar shares the *string pointer with vcsURL, so whichever flag is
-	// set last by flag.Parse wins — both point to the same underlying value.
-	// NOTE: If a user passes both --vcs-url and --gitea-url, the last one on
-	// the command line takes effect (standard flag package behavior). This is
-	// acceptable since --gitea-url is deprecated and both serve the same purpose.
-	//
-	// ORDERING: This must remain AFTER vcsURL's flag.String declaration and BEFORE
-	// flag.Parse(). The *vcsURL dereference captures the env-var-resolved default
-	// at registration time; moving flag.Parse() above this line would break it.
+	// Backward-compatible alias: --gitea-url shares vcsURL's pointer (last flag wins).
+	// Must use *vcsURL as default: StringVar sets *p=value at registration, so empty
+	// string would overwrite the env-resolved value from the --vcs-url declaration.
 	flag.StringVar(vcsURL, "gitea-url", *vcsURL, "Deprecated: use --vcs-url instead")
 
 	flag.Parse()
@@ -110,10 +102,8 @@ func main() {
 	slog.Info("review-bot starting", "version", version)
 
 	// Validate VCS provider
-	switch *provider {
-	case "gitea", "github":
-		// valid
-	default:
+	vcsProvider := vcs.VCSProvider(*provider)
+	if !vcsProvider.Valid() {
 		fmt.Fprintf(os.Stderr, "Error: invalid --provider %q (valid: gitea, github)\n", *provider)
 		os.Exit(1)
 	}
@@ -126,7 +116,7 @@ func main() {
 		os.Exit(1)
 	}
 	// --vcs-url is required only for gitea provider
-	if *provider == "gitea" && *vcsURL == "" {
+	if vcsProvider == vcs.ProviderGitea && *vcsURL == "" {
 		fmt.Fprintf(os.Stderr, "Error: --vcs-url (or --gitea-url) is required for provider=gitea\n")
 		os.Exit(1)
 	}
@@ -169,21 +159,16 @@ func main() {
 
 	// Initialize VCS client
 	var client vcs.Client
-	switch *provider {
-	case "gitea":
+	switch vcsProvider {
+	case vcs.ProviderGitea:
 		giteaClient := gitea.NewClient(*vcsURL, *reviewerToken)
 		client = gitea.NewAdapter(giteaClient)
-	case "github":
-		ghBaseURL := *baseURL
-		if ghBaseURL == "" {
-			ghBaseURL = "https://api.github.com"
-		}
-		client = github.NewClient(*reviewerToken, ghBaseURL)
+	case vcs.ProviderGitHub:
+		client = github.NewClient(*reviewerToken, *baseURL)
 	default:
-		fmt.Fprintf(os.Stderr, "Error: unhandled provider %q\n", *provider)
-		os.Exit(1)
+		panic("unreachable: provider validation should have caught " + vcsProvider.String())
 	}
-	slog.Info("VCS client initialized", "provider", *provider)
+	slog.Info("VCS client initialized", "provider", vcsProvider)
 
 	// Initialize LLM client
 	llmClient := llm.NewClient(*llmBaseURL, *llmAPIKey, *llmModel)
@@ -432,7 +417,7 @@ func main() {
 		currentSHA = currentPR.Head.SHA
 	}
 	if shouldSkipStaleReview(evaluatedSHA, currentSHA) {
-		slog.Warn("HEAD moved during review — skipping stale review",
+		slog.Warn("HEAD moved during review -- skipping stale review",
 			"evaluated", evaluatedSHA,
 			"current", currentSHA,
 			"pr", prNumber)
@@ -454,7 +439,7 @@ func main() {
 		inlineComments = append(inlineComments, vcs.ReviewComment{
 			Path:     f.File,
 			Position: pos,
-			CommitID: pr.Head.SHA,
+			CommitID: evaluatedSHA,
 			Body:     fmt.Sprintf("**[%s]** %s", f.Severity, f.Finding),
 		})
 	}
@@ -480,12 +465,12 @@ func main() {
 	}
 
 	// Self-request as reviewer (Gitea-specific; ensures we appear in required-reviewer checks)
-	if giteaAdapter, ok := client.(*gitea.Adapter); ok {
+	if selfReq, ok := client.(vcs.ReviewerSelfRequester); ok {
 		authUser, err := client.GetAuthenticatedUser(ctx)
 		if err != nil {
 			slog.Warn("could not determine authenticated user for reviewer self-request", "error", err)
 		} else if authUser != "" {
-			if err := giteaAdapter.Underlying().RequestReviewer(ctx, owner, repoName, prNumber, authUser); err != nil {
+			if err := selfReq.RequestReviewerSelf(ctx, owner, repoName, prNumber, authUser); err != nil {
 				slog.Warn("could not self-request as reviewer", "user", authUser, "error", err)
 			} else {
 				slog.Debug("self-requested as reviewer", "user", authUser, "pr", prNumber)
@@ -500,6 +485,7 @@ func main() {
 	reviewReq := vcs.ReviewRequest{
 		Body:     reviewBody,
 		Event:    event,
+		CommitID: evaluatedSHA,
 		Comments: inlineComments,
 	}
 	posted, err := client.PostReview(ctx, owner, repoName, prNumber, reviewReq)
@@ -509,11 +495,15 @@ func main() {
 	}
 	slog.Info("review posted", "review_id", posted.ID, "user", posted.User.Login, "pr", prNumber)
 
-	// Supersede all old reviews
+	// Supersede all old reviews via optional interface
 	if len(oldReviews) > 0 {
-		if err := supersedeOldReviews(ctx, client, *provider, *vcsURL, owner, repoName, prNumber, oldReviews, posted.ID, sentinel); err != nil {
-			slog.Error("failed to supersede old reviews", "error", err)
-			os.Exit(1)
+		if superseder, ok := client.(vcs.ReviewSuperseder); ok {
+			if err := superseder.SupersedeReviews(ctx, owner, repoName, prNumber, oldReviews, posted.ID, *vcsURL, sentinel); err != nil {
+				slog.Error("failed to supersede old reviews", "error", err)
+				os.Exit(1)
+			}
+		} else {
+			slog.Error("provider does not support review superseding", "provider", vcsProvider)
 		}
 	}
 }
@@ -530,84 +520,6 @@ func verdictToEvent(verdict string) vcs.ReviewEvent {
 	}
 }
 
-// supersedeOldReviews marks prior reviews as superseded so only the latest review is visible.
-// For GitHub: dismisses old reviews (vcsURL is unused in this path).
-// For Gitea: edits the review body with a link to the new review and resolves inline comments.
-//
-// The vcsURL parameter is only used in the Gitea path to construct review permalink URLs;
-// it is accepted unconditionally to keep the function signature uniform across providers.
-func supersedeOldReviews(ctx context.Context, client vcs.Client, provider, vcsURL, owner, repoName string, prNumber int, oldReviews []vcs.Review, newReviewID int64, sentinel string) error {
-	switch provider {
-	case "github":
-		// Best-effort dismissal: attempt all reviews, join any errors.
-		var errs []error
-		for _, old := range oldReviews {
-			if err := client.DismissReview(ctx, owner, repoName, prNumber, old.ID, "Superseded by new review"); err != nil {
-				slog.Warn("failed to dismiss review", "id", old.ID, "error", err)
-				errs = append(errs, fmt.Errorf("dismiss review %d: %w", old.ID, err))
-			} else {
-				slog.Info("dismissed old review", "review_id", old.ID, "new_review_id", newReviewID, "pr", prNumber)
-			}
-		}
-		return errors.Join(errs...)
-	case "gitea":
-		// Continue to Gitea-specific logic below the switch.
-	default:
-		return fmt.Errorf("supersedeOldReviews: unsupported provider %q", provider)
-	}
-
-	// The type assertion below is guaranteed to succeed: the caller's provider switch
-	// ensures we only reach this point when provider == "gitea", and the gitea provider
-	// always constructs a *gitea.Adapter. The !ok branch guards against future refactors
-	// (e.g. wrapping the adapter in a decorator) that would silently break this path.
-	giteaAdapter, ok := client.(*gitea.Adapter)
-	if !ok {
-		return fmt.Errorf("expected gitea.Adapter for gitea provider, got %T", client)
-	}
-	underlying := giteaAdapter.Underlying()
-
-	newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d", strings.TrimRight(vcsURL, "/"), owner, repoName, prNumber, newReviewID)
-	for _, oldReview := range oldReviews {
-		cid, err := underlying.GetTimelineReviewCommentIDForReview(ctx, owner, repoName, prNumber, oldReview.ID)
-		if err != nil {
-			slog.Warn("could not find comment ID for old review", "review_id", oldReview.ID, "error", err)
-			continue
-		}
-		supersededBody := buildSupersededBody(oldReview.Body, oldReview.CommitID, newReviewURL, sentinel)
-		if err := underlying.EditComment(ctx, owner, repoName, cid, supersededBody); err != nil {
-			slog.Warn("could not mark old review as superseded", "review_id", oldReview.ID, "comment_id", cid, "error", err)
-			continue
-		}
-		slog.Info("marked old review as superseded", "review_id", oldReview.ID, "new_review_id", newReviewID, "pr", prNumber)
-
-		// Resolve old review's inline comments
-		oldComments, err := underlying.ListReviewComments(ctx, owner, repoName, prNumber, oldReview.ID)
-		if err != nil {
-			slog.Warn("could not list old review comments for resolution", "review_id", oldReview.ID, "error", err)
-			continue
-		}
-		resolved, failed := 0, 0
-		for _, c := range oldComments {
-			if c.ID == 0 {
-				continue
-			}
-			if err := underlying.ResolveComment(ctx, owner, repoName, c.ID); err != nil {
-				slog.Debug("could not resolve inline comment", "comment_id", c.ID, "error", err)
-				failed++
-			} else {
-				resolved++
-			}
-		}
-		if resolved > 0 {
-			slog.Info("resolved old inline comments", "review_id", oldReview.ID, "count", resolved, "pr", prNumber)
-		}
-		if failed > 0 {
-			slog.Warn("some inline comments could not be resolved", "review_id", oldReview.ID, "failed", failed, "pr", prNumber)
-		}
-	}
-	return nil
-}
-
 // fetchFileContext fetches the full content of modified files from the PR branch.
 func fetchFileContext(ctx context.Context, client vcs.PRReader, owner, repo, ref string, files []vcs.ChangedFile) string {
 	var sb strings.Builder
@@ -635,6 +547,7 @@ func fetchFileContext(ctx context.Context, client vcs.PRReader, owner, repo, ref
 // patternsRepo is comma-separated list of owner/name repos.
 // patternsFiles is comma-separated list of file paths or directories.
 // If a path ends with / or is a directory, all files within it are fetched recursively.
+// Empty entries in patternsFiles are skipped (no implicit repo-root fetch).
 func fetchPatterns(ctx context.Context, client vcs.FileReader, patternsRepo, patternsFiles string) string {
 	var sb strings.Builder
 
@@ -759,14 +672,6 @@ func envOrDefaultInt(key string, defaultVal int) int {
 	return defaultVal
 }
 
-func envOrDefaultBool(key string, defaultVal bool) bool {
-	v := strings.TrimSpace(strings.ToLower(os.Getenv(key)))
-	if v == "" {
-		return defaultVal
-	}
-	return v == "true" || v == "1" || v == "yes"
-}
-
 // validateReviewerName checks that the name contains only safe characters
 // for embedding in an HTML comment sentinel ([a-zA-Z0-9_-]).
 func validateReviewerName(name string) error {
@@ -818,31 +723,6 @@ func validateWorkspacePath(path, pathName string) (string, error) {
 	return resolvedPath, nil
 }
 
-// buildSupersededBody creates the body for a superseded review: struck-through banner
-// with collapsed original content and the commit it was evaluated against.
-func buildSupersededBody(originalBody, commitSHA, newReviewURL, sentinel string) string {
-	shortSHA := commitSHA
-	if len(shortSHA) > 8 {
-		shortSHA = shortSHA[:8]
-	}
-	var sb strings.Builder
-	sb.WriteString("~~Original review~~\n\n")
-	sb.WriteString("**Superseded** \u2014 [see current review](")
-	sb.WriteString(newReviewURL)
-	sb.WriteString(") for up-to-date findings.\n\n")
-	if shortSHA != "" {
-		sb.WriteString("<details><summary>Previous findings (commit ")
-		sb.WriteString(shortSHA)
-		sb.WriteString(")</summary>\n\n")
-	} else {
-		sb.WriteString("<details><summary>Previous findings</summary>\n\n")
-	}
-	sb.WriteString(originalBody)
-	sb.WriteString("\n\n</details>\n\n")
-	sb.WriteString(sentinel)
-	return sb.String()
-}
-
 // hasSharedToken detects if another review-bot role posted under the same
 // VCS user. This indicates misconfiguration where two roles share a token
 // instead of having separate accounts. Returns true if shared token
@@ -860,7 +740,7 @@ func hasSharedToken(reviews []vcs.Review, ownSentinel string) bool {
 	}
 	for _, r := range reviews {
 		if r.User.Login == ownLogin && strings.Contains(r.Body, "<!-- review-bot:") && !strings.Contains(r.Body, ownSentinel) {
-			slog.Warn("shared token detected — another review-bot role is using the same VCS user",
+			slog.Warn("shared token detected -- another review-bot role is using the same VCS user",
 				"sibling_role", extractSentinelName(r.Body), "user", ownLogin)
 			return true
 		}
@@ -898,7 +778,6 @@ func extractSentinelName(body string) string {
 	return name
 }
 
-
 // findAllOwnReviews returns all non-superseded reviews matching the sentinel.
 func findAllOwnReviews(reviews []vcs.Review, sentinel string) []vcs.Review {
 	var result []vcs.Review

cmd/review-bot/main_test.go

@@ -162,55 +162,6 @@ func makeReview(id int64, login, state string, stale bool, body string) vcs.Revi
 	}
 }
 
-func TestBuildSupersededBody(t *testing.T) {
-	original := "# Review\n\nLooks good.\n\n<!-- review-bot:sonnet -->"
-	sentinel := "<!-- review-bot:sonnet -->"
-	newURL := "https://gitea.example.com/owner/repo/pulls/1#pullrequestreview-99"
-
-	result := buildSupersededBody(original, "abcdef1234567890", newURL, sentinel)
-
-	// Should contain the struck-through banner
-	if !strings.Contains(result, "~~Original review~~") {
-		t.Error("missing struck-through banner")
-	}
-	// Should contain superseded notice with link
-	if !strings.Contains(result, "**Superseded**") {
-		t.Error("missing superseded notice")
-	}
-	if !strings.Contains(result, "[see current review]("+newURL+")") {
-		t.Error("missing link to new review")
-	}
-	// Should contain collapsed original
-	if !strings.Contains(result, "<details>") {
-		t.Error("missing details/collapse")
-	}
-	// Should contain short commit SHA
-	if !strings.Contains(result, "abcdef12") {
-		t.Error("missing short SHA")
-	}
-	// Should NOT contain full SHA
-	if strings.Contains(result, "abcdef1234567890") {
-		t.Error("should truncate SHA to 8 chars")
-	}
-	// Should contain the original body inside details
-	if !strings.Contains(result, original) {
-		t.Error("original body not preserved in collapsed section")
-	}
-	// Should end with sentinel
-	if !strings.Contains(result, sentinel) {
-		t.Error("missing sentinel")
-	}
-}
-
-func TestBuildSupersededBodyShortSHA(t *testing.T) {
-	// Short SHA should pass through without panic
-	result := buildSupersededBody("body", "abc", "https://example.com/review", "<!-- review-bot:x -->")
-	if !strings.Contains(result, "abc") {
-		t.Error("short SHA not preserved")
-	}
-}
-
-
 func TestHasSharedToken(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -597,47 +548,6 @@ func TestEnvOrDefaultInt(t *testing.T) {
 	}
 }
 
-func TestEnvOrDefaultBool(t *testing.T) {
-	tests := []struct {
-		name       string
-		envVal     string
-		setEnv     bool
-		defaultVal bool
-		want       bool
-	}{
-		{"unset returns default true", "", false, true, true},
-		{"unset returns default false", "", false, false, false},
-		{"true", "true", true, false, true},
-		{"TRUE", "TRUE", true, false, true},
-		{"True", "True", true, false, true},
-		{"1", "1", true, false, true},
-		{"yes", "yes", true, false, true},
-		{"YES", "YES", true, false, true},
-		{"false", "false", true, true, false},
-		{"0", "0", true, true, false},
-		{"no", "no", true, true, false},
-		{"random string", "random", true, true, false},
-		{"empty string returns default", "", true, true, true},
-		{"whitespace true", "  true  ", true, false, true},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			envKey := "TEST_ENV_BOOL_" + strings.ReplaceAll(tc.name, " ", "_")
-			if tc.setEnv {
-				os.Setenv(envKey, tc.envVal)
-				defer os.Unsetenv(envKey)
-			} else {
-				os.Unsetenv(envKey)
-			}
-			got := envOrDefaultBool(envKey, tc.defaultVal)
-			if got != tc.want {
-				t.Errorf("envOrDefaultBool(%q, %v) = %v, want %v", tc.envVal, tc.defaultVal, got, tc.want)
-			}
-		})
-	}
-}
-
 func TestExtractSentinelName_EdgeCases(t *testing.T) {
 	tests := []struct {
 		body string
@@ -646,8 +556,8 @@ func TestExtractSentinelName_EdgeCases(t *testing.T) {
 		{"<!-- review-bot:sonnet --> rest", "sonnet"},
 		{"<!-- review-bot:gpt-review --> rest", "gpt-review"},
 		{"no sentinel here", "unknown"},
-		{"<!-- review-bot:", "unknown"},                   // prefix but no suffix
-		{"prefix <!-- review-bot:abc --> end", "abc"},     // embedded in text
+		{"<!-- review-bot:", "unknown"},               // prefix but no suffix
+		{"prefix <!-- review-bot:abc --> end", "abc"}, // embedded in text
 	}
 
 	for _, tc := range tests {

gitea/adapter.go

@@ -3,6 +3,8 @@ package gitea
 import (
 	"context"
 	"fmt"
+	"log/slog"
+	"strings"
 
 	"gitea.weiker.me/rodin/review-bot/vcs"
 )
@@ -16,6 +18,7 @@ type Adapter struct {
 
 // Compile-time interface conformance assertion.
 var _ vcs.Client = (*Adapter)(nil)
+var _ vcs.ReviewerSelfRequester = (*Adapter)(nil)
 
 // NewAdapter creates a new Adapter wrapping the given gitea Client.
 func NewAdapter(client *Client) *Adapter {
@@ -167,9 +170,9 @@ func (a *Adapter) PostReview(ctx context.Context, owner, repo string, number int
 			if err != nil {
 				return nil, fmt.Errorf("translate position %d in %s: %w", c.Position, c.Path, err)
 			}
-			// CommitID from vcs.ReviewComment is intentionally not forwarded:
-			// Gitea review comments are pinned to the PR head SHA automatically,
-			// and the CreatePullReview API has no per-comment commit_id field.
+			// Per-comment CommitID is not forwarded to Gitea inline comments:
+			// Gitea's CreatePullReview API has no per-comment commit_id field.
+			// The review-level commit anchor is set via req.CommitID instead.
 			giteaComments = append(giteaComments, ReviewComment{
 				Path:        c.Path,
 				NewPosition: int64(lineNum),
@@ -178,7 +181,7 @@ func (a *Adapter) PostReview(ctx context.Context, owner, repo string, number int
 		}
 	}
 
-	review, err := a.client.PostReview(ctx, owner, repo, number, event, req.Body, giteaComments)
+	review, err := a.client.PostReview(ctx, owner, repo, number, event, req.Body, req.CommitID, giteaComments)
 	if err != nil {
 		return nil, fmt.Errorf("post review: %w", err)
 	}
@@ -230,3 +233,84 @@ func (a *Adapter) DismissReview(ctx context.Context, owner, repo string, number
 func (a *Adapter) GetAuthenticatedUser(ctx context.Context) (string, error) {
 	return a.client.GetAuthenticatedUser(ctx)
 }
+
+// RequestReviewerSelf adds the given user as a requested reviewer on a pull request.
+// This implements vcs.ReviewerSelfRequester for the Gitea adapter.
+func (a *Adapter) RequestReviewerSelf(ctx context.Context, owner, repo string, number int, user string) error {
+	return a.client.RequestReviewer(ctx, owner, repo, number, user)
+}
+
+// Compile-time interface conformance assertion for ReviewSuperseder.
+var _ vcs.ReviewSuperseder = (*Adapter)(nil)
+
+// SupersedeReviews marks prior reviews as superseded by editing their body with a
+// link to the new review and resolving their inline comments. This is Gitea-specific
+// behavior that has no GitHub equivalent (GitHub uses DismissReview instead).
+//
+// baseURL is the Gitea instance URL used to construct review permalink URLs.
+// sentinel is the HTML comment sentinel that identifies reviews belonging to this reviewer.
+func (a *Adapter) SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []vcs.Review, newReviewID int64, baseURL, sentinel string) error {
+	// Validate baseURL scheme before embedding in Markdown link (defense-in-depth).
+	if !strings.HasPrefix(baseURL, "http://") && !strings.HasPrefix(baseURL, "https://") {
+		return fmt.Errorf("SupersedeReviews: baseURL must have http or https scheme, got %q", baseURL)
+	}
+
+	underlying := a.client
+
+	newReviewURL := fmt.Sprintf("%s/%s/%s/pulls/%d#pullrequestreview-%d",
+		strings.TrimRight(baseURL, "/"), owner, repo, prNumber, newReviewID)
+
+	for _, oldReview := range oldReviews {
+		cid, err := underlying.GetTimelineReviewCommentIDForReview(ctx, owner, repo, prNumber, oldReview.ID)
+		if err != nil {
+			slog.Warn("could not find comment ID for old review", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+		supersededBody := buildSupersededBody(oldReview.Body, oldReview.CommitID, newReviewURL, sentinel)
+		if err := underlying.EditComment(ctx, owner, repo, cid, supersededBody); err != nil {
+			slog.Warn("could not mark old review as superseded", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+
+		// Resolve old review's inline comments
+		oldComments, err := underlying.ListReviewComments(ctx, owner, repo, prNumber, oldReview.ID)
+		if err != nil {
+			slog.Warn("could not list old review comments for resolution", "review_id", oldReview.ID, "error", err)
+			continue
+		}
+		for _, c := range oldComments {
+			if c.ID == 0 {
+				continue
+			}
+			if err := underlying.ResolveComment(ctx, owner, repo, c.ID); err != nil {
+				slog.Debug("could not resolve inline comment", "comment_id", c.ID, "error", err)
+			}
+		}
+	}
+	return nil
+}
+
+// buildSupersededBody creates the body for a superseded review: struck-through banner
+// with collapsed original content and the commit it was evaluated against.
+func buildSupersededBody(originalBody, commitSHA, newReviewURL, sentinel string) string {
+	shortSHA := commitSHA
+	if len(shortSHA) > 8 {
+		shortSHA = shortSHA[:8]
+	}
+	var sb strings.Builder
+	sb.WriteString("~~Original review~~\n\n")
+	sb.WriteString("**Superseded** \u2014 [see current review](")
+	sb.WriteString(newReviewURL)
+	sb.WriteString(") for up-to-date findings.\n\n")
+	if shortSHA != "" {
+		sb.WriteString("<details><summary>Previous findings (commit ")
+		sb.WriteString(shortSHA)
+		sb.WriteString(")</summary>\n\n")
+	} else {
+		sb.WriteString("<details><summary>Previous findings</summary>\n\n")
+	}
+	sb.WriteString(originalBody)
+	sb.WriteString("\n\n</details>\n\n")
+	sb.WriteString(sentinel)
+	return sb.String()
+}

gitea/adapter_test.go

@@ -386,3 +386,95 @@ func TestAdapter_GetFileContent_RefRouting(t *testing.T) {
 		t.Errorf("GetFileContent(ref=\"abc123\") = %q, want %q", got, "content-at-ref")
 	}
 }
+
+func TestAdapter_RequestReviewerSelf(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Errorf("expected POST, got %s", r.Method)
+		}
+		expected := "/api/v1/repos/owner/repo/pulls/5/requested_reviewers"
+		if r.URL.Path != expected {
+			t.Errorf("path = %q, want %q", r.URL.Path, expected)
+		}
+		w.WriteHeader(http.StatusCreated)
+	}))
+	defer server.Close()
+
+	client := gitea.NewClient(server.URL, "token")
+	adapter := gitea.NewAdapter(client)
+
+	err := adapter.RequestReviewerSelf(context.Background(), "owner", "repo", 5, "bot-user")
+	if err != nil {
+		t.Fatalf("RequestReviewerSelf() error = %v", err)
+	}
+}
+
+func TestAdapter_PostReview_CommitID(t *testing.T) {
+	var gotPayload struct {
+		Body     string `json:"body"`
+		Event    string `json:"event"`
+		CommitID string `json:"commit_id"`
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        1,
+			"body":      "test",
+			"user":      map[string]any{"login": "bot"},
+			"commit_id": "abc123def456",
+		})
+	}))
+	defer server.Close()
+
+	client := gitea.NewClient(server.URL, "token")
+	adapter := gitea.NewAdapter(client)
+
+	review, err := adapter.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "LGTM",
+		Event:    vcs.ReviewEventApprove,
+		CommitID: "abc123def456",
+		// No comments → no diff fetch needed
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "abc123def456" {
+		t.Errorf("commit_id = %q, want %q", gotPayload.CommitID, "abc123def456")
+	}
+	if review.CommitID != "abc123def456" {
+		t.Errorf("review.CommitID = %q, want %q", review.CommitID, "abc123def456")
+	}
+}
+
+func TestAdapter_PostReview_EmptyCommitID_Omitted(t *testing.T) {
+	var gotRawPayload map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewDecoder(r.Body).Decode(&gotRawPayload)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   1,
+			"body": "test",
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := gitea.NewClient(server.URL, "token")
+	adapter := gitea.NewAdapter(client)
+
+	_, err := adapter.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:  "looks good",
+		Event: vcs.ReviewEventComment,
+		// CommitID intentionally empty
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// With empty CommitID and omitempty tag, the field should not appear in JSON
+	if _, exists := gotRawPayload["commit_id"]; exists {
+		t.Errorf("commit_id should be omitted when empty, but was present: %v", gotRawPayload["commit_id"])
+	}
+}

gitea/client.go

@@ -186,18 +186,22 @@ func (c *Client) GetFileContentRef(ctx context.Context, owner, repo, filepath, r
 }
 
 // PostReview submits a review to a PR and returns the created review.
-// event should be "APPROVED" or "REQUEST_CHANGES".
+// event should be one of "APPROVED", "REQUEST_CHANGES", or "COMMENT".
+// commitID anchors the review to a specific commit SHA. If empty, Gitea
+// defaults to the current PR head.
 // comments are optional inline comments attached to specific lines.
-func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body string, comments []ReviewComment) (*Review, error) {
+func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, event, body, commitID string, comments []ReviewComment) (*Review, error) {
 	reqURL := fmt.Sprintf("%s/api/v1/repos/%s/%s/pulls/%d/reviews", c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 
 	payload := struct {
 		Body     string          `json:"body"`
 		Event    string          `json:"event"`
+		CommitID string          `json:"commit_id,omitempty"`
 		Comments []ReviewComment `json:"comments,omitempty"`
 	}{
 		Body:     body,
 		Event:    event,
+		CommitID: commitID,
 		Comments: comments,
 	}
 

gitea/client_test.go

@@ -135,7 +135,7 @@ func TestPostReview(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", nil)
+	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", "", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -147,6 +147,46 @@ func TestPostReview(t *testing.T) {
 	}
 }
 
+func TestPostReview_CommitID(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "POST" {
+			t.Fatalf("expected POST, got %s", r.Method)
+		}
+
+		body, _ := io.ReadAll(r.Body)
+		var payload struct {
+			Body     string `json:"body"`
+			Event    string `json:"event"`
+			CommitID string `json:"commit_id"`
+		}
+		if err := json.Unmarshal(body, &payload); err != nil {
+			t.Fatalf("unmarshal payload: %v", err)
+		}
+		if payload.CommitID != "deadbeef123" {
+			t.Errorf("expected commit_id %q, got %q", "deadbeef123", payload.CommitID)
+		}
+		if payload.Event != "APPROVED" {
+			t.Errorf("expected event APPROVED, got %q", payload.Event)
+		}
+
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"id":101,"user":{"login":"review-bot"},"state":"APPROVED","stale":false,"commit_id":"deadbeef123"}`))
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	review, err := client.PostReview(context.Background(), "owner", "repo", 3, "APPROVED", "LGTM", "deadbeef123", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if review.ID != 101 {
+		t.Errorf("expected review ID 101, got %d", review.ID)
+	}
+	if review.CommitID != "deadbeef123" {
+		t.Errorf("expected commit_id %q, got %q", "deadbeef123", review.CommitID)
+	}
+}
+
 func TestGetPullRequest_Non200(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
@@ -182,7 +222,7 @@ func TestPostReview_Non200(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", nil)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "test", "", nil)
 	if err == nil {
 		t.Fatal("expected error for 403, got nil")
 	}
@@ -1144,3 +1184,62 @@ func TestSanitizeErrorForLog(t *testing.T) {
 		})
 	}
 }
+
+func TestPostReview_CommitID_InPayload(t *testing.T) {
+	var gotPayload struct {
+		Body     string `json:"body"`
+		Event    string `json:"event"`
+		CommitID string `json:"commit_id"`
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        200,
+			"body":      "LGTM",
+			"user":      map[string]any{"login": "bot"},
+			"state":     "APPROVED",
+			"commit_id": "deadbeef1234",
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	review, err := client.PostReview(context.Background(), "owner", "repo", 5, "APPROVED", "LGTM", "deadbeef1234", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "deadbeef1234" {
+		t.Errorf("sent commit_id = %q, want %q", gotPayload.CommitID, "deadbeef1234")
+	}
+	if review.CommitID != "deadbeef1234" {
+		t.Errorf("response commit_id = %q, want %q", review.CommitID, "deadbeef1234")
+	}
+}
+
+func TestPostReview_EmptyCommitID_OmittedFromPayload(t *testing.T) {
+	var gotRaw map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotRaw)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(200)
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":   201,
+			"body": "ok",
+			"user": map[string]any{"login": "bot"},
+		})
+	}))
+	defer server.Close()
+
+	client := NewClient(server.URL, "test-token")
+	_, err := client.PostReview(context.Background(), "owner", "repo", 5, "COMMENT", "ok", "", nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if _, exists := gotRaw["commit_id"]; exists {
+		t.Errorf("commit_id should be omitted when empty, but was present: %v", gotRaw["commit_id"])
+	}
+}

gitea/post_review_comments_test.go

@@ -37,7 +37,7 @@ func TestPostReview_WithComments(t *testing.T) {
 		{Path: "util.go", NewPosition: 10, Body: "[MINOR] Style issue"},
 	}
 
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", comments)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "REQUEST_CHANGES", "summary", "", comments)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -72,7 +72,7 @@ func TestPostReview_NilComments(t *testing.T) {
 	defer server.Close()
 
 	client := NewClient(server.URL, "test-token")
-	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", nil)
+	_, err := client.PostReview(context.Background(), "owner", "repo", 1, "APPROVED", "all good", "", nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}

gitea/supersede_test.go

@@ -0,0 +1,54 @@
+package gitea
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildSupersededBody(t *testing.T) {
+	original := "# Review\n\nLooks good.\n\n<!-- review-bot:sonnet -->"
+	sentinel := "<!-- review-bot:sonnet -->"
+	newURL := "https://gitea.example.com/owner/repo/pulls/1#pullrequestreview-99"
+
+	result := buildSupersededBody(original, "abcdef1234567890", newURL, sentinel)
+
+	// Should contain the struck-through banner
+	if !strings.Contains(result, "~~Original review~~") {
+		t.Error("missing struck-through banner")
+	}
+	// Should contain superseded notice with link
+	if !strings.Contains(result, "**Superseded**") {
+		t.Error("missing superseded notice")
+	}
+	if !strings.Contains(result, "[see current review]("+newURL+")") {
+		t.Error("missing link to new review")
+	}
+	// Should contain collapsed original
+	if !strings.Contains(result, "<details>") {
+		t.Error("missing details/collapse")
+	}
+	// Should contain short commit SHA
+	if !strings.Contains(result, "abcdef12") {
+		t.Error("missing short SHA")
+	}
+	// Should NOT contain full SHA in summary (it's truncated to 8)
+	if strings.Contains(result, "abcdef1234567890") {
+		t.Error("should truncate SHA to 8 chars")
+	}
+	// Should contain the original body inside details
+	if !strings.Contains(result, original) {
+		t.Error("original body not preserved in collapsed section")
+	}
+	// Should end with sentinel
+	if !strings.Contains(result, sentinel) {
+		t.Error("missing sentinel")
+	}
+}
+
+func TestBuildSupersededBodyShortSHA(t *testing.T) {
+	// Short SHA should pass through without panic
+	result := buildSupersededBody("body", "abc", "https://example.com/review", "<!-- review-bot:x -->")
+	if !strings.Contains(result, "abc") {
+		t.Error("short SHA not preserved")
+	}
+}

github/client.go

@@ -110,6 +110,11 @@ type Client struct {
 	// retryBackoff[i] is the delay before attempt i+1 (after attempt i fails).
 	// If nil, defaults to {1s, 2s}. Set to shorter durations in tests via SetRetryBackoff.
 	retryBackoff []time.Duration
+
+	// reviewPageSize overrides reviewsPerPage for testing. Zero means use default.
+	reviewPageSize int
+	// reviewMaxPages overrides maxReviewPages for testing. Zero means use default.
+	reviewMaxPages int
 }
 
 // defaultCheckRedirect is the redirect policy used by NewClient and SetHTTPClient(nil).
@@ -194,12 +199,32 @@ func (c *Client) SetRetryBackoff(d []time.Duration) error {
 	return nil
 }
 
-// doWithRetry performs an HTTP request with retry on 429 rate limit responses.
-// It delegates request construction to buildReq, which is called on each attempt
-// to produce a fresh *http.Request (allowing body re-reads for POST/PUT).
-// It respects the Retry-After header when present (capped at maxRetryAfter).
-// Transport errors (network failures, context cancellation) are not retried.
-func (c *Client) doWithRetry(ctx context.Context, reqURL string, buildReq func() (*http.Request, error)) ([]byte, error) {
+// SetReviewPagination overrides the page size and max pages for ListReviews.
+// Intended for testing only; must be called before any goroutines issue requests.
+func (c *Client) SetReviewPagination(pageSize, maxPages int) {
+	c.reviewPageSize = pageSize
+	c.reviewMaxPages = maxPages
+}
+
+// requestOptions holds per-request configuration for doRequestCore.
+type requestOptions struct {
+	// bodyFn returns a fresh io.Reader for the request body on each attempt.
+	// Must be non-nil for any request that carries a body (POST, PUT, PATCH,
+	// or DELETE when a body is required by the API).
+	// Returning a fresh reader on each call allows retries to re-send the body.
+	bodyFn func() io.Reader
+
+	// accept overrides the default Accept header. Empty means "application/vnd.github+json".
+	accept string
+
+	// extraHeaders are additional headers to set on each request attempt.
+	extraHeaders map[string]string
+}
+
+// doRequestCore is the shared implementation for all HTTP requests with retry
+// on 429 rate limit responses. It respects the Retry-After header when present
+// (capped at maxRetryAfter). Transport errors are not retried.
+func (c *Client) doRequestCore(ctx context.Context, method, reqURL string, opts requestOptions) ([]byte, error) {
 	const maxRetryAfter = 120 * time.Second
 
 	// maxErrorBodyBytes limits how much of an error response body is stored.
@@ -250,10 +275,29 @@ func (c *Client) doWithRetry(ctx context.Context, reqURL string, buildReq func()
 			}
 		}
 
-		req, err := buildReq()
+		var body io.Reader
+		if opts.bodyFn != nil {
+			body = opts.bodyFn()
+		}
+		req, err := http.NewRequestWithContext(ctx, method, reqURL, body)
 		if err != nil {
 			return nil, fmt.Errorf("create request: %w", err)
 		}
+		if c.token != "" {
+			// Bearer is the OAuth2 standard and is accepted by GitHub for both
+			// classic PATs and fine-grained tokens. The alternative "token" scheme
+			// is GitHub-specific and offers no additional compatibility.
+			req.Header.Set("Authorization", "Bearer "+c.token)
+		}
+		req.Header.Set("User-Agent", userAgent)
+		if opts.accept != "" {
+			req.Header.Set("Accept", opts.accept)
+		} else {
+			req.Header.Set("Accept", "application/vnd.github+json")
+		}
+		for k, v := range opts.extraHeaders {
+			req.Header.Set(k, v)
+		}
 
 		resp, err := c.httpClient.Do(req)
 		if err != nil {
@@ -264,9 +308,9 @@ func (c *Client) doWithRetry(ctx context.Context, reqURL string, buildReq func()
 		respStatus := resp.StatusCode
 		retryAfterHeader := resp.Header.Get("Retry-After")
 
-		body, done, handleErr := c.handleResponse(resp, maxResponseBytes, maxErrorBodyBytes)
+		respBody, done, handleErr := c.handleResponse(resp, maxResponseBytes, maxErrorBodyBytes)
 		if done {
-			return body, handleErr
+			return respBody, handleErr
 		}
 		lastErr = handleErr
 
@@ -310,26 +354,7 @@ func (c *Client) doWithRetry(ctx context.Context, reqURL string, buildReq func()
 // It respects the Retry-After header when present (capped at maxRetryAfter).
 // Transport errors (network failures, context cancellation) are not retried.
 func (c *Client) doRequest(ctx context.Context, method, reqURL string, accept string) ([]byte, error) {
-	buildReq := func() (*http.Request, error) {
-		req, err := http.NewRequestWithContext(ctx, method, reqURL, nil)
-		if err != nil {
-			return nil, err
-		}
-		if c.token != "" {
-			// Bearer is the OAuth2 standard and is accepted by GitHub for both
-			// classic PATs and fine-grained tokens. The alternative "token" scheme
-			// is GitHub-specific and offers no additional compatibility.
-			req.Header.Set("Authorization", "Bearer "+c.token)
-		}
-		req.Header.Set("User-Agent", userAgent)
-		if accept != "" {
-			req.Header.Set("Accept", accept)
-		} else {
-			req.Header.Set("Accept", "application/vnd.github+json")
-		}
-		return req, nil
-	}
-	return c.doWithRetry(ctx, reqURL, buildReq)
+	return c.doRequestCore(ctx, method, reqURL, requestOptions{accept: accept})
 }
 
 // handleResponse reads and closes the response body, returning the result.
@@ -361,8 +386,20 @@ func (c *Client) doGet(ctx context.Context, reqURL string) ([]byte, error) {
 	return c.doRequest(ctx, http.MethodGet, reqURL, "")
 }
 
+// doRequestWithBody is like doRequest but sends a request body.
+// It accepts the raw body bytes and sets Content-Type to application/json.
+// Retry semantics match doRequest (retries on 429 with Retry-After support).
+func (c *Client) doRequestWithBody(ctx context.Context, method, reqURL string, reqBody []byte) ([]byte, error) {
+	var opts requestOptions
+	if reqBody != nil {
+		opts.bodyFn = func() io.Reader { return bytes.NewReader(reqBody) }
+		opts.extraHeaders = map[string]string{"Content-Type": "application/json"}
+	}
+	return c.doRequestCore(ctx, method, reqURL, opts)
+}
+
 // doJSONRequest performs an HTTP request with a JSON body and returns the response body.
-// It delegates retry/backoff/429 handling to doWithRetry.
+// It delegates retry/backoff/429 handling to doRequestWithBody.
 // This is a general-purpose helper used by any method that needs to send JSON payloads
 // (e.g. PostReview, DismissReview).
 func (c *Client) doJSONRequest(ctx context.Context, method, reqURL string, payload any) ([]byte, error) {
@@ -370,19 +407,5 @@ func (c *Client) doJSONRequest(ctx context.Context, method, reqURL string, paylo
 	if err != nil {
 		return nil, fmt.Errorf("marshal request body: %w", err)
 	}
-
-	buildReq := func() (*http.Request, error) {
-		req, err := http.NewRequestWithContext(ctx, method, reqURL, bytes.NewReader(jsonBody))
-		if err != nil {
-			return nil, err
-		}
-		if c.token != "" {
-			req.Header.Set("Authorization", "Bearer "+c.token)
-		}
-		req.Header.Set("User-Agent", userAgent)
-		req.Header.Set("Accept", "application/vnd.github+json")
-		req.Header.Set("Content-Type", "application/json")
-		return req, nil
-	}
-	return c.doWithRetry(ctx, reqURL, buildReq)
+	return c.doRequestWithBody(ctx, method, reqURL, jsonBody)
 }

github/client_test.go

@@ -568,7 +568,6 @@ func TestSetHTTPClient_NilRestoresDefault(t *testing.T) {
 	}
 }
 
-
 func TestSetRetryBackoff_RejectsInvalidLength(t *testing.T) {
 	c := NewClient("token", "https://api.github.com")
 

github/conformance_test.go

@@ -5,6 +5,10 @@ import (
 	"gitea.weiker.me/rodin/review-bot/vcs"
 )
 
-// Compile-time interface conformance assertions.
-// These verify github.Client satisfies vcs.Client (the full interface).
+// Compile-time interface conformance assertion.
+// This verifies github.Client satisfies the full vcs.Client interface
+// (PRReader, FileReader, Reviewer, Identity).
 var _ vcs.Client = (*github.Client)(nil)
+
+// Verify github.Client implements ReviewSuperseder.
+var _ vcs.ReviewSuperseder = (*github.Client)(nil)

github/helpers_test.go

@@ -0,0 +1,23 @@
+package github
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// newTestClient creates a *Client backed by an httptest.Server running the
+// given handler. The server is automatically closed when the test finishes.
+// Shared across test files in package github.
+func newTestClient(t *testing.T, handler http.HandlerFunc) *Client {
+	t.Helper()
+	srv := httptest.NewServer(handler)
+	t.Cleanup(srv.Close)
+	c := NewClient("test-token", srv.URL, AllowInsecureHTTP())
+	c.SetHTTPClient(srv.Client())
+	if err := c.SetRetryBackoff([]time.Duration{1 * time.Millisecond, 1 * time.Millisecond}); err != nil {
+		t.Fatalf("SetRetryBackoff: %v", err)
+	}
+	return c
+}

github/identity_test.go

@@ -0,0 +1,46 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+)
+
+func TestGetAuthenticatedUser_HappyPath(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" {
+			t.Errorf("expected GET, got %s", r.Method)
+		}
+		if r.URL.Path != "/user" {
+			t.Errorf("unexpected path: %s", r.URL.Path)
+		}
+		if r.Header.Get("Authorization") != "Bearer test-token" {
+			t.Errorf("unexpected auth header: %s", r.Header.Get("Authorization"))
+		}
+		json.NewEncoder(w).Encode(map[string]string{"login": "review-bot"})
+	})
+
+	login, err := c.GetAuthenticatedUser(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if login != "review-bot" {
+		t.Errorf("expected login 'review-bot', got %q", login)
+	}
+}
+
+func TestGetAuthenticatedUser_401(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(401)
+		w.Write([]byte(`{"message":"Bad credentials"}`))
+	})
+
+	_, err := c.GetAuthenticatedUser(context.Background())
+	if err == nil {
+		t.Fatal("expected error for 401")
+	}
+	if !IsUnauthorized(err) {
+		t.Errorf("expected IsUnauthorized=true, got error: %v", err)
+	}
+}

github/review_test.go

@@ -0,0 +1,677 @@
+package github
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	"gitea.weiker.me/rodin/review-bot/vcs"
+)
+
+// --- PostReview tests ---
+
+func TestPostReview_HappyPath(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "POST" {
+			t.Fatalf("expected POST, got %s", r.Method)
+		}
+		if r.URL.Path != "/repos/owner/repo/pulls/5/reviews" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		if r.Header.Get("Content-Type") != "application/json" {
+			t.Errorf("expected Content-Type application/json, got %q", r.Header.Get("Content-Type"))
+		}
+
+		// Verify request body
+		body, _ := io.ReadAll(r.Body)
+		var req postReviewRequest
+		if err := json.Unmarshal(body, &req); err != nil {
+			t.Fatalf("unmarshal request: %v", err)
+		}
+		if req.Event != "APPROVE" {
+			t.Errorf("expected event APPROVE, got %q", req.Event)
+		}
+		if req.Body != "LGTM" {
+			t.Errorf("expected body 'LGTM', got %q", req.Body)
+		}
+		if req.CommitID != "abc123" {
+			t.Errorf("expected commit_id 'abc123', got %q", req.CommitID)
+		}
+		if len(req.Comments) != 1 {
+			t.Fatalf("expected 1 comment, got %d", len(req.Comments))
+		}
+		if req.Comments[0].Path != "main.go" {
+			t.Errorf("expected comment path 'main.go', got %q", req.Comments[0].Path)
+		}
+		if req.Comments[0].Position != 4 {
+			t.Errorf("expected comment position 4, got %d", req.Comments[0].Position)
+		}
+
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"id":        100,
+			"body":      "LGTM",
+			"state":     "APPROVED",
+			"commit_id": "abc123",
+			"user":      map[string]string{"login": "reviewer"},
+		})
+	})
+
+	review, err := c.PostReview(context.Background(), "owner", "repo", 5, vcs.ReviewRequest{
+		Body:  "LGTM",
+		Event: vcs.ReviewEventApprove,
+		Comments: []vcs.ReviewComment{
+			{Path: "main.go", Position: 4, CommitID: "abc123", Body: "nit: rename"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if review.ID != 100 {
+		t.Errorf("expected ID 100, got %d", review.ID)
+	}
+	if review.Body != "LGTM" {
+		t.Errorf("expected body 'LGTM', got %q", review.Body)
+	}
+	if review.State != "APPROVED" {
+		t.Errorf("expected state 'APPROVED', got %q", review.State)
+	}
+	if review.User.Login != "reviewer" {
+		t.Errorf("expected user 'reviewer', got %q", review.User.Login)
+	}
+	if review.CommitID != "abc123" {
+		t.Errorf("expected commit_id 'abc123', got %q", review.CommitID)
+	}
+}
+
+func TestPostReview_401(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(401)
+		w.Write([]byte(`{"message":"Bad credentials"}`))
+	})
+
+	_, err := c.PostReview(context.Background(), "owner", "repo", 5, vcs.ReviewRequest{
+		Body:  "LGTM",
+		Event: vcs.ReviewEventApprove,
+	})
+	if err == nil {
+		t.Fatal("expected error for 401")
+	}
+	if !IsUnauthorized(err) {
+		t.Errorf("expected IsUnauthorized=true, got error: %v", err)
+	}
+}
+
+func TestPostReview_422(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(422)
+		w.Write([]byte(`{"message":"Unprocessable Entity"}`))
+	})
+
+	_, err := c.PostReview(context.Background(), "owner", "repo", 5, vcs.ReviewRequest{
+		Body:  "LGTM",
+		Event: vcs.ReviewEventApprove,
+	})
+	if err == nil {
+		t.Fatal("expected error for 422")
+	}
+	// 422 should surface as a wrapped APIError
+	var apiErr *APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected *APIError, got %T: %v", err, err)
+	}
+	if apiErr.StatusCode != 422 {
+		t.Errorf("expected status 422, got %d", apiErr.StatusCode)
+	}
+}
+
+func TestPostReview_MalformedResponse(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`not json`))
+	})
+
+	_, err := c.PostReview(context.Background(), "owner", "repo", 5, vcs.ReviewRequest{
+		Body:  "LGTM",
+		Event: vcs.ReviewEventApprove,
+	})
+	if err == nil {
+		t.Fatal("expected error for malformed response")
+	}
+	if !strings.Contains(err.Error(), "parse review response") {
+		t.Errorf("expected parse error, got: %v", err)
+	}
+}
+
+// --- ListReviews tests ---
+
+func TestListReviews_HappyPath(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" {
+			t.Fatalf("expected GET, got %s", r.Method)
+		}
+		if r.URL.Path != "/repos/owner/repo/pulls/3/reviews" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		json.NewEncoder(w).Encode([]map[string]interface{}{
+			{
+				"id":        1,
+				"body":      "Approved",
+				"state":     "APPROVED",
+				"commit_id": "sha1",
+				"user":      map[string]string{"login": "user1"},
+			},
+			{
+				"id":        2,
+				"body":      "Needs work",
+				"state":     "CHANGES_REQUESTED",
+				"commit_id": "sha2",
+				"user":      map[string]string{"login": "user2"},
+			},
+			{
+				"id":        3,
+				"body":      "Comment only",
+				"state":     "COMMENTED",
+				"commit_id": "sha3",
+				"user":      map[string]string{"login": "user3"},
+			},
+			{
+				"id":        4,
+				"body":      "Old review",
+				"state":     "DISMISSED",
+				"commit_id": "sha4",
+				"user":      map[string]string{"login": "user4"},
+			},
+		})
+	})
+
+	reviews, err := c.ListReviews(context.Background(), "owner", "repo", 3)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 4 {
+		t.Fatalf("expected 4 reviews, got %d", len(reviews))
+	}
+
+	// Check state translation
+	expected := []struct {
+		id    int64
+		state string
+	}{
+		{1, "APPROVED"},
+		{2, "REQUEST_CHANGES"},
+		{3, "COMMENT"},
+		{4, "DISMISSED"},
+	}
+	for i, e := range expected {
+		if reviews[i].ID != e.id {
+			t.Errorf("review[%d]: expected ID %d, got %d", i, e.id, reviews[i].ID)
+		}
+		if reviews[i].State != e.state {
+			t.Errorf("review[%d]: expected state %q, got %q", i, e.state, reviews[i].State)
+		}
+	}
+}
+
+func TestListReviews_404(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(404)
+		w.Write([]byte(`{"message":"Not Found"}`))
+	})
+
+	_, err := c.ListReviews(context.Background(), "owner", "repo", 999)
+	if err == nil {
+		t.Fatal("expected error for 404")
+	}
+	if !IsNotFound(err) {
+		t.Errorf("expected IsNotFound=true, got error: %v", err)
+	}
+}
+
+func TestListReviews_401(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(401)
+		w.Write([]byte(`{"message":"Bad credentials"}`))
+	})
+
+	_, err := c.ListReviews(context.Background(), "owner", "repo", 3)
+	if err == nil {
+		t.Fatal("expected error for 401")
+	}
+	if !IsUnauthorized(err) {
+		t.Errorf("expected IsUnauthorized=true, got error: %v", err)
+	}
+}
+
+// --- DeleteReview tests ---
+
+func TestDeleteReview_HappyPath(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "DELETE" {
+			t.Fatalf("expected DELETE, got %s", r.Method)
+		}
+		if r.URL.Path != "/repos/owner/repo/pulls/5/reviews/42" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		w.WriteHeader(204)
+	})
+
+	err := c.DeleteReview(context.Background(), "owner", "repo", 5, 42)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDeleteReview_422_SubmittedReview(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(422)
+		w.Write([]byte(`{"message":"Can not delete a non pending review"}`))
+	})
+
+	err := c.DeleteReview(context.Background(), "owner", "repo", 5, 42)
+	if err == nil {
+		t.Fatal("expected error for 422")
+	}
+	if !errors.Is(err, ErrCannotDeleteSubmittedReview) {
+		t.Errorf("expected ErrCannotDeleteSubmittedReview, got: %v", err)
+	}
+}
+
+// --- DismissReview tests ---
+
+func TestDismissReview_HappyPath(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "PUT" {
+			t.Fatalf("expected PUT, got %s", r.Method)
+		}
+		if r.URL.Path != "/repos/owner/repo/pulls/5/reviews/10/dismissals" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+
+		body, _ := io.ReadAll(r.Body)
+		var req dismissReviewRequest
+		if err := json.Unmarshal(body, &req); err != nil {
+			t.Fatalf("unmarshal request: %v", err)
+		}
+		if req.Message != "Superseded by new review" {
+			t.Errorf("expected message 'Superseded by new review', got %q", req.Message)
+		}
+		if req.Event != "DISMISS" {
+			t.Errorf("expected event 'DISMISS', got %q", req.Event)
+		}
+
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"id":    10,
+			"state": "DISMISSED",
+		})
+	})
+
+	err := c.DismissReview(context.Background(), "owner", "repo", 5, 10, "Superseded by new review")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestDismissReview_404(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(404)
+		w.Write([]byte(`{"message":"Not Found"}`))
+	})
+
+	err := c.DismissReview(context.Background(), "owner", "repo", 5, 999, "dismiss")
+	if err == nil {
+		t.Fatal("expected error for 404")
+	}
+	if !IsNotFound(err) {
+		t.Errorf("expected IsNotFound=true, got error: %v", err)
+	}
+}
+
+func TestDismissReview_401(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(401)
+		w.Write([]byte(`{"message":"Bad credentials"}`))
+	})
+
+	err := c.DismissReview(context.Background(), "owner", "repo", 5, 10, "dismiss")
+	if err == nil {
+		t.Fatal("expected error for 401")
+	}
+	if !IsUnauthorized(err) {
+		t.Errorf("expected IsUnauthorized=true, got error: %v", err)
+	}
+}
+
+// --- State translation tests ---
+
+func TestTranslateGitHubReviewState(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{"approved passes through", "APPROVED", "APPROVED"},
+		{"changes_requested maps to REQUEST_CHANGES", "CHANGES_REQUESTED", "REQUEST_CHANGES"},
+		{"commented maps to COMMENT", "COMMENTED", "COMMENT"},
+		{"dismissed passes through", "DISMISSED", "DISMISSED"},
+		{"unknown state passes through", "UNKNOWN_STATE", "UNKNOWN_STATE"},
+		{"empty string passes through", "", ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := translateGitHubReviewState(tt.input)
+			if got != tt.want {
+				t.Errorf("translateGitHubReviewState(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestPostReview_ConflictingCommitIDs(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not be sent when commit IDs conflict")
+	})
+
+	_, err := c.PostReview(context.Background(), "owner", "repo", 5, vcs.ReviewRequest{
+		Body:  "Review",
+		Event: vcs.ReviewEventComment,
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "sha-1", Body: "first"},
+			{Path: "b.go", Position: 2, CommitID: "sha-2", Body: "second"},
+		},
+	})
+	if err == nil {
+		t.Fatal("expected error for conflicting commit IDs")
+	}
+	if !errors.Is(err, ErrConflictingCommitIDs) {
+		t.Errorf("expected ErrConflictingCommitIDs, got: %v", err)
+	}
+}
+
+func TestPostReview_RequestCommitID_TakesPriority(t *testing.T) {
+	var gotPayload struct {
+		CommitID string `json:"commit_id"`
+		Body     string `json:"body"`
+	}
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        42,
+			"body":      "LGTM",
+			"state":     "APPROVED",
+			"commit_id": "req-level-sha",
+			"user":      map[string]any{"login": "bot"},
+		})
+	})
+
+	review, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "LGTM",
+		Event:    vcs.ReviewEventApprove,
+		CommitID: "req-level-sha",
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "req-level-sha", Body: "looks good"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "req-level-sha" {
+		t.Errorf("sent commit_id = %q, want %q", gotPayload.CommitID, "req-level-sha")
+	}
+	if review.CommitID != "req-level-sha" {
+		t.Errorf("review.CommitID = %q, want %q", review.CommitID, "req-level-sha")
+	}
+}
+
+func TestPostReview_RequestCommitID_ConflictsWithComment(t *testing.T) {
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		t.Fatal("request should not be sent when commit IDs conflict")
+	})
+
+	// req.CommitID is set, and a comment has a different CommitID → conflict
+	_, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:     "Review",
+		Event:    vcs.ReviewEventComment,
+		CommitID: "req-sha",
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "different-sha", Body: "nit"},
+		},
+	})
+	if err == nil {
+		t.Fatal("expected error for conflicting commit IDs")
+	}
+	if !errors.Is(err, ErrConflictingCommitIDs) {
+		t.Errorf("expected ErrConflictingCommitIDs, got: %v", err)
+	}
+}
+
+func TestPostReview_RequestCommitID_FallbackToComment(t *testing.T) {
+	var gotPayload struct {
+		CommitID string `json:"commit_id"`
+	}
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&gotPayload)
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"id":        43,
+			"body":      "ok",
+			"state":     "COMMENTED",
+			"commit_id": "comment-sha",
+			"user":      map[string]any{"login": "bot"},
+		})
+	})
+
+	// req.CommitID is empty, so it falls back to the comment's CommitID
+	_, err := c.PostReview(context.Background(), "owner", "repo", 1, vcs.ReviewRequest{
+		Body:  "ok",
+		Event: vcs.ReviewEventComment,
+		// CommitID intentionally empty
+		Comments: []vcs.ReviewComment{
+			{Path: "a.go", Position: 1, CommitID: "comment-sha", Body: "note"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotPayload.CommitID != "comment-sha" {
+		t.Errorf("sent commit_id = %q, want %q (fallback from comment)", gotPayload.CommitID, "comment-sha")
+	}
+}
+
+// --- ListReviews pagination tests ---
+
+func TestListReviews_MultiPage(t *testing.T) {
+	// Test multi-page pagination: 2 full pages + 1 partial page.
+	// pageSize=3, so pages return [3, 3, 2] reviews = 8 total.
+	const pageSize = 3
+	callCount := 0
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "GET" {
+			t.Fatalf("expected GET, got %s", r.Method)
+		}
+		callCount++
+
+		page := r.URL.Query().Get("page")
+		var reviews []map[string]interface{}
+
+		switch page {
+		case "1":
+			for i := 1; i <= pageSize; i++ {
+				reviews = append(reviews, map[string]interface{}{
+					"id": i, "body": fmt.Sprintf("review %d", i),
+					"state": "APPROVED", "commit_id": "sha1",
+					"user": map[string]string{"login": "user1"},
+				})
+			}
+		case "2":
+			for i := pageSize + 1; i <= pageSize*2; i++ {
+				reviews = append(reviews, map[string]interface{}{
+					"id": i, "body": fmt.Sprintf("review %d", i),
+					"state": "COMMENTED", "commit_id": "sha1",
+					"user": map[string]string{"login": "user2"},
+				})
+			}
+		case "3":
+			// Partial page: only 2 reviews (less than pageSize)
+			for i := pageSize*2 + 1; i <= pageSize*2+2; i++ {
+				reviews = append(reviews, map[string]interface{}{
+					"id": i, "body": fmt.Sprintf("review %d", i),
+					"state": "CHANGES_REQUESTED", "commit_id": "sha1",
+					"user": map[string]string{"login": "user3"},
+				})
+			}
+		default:
+			t.Fatalf("unexpected page: %s", page)
+		}
+
+		json.NewEncoder(w).Encode(reviews)
+	})
+	c.SetReviewPagination(pageSize, 10)
+
+	reviews, err := c.ListReviews(context.Background(), "owner", "repo", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 8 {
+		t.Fatalf("expected 8 reviews, got %d", len(reviews))
+	}
+	if callCount != 3 {
+		t.Errorf("expected 3 API calls, got %d", callCount)
+	}
+
+	// Verify reviews are correctly concatenated in order
+	for i, r := range reviews {
+		expectedID := int64(i + 1)
+		if r.ID != expectedID {
+			t.Errorf("review[%d]: expected ID %d, got %d", i, expectedID, r.ID)
+		}
+	}
+}
+
+func TestListReviews_ExactMultipleOfPageSize(t *testing.T) {
+	// When total reviews is an exact multiple of pageSize, an extra request
+	// returning 0 results terminates the loop. No truncation warning.
+	const pageSize = 2
+	callCount := 0
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		callCount++
+		page := r.URL.Query().Get("page")
+
+		var reviews []map[string]interface{}
+		switch page {
+		case "1":
+			reviews = []map[string]interface{}{
+				{"id": 1, "body": "r1", "state": "APPROVED", "commit_id": "s1", "user": map[string]string{"login": "u1"}},
+				{"id": 2, "body": "r2", "state": "APPROVED", "commit_id": "s1", "user": map[string]string{"login": "u2"}},
+			}
+		case "2":
+			reviews = []map[string]interface{}{
+				{"id": 3, "body": "r3", "state": "APPROVED", "commit_id": "s1", "user": map[string]string{"login": "u3"}},
+				{"id": 4, "body": "r4", "state": "APPROVED", "commit_id": "s1", "user": map[string]string{"login": "u4"}},
+			}
+		case "3":
+			// Empty page — signals end of data
+			reviews = []map[string]interface{}{}
+		default:
+			t.Fatalf("unexpected page: %s", page)
+		}
+
+		json.NewEncoder(w).Encode(reviews)
+	})
+	c.SetReviewPagination(pageSize, 10)
+
+	reviews, err := c.ListReviews(context.Background(), "owner", "repo", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 4 {
+		t.Fatalf("expected 4 reviews, got %d", len(reviews))
+	}
+	// 3 calls: page 1 (full), page 2 (full), page 3 (empty)
+	if callCount != 3 {
+		t.Errorf("expected 3 API calls, got %d", callCount)
+	}
+}
+
+func TestListReviews_MaxPagesCutoff(t *testing.T) {
+	// When maxPages is hit and the last page is full, results are truncated
+	// and a warning would fire (we verify the reviews are still returned).
+	const pageSize = 2
+	const maxPages = 2
+	callCount := 0
+
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		callCount++
+		page := r.URL.Query().Get("page")
+
+		// Always return a full page (simulating more data exists)
+		var reviews []map[string]interface{}
+		var baseID int
+		switch page {
+		case "1":
+			baseID = 0
+		case "2":
+			baseID = pageSize
+		default:
+			t.Fatalf("unexpected page %s (should not exceed maxPages)", page)
+		}
+		for i := 1; i <= pageSize; i++ {
+			reviews = append(reviews, map[string]interface{}{
+				"id": baseID + i, "body": fmt.Sprintf("r%d", baseID+i),
+				"state": "APPROVED", "commit_id": "sha1",
+				"user": map[string]string{"login": "user"},
+			})
+		}
+
+		json.NewEncoder(w).Encode(reviews)
+	})
+	c.SetReviewPagination(pageSize, maxPages)
+
+	reviews, err := c.ListReviews(context.Background(), "owner", "repo", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Should return all reviews fetched within the cap
+	expectedCount := pageSize * maxPages
+	if len(reviews) != expectedCount {
+		t.Fatalf("expected %d reviews, got %d", expectedCount, len(reviews))
+	}
+	if callCount != maxPages {
+		t.Errorf("expected %d API calls, got %d", maxPages, callCount)
+	}
+	// Verify concatenation order
+	for i, r := range reviews {
+		if r.ID != int64(i+1) {
+			t.Errorf("review[%d]: expected ID %d, got %d", i, i+1, r.ID)
+		}
+	}
+}
+
+func TestListReviews_EmptyFirstPage(t *testing.T) {
+	// PR with no reviews: first page returns empty array.
+	callCount := 0
+	c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		callCount++
+		json.NewEncoder(w).Encode([]map[string]interface{}{})
+	})
+	c.SetReviewPagination(10, 5)
+
+	reviews, err := c.ListReviews(context.Background(), "owner", "repo", 1)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(reviews) != 0 {
+		t.Fatalf("expected 0 reviews, got %d", len(reviews))
+	}
+	if callCount != 1 {
+		t.Errorf("expected 1 API call, got %d", callCount)
+	}
+}

github/reviews.go

@@ -3,6 +3,7 @@ package github
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
@@ -19,35 +20,47 @@ const (
 	maxReviewPages = 100
 )
 
-// reviewResponse is the GitHub API response for a pull request review.
-type reviewResponse struct {
-	ID   int64  `json:"id"`
-	Body string `json:"body"`
-	User struct {
-		Login string `json:"login"`
-	} `json:"user"`
-	State    string `json:"state"`
-	CommitID string `json:"commit_id"`
+// ErrCannotDeleteSubmittedReview is returned when DeleteReview is called on
+// a review that has already been submitted (APPROVED, REQUEST_CHANGES, COMMENT).
+// GitHub only allows deletion of PENDING reviews. Callers that need to replace
+// a submitted review should use DismissReview instead.
+var ErrCannotDeleteSubmittedReview = errors.New("cannot delete submitted review: use DismissReview instead")
+
+// ErrConflictingCommitIDs is returned when PostReview receives comments with
+// differing non-empty CommitIDs. The GitHub API accepts only a single commit_id
+// per review submission; callers must ensure all comments target the same commit.
+var ErrConflictingCommitIDs = errors.New("comments contain conflicting commit IDs: all must target the same commit")
+
+// postReviewRequest is the GitHub API request body for creating a review.
+type postReviewRequest struct {
+	CommitID string               `json:"commit_id,omitempty"`
+	Body     string               `json:"body"`
+	Event    string               `json:"event"`
+	Comments []reviewCommentEntry `json:"comments,omitempty"`
 }
 
-// reviewCreateRequest is the GitHub API request body for creating a pull request review.
-type reviewCreateRequest struct {
-	Body     string                `json:"body"`
-	Event    string                `json:"event"`
-	Comments []reviewCommentCreate `json:"comments,omitempty"`
-	CommitID string                `json:"commit_id,omitempty"`
-}
-
-// reviewCommentCreate is a single inline comment in a review creation request.
-type reviewCommentCreate struct {
+// reviewCommentEntry is a single inline comment in a review creation request.
+type reviewCommentEntry struct {
 	Path     string `json:"path"`
 	Position int    `json:"position"`
 	Body     string `json:"body"`
 }
 
+// reviewResponse is the GitHub API response for a review.
+type reviewResponse struct {
+	ID       int64  `json:"id"`
+	Body     string `json:"body"`
+	State    string `json:"state"`
+	CommitID string `json:"commit_id"`
+	User     struct {
+		Login string `json:"login"`
+	} `json:"user"`
+}
+
 // dismissReviewRequest is the GitHub API request body for dismissing a review.
 type dismissReviewRequest struct {
 	Message string `json:"message"`
+	Event   string `json:"event"`
 }
 
 // userResponse is the GitHub API response for the authenticated user.
@@ -55,40 +68,67 @@ type userResponse struct {
 	Login string `json:"login"`
 }
 
-// translateReviewEvent converts a vcs.ReviewEvent to the GitHub API event string.
-func translateReviewEvent(event vcs.ReviewEvent) string {
-	switch event {
-	case vcs.ReviewEventApprove:
-		return "APPROVE"
-	case vcs.ReviewEventRequestChanges:
+// translateGitHubReviewState translates a GitHub API review state to the
+// canonical vcs.Review.State value.
+func translateGitHubReviewState(state string) string {
+	switch state {
+	case "CHANGES_REQUESTED":
 		return "REQUEST_CHANGES"
-	default:
+	case "COMMENTED":
 		return "COMMENT"
+	default:
+		// States like APPROVED, DISMISSED, and PENDING pass through unchanged
+		// as they already match the canonical vcs representation. PENDING appears
+		// on draft reviews that have not yet been submitted via the GitHub UI or API.
+		return state
 	}
 }
 
-// PostReview creates a new review on a pull request.
+// PostReview submits a review on a pull request.
+//
+// The vcs.ReviewEvent constants (ReviewEventApprove, ReviewEventRequestChanges,
+// ReviewEventComment) have string values that match GitHub's wire-format event
+// strings (APPROVE, REQUEST_CHANGES, COMMENT), so Event is cast directly to
+// string without translation.
+//
+// ReviewComment.Position maps directly to the GitHub API position field.
+// When req.Comments is empty, the payload omits the comments field entirely
+// (via the omitempty tag on postReviewRequest.Comments).
+//
+// The GitHub API accepts a single commit_id per review submission. PostReview
+// uses req.CommitID as the primary commit anchor. If req.CommitID is empty,
+// it falls back to extracting from the first comment with a non-empty CommitID.
+// If any subsequent comment specifies a different CommitID, PostReview returns
+// ErrConflictingCommitIDs. Comments with an empty CommitID are allowed and
+// inherit the review-level value.
 func (c *Client) PostReview(ctx context.Context, owner, repo string, number int, req vcs.ReviewRequest) (*vcs.Review, error) {
 	reqURL := fmt.Sprintf("%s/repos/%s/%s/pulls/%d/reviews",
 		c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number)
 
-	payload := reviewCreateRequest{
-		Body:  req.Body,
-		Event: translateReviewEvent(req.Event),
+	payload := postReviewRequest{
+		Body:     req.Body,
+		Event:    string(req.Event),
+		CommitID: req.CommitID,
 	}
 
+	// Build the payload in one pass. The GitHub API accepts a single commit_id
+	// per review. req.CommitID is the primary source; if empty, we extract from
+	// the first comment that supplies one. Reject if any comment disagrees with
+	// the resolved commit_id.
 	for _, comment := range req.Comments {
-		rc := reviewCommentCreate{
+		if comment.CommitID != "" {
+			if payload.CommitID == "" { // only reachable when req.CommitID is empty
+				payload.CommitID = comment.CommitID
+			} else if payload.CommitID != comment.CommitID {
+				return nil, ErrConflictingCommitIDs
+			}
+			// else: matching SHA is a no-op by design
+		}
+		payload.Comments = append(payload.Comments, reviewCommentEntry{
 			Path:     comment.Path,
 			Position: comment.Position,
 			Body:     comment.Body,
-		}
-		payload.Comments = append(payload.Comments, rc)
-		// Use CommitID from the first comment that has one.
-		// All comments in a single review are expected to reference the same commit.
-		if payload.CommitID == "" && comment.CommitID != "" {
-			payload.CommitID = comment.CommitID
-		}
+		})
 	}
 
 	body, err := c.doJSONRequest(ctx, http.MethodPost, reqURL, payload)
@@ -105,75 +145,108 @@ func (c *Client) PostReview(ctx context.Context, owner, repo string, number int,
 		ID:       resp.ID,
 		Body:     resp.Body,
 		User:     vcs.UserInfo{Login: resp.User.Login},
-		State:    resp.State,
+		State:    translateGitHubReviewState(resp.State),
 		CommitID: resp.CommitID,
 	}, nil
 }
 
-// ListReviews lists all reviews on a pull request.
+// ListReviews retrieves all reviews for a pull request with pagination.
+// GitHub review states are translated to canonical vcs values.
 func (c *Client) ListReviews(ctx context.Context, owner, repo string, number int) ([]vcs.Review, error) {
-	var allReviews []vcs.Review
+	perPage := reviewsPerPage
+	if c.reviewPageSize > 0 {
+		perPage = c.reviewPageSize
+	}
+	maxPages := maxReviewPages
+	if c.reviewMaxPages > 0 {
+		maxPages = c.reviewMaxPages
+	}
 
-	for page := 1; page <= maxReviewPages; page++ {
+	var allReviews []vcs.Review
+	truncated := false
+
+	for page := 1; page <= maxPages; page++ {
 		reqURL := fmt.Sprintf("%s/repos/%s/%s/pulls/%d/reviews?per_page=%d&page=%d",
-			c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number, reviewsPerPage, page)
+			c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number, perPage, page)
+
 		body, err := c.doGet(ctx, reqURL)
 		if err != nil {
 			return nil, fmt.Errorf("list reviews page %d: %w", page, err)
 		}
-		var reviews []reviewResponse
-		if err := json.Unmarshal(body, &reviews); err != nil {
-			return nil, fmt.Errorf("parse reviews JSON: %w", err)
+
+		var responses []reviewResponse
+		if err := json.Unmarshal(body, &responses); err != nil {
+			return nil, fmt.Errorf("parse reviews response: %w", err)
 		}
-		if len(reviews) == 0 {
+
+		if len(responses) == 0 {
 			break
 		}
-		for _, r := range reviews {
+
+		for _, r := range responses {
 			allReviews = append(allReviews, vcs.Review{
 				ID:       r.ID,
 				Body:     r.Body,
 				User:     vcs.UserInfo{Login: r.User.Login},
-				State:    r.State,
+				State:    translateGitHubReviewState(r.State),
 				CommitID: r.CommitID,
 			})
 		}
-		if len(reviews) < reviewsPerPage {
+
+		if len(responses) < perPage {
 			break
 		}
-		// NOTE: This warning only fires when the final page was full (the short-page
-		// break above did not trigger), meaning additional reviews likely exist beyond
-		// our page limit. The loop naturally exits after this iteration since page
-		// increments past maxReviewPages.
-		if page == maxReviewPages {
-			slog.Warn("ListReviews hit page limit; results may be truncated",
-				"owner", owner, "repo", repo, "pr", number,
-				"maxPages", maxReviewPages, "reviewsFetched", len(allReviews))
+
+		// Truncation detection: this runs on the final allowed iteration
+		// (page == maxPages) only when the page was full (the len < perPage
+		// early-break above didn't fire). A full final page means additional
+		// reviews likely exist beyond our pagination limit.
+		if page == maxPages {
+			truncated = true
 		}
 	}
 
+	if truncated {
+		slog.Warn("ListReviews hit page limit; results may be truncated",
+			"owner", owner, "repo", repo, "pr", number,
+			"maxPages", maxPages, "reviewsFetched", len(allReviews))
+	}
+
 	return allReviews, nil
 }
 
-// DeleteReview permanently deletes a review from a pull request.
-// Use DismissReview instead when the review should remain visible but marked as dismissed
-// (e.g., superseding an outdated review while preserving history).
+// DeleteReview deletes a pull request review.
+// Only PENDING reviews can be deleted; attempting to delete a submitted review
+// (APPROVED, CHANGES_REQUESTED, or COMMENTED per GitHub API naming) returns
+// ErrCannotDeleteSubmittedReview.
 func (c *Client) DeleteReview(ctx context.Context, owner, repo string, number int, reviewID int64) error {
 	reqURL := fmt.Sprintf("%s/repos/%s/%s/pulls/%d/reviews/%d",
 		c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number, reviewID)
-	_, err := c.doRequest(ctx, http.MethodDelete, reqURL, "")
+
+	// nil body: the GitHub DELETE endpoint for reviews requires no request body.
+	_, err := c.doRequestWithBody(ctx, http.MethodDelete, reqURL, nil)
 	if err != nil {
+		var apiErr *APIError
+		if errors.As(err, &apiErr) && apiErr.StatusCode == 422 {
+			return fmt.Errorf("delete review: %w", ErrCannotDeleteSubmittedReview)
+		}
 		return fmt.Errorf("delete review: %w", err)
 	}
 	return nil
 }
 
-// DismissReview dismisses a review on a pull request with a message.
+// DismissReview dismisses a submitted review on a pull request.
+// This is the correct way to "remove" a submitted review (APPROVED, REQUEST_CHANGES).
+// GitHub does not allow deleting submitted reviews — they must be dismissed.
 func (c *Client) DismissReview(ctx context.Context, owner, repo string, number int, reviewID int64, message string) error {
 	reqURL := fmt.Sprintf("%s/repos/%s/%s/pulls/%d/reviews/%d/dismissals",
 		c.baseURL, url.PathEscape(owner), url.PathEscape(repo), number, reviewID)
 
 	payload := dismissReviewRequest{
 		Message: message,
+		// Event is required by the GitHub API for dismissal requests, even though
+		// "DISMISS" is the only valid value for this endpoint.
+		Event: "DISMISS",
 	}
 
 	_, err := c.doJSONRequest(ctx, http.MethodPut, reqURL, payload)
@@ -183,6 +256,19 @@ func (c *Client) DismissReview(ctx context.Context, owner, repo string, number i
 	return nil
 }
 
+// SupersedeReviews marks prior reviews as superseded by dismissing them.
+// This implements vcs.ReviewSuperseder for the GitHub adapter.
+// The baseURL and sentinel parameters are unused for GitHub (dismissal is the mechanism).
+func (c *Client) SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []vcs.Review, newReviewID int64, _, _ string) error {
+	var errs []error
+	for _, old := range oldReviews {
+		if err := c.DismissReview(ctx, owner, repo, prNumber, old.ID, "Superseded by new review"); err != nil {
+			errs = append(errs, fmt.Errorf("dismiss review %d: %w", old.ID, err))
+		}
+	}
+	return errors.Join(errs...)
+}
+
 // GetAuthenticatedUser returns the login name of the authenticated user.
 func (c *Client) GetAuthenticatedUser(ctx context.Context) (string, error) {
 	reqURL := fmt.Sprintf("%s/user", c.baseURL)

review/persona_test.go

@@ -355,7 +355,7 @@ func TestCapitalizeFirst(t *testing.T) {
 		{"HELLO", "HELLO"},
 		{"a", "A"},
 		{"", ""},
-		{"日本語", "日本語"}, // Non-ASCII: Japanese doesn't have case
+		{"日本語", "日本語"},     // Non-ASCII: Japanese doesn't have case
 		{"über", "Über"},   // German umlaut
 		{"élève", "Élève"}, // French accent
 	}

vcs/interfaces.go

@@ -41,3 +41,20 @@ type Client interface {
 	Reviewer
 	Identity
 }
+
+// ReviewerSelfRequester is an optional interface implemented by adapters that support
+// requesting the authenticated user as a reviewer on a pull request. This is used for
+// Gitea-specific behavior (ensuring the bot appears in required-reviewer checks).
+// Consumers should use interface assertion: if sr, ok := client.(ReviewerSelfRequester); ok { ... }
+type ReviewerSelfRequester interface {
+	RequestReviewerSelf(ctx context.Context, owner, repo string, number int, user string) error
+}
+
+// ReviewSuperseder is an optional interface implemented by adapters that support
+// marking old reviews as superseded. For Gitea this means editing the review body
+// with a link to the new review and resolving inline comments. For GitHub this
+// means dismissing old reviews.
+// Consumers should use interface assertion: if rs, ok := client.(ReviewSuperseder); ok { ... }
+type ReviewSuperseder interface {
+	SupersedeReviews(ctx context.Context, owner, repo string, prNumber int, oldReviews []Review, newReviewID int64, baseURL, sentinel string) error
+}

vcs/provider.go

@@ -0,0 +1,26 @@
+package vcs
+
+// VCSProvider identifies a VCS platform. Using a typed string instead of bare
+// strings makes provider values compiler-checkable and prevents typos from
+// silently passing validation.
+type VCSProvider string
+
+const (
+	ProviderGitea  VCSProvider = "gitea"
+	ProviderGitHub VCSProvider = "github"
+)
+
+// Valid reports whether p is a known VCS provider.
+func (p VCSProvider) Valid() bool {
+	switch p {
+	case ProviderGitea, ProviderGitHub:
+		return true
+	default:
+		return false
+	}
+}
+
+// String returns the string representation of the provider.
+func (p VCSProvider) String() string {
+	return string(p)
+}

vcs/types.go

@@ -93,6 +93,11 @@ type ReviewRequest struct {
 	// Body is the top-level review comment.
 	Body string `json:"body"`
 	// Event is the review action (approve, request changes, or comment).
-	Event    ReviewEvent     `json:"event"`
+	Event ReviewEvent `json:"event"`
+	// CommitID anchors the review to a specific commit SHA.
+	// If empty, the platform defaults to the current PR head.
+	// Adapters use this as the primary commit anchor for the review submission.
+	CommitID string `json:"commit_id,omitempty"`
+
 	Comments []ReviewComment `json:"comments,omitempty"`
 }