lookaround

type Board struct {
	Version     int       `json:"version"`
	GeneratedAt time.Time `json:"generated_at"`
	View        string    `json:"view"`
	Project     Project   `json:"project"`
	Window      Window    `json:"window"`
	Sources     []Source  `json:"sources"`
	Rows        []Row     `json:"rows"`           // the state view's; empty in the feed
	Feed        *Feed     `json:"feed,omitempty"` // the feed view's
}

type Branch struct {
	Task   string   // the id the branch is linked to, else what its name spells
	Riders []string // a bundle's other members
	After  string   // the base task recorded on it
	Model  string   // the agent's model, where start recorded it
	Agent  string   // the agent's profile as typed (opus:high), where start recorded one
	// Finish is `f10 drive`'s record of running the branch's finish, while
	// that drive holds the task's lease
	Finish *ref.DriveFinish
}

type Facts struct {
	Project Project
	Prefix  string // the task id prefix, for reading ids off branches and titles
	Tasks   []Task
	PRs     []PR
	Local   *Local // nil when the local collector was skipped or failed
	People  []Person
	Sources []Source

	// the feed's: what the host did in the window, each started task's
	// other requests by id, and a local-only checkout's branch tips
	Activity *forge.Activity
	Earlier  map[string][]forge.PR
	Tips     []Tip
}

type Feed struct {
	Rows  []FeedRow `json:"rows"`
	Quiet Quiet     `json:"quiet"`
}

type FeedRow struct {
	Group string `json:"group"`
	Key   string `json:"key"` // the task id, else `#<number>`, else the branch
	Task  *Task  `json:"task,omitempty"`
	PR    *PRRef `json:"pr,omitempty"`
	From  string `json:"from"`
	Who   Who    `json:"who"`
	// Owes is who the next move waits on: the author after a review, a
	// requested reviewer before one.
	Owes      string      `json:"owes,omitempty"`
	Abandoned bool        `json:"abandoned,omitempty"` // closed without merging, nothing later
	Related   []RelatedPR `json:"related,omitempty"`   // the task's requests opened before PR
	Summary   string      `json:"summary,omitempty"`   // what happened, one sentence
	At        time.Time   `json:"at"`                  // the latest event in the window
}

type Findings struct {
	Round int
	Open  int // findings with no verdict, or a verdict of ask
	At    time.Time
}

type Inputs struct {
	Project Project
	Prefix  string
	// Since is where reading starts: the state view's done window, or the
	// earliest span the feed may show.
	Since time.Time

	// Feed reads what changed since Since instead of where every task
	// stands: the host's activity, the tracker's list, and nothing local
	// unless the checkout is local only.
	Feed bool

	// LocalOnly is a checkout with no origin remote: the host is skipped,
	// and the tracker too unless a driver answers it (Tasks set).
	LocalOnly bool

	Host      *forge.Host
	HostError string // why there is no host, for the source's error

	Tasks func(ctx context.Context) ([]Task, error)

	// RemoteOpen reports whether the project's declared remote reviewer
	// left a review on the request nobody handled; nil declares none. An
	// error is a note on the host source, the request kept without it.
	RemoteOpen func(ctx context.Context, number int) (bool, error)

	Remote bool
	Local  *LocalInputs

	// People is the user's map of one person's identities across the
	// sources; nil groups rows by whatever identity each source gives.
	People []Person

	// Now is the clock; nil is time.Now. A test fixes it so timings are
	// stable.
	Now func() time.Time
}

type Local struct {
	Runs       []state.Run
	Worktrees  []Worktree
	Branches   map[string]Branch    // by branch name
	Plans      map[string]time.Time // task id to the plan file's mtime
	Archived   map[string]bool      // task ids whose plan is archived
	Findings   map[string]Findings  // task id to its latest round
	Verdicts   map[string]string    // task id to its latest verdict
	Finished   map[string]bool      // task ids the ledger holds task_finished for
	Workspaces map[string]Workspace // worktree path to the Herdr workspace on it
}

type LocalInputs struct {
	Main       string // the main checkout
	StateDir   string // run state files
	TTL        time.Duration
	SharedRoot string           // the storage root every checkout shares; "" reads each checkout's .f10
	LedgerPath string           // "" reads no ledger
	ProjectID  string           // the ledger's project id
	Agents     agentctl.Backend // the agent backend, when reachable: read its workspaces; nil reads none
}

type Next struct {
	Command string `json:"command,omitempty"`
	Text    string `json:"text,omitempty"`
}

type PR struct {
	forge.PR

	Block      *trace.State   `json:"block,omitempty"`
	Trailers   []trace.Parsed `json:"trailers,omitempty"`
	HeadExists *bool          `json:"head_exists,omitempty"` // read for merged requests only
	RemoteOpen bool           `json:"remote_open,omitempty"` // the declared remote reviewer left one unhandled
}

