integrate

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 2, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package integrate implements the gz-git integrate command surface.

queue lists unfinished task branches. check answers readiness. run fast-forwards an authorized target and reclaims the task branch. Remote reclaim deletes with --force-with-lease against the integrated SHA. A repository that declares neither make check nor make lint is not ready unless --allow-skipped-checks is set.

Integration-branch lookup is not ResolveBase. ResolveBase only sees local refs/heads and prefers master over develop. This package uses a declared integrationBranch when present, otherwise the remote HEAD, and treats a missing base as a reportable state.

Index

Constants

View Source 
const (
	// DefaultExpiryDays is the queue age after which a branch is expired.
	DefaultExpiryDays = 7
	// QuietMaxBranches is the hook-style queue size above which --quiet exits.
	QuietMaxBranches = 20
)
View Source 
const (
	// SourceNone means no integration branch participates.
	SourceNone = config.IntegrationBranchSourceNone
	// SourceHeuristic means the remote-HEAD fallback won.
	SourceHeuristic = config.IntegrationBranchSourceHeuristic
	// SourceConfigPrefix prefixes a declared candidate source.
	SourceConfigPrefix = config.IntegrationBranchSourceConfigPrefix
)

Variables

View Source 
var ErrImplicitSourceIsTarget = errors.New("implicit source branch is the integration target")

ErrImplicitSourceIsTarget reports a bare integrate invocation from the resolved target branch. Callers should retry from a task-branch worktree.

Functions

func BootstrapApply 

func BootstrapApply(ctx context.Context, exec *gitcmd.Executor, plan BootstrapPlan, repoPath, confirmation string) error

BootstrapApply recomputes a confirmation plan and pushes it with an exact lease after the caller supplies the reviewed canonical digest.

func BootstrapPlanDigest 

func BootstrapPlanDigest(p BootstrapPlan) string

BootstrapPlanDigest is the canonical value a human must explicitly confirm.

func ExtractLocations 

func ExtractLocations(output string, tracked []string) []string

ExtractLocations pulls file:line tokens from tool output and normalizes them against the revision's tracked paths: an over-qualified path loses leading components, and a path emitted relative to a subdirectory is lifted back to its root-relative form when exactly one tracked path ends with it. Unmatched paths are kept, fail-closed.

func FormatCheck 

func FormatCheck(r *CheckReport) string

FormatCheck renders the readiness report.

func FormatQueue 

func FormatQueue(r *QueueReport) string

FormatQueue renders the branch-status table. Quiet already filtered rows.

func FormatRun 

func FormatRun(r *RunReport) string

FormatRun renders integrate/reclaim lines.

func NormalizeName 

func NormalizeName(raw string, remotes []string) string

NormalizeName preserves the integrate package's branch normalization API.

func ReadinessUpdateApply 

func ReadinessUpdateApply(ctx context.Context, exec *gitcmd.Executor, plan ReadinessUpdatePlan, repoPath, confirmation string) error

ReadinessUpdateApply revalidates and leases the reviewed update plan. Callers must enforce the human authorization boundary; the CLI requires a TTY and the downstream hook independently rejects unapproved direct invocations.

func ReadinessUpdatePlanDigest 

func ReadinessUpdatePlanDigest(p ReadinessUpdatePlan) string

ReadinessUpdatePlanDigest returns the canonical human-confirmation digest.

func SplitRemoteBranch 

func SplitRemoteBranch(raw string, remotes []string) (remote, branch string, ok bool)

SplitRemoteBranch preserves the integrate package's remote split API.

func UpstreamTargetsIntegration 

func UpstreamTargetsIntegration(branch, upstream string, resolution Resolution, remotes []string) bool

UpstreamTargetsIntegration preserves the integrate package's safety check API.

func WriteBootstrapPlan 

func WriteBootstrapPlan(path string, p BootstrapPlan) error

WriteBootstrapPlan writes a confirmation plan to stdout or a mode-0600 file.

func WriteReadinessUpdatePlan 

func WriteReadinessUpdatePlan(path string, p ReadinessUpdatePlan) error

WriteReadinessUpdatePlan writes a plan to stdout or a mode-0600 file.

Types

type BaseMeasurement 

type BaseMeasurement int

BaseMeasurement says what zero file:line diagnostics from a failed target tip actually mean.

len(base) == 0 conflates two states that need opposite handling:

  • The run died before it could analyze anything — mix without deps/, a test runner without node_modules/, a venv-less pytest. No baseline exists, so the gate was skipped, and --allow-skipped-checks may downgrade it. This is the state BaselineUnmeasurable was added for.
  • The run went all the way through and reported a failure in a shape that carries no file:line at all — gofmt -l, gci diff. That is a measurement of zero, so a branch that emits N has genuinely worsened it, and --allow-skipped-checks must not excuse that: the flag's contract is "this check was skipped", and this check was not.

The burden of proof sits on the second state, and that direction is the whole design. Removing the operator's escape hatch is the destructive action: get it wrong and a repository cannot land anything, which is the failure TASK-134 fixed and which this must not reintroduce. Leaving the hatch in place when it was not warranted costs one downgradable warning. So "measured" has to be positively evidenced, and everything else — an unrecognized failure, a crash, a bare `exit 1`, a caller that filled nothing in — stays unmeasured. 

const (
	// BaseMeasurementUnknown is the zero value, and it reads as unmeasured.
	// A caller that says nothing gets exactly the behavior it had before this
	// field existed: an empty base is an absent baseline. EvaluateBaseline and
	// BaselineInput are both exported, so the zero value is what every caller
	// outside this package already passes, and silently flipping their verdict
	// from a downgradable skip to a hard count failure is not a change this
	// field is entitled to make on their behalf.
	BaseMeasurementUnknown BaseMeasurement = iota
	// BaseMeasured is set only when the target-tip probe showed evidence it
	// enumerated repository files, which it could not have done without
	// reaching the analysis stage. Its zero is then a real zero.
	BaseMeasured
)

type BaselineInput 

type BaselineInput struct {
	BranchLocations []string
	BaseLocations   []string
	ChangedPaths    []string
	// BranchPrepared and BasePrepared record the tree each side ran in.
	BranchPrepared PrepareState
	BasePrepared   PrepareState
	// BaseMeasurement says whether the target-tip run reached the stage where
	// it could have reported a diagnostic at all.
	BaseMeasurement BaseMeasurement
}

BaselineInput is the already-normalized location lists for one make target, plus the evidence needed to read an empty BaseLocations correctly. The two evidence fields are documented with their types in check_baseline_state.go.

type BaselineResult 

type BaselineResult struct {
	Status BaselineStatus
	Reason string
}

BaselineResult is the count-only non-worsening verdict.

func EvaluateBaseline 

func EvaluateBaseline(in BaselineInput) BaselineResult

EvaluateBaseline is the non-worsening gate.

It does not compare diagnostic location sets. The measured lint run (golangci-lint, same commit, twice) produced 121 locations of which 78 differed — a set-diff makes the gate unpassable. Only two signals are stable: diagnostics on paths this branch changed, and a count increase.

type BaselineStatus 

type BaselineStatus int

BaselineStatus is the non-worsening verdict for a failed make target. 

const (
	// BaselinePass means the branch did not worsen the target tip.
	BaselinePass BaselineStatus = iota
	// BaselineFail means the branch introduced or increased failures.
	BaselineFail
	// BaselineUnmeasurable means the comparison could not be made at all:
	// the target tip's own run failed without emitting a single file:line
	// diagnostic, so there is no baseline to compare against. It is not a
	// verdict about the branch and must never be reported as one.
	BaselineUnmeasurable
)

type BootstrapOptions 

type BootstrapOptions struct {
	RepoPath, Branch, Target, Issuer string
	Expiry                           time.Duration
	PlanPath                         string
}

BootstrapOptions selects the source and exact target for a confirmation plan.

type BootstrapPlan 

type BootstrapPlan struct {
	Version             int    `json:"version"`
	OperationID         string `json:"operation_id"`
	Issuer              string `json:"issuer"`
	ExpiresAt           string `json:"expires_at"`
	Repository          string `json:"repository"`
	Remote              string `json:"remote"`
	TargetRef           string `json:"target_ref"`
	TargetSHA           string `json:"target_sha"`
	SourceRef           string `json:"source_ref"`
	SourceSHA           string `json:"source_sha"`
	ManifestPath        string `json:"manifest_path"`
	ManifestOID         string `json:"manifest_oid"`
	RunnerPath          string `json:"runner_path"`
	RunnerOID           string `json:"runner_oid"`
	ReadinessTreeOID    string `json:"readiness_tree_oid"`
	ReadinessTreeDigest string `json:"readiness_tree_digest"`
	PushEndpoint        string `json:"push_endpoint"`
	DestinationRef      string `json:"destination_ref"`
	IssuedAt            string `json:"issued_at"`
	TTLSeconds          int64  `json:"ttl_seconds"`
}

BootstrapPlan is an immutable, auditable confirmation plan for the one-commit readiness bootstrap. It is not a signed authorization; apply requires an explicit human confirmation and recomputes every field.

func BootstrapPlanFor 

func BootstrapPlanFor(ctx context.Context, exec *gitcmd.Executor, opts BootstrapOptions) (BootstrapPlan, error)

