forge package - github.com/herbhall/samverk/internal/forge

Documentation ¶

Overview ¶

Package forge provides the IssueTracker interface and implementations for GitHub, Gitea, and GitLab.

The interface abstracts git forge operations so the dispatcher, agents, and MCP server work identically regardless of the underlying platform. See docs/forge-compatibility.md for the API surface comparison.

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrNotSupported = errors.New("forge: operation not supported on this platform")

ErrNotSupported is returned by forge operations that are not available on the current platform (e.g. code search on Gitea). Callers can check with errors.Is to present a user-friendly "not available on this forge" message.

Functions ¶

This section is empty.

Types ¶

type Branch ¶

type Branch struct {
	Name       string    `json:"name"`
	LastCommit string    `json:"last_commit"`
	UpdatedAt  time.Time `json:"updated_at"`
}

Branch represents a git branch in the repository.

type Check ¶ added in v0.1.6

type Check struct {
	Name   string      `json:"name"`
	Status CheckStatus `json:"status"`
}

Check represents a single CI status check on a pull request.

type CheckStatus ¶ added in v0.1.6

type CheckStatus string

CheckStatus represents the state of a CI check.

const (
	CheckStatusSuccess CheckStatus = "success"
	CheckStatusFailure CheckStatus = "failure"
	CheckStatusPending CheckStatus = "pending"
)

type Comment ¶

type Comment struct {
	ID        int64
	Body      string
	Author    string
	CreatedAt time.Time
}

Comment represents a single comment on an issue.

type Commit ¶

type Commit struct {
	SHA     string    `json:"sha"`
	Message string    `json:"message"`
	Author  string    `json:"author"`
	Date    time.Time `json:"date"`
}

Commit represents a single commit in the repository log.

type CreateIssueRequest ¶

type CreateIssueRequest struct {
	Title     string
	Body      string
	Labels    []string
	Assignees []string
}

CreateIssueRequest contains the fields needed to create a new issue.

type CreatePRRequest ¶

type CreatePRRequest struct {
	Title string `json:"title"`
	Body  string `json:"body"`
	Head  string `json:"head"`
	Base  string `json:"base"`
}

CreatePRRequest contains the fields needed to create a pull request.

type Event ¶

type Event struct {
	Type          EventType
	IssueNumber   int
	Issue         *Issue
	Comment       *Comment
	Label         string
	Assignee      string
	IsPullRequest bool
}

Event represents a change detected on the forge.

type EventType ¶

type EventType string

EventType identifies what changed on the forge.

const (
	EventIssueOpened    EventType = "issue.opened"
	EventIssueClosed    EventType = "issue.closed"
	EventIssueLabeled   EventType = "issue.labeled"
	EventIssueAssigned  EventType = "issue.assigned"
	EventIssueCommented EventType = "issue.commented"
	EventIssueEdited    EventType = "issue.edited"
)

type FileEntry ¶

type FileEntry struct {
	Name string `json:"name"`
	Path string `json:"path"`
	Type string `json:"type"` // "file", "dir", "symlink"
	Size int    `json:"size"`
}

FileEntry represents a single file or directory in the repository tree.

type Issue ¶

type Issue struct {
	Number        int
	Title         string
	Body          string
	State         State
	Labels        []string
	Assignees     []string
	IsPullRequest bool
	CreatedAt     time.Time
	UpdatedAt     time.Time
	ClosedAt      *time.Time
}

Issue represents a forge issue in Samverk's domain.

type IssueTracker ¶

type IssueTracker interface {
	// Issues
	CreateIssue(ctx context.Context, req *CreateIssueRequest) (*Issue, error)
	GetIssue(ctx context.Context, number int) (*Issue, error)
	UpdateIssue(ctx context.Context, number int, req *UpdateIssueRequest) (*Issue, error)
	ListIssues(ctx context.Context, opts *ListOptions) ([]*Issue, error)

	// Comments
	AddComment(ctx context.Context, number int, body string) (*Comment, error)
	ListComments(ctx context.Context, number int) ([]*Comment, error)

	// Labels
	SetLabels(ctx context.Context, number int, labels []string) error
	AddLabel(ctx context.Context, number int, label string) error
	RemoveLabel(ctx context.Context, number int, label string) error

	// Assignment
	Assign(ctx context.Context, number int, assignee string) error
	Unassign(ctx context.Context, number int, assignee string) error

	// Event watching (polling-based initially; webhook support planned via issue #8)
	Watch(ctx context.Context, handler func(Event)) error
}

