ditzy.go

// Package ditzy detects timezone offsets from activity patterns.
//
// It analyzes timestamped events or pre-aggregated activity buckets to identify
// likely UTC offsets based on sleep patterns, lunch breaks, and activity distribution.
//
// Basic usage:
//
//	result := ditzy.FromEvents(events)
//	fmt.Printf("Most likely timezone: %s\n", result.Candidates[0].Timezone)
//
// For legacy code with pre-aggregated bucket data:
//
//	result := ditzy.FromBuckets(halfHourCounts,
//	    ditzy.WithClaimedTimezone("America/New_York"))
package ditzy

import (
	"log/slog"
	"time"
)

// Event represents a timestamped activity.
type Event struct {
	Time time.Time
	Type string // "commit", "push", "pr", "issue", "review", "comment", etc.
}

// hasPreservedTZ returns true if the event has non-Zulu timezone info.
func (e Event) hasPreservedTZ() bool {
	name, _ := e.Time.Zone()
	return name != "UTC"
}

// Candidate represents a detected timezone with full analysis data.
type Candidate struct {
	Timezone            string    `json:"timezone"`
	ScoringDetails      []string  `json:"-"` // Debug only, not exported to JSON
	SleepBucketsUTC     []float64 `json:"sleep_buckets_utc,omitempty"`
	SleepMidUTC         float64   `json:"sleep_mid_utc"`
	PeakStartUTC        float64   `json:"peak_start_utc,omitempty"`
	Offset              float64   `json:"offset"`
	LunchConfidence     float64   `json:"lunch_confidence"`
	LunchEndUTC         float64   `json:"lunch_end_utc"`
	WorkStartUTC        float64   `json:"work_start_utc"`
	WorkEndUTC          float64   `json:"work_end_utc"`
	LunchStartUTC       float64   `json:"lunch_start_utc"`
	LunchDipStrength    float64   `json:"lunch_dip_strength"`
	Confidence          float64   `json:"confidence"`
	PeakEndUTC          float64   `json:"peak_end_utc,omitempty"`
	EveningActivity     int       `json:"evening_activity"`
	PeakCount           int       `json:"peak_count,omitempty"`
	PeakTimeReasonable  bool      `json:"peak_time_reasonable"`
	SleepReasonable     bool      `json:"sleep_reasonable"`
	WorkHoursReasonable bool      `json:"work_hours_reasonable"`
	LunchReasonable     bool      `json:"lunch_reasonable"`
	IsProfile           bool      `json:"is_profile"`
}

// Hours returns the offset in hours (e.g., -8 for PST).
func (c Candidate) Hours() float64 {
	return c.Offset
}

// OffsetDuration returns the offset as a time.Duration.
func (c Candidate) OffsetDuration() time.Duration {
	return time.Duration(c.Offset) * time.Hour
}

// Analysis contains global detection results (not per-candidate).
type Analysis struct {
	HalfHourCounts   map[float64]int // raw bucket data for callers who need it
	SleepBuckets     []float64       // half-hour buckets (UTC) identified as sleep
	PeakStartUTC     float64         // global peak productivity start
	PeakEndUTC       float64         // global peak productivity end
	PeakCount        int             // activity count during peak
	LunchStartUTC    float64         // best global lunch pattern start
	LunchEndUTC      float64         // best global lunch pattern end
	LunchConfidence  float64         // confidence in lunch detection
	TotalEvents      int
	PreservedTZCount int     // events with preserved timezone info
	SleepConfidence  float64 // confidence in sleep detection
}

// Result contains timezone detection output.
type Result struct {
	Candidates []Candidate // ranked by confidence, highest first
	Analysis   Analysis    // global patterns for the activity data
}

// GlobalLunchPattern represents the best lunch pattern found globally in UTC.
type GlobalLunchPattern struct {
	StartUTC    float64
	EndUTC      float64
	Confidence  float64
	DropPercent float64
}

