Skip to content

fix(dashboard): scale usage calendar intensity by daily volume#425

Open
SantiagoDePolonia wants to merge 2 commits into
mainfrom
fix/github-like-tokens
Open

fix(dashboard): scale usage calendar intensity by daily volume#425
SantiagoDePolonia wants to merge 2 commits into
mainfrom
fix/github-like-tokens

Conversation

@SantiagoDePolonia

@SantiagoDePolonia SantiagoDePolonia commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Summary

The overview page's contribution calendar (the GitHub-style daily usage grid) shaded each day by its rank among non-zero days (quartile bucketing), so cell intensity reflected ordering rather than magnitude. A day with 10K tokens and a day with 1M tokens could render at the same shade — there was no visual difference between a light day and a heavy one.

This changes the level calculation to be relative to the busiest day in the displayed period, using a log scale:

var ratio = Math.log(value + 1) / Math.log(max + 1);

Token counts span orders of magnitude, so a plain linear ratio would collapse every quiet day to the lightest shade. The log curve compresses busy days and spreads out quiet ones, so low-volume days stay distinguishable while the busiest day is always the darkest.

User-visible impact

  • Calendar intensity now reflects how much was actually spent, scaled against the busiest day in the ~1-year window shown.
  • Quiet days read lighter; heavy days read darker — instead of every day looking roughly the same.
  • Applies to both the tokens and costs views (same code path).

Example (max = 1M tokens):

Day Before (quartile rank) After (log vs max)
1K varies by rank level 2
10K varies by rank level 3
100K varies by rank level 4
1M level 4 level 4

Notes

  • Scope of the max is the entire displayed period (the full ~365-day grid), not per-week/per-month.
  • The +1 offset suits token magnitudes; for very small cost values (sub-dollar) the curve behaves closer to linear. Flagging in case we later want unit-independent normalization across the log range.
  • No new dependencies; existing dashboard JS unit tests pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Refactor
    • Updated the contribution calendar intensity algorithm to scale day shading using a log-based ratio against the busiest day, improving consistency across ranges and ensuring the busiest day always receives the darkest level.
    • Adjusted the level selection logic to use fixed ratio cutoffs rather than percentile thresholds.
  • Tests
    • Added a dedicated test suite covering empty/invalid handling, monotonic behavior, boundary cases, and correct scaling for both token- and cost-based views.

The overview contribution calendar bucketed each day by its rank among
non-zero days (quartiles), so cell intensity reflected ordering rather
than magnitude — a 10K-token day and a 1M-token day could render at the
same shade.

Compute each day's level relative to the busiest day in the displayed
period instead, using a log scale (log(value+1)/log(max+1)). Token
counts span orders of magnitude, so a linear ratio would collapse every
quiet day to the lightest shade; the log curve compresses busy days and
spreads quiet ones, keeping low-volume days distinguishable. Applies to
both the tokens and costs views.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9417f28d-79fa-482c-a8d7-a01fd84bd58c

📥 Commits

Reviewing files that changed from the base of the PR and between 7b61d8f and fe02ccb.

📒 Files selected for processing (1)
  • internal/admin/dashboard/static/js/modules/contribution-calendar.test.cjs

📝 Walkthrough

Walkthrough

The contribution calendar's intensity-level algorithm is refactored: buildCalendarGrid now computes max from all day values (instead of filtering non-zero entries), and calendarLevel drops its sortedNonZero parameter, replacing percentile-based thresholding with a log-scaled ratio (log(value+1)/log(max+1)) against fixed cutoffs. A comprehensive test suite validates the new algorithm across edge cases, boundaries, monotonicity, and both tokens and costs modes.

Changes

Contribution Calendar Intensity Algorithm

Layer / File(s) Summary
Log-scaled intensity level computation
internal/admin/dashboard/static/js/modules/contribution-calendar.js
buildCalendarGrid computes max as the highest value across all day entries and calls calendarLevel(value, max) without the sorted non-zero list. calendarLevel removes the sortedNonZero parameter and replaces percentile thresholds with log(value+1)/log(max+1) ratio checks at fixed cutoffs; zero/invalid guard is retained.
Test suite for log-scaled intensity algorithm
internal/admin/dashboard/static/js/modules/contribution-calendar.test.cjs
Comprehensive test harness with deterministic date mocking validates calendarLevel edge cases, max/min levels, log-scaled band boundaries, and monotonicity. Integration tests for buildCalendarGrid confirm max-day darkness, lighter quiet-day levels, and zero-usage days in both tokens and costs modes.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • ENTERPILOT/GoModel#144: Both PRs modify the same contribution-calendar.js heatmap logic—especially calendarLevel and buildCalendarGrid used to compute day intensity/levels.

Poem

🐇 Hopping through the calendar grid so bright,
No more percentiles sorting left and right!
A log-scaled ratio, neat and clean,
The busiest day sets the max we've seen.
With tests to validate each edge and seam —
This rabbit loves the new algorithm! 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix(dashboard): scale usage calendar intensity by daily volume' clearly and specifically describes the main change: improving how the dashboard's contribution calendar scales intensity based on daily usage volume using a logarithmic approach instead of quartile bucketing.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/github-like-tokens

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@greptile-apps

greptile-apps Bot commented Jun 23, 2026

Copy link
Copy Markdown

Confidence Score: 5/5

This looks safe to merge, with one small follow-up for tests.

  • The changed runtime path is localized to the calendar level calculation.
  • No concrete breakage was found for the dashboard rendering path.
  • The new visible bucket behavior should be covered by tests.

internal/admin/dashboard/static/js/modules/contribution-calendar.js

Reviews (1): Last reviewed commit: "fix(dashboard): scale usage calendar int..." | Re-trigger Greptile

Comment on lines +128 to 138
calendarLevel(value, max) {
if (value <= 0 || max <= 0) return 0;
// Log scale against the busiest day: token counts span orders of
// magnitude, so a linear ratio collapses every quiet day to the
// lightest shade. Logs compress the busy days and spread the quiet
// ones, keeping low-volume days distinguishable.
var ratio = Math.log(value + 1) / Math.log(max + 1);
if (ratio <= 0.25) return 1;
if (ratio <= 0.5) return 2;
if (ratio <= 0.75) return 3;
return 4;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Add threshold tests This changes the visible calendar levels from quartile rank to log-scaled volume, but there are no tests for the new bucket boundaries. A small change to the 0.25, 0.5, or 0.75 cutoffs, or to the value + 1 normalization, can silently shift both token and cost cells into different CSS levels without failing any existing test. Please add tests that cover zero, the max day, and values around each new threshold.

Context Used: CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Address review feedback: add unit tests for the new contribution-calendar
level math. Covers zero/negative/maxless guards, the busiest day landing
at the darkest level, and values probed just around each 0.25/0.5/0.75
log cutoff (using max=65535 so the cutoffs fall on clean value
boundaries). Also exercises buildCalendarGrid end to end: levels scale
against the busiest day across the whole period, no-usage days stay at
level 0, and the costs view uses the same log scaling as tokens.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants