Reference
CLI Commands
hotspots analyze [path]
Core analysis command. Scans source files, computes metrics, scores functions. Also the entry point for ownership risk, snapshot pruning, config inspection, and the agent contract — former standalone subcommands (coordinate, prune, config, agent) that are now flags here instead; see their own subsections below.
hotspots analyze [PATH] [OPTIONS]PATH defaults to .. There is no --mode flag — every run does the full analysis that used to be --mode snapshot (the only mode that survived #375's removal of --mode delta).
| Flag | Default | Description |
|---|---|---|
--format | text | text, json, html, sarif |
--top N | none | Show top N functions by LRS |
--min-lrs F | 0.0 | Filter functions below this LRS |
--config PATH | auto | Path to config file |
--output PATH | .hotspots/report.html | Output file (HTML/SARIF) |
--html-output PATH | — | Also write the HTML report from the same analysis (with a non-html --format). Saves running a second full analysis when you want JSON and HTML for one commit; on large repos that second pass is roughly as costly as the first |
--explain | off | Per-function risk breakdown + phrase-table explanations for CRITICAL/HIGH when a trained ranker is active (text format only) |
--level | — | file aggregate view (ranked file risk table) (text format only) |
--force | off | Overwrite existing snapshot |
--no-persist | off | Skip writing snapshot to disk (persisted by default) |
--all-functions | off | Output flat array instead of triage buckets (JSON format only) |
--cold-start | off | Gini/label-density-gated ranking with no trained ranker required — see Cold-Start Ranking |
Ownership risk (was hotspots coordinate; see below):
| Flag | Description |
|---|---|
--files <FILES> | Comma-separated file paths to report ownership risk for, instead of analyzing |
--diff | Derive that file set from a unified diff read on stdin |
--staged | Derive that file set from git diff --cached --name-only |
--ownership | Report ownership risk; defaults to --staged when no other selector is given |
Snapshot maintenance (was hotspots prune; see below):
| Flag | Description |
|---|---|
--prune | Run pruning instead of analyzing |
--unreachable | With --prune: remove unreachable snapshots |
--older-than DAYS | With --prune --unreachable: only remove ones older than this |
--compact LEVEL | With --prune: compact retained history to level 0/1/2 |
--dry-run | With --prune: report what would change without modifying anything |
Config inspection (was hotspots config; see below):
| Flag | Description |
|---|---|
--show-config | Print the resolved configuration instead of analyzing |
--validate-config | Validate the config file instead of analyzing (exit 1 on failure) |
Agent contract (was hotspots agent; see below):
| Flag | Description |
|---|---|
--help-agent [analyze|diff] | Print the machine-readable agent contract instead of analyzing |
Notes:
--explainand--levelare mutually exclusive--forceand--no-persistare mutually exclusive- Text format requires
--explainor--level --cold-start,--axes,--prune,--show-config/--validate-config,--help-agent, and the ownership-risk flags (--files/--diff/--staged/--ownership) are all mutually exclusive with each other and with a plain analysis--unreachable/--older-than/--compact/--dry-runrequire--prune;--older-thanadditionally requires--unreachableanalyzehas no policy-evaluation mode; usehotspots diff --policyfor comparing two states — it has auto base-ref detection,--scope-to-diff, and--explain
Three environment variables replace flags that used to configure parallelism and diagnostics directly — see Environment variables: HOTSPOTS_JOBS (worker threads, was -j/--jobs), HOTSPOTS_SKIP_TOUCH_METRICS (was --skip-touch-metrics), and HOTSPOTS_SKIP_GATE (was --skip-gate).
hotspots diff [base] [head]
Compare snapshots between any two git refs. Both must have existing snapshots (or pass --auto-analyze to generate them). This is the "review my PR" entry point: run hotspots diff with no args inside a branch to compare HEAD against the auto-detected merge-base.
hotspots diff [BASE] [HEAD] [OPTIONS]Accepts: branch names, tags, full/short SHAs, HEAD~N relative refs. head defaults to HEAD. base defaults to the auto-detected merge-base against the repo's default branch (main/master/develop/trunk, checked both locally and as origin/<branch>) — pass it explicitly if auto-detection picks the wrong branch or fails.
| Flag | Description |
|---|---|
--format | text (default), json, html |
--output PATH | Write output to file |
--policy | Evaluate policies; exit 1 on blocking violations |
--top N | Limit to N new/modified functions by LRS (new) / |ΔLRS| (modified); deleted functions never count toward N (see below) |
--config PATH | Config file |
--auto-analyze | Generate missing snapshots via git worktrees |
--scope-to-diff | With --auto-analyze, only analyze files the diff touches (see below) |
--explain | Print a one-line factor breakdown under each changed function |
Exit codes: 0 = success, 1 = policy failure, 2 = auto-analysis failed, 3 = snapshot missing.
--top applies after policy evaluation — violations outside the top N are still detected. deleted-status functions are excluded from the --top N cutoff entirely rather than ranked alongside new by absolute LRS — research found that including them diluted recall of real regressions in the truncated view.
--scope-to-diff
On a large repo, --auto-analyze without this flag walks and parses every file in the repo to build a missing snapshot, even for a small PR. --scope-to-diff restricts that walk to just the files the base..head diff touches, benchmarked at roughly 50-70x less memory and wall-clock time on a 49-file PR against a large repo (full-repo: ~33GB peak RSS / 230-700s; scoped to the changed files: <1GB / ~10s).
This is opt-in, not the --auto-analyze default, because it has not yet been verified to always produce identical function-level results to a full-repo snapshot — cross-file effects from files outside the scoped set (e.g. via the call graph) are not accounted for. Use it when you want the speed and are comparing against a report that's scoped to the PR's own changed functions anyway; fall back to a full --auto-analyze run (no --scope-to-diff) if you need the full-repo picture or hit a discrepancy.
--explain
Prints a one-line factor breakdown under each changed function naming which raw metric drove the score change (e.g. "driven mainly by +4 cyclomatic complexity and +2 nesting depth"), computed directly from the before/after delta — unlike snapshot mode's --explain, this needs no repo-wide percentile computation, so it works without a full-repo pass.
hotspots train [PATH]
Fit a ranker from fix-commit history. Model saved to .hotspots/ranker.json and auto-loaded by hotspots analyze.
Before fitting a RandomForest, hotspots train runs a pre-flight comparison (the regime screener) between Ridge regression and a depth-2 RandomForest. If Ridge already matches the forest's ranking quality (Δρ < 0.03), it fits Ridge instead and skips RandomForest training — faster, and no less accurate on repos where the signal is linear. See docs/USAGE.md for the full verdict table. This selection is automatic; there is no flag to force one model class over the other.
Before training, the command always runs the pre-flight screen (there is no --screen flag to gate it — it aborts with SKIP_FT when the mean hotspots score is too flat to be worth training on), then prints an estimate and (for repos with > 1,000 functions) prompts for confirmation:
hotspots train: 12914 functions · 200 trees · 365 days of git history (file-level labels) · estimated ~4m 30s
Proceed? [y/N]
[10/200] ~4m 5s remaining
[100/200] ~2m 1s remaining
[200/200]
Model class: RandomForest (regime=STRONG, Δρ=+0.14)
Trained: 200 trees × depth 6 | 12914 samples | elapsed 4m 25sWhen the screener selects Ridge, RandomForest training is skipped:
Model class: Ridge (regime=LINEAR, Δρ=+0.03) — RandomForest training skipped
Trained: 0 trees × depth 0 | 874 samples | elapsed 2sTraining always ends with a Precision@K report (there is no --eval flag to gate it either).
| Flag | Default | Description |
|---|---|---|
--blame | off | Blame-based function-level labels (slower, more precise) |
--label-window DAYS | 365 | Days of history to scan |
--output PATH | .hotspots/ranker.json | Model output path |
--yes / -y | off | Skip confirmation prompt (CI / non-interactive) |
There is no --n-estimators/--max-depth (tree count and depth use TrainConfig's fixed defaults — 200 trees, depth 6 — ignored if the screener selects Ridge anyway) and no --quiet (per-tree progress lines are shown when stderr is a terminal and suppressed otherwise, the same convention analyze already uses for its own progress output).
Requires: ≥ 50 functions in snapshot, ≥ 5 positive and ≥ 10 negative labels. Fix keywords: fix:, bug, patch, hotfix, regression, defect.
The trained model (model_version 6) uses 9 features: lrs, cc, nd, loc, fo, fan_in, total_churn, authors_90d, directed_coupling. (convention_bug_fix_count was removed in model_version 6 — in our testing it ratchets the trained ranker monotonically, never improving once a function is flagged.) Models trained with an older version are rejected on load with a retrain message.
hotspots analyze prints which model class the loaded ranker uses:
hotspots: using trained ranker (model class: Ridge)Once a model is trained, hotspots analyze . --explain adds a ✦ phrase line below each CRITICAL/HIGH function — e.g. ✦ Churns heavily and is load-bearing. — derived from which features rank in the top 20th percentile for that repo. No ✦ lines appear without a trained ranker.
Cold-Start Ranking
hotspots analyze <PATH> --cold-start produces a ranking without a trained ranker and without the label thresholds hotspots train requires (≥ 50 functions, ≥ 5 positive / ≥ 10 negative labels). It skips the trained-ranker lookup and snapshot pipeline entirely — mutually exclusive with --axes and with every other absorbed-subcommand flag (--prune, --show-config/--validate-config, --help-agent, the ownership-risk flags).
hotspots analyze . --cold-start
hotspots analyze . --cold-start --top 20Routing is decided per-repo by two independent gates, checked in this order, and printed before the ranked list (cold-start route: formula|anomaly|uniform-prior):
- Uniform-prior guard. If no file stands out even by raw commit count (top decile of files by
commit_countaccounts for less than 20% of total commits), there's no basis for a ranking — prints(uniform prior — no ranking to show; all files equally likely)and returns an empty list rather than a manufactured one. - Low-label-density gate. If the repo has some fix-commit history but the function-level positive rate is low (5–30% of functions, with a Shannon-entropy floor to filter out near-degenerate splits) — plenty of history, not enough confirmed fixes to trust a supervised model — routes to the same label-free anomaly score as gate 3 below.
- Gini-coefficient gate (fallback). Computes the Gini coefficient of
commit_countacross all functions:- High concentration (a few files dominate commit activity, Gini ≥ 0.55) → the existing formula score (
activity_risk/lrs) is already a sufficient day-one ranking; no model needed. - Low concentration (Gini < 0.55) → fits a label-free
IsolationForeston an 8-feature history vector (commit_count,author_count,author_entropy,burst_score,isolation_rate,age_days,last_touch_days,authors_90d) and ranks by anomaly score.
- High concentration (a few files dominate commit activity, Gini ≥ 0.55) → the existing formula score (
Both anomaly routes (gate 2 and the low-Gini branch of gate 3) use the same IsolationForest implementation — memory-bounded, streaming, no full-matrix intermediate structure. Neither requires a .hotspots/ranker.json model file.
Gini dead zone. The Gini-coefficient gate is stateless and per-run — a repo whose Gini sits just under the 0.55 low threshold could flip from formula to anomaly on a marginal commit. Set cold_start_gini_dead_zone in .hotspotsrc.json (default 0.0) to widen the ambiguous middle zone that already defaults to formula: the effective low threshold becomes 0.55 - cold_start_gini_dead_zone, so Gini values in [0.55 - cold_start_gini_dead_zone, 0.55) route to formula instead of anomaly. The 0.55 and 0.60 constants themselves are unchanged; the dead zone only shrinks the anomaly region. Must be non-negative and less than 0.55.
{
"cold_start_gini_dead_zone": 0.03
}hotspots analyze — ownership risk
Was the standalone hotspots coordinate command; now flags on analyze. Reports ownership risk for a set of files before work starts. Needs only git history (no snapshot or AST analysis) and prints JSON. See USAGE.md for a longer walkthrough.
hotspots analyze [PATH] (--files a.rs,b.rs | --diff | --staged | --ownership)| Flag | Description |
|---|---|
--files <FILES> | Comma-separated file paths to report ownership risk for |
--diff | Derive the file set from a unified diff read on stdin |
--staged | Derive the file set from git diff --cached --name-only |
--ownership | Report ownership risk; defaults to --staged when no other selector is given |
JSON output only today. PATH defaults to .. --files/--diff/--staged are mutually exclusive with each other.
Output is the master-schema envelope's coordinate section (schema_version: 6):
ownership: per-fileauthor_count,author_entropy,newcomer_rate,knowledge_mode("concentrated"for narrow ownership: at most 3 authors and normalized entropy below 0.5; otherwisenull),ownership_risk(normalized author entropy, 0 to 1, higher = more diffuse;nullwith fewer than two authors) andownership_risk_band("low"below 0.754,"medium"below 0.907, else"high"; the cutoffs are terciles from our evaluation; evidence and limits).
There is no recommendation field, and no within_set/hidden_dependencies coupling facts either — both removed in hotspots 2.0 for lack of validated evidence. See USAGE.md for the full rationale and an example walkthrough.
hotspots analyze --prune
Was the standalone hotspots prune command; now a flag on analyze. Reduces the disk space used by the .hotspots/ snapshot history. Requires --prune, plus at least one of --unreachable/--compact:
hotspots analyze --prune --unreachable [--older-than DAYS] [--dry-run]
hotspots analyze --prune --compact LEVEL [--dry-run]| Flag | Description |
|---|---|
--prune | Run pruning instead of analyzing |
--unreachable | Remove snapshots whose commit is no longer reachable from refs/heads/*, refs/tags/* or refs/remotes/* (after a force-push or branch deletion), and snapshots that reference a commit no longer in git history |
--older-than DAYS | With --unreachable: only remove unreachable snapshots older than this many days |
--compact LEVEL | Compact the retained history: 0 keeps full snapshots (the default, and the way to undo a compaction setting), 1 stores intermediate snapshots as deltas against their parent, 2 drops snapshots in which no function changed band |
--dry-run | Report what would change without modifying any files |
Why it exists. Every analyze run writes a snapshot by default, so history grows with every commit analyzed. --prune is the cleanup for that growth.
When to use it. Run --unreachable --dry-run after force-pushes or deleting branches; run --compact 1 on a long-lived repo whose .hotspots/ directory has grown large. Level 2 loses per-commit detail, so use it only when you need band-change history rather than every score.
Reading the output. It prints the number of snapshots pruned or converted and, for compaction, the storage saved. --dry-run prints the same numbers without changing anything.
hotspots analyze --show-config/--validate-config
Was the standalone hotspots config command; now flags on analyze.
hotspots analyze --show-config # show resolved config (merged defaults + file)
hotspots analyze --show-config --config FILE # show a specific file
hotspots analyze --validate-config # validate auto-discovered config (exit 1 on failure)
hotspots analyze --validate-config --config FILE--show-config's output also includes a line reporting whether telemetry is currently enabled (see Telemetry).
hotspots analyze --help-agent [analyze|diff]
Was the standalone hotspots agent command; now a flag on analyze.
hotspots analyze --help-agent # full contract (analyze + diff)
hotspots analyze --help-agent=analyze # scoped to analyze
hotspots analyze --help-agent=diff # scoped to diffPrints a dense, machine-readable contract for a coding agent driving this CLI: an execution contract (always --format json, no interactive prompts except train's), a command/schema map (flag names and JSON shape), exit-code semantics, and guardrails against common mistakes. Plain text to stdout — this flag's own output is the documentation, not data meant to be parsed. No --format flag.
Progress output
All progress goes to stderr, so stdout stays clean for --format json. In a terminal you get a live bar. When stderr is not a terminal (CI, a redirected log), analyze prints labelled lines instead, so a long run shows which phase it is in:
Analyzing: 3630/3630 files [done in 1s]
hotspots: reading git history (churn) (1s elapsed)
hotspots: building call graph (32s elapsed)
hotspots: reading touch history, burst score and scoring functions (34s elapsed)While files are being analysed, a line with the count, elapsed time and an estimated time remaining is printed every 30 seconds, even if no file finished in that interval.
Files in unsupported languages
analyze only reads the languages it supports. Source files it recognises but does not analyze (Kotlin, Swift, Ruby, Scala, Dart, Lua, Objective-C, CUDA) are counted, and one line on stderr says so at the end of the run:
Not analyzed: 622 source file(s) in unsupported languages (515 .rb, 103 .kt, 2 .swift, 1 .cu, 1 .lua). Results cover only the supported languages; see docs/REFERENCE.md.Read it before trusting a ranking on a mixed-language repo: the ranking covers only the languages that were analyzed. Files excluded by your include/exclude config are not counted, and the line is omitted when nothing was left out. It goes to stderr, so JSON on stdout is unchanged.
Files skipped automatically
Some files in a supported language are skipped before parsing, each with one warning: skipping ... line on stderr (JSON on stdout is unchanged). Skipping them keeps one pathological file from dominating a ranking or aborting the whole run.
- Generated or minified code. A file whose first 2 KB contains
@generated,Autogenerated by, orCode generated ... DO NOT EDIT; a file with three or more lines longer than 1,000 characters; a file larger than 4 MiB; and paths undervendor/,third_party/and similar vendored-code directories. - Very deeply nested code. A Rust, TypeScript/JavaScript (including Vue and Astro) or Go file whose bracket nesting is deeper than 1,000 (Rust), 1,500 (TypeScript/JavaScript) or 5,000 (Go) levels. Those parsers recurse and can overflow the thread stack, which aborts the process and loses the whole run. Real hand-written code is nowhere near these depths; a generated fixture can be. This is a safeguard, not a complete fix: a single expression with tens of thousands of operators and no brackets can still overflow.
- Qt translation files. A
.tsfile that begins with an XML declaration,<!DOCTYPE TS>or a<TS ...>root element is a Qt Linguist translation catalog, not TypeScript. Projects such as Bitcoin Core keep dozens of them. - Flow-annotated JavaScript, mostly parsed. A
.jsfile with an@flowpragma is first parsed as JavaScript. If that fails it is retried as TypeScript, then with Flow-only syntax rewritten to same-length TypeScript (nullable?T,{| |}exact objects,opaque type,import typeof,%checks, variance sigils,component Name(...)declarations), and finally with object-type spreads and the inexact...marker removed. Only files that fail plain parsing are rewritten, and line numbers are unchanged. Some Flow syntax is still unsupported (component(...)andinterface {}types,matchexpressions,declareforms), and such a file is skipped with aFailed to parse source filewarning. On React Native, parse failures fell from 1,224 files to 141, of which 46 areflow-typeddeclaration files that contain no functions.
If a file you care about is skipped, the warning says why. Other languages' parsers do not need a nesting limit.
Global flags
hotspots --help
hotspots --versionEnvironment variables
NO_COLOR— disable ANSI colors in text outputGIT_DIR,GIT_WORK_TREE— override git repository locationGITHUB_EVENT_NAME=pull_request— triggers PR-context detection (affects whetheranalyzepersists a snapshot by default)CI_MERGE_REQUEST_IID(GitLab),CIRCLE_PULL_REQUEST(CircleCI),TRAVIS_PULL_REQUEST(Travis) — same effectHOTSPOTS_JOBS=N— parallel worker threads foranalyze(was-j/--jobs; default: CPU count)HOTSPOTS_SKIP_TOUCH_METRICS— set (to any value) to skip all git log I/O inanalyze: touch counts, churn, recency, directed coupling and burst score are omitted. For benchmarking or very large repos (was--skip-touch-metrics)HOTSPOTS_SKIP_GATE— set (to any value) to disableanalyze's suppression gate P@10 check (was--skip-gate)HOTSPOTS_TELEMETRY=on— opt in to anonymous usage pings, off by default; see Telemetry (washotspots telemetry enable/disable)
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success (or warnings only) |
| 1 | Error or blocking policy failure |
| 2 | Auto-analysis failed (hotspots diff --auto-analyze only) |
| 3 | Snapshot missing (hotspots diff only) |
Exit code 4 ("policy requested but could not be evaluated") existed for analyze --mode delta --policy's baseline-delta case; removed along with that mode. diff always requires both snapshots up front (or generates them via --auto-analyze), so it can never reach that state — exit 3 already covers "a snapshot is missing" more specifically.
Metrics
The four structural metrics
CC — Cyclomatic Complexity Number of independent decision paths. Counts: if, else if, for, while, do/while, case, catch, &&, ||, ternary. A function with no branches has CC 1.
ND — Nesting Depth Maximum depth of nested control structures (if, loops, try/catch, switch). Each additional level degrades readability non-linearly. ND ≥ 5 almost always warrants refactoring.
FO — Fan-Out Distinct functions called from within this function. Each call segment in a chained expression counts independently (foo().bar().baz() = 3). High FO = high external coupling.
NS — Non-Structured Exits Count of early returns, throws, breaks, and continues (excluding the final tail return). Scattered exits make control flow hard to trace and postconditions hard to reason about.
LOC — Lines of Code Physical line count. Reported for context only; it is not part of the LRS score.
LRS formula
R_cc = min(log2(CC + 1), 6.0) # logarithmic, capped at 6
R_nd = min(ND, 8.0) # linear, capped at 8
R_fo = min(log2(FO + 1), 6.0) # logarithmic, capped at 6
R_ns = min(NS, 6.0) # linear, capped at 6
LRS = 1.0×R_cc + 0.8×R_nd + 0.6×R_fo + 0.7×R_nsLogarithmic scaling for CC and FO: going from CC 1→4 matters more than CC 40→44. Linear for ND and NS: each additional level contributes uniformly. Caps prevent a single extreme value from dominating.
Theoretical range: 1.0 (trivial) to 20.2 (all four at cap).
Weight rationale: CC (1.0) = primary defect correlate; ND (0.8) = captures complexity CC can miss; NS (0.7) = implicit exit conditions; FO (0.6) = external coupling weighted lower.
These weights, and every other formula in this document, come from evaluation against real repo history rather than intuition — see the hotspots-public-research findings index for the methodology and results, including signals that were tested and rejected.
Risk bands
| Band | LRS range | Typical action |
|---|---|---|
| Critical | ≥ 9.0 | Refactor now |
| High | 6.0–8.9 | Refactor next time you touch it |
| Moderate | 3.0–5.9 | Monitor; block increases in CI |
| Low | < 3.0 | Leave alone |
Thresholds are configurable.
Field stability: absolute vs. population-relative
Output fields fall into two categories with different stability guarantees. This matters when diffing output commit-to-commit or gating CI on it:
| Field | Category | Behavior |
|---|---|---|
lrs | Absolute | Depends only on that function's own metrics (cc, nd, fo, ns). Unchanged unless the function itself changes. |
activity_risk | Absolute | lrs plus its file's git signals on a fixed scale (see Activity Risk below). Does not depend on any other function. Changes when the function, or any commit touching its file, changes. |
band (risk band) | Absolute | A fixed threshold on lrs (see Risk bands above). Moves only when the function's own score crosses a threshold. |
tier | Population-relative | active when the file's touch count is above the repo median or it changed in the last 30 days. The median moves with the rest of the repo, so a function can flip tier even if its own file did not change. |
Implication for CI gates: if you want a gate that only fires when a function's own risk changed — not when the rest of the repo's distribution shifted — key it on lrs, activity_risk, and band. Gates keyed on tier can trip on a commit that didn't touch the flagged function at all, because those labels are recomputed relative to the whole population on every run.
No output field is renamed or restructured by this distinction — it is purely documentation of behavior that already exists in compute_percentiles and compute_tiers (hotspots-core/src/snapshot.rs).
Activity Risk Score (snapshot mode)
Evidence and limits: activity risk formula.
Combines LRS with the file's git history into one absolute score. Each term is scaled to [0, 1] on a fixed scale, so no term swamps the others and the score never depends on the rest of the repo:
Activity Risk = LRS / 20.2
+ min(log2(1 + lines_added_and_deleted) / 14, 1) # churn (180-day window)
+ min(touch_count / 50, 1) # touch frequency (365-day window)
+ max(0, 1 − days_since_last_change / 35) # recencyThe scale constants are fixed in the code (hotspots-core/src/scoring.rs) and are not configurable. The range is roughly 0 to 4; a missing signal contributes 0, so with no git data Activity Risk is just LRS / 20.2. risk_factors in the JSON output breaks the score into {complexity, churn, touch, recency}.
What is and isn't validated. Our evaluation found that git activity (how often and how recently a file changes) carries most of the signal, and that call-graph and dependency-depth terms add none, which is why only activity terms remain. The fixed scales (20.2, 14, 50, 35) and the equal weighting of the four terms are design choices that keep the score bounded and comparable across repos. A small end-to-end comparison found the combined formula no worse than the previous one and modestly better, so treat it as a reasonable default rather than a precisely validated optimum.
How to read it, and why you can't "fix" it. Activity Risk estimates where attention is likely to be needed next, not how good the code is. It is built from how recently and how often a file has changed, so working on a file raises it for every function in that file (churn, touch and recency are file-level), including functions you did not edit. A fix therefore cannot lower it directly; it decays on its own as the file goes quiet (recency over about 35 days, churn over 180 days, touch over 365 days). On a feature branch, recency is measured from before the branch diverged, so your own edits do not reset it. The part a developer can change and see improve is LRS and its band, so use LRS for "did this refactor help" and Activity Risk for "where should I look first". Within each triage bucket, functions are sorted by Activity Risk, so editing one function can reorder its file's other functions in that list.
Only the four terms above feed the score. Fan-in, cyclic dependency, dependency depth, burst and neighbor churn do not: in our evaluation fan-in and cyclic dependency added nothing measurable, dependency depth was sign-inconsistent across repos, and the burst score is a full-history, effectively monotonic value that would make Activity Risk a one-way ratchet. Cyclic dependency, dependency depth, neighbor churn, PageRank and betweenness are no longer computed. fan_in is still reported per function, and burst_score is still computed as a cold-start ranking feature (trainer).
burst_score is a sliding 30-day-window max/mean commit ratio per file (always ≥ 1.0; higher means commits cluster into frantic bursts rather than steady, spread-out changes). For each commit touching a file, it counts how many of that file's commits fall within the following 30 days, then divides the largest such count by the mean — a file with 5 commits crammed into one week scores higher than one with 5 commits spread evenly across a year, even though both have commit_count = 5.
Computed as part of the same single full-history git log --name-only pass used for the other cold-start signals (commit_count, author_count, author_entropy, isolation_rate, age_days, last_touch_days) — one subprocess per hotspots analyze run, not one per file and not a separate walk from those other six signals. Files with fewer than 2 commits get the baseline 1.0 (no burst signal); files with no matching commit history keep burst_score = None.
Validated against real-world defect data: it's one of the strongest signals in a CVE/OSV-linked-file logistic regression (largest standardized coefficient of 5 candidate signals, positive across all leave-one-repo-out folds tested) in our cross-repo evaluation.
Touch window: the git-log window behind touch_count (renamed from touch_count_30d in hotspots 2.0 — the name was always wrong, see the field's rename note) and days_since_last_change is 365 days by default (git::TOUCH_WINDOW_DAYS), based on our pre-registered 13-repo cutoff-safe evaluation — 365 days gave the strongest, monotonic gain of every window tested, with a size-confound check ruling out "it's just counting more commits." On a high-commit-velocity repo this is a real, measured wall-clock cost (a single git subprocess call, but scanning more history: +16ms on a moderate-velocity repo, up to +943ms on a very active one in testing) — set HOTSPOTS_SKIP_TOUCH_METRICS=1 to skip git history entirely if that cost matters more than the ranking-quality gain. The window is fixed and not configurable.
Signal confidence (snapshot mode)
summary.signal_confidence ("low" or "high") and summary.conventional_prefix_rate (a float between 0 and 1, or null) are a repo-level pair: a label telling you whether this repo's authorship-based risk signals (author_entropy and the signals derived from it) have historically been more or less reliable for this specific repo, and the raw rate the label is derived from, shipped side by side so the label is never a black box — anyone can check it against their own repo with git log HEAD -n 500 --format=%s.
conventional_prefix_rate is the fraction of the repo's most recent 500 commits (fewer, on a smaller repo) whose subject line matches a Conventional-Commits-style prefix (feat:, fix(scope)!:, etc.). signal_confidence is "high" when that rate is at least 0.1, otherwise "low". Both are recomputed fresh on every analyze run, never cached — in our evaluation, this kind of commit-message convention is something a repo adopts partway through its life, not a fixed property, so a stale or full-history value would misdescribe current practice. See evidence and limits.
Population-level calibration, not a precise per-repo predictor. In our evaluation, repos in the "high" tier have a higher average authorship-signal reliability than repos in the "low" tier, across a large cross-repo sample — a real, if moderate, pattern. It is not a guarantee for any single repo: at least one repo in our evaluation sample fell in the "low" tier by commit-message convention while still having one of the most reliable authorship signals in the whole sample. Read signal_confidence as a population-calibrated hint about how much weight to put on file_risk_score and related rankings for this repo, not as a certified accuracy rating.
conventional_prefix_rate is null and signal_confidence defaults to "low" (the conservative direction) when a repo has fewer than 20 commits, or when the underlying git log call fails for any reason — it never panics or errors the whole run.
This field does not change file_risk_score, any band boundary, or any ranking order.
Call graph metrics (snapshot mode)
- Fan-in — functions that call this function (blast radius)
Fan-in is the only call graph metric still computed. PageRank, betweenness, strongly connected components, dependency depth and neighbor churn were removed (no validated consumer).
Activity tier
Each function gets a tier of active or quiet, based on activity alone:
active: its file has more touches (in the touch window) than the repo median, or it changed in the last 30 days.quiet: everything else.
Why it exists. The tier answers "is this code being worked on right now?". It makes no claim about how complex the code is; band carries that separately, so you can still select "complex and active" by combining the two. In our evaluation, adding a complexity gate to the activity set did not improve how well it predicted where fixes land, which is why the tier is activity-only. See why the quadrant was replaced.
How to use it. The triage view groups functions into active and quiet, each sorted by activity_risk. Start with the top of active. A function in quiet with a high band is dormant structural risk: not urgent, but worth knowing about before the file becomes active.
tier is population-relative (the median is taken from the current run) — see "Field stability" above before keying a CI gate on it.
Configuration
Config file is auto-discovered from project root in this order:
--config <path>CLI flag (explicit override).hotspotsrc.jsonhotspots.config.json"hotspots"key inpackage.json
The project root is determined by walking up from the analyzed path to find .git. CLI flags take precedence over config file values.
Validate: hotspots analyze --validate-config / Inspect resolved: hotspots analyze --show-config
Test files are excluded by default using each language's naming convention, so ranking is about shipped code: *.test.* and *.spec.* (TypeScript/JavaScript), test_*.py and *_test.py, *_test.go, and, for C and C++, *_test.{c,cc,cpp,cxx}, *_tests.* and *_unittest.*. C/C++ test cases written as macros (TEST(Suite, Name)) would otherwise rank as ordinary functions. Directory-only conventions (a bare tests/ folder) are not excluded; add them under exclude if you want them gone.
Full schema
{
"schema_version": 1,
"include": ["src/**/*.ts"],
"exclude": [
"**/*.test.ts", "**/*.spec.ts",
"**/node_modules/**", "**/__tests__/**", "**/__mocks__/**",
"**/dist/**", "**/build/**", "**/vendor/**",
"**/*.pb.go", "**/zz_generated*.go"
],
"min_lrs": 0.0,
"top": null,
"policy": {
"critical_introduction": "warn",
"critical_introduction_reason": "eval/ scripts are one-shot research code reviewed case-by-case, not shipped services — approved by @stephenc222 2026-07-06",
"excessive_risk_regression": "block"
}
}Fixed, not configurable. The LRS component weights, the risk band cutoffs (3 / 6 / 9), the activity-risk scale constants, the touch window (365 days), the churn window (180 days) and the co-change window (90 days, minimum 3 co-changes) are built in. They were previously configurable but nothing in our evaluation supported tuning them per repo, and one shared definition keeps scores comparable across repos and over time. A config file that still sets one of these keys is rejected as an unknown field.
Validation rules:
policy.*values must be one of"block","warn","off"policy.<name>_reasonis required (non-empty) wheneverpolicy.<name>is not"block"- Unknown fields are rejected (to catch typos)
schema_versionmust not exceed the version this build of hotspots supports
schema_version: defaults to the current config schema version (currently 1) when omitted, so existing .hotspotsrc.json files without it keep working unchanged. Bumped only when a breaking change to config semantics needs migration or explicit detection, mirroring schema_version on snapshot and delta files.
policy: severity overrides for the two blocking CI policies. Both default to "block". critical-introduction fires identically whether a function is brand-new or an existing function that regressed to Critical — a Critical function needs review either way, so there is no separate new-vs-regressed knob, only overall severity. Set to "warn" to report without failing CI (e.g. a research repo where new one-shot scripts are expected to score high on introduction), or "off" to disable the policy entirely. policy only changes what happens once something is Critical; the band cutoffs themselves are fixed.
Downgrading a policy below "block" requires a <name>_reason string — mirroring the // hotspots-ignore: <reason> convention for per-function suppression — so that anyone reviewing a .hotspotsrc.json diff sees why a blocking gate was weakened, not just that it was. hotspots analyze --validate-config rejects a downgrade with a missing or whitespace-only reason. This does not make the override unbypassable — anyone with commit access to the config can still weaken it, the same as anyone with access to a CI workflow file can remove a required check — but it does mean the change can't be silent.
JSON Schema
Schema versions
As of hotspots 2.0, every JSON-emitting command shares one envelope and one schema_version (currently 6) — the pre-2.0 model of separate version constants per command (AGENT_SNAPSHOT_SCHEMA_VERSION, DELTA_SCHEMA_VERSION, a bare unversioned --axes map, etc.) was unified in the 2.0 master-schema cut. The envelope always carries schema_version, commit, and analysis; everything else is an optional section, present only when that command/flag computed it:
| Section | Present when | Contents |
|---|---|---|
functions | always | Full per-function array (FunctionSnapshot) |
summary | always | Population-level aggregate stats |
triage | default analyze, not --all-functions | active/quiet groups, each with a count and the top functions by activity_risk |
architecture | --all-functions | file_risk/modules aggregates |
co_change | --all-functions | File co-change pairs |
coordinate | analyze --files/--diff/--staged/--ownership | Ownership/knowledge-mode facts for a file set |
delta | hotspots diff | deltas array + PR-wide aggregates |
axes | --axes | Risk/Coupling/Ownership per-axis rankings |
--all-functions toggles which sections an analyze run populates (full architecture/co_change instead of the triage buckets) — it is not a different schema version, just a different set of sections inside the same envelope. Always check schema_version before consuming output in tooling, and check for a section's presence (Option/possibly-absent key) rather than assuming it's always there.
analysis.formula_version is a separate integer that tracks the scoring formula (the activity_risk constants, LrsWeights, RiskThresholds), bumped only when a weight, threshold or scale constant changes. analysis.tool_version changes on every release; formula_version does not — use it in hotspots diff tooling to tell a score delta caused by a tool upgrade apart from one caused by a real code change.
formula_version vs. config schema_version — not the same thing.formula_version tracks changes to hotspots' built-in weights/thresholds/scales (the scoring.rs constants, LrsWeights::default() etc.) and is unaffected by a user's own .hotspotsrc.json — a repo with fully custom weights sees the same formula_version as one with no config at all, because their scoring didn't change even when the shipped defaults did. Config schema_version (above) tracks the shape/meaning of the config file format itself — e.g. a field being renamed or changing units — independent of what any particular default value is. A release that changes a default weight's value bumps formula_version only; a release that changes what a config field means bumps schema_version (and formula_version too, if that also changes computed scores). Note formula_version today only covers default-value changes, not changes to the scoring formula's structure (e.g. adding/removing a term from compute_activity_risk) — a structural change is not guaranteed to bump it.
Function fields (functions[], FunctionSnapshot)
{
"function_id": "src/api/billing.ts::processPlanUpgrade",
"file": "src/api/billing.ts",
"line": 142,
"language": "TypeScript",
"metrics": { "cc": 15, "nd": 4, "fo": 8, "ns": 3, "loc": 48 },
"lrs": 12.4,
"band": "critical",
"suppression_reason": null,
"churn": { "lines_added": 156, "lines_deleted": 89 },
"touch_count": 12,
"days_since_last_change": 3,
"callgraph": { "fan_in": 8 },
"activity_risk": 2.18,
"risk_factors": { "complexity": 0.59, "churn": 0.60, "touch": 0.24, "recency": 0.74 },
"tier": "active",
"subsystem": "",
"authors_90d": 2,
"directed_coupling": 0.31
}This is the full per-function shape in functions[] — present on every analyze run, with or without --all-functions. suppression_reason is omitted (not null) when no suppression is present. risk_factors is the {complexity, churn, touch, recency} breakdown that sums into activity_risk (see Activity Risk above) — fan_in/cyclic_dependency/depth/burst have no field here; they were removed from RiskFactors in hotspots 2.0.
This is distinct from the triage view's per-function entries (triage.{active,quiet}.top[], present on a default analyze run without --all-functions): those use a slimmer shape (function, file, line, band, tier, lrs, activity_risk, metrics, touch_count, days_since_last_change, fan_in) that omits risk_factors/callgraph's other fields/suppression_reason/subsystem/ authors_90d/directed_coupling. Don't assume the two shapes are interchangeable when writing a consumer against this schema.
lrs, activity_risk, and band are absolute — stable across runs unless the function's own metrics/history change. tier is population-relative — it can change between runs purely because other functions in the repo changed, even when this function did not. See "Field stability" under Metrics above.
Aggregates (--all-functions)
aggregates.file_risk — per-file ranked by file_risk_score:
file_risk_score = max_cc×0.4 + avg_cc×0.3 + log2(fn_count+1)×0.2Unvalidated heuristic — these component weights have no validation behind them, unlike lrs/activity_risk. Treat file_risk_score as a convenience ranking, not a calibrated signal. (The formula previously included a churn_factor×0.1 term and a file_churn field; both were removed — file_churn was always 0 in practice due to a file-path-matching bug in populate_churn's lookup, confirmed via our testing, including a direct smoke test against this repo.)
Validated for within-diff review triage, not for finding a bug repo-wide. In our evaluation, file_risk_score was tested two different ways. Given a bounded diff a reviewer is already looking at (e.g. a PR's changed files), ranking those files by file_risk_score put the file that later needed a fix in the #1 slot 57.3% of the time (134/234 real fix-commit instances, 25 repos/8 languages), vs. 19.7% for a raw lines-changed baseline — a real win on 23 of 25 repos, tied on the other 2, losing on none (McNemar exact test, p=2.65e-19). A sample-size convergence check confirms the result is stable, not an artifact of how much data was collected. Given the whole repo with no bounded diff, three separate attempts (an LLM agent with hotspots as an optional tool, the same with an instance-aware prompt, and the triage view handed over as static context) all converged on the same low hit rate as plain investigation with no tool at all. Read file_risk_score as "of the files already in front of you, which deserves the closest look," not as a tool for finding which file in an entire repository has a bug. (n=234 across 25 repos; still not formally pre-registered. A follow-up found max_cc alone — the single most complex function in the file — carries nearly all of this signal; the other two terms add little at the margin, an explainability note, not a formula change.)
No "refactor soon" cutoff is officially recommended for file_risk_score in this doc. If you want a rough high-risk marker, our 16-repo/82,574-file empirical distribution puts the 90th percentile at approximately 7.0 (p50 ≈ 2.9, p95 ≈ 9.6) — this is a percentile convenience marker from the real score distribution, not a defect-correlation-validated threshold.
aggregates.co_change — file pairs that change together in the same commit:
{
"file_a": "hotspots-cli/src/main.rs",
"file_b": "hotspots-core/src/aggregates.rs",
"co_change_count": 14,
"coupling_ratio": 0.78,
"has_static_dep": false,
"risk": "high"
}risk: "expected" = a static import exists; co-change is explained.
Delta output
hotspots diff's JSON output is the 2.0 master-schema envelope (schema_version: 6, unified with the snapshot schema version): the diff itself nested under delta. There is no separate top-level commit — delta.commit.sha already carries the head commit, and the master schema has zero field duplication (no value appears twice under different paths), so it isn't repeated at the envelope's top level too.
{
"schema_version": 6,
"delta": {
"commit": { "sha": "abc123", "parent": "def456" },
"baseline": false,
"deltas": [{
"function_id": "src/api/billing.ts::processPlanUpgrade",
"status": "modified",
"before": { "lrs": 11.0, "band": "high", "metrics": { "cc": 13, "nd": 3, "fo": 7, "ns": 2 } },
"after": { "lrs": 12.4, "band": "critical", "metrics": { "cc": 15, "nd": 4, "fo": 8, "ns": 3 } },
"delta": { "cc": 2, "nd": 1, "fo": 1, "ns": 1, "lrs": 1.4 },
"band_transition": { "from": "high", "to": "critical" }
}],
"policy": {
"failed": [{ "id": "critical-introduction", "severity": "blocking", "message": "..." }],
"warnings": []
},
"aggregates": {
"files": [{
"file": "src/api/billing.ts",
"net_lrs_delta": 1.4,
"regression_count": 1,
"improvement_count": 0,
"file_risk_score": 7.8,
"file_risk_diff_percentile": 0.94,
"file_risk_top_decile": true
}],
"pr_summary": {
"fn_changed_lines": 23,
"band": "critical",
"new_count": 0,
"modified_count": 1,
"deleted_count": 0,
"regression_count": 1,
"improvement_count": 0,
"band_upgrades": 1,
"policy_blocking": true
}
}
}
}Delta statuses: new, deleted, modified, unchanged (unchanged omitted by default).
delta.aggregates.files — one entry per changed file, net_lrs_delta sorted descending (worst regressions first). file_risk_score, file_risk_diff_percentile, and file_risk_top_decile rank that file's file_risk_score against only the other files changed in this same diff — not repo-wide, unlike aggregates.file_risk above. A file at or above the 90th percentile of that diff-local ranking gets file_risk_top_decile: true. The three fields are omitted for a file with no file_risk_score at all (deleted, or an unscoreable type) rather than populated with a zero that would look like a real low score; a diff with only one scoreable file gets no percentile/flag for it either (no meaningful relative rank in a population of one). In our evaluation this diff-local top decile was a real, cutoff-robust signal — replicated on repos outside the original sample — even though file_risk_score's raw value does not calibrate as an absolute probability (see the evidence in the public findings index — look for the top-decile flag row). --format text marks these files with [top 10%] inline.
delta.aggregates.pr_summary — collapses every changed function into a single PR-wide view. band is the highest risk band reached by any new/modified function's after state; the counts and band_upgrades summarize what changed.
fn_changed_lines is the count of diff-changed lines (git diff -U0) that fall inside a touched function's line span, summed across the whole diff. In our evaluation, tested directly against the real compiled binary, it was the strongest predictor of which PRs later need a defect fix, beating every LRS-weighted score tried on every repo tested. That is why no composite "PR risk score" is reported: read fn_changed_lines for "is this PR risky" and band for "what is the worst code in this diff". See the evidence. Present whenever aggregates is attached (always true for hotspots diff output).
Supported Languages
| Language | Extensions |
|---|---|
| TypeScript | .ts, .tsx, .mts, .cts, .mtsx, .ctsx |
| JavaScript | .js, .jsx, .mjs, .cjs, .mjsx, .cjsx |
| Go | .go |
| Python | .py, .pyw |
| Rust | .rs |
| Java | .java |
| C / C headers | .c, .h |
| C++ | .cpp, .cc, .cxx, .hpp, .hxx, .hh |
| C# | .cs |
| PHP | .php |
| Vue | .vue |
| Astro | .astro |
All languages have full parity across all metrics and features, with the C++ caveats below. Vue and Astro score only the <script> block / --- frontmatter fence respectively — template/markup sections are not analyzed for complexity.
C++ notes
- The score's ranking was checked on C++: it puts files that later get bug fixes above chance, mostly through its git-activity terms, but misses most of them in absolute terms, so treat it as an ordering to read first, not a detector. See Why the formula looks like this.
- Function names. Free functions keep their plain name. Members and functions inside namespaces or classes are qualified (
ns::Class::method,Foo::~Foo,Foo::operator==). If two functions in one file share a qualified name (overloads), each gets its parameter types appended, for examplef(int)andf(std::string&), so deltas can tell them apart. - Lambdas count toward the function that contains them and are not reported separately.
- Macros are not expanded. Code that depends on macros the parser cannot see (for example a namespace opened by a macro, as in some header-only libraries) may be named without its namespace or, if the macro makes the syntax unparseable, left out of the ranking.
.hfiles are parsed as C unless they contain C++ markers in code (class,template,namespace,::, range-basedfor, access labels), in which case they are parsed as C++. Markers inside comments and string literals are ignored, so a C header that mentions "size class" in a comment stays C. A header with no marker is also parsed as C++ if the C grammar reports errors and the C++ grammar parses it without any (for example one using references orconstexpr).- Objective-C++ (
.mm) and CUDA (.cu) are not supported.
JSX note: .jsx and .tsx files support JSX syntax. Plain .js files also enable JSX parsing (React webpack convention). JSX elements do not add CC; control flow in JSX (&&, ternary) does.
Scoring Changelog
All changes to formulas, weights, thresholds, or ranking rules are tracked in git commit history. The LRS formula and default weights have been stable since v1.0. The trained ranker feature was introduced in a later release; the current model is model_version 6 (9 features). Check CHANGELOG.md for version-specific details.
- The
authors_90danddirected_coupling--explainphrases were reworded from directive to descriptive language (e.g. "no clear owner" → "no single frequent owner in recent history") after four independent tests found no outcome benefit from acting on the ownership/coupling diagnosis.