pinfile

type Change struct {
	// Before is the reviewed file content; After is the candidate.
	Before, After []byte
	// Edits are the edits in the candidate, in request order.
	Edits []Edit
	// NewKeys holds the key of each edited entry after the change, in the
	// order of Edits. A deleted entry has the zero key.
	NewKeys []reviews.PinKey
	// Diff is the display diff from integration.UnifiedDiff: redacted and
	// sanitized. Added and Removed count the changed lines.
	Diff           string
	Added, Removed int
}

type Document struct {
	// Guard is the observation from integration.ReadInput: existence,
	// content hash, mode, and a symbolic link on the path. Parse leaves it
	// zero.
	Guard integration.FileGuard
	// Bytes is the exact file content; nil for an absent file.
	Bytes []byte
	// Entries lists the pin items that decode as mappings, in file order.
	Entries []Entry
	// FileBlock is the reason no entry can be edited, or empty. A link or
	// a file that this user cannot write blocks the write but still lets
	// Plan compute the change for review.
	FileBlock string
	// DecodeErr is a YAML syntax error of the first document. The listing
	// is then empty.
	DecodeErr error
	// ReaderErr is the error of reviews.ParseConfig on Bytes. The listing
	// keeps every entry that still decodes.
	ReaderErr error
	// ListErr reports a listing that differs from the pins that the
	// reader delivers, for example through an alias pin value or a pin
	// key from a merge key. The listing then cannot show which pins are
	// absent.
	ListErr error
	// ErrLine is the 1-based line of DecodeErr or ReaderErr, or 0. The
	// text of ListErr names its line itself.
	ErrLine int
}

type Edit struct {
	Ref EntryRef
	// Delete prunes the entry. Regions is then ignored, and a Rewrite is
	// not a valid request.
	Delete bool
	// Regions is the new region set of a retarget, in the order of the
	// region engine. An empty set means repository-wide.
	Regions []string
	// Provenance holds the IDs of the proposals linked to the entry. A
	// prune deletes only the provenance comments that name one of them.
	// The removal of an unlinked entry passes Entry.ProvenanceIDs, so the
	// provenance run of the entry goes with it. A run that stays would
	// read as the provenance of the next entry.
	Provenance []int64
	// Rewrite sets fields of the entry in place, for an entry that a
	// person edits in the console. With Rewrite set, Regions is ignored.
	Rewrite *Rewrite
}

type EditError struct {
	Ref EntryRef
	Err error
}

type Entry struct {
	// Index is the position of the item in the pin sequence. Empty items
	// count, so Index follows the YAML text and can differ from the
	// position in reviews.Config.Pin.
	Index int
	// Line is the 1-based dash line. EndLine is the last line that the
	// entry owns. Both are exact when the file parses for editing; else
	// they are the first and the last line of its decoded values.
	Line, EndLine int
	// Rule, Region, Regions, and Note are the decoded pin fields.
	Rule, Region, Note string
	Regions            []string
	// Unknown lists the keys that no reader uses, in file order. They do
	// not block an edit; a retarget keeps them.
	Unknown []string
	// Raw is the exact text of the entry's own lines with LF breaks. It is
	// file data: a caller sanitizes it before display.
	Raw string
	// Key is the canonical identity of the pin as delivered.
	Key reviews.PinKey
	// Block is the reason the entry cannot be edited, or empty.
	Block string
	// ProvenanceIDs are the proposal IDs that seamark provenance comments
	// directly above the entry name, in file order. They are a display
	// hint; a link never depends on them.
	ProvenanceIDs []int64
}

type EntryLink struct {
	Link Link
	// Applied, Pending, and Superseded list every row that matches the
	// entry, so an ambiguous entry can show all of them.
	Applied, Pending, Superseded []model.Proposal
	// NoteChanged is true for a linked entry whose live note differs from
	// the note that the proposal recorded.
	NoteChanged bool
}

type EntryRef struct {
	Index  int
	Key    reviews.PinKey
	RawSHA [32]byte
}

type Link int

type Links struct {
	// Entries holds one link per Document.Entries item, in the same order.
	Entries []EntryLink
	// NotPresent lists the applied rows that no live entry carries. It is
	// nil when the file could not be read; NotPresentErr then says so. A
	// row whose region fields disagree is listed with the link
	// LinkAmbiguousFields, so every applied row is in Entries or here.
	NotPresent    []model.Proposal
	NotPresentErr error
	// ByProposal holds the link of each applied and pending row by ID.
	// Superseded rows are history and have no entry here.
	ByProposal map[int64]Link
}

type Owners struct {
	// Entries are the live entries with the key, in file order.
	Entries []Entry
	// Applied and Pending are the proposal rows that own the key, in the
	// order of the input rows.
	Applied, Pending []model.Proposal
}

type Placement struct {
	// Tail puts the entries after the last entry of the list, for a pin
	// that a person writes in the console. A tail append must never
	// block later edits of the file, so it is stricter than an apply. It
	// refuses a file that fails the editing gate, CRLF line breaks
	// included. It also proves that the candidate passes the gate. An
	// absent file starts with the pin key alone, without a header.
	Tail bool
}

type Prepared struct {
	// Guard is the observation of the file that the write replaces.
	Guard integration.FileGuard
	// Written is the SHA-256 of the bytes that Apply writes. A later
	// Restore uses it to prove that the file still holds them.
	Written [32]byte
	// contains filtered or unexported fields
}

type Rewrite struct {
	// Rule is the new rule.
	Rule *string
	// Note is the new note. An empty note removes the note key, so the
	// pin reads as a rule-only reminder. A note key on the dash line
	// stays as note: "", because another key would have to move onto
	// the dash line.
	Note *string
	// Regions is the new region set, in the order of the user. An empty
	// set means repository-wide. The region keys change by the rules of
	// a retarget.
	Regions *[]string
}