worktreeproof

package
v0.182.5 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package worktreeproof owns neutral commit and receipt identity checks.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyWorktreeAge 

func ApplyWorktreeAge(result *AgeFields, worktree string, owners []string, state string, ttl time.Duration, now func() time.Time,
	readCreated func(string) (time.Time, error), statModified func(string) (time.Time, error))

ApplyWorktreeAge uses caller-owned readers, preserving manifest precedence.

func CommitFirstParent 

func CommitFirstParent(ctx context.Context, repository, revision string, git GitQuery) (string, error)

func CommitTree 

func CommitTree(ctx context.Context, repository, revision string, git GitQuery) (string, error)

func HasOnlyLowerHexCharacters 

func HasOnlyLowerHexCharacters(value string) bool

func IsAncestor 

func IsAncestor(ctx context.Context, repository, ancestor, descendant string,
	run func(context.Context, string, string, string) (int, error),
	lookup func(string) (bool, bool), store func(string, bool)) (bool, error)

IsAncestor keeps the self-comparison and memo policy independent of the Git runner.

func IsGitObjectID 

func IsGitObjectID(value string) bool

func IsGitRevisionID 

func IsGitRevisionID(value string) bool

func ParseCommitFirstParent 

func ParseCommitFirstParent(revision, parents string) (string, error)

func ParseCommitTree 

func ParseCommitTree(revision, tree string) (string, error)

func ParseRemoteDefaultBranch 

func ParseRemoteDefaultBranch(output string, valid func(string) bool) (string, error)

func SameAbsorbedPullRequest 

func SameAbsorbedPullRequest(left, right *PullRequest) bool

func SameSupersessionReceipt 

func SameSupersessionReceipt(left, right *SupersessionReceipt) bool

func WorktreeOwnerName 

func WorktreeOwnerName(owners []string, state string) string

Types

type AbsorbedConflictReceipt 

type AbsorbedConflictReceipt struct {
	ReceiptPath string `json:"receipt_path"`
	ID          string `json:"id"`
	Status      string `json:"status"`
	Lane        string `json:"lane"`
	Repository  string `json:"repository"`
	Target      string `json:"target"`
	TargetSHA   string `json:"target_sha"`
	Candidate   struct {
		Task     string `json:"task"`
		Worktree string `json:"worktree"`
		Branch   string `json:"branch"`
		SHA      string `json:"sha"`
	} `json:"candidate"`
	Sources []struct {
		Task     string `json:"task"`
		Worktree string `json:"worktree"`
		Branch   string `json:"branch"`
		SHA      string `json:"sha"`
	} `json:"sources"`
}

func (AbsorbedConflictReceipt) Identity 

func (receipt AbsorbedConflictReceipt) Identity() mergeack.ReceiptIdentity

type AgeFields 

type AgeFields struct {
	Owner      string
	CreatedAt  time.Time
	AgeSeconds int64
	TTLSeconds int64
	Expired    bool
}

AgeFields holds the reporting fields changed by ApplyWorktreeAge.

type DirtyWorktreeEvidence 

type DirtyWorktreeEvidence struct {
	SHA256 string `json:"sha256"`
	Bytes  int64  `json:"bytes"`
	Files  int    `json:"files"`
}

type GitQuery 

type GitQuery func(context.Context, string, ...string) (string, error)

GitQuery is a read-only, instance-scoped Git query supplied by the caller.

type OrphanedEvidence 

type OrphanedEvidence struct {
	Version            int       `json:"version"`
	ObservedAt         time.Time `json:"observed_at"`
	Actor              string    `json:"actor"`
	Reason             string    `json:"reason"`
	WorktreeAbsent     bool      `json:"worktree_absent"`
	RegistrationAbsent bool      `json:"registration_absent"`
	LocalBranchAbsent  bool      `json:"local_branch_absent"`
	RemoteBranchAbsent bool      `json:"remote_branch_absent"`
	TerminalAbsent     bool      `json:"terminal_absent"`
}

type PullRequest 

type PullRequest struct {
	Number     int        `json:"number"`
	URL        string     `json:"url"`
	Repository string     `json:"repository,omitempty"`
	State      string     `json:"state"`
	Base       string     `json:"base"`
	BaseSHA    string     `json:"base_sha,omitempty"`
	HeadSHA    string     `json:"head_sha"`
	MergeSHA   string     `json:"merge_sha,omitempty"`
	Merged     *time.Time `json:"merged_at,omitempty"`
}

PullRequest is immutable evidence used to corroborate a landing.

type RetiredPrepareCandidateReceipt 

type RetiredPrepareCandidateReceipt struct {
	ReceiptPath           string                       `json:"receipt_path"`
	ID                    string                       `json:"id"`
	Phase                 string                       `json:"phase"`
	Status                string                       `json:"status"`
	Lane                  string                       `json:"lane"`
	Repository            string                       `json:"repository"`
	Target                string                       `json:"target"`
	TargetSHA             string                       `json:"target_sha"`
	LandingSHA            string                       `json:"landing_sha"`
	PullRequest           string                       `json:"pull_request"`
	PublishedCandidateSHA string                       `json:"published_candidate_sha"`
	Candidate             retiredcandidateack.Source   `json:"candidate"`
	Sources               []retiredcandidateack.Source `json:"sources"`
}

func (RetiredPrepareCandidateReceipt) Identity 

