compass_teams_nhs/internal/dashboard/dashboard.go

// Package dashboard turns stored items into the per-child view required by
// AGENTS.md §4 (FR-6, FR-7) and §5: overdue first, then due today, due this
// week, then messages. It holds no state; the same code feeds the web
// dashboard and the stored draft brief (FR-9/FR-10).
package dashboard

import (
	"fmt"
	"sort"
	"strings"
	"time"

	"gitea.lab.audasmedia.com.au/sam/compass_teams_nhs/internal/period"
	"gitea.lab.audasmedia.com.au/sam/compass_teams_nhs/internal/store"
)

// Buckets is one child's items, split into the sections the dashboard shows.
// Later and NoDue are counted but not given a heading of their own unless they
// carry work, so the page stays brief (AGENTS.md §10 rule 6).
type Buckets struct {
	Overdue  []store.Item
	DueToday []store.Item
	DueWeek  []store.Item
	NoDue    []store.Item
	Messages []store.Item
	// Later is work due after this week; Done is submitted work. Both are kept
	// so the summary can count them and nothing is silently dropped.
	Later []store.Item
	Done  []store.Item
	// PeriodsToday is the child's own timetable for today (FR-16/FR-17).
	PeriodsToday []store.Item
	// EventsToday is today's major school events (concerts, excursions, exams).
	EventsToday []store.Item
	// FutureWork is the outstanding work due today or later. The morning brief
	// lists it under "DUE IN FUTURE" (FR-9).
	FutureWork []store.Item
}

// Actionable is the number of task items that still need doing.
func (b Buckets) Actionable() int {
	return len(b.Overdue) + len(b.DueToday) + len(b.DueWeek) + len(b.NoDue)
}

// Empty reports whether the child has nothing to show at all.
func (b Buckets) Empty() bool {
	return b.Actionable() == 0 && len(b.Messages) == 0
}

// Headline is the one-line summary used at the top of a child tab and in the
// brief.
func (b Buckets) Headline() string {
	return fmt.Sprintf("%d overdue · %d due today · %d this week · %d message(s)",
		len(b.Overdue), len(b.DueToday), len(b.DueWeek), len(b.Messages))
}

// Classify splits items into buckets for one child.
//
// A task counts as overdue when Compass says so ("Status: Overdue" or
// "Submitted: Overdue"), or when it is not submitted and its due date is
// before today. Submitted work (On Time / Received Late) is not "due", so it
// is kept out of the due lists (the parser stores every historical task; the
// dashboard shows what still needs doing).
func Classify(items []store.Item, now time.Time, loc *time.Location) Buckets {
	if loc == nil {
		loc = time.UTC
	}
	startToday := startOfDay(now, loc)
	endToday := startToday.AddDate(0, 0, 1)
	endWeek := startToday.AddDate(0, 0, 7)

	var b Buckets
	for _, it := range items {
		switch it.Type {
		case "message":
			b.Messages = append(b.Messages, it)
			continue
		case "task":
			// handled below
		case "event":
			// A lesson or event is never "overdue": a past lesson is history, not
			// work to do. Only today and the coming week are shown.
			if it.DueAt == nil {
				continue
			}
			due := it.DueAt.In(loc)
			switch {
			case !due.Before(startToday) && due.Before(endToday):
				b.DueToday = append(b.DueToday, it)
				if isPeriodItem(it) {
					b.PeriodsToday = append(b.PeriodsToday, it)
				} else {
					b.EventsToday = append(b.EventsToday, it)
				}
			case !due.Before(endToday) && due.Before(endWeek):
				b.DueWeek = append(b.DueWeek, it)
			case !due.Before(endWeek):
				b.Later = append(b.Later, it)
			}
			continue
		default:
			continue
		}

		status := Status(it.Body)
		if isSubmitted(status) {
			b.Done = append(b.Done, it)
			continue
		}
		if it.DueAt == nil {
			b.NoDue = append(b.NoDue, it)
			continue
		}

		due := it.DueAt.In(loc)
		switch {
		case status == "overdue":
			b.Overdue = append(b.Overdue, it)
		case due.Before(startToday):
			b.Overdue = append(b.Overdue, it)
		case due.Before(endToday):
			b.DueToday = append(b.DueToday, it)
			b.FutureWork = append(b.FutureWork, it)
		case due.Before(endWeek):
			b.DueWeek = append(b.DueWeek, it)
			b.FutureWork = append(b.FutureWork, it)
		default:
			b.Later = append(b.Later, it)
			b.FutureWork = append(b.FutureWork, it)
		}
	}

	for _, s := range [][]store.Item{b.Overdue, b.DueToday, b.DueWeek, b.NoDue, b.Later, b.Done, b.PeriodsToday, b.EventsToday, b.FutureWork} {
		sort.SliceStable(s, func(i, j int) bool { return less(s[i], s[j]) })
	}
	sort.SliceStable(b.Messages, func(i, j int) bool {
		ti, tj := timeOf(b.Messages[i]), timeOf(b.Messages[j])
		return ti.After(tj)
	})
	return b
}