// config holds options for detection.
type config struct {
	newestActivity  time.Time
	logger          *slog.Logger
	claimedTimezone string
	username        string
	bestGlobalLunch GlobalLunchPattern
}

// Option configures detection behavior.
type Option func(*config)

// WithLogger sets a custom logger.
func WithLogger(l *slog.Logger) Option {
	return func(c *config) { c.logger = l }
}

// WithClaimedTimezone provides a timezone claimed by the user's profile.
func WithClaimedTimezone(tz string) Option {
	return func(c *config) { c.claimedTimezone = tz }
}

// WithUsername provides the username for logging/debugging.
func WithUsername(u string) Option {
	return func(c *config) { c.username = u }
}

// WithNewestActivity provides the most recent activity timestamp.
func WithNewestActivity(t time.Time) Option {
	return func(c *config) { c.newestActivity = t }
}

// WithGlobalLunch provides a pre-computed global lunch pattern.
func WithGlobalLunch(g GlobalLunchPattern) Option {
	return func(c *config) { c.bestGlobalLunch = g }
}

// FromEvents analyzes timestamped events and returns timezone candidates.
// This is the preferred API for new code.
func FromEvents(events []Event, opts ...Option) *Result {
	if len(events) == 0 {
		return &Result{}
	}

	cfg := &config{}
	for _, opt := range opts {
		opt(cfg)
	}
	if cfg.logger == nil {
		cfg.logger = slog.Default()
	}

	// Aggregate events into half-hourly and hourly buckets
	halfHourly := make(map[float64]int)
	hourly := make(map[int]int)
	preservedCount := 0

	for _, e := range events {
		hour := float64(e.Time.Hour())
		if e.Time.Minute() >= 30 {
			hour += 0.5
		}
		halfHourly[hour]++
		hourly[e.Time.Hour()]++

		if e.hasPreservedTZ() {
			preservedCount++
		}
	}

	cfg.logger.Debug("aggregated activity",
		"total_events", len(events),
		"preserved_tz_count", preservedCount,
		"buckets", len(halfHourly))

	result := fromBucketsInternal(halfHourly, hourly, cfg)
	result.Analysis.TotalEvents = len(events)
	result.Analysis.PreservedTZCount = preservedCount
	return result
}

// FromBuckets analyzes pre-aggregated half-hour activity buckets.
// This is provided for legacy code that already has bucket data.
// Keys are hours (0-23) with .5 for second half (e.g., 14.5 = 2:30-2:59 PM UTC).
func FromBuckets(halfHourCounts map[float64]int, opts ...Option) *Result {
	if len(halfHourCounts) == 0 {
		return &Result{}
	}

	cfg := &config{}
	for _, opt := range opts {
		opt(cfg)
	}
	if cfg.logger == nil {
		cfg.logger = slog.Default()
	}

	// Convert half-hour buckets to hourly for compatibility
	hourly := make(map[int]int)
	total := 0
	for bucket, count := range halfHourCounts {
		hourly[int(bucket)] += count
		total += count
	}

	result := fromBucketsInternal(halfHourCounts, hourly, cfg)
	result.Analysis.TotalEvents = total
	return result
}

