apply

package
v0.21.4 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package apply reads what a commit asserted about a forge object and carries it there.

This is the reading half of spec 0012: the `Updates:` trailer, the target it names, and the statement it makes. Applying a statement needs a forge that can write a comment, which go/forge does not expose yet (go/forge#23), so the writing half is a narrow interface here and nothing implements it in this package.

Nothing in here infers anything. A commit says what happened to a forge object or the object is left alone, which is spec 0012 D1 and the reason this package has no history reading of its own.

Index

Constants

View Source
const Trailer = "updates"

Trailer is the key a commit uses to address a forge object. One key for every kind of target, because a trailer block is read by people and a reader should not have to learn a spelling per kind (spec 0012 D2).

Variables

View Source
var (
	// ErrNoFrontmatter reports a page that opens with no frontmatter block.
	ErrNoFrontmatter = errors.New("apply: page has no frontmatter")

	// ErrNoField reports a frontmatter block that does not carry the field a
	// statement names. The field is not created: a page whose schema does not
	// have it is a page this statement was not written for (spec 0012 D3).
	ErrNoField = errors.New("apply: frontmatter has no such field")
)
View Source
var ErrBadTarget = errors.New("apply: bad target")

ErrBadTarget reports a target this package cannot address.

View Source
var ErrNothingToDo = errors.New("apply: no commit in the span asserts anything")

ErrNothingToDo reports a span whose commits asserted nothing. Not an error from Do, which returns no results happily; it exists for a caller that wants to say so.

View Source
var ErrUnknownKeyword = errors.New("apply: unknown keyword")

ErrUnknownKeyword reports a statement this package will not act on.

Functions

func Failures added in v0.11.0

func Failures(results []Result) int

Failures counts the results a caller can do something about: the forge was asked and refused.

Separate from Problems because the two answer different questions. A person reading the log wants to know that something was skipped; a pipeline deciding whether the run succeeded must not, since a forge that cannot carry an instruction would report the same unclearable problem on every merge (spec 0022 D1).

func Field

func Field(content, field string) (string, bool)

Field reads one frontmatter field's value, for a report line about a page that is already where the statement wanted it.

func Problems

func Problems(results []Result) int

Problems reports whether any result needs a person's attention, which is what a caller prints a summary line from.

It counts Skipped as well as Failed, so it is the wrong thing to gate on: Skipped is a forge without the capability, which no change to a repository can clear. Failures is what a caller may act on (spec 0022 D1).

func SetField

func SetField(content, field, value string) (string, bool, error)

SetField sets one frontmatter field and returns the page, whether the value changed, and any refusal.

Line-based, deliberately, rather than a YAML round trip: re-serialising would reformat a page a person wrote and reorder what they ordered, and the diff would be the whole file. Only the one line moves.

Types

type Applier

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

Applier carries statements to forge objects.

Each capability is optional and separately absent: a forge with no wiki, or no issue tracker, reports the instructions it cannot carry and applies the rest. That is `forge.As` at the command layer, and a nil field here.

func New

func New(issues IssueCommenter, mrs MergeRequestCommenter, wikis Wikis) *Applier

New builds an Applier. Any of the three may be nil, meaning the forge does not offer it.

func (*Applier) Do

func (a *Applier) Do(ctx context.Context, req Request) ([]Result, error)

Do applies every instruction and returns one result each, in order.

It returns an error only when it could not start. A refusal against a single target is a result, not an error, because by the time this runs the merge has happened and a red pipeline over an annotation is worse signal than a yellow one (spec 0012 D5).

A comment is posted with the instruction's marker as go/forge's idempotency key, so the provider finds an existing one and returns it rather than posting twice. That guarantee is the provider's and its result is not distinguishable from a fresh post, so a comment reports Applied either way; only a wiki field, which this package reads before writing, can report Unchanged.

type Commit

type Commit struct {
	SHA  string
	Body string
}

Commit is the minimum this package needs. Not policy.Commit: nothing here decides a version, and a package that reads prose should not depend on the one that decides releases.

type Instruction

type Instruction struct {
	// SHA is the commit that asserted it, which is what the idempotence
	// marker names (spec 0012 D4).
	SHA string

	Target    Target
	Statement Statement

	// Raw is the trailer's value as written, for a report line about a
	// trailer this package could not read.
	Raw string

	// Err is why this trailer will not be applied, or nil. A refusal is
	// carried rather than returned, because one unreadable trailer must not
	// stop the others (spec 0012 D5).
	Err error
}

Instruction is one `Updates:` trailer, resolved.

func Collect

func Collect(commits []Commit) []Instruction

Collect reads every `Updates:` trailer across a span of commits, oldest first as the caller supplies them, and resolves each into an instruction.

Every trailer produces an instruction, including one this package cannot read: a malformed target is a thing a person wrote and meant, so it is reported rather than dropped, which is the difference between a quiet tool and a silent one.

func (Instruction) Key

func (i Instruction) Key() string

Key identifies this assertion to the forge's at-most-once check: the commit that made it and the object it was about, so one commit updating two objects posts to both, and the same commit twice posts once.

func (Instruction) Readable

func (i Instruction) Readable() bool

Readable reports whether this instruction can be applied.

type IssueCommenter

type IssueCommenter interface {
	CreateIssueComment(
		ctx context.Context, owner, repo string, number int, draft forge.CommentDraft,
	) (forge.Comment, error)
}

IssueCommenter posts a comment on an issue. The method set is go/forge's capability of the same name, so a provider satisfies this directly.

type Keyword

type Keyword string

Keyword is what a commit says about a target. A small closed vocabulary rather than free text, because the same statement has to mean something on a tracker object (a comment) and on a wiki page (a field value), and because a word the tool does not know must be refused rather than guessed at (spec 0012 D11).

const (
	// Shipped says the work reached a release.
	Shipped Keyword = "shipped"

	// Implemented says a record's work is done, which on a wiki page is the
	// status vocabulary's own word.
	Implemented Keyword = "implemented"
)

type Kind

type Kind string

Kind is what sort of forge object a target names.

const (
	// Issue is `#123` or `project#123`.
	Issue Kind = "issue"

	// MergeRequest is `!45` or `project!45`. A pull request is the same thing
	// under the other name, as it is throughout colophon.
	MergeRequest Kind = "merge request"

	// Wiki is a path to a wiki page, `project/wikis/specs/0079-thing`.
	Wiki Kind = "wiki page"
)

type MergeRequestCommenter

type MergeRequestCommenter interface {
	Comment(
		ctx context.Context, owner, repo string, number int, draft forge.CommentDraft,
	) (forge.Comment, error)
}

MergeRequestCommenter posts a comment on a merge or pull request.

type Request

type Request struct {
	// Owner and Repo are the repository the commits are in, and the default
	// project for a target that names none (spec 0012 D7).
	Owner string
	Repo  string

	Instructions []Instruction

	// Message is the commit message a wiki edit is recorded under.
	Message string
}

Request is one run of the verb.

type Result

type Result struct {
	Instruction Instruction
	Status      Status

	// Detail is the reason, for every status but Applied.
	Detail string
}

Result is one instruction's outcome.

type Statement

type Statement struct {
	Keyword Keyword

	// Text is whatever followed the keyword, verbatim and optional. It is
	// shown to a reader on a tracker object and ignored on a wiki page, where
	// there is nowhere to put it (spec 0012 D11).
	Text string
}

Statement is what a commit said about its target.

func ParseStatement

func ParseStatement(s string) (Statement, error)

ParseStatement reads the keyword and the optional text after it.

func (Statement) Comment

func (s Statement) Comment() string

Comment is the body this statement writes on a tracker object: the keyword's sentence, then whatever the commit added.

func (Statement) Field

func (s Statement) Field() (field, value string)

Field is the wiki frontmatter field this statement sets, and its value.

type Status

type Status string

Status is what became of one instruction.

const (
	// Applied: the forge was written to.
	Applied Status = "applied"

	// Unchanged: the target already said what the statement says. Only a wiki
	// field can report this; a comment's at-most-once is the provider's
	// promise and is not visible to a caller (see the note on Do).
	Unchanged Status = "unchanged"

	// Skipped: nothing was attempted, and Detail says why. An unreadable
	// trailer or a forge that cannot do this.
	Skipped Status = "skipped"

	// Failed: it was attempted and the forge refused. Detail says why, and
	// the run continues (spec 0012 D5).
	Failed Status = "failed"
)

type Target

type Target struct {
	Kind Kind

	// Project is empty when the trailer named none, which means the
	// repository the commit is in (spec 0012 D7).
	Project string

	// Number identifies an issue or a merge request; Path identifies a wiki
	// page. Exactly one is set.
	Number int
	Path   string
}

Target is one forge object a commit named.

func ParseTarget

func ParseTarget(s string) (Target, error)

ParseTarget reads the target at the head of a trailer value.

The project is optional and defaults to the commit's own repository, since a commit finishing a ticket in the same project is the common case and naming it every time is noise. A cross-project target is ordinary in this estate and is why the token matters (spec 0012 D7).

func (Target) String

func (t Target) String() string

String renders a target the way a trailer writes it, which is what the report prints.

type Wikis

type Wikis interface {
	GetWikiPage(ctx context.Context, owner, repo, path string, maxBytes int64) (forge.WikiPage, error)
	UpdateWikiPage(ctx context.Context, owner, repo string, page forge.WikiPage, message string) error
}

Wikis reads and writes a project's wiki pages.

Jump to

Keyboard shortcuts

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