// less orders actionable items by due date, then title. A nil due date sorts last.
func less(a, b store.Item) bool {
	switch {
	case a.DueAt == nil && b.DueAt == nil:
		return a.Title < b.Title
	case a.DueAt == nil:
		return false
	case b.DueAt == nil:
		return true
	case a.DueAt.Equal(*b.DueAt):
		return a.Title < b.Title
	default:
		return a.DueAt.Before(*b.DueAt)
	}
}

func timeOf(it store.Item) time.Time {
	if it.DueAt == nil {
		return time.Time{}
	}
	return *it.DueAt
}

// Status reads the status line the parser writes into a task body: the JSON
// parser writes "Status: Overdue", the HTML grid writes "Submitted: Overdue".
// It returns a lower-case label, or "" when the body carries no status.
func Status(body string) string {
	for _, line := range strings.Split(body, "\n") {
		line = strings.TrimSpace(line)
		for _, prefix := range []string{"Status:", "Submitted:"} {
			if strings.HasPrefix(line, prefix) {
				v := strings.TrimSpace(strings.TrimPrefix(line, prefix))
				v = strings.TrimRight(v, ".")
				return strings.ToLower(v)
			}
		}
	}
	return ""
}

// submittedStatuses are the labels that mean the work no longer needs doing.
var submittedStatuses = map[string]bool{
	"on time":       true,
	"received late": true,
	"submitted":     true,
	"completed":     true,
}

// IsSubmittedStatus reports whether a task status means the work no longer
// needs doing, so it is excluded from the calendar's work lists.
func IsSubmittedStatus(status string) bool { return isSubmitted(status) }

func isSubmitted(status string) bool { return submittedStatuses[status] }

// isPeriodItem reports whether an event is a routine class period from the
// child's own timetable rather than a school event. Compass writes a lesson as
// "1 - 7SCF - H14LAB - KNI" (FR-16/FR-17).
func isPeriodItem(it store.Item) bool {
	parts := period.SplitDash(it.Title)
	return len(parts) > 0 && period.IsPeriodLabel(parts[0])
}

func startOfDay(t time.Time, loc *time.Location) time.Time {
	t = t.In(loc)
	return time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, loc)
}

// Limits caps a section so a brief stays brief (AGENTS.md §10 rule 6). Overdue
// work is never capped; pending work without a due date is the long tail, so it
// is the one that is summarised.
type Limits struct {
	// NoDue is the most no-due-date items a brief lists (0 means no cap).
	NoDue int
}

// MorningLimits is the cap the per-boy and combined morning briefs use. The
// dashboard and the preview always show the full lists.
var MorningLimits = Limits{NoDue: 5}

// Render writes one child's brief as plain text: overdue first, then due today,
// due this week, no due date and messages (FR-9, FR-14, AGENTS.md §4 rule 6).
func Render(child string, b Buckets, loc *time.Location) string {
	return RenderWithLimits(child, b, loc, Limits{})
}

// RenderWithLimits is Render with a cap on the long-tail sections.
func RenderWithLimits(child string, b Buckets, loc *time.Location, lim Limits) string {
	if loc == nil {
		loc = time.UTC
	}
	var sb strings.Builder
	fmt.Fprintf(&sb, "%s — %s.\n", child, b.Headline())

	writeSection(&sb, "OVERDUE", b.Overdue, loc, 0)
	writeSection(&sb, "DUE TODAY", b.DueToday, loc, 0)
	writeSection(&sb, "DUE THIS WEEK", b.DueWeek, loc, 0)
	writeSection(&sb, "NO DUE DATE", b.NoDue, loc, lim.NoDue)
	writeMessages(&sb, b.Messages, loc)
	return strings.TrimRight(sb.String(), "\n") + "\n"
}

func writeSection(sb *strings.Builder, title string, items []store.Item, loc *time.Location, limit int) {
	if len(items) == 0 {
		return
	}
	fmt.Fprintf(sb, "\n%s\n", title)
	for i, it := range items {
		if limit > 0 && i >= limit {
			fmt.Fprintf(sb, "- … and %d more with no due date (see the dashboard)\n", len(items)-limit)
			break
		}
		fmt.Fprintf(sb, "- %s\n", line(it, loc))
	}
}

