Skip to content
Stephen-Collins-techPublic

About

Find the riskiest code in any repo. A CLI for surfacing complexity hotspots and refactor targets.

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Latest commit

 

History

792 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Hotspots

Hotspots

CI Security npm downloads

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.

New here? Start with the Quick Start guide.

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 . --format text --explain --top 10

# Block complexity regressions in CI
hotspots diff --auto-analyze --policy

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

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

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

# Train a repo-specific ranker from your bug history (always runs its own P@K eval)
hotspots train . --blame

# Driving this CLI from a coding agent? Start here
hotspots analyze --help-agent

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).

Every analyze run also combines LRS with the file's git history (churn, touch frequency, recency) into an absolute Activity Risk Score, and marks each function active (its file is touched more than the repo median, or changed in the last 30 days) or quiet:

Activity Risk = LRS/20.2 + churn + touch + recency      (each term scaled to 0–1)

Activity Risk says where attention is likely needed next, not how good the code is. Editing a file raises it for every function in the file and it decays as the file goes quiet, so use the risk band (from LRS) to judge structure and Activity Risk to decide where to look first. See Activity Risk and Activity tier.

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

These formulas aren't hand-tuned guesses — every weight, cutoff, and signal that made it into the CLI was validated (or rejected) against real repo history and ground-truth bug/fix data in the open hotspots-public-research repo. See its findings index for the evidence behind each shipped feature, including the negative results that kept things out.


Supported Languages

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

All supported file extensions (.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .go, .py, .rs, .java, .c, .h, .cpp, .cc, .cxx, .hpp, .hxx, .hh, .cs, .php, .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 diff --auto-analyze --policy

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


Key Features

Policy engine — blocks: new critical-risk functions and LRS regressions ≥ 1.0.

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 (training always checks P@K vs. base rate before saving the model):

hotspots train . --blame

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

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

{
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.test.ts"],
  "min_lrs": 0.0,
  "policy": { "critical_introduction": "block" }
}

Documentation

  • docs/COMMANDS.md — every command: why it exists, when to use it, how to read its output
  • 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
  • hotspots-public-research — the published evidence behind the scoring formulas: what was tested, what shipped, and what was rejected

Telemetry (opt-in)

Off by default. If you choose to enable it (set HOTSPOTS_TELEMETRY=on), 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 analyze --show-config to see whether it's currently on, and unset HOTSPOTS_TELEMETRY (or set it to anything other than on) 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.

About

Find the riskiest code in any repo. A CLI for surfacing complexity hotspots and refactor targets.

Topics

Resources

Contributing

Security policy

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages