feat: comprehensive economics analysis and code quality improvements by FlorianBruniaux · Pull Request #21 · rtk-ai/rtk

FlorianBruniaux · 2026-01-30T13:08:07Z

Summary

This PR adds comprehensive Claude Code economics analysis combining ccusage spending data with rtk savings tracking, plus systematic code quality improvements.

New Feature: `rtk cc-economics`

Combines ccusage (tokens spent) with rtk (tokens saved) for economic impact analysis.

Commands:

rtk cc-economics              # Summary view (default)
rtk cc-economics --daily      # Daily breakdown
rtk cc-economics --weekly     # Weekly breakdown
rtk cc-economics --monthly    # Monthly breakdown
rtk cc-economics --all        # All views
rtk cc-economics --format json|csv   # Export

Key Features:

Dual metric system: active CPT (cost/input+output) vs blended CPT (cost/total incl. cache)
Graceful degradation when ccusage unavailable
HashMap-based O(n+m) merge algorithm
ISO-8601 week alignment
Real-world validation: $3.4K spent, 1.2M tokens saved, 24.4% active savings

Architecture:

src/ccusage.rs - Isolated ccusage CLI interface (7 tests)
src/cc_economics.rs - Business logic + display (10 tests)
src/display_helpers.rs - Trait-based generic display system
src/utils.rs - Shared formatting utilities (8 tests)

Code Quality Improvements

Applied comprehensive fixes based on code audit:

Phase 1: Dead Code Removal

Removed run_compact(), track_tokens(), TRACKER singleton
Cleaned CommandRecord struct fields

Phase 2: Error Handling & Safety

Added .context() to 40+ error propagation sites
Fixed bounds check panic in weekly display
Reduced visibility: estimate_tokens pub → private
Replaced manual loops with .collect::<Result<Vec<_>, _>>()?
Removed unnecessary clones

Phase 3: Duplication Refactoring

Created PeriodStats trait for generic display
Eliminated 132 lines of duplication in gain.rs
Output bit-identical validation

Phase 4: Optimization & Safety Checks

Optimized HashMap merge: destructure CcusagePeriod to avoid clones
Added const BILLION: f64 = 1e9 for magic number
Added NaN/Infinity safety check in format_usd()

Test Coverage

17 new tests (ccusage: 7, cc_economics: 10, utils: 8)
All new tests passing
Build: Clean (1 pre-existing warning)
Tests: 79/82 passing (3 pre-existing failures)

Validation

✅ cargo fmt
✅ cargo clippy --all-targets
✅ cargo test (79 passed)
✅ Functional tests (all commands verified)
✅ Real-world data test (2 months, $3.4K spent)

Commits

76703ca - feat: add comprehensive temporal audit system
ec1cf9a - feat: add comprehensive claude code economics analysis
5b840cc - fix: comprehensive code quality improvements
3b847f8 - fix: optimize HashMap merge and add safety checks

Lines of Code

New code: +1700 lines (ccusage: 309, cc_economics: 813, display_helpers: 337, utils: +50)
Refactored: -141 lines net (dead code removal + duplication elimination)
Tests: +250 lines

🤖 Generated with Claude Code

