fix(vcs): address PR #83 review findings (round 2)

- Extract named HeadRef and UserInfo structs from anonymous structs
  in PullRequest and Review (comments 16615, 16616)
- Change ReviewEventApprove value from "APPROVED" to "APPROVE" to
  represent the action, not the state; document adapter translation
  responsibility (comment 16621)
- Add doc comment on ReviewComment.CommitID noting optionality (16531)
- Move compile-time assertion from check.go (//go:build ignore) to
  check_test.go with a "phase2" build tag — removes gitea adapter
  import from the vcs package (comment 16622)
- check.go misleading comment was already fixed in prior commit (16532, 16539)
- Sha→SHA, typed ReviewEvent, duplicate package doc already resolved (16537, 16538, 16530)

vcs/check_test.go

@@ -1,10 +1,14 @@
-//go:build ignore
+//go:build phase2
 
-// This file is excluded from normal builds.
+package vcs_test
-// Remove the //go:build ignore tag and run `go build ./vcs/` to see the documented gaps between
+
-// gitea.Client and vcs.Client that Phase 2 (Gitea adapter) must bridge.
+import (
-//
+	"gitea.weiker.me/rodin/review-bot/gitea"
-// Known gaps (as of Phase 1):
+	"gitea.weiker.me/rodin/review-bot/vcs"
+)
+
+// Compile-time assertion: documents the gap between gitea.Client and vcs.Client.
+// Guarded by the "phase2" build tag — enable once the Gitea adapter bridges these gaps:
 //
 //  1. PostReview signature mismatch:
 //     gitea.Client:  PostReview(ctx, owner, repo, number, event, body string, comments []gitea.ReviewComment)
@@ -20,11 +24,4 @@
 //     vcs.ReviewComment uses Position int (GitHub diff-position convention)
 //
 // The Gitea adapter (Phase 2) will wrap gitea.Client to bridge these gaps.
-
+var _ vcs.Client = (*gitea.Client)(nil)
-package vcs
-
-import "gitea.weiker.me/rodin/review-bot/gitea"
-
-// This compile-time assertion intentionally fails.
-// It documents what the Gitea adapter must implement to satisfy vcs.Client.
-var _ Client = (*gitea.Client)(nil)

vcs/types.go

@@ -1,25 +1,36 @@
 package vcs
 
 // ReviewEvent is the event type for a pull request review action.
+// Adapters must translate these action constants to/from platform-native values.
+// For example, Gitea uses "APPROVED" as both action and state, while GitHub
+// uses "APPROVE" for the action and returns "approved" as the state.
 type ReviewEvent string
 
 const (
 	// ReviewEventApprove approves the pull request.
-	ReviewEventApprove ReviewEvent = "APPROVED"
+	ReviewEventApprove ReviewEvent = "APPROVE"
 	// ReviewEventRequestChanges requests changes to the pull request.
 	ReviewEventRequestChanges ReviewEvent = "REQUEST_CHANGES"
 	// ReviewEventComment posts a review comment without approval or rejection.
 	ReviewEventComment ReviewEvent = "COMMENT"
 )
 
+// HeadRef identifies the source branch and latest commit of a pull request.
+type HeadRef struct {
+	SHA string `json:"sha"`
+	Ref string `json:"ref"`
+}
+
+// UserInfo identifies a user by login name.
+type UserInfo struct {
+	Login string `json:"login"`
+}
+
 // PullRequest holds relevant PR metadata.
 type PullRequest struct {
 	Title string  `json:"title"`
 	Body  string  `json:"body"`
-	Head  struct {
+	Head  HeadRef `json:"head"`
-		SHA string `json:"sha"`
-		Ref string `json:"ref"`
-	} `json:"head"`
 }
 
 // ChangedFile represents a file modified in a PR.
@@ -39,9 +50,7 @@ type ContentEntry struct {
 type Review struct {
 	ID       int64    `json:"id"`
 	Body     string   `json:"body"`
-	User struct {
+	User     UserInfo `json:"user"`
-		Login string `json:"login"`
-	} `json:"user"`
 	State    string   `json:"state"`
 	Stale    bool     `json:"stale"`
 	CommitID string   `json:"commit_id"`
@@ -50,7 +59,9 @@ type Review struct {
 // ReviewComment represents an inline comment in a review.
 // All adapters use GitHub diff-position convention:
 //   - Position is a 1-indexed offset from the @@ hunk line in the unified diff.
-//   - CommitID is the commit SHA the comment is anchored to.
+//   - CommitID identifies the commit the comment is anchored to.
+//     It is optional; omit (empty string) for review-level comments that are
+//     not attached to a specific commit.
 //
 // Adapters are responsible for translating to/from platform-native formats
 // (e.g. Gitea uses line numbers; GitHub uses diff positions natively).