func (receipt RetiredPrepareCandidateReceipt) Identity() retiredcandidateack.ReceiptIdentity

type SupersessionApproval 

type SupersessionApproval struct {
	Actor      string    `json:"actor"`
	Trusted    bool      `json:"trusted"`
	Decision   string    `json:"decision"`
	ReceiptID  string    `json:"receipt_id"`
	ApprovedAt time.Time `json:"approved_at"`
}

SupersessionApproval is the explicit trusted-reviewer boundary. Trusted is intentionally a field in the immutable receipt: WB never guesses who is trusted from a PR, commit author, CI result, or local identity.

type SupersessionDependencyDelta 

type SupersessionDependencyDelta struct {
	SourcePR         string `json:"source_pr"`
	SourceHead       string `json:"source_head"`
	Consumer         string `json:"consumer"`
	Ecosystem        string `json:"ecosystem"`
	Package          string `json:"package"`
	Manifest         string `json:"manifest"`
	Selector         string `json:"selector"`
	Before           string `json:"before"`
	RequestedAfter   string `json:"requested_after"`
	CandidateAfter   string `json:"candidate_after"`
	Lockfile         string `json:"lockfile,omitempty"`
	LockfileSelector string `json:"lockfile_selector,omitempty"`
	LockfileVersion  string `json:"lockfile_version,omitempty"`
	Reviewed         bool   `json:"reviewed"`
}

SupersessionDependencyDelta is immutable, per-source-PR evidence used before an old dependency PR may be called superseded. The selector is deliberately explicit: nx and @nx/* are different direct package identities.

func SortedDependencyDeltas 

func SortedDependencyDeltas(deltas []SupersessionDependencyDelta) []SupersessionDependencyDelta

type SupersessionReceipt 

type SupersessionReceipt struct {
	Version           int                       `json:"version"`
	Repository        string                    `json:"repository"`
	Task              string                    `json:"task"`
	Branch            string                    `json:"branch"`
	OriginalHead      string                    `json:"original_head"`
	Target            string                    `json:"target"`
	TargetHead        string                    `json:"target_head"`
	Replacements      []SupersessionReplacement `json:"replacements"`
	Residuals         []SupersessionResidual    `json:"residuals"`
	ResidualsComplete bool                      `json:"residuals_complete"`
	Approval          SupersessionApproval      `json:"approval"`
	// OriginalPR identifies the source pull request when this is a dependency
	// consolidation. A PR-scoped receipt opts into exact dependency proof;
	// generic worktree supersessions leave it empty.
	OriginalPR               string                        `json:"original_pr,omitempty"`
	OriginalPRNumber         int                           `json:"original_pr_number,omitempty"`
	OriginalPRRepository     string                        `json:"original_pr_repository,omitempty"`
	OriginalPRHead           string                        `json:"original_pr_head,omitempty"`
	DependencyDeltasComplete bool                          `json:"dependency_deltas_complete,omitempty"`
	DependencyDeltas         []SupersessionDependencyDelta `json:"dependency_deltas,omitempty"`
	// WorkflowAdoptions binds a newly introduced dependency-bearing workflow
	// to identical bytes already present in a reviewed replacement at target.
	// It is intentionally narrower than dependency PR evidence: it cannot
	// certify package manifests, lockfiles, or modified existing workflows.
	WorkflowAdoptions []SupersessionWorkflowAdoption `json:"workflow_adoptions,omitempty"`
}

SupersessionReceipt is the trusted-reviewer evidence required to retire a clean branch whose intent was split across replacement changes. It is an operator-supplied receipt, never an inference from CI, a closed PR, or patch/tree similarity.

func (SupersessionReceipt) DependencyAuditJSON 

func (receipt SupersessionReceipt) DependencyAuditJSON() ([]byte, error)

DependencyAuditJSON and DependencyAuditMarkdown are deterministic per-PR renderings. They sort a copy so receipt bytes remain immutable.

func (SupersessionReceipt) DependencyAuditMarkdown 

func (receipt SupersessionReceipt) DependencyAuditMarkdown() string

type SupersessionReplacement 

type SupersessionReplacement struct {
	Kind string `json:"kind"` // pr or commit
	Ref  string `json:"ref"`
	SHA  string `json:"sha,omitempty"`
}

SupersessionReplacement identifies the reviewed change that replaced an intended slice. A replacement may be a merged PR or an exact commit.

type SupersessionResidual 

type SupersessionResidual struct {
	Commit         string   `json:"commit"`
	Classification string   `json:"classification"` // replaced, obsolete, regressive, or cosmetic
	Reason         string   `json:"reason"`
	ReplacementRef string   `json:"replacement_ref,omitempty"`
	Paths          []string `json:"paths,omitempty"`
	Reviewed       bool     `json:"reviewed"`
}

SupersessionResidual classifies one commit reachable from the original branch and outside the exact target. Every such commit must appear exactly once, including commits whose intended slice was replaced elsewhere.

type SupersessionWorkflowAdoption 

type SupersessionWorkflowAdoption struct {
	Path           string `json:"path"`
	SourceSHA256   string `json:"source_sha256"`
	ReplacementSHA string `json:"replacement_sha"`
	Reviewed       bool   `json:"reviewed"`
}

SupersessionWorkflowAdoption records exact evidence that one newly added workflow file has already been reviewed and landed as part of a replacement.

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.