taskgraph

type BindStatus int

type Binder interface {
	// Store adds bindings to the binder that can be retrieved with Get().
	Store(...Binding) error

	// Returns whether the given IDs have all been bound (as Present or Absent).
	Has(...ID) bool

	// Get a previously stored binding. If no binding with the given ID has yet been stored, a binding with Status() = Pending is generated.
	Get(ID) Binding

	// GetAll returns all stored bindings. This is typically used only for tests.
	GetAll() []Binding
}

type Binding interface {
	// ID returns the ID of the key which is bound by this Binding.
	ID() ID

	// Status returns the status of this binding.
	Status() BindStatus

	// Value returns the value bound to the key. This should only be called if Status() returns Present.
	Value() any

	// Value returns the error bound to the key. This should only be called if Status() returns Absent.
	Error() error
}

type Condition interface {
	// Evaluate should return whether the conditional task should be executed.
	Evaluate(ctx context.Context, b Binder) (bool, error)
	// Deps should return the IDs of the keys used by the Evaluate function.
	Deps() []ID
}

type ConditionAnd []ReadOnlyKey[bool]

type ConditionOr []ReadOnlyKey[bool]

type Conditional struct {
	NamePrefix      string
	Wrapped         TaskSet
	Condition       Condition
	DefaultBindings []Binding
	// contains filtered or unexported fields
}

type Graph interface {
	// Check whether the given input bindings are sufficient to run the graph.
	//
	// This is intended to be run by a genrule at build time to assert that all keys required by tasks
	// in the graph are provided either as an input or by some other task in the graph. It also checks
	// that there are no duplicate inputs.
	Check(inputs ...Binding) error

	// Run executes the task graph with the given inputs, returning a Binder containing the bound
	// values from all tasks (but not any of the input bindings).
	//
	// It is advisable to set a timeout on the passed context, although it is up to the individual
	// tasks to listen for context cancellation.
	Run(ctx context.Context, inputs ...Binding) (Binder, error)

	// AsTask produces a Task which runs this Graph in full to allow composition of graphs. The task
	// depends on all keys which are required by any task within it and not provided by any task
	// within it. The task provides only the key IDs passed to this method; and only their bindings
	// will be available in the result of any graph the task is included in (any bindings produced by
	// tasks within this graph whose IDs were not passed to this method will be suppressed).
	//
	// Bindings for the exposed keys are added to the binder of the parent task as soon as they are
	// generated by tasks within this graph, which means that tasks outside this graph which depend on
	// the exposed keys can start running as soon as the producing task completes, rather than waiting
	// for this entire task to complete.
	AsTask(exposeKeys ...ID) (Task, error)

	// Graphviz produces a graphviz representation of the graph, with the tasks as nodes and the
	// dependencies as edges. This output can be pased into tools like
	// https://dreampuf.github.io/GraphvizOnline or https://dot-to-ascii.ggerganov.com/ to view the
	// structure of the graph.
	//
	// The includeInputs parameter controls whether graph inputs are included in the output; including
	// them tends to make the graph significantly more complicated and harder for the graphviz engine
	// to lay out in a useful way.
	Graphviz(includeInputs bool) string
}

type GraphOption func(opts *GraphOptions) error

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

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

type Key[T any] interface {
	ReadOnlyKey[T]

	// Bind this key to the given value.
	Bind(val T) Binding

	// Bind this key as absent (see the comment on the Absent BindStatus). This is equivalent to
	// calling BindError(ErrIsAbsent)
	BindAbsent() Binding

	// Bind this key as absent with a specific error (see the comment on the Absent BindStatus).
	BindError(err error) Binding
}

type Maybe[T any] struct {
	// contains filtered or unexported fields
}

type MaybeStatus interface {
	Error() error
	Present() bool
}

type ReadOnlyKey[T any] interface {
	// ID returns the type-parameter-less ID which identifies the key.
	ID() ID

	// Location returns the file and line where this key was defined.
	Location() string

	// Get retrieves the value for this key from the binder.
	Get(Binder) (T, error)
}

type Reflect[T any] struct {
	// Name of the built task
	Name string

	// The key which Fn produces a value for
	ResultKey Key[T]

	// The task function. This function should:
	//  * Optionally take a context.Context as the first argument
	//  * Take one argument for each entry in Depends whose type matches the type parameter of the Key
	//  * Return T or (T, error)
	Fn any

	// A list of Key[X], where X may be different for each key (which is why this is []any). These
	// keys are used to provide the arguments to Fn. Each key is expected to be bound as present when
	// the Task is run; it is up to the user to either wrap the built task in a Conditional() or to
	// use Optional() keys where necessary.
	Depends []any
	// contains filtered or unexported fields
}

type ReflectMulti struct {
	// Name of the built task
	Name string

	// The task function. This function should:
	//  * Optionally take a context.Context as the first argument
	//  * Take one argument for each entry in Depends whose type matches the type parameter of the Key
	//  * Return []Binding or ([]Binding, error)
	Fn any

	// The list of key IDs which the task provides.
	Provides []ID

	// A list of Key[X], where X may be different for each key (which is why this is []any). These
	// keys are used to provide the arguments to Fn. Each key is expected to be bound as present when
	// the Task is run; it is up to the user to either wrap the built task in a Conditional() or to
	// use Optional() keys where necessary.
	Depends []any
	// contains filtered or unexported fields
}

type Task interface {
	// A task can be considered to be a singleton set.
	TaskSet

	// Name returns the name of the task given when the task was created.
	Name() string
	// Depends returns the IDs of the keys on which this task depends (i.e. the keys which must be
	// provided as a graph input or by another task before this task can be executed)
	Depends() []ID
	// Provides returns the IDs of the keys for which this task provides bindings (i.e. the list of
	// Bindings returned by Execute must exactly match this list aside from ordering).
	Provides() []ID
	// Execute performs the unit of work for this task, consuming its dependencies from the given
	// Binder, and returning Bindings for each key the task has declared that it provides. Any error
	// returned from Execute() will terminate the processing of the entire graph.
	Execute(context.Context, Binder) ([]Binding, error)
	// Location returns the file and line where this task was defined.
	Location() string
}

type TaskSet interface {
	Tasks() []Task
}