Implement `rtk cc-economics` command combining ccusage spending data with rtk savings analytics for economic impact reporting. Features: - Dual metric system (active vs blended cost-per-token) - Daily/weekly/monthly granularity with ISO-8601 week alignment - JSON/CSV export support for data analysis - Graceful degradation when ccusage unavailable - Real-time data merge with O(n+m) HashMap performance Architecture: - src/ccusage.rs: Isolated ccusage CLI interface (7 tests) - src/cc_economics.rs: Business logic + display (10 tests) - src/utils.rs: Shared formatting utilities (8 tests) - Refactored gain.rs to use shared format_tokens() Test coverage: 17 new tests, all passing Validated with real-world data (2 months, $3.4K spent, 1.2M saved) Addresses: #economics-integration Impact: 24.4% cost savings identified ($830.91 active pricing) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Apply systematic quality fixes identified in code audit: Phase 1: Remove dead code (4 warnings → 0) - Remove unused run_compact() function in gain.rs - Remove unused track_tokens() function in tracking.rs - Remove unused TRACKER singleton (Mutex) - Clean up CommandRecord struct (remove unused fields) Phase 2: Add error context and quality fixes - Add .context() to all ? operators in cc_economics.rs (15+ callsites) - Add .context() to all ? operators in gain.rs (10+ callsites) - Fix bounds check panic risk in gain.rs:252 (week_start slice) - Reduce visibility: estimate_tokens pub → private - Replace 6 manual loops with idiomatic .collect::<Result<Vec<_>, _>>()? - Remove residual dev comment (// psk:) - Remove unnecessary .clone() in main.rs Phase 3: Refactor duplication (132 lines eliminated) - Create display_helpers.rs module with PeriodStats trait - Unify print_daily_full/weekly/monthly in gain.rs (152 lines → 9 lines) - Implement trait for DayStats, WeekStats, MonthStats - Zero-overhead compile-time dispatch (monomorphization) - Output bit-identical, all tests passing Impact: - Dead code: -20 lines - Error context: Errors now actionable instead of opaque - Duplication: -132 lines of pure duplication - Safety: Bounds check prevents potential panic - Idiomaticity: .collect() over manual loops Metrics: - Build: 0 errors, 1 warning (pre-existing cache_* fields) - Tests: 79/82 passing (3 pre-existing failures) - Clippy: 13 warnings (all pre-existing) - Functional: rtk gain --daily, rtk cc-economics validated Addresses code audit feedback from parallel session Detailed report: claudedocs/refactoring-report.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Applies targeted code quality improvements: Issue rtk-ai#5: Reduce clones in HashMap merge - Destructure CcusagePeriod to avoid cloning key - Use .or_insert_with_key() for ccusage data merging - Keep necessary clones for rtk data (HashMap ownership requirement) - Affects: merge_daily, merge_weekly, merge_monthly Issue rtk-ai#7: Replace magic number with named constant - Add const BILLION: f64 = 1e9 - Improves readability in cache token calculation Issue rtk-ai#8: Add NaN/Infinity safety check - Guard format_usd() against invalid float values - Return "$0.00" for non-finite inputs Build: Clean (1 pre-existing warning) Tests: 79/82 passing (3 pre-existing failures) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR introduces a comprehensive economics analysis feature combining Claude Code usage tracking (via ccusage) with token savings tracking (via rtk), along with systematic code quality improvements including dead code removal, enhanced error handling, and refactoring to eliminate duplication through a trait-based display system.

Changes:

New rtk cc-economics command providing dual-metric cost analysis (active vs blended CPT) with daily/weekly/monthly breakdowns and JSON/CSV export
Code quality improvements including dead code removal, enhanced error handling with context annotations, and reduced code duplication through generic trait-based display helpers
New utility functions for token and USD formatting with comprehensive test coverage

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/utils.rs	Added format_tokens() and format_usd() utility functions with 8 tests
src/tracking.rs	Cleaned up dead code (TRACKER singleton, track_tokens()), reduced visibility of estimate_tokens, improved error handling
src/main.rs	Added CcEconomics command variant and wiring, code formatting improvements
src/gain.rs	Refactored to use shared utilities and trait-based display system, eliminating ~132 lines of duplication
src/display_helpers.rs	New trait-based generic display system (PeriodStats trait) for eliminating display duplication
src/ccusage.rs	New module providing isolated ccusage CLI integration with graceful degradation and 7 tests
src/cc_economics.rs	New module implementing economics analysis with merge logic, dual metrics, and 10 tests
claudedocs/refactoring-report.md	Documentation of refactoring approach and validation
claudedocs/cc-economics-implementation.md	Implementation details and architecture documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-30T13:14:17Z

+
+**Test 2: `rtk gain --weekly`**
+```
+📊 Weekly Breakdown (1 weeklys)


The plural "weeklys" is grammatically incorrect. It should be "weeks".

Suggested change

📊 Weekly Breakdown (1 weeklys)

📊 Weekly Breakdown (1 weeks)

Copilot · 2026-01-30T13:14:18Z

+/// Formate un nombre de tokens avec suffixes K/M pour lisibilité.
+///
+/// # Arguments
+/// * `n` - Nombre de tokens
+///
+/// # Returns
+/// String formaté (ex: "1.2M", "59.2K", "694")
+///
+/// # Examples
+/// ```
+/// use rtk::utils::format_tokens;
+/// assert_eq!(format_tokens(1_234_567), "1.2M");
+/// assert_eq!(format_tokens(59_234), "59.2K");
+/// assert_eq!(format_tokens(694), "694");
+/// ```


The documentation comments for these functions are in French rather than English. For consistency with the rest of the codebase, documentation should be in English.

Copilot · 2026-01-30T13:14:18Z

