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/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 {
-		SHA string `json:"sha"`
-		Ref string `json:"ref"`
-	} `json:"head"`
+	Title string  `json:"title"`
+	Body  string  `json:"body"`
+	Head  HeadRef `json:"head"`
 }
 
 // ChangedFile represents a file modified in a PR.
@@ -37,20 +48,20 @@ type ContentEntry struct {
 
 // Review represents a pull request review.
 type Review struct {
-	ID   int64  `json:"id"`
-	Body string `json:"body"`
-	User struct {
-		Login string `json:"login"`
-	} `json:"user"`
-	State    string `json:"state"`
-	Stale    bool   `json:"stale"`
-	CommitID string `json:"commit_id"`
+	ID       int64    `json:"id"`
+	Body     string   `json:"body"`
+	User     UserInfo `json:"user"`
+	State    string   `json:"state"`
+	Stale    bool     `json:"stale"`
+	CommitID string   `json:"commit_id"`
 }
 
 // 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).