hotspots-cli 1.25.1__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,655 @@
1
+ Metadata-Version: 2.4
2
+ Name: hotspots-cli
3
+ Version: 1.25.1
4
+ Classifier: Development Status :: 5 - Production/Stable
5
+ Classifier: Intended Audience :: Developers
6
+ Classifier: License :: OSI Approved :: MIT License
7
+ Classifier: Programming Language :: Rust
8
+ Classifier: Topic :: Software Development :: Quality Assurance
9
+ License-File: LICENSE-MIT
10
+ Summary: Static analysis CLI for TypeScript, JavaScript, Go, Python, Rust, and Java that computes Local Risk Score (LRS)
11
+ Keywords: hotspots,complexity,static-analysis,typescript,code-quality,lrs,cyclomatic-complexity
12
+ Home-Page: https://hotspots.dev
13
+ License: MIT
14
+ Requires-Python: >=3.8
15
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
16
+ Project-URL: Homepage, https://hotspots.dev
17
+ Project-URL: Issues, https://github.com/Stephen-Collins-tech/hotspots/issues
18
+ Project-URL: Repository, https://github.com/Stephen-Collins-tech/hotspots
19
+
20
+ <p align="center">
21
+ <img src="assets/logo.svg" alt="Hotspots" width="96" height="96" />
22
+ </p>
23
+
24
+ # Hotspots
25
+
26
+ [![CI](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/ci.yml/badge.svg)](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/ci.yml)
27
+ [![Security](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/security.yml/badge.svg)](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/security.yml)
28
+
29
+ **Website:** https://hotspots.dev &nbsp;|&nbsp; **Docs:** https://docs.hotspots.dev &nbsp;|&nbsp; **Crates.io:** [![crates.io](https://img.shields.io/crates/v/hotspots-cli.svg)](https://crates.io/crates/hotspots-cli)
30
+
31
+ **Install:** `cargo install hotspots-cli` &nbsp;|&nbsp; `curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh`
32
+
33
+ **Find the code that's actually causing problems.**
34
+
35
+ 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.
36
+
37
+ Stop refactoring code that doesn't matter. Focus on what's hurting you right now.
38
+
39
+ ---
40
+
41
+ ## The Problem
42
+
43
+ You know your codebase has tech debt. But which code should you actually refactor?
44
+
45
+ ❌ **Refactor by gut feeling** → Waste weeks on code that rarely causes issues
46
+ ❌ **Refactor everything** → Impossible, and you'll rewrite stable code that doesn't need touching
47
+ ❌ **Refactor nothing** → Tech debt compounds until "fix this bug" becomes "rewrite everything"
48
+
49
+ **The real question:** Which functions are both complex AND frequently changed?
50
+
51
+ Those are the functions causing production incidents, slowing down features, and burning out your team.
52
+
53
+ ---
54
+
55
+ ## The Solution
56
+
57
+ Hotspots analyzes your codebase and git history to find functions that are:
58
+
59
+ 1. **Complex** - High cyclomatic complexity, deep nesting, lots of branching
60
+ 2. **Volatile** - Changed frequently in recent commits
61
+ 3. **Risky** - The dangerous combination of both
62
+
63
+ Instead of guessing what to refactor, you get a prioritized list:
64
+
65
+ ![Hotspots Example Report](https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/assets/hotspots-example-report.png)
66
+
67
+ *Risk Landscape from a real 7,911-function codebase: 284 Critical (red), 491 High (orange). Each dot is a function — top-right are your hotspots.*
68
+
69
+ ```bash
70
+ hotspots analyze src/
71
+
72
+ # Output:
73
+ Critical (LRS ≥ 9.0):
74
+ processPlanUpgrade src/api/billing.ts:142 LRS 12.4 CC 15 ND 4 FO 8 NS 3
75
+
76
+ High (6.0 ≤ LRS < 9.0):
77
+ validateSession src/auth/session.ts:67 LRS 9.8 CC 11 ND 3 FO 7 NS 2
78
+ applySchema src/db/migrations.ts:203 LRS 8.1 CC 10 ND 2 FO 5 NS 2
79
+ ```
80
+
81
+ Now you know exactly where to focus.
82
+
83
+ ---
84
+
85
+ ## What You Get
86
+
87
+ ### ✅ Refactor What Actually Matters
88
+
89
+ Stop wasting time on code that "looks messy" but never causes problems. Focus on the 20% of functions responsible for 80% of your incidents.
90
+
91
+ ### ✅ Block Complexity Regressions in CI
92
+
93
+ Catch risky changes before they merge:
94
+
95
+ ```bash
96
+ # Run in CI with policy checks
97
+ hotspots analyze src/ --mode delta --policy
98
+ # Exit code 1 if policies fail → CI fails
99
+ ```
100
+
101
+ Your CI fails if someone introduces high-risk code. No manual review needed.
102
+
103
+ **GitHub Actions** — use the native action for zero-config CI integration:
104
+
105
+ ```yaml
106
+ - uses: Stephen-Collins-tech/hotspots/action@v1
107
+ with:
108
+ github-token: ${{ secrets.GITHUB_TOKEN }}
109
+ ```
110
+
111
+ See [docs/guide/github-action.md](docs/guide/github-action.md) for the full action reference.
112
+
113
+ ### ✅ Fine-Tune Rankings with Repo-Specific ML
114
+
115
+ The default heuristic ranker works out of the box, but every codebase is different. Train a local RandomForest ranker from your own fix-commit history to score functions based on patterns that actually predict bugs in your repo:
116
+
117
+ ```bash
118
+ # Fit a ranker from the last year of fix commits (precise blame-based labels)
119
+ hotspots train . --blame
120
+
121
+ # Next analyze picks up the trained ranker automatically
122
+ hotspots analyze .
123
+ ```
124
+
125
+ The trained model learns which structural features (complexity, churn, call graph) correlate with real bug fixes in your history — not a generic heuristic. Scores are saved to `.hotspots/ranker.json` and reused on every subsequent `analyze`.
126
+
127
+ **Not sure if training actually helped?** Use `--eval` to check:
128
+
129
+ ```bash
130
+ hotspots train . --eval
131
+ ```
132
+
133
+ This prints a Precision@K table after training — how many of the top-K ranked functions were genuinely in fix commits:
134
+
135
+ ```
136
+ P@K evaluation (365-day fix-label window):
137
+ K P@K base_rate
138
+ 10 0.400 0.084
139
+ 20 0.300 0.084
140
+ 50 0.200 0.084
141
+ 100 0.150 0.084
142
+ 200 0.110 0.084
143
+ ```
144
+
145
+ **How to read it:** `base_rate` is the fraction of all functions that appeared in a bug-fix commit. If `P@10` is much higher than `base_rate`, the ranker is genuinely surfacing risky functions at the top. If `P@10` ≈ `base_rate`, the model is no better than random — skip applying it and rely on the default LRS ranking instead.
146
+
147
+ ### ✅ Ship with Confidence, Not Crossed Fingers
148
+
149
+ Know which files are landmines before you touch them. See complexity trends over time. Make informed decisions about refactoring vs rewriting vs leaving it alone.
150
+
151
+ ### ✅ Get AI-Assisted Refactoring
152
+
153
+ Hotspots integrates with Claude Code, Cursor, and GitHub Copilot. Point your AI at the hottest functions and get refactoring suggestions that actually improve your codebase.
154
+
155
+ ```bash
156
+ # Analyze changes in your project
157
+ hotspots analyze . --mode delta --format json
158
+
159
+ # Get agent-optimized output (quadrant buckets + action text)
160
+ hotspots analyze . --mode delta --all-functions --format json
161
+ ```
162
+
163
+ ---
164
+
165
+ ## Quick Start
166
+
167
+ ### 1. Install
168
+
169
+ **cargo (Rust toolchain):**
170
+ ```bash
171
+ cargo install hotspots-cli
172
+ ```
173
+
174
+ **macOS / Linux:**
175
+ ```bash
176
+ curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh
177
+ ```
178
+
179
+ Installs to `~/.local/bin/hotspots`. Verify with `hotspots --version`.
180
+
181
+ **GitHub Action:**
182
+ ```yaml
183
+ - uses: Stephen-Collins-tech/hotspots/action@v1
184
+ with:
185
+ github-token: ${{ secrets.GITHUB_TOKEN }}
186
+ ```
187
+ See [docs/guide/github-action.md](docs/guide/github-action.md) for inputs, outputs, and examples.
188
+
189
+ ### 2. Analyze Your Code
190
+
191
+ ```bash
192
+ # Find your hotspots
193
+ hotspots analyze src/
194
+
195
+ # Filter to critical functions only
196
+ hotspots analyze src/ --min-lrs 9.0
197
+
198
+ # Get per-function explanations with driver labels
199
+ hotspots analyze . --mode snapshot --format text --explain --top 10
200
+
201
+ # Get JSON for tooling/AI
202
+ hotspots analyze src/ --format json
203
+
204
+ # Stream JSONL for pipeline processing
205
+ hotspots analyze src/ --format jsonl
206
+
207
+ # Compare with previous commit (delta mode)
208
+ hotspots analyze src/ --mode delta --policy
209
+ ```
210
+
211
+ **Large repos:** By default, hotspots uses hybrid touch mode — file-level git activity for all functions, with per-function precision only for actively-changed files (≥5 commits in 30 days). This keeps memory usage low and completes reliably on repos of any size.
212
+
213
+ ```bash
214
+ # Default: hybrid touch (fast, completes on any repo)
215
+ hotspots analyze . --mode snapshot --explain
216
+
217
+ # Full precision (slower cold start, more accurate activity scores)
218
+ hotspots analyze . --mode snapshot --explain --per-function-touches
219
+
220
+ # Fastest possible (file-level only, no per-function git log)
221
+ hotspots analyze . --mode snapshot --explain --no-per-function-touches
222
+ ```
223
+
224
+ ### 3. Act on Results
225
+
226
+ **Critical functions (LRS ≥ 9.0):** Refactor now. These are your top priority.
227
+ **High functions (LRS 6.0-9.0):** Watch closely. Refactor before they become critical.
228
+ **Moderate functions (LRS 3.0-6.0):** Keep an eye on them. Block complexity increases.
229
+ **Low functions (LRS < 3.0):** You're good. Don't overthink these.
230
+
231
+ ---
232
+
233
+ ## Supported Languages
234
+
235
+ - **TypeScript** - `.ts`, `.tsx`, `.mts`, `.cts`
236
+ - **JavaScript** - `.js`, `.jsx`, `.mjs`, `.cjs`
237
+ - **Go** - `.go`
238
+ - **Python** - `.py`
239
+ - **Rust** - `.rs`
240
+ - **Java** - `.java`
241
+ - **C** - `.c`, `.h`
242
+ - **C#** - `.cs`
243
+
244
+ Full language parity across all metrics and features. See [docs/reference/language-support.md](docs/reference/language-support.md) for details.
245
+
246
+ ---
247
+
248
+ ## How It Works
249
+
250
+ Hotspots computes a **Local Risk Score (LRS)** for each function based on:
251
+
252
+ 1. **Cyclomatic Complexity (CC)** - How many paths through the code?
253
+ 2. **Nesting Depth (ND)** - How deeply nested are your if/for/while statements?
254
+ 3. **Fan-Out (FO)** - How many other functions does this call?
255
+ 4. **Non-Structured Exits (NS)** - How many early returns, breaks, throws?
256
+
257
+ These metrics combine into a single **Local Risk Score (LRS)**. Higher LRS = higher risk of bugs, incidents, and developer confusion.
258
+
259
+ LRS is then combined with **Activity Risk** signals from git history and the call graph:
260
+
261
+ - **Churn** — lines changed in the last 30 days (volatile code)
262
+ - **Touch frequency** — commit count touching this function
263
+ - **Recency** — days since last change (branch-aware)
264
+ - **Fan-in** — how many other functions call this one (call graph)
265
+ - **Cyclic dependency** — SCC membership (tightly coupled code)
266
+ - **Neighbor churn** — lines changed in direct dependencies
267
+
268
+ The call graph engine resolves imports to detect fan-in, PageRank, betweenness centrality, and SCC membership. Functions that are both complex AND heavily depended upon by other changing code rise to the top.
269
+
270
+ ### Understanding Quadrants
271
+
272
+ Every function is placed in one of four quadrants based on its structural complexity and recent activity:
273
+
274
+ | Quadrant | Complexity | Recent Activity | What it means |
275
+ |---|---|---|---|
276
+ | **fire** | High | High | Live regression risk — complex AND actively changing right now |
277
+ | **debt** | High | Low | Structural debt — complex but not recently touched; high blast radius when next changed |
278
+ | **simple-active** | Low | High | Active but manageable — monitor, low structural risk |
279
+ | **simple-stable** | Low | Low | Lowest priority |
280
+
281
+ **Important:** The activity-weighted risk score (and `lrs`) is a decay function computed over git history — it never reaches zero even if a function hasn't been touched in months. A high risk score alone does **not** mean a function is actively changing. Always check `quadrant` and `touches_30d` to determine whether a function is a live regression risk (fire) or structural debt (debt).
282
+
283
+ - **fire**: Refactor now — every commit is landing on a complex function
284
+ - **debt**: Schedule proactively — refactor before the next development push into that area, not urgently
285
+ - **simple-active**: Watch closely but don't over-invest in refactoring
286
+ - **simple-stable**: Leave it alone unless metrics change
287
+
288
+ **Example:**
289
+
290
+ ```typescript
291
+ // LRS: 12.4 (Critical) - Complex AND frequently changed
292
+ function processPlanUpgrade(user, newPlan, paymentMethod) {
293
+ if (!user.isActive) return false;
294
+ if (user.plan === newPlan) return true;
295
+
296
+ if (paymentMethod.type === "card") {
297
+ if (paymentMethod.isExpired) {
298
+ try {
299
+ paymentMethod = renewPaymentMethod(user);
300
+ } catch (error) {
301
+ logError(error);
302
+ notifyUser(user, "payment_failed");
303
+ return false;
304
+ }
305
+ }
306
+
307
+ if (newPlan.price > user.plan.price) {
308
+ const prorated = calculateProration(user, newPlan);
309
+ if (!chargeCard(paymentMethod, prorated)) {
310
+ return false;
311
+ }
312
+ }
313
+ } else if (paymentMethod.type === "invoice") {
314
+ // Different logic for invoice customers...
315
+ }
316
+
317
+ updateDatabase(user, newPlan);
318
+ sendConfirmation(user);
319
+ return true;
320
+ }
321
+ ```
322
+
323
+ **This function:**
324
+ - CC: 15 (lots of branching)
325
+ - ND: 4 (deeply nested)
326
+ - FO: 8 (calls many functions)
327
+ - NS: 3 (multiple early returns)
328
+ - **LRS: 12.4** ← This is a hotspot
329
+
330
+ Refactor this before it causes a production incident.
331
+
332
+ ---
333
+
334
+ ## Features
335
+
336
+ ### 🚦 Policy Enforcement (CI/CD)
337
+
338
+ Block risky code before it merges:
339
+
340
+ - **Critical Introduction** - Fail CI if new functions exceed LRS 9.0
341
+ - **Excessive Regression** - Fail CI if LRS increases by ≥1.0
342
+ - **Watch/Attention Warnings** - Warn about functions approaching thresholds
343
+ - **Rapid Growth Detection** - Catch functions growing >50% in complexity
344
+
345
+ ```bash
346
+ # Run in CI with policy checks
347
+ hotspots analyze src/ --mode delta --policy
348
+ # Exit code 1 if policies fail → CI fails
349
+ ```
350
+
351
+ ### 🔍 Driver Labels & Explain Mode
352
+
353
+ Understand *why* a function is flagged and get concrete refactoring advice:
354
+
355
+ ```bash
356
+ hotspots analyze . --mode snapshot --format text --explain --top 10
357
+ ```
358
+
359
+ Each function shows its primary **driver** (`high_complexity`, `deep_nesting`,
360
+ `high_churn_low_cc`, `high_fanout_churning`, `high_fanin_complex`, `cyclic_dep`,
361
+ `composite`) plus an **Action** line with dimension-specific guidance:
362
+
363
+ ```
364
+ processPayment /src/billing.ts:89
365
+ LRS: 14.52 | Band: critical | Driver: high_complexity
366
+ CC: 15, ND: 4, FO: 8, NS: 3
367
+ Action: Reduce branching; extract sub-functions
368
+ ```
369
+
370
+ Use `--level file` or `--level module` for higher-level aggregated views.
371
+
372
+ ### 📊 Multiple Output Formats
373
+
374
+ **Terminal (human-readable):**
375
+ ```
376
+ Critical (LRS ≥ 9.0):
377
+ processPlanUpgrade src/api/billing.ts:142 LRS 12.4 CC 15 ND 4 FO 8 NS 3
378
+ ```
379
+
380
+ **JSON (machine-readable):**
381
+ ```json
382
+ {
383
+ "schema_version": 2,
384
+ "functions": [
385
+ {
386
+ "function_id": "src/api/billing.ts::processPlanUpgrade",
387
+ "file": "src/api/billing.ts",
388
+ "line": 142,
389
+ "lrs": 12.4,
390
+ "band": "critical",
391
+ "driver": "high_complexity",
392
+ "metrics": { "cc": 15, "nd": 4, "fo": 8, "ns": 3 }
393
+ }
394
+ ]
395
+ }
396
+ ```
397
+
398
+ **JSONL (streaming per-function):**
399
+ ```bash
400
+ hotspots analyze src/ --mode snapshot --format jsonl | grep '"band":"critical"'
401
+ ```
402
+ One JSON object per line — ideal for large repos and shell pipeline processing.
403
+
404
+ **HTML (interactive reports):**
405
+ - Sortable, filterable tables
406
+ - Risk band visualization
407
+ - Shareable with stakeholders
408
+ - Upload as CI artifacts
409
+
410
+ **SARIF (Static Analysis Results Interchange Format):**
411
+ ```bash
412
+ hotspots analyze src/ --format sarif
413
+ ```
414
+ Compatible with GitHub Code Scanning and any SARIF-aware tool.
415
+
416
+ ### 🔇 Suppression Comments
417
+
418
+ Have complex code you can't refactor yet? Suppress warnings with a reason:
419
+
420
+ ```typescript
421
+ // hotspots-ignore: legacy payment processor, rewrite scheduled Q2 2026
422
+ function legacyBillingLogic() {
423
+ // Complex but can't touch it yet
424
+ }
425
+ ```
426
+
427
+ Functions with suppressions:
428
+ - ✅ Still appear in reports (visibility)
429
+ - ❌ Don't fail CI policies (pragmatism)
430
+ - 📝 Require a reason (accountability)
431
+
432
+ ### ⚙️ Configuration
433
+
434
+ Customize thresholds, weights, and file patterns:
435
+
436
+ ```json
437
+ {
438
+ "thresholds": {
439
+ "moderate": 3.0,
440
+ "high": 6.0,
441
+ "critical": 9.0
442
+ },
443
+ "include": ["src/**/*.ts"],
444
+ "exclude": ["**/*.test.ts", "**/__mocks__/**"]
445
+ }
446
+ ```
447
+
448
+ See [docs/guide/configuration.md](docs/guide/configuration.md) for all options.
449
+
450
+ ### 🤖 AI Integration
451
+
452
+ **Claude Code:**
453
+ ```bash
454
+ # Analyze changes and feed to Claude Code
455
+ hotspots analyze . --mode delta --format json
456
+
457
+ # Get agent-optimized output
458
+ hotspots analyze . --mode delta --all-functions --format json
459
+ ```
460
+
461
+ See [docs/integrations/ai-agents.md](docs/integrations/ai-agents.md) for complete guide.
462
+
463
+ **Cursor/GitHub Copilot:**
464
+ ```bash
465
+ hotspots analyze src/ --format json | jq '.functions[] | select(.lrs > 9)'
466
+ # Feed results to your AI coding assistant
467
+ ```
468
+
469
+ ### 📈 Git History Analysis
470
+
471
+ Track complexity over time:
472
+
473
+ ```bash
474
+ # Create baseline snapshot
475
+ hotspots analyze src/ --mode snapshot
476
+
477
+ # Compare current code vs baseline
478
+ hotspots analyze src/ --mode delta
479
+
480
+ # Compare any two git refs (branches, tags, SHAs)
481
+ hotspots diff main HEAD
482
+ hotspots diff v1.0.0 v2.0.0 --format json
483
+ hotspots diff main HEAD --top 10 --policy
484
+
485
+ # See complexity trends
486
+ hotspots trends .
487
+
488
+ # Train a repo-specific ranker from fix-commit history
489
+ hotspots train . --blame
490
+
491
+ # Check whether the trained model is actually useful (P@K evaluation)
492
+ hotspots train . --eval
493
+
494
+ # Prune unreachable snapshots (after force-push or branch deletion)
495
+ hotspots prune --unreachable --older-than 30
496
+
497
+ # Compact snapshot history
498
+ hotspots compact --level 0
499
+ ```
500
+
501
+ Delta mode and `hotspots diff` show:
502
+ - Functions that got more complex
503
+ - Functions that were simplified
504
+ - New high-complexity functions introduced
505
+ - Overall repository complexity trend
506
+
507
+ `hotspots diff` requires snapshots to exist for both refs (run `hotspots analyze --mode snapshot` at each ref first). Use `--auto-analyze` to generate missing snapshots automatically via git worktrees.
508
+
509
+ ### ⚙️ Configuration Commands
510
+
511
+ ```bash
512
+ # Show resolved configuration (weights, thresholds, filters)
513
+ hotspots config show
514
+
515
+ # Validate configuration file without running analysis
516
+ hotspots config validate
517
+ ```
518
+
519
+ ### 🪝 Hook Templates
520
+
521
+ ```bash
522
+ # Print pre-commit and CI hook templates to stdout
523
+ hotspots init --hooks
524
+ ```
525
+
526
+ Outputs ready-to-use shell hooks and pre-commit framework config for enforcing policies locally.
527
+
528
+ ---
529
+
530
+ ## Documentation
531
+
532
+ - 🚀 [Quick Start](docs/getting-started/quick-start.md) - Get started in 5 minutes
533
+ - 📖 [CLI Reference](docs/reference/cli.md) - All commands and options
534
+ - 📊 [Scoring Methodology](docs/reference/scoring.md) - How scores are calculated and ranked
535
+ - 🎯 [CI Integration](docs/guide/ci-integration.md) - GitHub Actions, GitLab CI
536
+ - 🤖 [AI Integration](docs/integrations/ai-agents.md) - Claude, Cursor, Copilot
537
+ - 🏗️ [Architecture](docs/architecture/overview.md) - How it works
538
+ - 🤝 [Contributing](docs/contributing/index.md) - Add languages, fix bugs, improve docs
539
+
540
+ **Full documentation:** [docs/index.md](docs/index.md)
541
+
542
+ ---
543
+
544
+ ## Why Hotspots?
545
+
546
+ ### vs ESLint Complexity Rules
547
+
548
+ **ESLint:** Checks individual metrics (CC > 10). No context about change frequency or real-world risk.
549
+ **Hotspots:** Combines multiple metrics into LRS. Integrates git history. Prioritizes based on actual risk.
550
+
551
+ ### vs SonarQube / CodeClimate
552
+
553
+ **SonarQube:** Enterprise platform, complex setup, slow scans, requires server infrastructure.
554
+ **Hotspots:** Single binary, instant analysis, zero config, works offline, git history built-in.
555
+
556
+ ### vs Code Reviews
557
+
558
+ **Reviews:** Catch complexity subjectively. Miss gradual regressions. Don't track trends.
559
+ **Hotspots:** Objective metrics. Catches every change. Shows trends over time. Enforces policies automatically.
560
+
561
+ **Use both:** Hotspots + code reviews = comprehensive quality control.
562
+
563
+ ---
564
+
565
+ ## Real-World Use Cases
566
+
567
+ ### 🔥 Incident Prevention
568
+ "We had 3 production incidents in Q1. All originated from the same 5 functions. Hotspots flagged all 5 as critical. We refactored them in Q2. Zero incidents since."
569
+
570
+ ### 🚀 Faster Onboarding
571
+ "New engineers use Hotspots to identify risky code before touching it. 'This function is LRS 11.2, be careful' = instant context."
572
+
573
+ ### 🎯 Refactoring Sprints
574
+ "We allocate 1 sprint per quarter to reduce our top 10 hotspots. Dropped average LRS from 6.2 to 4.1 over 6 months."
575
+
576
+ ### 🤖 AI-Guided Refactoring
577
+ "Feed hotspots JSON to Claude. It suggests refactorings for critical functions. Accept, commit, verify LRS dropped. Repeat."
578
+
579
+ ### ⚖️ Technical Debt Metrics
580
+ "Execs ask 'How's our tech debt?' I show them: 23 critical functions (down from 31), average LRS 4.8 (down from 5.3). Clear progress."
581
+
582
+ ---
583
+
584
+ ## Installation
585
+
586
+ ### Quick Install
587
+
588
+ **cargo (Rust toolchain):**
589
+ ```bash
590
+ cargo install hotspots-cli
591
+ ```
592
+
593
+ **macOS / Linux:**
594
+ ```bash
595
+ curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh
596
+ ```
597
+
598
+ Installs to `~/.local/bin/hotspots`. Verify with `hotspots --version`.
599
+
600
+ **Install a specific version:**
601
+ ```bash
602
+ HOTSPOTS_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh
603
+ ```
604
+
605
+ ### Build from Source
606
+
607
+ ```bash
608
+ git clone https://github.com/Stephen-Collins-tech/hotspots.git
609
+ cd hotspots
610
+ cargo build --release
611
+ mkdir -p ~/.local/bin
612
+ cp target/release/hotspots ~/.local/bin/
613
+ ```
614
+
615
+ **Requirements:** Rust 1.75 or later
616
+
617
+ ---
618
+
619
+ ## Contributing
620
+
621
+ We welcome contributions!
622
+
623
+ - 🐛 [Report bugs](https://github.com/Stephen-Collins-tech/hotspots/issues)
624
+ - 💡 [Request features](https://github.com/Stephen-Collins-tech/hotspots/discussions)
625
+ - 🔧 [Submit PRs](docs/contributing/index.md)
626
+ - 📖 [Improve docs](docs/contributing/index.md)
627
+
628
+ **Want to add a language?** See [docs/contributing/adding-languages.md](docs/contributing/adding-languages.md) - we have a proven pattern for adding TypeScript, JavaScript, Go, Python, Rust, and Java.
629
+
630
+ ---
631
+
632
+ ## License
633
+
634
+ MIT License - see [LICENSE-MIT](LICENSE-MIT) for details.
635
+
636
+ ---
637
+
638
+ ## Next Steps
639
+
640
+ 1. ⚡ [Install Hotspots](#installation) (2 minutes)
641
+ 2. 🔍 Run your first analysis: `hotspots analyze src/`
642
+ 3. 🎯 Identify your top 10 hotspots
643
+ 4. 🛠️ Refactor the worst offender
644
+ 5. 📊 Add to CI/CD: `hotspots analyze src/ --mode delta --policy`
645
+ 6. 🧠 Train a repo-specific ranker: `hotspots train . --blame`
646
+ 6. 🤖 Integrate with AI: [AI Integration Guide](docs/integrations/ai-agents.md)
647
+
648
+ **Questions?** Open a [GitHub Discussion](https://github.com/Stephen-Collins-tech/hotspots/discussions).
649
+
650
+ **Found a bug?** Open an [issue](https://github.com/Stephen-Collins-tech/hotspots/issues).
651
+
652
+ ---
653
+
654
+ **Stop refactoring guesswork. Start with Hotspots.**
655
+
@@ -0,0 +1,6 @@
1
+ hotspots_cli-1.25.1.data/scripts/hotspots.exe,sha256=kV7A52XZvzMF9W7REzkiA43FnPe3PhZQ1POwhtYXawQ,19574784
2
+ hotspots_cli-1.25.1.dist-info/METADATA,sha256=HPEK2BFUXvXapdIr0mT9s2Br_7gh-ol5Gr9IfR535Us,22560
3
+ hotspots_cli-1.25.1.dist-info/WHEEL,sha256=T1DkkvVlw1bn9taKYXZyic2iz5lp4CFExsOlxcRDXDI,94
4
+ hotspots_cli-1.25.1.dist-info/licenses/LICENSE-MIT,sha256=4R-_2wBoLyW7L4k2VoYA3fd9_dtHBBMvXMTIJvFoTrc,1093
5
+ hotspots_cli-1.25.1.dist-info/sboms/hotspots-cli.cyclonedx.json,sha256=rbKYEAOeeJuEdNPkClm0BXS7CzhwlSNI7c8OyCDCfpw,209460
6
+ hotspots_cli-1.25.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.14.0)
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-win_amd64
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Stephen Collins
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.