I Built a CLI to Find the Riskiest Code in Any Repo — Introducing Hotspots

Source: Dev.to

Every team has those files.
The ones everyone knows are dangerous. The ones where a “simple” change takes three days of careful testing. The ones that keep showing up in post‑mortems.

I spent a long time noticing that pattern—the same 10 % of a codebase causing 80 % of the pain—and wondering why our tooling didn’t just show us where that 10 % was. ESLint can tell you a function has high cyclomatic complexity, but that doesn’t tell you whether it’s actively being changed, who’s touching it, or whether it’s likely to bite you in the next sprint.

So I built Hotspots – a Rust CLI that finds risky code by combining structural complexity with real Git activity.

---

The Core Idea: Complexity × Change

Raw complexity metrics are useful, but they’re incomplete. A gnarly function that hasn’t been touched in two years isn’t your emergency today. The real danger is complexity plus active change — functions that are structurally hard to reason about and are being modified regularly.

Hotspots computes a risk score for every function in your codebase by combining:

The result is an activity‑weighted risk score – a prioritized list of functions that are both dangerous and active. Not “functions you should eventually clean up.” Functions you should care about this sprint.

---

Getting Started

Install

curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh

Run a snapshot

hotspots analyze . --mode snapshot --format text

You’ll get a ranked output grouped into risk bands, e.g.:

Critical (risk ≥ 9.0):
  processPlanUpgrade    src/api/billing.ts:142    risk 12.4  CC 15  ND 4  FO 8

High (6.0 ≤ risk  snapshot.json

In v1.2.0, Hotspots detects two tiers of patterns:

Tier 1 – Structural

• complex_branching
• deeply_nested
• exit_heavy
• long_function
• god_function

Tier 2 – Relational & Temporal

• hub_function
• cyclic_hub
• middle_man
• neighbor_risk
• stale_complex
• churn_magnet
• shotgun_target
• volatile_god

A function tagged god_function + cyclic_hub is both monolithic and at the center of a dependency cycle — a very different refactoring situation than one tagged exit_heavy + long_function. The labels make the action obvious.

---

CI Policy Checks: Stop Regressions Before They Merge

Identifying hotspots is useful. Preventing new ones from landing is better. Hotspots has a delta mode that compares the current branch against the baseline and applies configurable policy checks:

hotspots analyze . --mode delta --policy

Available policies

• Critical Introduction – fail if a new function lands in the critical band
• Excessive Regression – fail if a function’s risk score jumps by a large delta
• Rapid Growth – flag unusually fast complexity growth
• Watch/Attention – warn when functions approach thresholds

Add it to CI; start in warn‑only mode, then flip to blocking when you’re ready.

Example GitHub Actions step

- name: Hotspots policy check
  run: hotspots analyze . --mode delta --policy

The command exits with code 1 if any blocking policy fails, otherwise 0.

---

hotspots.dev – Automated OSS Analysis

Alongside the CLI, I’ve built hotspots.dev – a blog that runs automated Hotspots analyses on trending open‑source repos every night.

Pipeline

1. A GitHub Actions crawl job selects a fresh trending repo.
2. Hotspots analyzes it and extracts the top functions and antipatterns.
3. An AI draft gets generated and opened as a PR for review.
4. Once merged, it deploys automatically.

The HTML reports are hosted at reports.hotspots.dev, so you can drill into the full ranked analysis for any repo. It’s a real‑world showcase of what the tool surfaces in popular codebases — eslint, Flowise, and more. The hotspots are rarely where you’d guess.

---

Try It

# Install
curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh

# Snapshot your current repo
hotspots analyze . --mode snapshot --format text

# Full JSON with pattern labels
hotspots analyze . --mode snapshot --format json --explain-patterns > snapshot.json

# CI policy check
hotspots analyze . --mode delta --policy

Docs:
Live analyses:

[spots.dev/](https://spots.dev/)

🦀 **Source:** [github.com/Stephen-Collins-tech/hotspots](https://github.com/Stephen-Collins-tech/hotspots)

- **License:** MIT  
- **Written in:** Rust  
- **Language support:** Works on any language (operates on Git history and AST‑level metrics rather than language‑specific rules)

> If you've ever looked at a PR and thought *“this feels risky but I can't explain why”* — run **Hotspots**. It'll tell you why.

### TL;DR

Complexity metrics alone miss the point. **Hotspots** combines structural analysis with real Git activity to surface the functions that are both **hard to change** *and* **actively being changed**.  

- Rust CLI  
- Works on any language  
- Can gate PRs in CI  

[Try it.](https://github.com/Stephen-Collins-tech/hotspots)