cctally 1.7.4 → 1.8.0

package/bin/_cctally_tui.py

@@ -808,55 +808,18 @@ class TuiCurrentWeek:
     five_hour_block: dict | None = None
 
 
-@dataclass
-class TuiTrendRow:
-    week_label: str              # e.g. "Apr 14"
-    week_start_at: dt.datetime
-    used_pct: float | None       # None when the week has a cost snapshot
-                                 # but no usage snapshot (phantom weeks)
-    dollars_per_percent: float | None
-    delta_dpp: float | None      # vs prior week
-    spark_height: int            # 1..8 normalized
-    is_current: bool
-
-
-@dataclass
-class WeeklyPeriodRow:
-    """One subscription-week row for the dashboard's Weekly panel/modal.
-
-    `models` is a list of `{model, display, chip, cost_usd, cost_pct}`
-    dicts sorted by `cost_usd` descending. Pre-bucketed in Python so
-    the React layer never re-derives per-model coloring.
-    """
-    label: str                          # "04-23" — MM-DD of the week start
-    cost_usd: float
-    total_tokens: int
-    input_tokens: int
-    output_tokens: int
-    cache_creation_tokens: int
-    cache_read_tokens: int
-    used_pct: float | None              # from weekly_usage_snapshots overlay
-    dollar_per_pct: float | None        # cost / used_pct when used_pct > 0
-    delta_cost_pct: float | None        # (cost - prev_cost) / prev_cost
-    is_current: bool
-    models: list[dict[str, Any]]
-    week_start_at: str                  # ISO-8601 with tz, from SubWeek.start_ts
-    week_end_at: str                    # ISO-8601 with tz, from SubWeek.end_ts
-
-
-@dataclass
-class MonthlyPeriodRow:
-    """One calendar-month row for the dashboard's Monthly panel/modal."""
-    label: str                          # "YYYY-MM"
-    cost_usd: float
-    total_tokens: int
-    input_tokens: int
-    output_tokens: int
-    cache_creation_tokens: int
-    cache_read_tokens: int
-    delta_cost_pct: float | None
-    is_current: bool
-    models: list[dict[str, Any]]
+# ---- View-model row dataclasses moved to bin/_lib_view_models.py ----
+# Re-exported here so `from _cctally_tui import TuiTrendRow` and
+# `ns["TuiTrendRow"]` direct-dict reads in tests keep resolving. The
+# **extended** TuiTrendRow (spec §4.1: +10 nullable fields) is imported
+# from the same module; the new fields default to None so existing TUI
+# / dashboard fixtures that construct TuiTrendRow positionally stay
+# byte-stable.
+from _lib_view_models import (  # noqa: E402
+    TuiTrendRow,
+    WeeklyPeriodRow,
+    MonthlyPeriodRow,
+)
 
 
 @dataclass
@@ -878,43 +841,8 @@ class BlocksPanelRow:
     label: str             # "HH:MM MMM DD" in local tz, e.g. "14:00 Apr 26"
 
 
-@dataclass
-class DailyPanelRow:
-    """One row of the dashboard's Daily heatmap panel.
-
-    `intensity_bucket` is the server-computed quintile bucket (0..5) —
-    bucket 0 is reserved for zero-cost days; buckets 1..5 are quintiles
-    over non-zero days.
-
-    v2.3: Added per-day token rollup + `cache_hit_pct` so the Daily
-    detail modal can surface the same fields the CLI's `daily` command
-    shows. Defaults preserve compatibility with `_empty_dashboard_snapshot`
-    and any pre-v2.3 fixture that omits the new fields.
-    """
-    date: str              # local-tz YYYY-MM-DD
-    label: str             # "MM-DD" — pre-formatted, mirrors Weekly/Monthly idiom
-    cost_usd: float
-    is_today: bool
-    intensity_bucket: int  # 0..5
-    models: list[dict[str, Any]]   # ModelCostRow shape, sorted desc by cost
-    # ---- v2.3 additions: Daily modal token + cache rollup ----
-    input_tokens: int = 0
-    output_tokens: int = 0
-    cache_creation_tokens: int = 0
-    cache_read_tokens: int = 0
-    total_tokens: int = 0
-    cache_hit_pct: float | None = None
-
-
-@dataclass
-class TuiSessionRow:
-    started_at: dt.datetime
-    duration_minutes: float
-    model_primary: str           # first model used in the session
-    cost_usd: float
-    cache_hit_pct: float | None
-    project_label: str           # basename of project_path
-    session_id: str              # full session UUID (v2: needed for session-detail modal)
+# DailyPanelRow + TuiSessionRow moved to bin/_lib_view_models.py — re-export.
+from _lib_view_models import DailyPanelRow, TuiSessionRow  # noqa: E402
 
 
 @dataclass
@@ -1096,6 +1024,26 @@ class DataSnapshot:
     # at sync-thread time so ``snapshot_to_envelope`` stays a pure
     # renderer; empty list when no current 5h block is bound.
     five_hour_milestones: list[dict] = field(default_factory=list)
+    # ---- view-model unification (Bundle 1): pre-computed totals ----
+    # Populated by the sync thread as sum-over-visible-rows over the
+    # panel rows ``_dashboard_build_{daily,monthly,weekly}_periods``
+    # returned (see ``_tui_build_snapshot``); the dashboard envelope
+    # adapter emits these as ``<domain>.total_cost_usd`` /
+    # ``total_tokens`` so the React panels stop running
+    # ``rows.reduce(...)`` in JS. Sum-over-visible-rows is a structural
+    # invariant: ``total === sum(rows[*].cost_usd)`` by construction —
+    # see ``test_weekly_envelope_total_matches_sum_of_visible_rows``.
+    # ``trend_avg_dollars_per_pct`` is sourced from ``build_trend_view``
+    # (3-sample-rule mean per spec §4.3). Defaults preserve
+    # compatibility with pre-Bundle-1 fixture modules that construct
+    # ``DataSnapshot`` positionally. Spec §6.6.
+    daily_total_cost_usd: float = 0.0
+    daily_total_tokens: int = 0
+    monthly_total_cost_usd: float = 0.0
+    monthly_total_tokens: int = 0
+    weekly_total_cost_usd: float = 0.0
+    weekly_total_tokens: int = 0
+    trend_avg_dollars_per_pct: float | None = None
 
     @classmethod
     def synthesize_for_marketing(cls, *, as_of_iso: str) -> "DataSnapshot":
@@ -1495,158 +1443,16 @@ def _tui_build_trend(
 ) -> list[TuiTrendRow]:
     """Build the last `count` trend rows, chronological (oldest first).
 
-    `cmd_report` inlines its row build rather than delegating to a helper,
-    so instead of refactoring the subcommand we call the same underlying
-    loaders (`get_recent_weeks` + `get_latest_usage_for_week` +
-    `get_latest_cost_for_week`) directly here. Output for the shared
-    columns (`week_start_at`, `used_pct`, `dollars_per_percent`) matches
-    `cmd_report` byte-for-byte — verified in the bundle regression diff.
+    Bundle 1 / Task 10: wraps the unified ``build_trend_view`` kernel
+    (spec §5.4) — the loop body that used to live here moved into
+    ``bin/_lib_view_models.build_trend_view``. The TUI snapshot module
+    consumes the first 7 ``TuiTrendRow`` fields and ignores the 10
+    extended fields (which exist for cmd_report's JSON contract).
     """
-    # `get_recent_weeks` returns WeekRef rows DESC by week_start_date,
-    # already routed through `_apply_reset_events_to_weekrefs` so credited
-    # weeks come back as TWO refs (pre-credit + post-credit) sharing the
-    # same `WeekRef.key`.
-    week_refs = get_recent_weeks(conn, max(1, count))
-
-    # Figure out which week_ref corresponds to the current subscription week.
-    # Mirrors `cmd_report`'s Bug D pattern: build a current_ref from the
-    # latest usage snapshot, route it through `_apply_reset_events_to_weekrefs`
-    # so its `week_start_at` reflects the post-credit segment (or the
-    # original start for non-credit weeks), then disambiguate the
-    # synthesized pre-credit ref from the live post-credit ref via BOTH
-    # `key` AND `week_start_at`. Key-only equality marks both segments
-    # as current, which is why the dashboard's trend panel previously
-    # showed two adjacent rows both highlighted as "current" with
-    # identical 4.0% values on the user's live in-place credit data.
-    latest_usage = conn.execute(
-        "SELECT week_start_date, week_end_date "
-        "FROM weekly_usage_snapshots "
-        "ORDER BY captured_at_utc DESC, id DESC LIMIT 1"
-    ).fetchone()
-    current_key: str | None = None
-    current_week_start_at: str | None = None
-    if latest_usage is not None and latest_usage["week_start_date"] is not None:
-        current_key = latest_usage["week_start_date"]
-        try:
-            c = _cctally()
-            canon_start, canon_end = c._get_canonical_boundary_for_date(
-                conn, latest_usage["week_start_date"]
-            )
-            current_ref = make_week_ref(
-                week_start_date=latest_usage["week_start_date"],
-                week_end_date=latest_usage["week_end_date"],
-                week_start_at=canon_start,
-                week_end_at=canon_end,
-            )
-            _adjusted = c._apply_reset_events_to_weekrefs(conn, [current_ref])
-            if _adjusted:
-                current_week_start_at = _adjusted[0].week_start_at
-        except (ValueError, sqlite3.DatabaseError, AttributeError):
-            current_week_start_at = None
-
-    # Build an intermediate list of (week_ref, used_pct, dpp) in oldest-first
-    # chronological order.
-    chrono = list(reversed(week_refs))
-    # Split-key set (Bug D): credited weeks appear twice in `week_refs`
-    # with identical `WeekRef.key`. For those keys ONLY, pin
-    # `as_of_utc=week_ref.week_end_at` so each segment finds its own
-    # latest snapshot — without this both segments collapse to the
-    # post-credit snapshot's weekly_percent. Non-credit weeks (single
-    # ref per key) keep the legacy unfiltered lookup.
-    _split_keys = {
-        r.key
-        for r in week_refs
-        if sum(1 for x in week_refs if x.key == r.key) > 1
-    }
-    intermediate: list[tuple[Any, float | None, float | None]] = []
-    for week_ref in chrono:
-        usage = get_latest_usage_for_week(
-            conn,
-            week_ref,
-            as_of_utc=(
-                week_ref.week_end_at if week_ref.key in _split_keys else None
-            ),
-        )
-        # See cmd_report for why reset-affected weeks skip the cost cache
-        # and live-compute from session_entries over the effective range.
-        if _week_ref_has_reset_event(conn, week_ref):
-            cost_usd = _compute_cost_for_weekref(week_ref)
-        else:
-            cost = get_latest_cost_for_week(conn, week_ref)
-            cost_usd = float(cost["cost_usd"]) if cost else None
-        percent = float(usage["weekly_percent"]) if usage else None
-        ratio = (cost_usd / percent) if (
-            cost_usd is not None and percent and percent > 0
-        ) else None
-        intermediate.append((week_ref, percent, ratio))
-
-    # Normalize dpp into spark heights 1..8 across the window.
-    dpps = [d for _, _, d in intermediate if d is not None]
-    if dpps:
-        lo, hi = min(dpps), max(dpps)
-        span = (hi - lo) or 1e-9
-    else:
-        lo, hi, span = 0.0, 1.0, 1e-9
-
-    out: list[TuiTrendRow] = []
-    prev_dpp: float | None = None
-    for week_ref, percent, dpp in intermediate:
-        delta = (dpp - prev_dpp) if (dpp is not None and prev_dpp is not None) else None
-        spark = 1
-        if dpp is not None:
-            spark = int(round((dpp - lo) / span * 7)) + 1
-            spark = max(1, min(8, spark))
-        # WeekRef.week_start is a date; synthesize a UTC datetime so
-        # TuiTrendRow carries a timezone-aware instant (prefer the explicit
-        # week_start_at if present).
-        if week_ref.week_start_at:
-            week_start_dt = parse_iso_datetime(
-                week_ref.week_start_at, "week_start_at"
-            )
-            week_label = format_display_dt(
-                week_start_dt, display_tz, fmt="%b %d", suffix=False,
-            )
-        else:
-            week_start_dt = dt.datetime.combine(
-                week_ref.week_start, dt.time(0, 0), dt.timezone.utc
-            )
-            # No real boundary instant — format the calendar date directly so
-            # localizing midnight-UTC doesn't shift it to the prior day in
-            # zones west of UTC (e.g. 2026-04-14 → "Apr 13" in America/New_York).
-            week_label = week_ref.week_start.strftime("%b %d")
-        # Bug G (v1.7.2 round-5): match on BOTH `key` AND `week_start_at`
-        # for credited weeks so the pre-credit synthesized ref doesn't
-        # also light up as "current" — both refs share `key`, only their
-        # `week_start_at` differs (post-credit = effective reset moment,
-        # pre-credit = original API-derived start). Non-credit weeks
-        # have only one ref per key so `week_start_at` matching is
-        # automatic. When `current_week_start_at` is None (no reset
-        # event for the current week, or the resolution above failed),
-        # falls back to legacy key-only matching.
-        is_cur = (
-            current_key is not None
-            and week_ref.key == current_key
-            and (
-                current_week_start_at is None
-                or week_ref.week_start_at == current_week_start_at
-            )
-        )
-        out.append(TuiTrendRow(
-            week_label=week_label,
-            week_start_at=week_start_dt,
-            # Preserve None when no usage snapshot exists for this week —
-            # matches `cmd_report`'s "n/a" rendering (9980) and avoids
-            # fabricating a 0.0% row for the phantom-week case (cost
-            # snapshot present, usage snapshot absent).
-            used_pct=float(percent) if percent is not None else None,
-            dollars_per_percent=dpp,
-            delta_dpp=delta,
-            spark_height=spark,
-            is_current=is_cur,
-        ))
-        if dpp is not None:
-            prev_dpp = dpp
-    return out
+    c = _cctally()
+    view = c.build_trend_view(conn, now_utc=now_utc, n=max(1, count),
+                               display_tz=display_tz)
+    return list(view.rows)
 
 
 def _tui_build_weekly_history(
@@ -1685,6 +1491,14 @@ def _tui_build_sessions(
 
     When `skip_sync=True`, honors the parent's `--no-sync` intent: no
     ingest pass, just read whatever is already cached.
+
+    Bundle 2 / Task 15: wraps the unified ``build_sessions_view``
+    kernel — the prior 40-line inline-derivation body now lives at
+    ``bin/_lib_view_models.build_sessions_view``. The TUI keeps
+    ownership of the bounded 365-day scan window (rationale below) and
+    consumes ``view.rows`` (the typed ``TuiSessionRow`` tuple). The
+    view's parallel ``view.aggregated`` is reserved for the CLI / share
+    surfaces; the TUI doesn't need ``ClaudeSessionUsage`` fields.
     """
     # Bounded scan window — the sessions pane promises "last `limit`". A
     # 365-day scan covers virtually all users (even one-session-every-few-days
@@ -1693,23 +1507,11 @@ def _tui_build_sessions(
     # on every entry in the window before slicing.
     range_start = now_utc - dt.timedelta(days=365)
     entries = get_claude_session_entries(range_start, now_utc, skip_sync=skip_sync)
-    sessions = _aggregate_claude_sessions(entries)   # last_activity desc
-    out: list[TuiSessionRow] = []
-    for s in sessions[:limit]:
-        duration_min = (s.last_activity - s.first_activity).total_seconds() / 60.0
-        total_read = s.cache_read_tokens
-        total_io = s.input_tokens + s.cache_creation_tokens + s.cache_read_tokens
-        cache_pct = (total_read / total_io * 100) if total_io > 0 else None
-        out.append(TuiSessionRow(
-            started_at=s.first_activity,
-            duration_minutes=duration_min,
-            model_primary=(s.models[0] if s.models else "—"),
-            cost_usd=s.cost_usd,
-            cache_hit_pct=cache_pct,
-            project_label=os.path.basename(s.project_path) or s.project_path,
-            session_id=s.session_id,
-        ))
-    return out
+    c = _cctally()
+    view = c.build_sessions_view(
+        entries, now_utc=now_utc, limit=limit, display_tz=None,
+    )
+    return list(view.rows)
 
 
 @dataclass
@@ -1853,10 +1655,19 @@ def _tui_build_snapshot(
             fc = _tui_build_forecast(conn, now_utc, skip_sync=skip_sync)
         except Exception as exc:
             errors.append(f"forecast: {exc}")
+        # Trend: source from build_trend_view so we capture the 3-sample
+        # avg_dollars_per_pct alongside the rows. The TUI build path
+        # historically called _tui_build_trend (which now wraps the
+        # builder); calling the builder directly here saves one
+        # `_aggregate_*` round-trip.
+        trend_avg_dpp = None
         try:
-            trend = _tui_build_trend(
-                conn, now_utc, skip_sync=skip_sync, display_tz=_build_display_tz,
+            c = _cctally()
+            _trend_view = c.build_trend_view(
+                conn, now_utc=now_utc, n=8, display_tz=_build_display_tz,
             )
+            trend = list(_trend_view.rows)
+            trend_avg_dpp = _trend_view.avg_dollars_per_pct
         except Exception as exc:
             errors.append(f"trend: {exc}")
         try:
@@ -1881,17 +1692,53 @@ def _tui_build_snapshot(
         except Exception as exc:
             errors.append(f"weekly-history: {exc}")
         # ---- v2.1 additions: dashboard Weekly / Monthly panels ----
+        # Sync-thread view-model totals (spec §6.6): sum directly over
+        # the panel rows the dashboard ACTUALLY renders. The previous
+        # implementation called ``build_weekly_view`` a second time to
+        # capture totals, but that builder doesn't see the Bug-K
+        # pre-credit synthesized rows that ``_dashboard_build_weekly_periods``
+        # layers on top (``_apply_reset_events_to_subweeks`` shifts the
+        # post-reset SubWeek's ``start_ts`` so the pre-credit interval
+        # has no SubWeek for ``_aggregate_weekly`` to bucket). On credit
+        # weeks the sync-thread total understated the rendered footer by
+        # hundreds of dollars (~$372 in the v1.7.2 round-5 data).
+        # Sum-over-visible-rows is a structural invariant — see
+        # ``test_weekly_envelope_total_matches_sum_of_visible_rows``.
+        weekly_total_cost_usd = 0.0
+        weekly_total_tokens = 0
         try:
             weekly_periods = _dashboard_build_weekly_periods(
                 conn, now_utc, n=12, skip_sync=skip_sync
             )
+            # ``sum(..., 0.0)`` pins the type to ``float`` on empty rows so
+            # the envelope stays byte-stable with the pre-fix ``0.0`` shape
+            # (the dashboard fixture goldens assert exact JSON match).
+            weekly_total_cost_usd = sum(
+                (r.cost_usd for r in weekly_periods), 0.0,
+            )
+            weekly_total_tokens = sum(
+                (r.total_tokens for r in weekly_periods), 0,
+            )
         except Exception as exc:
             errors.append(f"weekly-periods: {exc}")
+        # Sync-thread view-model totals (spec §6.6): sum-over-visible-rows
+        # (same invariant as weekly above). Monthly has no Bug-K analogue,
+        # but coupling the footer total to the panel-row source of truth
+        # eliminates a parallel ``build_monthly_view`` pass that did the
+        # same arithmetic with no behavioral upside.
+        monthly_total_cost_usd = 0.0
+        monthly_total_tokens = 0
         try:
             monthly_periods = _dashboard_build_monthly_periods(
                 conn, now_utc, n=12, skip_sync=skip_sync,
                 display_tz=_build_display_tz,
             )
+            monthly_total_cost_usd = sum(
+                (r.cost_usd for r in monthly_periods), 0.0,
+            )
+            monthly_total_tokens = sum(
+                (r.total_tokens for r in monthly_periods), 0,
+            )
         except Exception as exc:
             errors.append(f"monthly-periods: {exc}")
         # ---- v2.2 additions: dashboard Blocks / Daily panels ----
@@ -1906,11 +1753,25 @@ def _tui_build_snapshot(
                 )
         except Exception as exc:
             errors.append(f"blocks-panel: {exc}")
+        # Sync-thread view-model totals (Bundle 1 / spec §6.6):
+        # sum-over-visible-rows (same invariant as weekly/monthly above).
+        # Gap days in the materialized panel carry ``cost_usd=0.0`` /
+        # ``total_tokens=0``, so summing the panel rows preserves the
+        # gap-free totals semantically — and removes a duplicate
+        # ``build_daily_view`` pass that did the same arithmetic.
+        daily_total_cost_usd = 0.0
+        daily_total_tokens = 0
         try:
             daily_panel = _dashboard_build_daily_panel(
                 conn, now_utc, n=30, skip_sync=skip_sync,
                 display_tz=_build_display_tz,
             )
+            daily_total_cost_usd = sum(
+                (r.cost_usd for r in daily_panel), 0.0,
+            )
+            daily_total_tokens = sum(
+                (r.total_tokens for r in daily_panel), 0,
+            )
         except Exception as exc:
             errors.append(f"daily-panel: {exc}")
         # ---- threshold-actions T5: alerts envelope array ----
@@ -1951,6 +1812,13 @@ def _tui_build_snapshot(
             daily_panel=daily_panel,
             alerts=alerts,
             five_hour_milestones=fh_milestones,
+            daily_total_cost_usd=daily_total_cost_usd,
+            daily_total_tokens=daily_total_tokens,
+            monthly_total_cost_usd=monthly_total_cost_usd,
+            monthly_total_tokens=monthly_total_tokens,
+            weekly_total_cost_usd=weekly_total_cost_usd,
+            weekly_total_tokens=weekly_total_tokens,
+            trend_avg_dollars_per_pct=trend_avg_dpp,
         )
     finally:
         conn.close()