settings

type Activation struct {
	Field Field
	// When names the action that first uses the new value.
	When string
	// Notes explain the effect and its limits.
	Notes []string
}

type BlockedError struct {
	Reason string
	// Line is the 1-based line in the file, or 0 when unknown.
	Line int
	// File is the document to edit by hand, relative to the root. Empty
	// means config.yaml, the only document of the callers before the
	// lessons document.
	File string
}

type Edit struct {
	Field Field
	// Reset removes the key from the file.
	Reset bool
	// String is the agent.cli preset (a registered invocation ID) or the
	// hook_delivery mode.
	String string
	// Bool is the value of distill.write or index.generated.
	Bool bool
	// Days is a positive reviews.window_days value.
	Days int
	// Unlimited sets reviews.window_days to 0, the reader's unlimited.
	Unlimited bool
	// List is the index.exclude patterns. An empty list is a reset.
	List []string
	// Int is the threshold, pin_budget, or change_budget value, from 1
	// to math.MaxInt32. The editor writes no value that the reader
	// replaces with its default.
	Int int
	// Mute is the one mute operation of a mute field edit.
	Mute *MuteEdit
}

type Field string

type FieldState struct {
	Field  Field
	Stored Stored
	// Default and Effective are display text. They come from the owning
	// reader, so the UI never computes a default itself.
	Default   string
	Effective string
	Source    Source
	// Notes explain the effective value, for example an override.
	Notes []string
	// Err is set when the owning reader or the invocation resolver
	// fails. The value is then unknown, not the default.
	Err error
}

type Group int

type LessonsPart struct {
	// Path is the absolute file under the inspected root. The caller
	// passes the effective root, so this is the file that Pins lists.
	Path string
	// Guard is the observation that every lessons plan binds to.
	Guard integration.FileGuard
	// Exists is true when the file exists.
	Exists bool
	// Blocked holds the reason that stops a save of every lessons group:
	// the file is unreadable, linked, hard-linked, or not writable for
	// this user. Line breaks other than LF (CRLF, bare CR, mixed) and a
	// failed structural gate also block every lessons group. A save of
	// either group replaces the whole file, so a file problem blocks both.
	// BlockedAt is the 1-based line to open, or 0.
	Blocked   error
	BlockedAt int
	// ReaderErr is the failure of reviews.ParseConfig on the file bytes,
	// the reader of every lesson consumer. The editor never repairs a
	// file that the reader rejects, so it blocks both lessons groups.
	ReaderErr error
	// Config is the decoded file; nil when the reader fails.
	Config *reviews.Config
	// Mutes lists every item of the mute list in file order, null items
	// included. An item of a flow list has no line span, so its RawSHA is
	// zero; every mute operation refuses a flow list.
	Mutes []MuteEntry
	// contains filtered or unexported fields
}

type MuteEdit struct {
	Op   MuteOp
	Ref  MuteRef
	Rule string
	// Region is the typed region; CheckMute normalizes it.
	Region string
}

type MuteEntry struct {
	// Index is the position of the item in the YAML sequence. A null
	// item counts, so Index can differ from the index in
	// reviews.Config.Mute, which drops null items.
	Index int
	// Line is the 1-based dash line of the item.
	Line int
	// Rule and Region are the decoded values; "" when absent.
	Rule, Region string
	// RawSHA is the SHA-256 of the item lines, from the dash line to the
	// last line of the item. A MuteRef binds an edit to this text.
	RawSHA [32]byte
	// NoOp is true when the entry matches nothing: it has neither a rule
	// nor a region, as a null item or "- {}".
	NoOp bool
	// DuplicateOf is the Index of an earlier entry with the same rule
	// (any case) and exactly the same region, or -1.
	DuplicateOf int
	// Flow is true for an item in flow style, such as "- {rule: a}", and
	// for each item of a flow list. A change refuses a flow item; a
	// removal works in a block list.
	Flow bool
	// Extra lists the keys of the item that the reader does not know, in
	// file order. A change keeps them.
	Extra []string
}

