forge

Documentation

Overview

Package forge provides an abstraction layer between git-spice and the underlying forge (e.g. GitHub, GitLab, Bitbucket).

Index

• Variables
• func MatchRemoteURL(r *Registry, remoteURL string) (forge Forge, rid RepositoryID, ok bool)
• type AuthenticationToken
• type ChangeCommentID
• type ChangeID
• type ChangeMetadata
• type ChangeState
  • func (s ChangeState) GoString() string
  • func (s ChangeState) MarshalText() ([]byte, error)
  • func (s ChangeState) String() string
  • func (s *ChangeState) UnmarshalText(b []byte) error
• type ChangeTemplate
• type EditChangeOptions
• type FindChangeItem
• type FindChangesOptions
• type Forge
• type ListChangeCommentItem
• type ListChangeCommentsOptions
• type Registry
  • func (r *Registry) All() iter.Seq[Forge]
  • func (r *Registry) Lookup(id string) (Forge, bool)
  • func (r *Registry) Register(f Forge) (unregister func())
• type Repository
• type RepositoryID
• type SubmitChangeRequest
• type SubmitChangeResult

Variables

var ErrUnsubmittedBase = errors.New("base branch has not been submitted yet")

ErrUnsubmittedBase indicates that a change cannot be submitted because the base branch has not been pushed yet.

var ErrUnsupportedURL = errors.New("unsupported URL")

ErrUnsupportedURL indicates that the given remote URL does not match any registered forge.

Functions

func MatchRemoteURL

func MatchRemoteURL(r *Registry, remoteURL string) (forge Forge, rid RepositoryID, ok bool)

MatchRemoteURL attempts to match the given remote URL with a registered forge. Returns the matched forge, and information about the matched repository.

Types

type AuthenticationToken

type AuthenticationToken interface {
	// contains filtered or unexported methods
}

AuthenticationToken is a secret that results from a successful login. It will be persisted in a safe place, and re-used for future authentication with the forge.

Implementations must embed this interface.

type ChangeCommentID

type ChangeCommentID interface {
	String() string
}

ChangeCommentID is a unique identifier for a comment on a change.

type ChangeID

type ChangeID interface {
	String() string
}

ChangeID is a unique identifier for a change in a repository.

type ChangeMetadata

type ChangeMetadata interface {
	ForgeID() string

	// ChangeID is a human-readable identifier for the change.
	// This is presented to the user in the UI.
	ChangeID() ChangeID

	// NavigationCommentID is a comment left on the Change
	// that contains a visualization of the stack.
	NavigationCommentID() ChangeCommentID

	// SetNavigationCommentID sets the ID of the navigation comment
	// on the chnage metadata to persist it later.
	//
	// The ID may be nil to indicate that there is no navigation comment.
	SetNavigationCommentID(ChangeCommentID)
}

ChangeMetadata defines Forge-specific per-change metadata. This metadata is persisted to the state store alongside the branch state. It is used to track the relationship between a branch and its corresponding change in the forge.

The implementation is per-forge, and should contain enough information for the forge to uniquely identify a change within a repository.

The metadata must be JSON-serializable (as defined by methods on Forge).

type ChangeState

type ChangeState int

ChangeState is the current state of a change.

const (
	// ChangeOpen specifies that a change is open.
	ChangeOpen ChangeState = iota + 1

	// ChangeMerged specifies that a change has been merged.
	ChangeMerged

	// ChangeClosed specifies that a change has been closed.
	ChangeClosed
)

func (ChangeState) GoString

func (s ChangeState) GoString() string

GoString returns a Go-syntax representation of the change state.

func (ChangeState) MarshalText

func (s ChangeState) MarshalText() ([]byte, error)

MarshalText serialize the change state to text. This implements encoding.TextMarshaler.

func (ChangeState) String

func (s ChangeState) String() string

func (*ChangeState) UnmarshalText

func (s *ChangeState) UnmarshalText(b []byte) error

UnmarshalText parses the change state from text. This implements encoding.TextUnmarshaler.

type ChangeTemplate

