turn

Documentation

Overview

Package turn provides a client for the Turn API service that helps track pull request review states and blocking actions.

Index

• Constants
• type Action
• type ActionKind
• type Analysis
• type CheckRequest
• type CheckResponse
• type Checks
• type Client
  • func New(opts ...Option) (*Client, error)
  • func NewClient(baseURL string) (*Client, error)
  • func NewDefaultClient() (*Client, error)
  • func (c *Client) Check(ctx context.Context, prURL, user string, updatedAt time.Time) (*CheckResponse, error)
  • func (c *Client) CurrentUser(ctx context.Context) (string, error)
  • func (c *Client) IncludeEvents()
  • func (c *Client) SetAuthToken(token string)
  • func (c *Client) SetLogger(logger *log.Logger)
  • func (c *Client) SetNoCache(noCache bool)
• type LastActivity
• type Option
  • func WithAuthToken(token string) Option
  • func WithBackend(baseURL string) Option
  • func WithLogger(logger *log.Logger) Option
  • func WithNoCache(noCache bool) Option
• type StateTransition
• type WorkflowState

Constants

const (
	// DefaultBackend is the default backend URL for the Turn API service.
	DefaultBackend = "https://turn.github.codegroove.app"
)

Types

type Action

type Action struct {
	Since    time.Time  `json:"since"`
	Kind     ActionKind `json:"kind"`
	Reason   string     `json:"reason"`
	Critical bool       `json:"critical"`
}

Action represents an expected action from a specific user.

type ActionKind

type ActionKind string

ActionKind represents the type of action required from a user.

const (
	ActionResolveComments  ActionKind = "resolve_comments"
	ActionPublishDraft     ActionKind = "publish_draft"
	ActionRequestReviewers ActionKind = "request_reviewers"
	ActionReview           ActionKind = "review"
	ActionReReview         ActionKind = "re_review"
	ActionReviewDiscussion ActionKind = "review_discussion" // Respond to discussion/questions without code changes
	ActionApprove          ActionKind = "approve"           // Formally approve PR (for LGTM scenarios)
	ActionFixTests         ActionKind = "fix_tests"
	ActionTestsPending     ActionKind = "tests_pending"
	ActionRerunTests       ActionKind = "rerun_tests"
	ActionRespond          ActionKind = "respond"
	ActionFixConflict      ActionKind = "fix_conflict"
	ActionMerge            ActionKind = "merge"
)

Action constants.

type Analysis

type Analysis struct {
	LastActivity       LastActivity      `json:"last_activity"`
	NextAction         map[string]Action `json:"next_action"`
	SecondsInState     map[string]int    `json:"seconds_in_state,omitempty"`
	Size               string            `json:"size"`
	WorkflowState      string            `json:"workflow_state,omitempty"`
	Tags               []string          `json:"tags"`
	StateTransitions   []StateTransition `json:"state_transitions,omitempty"`
	Checks             Checks            `json:"checks"`
	UnresolvedComments int               `json:"unresolved_comments"`
	ReadyToMerge       bool              `json:"ready_to_merge"`
	MergeConflict      bool              `json:"merge_conflict"`
	Approved           bool              `json:"approved"`
}

Analysis represents the computed analysis of a PR.

type CheckRequest

type CheckRequest struct {
	URL           string    `json:"url"`
	UpdatedAt     time.Time `json:"updated_at"` // Last known update time of the PR (required)
	User          string    `json:"user"`
	IncludeEvents bool      `json:"include_events,omitempty"` // Include full event list from prx (defaults to false)
}

CheckRequest represents a request to check if a PR is blocked by a user.

type CheckResponse

type CheckResponse struct {
	Timestamp             time.Time       `json:"timestamp"`
	Commit                string          `json:"commit"`
	Events                []prx.Event     `json:"events,omitempty"`
	PullRequest           prx.PullRequest `json:"pull_request"`
	Analysis              Analysis        `json:"analysis"`
	Tier                  string          `json:"tier,omitempty"`                  // GitHub Marketplace tier (free/pro/flock), only set for GitHub
	PrivateReposEnabled   bool            `json:"private_repos_enabled,omitempty"` // Whether user can access private repos
	TierEnforcementActive bool            `json:"tier_enforcement_active"`         // Whether tier restrictions are enforced
}

