rules

type Action struct {
	Name remedy.Name `yaml:"name"`
}

type BaseHead string

type Catalogue struct {
	// Rules are ordered by how much they ask of a PR, the most specific
	// first, and by name among equals. The first rule that matches wins, so
	// a narrow rule is never shadowed by a broad one that happens to sort
	// earlier. The order is part of the contract and scenarios pin it.
	Rules []*Rule
	// Digest identifies the exact catalogue this sweep ran, and is written
	// into the evidence of every action a rule selected.
	Digest string
	// Source says where the catalogue came from.
	Source string
	// Ref is the branch the catalogue was read from, empty for a local
	// directory.
	Ref string
	// Skipped names the documents that failed to parse, with the reason.
	// They are left out; the rest of the catalogue still runs.
	Skipped []Skipped
}

type CheckMatch struct {
	// Name is a glob over the failing check names.
	Name string `yaml:"name"`
}

type CheckState string

type Coverage struct {
	NoPositive []string
	NoNegative []string
	// Orphans are scenario directories that name no rule of the catalogue.
	Orphans []string
}

type Evidence struct {
	// Reason is the line written on the PR under the action name.
	Reason string `yaml:"reason"`
}

type Hit struct {
	Rule *Rule
	// Check is the failing check the signal matched, or "" for a rule whose
	// signal is PR metadata alone.
	Check string
	// Excerpt is the log excerpt the pattern matched, empty for a rule with
	// no log signal.
	Excerpt string
	// LogMatched reports whether a log excerpt decided the match. An action
	// that writes is guarded on it.
	LogMatched bool
	// MissingContexts are the required contexts the protection signal
	// selected. An action that rewrites a protection touches these and no
	// other.
	MissingContexts []string
}

type Loader struct {
	Client *github.Client
	Owner  string
	Repo   string
	// Dir is the directory inside the repository that holds the documents.
	Dir string
	Ref string

	// LocalPath reads the catalogue from this directory instead of GitHub.
	LocalPath string
}

type LogMatch struct {
	// Source selects where the excerpt comes from.
	Source LogSource `yaml:"source"`
	// Pattern is an RE2 expression matched against the excerpt.
	Pattern string `yaml:"pattern"`
	// MaxBytes bounds the excerpt read from the tail of the log. Zero uses
	// the default.
	MaxBytes int `yaml:"maxBytes"`
}

type LogSource string

type Match struct {
	// States names the classifications the rule applies to, from the
	// remediable set. Empty applies to every remediable state.
	States []string `yaml:"states"`
	// Kinds names the bot PR kinds. Empty applies to every trusted kind.
	Kinds []string `yaml:"kinds"`

	Check      *CheckMatch      `yaml:"check"`
	Log        *LogMatch        `yaml:"log"`
	PR         *PRMatch         `yaml:"pr"`
	Protection *ProtectionMatch `yaml:"protection"`
}

type PRMatch struct {
	// BaseHead states what the base head must report for the failing checks.
	BaseHead BaseHead `yaml:"baseHead"`
	// TitlePattern is an RE2 expression matched against the PR title.
	TitlePattern string `yaml:"titlePattern"`
	// Files are globs; every one of them must match a file of the diff.
	Files []string `yaml:"files"`
}

type ProtectionMatch struct {
	// MissingContexts are globs over the required contexts the head never
	// reported. They are alternatives: the rule matches when any of them
	// selects a context, and the action drops only what they selected.
	MissingContexts []string `yaml:"missingContexts"`
}

type Rule struct {
	// Name identifies the rule and matches its file name.
	Name string `yaml:"name"`
	// Summary says in one line what the rule recognises.
	Summary string `yaml:"summary"`
	// Source cites where the pattern comes from, for instance the runbook
	// row it was imported from.
	Source string `yaml:"source"`

	Match    Match    `yaml:"match"`
	Action   Action   `yaml:"action"`
	Refuse   []string `yaml:"refuse"`
	Evidence Evidence `yaml:"evidence"`
	// contains filtered or unexported fields
}

type Scenario struct {
	// Name says what the case shows, in the words of a test name.
	Name string `yaml:"name"`
	// Subject is the classified PR as the sweep saw it.
	Subject ScenarioSubject `yaml:"subject"`
	// Expect names the rule that must match, or "" for a case that must
	// match nothing.
	Expect ScenarioExpect `yaml:"expect"`

	// Path is where the fixture was read from.
	Path string `yaml:"-"`
	// Rule is the rule the fixture belongs to, from its directory name.
	Rule string `yaml:"-"`
}

type ScenarioExpect struct {
	// Rule is the rule that must match, or "" for no match.
	Rule string `yaml:"rule"`
	// Check is the failing check the signal must have matched. Empty skips
	// the assertion.
	Check string `yaml:"check"`
}

type ScenarioSubject struct {
	State     string                `yaml:"state"`
	Kind      string                `yaml:"kind"`
	Title     string                `yaml:"title"`
	Failing   []string              `yaml:"failing"`
	BaseState map[string]CheckState `yaml:"baseState"`
	// MissingContexts records the required contexts of the base branch that
	// the head never reported.
	MissingContexts []string          `yaml:"missingContexts"`
	Files           []string          `yaml:"files"`
	Logs            map[string]string `yaml:"logs"`
}

type Skipped struct {
	Path   string
	Reason string
}

type Subject struct {
	State pr.StatusState
	Kind  pr.Kind
	Title string
	// Failing names the red checks that produced a verdict, in the order the
	// classification found them.
	Failing []string
	// BaseState says what the base head reported for each failing check.
	// A name absent from the map is CheckAbsent, and absent is not green.
	BaseState map[string]CheckState
	// MissingContexts names the required contexts of the base branch that
	// the head never reported.
	MissingContexts []string
	// Files returns the paths of the PR diff. It is called only for a rule
	// that carries a file signal, so a catalogue without one costs no
	// comparison. Nil returns no files, and such a rule does not match.
	Files func() []string
	// Log returns a bounded excerpt of one check's log. A rule with a log
	// signal never matches when Log is nil or reports false: an unreadable
	// log leaves the failure as it was classified.
	Log func(source LogSource, check string, maxBytes int) (string, bool)
}