feat(report): add comprehensive token usage analytics and reporting (#56)

[luongnv89]

Closes #56

Summary

Adds a new context-stats report subcommand that generates comprehensive token usage analytics across all Claude Code projects. Users can now analyze token consumption patterns with project-level, session-level, and subagent-level breakdowns.

Features

• Aggregate Analytics: Summarize token consumption across all projects
• Project Breakdown: Per-project token usage with cost tracking
• Session Details: Top 10 most expensive sessions per project with:
  • Token counts (input, output, cache creation, cache read)
  • Session duration and start time
  • Model ID and cost
• Subagent Tracking: Identify most-used subagents per project
• Date Filtering: Optional --since-days parameter to limit scope
• Flexible Output: Configurable output file path with timestamp-based default

Implementation

New modules:

• src/claude_statusline/analytics.py (287 lines) — Project data discovery and aggregation

  • Discovers projects in ~/.claude/projects/
  • Loads session state files from ~/.claude/statusline/
  • Parses subagent data from session JSONL files
  • Filters by date range

• src/claude_statusline/cli/report.py (202 lines) — Report generation and formatting

  • Generates markdown with grand totals and per-project breakdowns
  • Formats token counts and dates for readability
  • Saves reports to disk with configurable paths

Updates:

• src/claude_statusline/cli/context_stats.py — Add report action dispatch
  • Updated _KNOWN_ACTIONS to include "report"
  • Modified _normalize_argv() to handle report as session-ID-optional action
  • Added report action dispatch in main()
  • Updated help text and examples

Tests:

• tests/python/test_report.py — Unit tests for report generation

Test Results

All 347 existing tests pass + 2 new tests:

• ✓ Report generation with sample project data
• ✓ Report generation with no data

Usage Examples

# Generate report for all projects
context-stats report

# Generate report with custom output file
context-stats report --output my-report.md

# Generate report for last 30 days
context-stats report --since-days 30

Architecture

• No external dependencies — uses only stdlib and existing project modules
• Defensive parsing — gracefully handles missing/malformed project data
• Session-ID-optional action — similar to existing explain command
• Data flows from ~/.claude/projects/ → state files → aggregation → markdown

Acceptance Criteria

• Create new CLI subcommand for token usage reports
• Parse session data from ~/.claude/projects/ with proper encoding handling
• Generate markdown reports with project, session, and subagent breakdowns
• Support date filtering via --since-days
• Track input, output, cache creation, and cache read tokens
• Format output with readable numbers and timestamps
• Save reports to configurable output directory
• Implement in Python package for CLI and library use
• Add integration tests for sample data