CheckResponse represents the response from a PR check.

type Checks

type Checks struct {
	Total   int `json:"total"`   // number of checks associated to this PR
	Failing int `json:"failing"` // number of checks that failed
	Waiting int `json:"waiting"` // waiting for a deployment protection rule to be satisfied.
	Pending int `json:"pending"` // Pending execution (effectively: total - failing - waiting - passing)
	Passing int `json:"passing"` // Number of checks that passed
	Ignored int `json:"ignored"` // Number of failing tests we ignored
}

Checks represents the status of CI checks for a pull request.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client communicates with the Turn API. Client methods are safe for concurrent use after initialization. Set* methods should only be called during setup before concurrent use.

func New

func New(opts ...Option) (*Client, error)

New creates a new Turn API client with options. If no backend is specified via WithBackend, uses DefaultBackend.

func NewClient

func NewClient(baseURL string) (*Client, error)

NewClient creates a new Turn API client with the specified backend URL. The baseURL should be a valid HTTP(S) URL without trailing slash.

func NewDefaultClient

func NewDefaultClient() (*Client, error)

NewDefaultClient creates a new Turn API client using the default backend.

func (*Client) Check

func (c *Client) Check(ctx context.Context, prURL, user string, updatedAt time.Time) (*CheckResponse, error)

Check validates a PR state at the given URL for the specified user. The updatedAt timestamp is used for caching.

func (*Client) CurrentUser

func (c *Client) CurrentUser(ctx context.Context) (string, error)

CurrentUser retrieves the current authenticated GitHub user's login.

func (*Client) IncludeEvents

func (c *Client) IncludeEvents()

IncludeEvents enables including the full event list in check responses.

func (*Client) SetAuthToken

func (c *Client) SetAuthToken(token string)

SetAuthToken sets the GitHub authentication token.

func (*Client) SetLogger

func (c *Client) SetLogger(logger *log.Logger)

SetLogger sets a custom logger for the client.

func (*Client) SetNoCache

func (c *Client) SetNoCache(noCache bool)

SetNoCache enables or disables caching for this client.

type LastActivity

type LastActivity struct {
	Timestamp time.Time `json:"timestamp"`
	Kind      string    `json:"kind"`
	Actor     string    `json:"actor"`
	Message   string    `json:"message"`
}

LastActivity represents the most recent activity on a PR.

type Option

type Option func(*Client)

Option configures a Client.

func WithAuthToken

func WithAuthToken(token string) Option

WithAuthToken sets the GitHub authentication token.

func WithBackend

func WithBackend(baseURL string) Option

WithBackend sets a custom backend URL.

func WithLogger

func WithLogger(logger *log.Logger) Option

WithLogger sets a custom logger.

func WithNoCache

func WithNoCache(noCache bool) Option

WithNoCache enables or disables caching.

type StateTransition

type StateTransition struct {
	FromState     string    `json:"from_state"`
	ToState       string    `json:"to_state"`
	Timestamp     time.Time `json:"timestamp"`
	TriggerEvent  string    `json:"trigger_event"`
	LastEventKind string    `json:"last_event_kind"` // The last event kind seen before this transition
}

StateTransition represents a state change based on an event.

type WorkflowState

type WorkflowState string

WorkflowState represents the current state of a PR in the workflow.

const (
	StateNewlyPublished             WorkflowState = "NEWLY_PUBLISHED"
	StateInDraft                    WorkflowState = "IN_DRAFT"
	StatePublishedWaitingForTests   WorkflowState = "PUBLISHED_WAITING_FOR_TESTS"
	StateTestedWaitingForFixes      WorkflowState = "TESTED_WAITING_FOR_FIXES"
	StateTestedWaitingForAssignment WorkflowState = "TESTED_WAITING_FOR_ASSIGNMENT"
	StateAssignedWaitingForReview   WorkflowState = "ASSIGNED_WAITING_FOR_REVIEW"
	StateReviewedNeedsRefinement    WorkflowState = "REVIEWED_NEEDS_REFINEMENT"
	StateRefinedWaitingForApproval  WorkflowState = "REFINED_WAITING_FOR_APPROVAL"
	StateApprovedWaitingForMerge    WorkflowState = "APPROVED_WAITING_FOR_MERGE"
)

Workflow state constants for tracking time spent in each state.