Help us shape the future of Go! Take the 2026 Go Developer Survey

stackview

package
v0.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package stackview builds read-only view models of the stack — the managed worktree index and per-branch display annotations — for adapters (CLI, TUI, API) to render. It never renders anything itself: adapters convert these values into their own presentation types.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BranchesFromGraph 

func BranchesFromGraph(graph *engine.StackGraph, names []string) engine.Branches

BranchesFromGraph resolves branch names to their graph Branch objects, skipping any name not present in the graph.

Types

type AnnotationOptions 

type AnnotationOptions struct {
	SkipCommitMessages bool
	SkipDiffStats      bool
}

AnnotationOptions controls which expensive git-derived fields are skipped. The zero value populates every field — opt out of work, never into it, so callers that forget the struct still get a complete annotation.

type AnnotationReader 

type AnnotationReader interface {
	ScopeReader
	// contains filtered or unexported methods
}

AnnotationReader is the engine surface annotations with worktree info read.

type BranchAnnotation 

type BranchAnnotation struct {
	IsLocked      bool
	IsFrozen      bool
	Scope         string
	ExplicitScope string

	// LocalSHA is the short commit SHA of the branch head.
	LocalSHA string

	PRNumber *git.PRNumber
	PRState  git.PRState
	PRURL    string
	IsDraft  bool

	CommitCount    int
	CommitMessages []string
	LinesAdded     int
	LinesDeleted   int

	// MergedDownstack holds historical merged parents.
	MergedDownstack []git.MergedParent

	Check  CheckState
	Review ReviewState

	// WorktreePath is set when the branch's stack is owned by a managed worktree.
	WorktreePath engine.WorktreePath
	// IsEmptyWorktree marks a worktree anchor with no child branches.
	IsEmptyWorktree bool
}

BranchAnnotation is the display data for one branch in a stack view: branch state, PR metadata, git-derived stats, forge (CI/review) status, and worktree ownership. Adapters convert it into their own render types.

func BaseAnnotation 

func BaseAnnotation(eng ScopeReader, branch engine.Branch, stat engine.BranchStat, opts AnnotationOptions) BranchAnnotation

BaseAnnotation returns a branch's annotation without forge or worktree enrichment. The git-computed fields (short SHA, commit count, diff stats) come from stat, a batched value the caller resolves with BatchBranchStats — code annotating a set of branches must build that batch rather than reading per branch.

func FullAnnotation 

func FullAnnotation(eng AnnotationReader, branch engine.Branch, stat engine.BranchStat, enrichment *Enrichment, opts AnnotationOptions) BranchAnnotation

FullAnnotation returns BaseAnnotation joined with the enrichment's CI and review status and worktree info. A nil enrichment yields the base annotation.

func MinimalAnnotation 

func MinimalAnnotation(eng AnnotationReader, branch engine.Branch, worktrees *WorktreeIndex) BranchAnnotation

MinimalAnnotation returns the instant fields of an annotation — branch state, scope, and worktree info — with no git or network work, for fast initial rendering before full data is loaded.

type BranchData 

type BranchData struct {
	RemoteStatuses engine.BranchRemoteStatuses
	Stats          map[string]engine.BranchStat
	Commits        map[string]git.Commits
	CommitInfo     map[string]git.CommitInfo
	Statuses       engine.BranchStatuses
}

BranchData holds per-branch data read via batch calls, keyed by branch name. Resolve it once via FetchBranchData over the union of branches in every stack being shown, not once per stack — RemoteStatuses in particular backs a network round trip (`git ls-remote`) whose cost does not depend on how many branches it covers.

func FetchBranchData 

func FetchBranchData(ctx context.Context, eng BranchDataReader, branches engine.Branches) BranchData

FetchBranchData runs the batch reads backing BranchData: one remote listing, one stats pass, one commits pass, one commit-info pass, and one restack-status pass for all branches.

type BranchDataReader 

type BranchDataReader interface {
	ReadBranchRemoteStatuses(ctx context.Context, branches engine.Branches) engine.BranchRemoteStatuses
	BatchBranchStats(branches engine.Branches) map[string]engine.BranchStat
	BatchCommits(branches engine.Branches) map[string]git.Commits
	BatchCommitInfo(branches engine.Branches) map[string]git.CommitInfo
	ReadBranchStatuses(branches engine.Branches) engine.BranchStatuses
}

BranchDataReader is the engine surface FetchBranchData reads.

type CheckState 

type CheckState string

CheckState is the aggregate CI state of a branch's PR. The zero value means no CI status is known. 

const (
	CheckUnknown CheckState = ""
	CheckPassing CheckState = "passing"
	CheckFailing CheckState = "failing"
	CheckPending CheckState = "pending"
)

CheckState values.

type Enrichment 

