flatten

Documentation

Overview

Package flatten provides functionality for flattening stacked branches closer to trunk.

Index

• func Action(ctx *app.Context, opts Options, handler Handler) error
• func HasFlattenWork(ctx *app.Context, opts Options) (bool, error)
• type AnalysisProgressFunc
• type ExcludedBranch
• type Handler
• type NullHandler
  • func (h *NullHandler) Complete(Result)
  • func (h *NullHandler) OnBranchMoved(string, string, string)
  • func (h *NullHandler) OnValidationProgress(int, int, string)
  • func (h *NullHandler) PromptConfirmFlatten(Preview) (bool, error)
  • func (h *NullHandler) Start(int)
• type Options
• type PlannedMove
• type Preview
• type Result
• type Step

Functions

func Action

func Action(ctx *app.Context, opts Options, handler Handler) error

Action performs the flatten operation. Flatten analyzes the stack and moves branches as close to trunk as possible while respecting dependencies (branches that would conflict stay in place).

func HasFlattenWork

func HasFlattenWork(ctx *app.Context, opts Options) (bool, error)

HasFlattenWork reports whether Action has at least one feature branch in the requested stack that's a candidate for flattening. Use this from the CLI to gate TUI initialization — if there's no candidate, starting the bubbletea runner only flashes startup/teardown escape codes and silences the explanatory "no branches to flatten" message via quiet mode.

This does *not* run the expensive flatten plan; a candidate found here may still end up unmoved after validation, in which case Action falls back to the handler.Complete summary path.

Types

type AnalysisProgressFunc

type AnalysisProgressFunc func(current, total int, branchName string)

AnalysisProgressFunc is called to report progress during flatten plan analysis.

type ExcludedBranch

type ExcludedBranch struct {
	Branch string // Branch name
	Reason string // Why it was kept in place (e.g., "X depends on this branch")
}

ExcludedBranch represents a branch that was kept in place due to code dependencies

type Handler

type Handler interface {
	// Start is called at the beginning of flatten
	Start(branchCount int)

	// OnStep is called for each step in the flatten process
	OnStep(step Step, status basehandler.StepStatus, message string)

	// OnValidationProgress is called during branch validation to report progress
	OnValidationProgress(current, total int, branchName string)

	// OnBranchMoved is called when a branch is moved to a new parent
	OnBranchMoved(branch, oldParent, newParent string)

	// Complete is called when flatten finishes
	Complete(result Result)

	// Cleanup restores terminal state (may be no-op)
	Cleanup()

	// IsInteractive returns true if the handler supports interactive prompts
	IsInteractive() bool

	// PromptConfirmFlatten displays a preview of the flatten and asks for confirmation.
	// Returns true to proceed with the flatten, false to cancel.
	// In non-interactive mode, returns true (auto-confirm).
	PromptConfirmFlatten(preview Preview) (bool, error)
}

Handler receives events from flatten action

type NullHandler

type NullHandler struct {
	basehandler.NullBase
	basehandler.NullProgress[Step]
}

NullHandler is a no-op handler for when nil is passed. It embeds basehandler.NullBase for Cleanup() and IsInteractive(), and basehandler.NullProgress[Step] for OnStep().

func (*NullHandler) Complete

func (h *NullHandler) Complete(Result)

Complete implements Handler.

func (*NullHandler) OnBranchMoved

func (h *NullHandler) OnBranchMoved(string, string, string)

OnBranchMoved implements Handler.

func (*NullHandler) OnValidationProgress

func (h *NullHandler) OnValidationProgress(int, int, string)

OnValidationProgress implements Handler.

func (*NullHandler) PromptConfirmFlatten

func (h *NullHandler) PromptConfirmFlatten(Preview) (bool, error)

PromptConfirmFlatten implements Handler. Returns true (auto-confirm) for null handler.

func (*NullHandler) Start

func (h *NullHandler) Start(int)

Start implements Handler.

type Options

type Options struct {
	BranchName  string // Branch to start flattening from (defaults to current branch)
	SkipConfirm bool   // Skip confirmation prompt (--yes flag)
}

Options contains options for the flatten command

type PlannedMove

type PlannedMove struct {
	Branch    string // Branch being moved
	OldParent string // Current parent branch
	NewParent string // Target parent branch (closer to trunk)
}

PlannedMove represents a single branch move in the flatten plan

type Preview

type Preview struct {
	Moves            []PlannedMove    // Branches that will be moved
	UnchangedCount   int              // Number of branches that won't change
	ExcludedBranches []ExcludedBranch // Branches kept in place due to dependencies
}

Preview contains information about the planned flatten for confirmation

type Result

type Result struct {
	MovedCount     int // Number of branches that were moved
	UnchangedCount int // Number of branches that stayed in place
}

Result contains the result of the flatten action

type Step

type Step string

Step represents a step in the flatten process

const (
	StepAnalyzing  Step = "analyzing"
	StepValidating Step = "validating"
	StepFlattening Step = "flattening"
	StepRestacking Step = "restacking"
)

Flatten step constants