+/// Formate un montant USD avec précision adaptée.
+///
+/// # Arguments
+/// * `amount` - Montant en dollars
+///
+/// # Returns
+/// String formaté avec $ prefix
+///
+/// # Examples
+/// ```
+/// use rtk::utils::format_usd;
+/// assert_eq!(format_usd(1234.567), "$1234.57");
+/// assert_eq!(format_usd(12.345), "$12.35");
+/// assert_eq!(format_usd(0.123), "$0.12");
+/// assert_eq!(format_usd(0.0096), "$0.0096");
+/// ```


The documentation comments for this function are in French rather than English. For consistency with the rest of the codebase, documentation should be in English.

Copilot · 2026-01-30T13:14:18Z

+    // Merge rtk data (week_start = legacy Saturday "2026-01-18")
+    // Convert Saturday to Monday for alignment
+    for entry in rtk {
+        let monday_key = match convert_saturday_to_monday(&entry.week_start) {
+            Some(m) => m,
+            None => {
+                eprintln!("⚠️  Invalid week_start format: {}", entry.week_start);
+                continue;
+            }
+        };


The comment states "week_start = legacy Saturday" but the SQL query in tracking.rs line 259 shows that rtk uses 'weekday 0', '-6 days' which calculates Monday (Sunday minus 6 days), not Saturday. This comment is incorrect and may have led to the incorrect conversion logic in convert_saturday_to_monday.

Suggested change

// Merge rtk data (week_start = legacy Saturday "2026-01-18")

// Convert Saturday to Monday for alignment

for entry in rtk {

let monday_key = match convert_saturday_to_monday(&entry.week_start) {

Some(m) => m,

None => {

eprintln!("⚠️ Invalid week_start format: {}", entry.week_start);

continue;

}

};

// Merge rtk data (week_start is already ISO Monday "2026-01-20")

// Use week_start directly for alignment with ccusage

for entry in rtk {

let monday_key = entry.week_start.clone();

Copilot · 2026-01-30T13:14:18Z

+        println!(
+            "  │ Active token pricing:  {}  ({:.1}%)         │ ← most representative",
+            format_usd(active_savings).trim_end(),
+            active_pct
+        );


The formatting in this line attempts to align the output within a fixed-width box, but uses .trim_end() on the formatted USD string which will remove trailing spaces needed for alignment. This could cause the box borders to become misaligned if the USD values have different lengths. Consider removing .trim_end() or adjusting the box drawing approach to accommodate variable-length values.

Copilot · 2026-01-30T13:14:19Z

+/// Convert Saturday week_start (legacy rtk) to ISO Monday
+/// Example: "2026-01-18" (Sat) -> "2026-01-20" (Mon)
+fn convert_saturday_to_monday(saturday: &str) -> Option<String> {
+    let sat_date = NaiveDate::parse_from_str(saturday, "%Y-%m-%d").ok()?;
+
+    // rtk uses Saturday as week start, ISO uses Monday
+    // Saturday + 2 days = Monday
+    let monday = sat_date + chrono::TimeDelta::try_days(2)?;


The comment states that rtk uses Saturday as week_start, but the SQL query in tracking.rs shows that weekday 0 (Sunday) minus 6 days equals Monday, not Saturday. The function name and implementation suggest it converts Saturday to Monday by adding 2 days, but the actual rtk data already uses Monday. This creates a misalignment where Monday dates are shifted to Wednesday. Either the comment is incorrect, or the conversion logic is wrong. Please verify which weekday rtk actually uses and correct either the comment or the conversion logic.

Copilot · 2026-01-30T13:14:20Z

+        println!(
+            "  │ Blended pricing:       {}  ({:.2}%)          │",
+            format_usd(blended_savings).trim_end(),
+            blended_pct
+        );


Similar to the line above, using .trim_end() on the formatted USD string could cause misalignment in the box borders. Consider a consistent approach to formatting that maintains alignment.

Copilot · 2026-01-30T13:14:20Z

+        self.rtk_savings_pct = Some(if stats.input_tokens + stats.output_tokens > 0 {
+            stats.saved_tokens as f64
+                / (stats.saved_tokens + stats.input_tokens + stats.output_tokens) as f64
+                * 100.0
+        } else {
+            0.0
+        });


The MonthStats struct already has a savings_pct field that is correctly calculated in tracking.rs as (saved/input * 100). This recalculation is unnecessary and uses an incorrect formula: saved/(saved+input+output) instead of saved/input. This will produce significantly different percentage values (e.g., if saved=100, input=100, output=50, the correct calculation gives 100% but this formula gives 40%). Remove this calculation and use stats.savings_pct directly, as done in set_rtk_from_day and set_rtk_from_week.

Suggested change

self.rtk_savings_pct = Some(if stats.input_tokens + stats.output_tokens > 0 {

stats.saved_tokens as f64

/ (stats.saved_tokens + stats.input_tokens + stats.output_tokens) as f64

* 100.0

} else {

0.0

});

self.rtk_savings_pct = Some(stats.savings_pct);

Copilot · 2026-01-30T13:14:20Z

+    fn period(&self) -> String {
+        let start = if self.week_start.len() > 5 {
+            &self.week_start[5..]
+        } else {
+            &self.week_start
+        };
+        let end = if self.week_end.len() > 5 {
+            &self.week_end[5..]
+        } else {
+            &self.week_end
+        };
+        format!("{} → {}", start, end)


This string slicing operation could panic if week_start or week_end strings are shorter than 5 characters or contain multi-byte UTF-8 characters at the slice boundary. Consider using safer string methods like .get(5..) or .chars().skip(5).collect(), or validate the string format before slicing.

Copilot · 2026-01-30T13:14:20Z

+
+**Test 1: `rtk gain --daily`**
+```
+📅 Daily Breakdown (3 dailys)


The plural "dailys" is grammatically incorrect. It should be "days".

Suggested change

📅 Daily Breakdown (3 dailys)

📅 Daily Breakdown (3 days)

1. CRITICAL: Fix 'latest' tag creation after releases - Move update-latest-tag job from release.yml to release-please.yml - release-please creates tags via API (no push event) → must run in same workflow - Job now conditional on release_created output 2. IMPORTANT: Add npx fallback for ccusage + improve message - Check binary in PATH first, fallback to 'npx ccusage' - Updated message: "npm i -g ccusage (or use npx ccusage)" - Consistent with other JS tooling (next_cmd, tsc_cmd, prettier_cmd) 3. PROCESS: Slow down version bumps with release-please config - Add release-please-config.json with bump-patch-for-minor-pre-major - In 0.x versions: feat: → patch bump instead of minor - Prevents rapid version inflation (0.3.1 → 0.5.0 in 21h) Fixes issues raised by Patrick after PR rtk-ai#21 merge. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

…dit-system feat: comprehensive economics analysis and code quality improvements

1. CRITICAL: Fix 'latest' tag creation after releases - Move update-latest-tag job from release.yml to release-please.yml - release-please creates tags via API (no push event) → must run in same workflow - Job now conditional on release_created output 2. IMPORTANT: Add npx fallback for ccusage + improve message - Check binary in PATH first, fallback to 'npx ccusage' - Updated message: "npm i -g ccusage (or use npx ccusage)" - Consistent with other JS tooling (next_cmd, tsc_cmd, prettier_cmd) 3. PROCESS: Slow down version bumps with release-please config - Add release-please-config.json with bump-patch-for-minor-pre-major - In 0.x versions: feat: → patch bump instead of minor - Prevents rapid version inflation (0.3.1 → 0.5.0 in 21h) Fixes issues raised by Patrick after PR rtk-ai#21 merge. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

FlorianBruniaux and others added 3 commits January 30, 2026 12:34

Copilot AI review requested due to automatic review settings January 30, 2026 13:08

Copilot started reviewing on behalf of FlorianBruniaux January 30, 2026 13:08 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

pszymkowiak merged commit 8e72e7a into rtk-ai:master Jan 30, 2026
6 of 7 checks passed

FlorianBruniaux mentioned this pull request Jan 30, 2026

fix: 3 issues (latest tag, ccusage fallback, versioning) #23

Merged

ahundt pushed a commit to ahundt/rtk that referenced this pull request Feb 23, 2026

Merge pull request rtk-ai#21 from FlorianBruniaux/feature/temporal-au…

f640db6

…dit-system feat: comprehensive economics analysis and code quality improvements

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: comprehensive economics analysis and code quality improvements#21

feat: comprehensive economics analysis and code quality improvements#21
pszymkowiak merged 3 commits intortk-ai:masterfrom
FlorianBruniaux:feature/temporal-audit-system

FlorianBruniaux commented Jan 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Copilot AI Jan 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	📊 Weekly Breakdown (1 weeklys)
	📊 Weekly Breakdown (1 weeks)

	📅 Daily Breakdown (3 dailys)
	📅 Daily Breakdown (3 days)

Conversation

FlorianBruniaux commented Jan 30, 2026

Summary

New Feature: rtk cc-economics

Code Quality Improvements

Test Coverage

Validation

Commits

Lines of Code

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

New Feature: `rtk cc-economics`