BootstrapPlanFor validates a one-commit readiness introduction and returns the exact expiring facts that a human must review before apply.

func ReadBootstrapPlan 

func ReadBootstrapPlan(path string) (BootstrapPlan, error)

ReadBootstrapPlan decodes an exact V1 confirmation-plan JSON object.

type CheckItem 

type CheckItem struct {
	Name   string
	Status string
	Detail string
}

CheckItem is one readiness row.

type CheckOptions 

type CheckOptions struct {
	RepoPath           string
	Branch             string
	Target             string
	DirectToDefault    bool
	Release            bool
	AllowSkippedChecks bool
	IntegrationConfig  []string
	// ControllerConfig is an explicit devbox/controller file. It is never
	// discovered from ancestors and never inherits repository readiness.
	ControllerConfig string
	// NoFetch skips git fetch of the remote before resolving the target.
	// The target is resolved from the local remote-tracking ref; when that
	// ref is absent the check fails instead of falling back to a stale
	// local integration branch.
	NoFetch bool
}

CheckOptions configures a read-only readiness check.

type CheckReport 

type CheckReport struct {
	Ready     bool
	Plan      TargetPlan
	Items     []CheckItem
	Failures  int
	Warnings  int
	RootFacts []string
	// Gate provenance is recorded so run can repeat the exact checked state.
	GateMode          string
	ManifestPath      string
	ContractDigest    string
	ManifestOID       string
	RunnerPath        string
	RunnerOID         string
	ReadinessTreeOID  string
	ReadinessStatus   string
	ReadinessDuration time.Duration
	PrepareProfile    string
	PrepareInputs     string
	Controller        *controllerBinding
}

CheckReport is the readiness answer. It never pushes or reclaims.

func Check 

func Check(ctx context.Context, exec *gitcmd.Executor, opts CheckOptions) (*CheckReport, error)

Check answers whether the branch can land on the target.

type Facts 

type Facts = config.IntegrationBranchFacts

Facts remains an alias for the integrate command's established API.

type PrepareState 

type PrepareState string

PrepareState names the tree a probe was measured in.

It exists because the two probes are not prepared alike. With no controller profile the branch is measured in the live working directory, where deps/, node_modules/ and .venv already sit from earlier runs, while the baseline is measured in a worktree checked out fresh at the target SHA, where none of them do. That asymmetry — not the target tip's own health — is what makes a bootstrap-hungry checker die on the baseline side only, so it has to be reportable as the reason rather than left as an unstated premise. 

const (
	// PrepareStateUnknown means the caller did not say, so no claim about
	// symmetry can be made in either direction.
	PrepareStateUnknown PrepareState = ""
	// PrepareStateWorkingDir is the live repository working directory, with
	// whatever build artifacts previous runs left in it.
	PrepareStateWorkingDir PrepareState = "the live working directory"
	// PrepareStatePristine is a worktree checked out fresh at one SHA and
	// never bootstrapped.
	PrepareStatePristine PrepareState = "a pristine worktree"
	// PrepareStateProfilePrepared is a fresh worktree that runPrepareProfile
	// then bootstrapped. Both sides get it, so those two probes are symmetric
	// and the asymmetry clause below stays silent.
	PrepareStateProfilePrepared PrepareState = "a profile-prepared worktree"
)

type QueueEntry 

type QueueEntry struct {
	Ref        string
	Ahead      int
	Behind     int
	BaseState  string
	MergeState string
	AgeDays    int
	Note       string
	Expired    bool
}

QueueEntry is one local or remote task branch that is not the base, the remote HEAD, or the integration branch.

type QueueOptions 

type QueueOptions struct {
	RepoPath   string
	Base       string
	ExpiryDays int
	NoFetch    bool
	Quiet      bool
	// ControllerConfig is an explicitly selected devbox/controller file. It is
	// never discovered from ancestors and, when set, supplies the authoritative
	// remote, integration branch, and optional task-branch namespace.
	ControllerConfig string
	// ConfigValues is the declared integrationBranch list. Empty means
	// load the repo-root .gz-git.yaml, same as check/run.
	ConfigValues []string
	Now          time.Time
}

QueueOptions configures a read-only integrate queue scan.

type QueueReport 

type QueueReport struct {
	Base          string
	BaseSource    string
	BaseMissing   bool
	Integration   Resolution
	Remote        string
	Entries       []QueueEntry
	StaleCount    int
	ConflictCount int
	ExpiredCount  int
	MergedCount   int
	ExpiryDays    int
	QuietSkipped  bool
}

QueueReport is the read-only answer to "what is waiting to integrate?".

func CollectQueue 

func CollectQueue(ctx context.Context, exec *gitcmd.Executor, opts QueueOptions) (*QueueReport, error)