type Enrichment struct {
	CIStatuses github.ChecksByBranch
	Worktrees  *WorktreeIndex
}

Enrichment holds data resolved once for a whole view and joined into each branch's annotation: forge status (fetched separately from branch state) and the managed worktree index.

type LocalStackStatus 

type LocalStackStatus string

LocalStackStatus is a stack's status judged from local branch state only. 

const (
	LocalStackShippable  LocalStackStatus = "shippable"
	LocalStackPending    LocalStackStatus = "pending"
	LocalStackBlocked    LocalStackStatus = "blocked"
	LocalStackIncomplete LocalStackStatus = "incomplete"
)

LocalStackStatus values. The strings match shippable.Status on purpose so the web UI can style both, but the rules differ — see LocalStatus.

func LocalStatus 

func LocalStatus(graph *engine.StackGraph, branchNames []string, statuses engine.BranchStatuses) LocalStackStatus

LocalStatus classifies a stack from local metadata alone: locked → blocked, needs restack → pending, missing PR → incomplete, else shippable. statuses should come from one ReadBranchStatuses batch covering branchNames.

This is deliberately not shippable.determineStatus, which classifies from forge state (CI checks, review decision, draft, pushed-vs-remote) and is what `merge`/the dashboard use to decide what can actually ship. This one needs no network and backs the API's stack summaries; the two can disagree (e.g. a locked stack with green CI, or a failing-CI stack that is up to date locally).

type ReviewState 

type ReviewState string

ReviewState is the review decision on a branch's PR. The zero value means no review decision is known. 

const (
	ReviewUnknown          ReviewState = ""
	ReviewApproved         ReviewState = "approved"
	ReviewChangesRequested ReviewState = "changes_requested"
	ReviewAwaiting         ReviewState = "review_required"
)

ReviewState values.

type ScopeReader 

type ScopeReader interface {
	GetScope(branch engine.Branch) engine.Scope
}

ScopeReader resolves a branch's effective scope.

type StackInfo 

type StackInfo struct {
	RootBranch  string   // Stack root branch name (direct child of trunk)
	AllBranches []string // All branches in the stack (root to tip, in order)
	PRCount     int      // Number of PRs in this stack
	Scope       string   // Stack scope if any
}

StackInfo describes one independent stack rooted at a direct child of trunk.

func (StackInfo) Label 

func (s StackInfo) Label() string

Label returns the display label for a stack.

type Stacks 

type Stacks []StackInfo

Stacks is an ordered collection of independent stacks.

func DiscoverStacks 

func DiscoverStacks(eng engine.StackView) Stacks

DiscoverStacks returns all independent stacks rooted at trunk, with siblings ordered alphabetically. Each stack is represented by its root branch (direct child of trunk) and includes all branches in the stack in topological order.

func DiscoverStacksWithSort 

func DiscoverStacksWithSort(eng engine.StackView, strategy engine.SortStrategy) Stacks

DiscoverStacksWithSort is like DiscoverStacks but allows specifying the sort strategy. Use SortStrategySmart to match the ordering of `stackit tree`.

func (Stacks) AllBranchNames 

func (stacks Stacks) AllBranchNames() []string

AllBranchNames returns every branch of every stack, in stack order.

func (Stacks) FilterByRoots 

func (stacks Stacks) FilterByRoots(selectedRoots []string) Stacks

FilterByRoots returns stacks selected by root name, preserving selection order. If selectedRoots is empty, returns all stacks.

type WorktreeIndex 

type WorktreeIndex struct {
	// Empty maps worktree anchor branches that have no child branches.
	Empty map[string]*engine.WorktreeInfo
	// ByStackRoot maps every managed worktree's stack root to its info.
	ByStackRoot map[string]*engine.WorktreeInfo
}

WorktreeIndex holds managed worktree information resolved from a single ListManagedWorktrees call, so per-branch lookups are map reads.

func BuildWorktreeIndex 

func BuildWorktreeIndex(src WorktreeSource) *WorktreeIndex

BuildWorktreeIndex lists managed worktrees once and indexes them by stack root, also recording which worktree anchors are empty (have no descendants). A listing failure yields an empty index.

func (*WorktreeIndex) EmptyAnchorNames 

func (idx *WorktreeIndex) EmptyAnchorNames() map[string]bool

EmptyAnchorNames returns the set of empty worktree anchor names, or nil when there are none, for renderers that keep empty anchors visible.

type WorktreeSource 

type WorktreeSource interface {
	ListManagedWorktrees() ([]engine.WorktreeInfo, error)
	GetBranch(branchName string) engine.Branch
	BranchesDepthFirst(startBranch engine.Branch) iter.Seq2[engine.Branch, int]
}

WorktreeSource is the engine surface BuildWorktreeIndex reads.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.