Module hotspot_velocity 

hotspot-velocity analysis — which files are heating up.

Hotspots rank all-time churn; velocity asks the forward-looking question: is a file’s change rate accelerating? A file that suddenly starts churning is becoming a hotspot before its all-time count says so — an early-warning signal.

For each file the analysis compares two windows ending at the latest commit in the data:

• recent — the last RECENT_DAYS days,
• baseline — the BASELINE_DAYS days before that.

Both are normalised to revisions-per-week (the windows have different lengths) and acceleration = recent_per_week − baseline_per_week. Positive = heating up, negative = cooling down. Subtracting rates (rather than a ratio) keeps brand-new files — baseline 0, recent high — at the top where they belong, instead of dividing by zero.

Anchoring

“Now” defaults to MAX(commits.date), NOT wall-clock today, so the result is reproducible and survives back-testing (the same anchor lesson code-age / stale-code learned). A repo whose last commit was a year ago still reports its final-year velocity, not all-zeros. --age-time-now <date> overrides the anchor with that calendar date’s end-of-day, re-cutting both windows so a back-test reproduces the velocity the repo showed on that date.

Structs

HotspotVelocityRow

One hotspot-velocity finding.

Constants

BASELINE_DAYS

Length of the “baseline” window (immediately preceding recent) in days.

RECENT_DAYS

Length of the “recent” window in days.

Functions

run_hotspot_velocity

Run the hotspot-velocity analysis. Returns files ranked by change acceleration (heating up first).