type ChangeTemplate struct {
	// Filename is the name of the template file.
	//
	// This is NOT a path.
	Filename string

	// Body is the content of the template file.
	Body string
}

ChangeTemplate is a template for a new change proposal.

type EditChangeOptions

type EditChangeOptions struct {
	// Base specifies the name of the base branch.
	//
	// If unset, the base branch is not changed.
	Base string

	// Draft specifies whether the change should be marked as a draft.
	// If unset, the draft status is not changed.
	Draft *bool

	Labels []string
}

EditChangeOptions specifies options for an operation to edit an existing change.

type FindChangeItem

type FindChangeItem struct {
	// ID is a unique identifier for the change.
	ID ChangeID // required

	// URL is the web URL at which the change can be viewed.
	URL string // required

	// State is the current state of the change.
	State ChangeState // required

	// Subject is the title of the change.
	Subject string // required

	// HeadHash is the hash of the commit at the top of the change.
	HeadHash git.Hash // required

	// BaseName is the name of the base branch
	// that this change is proposed against.
	BaseName string // required

	// Draft is true if the change is not yet ready to be reviewed.
	Draft bool // required
}

FindChangeItem is a single result from searching for changes in the repository.

type FindChangesOptions

type FindChangesOptions struct {
	State ChangeState // 0 = all

	// Limit specifies the maximum number of changes to return.
	// Changes are sorted by most recently updated.
	// Defaults to 10.
	Limit int
}

FindChangesOptions specifies filtering options for searching for changes.

type Forge

type Forge interface {
	// ID reports a unique identifier for the forge, e.g. "github".
	ID() string // TODO: Rename to "slug" or "name" as that's more correct

	// CLIPlugin returns a Kong plugin for this Forge.
	//
	// This will be installed into the application to provide
	// additional Forge-specific flags or environment variable overrides.
	//
	// Return nil if the forge does not require any extra CLI flags.
	CLIPlugin() any

	// ParseRemoteURL extracts information about a Forge-hosted repository
	// from the given remote URL, and returns a [RepositoryID] identifying it.
	//
	// Returns ErrUnsupportedURL if the remote URL does not match
	// this forge.
	//
	// This operation should not make any network requests,
	//
	// For example, this would take "https://github.com/foo/bar.git"
	// and return a GitHub RepositoryID for the repository "foo/bar".
	ParseRemoteURL(remoteURL string) (RepositoryID, error)

	// OpenRepository opens the remote repository that the given ID points to.
	OpenRepository(ctx context.Context, tok AuthenticationToken, repo RepositoryID) (Repository, error)

	// ChangeTemplatePaths reports the case-insensitive paths at which
	// it's possible to define change templates in the repository.
	ChangeTemplatePaths() []string

	// MarshalChangeID serializes the given change ID into a valid JSON blob.
	MarshalChangeID(ChangeID) (json.RawMessage, error)

	// UnmarshalChangeID deserializes the given JSON blob into a change ID.
	UnmarshalChangeID(json.RawMessage) (ChangeID, error)

	// MarshalChangeMetadata serializes the given change metadata
	// into a valid JSON blob.
	MarshalChangeMetadata(ChangeMetadata) (json.RawMessage, error)

	// UnmarshalChangeMetadata deserializes the given JSON blob
	// into change metadata.
	UnmarshalChangeMetadata(json.RawMessage) (ChangeMetadata, error)

	// AuthenticationFlow runs the authentication flow for the forge.
	// This may prompt the user, perform network requests, etc.
	//
	// The implementation should return a secret that the Forge
	// can serialize and store for future use.
	AuthenticationFlow(ctx context.Context, view ui.View) (AuthenticationToken, error)

	// SaveAuthenticationToken saves the given authentication token
	// to the secret stash.
	SaveAuthenticationToken(secret.Stash, AuthenticationToken) error

	// LoadAuthenticationToken loads the authentication token
	// from the secret stash.
	LoadAuthenticationToken(secret.Stash) (AuthenticationToken, error)

	// ClearAuthenticationToken removes the authentication token
	// from the secret stash.
	ClearAuthenticationToken(secret.Stash) error
}

Forge is a forge that hosts Git repositories.

type ListChangeCommentItem