type MuteInput struct {
	Rule, Region string
	Notes        []string
}

type MuteOp int

type MuteRef struct {
	Index  int
	RawSHA [32]byte
}

type Outcome int

type Plan struct {
	// Snapshot is the observation that the plan starts from.
	Snapshot *Snapshot
	Group    Group
	Edits    []Edit
	// File is the edited document relative to the root: File or
	// pinfile.File, as Group.Document returns it.
	File string
	// Bytes holds the reviewed and the planned file bytes of a lessons
	// plan, a no-op included; zero for a config.yaml plan. After equals
	// the bytes of the guarded write. A selection sample reads them.
	Bytes PlanBytes
	// Setup is the guarded write plan; nil for a no-op.
	Setup *integration.SetupPlan
	// Preview is the redacted file diff; zero for a no-op.
	Preview integration.WritePreview
	// Before and After are the states of the group's fields, from the
	// owning readers.
	Before, After []FieldState
	// Activation holds one entry per edited field.
	Activation []Activation
	// Notes apply to the save as a whole.
	Notes []string
	// NoOp is true when the edits leave the file bytes unchanged.
	NoOp bool
}

type PlanBytes struct {
	Before, After []byte
}

type Result struct {
	// Outcome says what the file holds after the save.
	Outcome Outcome
	// Written is true when the file holds the planned bytes: Outcome is
	// Written.
	Written bool
	// Created is true when the file did not exist before the save.
	Created bool
	// Path is the absolute path of the file.
	Path string
	// Err is the cause of a failed save. Outcome says what the file
	// holds then.
	Err error
}

type Snapshot struct {
	// Root is the absolute workspace root; Path is the absolute
	// config.yaml file.
	Root, Path string
	// Guard is the observation that every config.yaml plan binds to.
	Guard integration.FileGuard
	// Blocked is set when no config.yaml group can be saved: the file is
	// unreadable, linked, read-only, or structurally unsafe to edit.
	// BlockedAt is the 1-based line to open, or 0. It never blocks a
	// lessons group.
	Blocked   error
	BlockedAt int
	// ReadErr is the failure of reading config.yaml itself, before any
	// reader runs; nil when the read worked or the file is absent. A
	// reader that rejects the text sets ReaderErrs, not ReadErr. The
	// console checks its reload after a save with it, because a reader
	// error of another section does not mean that the read failed.
	ReadErr error
	// Fields holds every supported field of both documents in display
	// order.
	Fields []FieldState
	// Presets lists the valid agent.cli values in registry order.
	Presets []string
	// Invocation is the resolved agent command; zero with InvocationErr.
	Invocation    agent.CommandSpec
	InvocationErr error
	// ReaderErrs holds each reader's failure, keyed by ReaderAgent,
	// ReaderDistill, ReaderIndex, or ReaderLessons. A missing key means
	// success. The ReaderLessons entry is Lessons.ReaderErr, so a lookup
	// by Field.Reader works for every field.
	ReaderErrs map[string]error
	// Lessons is the observation of lessons.yaml. Inspect always sets it.
	Lessons *LessonsPart
	// Agent, Distill, and Index are the decoded sections; nil when the
	// reader failed. The UI seeds its drafts from them.
	Agent   *agent.Config
	Distill *distill.Config
	Index   *index.Config
	// InspectedAt is the time of the observation.
	InspectedAt time.Time
	// contains filtered or unexported fields
}

type Source int

type Stored struct {
	// Present is true when the key exists in the file.
	Present bool
	// Raw is the sanitized source text of the value, for display.
	Raw string
	// Line is the 1-based line of the key; 0 when absent.
	Line int
}

type Writer func(*integration.SetupPlan, integration.ApplyOptions) (integration.SetupResult, error)