status

Documentation

Overview

Package status handles status spec loading, validation, and resolution.

Index

• Variables
• func RepoSlug(url string) string
• func Save(path string, s *Spec) error
• func Validate(s *Spec) error
• type CheckRunner
• type Entry
  • func (e Entry) ColorCode() string
• type RepoInfo
• type RepoResult
• type Resolver
  • func (r *Resolver) ResolveRepo(ctx context.Context, spec *Spec, repo RepoInfo, wsID, wsName string) string
  • func (r *Resolver) ResolveWorkspace(ctx context.Context, spec *Spec, repos []RepoInfo, wsID, wsName string) *WorkspaceResult
• type ShellRunner
  • func (r *ShellRunner) RunCheck(ctx context.Context, command string, env []string) bool
• type Spec
  • func DefaultSpec() *Spec
  • func Load(path string) (*Spec, error)
  • func LoadWithFallback(workspacePath, globalPath string) (*Spec, error)
  • func (s *Spec) ColorMap() map[string]string
  • func (s *Spec) DisplayOrder() map[string]int
• type SpecBody
• type WorkspaceResult

Variables

var (
	ErrInvalidAPIVersion = errors.New("apiVersion must be flow/v1")
	ErrInvalidKind       = errors.New("kind must be Status")
	ErrNoStatuses        = errors.New("statuses must not be empty")
	ErrNoDefault         = errors.New("exactly one status must have default: true")
	ErrMultipleDefaults  = errors.New("only one status may have default: true")
	ErrDuplicateName     = errors.New("status names must be unique")
	ErrMissingName       = errors.New("status name is required")
	ErrMissingCheck      = errors.New("non-default status must have a check command")
	ErrSpecNotFound      = errors.New("no status spec found")
)

Validation errors for status spec files.

Functions

func RepoSlug

func RepoSlug(url string) string

RepoSlug converts a repo URL to owner/repo format for gh CLI. Handles SSH (git@github.com:org/repo.git) and HTTPS (github.com/org/repo) URLs.

func Save

func Save(path string, s *Spec) error

Save writes a Spec to disk as YAML.

func Validate

func Validate(s *Spec) error

Validate checks that a Spec has all required fields and is well-formed.

Types

type CheckRunner

type CheckRunner interface {
	RunCheck(ctx context.Context, command string, env []string) bool
}

CheckRunner executes a status check command and returns whether it matched.

type Entry

type Entry struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	Color       string `yaml:"color,omitempty"`
	Check       string `yaml:"check,omitempty"`
	Default     bool   `yaml:"default,omitempty"`
}

Entry defines a single status in the spec.

func (Entry) ColorCode

func (e Entry) ColorCode() string

ColorCode returns the ANSI color code for an Entry's color. Supports named colors (green, yellow, etc.) and raw ANSI codes. Returns empty string if no color is set.

type RepoInfo

type RepoInfo struct {
	URL    string
	Branch string
	Path   string
}

RepoInfo provides context for running status checks against a repo.

type RepoResult

type RepoResult struct {
	URL      string
	Branch   string
	Status   string
	Duration time.Duration
}

RepoResult holds the resolved status for a single repo.

type Resolver

type Resolver struct {
	Runner CheckRunner
}

Resolver resolves workspace statuses using a CheckRunner.

func (*Resolver) ResolveRepo

func (r *Resolver) ResolveRepo(ctx context.Context, spec *Spec, repo RepoInfo, wsID, wsName string) string

ResolveRepo determines the status of a single repo by evaluating checks in order. Returns the name of the first matching status or the default.

func (*Resolver) ResolveWorkspace

func (r *Resolver) ResolveWorkspace(ctx context.Context, spec *Spec, repos []RepoInfo, wsID, wsName string) *WorkspaceResult

ResolveWorkspace resolves the status for each repo concurrently and returns the aggregated workspace result. The workspace status is the least-advanced status (highest index in spec order) across all repos.

type ShellRunner

type ShellRunner struct{}

ShellRunner executes check commands via sh -c.

func (*ShellRunner) RunCheck

func (r *ShellRunner) RunCheck(ctx context.Context, command string, env []string) bool

RunCheck executes the command in a shell. Returns true if exit code is 0.

type Spec

type Spec struct {
	APIVersion string   `yaml:"apiVersion"`
	Kind       string   `yaml:"kind"`
	Spec       SpecBody `yaml:"spec,omitempty"`
}

Spec represents a status spec file.

func DefaultSpec

func DefaultSpec() *Spec

DefaultSpec returns a starter status spec with a basic PR workflow.

Status checks are evaluated top-to-bottom per repo; first match wins. The workspace-level status is the least-advanced (highest index) across repos.

Default statuses:

closed       — a merged PR exists and no open PRs remain (requires gh)
stale        — no commits on the branch in the last 14 days (local git only)
in-review    — a non-draft open PR exists on the branch (requires gh)
in-progress  — uncommitted changes, unpushed commits, or a draft PR
open         — default; none of the above matched

func Load

func Load(path string) (*Spec, error)

Load reads and parses a status spec file from disk.

func LoadWithFallback

func LoadWithFallback(workspacePath, globalPath string) (*Spec, error)

LoadWithFallback loads a workspace-level spec if it exists, otherwise falls back to the global spec. Returns ErrSpecNotFound if neither exists.

func (*Spec) ColorMap

func (s *Spec) ColorMap() map[string]string

ColorMap returns a map of status name to ANSI color code.

func (*Spec) DisplayOrder

func (s *Spec) DisplayOrder() map[string]int

DisplayOrder returns a map of status name to display sort index. The default (least-advanced) status gets index 0, most-advanced gets the highest.

type SpecBody

type SpecBody struct {
	Statuses []Entry `yaml:"statuses,omitempty"`
}

SpecBody holds the statuses list nested under spec.

type WorkspaceResult

type WorkspaceResult struct {
	WorkspaceID   string
	WorkspaceName string
	Status        string
	Duration      time.Duration
	Repos         []RepoResult
}

WorkspaceResult holds the resolved status for a workspace.