gen

type Artifact struct {
	// Path is relative to the generator's output directory.
	Path string
	// Content is the complete file.
	Content []byte
	Mode    WriteMode
	// Perm defaults to 0644 when zero.
	Perm fs.FileMode
}

type Delta struct {
	Generator string
	Path      string
	Status    Status
	// Reason explains a conflict.
	Reason string
	// contains filtered or unexported fields
}

type DiffOptions struct {
	// Partial says some of the configured generators were held back, as --only
	// does.
	//
	// Staleness is relative to the run. A generator that did not run still owns
	// every file it wrote, and calling those leftovers would turn a narrow
	// regeneration into a proposal to delete most of the project. Which
	// generators ran is read from the results; that a generator was held back
	// is the one thing the results cannot say, because a generator nobody asked
	// leaves nothing behind to be missing from.
	Partial bool
}

type Entry struct {
	// Path is relative to the project root, in slash form, so a manifest
	// committed on one machine reads correctly on another.
	Path      string `json:"path"`
	Generator string `json:"generator"`
	Mode      string `json:"mode"`
	SHA256    string `json:"sha256"`
}

type Generator interface {
	// Name is the registry key, and what rig.yaml refers to.
	Name() string
	// Description is one line, shown by `rig generators`.
	Description() string
	// Version changes when the output format changes, so a stale manifest can
	// be recognized as stale.
	Version() string

	// Generate must be pure: the same document and options must always produce
	// byte-identical artifacts. No filesystem, no clock, no network, and no
	// iteration over a map without sorting it first.
	//
	// Whatever the output format can say about a field, it says with the
	// document's own words: ir.Field.Description is the single copy of the
	// human-readable text, and an output that has somewhere to put one — a doc
	// comment, an OpenAPI description, a JSDoc block — puts that one there
	// rather than a paraphrase of it.
	Generate(ctx context.Context, doc *ir.Document, opts Options) ([]Artifact, error)
}

type Manifest struct {
	// Version is the manifest format, not the tool's.
	Version int `json:"version"`
	// IRHash identifies the document the recorded files were generated from.
	IRHash string `json:"ir_hash,omitempty"`
	// Generators maps a generator name to the version that last ran.
	Generators map[string]string `json:"generators,omitempty"`
	// Files is every file rig wrote, ordered by path.
	Files []Entry `json:"files"`
}

type Options struct {
	// OutDir is where the artifacts go, resolved to an absolute path.
	OutDir string
	// Root is the project root.
	//
	// Almost everything a generator writes belongs under OutDir. The exception
	// is a hand-owned scaffold, which belongs where the developer works rather
	// than beside the code it implements — so a generator that emits one needs
	// to know where the project starts.
	Root string
	// Raw is this generator's own options block from rig.yaml.
	Raw map[string]any
}

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

type Result struct {
	Generator string
	Version   string
	Artifacts []Artifact
}

type Spec struct {
	Name    string
	OutDir  string
	Options map[string]any
}

type Status string

type WriteMode int

type WriteOptions struct {
	// Force overwrites files that were edited by hand.
	Force bool
	// Prune deletes files no generator claims any more.
	Prune bool
	// Previous is the manifest this run started from, if there was one.
	//
	// The new manifest is built from this run's deltas, and a run narrowed by
	// --only has no deltas for the generators it held back. Without their old
	// entries carried across, a narrow regeneration would cost every other
	// generator's files the one record that tells a hand edit from output rig
	// has not caught up with.
	Previous *Manifest
}