IssueTracker is the platform-agnostic interface for git forge issue operations. Implementations exist for GitHub (internal/forge/github) and Gitea (planned).

type ListOptions ¶

type ListOptions struct {
	State    State
	Labels   []string
	Assignee string
	Page     int
	PerPage  int
}

ListOptions controls filtering and pagination for issue listing.

type ListPROptions ¶

type ListPROptions struct {
	State   State  `json:"state,omitempty"`
	Head    string `json:"head,omitempty"`
	Base    string `json:"base,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

ListPROptions controls filtering for pull request listing.

type MergeMethod ¶

type MergeMethod string

MergeMethod specifies how a pull request should be merged.

const (
	MergeMethodMerge  MergeMethod = "merge"
	MergeMethodSquash MergeMethod = "squash"
	MergeMethodRebase MergeMethod = "rebase"
)

type PullRequest ¶

type PullRequest struct {
	Number    int       `json:"number"`
	Title     string    `json:"title"`
	Body      string    `json:"body"`
	State     State     `json:"state"`
	Head      string    `json:"head"`
	Base      string    `json:"base"`
	Author    string    `json:"author"`
	Mergeable bool      `json:"mergeable"`
	Draft     bool      `json:"draft"`
	Labels    []string  `json:"labels"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

PullRequest represents a pull request in Samverk's domain.

type PullRequestManager ¶

type PullRequestManager interface {
	CreatePullRequest(ctx context.Context, req *CreatePRRequest) (*PullRequest, error)
	GetPullRequest(ctx context.Context, number int) (*PullRequest, error)
	ListPullRequests(ctx context.Context, opts *ListPROptions) ([]*PullRequest, error)
	MergePullRequest(ctx context.Context, number int, method MergeMethod, commitMsg string) error
	GetPRChecks(ctx context.Context, number int) ([]Check, error)
	ListReviewComments(ctx context.Context, prNumber int) ([]ReviewComment, error)
}

PullRequestManager provides pull request operations on a git forge.

type RepoReader ¶

type RepoReader interface {
	ListFiles(ctx context.Context, path, ref string) ([]FileEntry, error)
	ReadFile(ctx context.Context, path, ref string) ([]byte, error)
	GetDiff(ctx context.Context, base, head string) (string, error)
	ListBranches(ctx context.Context) ([]Branch, error)
	GetCommitLog(ctx context.Context, branch string, limit int) ([]Commit, error)
	SearchCode(ctx context.Context, query string) ([]SearchResult, error)
}

RepoReader provides read-only access to a git repository's contents.

type RepoWriter ¶ added in v0.1.5

type RepoWriter interface {
	// CreateBranch creates a new branch from the default branch HEAD.
	CreateBranch(ctx context.Context, name string) error

	// CreateOrUpdateFile creates or updates a file on the given branch.
	CreateOrUpdateFile(ctx context.Context, branch, path, content, message string) error
}

RepoWriter provides write access to a git repository's contents.

type ReviewComment ¶ added in v0.1.8

type ReviewComment struct {
	Author    string    `json:"author"`
	Body      string    `json:"body"`
	Path      string    `json:"path"`
	StartLine int       `json:"start_line"`
	EndLine   int       `json:"end_line"`
	Resolved  bool      `json:"resolved"`
	CreatedAt time.Time `json:"created_at"`
}

ReviewComment represents a review comment on a pull request.

type SearchResult ¶

type SearchResult struct {
	Path       string `json:"path"`
	LineNumber int    `json:"line_number"`
	Line       string `json:"line"`
}

SearchResult represents a single code search match.

type State ¶

type State string

State represents the open/closed state of an issue.

const (
	StateOpen   State = "open"
	StateClosed State = "closed"
)

type UpdateIssueRequest ¶

type UpdateIssueRequest struct {
	Title *string
	Body  *string
	State *State
}

UpdateIssueRequest contains the fields to update on an existing issue. Nil pointer fields are left unchanged.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
gitea Package gitea implements the forge.IssueTracker interface for Gitea using the official Gitea Go SDK.	Package gitea implements the forge.IssueTracker interface for Gitea using the official Gitea Go SDK.
github Package github implements the forge.IssueTracker interface for GitHub using the google/go-github SDK.	Package github implements the forge.IssueTracker interface for GitHub using the google/go-github SDK.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL