cctally 1.22.1 → 1.22.2

package/bin/cctally

@@ -603,6 +603,13 @@ cmd_alerts_test = _cctally_alerts.cmd_alerts_test
 _cctally_sync_week = _load_sibling("_cctally_sync_week")
 cmd_sync_week = _cctally_sync_week.cmd_sync_week
 
+# Eager re-export of bin/_cctally_project.py — `cmd_project` is invoked
+# only via the parser's `set_defaults(func=c.cmd_project)`, which resolves
+# through cctally's namespace, so it must live here. The 4 helpers stay
+# module-private (no external caller).
+_cctally_project = _load_sibling("_cctally_project")
+cmd_project = _cctally_project.cmd_project
+
 
 # config.json reader/writer/lock + validators + `cctally config` entry point.
 # Eager-loaded with per-symbol re-export so bare-name callers in cctally
@@ -6207,684 +6214,6 @@ def cmd_codex_session(args: argparse.Namespace) -> int:
     return 0
 
 
-def _load_week_snapshots(
-    since: dt.datetime, until: dt.datetime
-) -> dict[dt.datetime, float]:
-    """Return {week_start_utc -> max(weekly_percent)} for weeks intersecting
-    the [since, until] range.
-
-    Reads the `weekly_percent` column of `weekly_usage_snapshots` (authoritative
-    column name — NOT `used_7d_percent`). A week's "used %" is the maximum
-    snapshot captured within that week (the monotonic-within-window invariant:
-    weekly_percent only increases across the life of a week). Skips rows
-    whose `week_start_at` or `week_end_at` are NULL (pre-migration legacy
-    rows that only carried date granularity).
-
-    MAX is computed in Python keyed on the parsed UTC datetime so that rows
-    holding different string spellings of the same instant (e.g. `+00:00` vs
-    `+03:00` from pre-UTC-cast canonicalizer history) coalesce into one
-    bucket instead of splitting and silently dropping the higher value.
-
-    Returns an empty dict if the stats DB has no relevant rows.
-    """
-    conn = open_db()
-    try:
-        cur = conn.execute(
-            "SELECT week_start_at, weekly_percent FROM weekly_usage_snapshots "
-            "WHERE week_start_at IS NOT NULL "
-            "AND week_end_at IS NOT NULL "
-            "AND datetime(week_start_at) < datetime(?) "
-            "AND datetime(week_end_at) > datetime(?)",
-            (until.isoformat(), since.isoformat()),
-        )
-        result: dict[dt.datetime, float] = {}
-        for ws_iso, pct in cur.fetchall():
-            if ws_iso is None or pct is None:
-                continue
-            ws = dt.datetime.fromisoformat(
-                str(ws_iso).replace("Z", "+00:00")
-            )
-            key = ws.astimezone(dt.timezone.utc)
-            pct_f = float(pct)
-            prev = result.get(key)
-            if prev is None or pct_f > prev:
-                result[key] = pct_f
-        return result
-    finally:
-        conn.close()
-
-
-def _accumulate_entry_into_bucket(
-    b: dict,
-    entry: "_JoinedClaudeEntry",
-    pre_computed_cost: float | None = None,
-) -> None:
-    """Add one joined-Claude entry's tokens, cost, session-id, and timestamps
-    into a project×week bucket dict.
-
-    Cost is computed via the same `_calculate_entry_cost(model, usage_dict,
-    mode="auto", cost_usd=...)` path used by `_aggregate_cache_by_session`
-    (the other `_JoinedClaudeEntry` consumer) so pricing updates flow through
-    uniformly. Per-model sub-buckets mirror the parent bucket's shape.
-
-    `pre_computed_cost`: if callers have already invoked `_calculate_entry_cost`
-    for this entry (e.g. to also feed the attribution denominator in
-    `cmd_project`), pass it in to avoid double work.
-    """
-    # Mirror `_aggregate_claude_sessions`: NULL session_id falls back to the
-    # source-file basename so distinct files don't collapse into one bucket.
-    if entry.session_id:
-        sid = entry.session_id
-    else:
-        sid = os.path.splitext(os.path.basename(entry.source_path))[0]
-    b["sessions"].add(sid)
-    if entry.timestamp < b["first_seen"]:
-        b["first_seen"] = entry.timestamp
-    if entry.timestamp > b["last_seen"]:
-        b["last_seen"] = entry.timestamp
-    b["input"] += entry.input_tokens
-    b["output"] += entry.output_tokens
-    b["cache_write"] += entry.cache_creation_tokens
-    b["cache_read"] += entry.cache_read_tokens
-    if pre_computed_cost is not None:
-        cost = pre_computed_cost
-    else:
-        cost = _calculate_entry_cost(
-            entry.model,
-            {
-                "input_tokens": entry.input_tokens,
-                "output_tokens": entry.output_tokens,
-                "cache_creation_input_tokens": entry.cache_creation_tokens,
-                "cache_read_input_tokens": entry.cache_read_tokens,
-            },
-            mode="auto",
-            cost_usd=entry.cost_usd,
-        )
-    b["cost_usd"] += cost
-    model = entry.model or "(unknown-model)"
-    mb = b["models"].get(model)
-    if mb is None:
-        mb = {
-            "cost_usd": 0.0,
-            "input": 0, "output": 0,
-            "cache_write": 0, "cache_read": 0,
-            "first_seen": entry.timestamp, "last_seen": entry.timestamp,
-        }
-        b["models"][model] = mb
-    if entry.timestamp < mb["first_seen"]:
-        mb["first_seen"] = entry.timestamp
-    if entry.timestamp > mb["last_seen"]:
-        mb["last_seen"] = entry.timestamp
-    mb["cost_usd"] += cost
-    mb["input"] += entry.input_tokens
-    mb["output"] += entry.output_tokens
-    mb["cache_write"] += entry.cache_creation_tokens
-    mb["cache_read"] += entry.cache_read_tokens
-
-
-def _project_json_output(
-    *,
-    since: dt.datetime,
-    until: dt.datetime,
-    weeks_in_range: int,
-    group_mode: str,
-    rows: list[dict],
-    weeks_missing_snapshot: set[dt.datetime],
-    warnings: list[str],
-    include_breakdown: bool,
-    week_snapshots: dict[dt.datetime, float],
-) -> str:
-    """Render the project subcommand's --json payload per spec §4.
-
-    Accepts rows already sorted by the caller (so ordering flags apply
-    uniformly to both terminal and JSON modes). Aggregates `totals.costUsd`
-    from `rows` and `totals.usedPercent` from `week_snapshots` (sum over
-    all weeks with snapshots in the range — matches the conservation-law
-    denominator used by per-project attribution). `models[]` is included
-    per-project only when `--breakdown` is requested to avoid payload bloat.
-    """
-    total_cost = sum(r["cost_usd"] for r in rows)
-    # Aggregate used % across all weeks with snapshots in the range.
-    total_used_pct: float | None
-    if week_snapshots:
-        total_used_pct = sum(week_snapshots.values())
-    else:
-        total_used_pct = None
-
-    def _fmt_dt(ts: dt.datetime) -> str:
-        return ts.astimezone(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-
-    projects_json = []
-    for row in rows:  # rows come already sorted by caller
-        p = {
-            "displayKey": row["key"].display_key,
-            "projectPath": row["key"].bucket_path,
-            "gitRoot": row["key"].git_root,
-            "sessions": len(row["sessions"]),
-            "firstSeen": _fmt_dt(row["first_seen"]),
-            "lastSeen": _fmt_dt(row["last_seen"]),
-            "inputTokens": row["input"],
-            "outputTokens": row["output"],
-            "cacheWriteTokens": row["cache_write"],
-            "cacheReadTokens": row["cache_read"],
-            "costUsd": round(row["cost_usd"], 4),
-            "attributedUsedPercent": (
-                round(row["attributed_pct"], 4)
-                if row["attributed_pct"] is not None else None
-            ),
-            "costPerPercent": (
-                round(row["cost_per_pct"], 4)
-                if row["cost_per_pct"] is not None else None
-            ),
-        }
-        if include_breakdown:
-            p["models"] = [
-                {
-                    "model": mname,
-                    "firstSeen": _fmt_dt(mb["first_seen"]),
-                    "lastSeen": _fmt_dt(mb["last_seen"]),
-                    "inputTokens": mb["input"],
-                    "outputTokens": mb["output"],
-                    "cacheWriteTokens": mb["cache_write"],
-                    "cacheReadTokens": mb["cache_read"],
-                    "costUsd": round(mb["cost_usd"], 4),
-                }
-                for mname, mb in sorted(row["models"].items())
-            ]
-        projects_json.append(p)
-
-    payload = {
-        "rangeStart": since.date().isoformat(),
-        "rangeEnd": until.date().isoformat(),
-        "weeksInRange": weeks_in_range,
-        "groupMode": group_mode,
-        "totals": {
-            "costUsd": round(total_cost, 4),
-            "usedPercent": (
-                round(total_used_pct, 4) if total_used_pct is not None else None
-            ),
-            "weeklyAttributionAvailable": len(weeks_missing_snapshot) == 0,
-        },
-        "projects": projects_json,
-        "warnings": warnings,
-    }
-    return json.dumps(payload, indent=2)
-
-
-def _project_sort_key(row: dict, sort_by: str, order: str):
-    """Return (primary, dname) where the primary is flipped to match
-    ``order``. Tie-break on dname ascending regardless of direction.
-
-    ``sort_by`` values align with argparse choices: cost|used|name|last-seen.
-    """
-    dname = row["key"].display_key.lower()
-    sign = -1 if order == "desc" else 1
-    if sort_by == "cost":
-        return (sign * row["cost_usd"], dname)
-    if sort_by == "used":
-        v = row["attributed_pct"] if row["attributed_pct"] is not None else -1
-        return (sign * v, dname)
-    if sort_by == "last-seen":
-        return (sign * row["last_seen"].timestamp(), dname)
-    if sort_by == "name":
-        # name is asc-natural; caller uses sorted(reverse=order=='desc').
-        return (dname,)
-    # Unreachable given argparse choices, but safe default.
-    return (sign * row["cost_usd"], dname)
-
-
-def cmd_project(args: argparse.Namespace) -> int:
-    """Roll entries up by project (git-root) with per-project usage attribution."""
-    _share_validate_args(args)
-    config = _load_claude_config_for_args(args)
-    # Session A (spec §7.2): bridge -z/--timezone into args.tz so the
-    # existing resolve_display_tz precedence absorbs the new alias.
-    _bridge_z_into_tz(args, config)
-    args._resolved_tz = resolve_display_tz(args, config)
-
-    # Flag-combination validation (must run before any expensive work).
-    if args.weeks is not None and args.weeks < 1:
-        eprint("Error: --weeks must be >= 1")
-        return 1
-    if args.weeks is not None and (args.since or args.until):
-        eprint("Error: --weeks cannot be combined with --since/--until")
-        return 1
-    if args.since and args.until:
-        # Parse both as dates using the same multi-format helper shape used
-        # elsewhere in the codebase so YYYY-MM-DD and YYYYMMDD both compare
-        # correctly (string compare alone breaks across mixed formats).
-        def _parse(raw: str) -> dt.date | None:
-            for fmt in ("%Y-%m-%d", "%Y%m%d"):
-                try:
-                    return dt.datetime.strptime(raw, fmt).date()
-                except ValueError:
-                    continue
-            return None
-
-        since_parsed = _parse(args.since)
-        until_parsed = _parse(args.until)
-        # Silent-skip if either date failed to parse: we only want to surface
-        # a "range order" error here when both inputs are well-formed. Any
-        # format error will be reported downstream by _parse_cli_date_range()
-        # so the user sees the parse problem first (not a misleading order
-        # complaint triggered by garbage input).
-        if since_parsed is not None and until_parsed is not None and since_parsed > until_parsed:
-            eprint("Error: --since must be <= --until")
-            return 1
-
-    now = _command_as_of()
-    conn = open_db()
-
-    # Resolve [since_dt, until_dt] in UTC.
-    if args.since or args.until:
-        parsed = _parse_cli_date_range(args, now_utc=now)
-        if isinstance(parsed, int):
-            return parsed
-        since_dt, until_dt = parsed
-        since_dt = since_dt.astimezone(dt.timezone.utc)
-        until_dt = until_dt.astimezone(dt.timezone.utc)
-    else:
-        # Default to the current subscription week; --weeks N extends backwards.
-        # Widen by 1us so the emit loop fires when `now` is exactly at a reset
-        # boundary (zero-width [now, now] makes Case A's `current < range_end`
-        # false, which would otherwise wrongly fall through to the Monday
-        # fallback for non-Monday-reset accounts).
-        current_weeks = _compute_subscription_weeks(
-            conn, now, now + dt.timedelta(microseconds=1), config=config,
-        )
-        if current_weeks:
-            cw_start = parse_iso_datetime(
-                current_weeks[0].start_ts, "week.start_ts"
-            ).astimezone(dt.timezone.utc)
-        else:
-            # No snapshots available: fall back to a Monday-anchored week.
-            cw_start = (now - dt.timedelta(days=now.weekday())).replace(
-                hour=0, minute=0, second=0, microsecond=0
-            )
-        if args.weeks is not None:
-            since_dt = cw_start - dt.timedelta(days=7 * (args.weeks - 1))
-        else:
-            since_dt = cw_start
-        until_dt = now
-
-    # Pre-compute subscription-week bounds for the query window so each entry
-    # can be bucketed onto a canonical subscription-week start_ts. Mirrors
-    # `_aggregate_weekly`'s bisect pattern (first-match-wins on overlap).
-    subweeks = _compute_subscription_weeks(
-        conn, since_dt, until_dt, config=config,
-    )
-    parsed_bounds: list[tuple[dt.datetime, dt.datetime]] = []
-    for sw in subweeks:
-        s_dt = parse_iso_datetime(sw.start_ts, "week.start_ts").astimezone(dt.timezone.utc)
-        e_dt = parse_iso_datetime(sw.end_ts, "week.end_ts").astimezone(dt.timezone.utc)
-        parsed_bounds.append((s_dt, e_dt))
-    week_starts = [b[0] for b in parsed_bounds]
-
-    def _week_start_for(ts: dt.datetime) -> dt.datetime | None:
-        """Return the canonical subscription-week start_dt for `ts`, or None
-        if `ts` falls outside every SubWeek interval (may happen near the
-        boundaries of the requested [since_dt, until_dt] window)."""
-        ts_utc = ts.astimezone(dt.timezone.utc)
-        idx = bisect.bisect_right(week_starts, ts_utc) - 1
-        if idx < 0:
-            return None
-        # First-match-wins on Anthropic reset-day-drift overlap (same
-        # walk-back as `_aggregate_weekly`).
-        while idx > 0:
-            prev_start, prev_end = parsed_bounds[idx - 1]
-            if prev_start <= ts_utc < prev_end:
-                idx -= 1
-            else:
-                break
-        s_dt, e_dt = parsed_bounds[idx]
-        if s_dt <= ts_utc < e_dt:
-            return s_dt
-        return None
-
-    # Pre-lower filter patterns (substring, OR semantics, repeatable).
-    project_patterns = [p.lower() for p in (args.project or [])]
-    model_patterns = [m.lower() for m in (args.model or [])]
-
-    # Widen scan to full subscription-week bounds so the attribution
-    # denominator includes ALL week cost, even entries outside the
-    # user's [since_dt, until_dt] slice. Visible buckets are still
-    # gated on the user slice below. Without this, a partial-week
-    # --since/--until slice understates the denominator and inflates
-    # every row's Used %.
-    if parsed_bounds:
-        scan_start = min(since_dt, parsed_bounds[0][0])
-        scan_end = max(until_dt, parsed_bounds[-1][1])
-    else:
-        scan_start, scan_end = since_dt, until_dt
-
-    resolver_cache: dict[str, ProjectKey] = {}
-    buckets: dict[tuple[ProjectKey, dt.datetime], dict] = {}
-    total_cost_by_week: dict[dt.datetime, float] = {}
-    unknown_entry_count = 0
-    missing_sid_count = 0
-
-    # Issue #89: materialize the joined-entry iterator once so we can
-    # (a) pre-compute the --debug report's scope (entries passing all
-    # rendered-row filters — user slice + --model + --project) BEFORE
-    # the aggregation loop runs and (b) preserve the existing
-    # aggregation semantics (denominator widened to ALL entries; visible
-    # rows only the post-filter subset). The list is small enough to
-    # hold (entries already in memory via the cache row factory).
-    joined_entries_all = list(get_claude_session_entries(scan_start, scan_end))
-
-    # Build the --debug report dataset: skip synthetic + out-of-window
-    # entries, then apply --model and --project filters (mirroring the
-    # exact predicate at the aggregation loop below). This must match
-    # the rendered scope, NOT the denominator scope.
-    if getattr(args, "debug", False):
-        filtered_for_report = []
-        for je in joined_entries_all:
-            if je.model == "<synthetic>":
-                continue
-            if _week_start_for(je.timestamp) is None:
-                continue
-            if je.timestamp < since_dt or je.timestamp > until_dt:
-                continue
-            if model_patterns:
-                mname = (je.model or "").lower()
-                if not any(p in mname for p in model_patterns):
-                    continue
-            key_for_filter = _resolve_project_key(
-                je.project_path, args.group, resolver_cache,
-            )
-            if not _project_filter_matches(key_for_filter, project_patterns):
-                continue
-            filtered_for_report.append(je)
-        _emit_debug_samples_if_set(
-            args,
-            [_usage_entry_from_joined(je) for je in filtered_for_report],
-            command_label="project",
-        )
-
-    for entry in joined_entries_all:
-        # Skip synthetic entries (Claude Code internal markers) to match
-        # `_aggregate_cache_by_session` / `_aggregate_claude_sessions`.
-        if entry.model == "<synthetic>":
-            continue
-
-        week_start = _week_start_for(entry.timestamp)
-        if week_start is None:
-            continue
-
-        entry_cost = _calculate_entry_cost(
-            entry.model,
-            {
-                "input_tokens": entry.input_tokens,
-                "output_tokens": entry.output_tokens,
-                "cache_creation_input_tokens": entry.cache_creation_tokens,
-                "cache_read_input_tokens": entry.cache_read_tokens,
-            },
-            mode="auto",
-            cost_usd=entry.cost_usd,
-        )
-
-        # Denominator: always contribute (whole-week attribution) so
-        # `--model`/`--project`/partial-slice do NOT rescale it.
-        total_cost_by_week[week_start] = (
-            total_cost_by_week.get(week_start, 0.0) + entry_cost
-        )
-
-        # User-slice gate: visible rows only include entries within
-        # [since_dt, until_dt]. Entries outside the slice still
-        # contributed to the denominator above.
-        if entry.timestamp < since_dt or entry.timestamp > until_dt:
-            continue
-
-        if model_patterns:
-            mname = (entry.model or "").lower()
-            if not any(p in mname for p in model_patterns):
-                continue
-
-        key = _resolve_project_key(entry.project_path, args.group, resolver_cache)
-        if key.is_unknown:
-            unknown_entry_count += 1
-
-        # --project filter: match against display_key OR the underlying
-        # path (git_root / bucket_path). Matching only display_key makes
-        # basename-collision suffixes (e.g. `foo (repos)`) impossible to
-        # select by their path segment.
-        if project_patterns:
-            dname = key.display_key.lower()
-            pname = (key.git_root or key.bucket_path or "").lower()
-            if not any((p in dname) or (p in pname) for p in project_patterns):
-                continue
-
-        if entry.session_id is None:
-            missing_sid_count += 1
-
-        bkey = (key, week_start)
-        b = buckets.get(bkey)
-        if b is None:
-            b = {
-                "key": key,
-                "week_start": week_start,
-                "sessions": set(),
-                "first_seen": entry.timestamp,
-                "last_seen": entry.timestamp,
-                "input": 0, "output": 0,
-                "cache_write": 0, "cache_read": 0,
-                "cost_usd": 0.0,
-                "models": {},
-            }
-            buckets[bkey] = b
-        _accumulate_entry_into_bucket(b, entry, pre_computed_cost=entry_cost)
-
-    if unknown_entry_count > 0:
-        eprint(
-            f"Warning: {unknown_entry_count} entries lacked project_path — "
-            f"run `cache-sync` to backfill."
-        )
-    if missing_sid_count > 0:
-        eprint(
-            f"Warning: {missing_sid_count} entries lacked session_files "
-            f"session_id — run `cache-sync` to backfill."
-        )
-
-    # --- Attribution math (Task 5) -----------------------------------------
-    # Load per-week `weekly_percent` (max within window) for every week that
-    # intersects [since_dt, until_dt]. Missing snapshots are tracked so we
-    # can surface `weeksMissingSnapshot` in the output — those weeks can't
-    # contribute to attributed %.
-    week_snapshots: dict[dt.datetime, float] = _load_week_snapshots(
-        since_dt, until_dt
-    )
-
-    # Set of every week the user asked about (from the computed SubWeek
-    # bounds), used to report `weeksInRange` and `weeksMissingSnapshot`
-    # independent of whether that week had any project activity.
-    weeks_in_range: set[dt.datetime] = {ws for ws in week_starts}
-    weeks_missing_snapshot: set[dt.datetime] = {
-        ws for ws in weeks_in_range if ws not in week_snapshots
-    }
-
-    # Collapse (project_key, week) buckets into one row per project, summing
-    # tokens / cost / sessions / first_seen / last_seen / models across the
-    # weeks the project appears in.
-    #
-    # Attribution: for each (project P, week W) bucket,
-    #     attributed_pct[P,W] = (cost[P,W] / total_cost[W]) * weekly_percent[W]
-    # iff a snapshot exists for W. Weeks without a snapshot contribute None
-    # (their weeks are already counted in `weeks_missing_snapshot`).
-    project_rows: dict[str, dict] = {}
-    for (key, wstart), b in buckets.items():
-        row = project_rows.get(key.bucket_path)
-        if row is None:
-            row = {
-                "key": key,
-                "sessions": set(),
-                "first_seen": b["first_seen"],
-                "last_seen": b["last_seen"],
-                "input": 0, "output": 0,
-                "cache_write": 0, "cache_read": 0,
-                "cost_usd": 0.0,
-                # `None` until the first week with a snapshot contributes —
-                # preserves the distinction between "every contributing week
-                # lacked a snapshot" (→ None) and "genuine zero attribution"
-                # (→ 0.0 after a real contribution). Spec §3.
-                "attributed_pct": None,
-                "models": {},
-            }
-            project_rows[key.bucket_path] = row
-        row["sessions"] |= b["sessions"]
-        if b["first_seen"] < row["first_seen"]:
-            row["first_seen"] = b["first_seen"]
-        if b["last_seen"] > row["last_seen"]:
-            row["last_seen"] = b["last_seen"]
-        row["input"] += b["input"]
-        row["output"] += b["output"]
-        row["cache_write"] += b["cache_write"]
-        row["cache_read"] += b["cache_read"]
-        row["cost_usd"] += b["cost_usd"]
-
-        # Merge per-model sub-buckets.
-        for model, mb in b["models"].items():
-            rm = row["models"].get(model)
-            if rm is None:
-                rm = {
-                    "cost_usd": 0.0,
-                    "input": 0, "output": 0,
-                    "cache_write": 0, "cache_read": 0,
-                    "first_seen": mb["first_seen"],
-                    "last_seen": mb["last_seen"],
-                }
-                row["models"][model] = rm
-            if mb["first_seen"] < rm["first_seen"]:
-                rm["first_seen"] = mb["first_seen"]
-            if mb["last_seen"] > rm["last_seen"]:
-                rm["last_seen"] = mb["last_seen"]
-            rm["cost_usd"] += mb["cost_usd"]
-            rm["input"] += mb["input"]
-            rm["output"] += mb["output"]
-            rm["cache_write"] += mb["cache_write"]
-            rm["cache_read"] += mb["cache_read"]
-
-        # Attribution contribution (only if this week has a snapshot and
-        # the week has nonzero total cost — a zero denominator would make
-        # the ratio meaningless). `attributed_pct` stays `None` until the
-        # first real contribution; subsequent contributions accumulate.
-        week_pct = week_snapshots.get(wstart)
-        week_total = total_cost_by_week.get(wstart, 0.0)
-        if week_pct is not None and week_total > 0:
-            contribution = (b["cost_usd"] / week_total) * week_pct
-            row["attributed_pct"] = (
-                (row["attributed_pct"] or 0.0) + contribution
-            )
-
-    # Compute $/1% per project: `cost_per_pct = cost_usd / attributed_pct`
-    # when attribution is positive; None otherwise (e.g. every contributing
-    # week lacked a snapshot — `attributed_pct` still None — or attribution
-    # came out to zero).
-    for row in project_rows.values():
-        ap = row["attributed_pct"]
-        if ap is not None and ap > 0:
-            row["cost_per_pct"] = row["cost_usd"] / ap
-        else:
-            row["cost_per_pct"] = None
-
-    # Collect warnings to surface in the JSON payload (terminal path emits
-    # them inline via eprint earlier, so this list stays JSON-specific).
-    warnings: list[str] = []
-    if unknown_entry_count > 0:
-        warnings.append(
-            f"{unknown_entry_count} entries lacked project_path — "
-            f"run `cache-sync` to backfill."
-        )
-    if missing_sid_count > 0:
-        warnings.append(
-            f"{missing_sid_count} entries lacked session_files session_id — "
-            f"run `cache-sync` to backfill."
-        )
-
-    # Honor --sort / --order. For numeric keys, `_project_sort_key` flips the
-    # primary-key sign to match the requested direction so natural `sorted()`
-    # ordering already produces the right answer; the dname tie-break stays
-    # ascending in both directions (ties never invert alphabetically). For
-    # `name`, the key is asc-natural (a-z) and `reverse=` is used for desc.
-    if args.sort == "name":
-        sorted_rows = sorted(
-            project_rows.values(),
-            key=lambda r: _project_sort_key(r, args.sort, args.order),
-            reverse=(args.order == "desc"),
-        )
-    else:
-        sorted_rows = sorted(
-            project_rows.values(),
-            key=lambda r: _project_sort_key(r, args.sort, args.order),
-        )
-
-    # Shareable-reports gate: --format short-circuits the JSON / table
-    # dispatch via `_share_render_and_emit`. The mutex in
-    # `_add_share_args` keeps `--format` and `--json` from coexisting.
-    # Privacy invariant (Section 8.4 / 5.3): the wrapper runs `_lib_share._scrub`
-    # before rendering, so default output anonymizes project labels to
-    # `project-1` / `project-2` / ...; `--reveal-projects` opts back in.
-    # The builder populates `ProjectCell.label` / `ChartPoint.project_label`
-    # / `ChartPoint.x_label` with REAL names; the wrapper-level scrubber is
-    # the single chokepoint that rewrites them.
-    if getattr(args, "format", None):
-        # Note: --breakdown is a no-op under --format (snapshot focuses on
-        # the headline per-project usage table + HBar chart; per-model
-        # sub-rows aren't in the share spec scope). Same convention as
-        # cmd_daily / cmd_weekly / cmd_report.
-        display_tz_str = _share_display_tz_label(args._resolved_tz)
-        snap = _build_project_snapshot(
-            list(sorted_rows),
-            period_start=since_dt,
-            period_end=until_dt,
-            display_tz=display_tz_str,
-            version=_share_resolve_version(),
-            theme=args.theme,
-            reveal_projects=args.reveal_projects,
-        )
-        _share_render_and_emit(snap, args)
-        return 0
-
-    if args.json:
-        print(_project_json_output(
-            since=since_dt,
-            until=until_dt,
-            weeks_in_range=len(weeks_in_range),
-            group_mode=args.group,
-            rows=sorted_rows,
-            weeks_missing_snapshot=weeks_missing_snapshot,
-            warnings=warnings,
-            include_breakdown=args.breakdown,
-            week_snapshots=week_snapshots,
-        ))
-        return 0
-
-    # Terminal path
-    range_label = f"{since_dt.date().isoformat()} \u2014 {until_dt.date().isoformat()}"
-    title = f"Claude Token Usage Report - Projects ({range_label})"
-
-    if not sorted_rows:
-        eprint("No project usage found in range.")
-        return 0
-
-    # Session A (spec §7.3): the new --color flag overrides NO_COLOR
-    # env; --no-color overrides FORCE_COLOR env; deny-wins on the
-    # --color + --no-color clash. _resolve_color_enabled returns the
-    # effective bool; pass it as ``color=`` so the renderer skips its
-    # internal _supports_color_stdout() auto-detect (which would
-    # re-consult NO_COLOR and incorrectly disable color when the user
-    # passed --color under NO_COLOR=1).
-    print(_render_project_table(
-        sorted_rows,
-        title=title,
-        breakdown=args.breakdown,
-        weeks_missing_snapshot=len(weeks_missing_snapshot),
-        weeks_in_range=len(weeks_in_range),
-        color=_resolve_color_enabled(args),
-        compact=args.compact,
-    ))
-    return 0
-
-
 # ─────────────────────────────────────────────────────────────────────
 # diff subcommand
 # ─────────────────────────────────────────────────────────────────────