type ListChangeCommentItem struct {
	ID   ChangeCommentID
	Body string
}

ListChangeCommentItem is a single result from listing comments on a change.

type ListChangeCommentsOptions

type ListChangeCommentsOptions struct {
	// BodyMatchesAll specifies zero or more regular expressions
	// that must all match the comment body.
	//
	// If empty, all comments are returned.
	BodyMatchesAll []*regexp.Regexp

	// CanUpdate specifies whether only comments that can be updated
	// by the current user should be returned.
	//
	// If false, all comments are returned.
	CanUpdate bool
}

ListChangeCommentsOptions specifies options for filtering and limiting comments listed by ListChangeComments.

Conditions specified here are combined with AND.

type Registry

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

Registry is a collection of known code forges.

func (*Registry) All

func (r *Registry) All() iter.Seq[Forge]

All returns an iterator over items in the Forge in an unspecified order.

func (*Registry) Lookup

func (r *Registry) Lookup(id string) (Forge, bool)

Lookup searches for a registered Forge by ID. It returns false if a forge with that ID is not known.

func (*Registry) Register

func (r *Registry) Register(f Forge) (unregister func())

Register registers a Forge with the Registry. The Forge may be unregistered by calling the returned function.

type Repository

type Repository interface {
	Forge() Forge

	// SubmitChange creates a new change request in the repository.
	//
	// Special errors:
	//
	//  - ErrUnsubmittedBase indicates that the change cannot be submitted
	//    because the base branch has not been pushed to the remote yet.
	SubmitChange(ctx context.Context, req SubmitChangeRequest) (SubmitChangeResult, error)

	EditChange(ctx context.Context, id ChangeID, opts EditChangeOptions) error
	FindChangesByBranch(ctx context.Context, branch string, opts FindChangesOptions) ([]*FindChangeItem, error)
	FindChangeByID(ctx context.Context, id ChangeID) (*FindChangeItem, error)
	ChangesStates(ctx context.Context, ids []ChangeID) ([]ChangeState, error)

	// Post and update comments on changes.
	PostChangeComment(context.Context, ChangeID, string) (ChangeCommentID, error)
	UpdateChangeComment(context.Context, ChangeCommentID, string) error

	// List comments on a CR, optionally filtered per the given options.
	ListChangeComments(context.Context, ChangeID, *ListChangeCommentsOptions) iter.Seq2[*ListChangeCommentItem, error]

	// NewChangeMetadata builds a ChangeMetadata for the given change ID.
	//
	// This may perform network requests to fetch additional information
	// if necessary.
	NewChangeMetadata(ctx context.Context, id ChangeID) (ChangeMetadata, error)

	// ListChangeTemplates returns templates defined in the repository
	// for new change proposals.
	//
	// Returns an empty list if no templates are found.
	ListChangeTemplates(context.Context) ([]*ChangeTemplate, error)
}

Repository is a Git repository hosted on a forge.

type RepositoryID

type RepositoryID interface {
	// String reports a human-readable name for the repository,
	// e.g. "foo/bar" for GitHub.
	String() string

	// ChangeURL returns the web URL for the given change ID hosted on the forge
	// in this repository.
	ChangeURL(changeID ChangeID) string
}

RepositoryID is a unique identifier for a repository hosted on a Forge.

It is cheap to calculate from the remote URL of the repository, without performing any network requests.

type SubmitChangeRequest

type SubmitChangeRequest struct {
	// Subject is the title of the change.
	Subject string // required

	// Body is the description of the change.
	Body string

	// Base is the name of the base branch
	// that this change is proposed against.
	Base string // required

	// Head is the name of the branch containing the change.
	//
	// This must have already been pushed to the remote.
	Head string // required

	// Draft specifies whether the change should be marked as a draft.
	Draft bool

	// Labels are optional labels to apply to the change.
	Labels []string
}

SubmitChangeRequest is a request to submit a new change in a repository. The change must have already been pushed to the remote.

type SubmitChangeResult

type SubmitChangeResult struct {
	ID  ChangeID
	URL string
}

SubmitChangeResult is the result of creating a new change in a repository.