CollectQueue lists unfinished task branches. An empty queue is success. A missing base is a reportable state, not a guessed origin/master.

type ReadinessUpdateOptions 

type ReadinessUpdateOptions struct {
	RepoPath, Branch, Target, Issuer string
	Expiry                           time.Duration
}

ReadinessUpdateOptions selects the source and target for an update plan.

type ReadinessUpdatePlan 

type ReadinessUpdatePlan struct {
	Version                int64  `json:"version"`
	OperationID            string `json:"operation_id"`
	Issuer                 string `json:"issuer"`
	ExpiresAt              string `json:"expires_at"`
	Repository             string `json:"repository"`
	Remote                 string `json:"remote"`
	TargetRef              string `json:"target_ref"`
	TargetSHA              string `json:"target_sha"`
	SourceRef              string `json:"source_ref"`
	SourceSHA              string `json:"source_sha"`
	PushEndpoint           string `json:"push_endpoint"`
	DestinationRef         string `json:"destination_ref"`
	OperationRef           string `json:"operation_ref"`
	IssuedAt               string `json:"issued_at"`
	TTLSeconds             int64  `json:"ttl_seconds"`
	OldManifestPath        string `json:"old_manifest_path"`
	OldManifestOID         string `json:"old_manifest_oid"`
	OldRunnerPath          string `json:"old_runner_path"`
	OldRunnerOID           string `json:"old_runner_oid"`
	OldReadinessTreeOID    string `json:"old_readiness_tree_oid"`
	OldReadinessTreeDigest string `json:"old_readiness_tree_digest"`
	OldReadinessTreePath   string `json:"old_readiness_tree_path"`
	OldContractDigest      string `json:"old_contract_digest"`
	NewManifestPath        string `json:"new_manifest_path"`
	NewManifestOID         string `json:"new_manifest_oid"`
	NewRunnerPath          string `json:"new_runner_path"`
	NewRunnerOID           string `json:"new_runner_oid"`
	NewReadinessTreeOID    string `json:"new_readiness_tree_oid"`
	NewReadinessTreeDigest string `json:"new_readiness_tree_digest"`
	NewReadinessTreePath   string `json:"new_readiness_tree_path"`
	NewContractDigest      string `json:"new_contract_digest"`
}

ReadinessUpdatePlan is the one-use, human-confirmed transaction for changing a target-owned readiness V1 contract. It intentionally binds both sides of the contract, rather than treating a changed runner as an ordinary run.

func ReadReadinessUpdatePlan 

func ReadReadinessUpdatePlan(path string) (ReadinessUpdatePlan, error)

ReadReadinessUpdatePlan decodes an exact V1 plan object.

func ReadinessUpdatePlanFor 

func ReadinessUpdatePlanFor(ctx context.Context, exec *gitcmd.Executor, opts ReadinessUpdateOptions) (ReadinessUpdatePlan, error)

ReadinessUpdatePlanFor validates and snapshots a one-commit contract update.

type ReclaimResult 

type ReclaimResult struct {
	Skipped string
	Done    []string
	Failed  []string
}

ReclaimResult records what reclaim did after a successful integrate.

func (ReclaimResult) Incomplete 

func (r ReclaimResult) Incomplete() bool

Incomplete reports a successful integrate whose reclaim did not finish.

type Resolution 

type Resolution = config.IntegrationBranchResolution

Resolution remains an alias for the integrate command's established API.

func ResolveFromFacts 

func ResolveFromFacts(f Facts) Resolution

ResolveFromFacts preserves the integrate package's facts-only API.

func ResolveIntegrationBranch 

func ResolveIntegrationBranch(ctx context.Context, exec *gitcmd.Executor, repoPath string, configValues []string) (Resolution, error)

ResolveIntegrationBranch preserves the integrate package's Git-backed API.

type RunOptions 

type RunOptions struct {
	CheckOptions
}

RunOptions configures a fast-forward integrate and reclaim.

type RunReport 

type RunReport struct {
	Check      *CheckReport
	Source     string
	Target     string
	SHA        string
	Reclaim    ReclaimResult
	Printed    []string
	Integrated bool
}

RunReport is the result of integrate run.

func Run 

func Run(ctx context.Context, exec *gitcmd.Executor, opts RunOptions) (*RunReport, error)

Run fast-forwards the target and reclaims the task branch. Reclaim only matches declared taskPattern. No pattern → reclaim nothing.

type TargetPlan 

type TargetPlan struct {
	Branch      string
	BranchSHA   string
	Remote      string
	Target      string
	TargetSHA   string
	DefaultRef  string
	Integration Resolution
	HeadSHA     string
}

TargetPlan is the resolved check/run destination.

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.