// fromBucketsInternal is the shared implementation for both entry points.
func fromBucketsInternal(halfHourly map[float64]int, hourly map[int]int, cfg *config) *Result {
	// Find quiet hours and active start
	quietHours := findQuietHours(hourly)
	activeStart := findActiveStart(halfHourly)
	midQuiet := 0.0
	if len(quietHours) > 0 {
		sum := 0
		for _, h := range quietHours {
			sum += h
		}
		midQuiet = float64(sum) / float64(len(quietHours))
	}

	// Detect global patterns
	sleepBuckets := detectSleepBuckets(halfHourly, 0)
	peakStart, peakEnd, peakCount := detectPeakProductivity(halfHourly)

	// Use provided global lunch or detect it
	globalLunch := cfg.bestGlobalLunch
	if globalLunch.Confidence == 0 {
		detected := findBestGlobalLunchPattern(halfHourly)
		globalLunch = GlobalLunchPattern{
			StartUTC:    detected.startUTC,
			EndUTC:      detected.endUTC,
			Confidence:  detected.confidence,
			DropPercent: detected.dropPercent,
		}
	}

	// Run evaluation
	evalInput := evaluationInput{
		username:        cfg.username,
		hourCounts:      hourly,
		halfHourCounts:  halfHourly,
		profileTimezone: cfg.claimedTimezone,
		quietHours:      quietHours,
		midQuiet:        midQuiet,
		activeStart:     activeStart,
		newestActivity:  cfg.newestActivity,
		bestGlobalLunch: globalLunchPattern{
			startUTC:    globalLunch.StartUTC,
			endUTC:      globalLunch.EndUTC,
			confidence:  globalLunch.Confidence,
			dropPercent: globalLunch.DropPercent,
		},
	}

	// Count total activity
	for _, count := range halfHourly {
		evalInput.totalActivity += count
	}

	evalCandidates := evaluate(evalInput)

	// Convert to public Candidate type
	candidates := make([]Candidate, 0, len(evalCandidates))
	for i := range evalCandidates {
		ec := &evalCandidates[i]
		candidates = append(candidates, Candidate{
			Timezone:            ec.timezone,
			ScoringDetails:      ec.scoringDetails,
			SleepBucketsUTC:     ec.sleepBucketsUTC,
			SleepMidUTC:         ec.sleepMidUTC,
			PeakStartUTC:        ec.peakStartUTC,
			Offset:              ec.offset,
			LunchConfidence:     ec.lunchConfidence,
			LunchEndUTC:         ec.lunchEndUTC,
			WorkStartUTC:        ec.workStartUTC,
			WorkEndUTC:          ec.workEndUTC,
			LunchStartUTC:       ec.lunchStartUTC,
			LunchDipStrength:    ec.lunchDipStrength,
			Confidence:          ec.confidence,
			PeakEndUTC:          ec.peakEndUTC,
			EveningActivity:     ec.eveningActivity,
			PeakCount:           ec.peakCount,
			PeakTimeReasonable:  ec.peakTimeReasonable,
			SleepReasonable:     ec.sleepReasonable,
			WorkHoursReasonable: ec.workHoursReasonable,
			LunchReasonable:     ec.lunchReasonable,
			IsProfile:           ec.isProfile,
		})
	}

	// Build analysis with global patterns
	sleepConfidence := 0.0
	if len(sleepBuckets) >= 8 {
		sleepConfidence = 0.8
	} else if len(sleepBuckets) >= 4 {
		sleepConfidence = 0.5
	}

	return &Result{
		Candidates: candidates,
		Analysis: Analysis{
			HalfHourCounts:  halfHourly,
			SleepBuckets:    sleepBuckets,
			SleepConfidence: sleepConfidence,
			PeakStartUTC:    peakStart,
			PeakEndUTC:      peakEnd,
			PeakCount:       peakCount,
			LunchStartUTC:   globalLunch.StartUTC,
			LunchEndUTC:     globalLunch.EndUTC,
			LunchConfidence: globalLunch.Confidence,
		},
	}
}

// findQuietHours finds hours with zero activity.
func findQuietHours(hourly map[int]int) []int {
	var quiet []int
	for hour := range 24 {
		if hourly[hour] == 0 {
			quiet = append(quiet, hour)
		}
	}
	return quiet
}

// findActiveStart finds the first half-hour bucket with activity.
func findActiveStart(halfHourly map[float64]int) float64 {
	for hour := 0.0; hour < 24.0; hour += 0.5 {
		if halfHourly[hour] > 0 {
			return hour
		}
	}
	return 0
}