From d4d369798c3c6c8afefb20df2c3ba677779c9b1b Mon Sep 17 00:00:00 2001 From: claw Date: Wed, 13 May 2026 04:14:30 -0700 Subject: [PATCH] docs(cmd,github): clarify type assertion and parameter usage in review superseding Address sonnet-review feedback on PR #106: - Document that the type assertion in supersedeOldReviews is guaranteed to succeed given the caller's provider switch, with the !ok branch guarding against future refactors (comment 18889). - Clarify that vcsURL is only used in the Gitea path for constructing review permalink URLs (comment 18890). - Add note explaining why the page-limit warning in ListReviews only fires when the final page is full, confirming the logic is intentional (comment 18891). --- cmd/review-bot/main.go | 13 +++++++++++-- github/reviews.go | 4 ++++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/cmd/review-bot/main.go b/cmd/review-bot/main.go index 940ee7e..b5c48d6 100644 --- a/cmd/review-bot/main.go +++ b/cmd/review-bot/main.go @@ -531,8 +531,12 @@ func verdictToEvent(verdict string) vcs.ReviewEvent { } // supersedeOldReviews marks old reviews as superseded. -// For GitHub: dismisses old reviews. -// For Gitea: edits the review body and resolves inline comments. +// 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": @@ -553,6 +557,11 @@ func supersedeOldReviews(ctx context.Context, client vcs.Client, provider, vcsUR 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) diff --git a/github/reviews.go b/github/reviews.go index 158ef0d..3ac0742 100644 --- a/github/reviews.go +++ b/github/reviews.go @@ -140,6 +140,10 @@ func (c *Client) ListReviews(ctx context.Context, owner, repo string, number int if len(reviews) < reviewsPerPage { 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,