commit

type Backend ¶

type Backend interface {
	Execute(ctx context.Context, plan *Plan, conventional bool) (*Result, error)
}

Backend executes a commit plan.

type CommitBlock ¶ added in v0.6.0

type CommitBlock struct {
	Ring    CommitRing
	ID      string // stable identifier for programmatic use and output
	Message string // human-readable explanation
}

CommitBlock is a classified failure at any stage of commit planning or execution. Hard rings (Mechanical, Determinism) propagate as errors. Governance rings accumulate and are either reported or bypassed.

func (b CommitBlock) Overrideable() bool

type CommitBlocks ¶ added in v0.6.0

type CommitBlocks []CommitBlock

CommitBlocks is an ordered collection of CommitBlock values.

func (bs CommitBlocks) GovernanceOnly() CommitBlocks

func (bs CommitBlocks) HasDeterminism() bool

func (bs CommitBlocks) HasGovernance() bool

func (bs CommitBlocks) HasHard() bool

func (bs CommitBlocks) HasMechanical() bool

type CommitRing ¶ added in v0.6.0

type CommitRing string

CommitRing classifies a commit failure by its relationship to the commit path's safety and determinism. The ring determines whether a failure is absolute or can be bypassed with explicit maintainer intent.

Three rings, ordered by overrideability:

RingMechanical   → git integrity is broken. No escape.
RingDeterminism  → StageFreight cannot reliably describe what will happen. No escape.
RingGovernance   → StageFreight policy or model is degraded, but the commit
                   path is still deterministic. Bypassed by --maintainer-override.

The rule: do not let Ring 3 failures disable a still-deterministic commit path.

const (
	// RingMechanical covers failures where the git repository, index, or
	// filesystem state makes committing impossible regardless of intent:
	//   - detached HEAD
	//   - unresolved rebase/merge conflict
	//   - index write failure
	//   - hook rejected the commit
	//   - push explicitly requested but mechanically blocked
	// Cannot be overridden.
	RingMechanical CommitRing = "mechanical"

	// RingDeterminism covers failures where StageFreight cannot reliably
	// determine what will be committed, construct the message, or truthfully
	// describe the result:
	//   - missing commit summary
	//   - unresolvable path set
	//   - sync plan logically impossible (not a git error, a planning error)
	// Cannot be overridden.
	RingDeterminism CommitRing = "determinism"

	// RingGovernance covers failures where StageFreight policy, schema, or
	// model is degraded but the commit path itself remains deterministic:
	//   - partial config-model migration incomplete
	//   - generated outputs stale (docs, badges, manifests)
	//   - convention strictness failures
	//   - unrelated StageFreight subsystem broken
	// Can be bypassed with --maintainer-override.
	// Bypasses are recorded in Result.OverriddenBlocks and printed to output.
	RingGovernance CommitRing = "governance"
)

type DryRunBackend ¶

type DryRunBackend struct {
	RootDir string
}

DryRunBackend prints the commit plan without side effects.

func (d *DryRunBackend) Execute(_ context.Context, plan *Plan, conventional bool) (*Result, error)

type Engine ¶ added in v0.6.0

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

Engine orchestrates repository convergence as an explicit state machine.

Every mutation is a validated transition between named states. No operation is performed outside of a valid (from, action, to) triple.

Transition table:

CLEAN_SYNCED  → (no-op)                              → CLEAN_SYNCED
CLEAN_BEHIND  → FAST_FORWARD                         → CLEAN_SYNCED
CLEAN_AHEAD   → PUSH                                 → CLEAN_SYNCED
DIVERGED      → REPLAY → CLEAN_AHEAD → PUSH          → CLEAN_SYNCED

Blocked states (hard stops — no transitions allowed):

DETACHED_HEAD, DIRTY_WORKTREE, NO_UPSTREAM

When RebaseOnDiverge is false, DIVERGED returns ErrInvalidTransition instead of attempting replay — the caller must resolve the divergence manually.

func NewEngine(session *gitstate.SyncSession, opts EngineOptions) *Engine

func (e *Engine) Sync() (*SyncResult, error)

type EngineOptions ¶ added in v0.6.0

type EngineOptions struct {
	// RebaseOnDiverge: when true, DIVERGED state triggers Replay + Push.
	// When false, DIVERGED returns ErrInvalidTransition — the user must
	// resolve the divergence manually before pushing.
	RebaseOnDiverge bool

	// Remote overrides the remote resolved from the session state.
	// Empty means "use whatever the branch tracking config says".
	Remote string

	// Refspec is an optional explicit push refspec (e.g. "HEAD:refs/heads/main").
	// Empty means push the current branch to its upstream.
	Refspec string

	// OnEvent receives a structured event for every state transition.
	// If nil, events are silently dropped.
	// Use this for CI log output, tracing, or UI state panels.
	OnEvent func(gitstate.TransitionEvent)
}