func writeMessages(sb *strings.Builder, items []store.Item, loc *time.Location) {
	if len(items) == 0 {
		return
	}
	sb.WriteString("\nMESSAGES\n")
	for _, it := range items {
		when := ""
		if it.DueAt != nil {
			when = " (" + it.DueAt.In(loc).Format("Mon 02 Jan 15:04") + ")"
		}
		fmt.Fprintf(sb, "- %s%s\n", it.Title, when)
	}
}

// Combined is one child's share of the combined brief.
type Combined struct {
	Child   string
	Buckets Buckets
}

// RenderCombined writes the single brief for Jo and Sam (FR-14): both boys in
// one message, overdue first, lists only (AGENTS.md §10 rule 6). Every line is
// prefixed with the child's name so a parent never has to guess whose work it
// is. It never claims "nothing due" by itself: the caller adds the scan warning
// when a scan failed (FR-12).
func RenderCombined(parts []Combined, loc *time.Location) string {
	return RenderCombinedWithLimits(parts, loc, Limits{})
}

// RenderCombinedWithLimits is RenderCombined with a cap on the long tail.
func RenderCombinedWithLimits(parts []Combined, loc *time.Location, lim Limits) string {
	if loc == nil {
		loc = time.UTC
	}
	names := make([]string, 0, len(parts))
	for _, p := range parts {
		names = append(names, p.Child)
	}

	var sb strings.Builder
	fmt.Fprintf(&sb, "%s — %s.\n", joinNames(names), combinedHeadline(parts))

	writeCombined(&sb, "OVERDUE", parts, loc, 0, func(b Buckets) []store.Item { return b.Overdue })
	writeCombined(&sb, "DUE TODAY", parts, loc, 0, func(b Buckets) []store.Item { return b.DueToday })
	writeCombined(&sb, "DUE THIS WEEK", parts, loc, 0, func(b Buckets) []store.Item { return b.DueWeek })
	writeCombined(&sb, "NO DUE DATE", parts, loc, lim.NoDue, func(b Buckets) []store.Item { return b.NoDue })
	writeCombinedMessages(&sb, parts, loc)
	return strings.TrimRight(sb.String(), "\n") + "\n"
}

// joinNames renders "Harry and Finn" for any number of children.
func joinNames(names []string) string {
	switch len(names) {
	case 0:
		return "School brief"
	case 1:
		return names[0]
	case 2:
		return names[0] + " and " + names[1]
	default:
		return strings.Join(names[:len(names)-1], ", ") + " and " + names[len(names)-1]
	}
}

// combinedHeadline counts both boys in one line, so the whole family sees the
// size of the day before the lists.
func combinedHeadline(parts []Combined) string {
	var overdue, today, week, messages int
	for _, p := range parts {
		overdue += len(p.Buckets.Overdue)
		today += len(p.Buckets.DueToday)
		week += len(p.Buckets.DueWeek)
		messages += len(p.Buckets.Messages)
	}
	return fmt.Sprintf("%d overdue · %d due today · %d this week · %d message(s)",
		overdue, today, week, messages)
}

func writeCombined(sb *strings.Builder, title string, parts []Combined, loc *time.Location, limit int, pick func(Buckets) []store.Item) {
	var lines []string
	for _, p := range parts {
		for _, it := range pick(p.Buckets) {
			lines = append(lines, fmt.Sprintf("- %s: %s\n", p.Child, line(it, loc)))
		}
	}
	if len(lines) == 0 {
		return
	}
	fmt.Fprintf(sb, "\n%s\n", title)
	for i, l := range lines {
		if limit > 0 && i >= limit {
			fmt.Fprintf(sb, "- … and %d more with no due date (see the dashboard)\n", len(lines)-limit)
			break
		}
		sb.WriteString(l)
	}
}

func writeCombinedMessages(sb *strings.Builder, parts []Combined, loc *time.Location) {
	var lines []string
	for _, p := range parts {
		for _, it := range p.Buckets.Messages {
			when := ""
			if it.DueAt != nil {
				when = " (" + it.DueAt.In(loc).Format("Mon 02 Jan 15:04") + ")"
			}
			lines = append(lines, fmt.Sprintf("- %s: %s%s\n", p.Child, it.Title, when))
		}
	}
	if len(lines) == 0 {
		return
	}
	sb.WriteString("\nMESSAGES\n")
	for _, l := range lines {
		sb.WriteString(l)
	}
}

