review

Documentation

Overview

Package review runs a directory of prompts as independent reviews, each on its own sidecar.

Index

• Constants
• Variables
• func ClientExec(ctx context.Context, entry *sidecar.PoolEntry, script string, ...) (int, error)
• func PoolSize(parallelism, prompts int) int
• func WaitReady(ctx context.Context, waitSynced func(context.Context) error) error
• type Credential
• type Execer
• type Options
• type ProgressEvent
• type Prompt
  • func LoadPrompts(dir string) ([]Prompt, error)
• type PromptState
• type Result
  • func RunPass(ctx context.Context, acquire func(context.Context) (*sidecar.PoolEntry, error), ...) ([]Result, error)

Constants

const DefaultDir = ".chunk/reviews"

DefaultDir is where prompts are read from, relative to the project root, when no directory is given.

const DefaultTimeout = 15 * time.Minute

DefaultTimeout bounds one review. Claude explores the repo before answering, so this is minutes rather than the seconds a single API call would take.

const PoolName = "review"

PoolName is the sidecar pool name for reviews. It keys the persisted pool state in .chunk/review-pool.json, so a later run — or a later pass in the same run — picks up the same warm sidecars instead of booting new ones.

Variables

var ErrClaudeMissing = errors.New("claude is not installed on the sidecar")

ErrClaudeMissing is returned when a sidecar has no claude binary.

var ErrCredentialRejected = errors.New("anthropic rejected the credential")

ErrCredentialRejected is returned when Anthropic rejects the credential.

var ErrNoPrompts = errors.New("no prompts found")

ErrNoPrompts is returned when a prompts directory holds nothing to review.

Functions

func ClientExec

func ClientExec(ctx context.Context, entry *sidecar.PoolEntry, script string, env map[string]string, onOutput circleci.OutputFn) (int, error)

ClientExec runs scripts through the pool entry's CircleCI client.

func PoolSize

func PoolSize(parallelism, prompts int) int

PoolSize picks how many sidecars to boot: one per prompt, capped at the requested parallelism. Booting more sidecars than prompts only bills idle machines, since each review occupies exactly one sidecar.

func WaitReady

func WaitReady(ctx context.Context, waitSynced func(context.Context) error) error

WaitReady blocks until the pool's background clone creation and sync have finished, via waitSynced (the pool's WaitSynced), and reports any member that failed.

sidecar.NewPool returns as soon as its members exist, while reused members may still be syncing in the background. Waiting here makes a failed sync surface before any review starts, rather than as one review failing partway through a pass. It holds no members while waiting: the pool reports a failed member through Acquire only once nothing is checked out.

Types

type Credential

type Credential struct {
	EnvVar string
	Value  string
}

Credential is the Claude credential a review authenticates with. EnvVar is the variable claude reads it from, so only one of the two is ever sent and a stale one cannot shadow the other.

type Execer

type Execer func(ctx context.Context, entry *sidecar.PoolEntry, script string, env map[string]string, onOutput circleci.OutputFn) (exitCode int, err error)

Execer runs a shell script on a sidecar and streams its output.

type Options

type Options struct {
	Credential Credential
	// BaseURL is forwarded to claude when it is not Anthropic's own, so a
	// credential issued by a gateway is sent to that gateway.
	BaseURL    string
	Model      string        // optional; claude's default when empty
	Timeout    time.Duration // per review; DefaultTimeout when zero
	StatusFn   iostream.StatusFunc
	ProgressFn func(ProgressEvent) // optional; called on each prompt state change
}

Options configures one review pass.

type ProgressEvent

type ProgressEvent struct {
	Prompt    string
	SidecarID string
	State     PromptState
	Duration  time.Duration
	Error     string
}

ProgressEvent reports a state change for one prompt.

type Prompt

type Prompt struct {
	Name string
	Body string
}

Prompt is one review to run. Name is the file name without its extension and identifies the review in output across passes.

func LoadPrompts

func LoadPrompts(dir string) ([]Prompt, error)

LoadPrompts reads every prompt file directly inside dir, sorted by name so runs are reproducible. Subdirectories are not descended into, and files that are empty after trimming whitespace are skipped rather than run as blank reviews.

type PromptState

type PromptState int

PromptState is the lifecycle state of one review in a pass.

const (
	StateQueued  PromptState = iota // waiting for a sidecar
	StateRunning                    // executing on a sidecar
	StateDone                       // completed successfully
	StateFailed                     // completed with error
)

Prompt lifecycle states.

type Result

type Result struct {
	Prompt    string
	SidecarID string
	Output    string
	Error     string
	Duration  time.Duration
}

Result is the outcome of one prompt in one pass. Output and Error are not exclusive: a review that fails partway keeps what it produced.

func RunPass

func RunPass(ctx context.Context, acquire func(context.Context) (*sidecar.PoolEntry, error), release func(*sidecar.PoolEntry), exec Execer, prompts []Prompt, opts Options) ([]Result, error)

RunPass runs every prompt once, each on a sidecar checked out with acquire and returned with release (the pool's Acquire and Release), and returns results in prompt order for every prompt that started. Per-prompt failures are recorded in Result.Error; the returned error is for failures that stop the pass itself.

A missing claude binary or a rejected credential stops the pass rather than being recorded per prompt: every sidecar in a pool shares one image and one credential, so either would fail every review the same way.