EngineOptions configures Engine behaviour.

type FileChange ¶

type FileChange struct {
	Path    string
	Deleted bool
}

FileChange represents a file with its change status.

type ForgeBackend ¶

type ForgeBackend struct {
	RootDir     string
	ForgeClient forge.Forge
	Branch      string
}

ForgeBackend creates commits purely via forge API (no local git commit).

func (f *ForgeBackend) Execute(ctx context.Context, plan *Plan, conventional bool) (*Result, error)

type GitBackend ¶

type GitBackend struct {
	RootDir string
	// OnCommitLine is called for each output line during hook execution and sync
	// transition events. stream: "stdout", "stderr", "hook_side_effect", "sync".
	// If nil, output is captured but not forwarded.
	OnCommitLine func(stream string, line string)
}

GitBackend executes commits via go-git — no git binary required. Push/sync is also handled via go-git through the Engine.

func (g *GitBackend) Execute(_ context.Context, plan *Plan, conventional bool) (*Result, error)

func (g *GitBackend) Push(opts PushOptions) (*SyncResult, error)

type Plan ¶

type Plan struct {
	Type      string
	Scope     string
	Summary   string
	Body      string
	Breaking  bool
	SkipCI    bool
	Paths     []string // for StageExplicit
	StageMode StageMode
	Push      PushOptions
	SignOff   bool
}

Plan is a fully resolved, validated commit intent.

func BuildPlan(opts PlannerOptions, cfg config.CommitConfig, registry *TypeRegistry, rootDir string) (*Plan, error)

func (p Plan) Message(conventional bool) string

func (p Plan) Subject(conventional bool) string

type PlannerOptions ¶

type PlannerOptions struct {
	Type     string
	Scope    string
	Message  string // positional or --message
	Body     string
	Breaking bool
	SkipCI   *bool    // nil = use config default
	Push     *bool    // nil = use config default
	Paths    []string // from --add flags
	All      bool
	SignOff  bool
	Remote   string
	Refspec  string
}

PlannerOptions holds raw inputs from CLI flags and positional args.

type PushOptions ¶

type PushOptions struct {
	Enabled         bool
	Remote          string // default: "origin"
	Refspec         string // default: "" (current branch)
	RebaseOnDiverge bool   // when true (default), rebase onto upstream if diverged before pushing
}

PushOptions controls post-commit push behavior.

type Result ¶

type Result struct {
	SHA     string
	Message string
	Files   []string // actual staged files (from git diff --cached --name-only)
	Pushed  bool
	NoOp    bool
	Backend string      // stable descriptor: "git", "forge (gitlab)", "forge (github)", "dry-run"
	Sync    *SyncResult // populated when push was executed via the convergence engine

	// MaintainerOverride is true when --maintainer-override was active for this commit.
	// OverriddenBlocks records which governance checks were bypassed.
	// Both are empty for normal commits with no governance failures.
	MaintainerOverride bool
	OverriddenBlocks   CommitBlocks
}

Result holds the outcome of a commit execution. All informational status must be represented here, not printed by backends.

type StageMode ¶

type StageMode string

StageMode determines how files are staged before commit.

const (
	StageExplicit StageMode = "explicit" // --add paths
	StageAll      StageMode = "all"      // --all (git add -A)
	StageStaged   StageMode = "staged"   // default: commit whatever is already staged
)

type SyncAction ¶ added in v0.6.0

type SyncAction string

SyncAction names a single step in the repository convergence plan.

const (
	SyncSetUpstream SyncAction = "set-upstream" // configure tracking branch on first push
	SyncFetch       SyncAction = "fetch"        // fetch remote before rebase or fast-forward
	SyncFastForward SyncAction = "fast-forward" // merge --ff-only to catch up to upstream
	SyncRebase      SyncAction = "rebase"       // rebase local commits onto upstream
	SyncPush        SyncAction = "push"         // push to remote
	SyncNoop        SyncAction = "noop"         // already up to date, nothing to do
)

type SyncResult ¶ added in v0.6.0

type SyncResult struct {
	ActionsExecuted []SyncAction
	PushedRef       string // remote name that was pushed to
	Noop            bool   // true only when SyncNoop was the sole action
}

SyncResult is the outcome of a push operation.

type TypeRegistry ¶

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

TypeRegistry validates and resolves commit type keys.

func NewTypeRegistry(types []config.CommitType) *TypeRegistry

func (r *TypeRegistry) List() []config.CommitType

func (r *TypeRegistry) Resolve(key string) (resolvedKey string, forceBang bool, err error)

func (r *TypeRegistry) Valid(key string) bool