type PRRef struct {
	Number    int    `json:"number"`
	Title     string `json:"title,omitempty"`
	URL       string `json:"url,omitempty"`
	State     string `json:"state"` // open, merged or closed
	Draft     bool   `json:"draft,omitempty"`
	Head      string `json:"head,omitempty"`
	Base      string `json:"base,omitempty"`
	Mergeable string `json:"mergeable,omitempty"` // clean, conflicts or blocked
	Checks    string `json:"checks,omitempty"`    // green, red or pending
}

type Person struct {
	Name    string
	Tracker string
	Host    string
	Emails  []string
}

type Project struct {
	ID       string `json:"id"`                 // the normalised remote, `github.com/org/repo`
	Name     string `json:"name"`               // the main checkout's basename
	Host     string `json:"host,omitempty"`     // gh or glab
	Checkout string `json:"checkout,omitempty"` // the main checkout; empty with no checkout read
	Remote   bool   `json:"remote"`             // local collectors skipped
	// LocalOnly is a checkout with no origin remote: no host to read, so
	// the board is this machine's alone.
	LocalOnly bool `json:"local_only,omitempty"`
}

type Quiet struct {
	Count  int       `json:"count"`
	Oldest time.Time `json:"oldest,omitzero"` // the oldest one's creation time
}

type RelatedPR struct {
	Number   int    `json:"number"`
	URL      string `json:"url,omitempty"`
	State    string `json:"state"` // open, merged or closed
	Relation string `json:"relation"`
}

type ReviewFacts struct {
	Step             string `json:"step,omitempty"` // the step the state block names
	Round            int    `json:"round,omitempty"`
	Open             int    `json:"open,omitempty"`
	Asks             int    `json:"asks,omitempty"`
	Approvals        int    `json:"approvals,omitempty"`
	ChangesRequested int    `json:"changes_requested,omitempty"`
	RemoteOpen       bool   `json:"remote_open,omitempty"` // the declared remote reviewer left one unhandled
}

type Row struct {
	Key          string       `json:"key"` // the task id, else `#<number>`
	Task         *Task        `json:"task,omitempty"`
	Stage        string       `json:"stage"`
	StageFrom    string       `json:"stage_from"`
	Who          Who          `json:"who"`
	Where        Where        `json:"where"`
	Review       *ReviewFacts `json:"review,omitempty"`
	BlockedBy    []string     `json:"blocked_by,omitempty"`
	LastActivity time.Time    `json:"last_activity,omitzero"`
	Next         Next         `json:"next"`
}

type Source struct {
	Name    string   `json:"name"`
	OK      bool     `json:"ok"`
	Skipped bool     `json:"skipped,omitempty"`
	Error   string   `json:"error,omitempty"`
	Notes   []string `json:"notes,omitempty"`
	TookMS  int64    `json:"took_ms"`
}

type Task struct {
	ID       string `json:"id"`
	Title    string `json:"title,omitempty"`
	URL      string `json:"url,omitempty"`
	Status   string `json:"status,omitempty"`
	Priority string `json:"priority,omitempty"`
	Assignee string `json:"assignee,omitempty"`
	After    string `json:"after,omitempty"` // the base its body names
	// Created is when the tracker created it, where the tracker says.
	Created time.Time `json:"created,omitzero"`
}

type Tip struct {
	Branch string
	At     time.Time
}

type Where struct {
	PR        *PRRef `json:"pr,omitempty"`
	Branch    string `json:"branch,omitempty"`
	Worktree  string `json:"worktree,omitempty"`
	Workspace string `json:"workspace,omitempty"`
	// BranchLeft marks a merged row whose branch outlived its worktree
	BranchLeft bool `json:"branch_left,omitempty"`
}

type Who struct {
	Agent       string   `json:"agent,omitempty"`        // the Herdr agent in its worktree
	AgentStatus string   `json:"agent_status,omitempty"` // idle, working, done
	Model       string   `json:"model,omitempty"`
	Author      string   `json:"author,omitempty"` // the request's author
	Assignees   []string `json:"assignees,omitempty"`
	Reviewers   []string `json:"reviewers,omitempty"`  // requested and not yet heard from
	Committers  []string `json:"committers,omitempty"` // the author emails on the row's commits
	// Person is the one name the row groups under: the assignee, else the
	// author, else the first committer, through the people map where it matches.
	Person string `json:"person,omitempty"`
}

type Window struct {
	Since time.Time `json:"since"`
	// End closes the feed's span, exclusive; zero in the state view.
	End time.Time `json:"end,omitzero"`
	// Chosen is how the feed's span was picked: the window named
	// (`today`, `last-week`, a date) or the default's pick.
	Chosen string `json:"chosen,omitempty"`
	// Fallback is the default falling back to the last working day
	// because today has no activity yet.
	Fallback bool `json:"fallback,omitempty"`
}

type Workspace struct {
	ID          string
	Label       string
	AgentStatus string
}

type Worktree struct {
	Path   string
	Branch string
	Ahead  int      // commits past its base
	Emails []string // the distinct author emails on those commits
}