analytics

type AgingItem struct {
	SpecID string
	Stage  string
	Dwell  time.Duration
	P85    time.Duration
	Ratio  float64
}

type AgingJSON struct {
	SpecID string       `json:"spec_id"`
	Stage  string       `json:"stage"`
	Dwell  DurationJSON `json:"dwell"`
	P85    DurationJSON `json:"p85"`
	Ratio  float64      `json:"ratio"`
}

type BlockedSpell struct {
	Start time.Time
	End   time.Time
}

type Coverage struct {
	CommitsScanned int
	Transitions    int
	Unattributable int
}

type Distribution struct {
	Samples []time.Duration
	P50     time.Duration
	P85     time.Duration
	P95     time.Duration
}

type DistributionJSON struct {
	Samples int          `json:"samples"`
	P50     DurationJSON `json:"p50"`
	P85     DurationJSON `json:"p85"`
	P95     DurationJSON `json:"p95"`
}

type DurationJSON struct {
	Seconds int64  `json:"seconds"`
	Human   string `json:"human"`
}

type Event struct {
	SpecID    string
	Kind      EventKind
	FromStage string // empty for scaffolds
	ToStage   string
	At        time.Time
	Source    EventSource
}

type EventKind string

type EventSource string

type ExtractResult struct {
	Events         []Event
	CommitsScanned int
	Transitions    int // status transitions successfully attributed
	Unattributable int // spec-file changes whose status could not be read
}

type FlowInput struct {
	Timelines  map[string]*Timeline
	Events     []Event
	Window     Window
	Now        time.Time
	StageNames []string        // full pipeline order
	Terminal   []string        // terminal stage names
	WorkStages []string        // engineer-owned stages (flow-efficiency numerator)
	FastTrack  map[string]bool // spec IDs flagged fast_track
	Filter     map[string]bool // optional spec-ID scope (nil = all)
}

type FlowReport struct {
	Window            Window
	Completed         int
	LeadTime          Distribution
	CycleTime         Distribution
	FastTrackLead     Distribution // separate population, may be empty
	FlowEfficiency    float64      // work-stage time / lead time; -1 when unknown
	ThroughputPerWeek float64
	StageDwell        []StageDwell // pipeline order, stages with samples only
	Bottleneck        string       // stage with largest p50 dwell
	Reversions        []ReversionBoundary
	TotalAdvances     int
	TotalReversions   int
	AgingWIP          []AgingItem
	BlockedSpecs      int
	BlockedTotal      time.Duration
	Coverage          Coverage
}

type ReportJSON struct {
	Window struct {
		From  time.Time `json:"from"`
		To    time.Time `json:"to"`
		Label string    `json:"label"`
	} `json:"window"`
	Completed         int               `json:"completed"`
	LeadTime          DistributionJSON  `json:"lead_time"`
	CycleTime         DistributionJSON  `json:"cycle_time"`
	FastTrackLead     *DistributionJSON `json:"fast_track_lead,omitempty"`
	FlowEfficiency    *float64          `json:"flow_efficiency,omitempty"`
	ThroughputPerWeek float64           `json:"throughput_per_week"`
	StageDwell        []StageDwellJSON  `json:"stage_dwell"`
	Bottleneck        string            `json:"bottleneck,omitempty"`
	Reversions        []ReversionJSON   `json:"reversions"`
	TotalAdvances     int               `json:"total_advances"`
	TotalReversions   int               `json:"total_reversions"`
	AgingWIP          []AgingJSON       `json:"aging_wip"`
	BlockedSpecs      int               `json:"blocked_specs"`
	BlockedTotal      DurationJSON      `json:"blocked_total"`
	Coverage          struct {
		CommitsScanned int `json:"commits_scanned"`
		Transitions    int `json:"transitions"`
		Unattributable int `json:"unattributable"`
	} `json:"coverage"`
}

type Reversion struct {
	From string
	To   string
	At   time.Time
}

type ReversionBoundary struct {
	From  string
	To    string
	Count int
}

type ReversionJSON struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Count int    `json:"count"`
}

type StageDwell struct {
	Stage string
	Dist  Distribution
}

type StageDwellJSON struct {
	Stage string           `json:"stage"`
	Dwell DistributionJSON `json:"dwell"`
}

type StageVisit struct {
	Stage   string
	Entered time.Time
	Exited  time.Time
}

type Timeline struct {
	SpecID       string
	Created      time.Time
	Visits       []StageVisit // closed visits only
	Blocked      []BlockedSpell
	Reversions   []Reversion
	Advances     int
	CurrentStage string    // stage the spec occupies after the last event
	CurrentSince time.Time // when it entered CurrentStage
	CompletedAt  time.Time // zero until the spec first enters a terminal stage
}

type Window struct {
	From  time.Time
	To    time.Time
	Label string
}