hotspots-cli 1.29.0

Static analysis CLI for TypeScript, JavaScript, Go, Python, Rust, and Java that computes Local Risk Score (LRS)

Hotspots

Website: https://hotspots.dev  |  Docs: https://docs.hotspots.dev  |  Crates.io:

Install: brew install Stephen-Collins-tech/tap/hotspots  |  npm install -g @stephencollinstech/hotspots  |  pip install hotspots-cli  |  cargo install hotspots-cli

Find the code that's actually causing problems.

Your codebase has thousands of functions. Some are messy but never break. Others are complex AND change constantly — those are your hotspots, the 20% of code causing 80% of your bugs, incidents, and slowdowns.

---

Install

brew install Stephen-Collins-tech/tap/hotspots   # macOS
npm install -g @stephencollinstech/hotspots       # any platform
pip install hotspots-cli                          # any platform
cargo install hotspots-cli                        # Rust toolchain
curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh  # Linux

Windows: download the binary from GitHub Releases.

Verify: hotspots --version

GitHub Action:

- uses: Stephen-Collins-tech/hotspots/action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

---

Quick Start

# Find your hotspots
hotspots analyze src/

# Critical (LRS ≥ 9.0):
# processPlanUpgrade    src/api/billing.ts:142    LRS 12.4  CC 15  ND 4  FO 8  NS 3
#
# High (6.0 ≤ LRS < 9.0):
# validateSession       src/auth/session.ts:67    LRS 9.8   CC 11  ND 3  FO 7  NS 2

Critical = refactor now. High = refactor next time you touch it. Moderate = block increases. Low = leave it alone.

Common commands

# Per-function explanations with refactoring advice
hotspots analyze . --mode snapshot --format text --explain --top 10

# Block complexity regressions in CI
hotspots analyze src/ --mode delta --policy

# Compare any two git refs
hotspots diff main HEAD --top 10 --policy

# Interactive HTML report
hotspots analyze src/ --mode snapshot --format html

# JSON for tooling/AI
hotspots analyze src/ --format json

# Track trends over time
hotspots trends .

# Train a repo-specific ranker from your bug history
hotspots train . --blame --eval

---

How It Works

Hotspots computes a Local Risk Score (LRS) per function from four structural metrics:

Metric	What it measures
CC — Cyclomatic Complexity	Independent decision paths (if/loop/catch/&&/||)
ND — Nesting Depth	Maximum depth of nested control structures
FO — Fan-Out	Distinct functions called
NS — Non-Structured Exits	Early returns, throws, breaks

LRS = 1.0×R_cc + 0.8×R_nd + 0.6×R_fo + 0.7×R_ns

where each component is log-scaled and capped to prevent outliers from dominating.

In snapshot mode, LRS is combined with git history (churn, touch frequency, recency) and call graph metrics (fan-in, PageRank, SCC membership) to compute an Activity Risk Score and place each function in a triage quadrant:

Quadrant	Complexity	Activity	Action
fire	High	High	Refactor now
debt	High	Low	Schedule before next push
watch	Low	High	Monitor
ok	Low	Low	Leave it alone

Risk bands: Low (< 3) · Moderate (3–6) · High (6–9) · Critical (≥ 9)

---

Supported Languages

TypeScript · JavaScript · Go · Python · Rust · Java · C/C headers · C# · Vue

All 12 file extensions (.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .go, .py, .rs, .java, .c, .h, .cs, .vue) work out of the box.

---

CI/CD Integration

GitHub Action (zero config)

name: Hotspots
on: [pull_request, push]
jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: Stephen-Collins-tech/hotspots-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Posts PR comments, generates HTML reports, fails builds on policy violations.

Manual CI

# Fail CI if new critical functions introduced or LRS increases ≥ 1.0
hotspots analyze src/ --mode delta --policy

Exit code 1 on blocking violations, 0 on warnings only.

---

Key Features

Policy engine — blocks: new critical-risk functions, LRS regressions ≥ 1.0, net repo regression ≥ 5.0. Warns: approaching thresholds, rapid growth > 50%.

Driver labels — each function gets a primary diagnosis: high_complexity, deep_nesting, exit_heavy, high_churn_low_cc, high_fanout_churning, high_fanin_complex, cyclic_dep, or composite.

Pattern detection — 13 named patterns in two tiers: structural (always, e.g. complex_branching, god_function) and enriched (snapshot mode, e.g. churn_magnet, cyclic_hub, volatile_god).

Suppression comments — exclude functions from CI failures while keeping them visible:

// hotspots-ignore: legacy payment processor, rewrite scheduled Q2 2026
function legacyBillingLogic() { ... }

Trained ranker — fit a RandomForest from your repo's bug-fix history:

hotspots train . --blame --eval   # train + check P@K vs base rate

Output formats — text (terminal), json (machine), jsonl (streaming), html (interactive), sarif (GitHub Code Scanning).

Configuration — .hotspotsrc.json in project root (auto-discovered):

{
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.test.ts"],
  "thresholds": { "moderate": 3.0, "high": 6.0, "critical": 9.0 },
  "weights": { "cc": 1.0, "nd": 0.8, "fo": 0.6, "ns": 0.7 }
}

---

Documentation

• docs/USAGE.md — workflows, CI setup, output formats, policy engine, suppression, training, snapshot management
• docs/REFERENCE.md — complete CLI reference, all flags, config options, JSON schema, metrics formula
• docs/ARCHITECTURE.md — system design, analysis pipeline, invariants, design decisions
• docs/CONTRIBUTING.md — dev setup, adding languages, release process

---

Why Hotspots?

vs ESLint complexity rules — ESLint checks one metric in isolation with no git context. Hotspots combines four metrics, git history, and call graph topology into a single prioritized list.

vs SonarQube / CodeClimate — Enterprise platforms requiring server infrastructure. Hotspots is a single binary, zero config, works offline, results in seconds.

vs code reviews — Reviews catch complexity subjectively and miss gradual drift. Hotspots enforces objective thresholds automatically on every commit.

---

Contributing

• Bug reports: GitHub Issues
• Feature requests: GitHub Discussions
• PRs: see docs/CONTRIBUTING.md

---

License

MIT — see LICENSE-MIT.