Skip to main content

Hotspots

Hotspots

CI Security

Website: https://hotspots.dev  |  Docs: https://docs.hotspots.dev  |  Crates.io: 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 (full formula, caps, and weight rationale).

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 · Astro

All 13 file extensions (.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .go, .py, .rs, .java, .c, .h, .cs, .vue, .astro) 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

Telemetry (opt-in)

Off by default. If you choose to enable it, hotspots sends one anonymous ping a day (version, OS, architecture, install channel, subcommand name, random install id) so I can see real usage and decide what to improve. No code, paths or results. Run hotspots telemetry show to see exactly what would be sent, and hotspots telemetry disable to turn it off. Details: docs/TELEMETRY.md.


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


License

MIT — see LICENSE-MIT.

Metadata

Release files for hotspots-cli 2.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for hotspots-cli 2.6.2
File Interpreter ABI Platform Actions
hotspots_cli-2.6.2-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for hotspots_cli-2.6.2-py3-none-win_amd64.whl
hotspots_cli-2.6.2-py3-none-manylinux_2_39_x86_64.whl Python 3 none Linux glibc 2.39+ x86-64 Details for hotspots_cli-2.6.2-py3-none-manylinux_2_39_x86_64.whl
hotspots_cli-2.6.2-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for hotspots_cli-2.6.2-py3-none-macosx_11_0_arm64.whl

Total release size: 22.2 MB

Release files / hotspots_cli-2.6.2-py3-none-win_amd64.whl

Download URL hotspots_cli-2.6.2-py3-none-win_amd64.whl
Size 7.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
915dbdaef788d498193070f806ca88c589da1c8b280aa40c60f800f0c5b76057
BLAKE2b-256 checksum
How to use checksums
02f853418c38ee50335cc0089a4070bed5c272bd17e0a03db41b2d5024afbd6c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

Release files / hotspots_cli-2.6.2-py3-none-manylinux_2_39_x86_64.whl

Download URL hotspots_cli-2.6.2-py3-none-manylinux_2_39_x86_64.whl
Size 7.8 MB
Tags Linux glibc 2.39+ x86-64 Python 3
SHA-256 checksum
How to use checksums
607f5d3d521e6c4f52c61b27082d0270d54ea471e3b4f89464f21f6e35893c31
BLAKE2b-256 checksum
How to use checksums
6d0acd0947a6b85730134b7250ac73cf9033ac5a793cd68f6fc11269387d27ab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

Release files / hotspots_cli-2.6.2-py3-none-macosx_11_0_arm64.whl

Download URL hotspots_cli-2.6.2-py3-none-macosx_11_0_arm64.whl
Size 7.0 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
963961579bac0ef7adb613f7b49deae8f6020aca904969356f830776ef91c6ee
BLAKE2b-256 checksum
How to use checksums
11b1c2a43f1aee2456b001094f2952ab80dc1d171b155c689b24c9934f4bff32
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.16.0

Security for hotspots-cli 2.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.6.2 This release

3 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page