// line renders one actionable item for the brief.
func line(it store.Item, loc *time.Location) string {
	subject := strings.TrimSpace(it.Subject)
	title := strings.TrimSpace(it.Title)
	switch {
	case subject != "" && subject != title:
		title = subject + ": " + title
	}
	due := ""
	if it.DueAt != nil {
		due = " (due " + it.DueAt.In(loc).Format("Mon 02 Jan 15:04") + ")"
	}
	status := Status(it.Body)
	mark := ""
	if status != "" && status != "pending" {
		mark = " [" + status + "]"
	}
	return title + due + mark
}

// CombinedBrief is one child's block of the combined brief, in the required
// order: Finn's block first, then Harry's (FR-9).
type CombinedBrief struct {
	Child   string
	Buckets Buckets
}

// RenderBrief writes one child's block in the required Phase 7 shape (FR-9,
// FR-16, FR-17, FR-18):
//
//	=== FINN ===
//	PERIODS TODAY
//	EVENTS TODAY
//	OVERDUE
//	DUE IN FUTURE
//
// An empty section is printed with "none"; it is never omitted silently.
// decode turns a raw lesson title into plain English (FR-17); pass nil to
// render the raw codes.
func RenderBrief(child string, b Buckets, decode func(string) string, loc *time.Location) string {
	if loc == nil {
		loc = time.UTC
	}
	var sb strings.Builder
	fmt.Fprintf(&sb, "=== %s ===\n", strings.ToUpper(strings.TrimSpace(child)))

	writeBriefPeriods(&sb, b.PeriodsToday, decode, loc)
	writeBriefEvents(&sb, b.EventsToday, decode, loc)
	writeBriefWork(&sb, "OVERDUE", b.Overdue, loc)
	writeBriefFuture(&sb, b, loc)
	return sb.String()
}

// RenderCombinedBrief writes the single brief for Jo and Sam (FR-14) as two
// separate blocks — Finn first, then Harry — and never interleaves them (FR-9).
func RenderCombinedBrief(parts []CombinedBrief, decode func(string) string, loc *time.Location) string {
	blocks := make([]string, 0, len(parts))
	for _, p := range parts {
		blocks = append(blocks, RenderBrief(p.Child, p.Buckets, decode, loc))
	}
	return strings.Join(blocks, "\n")
}

// writeBriefPeriods lists the child's own periods for today, decoded (FR-17).
func writeBriefPeriods(sb *strings.Builder, items []store.Item, decode func(string) string, loc *time.Location) {
	sb.WriteString("\nPERIODS TODAY\n")
	if len(items) == 0 {
		sb.WriteString("- none\n")
		return
	}
	for _, it := range items {
		title := strings.TrimSpace(it.Title)
		if decode != nil {
			title = decode(title)
		}
		when := ""
		if it.DueAt != nil {
			when = " (" + it.DueAt.In(loc).Format("15:04") + ")"
		}
		fmt.Fprintf(sb, "- %s%s\n", title, when)
	}
}

// writeBriefEvents lists today's major school events (FR-9b), decoded through
// the same map as periods so an ensemble or a concert reads as plain English
// (FR-17). Unknown codes stay raw.
func writeBriefEvents(sb *strings.Builder, items []store.Item, decode func(string) string, loc *time.Location) {
	sb.WriteString("\nEVENTS TODAY\n")
	if len(items) == 0 {
		sb.WriteString("- none\n")
		return
	}
	for _, it := range items {
		title := strings.TrimSpace(it.Title)
		if decode != nil {
			title = decode(title)
		}
		when := ""
		if it.DueAt != nil {
			when = " (" + it.DueAt.In(loc).Format("15:04") + ")"
		}
		fmt.Fprintf(sb, "- %s%s\n", title, when)
	}
}

// writeBriefWork lists outstanding work (FR-9c).
func writeBriefWork(sb *strings.Builder, title string, items []store.Item, loc *time.Location) {
	fmt.Fprintf(sb, "\n%s\n", title)
	if len(items) == 0 {
		sb.WriteString("- none\n")
		return
	}
	for _, it := range items {
		fmt.Fprintf(sb, "- %s\n", line(it, loc))
	}
}

// writeBriefFuture lists work due today or later (FR-9d). The undated tail is
// never dumped: it is one line with a count and a pointer to the dashboard
// (FR-18).
func writeBriefFuture(sb *strings.Builder, b Buckets, loc *time.Location) {
	sb.WriteString("\nDUE IN FUTURE\n")
	wrote := false
	for _, it := range b.FutureWork {
		fmt.Fprintf(sb, "- %s\n", line(it, loc))
		wrote = true
	}
	if n := len(b.NoDue); n > 0 {
		fmt.Fprintf(sb, "- %d task(s) with no due date (see the dashboard)\n", n)
		wrote = true
	}
	if !wrote {
		sb.WriteString("- none\n")
	}
}