engine

type FollowOptions struct {
	Repo, Forge, Base string
	// Gardening: the roles' gardening merge requests too (ADR-0034, amended).
	Gardening bool
	// People: each person's merge request into Base, left in conflict with
	// it only on lines workline writes, gets Base merged in, those lines
	// settled (the documentalist's `update-branches: conflicts`, ADR-0041).
	People bool
	// IsDoc says whether a file is one of the docs, whose header workline
	// writes; nil, none is.
	IsDoc func(path string) bool
	// Release says whether a branch is a release tool's: its merge request
	// is a bot's, rebuilt by the tool.
	Release func(branch string) bool
	// Derive says whether the docs' derived blocks, in the tree at dir,
	// read what the documentalist's `derive` commands give there: a merge
	// request regenerating them is `derived` at `normal` only then; nil,
	// never.
	Derive func(dir string, docs map[string]string) bool
	// Merge is the project's merge policy, its level (`merge: {autonomy:
	// cautious}`); "" none: no merge request's auto-merge is touched
	// (ADR-0042, merge.go).
	Merge string
	// Verdict is a file holding the line's verdict on a merge request's
	// head (`workline route --verdict`), kept first, for the merge policy;
	// with VerdictOnly, nothing else is done: a job of its own keeps it,
	// which no newer run cancels (GitHub's concurrency).
	Verdict     string
	VerdictOnly bool
}

type FromMergeRequest struct {
	Repo     string // its checkout of the base: the project's settings are read there
	RolesDir string // its engine's roles
	Forge    string // its forge
	ID       int    // the merge request whose run it applies
	Head     string // the commit that run judged, as the forge's event names it
}

type HeadVerdict struct {
	Head     string            `json:"head"`
	Status   string            `json:"status"`
	Steps    []StepStatus      `json:"steps,omitempty"`
	Findings []verdict.Finding `json:"findings,omitempty"`
}

type Options struct {
	Repo      string            // repository the role works on
	RolesDir  string            // folder holding the roles
	Role      string            // role name
	Event     string            // event the role runs on
	AI        string            // agent spec, see agent.Parse; empty = the project's setting
	DefaultAI string            // used when neither AI nor the project says (the user's own default)
	Inputs    map[string]string // name -> value, written to in/input/<name>
	Targets   map[string]string // name -> file an intention writes back to (e.g. the hook's message file)

	Forge  string        // forge spec, see forge.Open; empty = the project's `forge` setting
	Target *forge.Target // the issue or merge request comments and labels go on
	// Branch is the one the targeted merge request comes from, when the job
	// knows it without the forge (a CI job without the forge's token); else
	// the forge is asked. Its branch tells a release tool's (ADR-0017).
	Branch string
	Scope  []string // paths the task is about; a patch outside is refused
	// NoApply stops after judging: the proposals and what apply needs are kept
	// in the run folder, for `workline apply` in another job holding the token.
	NoApply bool
	// OpenMergeRequest puts what the patches wrote on a branch of the role's,
	// and opens a merge request for it, or updates the one open (ADR-0006).
	OpenMergeRequest bool
	// PushToMergeRequest commits what the patches wrote to the branch of the
	// merge request the run targets; from a fork, the diff goes in a comment.
	PushToMergeRequest bool

	// TamperBeforeApply changes the prepared input between propose and apply.
	// It exists only for the conformance test that proves apply notices.
	TamperBeforeApply bool
}

type Result struct {
	Status     string            `json:"status"`
	Summary    string            `json:"summary,omitempty"`
	Findings   []verdict.Finding `json:"findings,omitempty"`
	AgentCalls int               `json:"agent-calls"`
	Calls      []agent.Call      `json:"calls,omitempty"` // each call: what was asked, what answered
	Applied    []string          `json:"applied"`
	Refused    []string          `json:"refused"`
	Handoffs   []any             `json:"handoffs,omitempty"` // next roles asked for; routing runs them
	Notes      []string          `json:"notes,omitempty"`    // what the agent left for a person: a round's notes each
	RunDir     string            `json:"run-dir"`
	ToApply    bool              `json:"to-apply,omitempty"` // judged with NoApply: `workline apply` still has work
	// Pending: the run folders `workline apply` is given, one a round, when
	// a run judged with NoApply went round, each round a merge request of
	// its own (ADR-0013's amendment).
	Pending      []string `json:"pending,omitempty"`
	MergeRequest int      `json:"merge-request,omitempty"` // the merge request the patches went to
	// Issues and Waiting are a role keeping a backlog's links, for the
	// job's summary (ADR-0038): the address of the forge's issues, an
	// issue's number after it making its page; the saved filter of what
	// waits on a person, workline:proposed.
	Issues  string `json:"issues,omitempty"`
	Waiting string `json:"waiting,omitempty"`
	// contains filtered or unexported fields
}

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