reviews

type Comment struct {
	ID        int64
	Reviewer  string // classified: coderabbit | copilot | bot | human
	Author    string // raw user.login
	Body      string
	Path      string // repo-relative file the comment lands on
	Line      int    // resolved line (line, else original_line)
	URL       string // html_url, for provenance
	CreatedAt int64  // unix seconds
	PR        int    // pull-request number
	RuleCode  string // extracted linter code (RUF001, reportArgumentType…), or ""
	InReplyTo int64  // id of the thread's top comment; 0 when this IS one
}

type Config struct {
	// Threshold overrides the minimum recurrences to surface a lesson.
	Threshold int `yaml:"threshold"`
	// PinBudget overrides how many pins the edit hook injects per edit
	// (most-specific regions first; the rest are one pointer line away).
	// 0 means DefaultPinBudget.
	PinBudget int `yaml:"pin_budget"`
	// ChangeBudget overrides how many lessons one change_set answer
	// carries across all its files. 0 means DefaultChangeBudget.
	ChangeBudget int `yaml:"change_budget"`
	// Mute hides mined lessons by rule code and/or region prefix.
	Mute []MuteRule `yaml:"mute"`
	// Pin surfaces curated lessons unconditionally — the "must not be
	// ignored" list — even when mining never found them.
	Pin []PinRule `yaml:"pin"`
}

type Fetcher func(owner, repo string, opts Options) ([]byte, error)

type Fired struct {
	Region  string
	Symptom string
	Count   int
	LastTS  string
}

type FiredLesson struct {
	Region  string `json:"region"`
	Symptom string `json:"symptom"`
}

type Firing struct {
	TS string `json:"ts"`
	// Surface names the emitter: "" reads as the edit hook (the only
	// writer before change_set and check joined).
	Surface string `json:"surface,omitempty"`
	// File carries a single-file firing (the hook); Files a multi-file
	// one (change_set, check) — individually, so distinct-file counts
	// stay meaningful whatever order a diff lists them in.
	File  string        `json:"file,omitempty"`
	Files []string      `json:"files,omitempty"`
	Tool  string        `json:"tool,omitempty"`
	Fired []FiredLesson `json:"fired"`
}

type MuteRule struct {
	Rule   string `yaml:"rule"`
	Region string `yaml:"region"`
}

type Options struct {
	// Logf receives fetch and clustering progress; nil discards it. The
	// GitHub fetch is the silent long pole of a mine — pages of network
	// I/O — and silence reads as stuck.
	Logf func(format string, args ...any)
	// WindowDays bounds how old a review comment may be and still
	// enter the corpus (RFC-002 §9): fix mining always had a shelf
	// life; review comments were immortal, and seven-year-old feedback
	// weighed like last month's. 0 means DefaultReviewWindowDays;
	// negative means unlimited (the config's `window_days: 0`).
	WindowDays int
}

type PinAnnotator func(PinRule) (rank int, note string)

type PinKey struct {
	Rule   string
	Region string
}

type PinRule struct {
	Rule   string `yaml:"rule"`   // the symptom shown (a code or short label)
	Region string `yaml:"region"` // file or directory; "*" or "" is repo-wide
	// Regions widens a pin to a small set of places — one theme
	// legitimately living in `api` AND `db` needs no repo-wide `*`.
	// Flow-rendered (`regions: [api, db]`) so applied entries stay
	// single-line-parseable; readers predating this field see Region,
	// the set's first entry — narrower than the `*` they used to get.
	Regions []string `yaml:"regions,omitempty,flow"`
	Note    string   `yaml:"note"` // human explanation, carried into output
}

type Result struct {
	Lessons  []model.Lesson
	Findings []model.Finding
	Fetched  bool
	Note     string
}

type Summary struct {
	Total int // firing events across every surface
	// BySurface splits the events: an actual pre-edit hook reminder, a
	// change_set plan, and a CI check are different kinds of exposure,
	// and "edits reminded" must not count the other two.
	BySurface  map[string]int
	Files      int            // distinct files that triggered a firing
	Ranked     []Fired        // surfaced lessons that fired, most-fired first
	NeverFired []model.Lesson // lessons that would surface but never have
}

type SurfacedPin struct {
	Pin  PinRule
	Rank int    // annotator's confidence rank; equal when unannotated
	Note string // annotator's display note, "" for none
	// Depth is the deepest of the pin's regions matching the queried
	// scope — the specificity that earned it consideration there.
	Depth int
}