Stephen-Collins-tech/hotspots

# Hotspots [](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/ci.yml) [](https://github.com/Stephen-Collins-tech/hotspots/actions/workflows/security.yml) **网站：** https://hotspots.dev  |  **文档：** https://docs.hotspots.dev  |  **安装：** `curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh` **找出真正导致问题的代码。** 你的代码库有成千上万个函数。有些虽然混乱但从不报错。另一些则既复杂又频繁变更——这些就是你的 **热点**，即那 20% 却导致了 80% bug、故障和性能瓶颈的代码。 停止重构无关紧要的代码。专注于当前正在对你造成伤害的部分。 ## 问题所在 你知道你的代码库有技术债务。但你到底应该重构哪些代码？ ❌ **凭直觉重构** → 在很少出问题的代码上浪费数周时间 ❌ **重构所有内容** → 不可能，而且你会重写不需要改动的稳定代码 ❌ **完全不重构** → 技术债务不断累积，直到“修复这个 bug”变成了“重写所有内容” **真正的问题在于：** 哪些函数既复杂又经常被修改？ 正是这些函数导致了生产环境故障、拖慢了功能开发，并耗尽了团队的精力。 ## 解决方案 Hotspots 分析你的代码库和 git 历史，以找出符合以下条件的函数： 1. **复杂** - 高圈复杂度、深层嵌套、大量分支 2. **易变** - 在最近的提交中频繁更改 3. **高风险** - 两者兼有的危险组合 不再猜测该重构什么，你会得到一个优先级列表： ``` hotspots analyze src/ # Output: 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 applySchema src/db/migrations.ts:203 LRS 8.1 CC 10 ND 2 FO 5 NS 2 ``` 现在你确切地知道该把精力集中在哪里。 ## 你将获得什么 ### ✅ 重构真正重要的部分 停止在那些“看起来很乱”但从未导致问题的代码上浪费时间。专注于那 20% 却导致了 80% 故障的函数。 ### ✅ 在 CI 中阻断复杂性回退 在 risky 变更合并前将其捕获： ``` # 在 CI 中运行并执行 policy 检查 hotspots analyze src/ --mode delta --policy # Exit code 1 如果 policies 失败 → CI 失败 ``` 如果有人引入了高风险代码，你的 CI 将会失败。无需人工审查。 ### ✅ 自信地发布，无需提心吊胆 在触碰文件之前就知道哪些是“地雷”。查看随时间变化的复杂性趋势。在重构、重写或维持现状之间做出明智的决定。 ### ✅ 获得 AI 辅助的重构 Hotspots 与 Claude Code、Cursor 和 GitHub Copilot 集成。将你的 AI 指向最热门的函数，并获得能切实改善代码库的重构建议。 ``` # 分析项目中的变更 hotspots analyze . --mode delta --format json # 获取 agent 优化后的 output (quadrant buckets + action 文本) hotspots analyze . --mode delta --all-functions --format json ``` ## 快速开始 ### 1. 安装 **macOS / Linux:** ``` curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh ``` 安装到 `~/.local/bin/hotspots`。使用 `hotspots --version` 进行验证。 **GitHub Action:** 即将推出。目前请在你的 workflows 中直接使用 CLI。 ### 2. 分析你的代码 ``` # 查找您的 hotspots hotspots analyze src/ # 仅筛选 critical 函数 hotspots analyze src/ --min-lrs 9.0 # 获取带有 driver 标签的逐函数解释 hotspots analyze . --mode snapshot --format text --explain --top 10 # 获取用于 tooling/AI 的 JSON hotspots analyze src/ --format json # Stream JSONL 用于 pipeline 处理 hotspots analyze src/ --format jsonl # 与 previous commit 进行比较 (delta mode) hotspots analyze src/ --mode delta --policy ``` ### 3. 根据结果采取行动 **关键函数 (LRS ≥ 9.0):** 立即重构。这些是你的最高优先级。 **高危函数 (LRS 6.0-9.0):** 密切关注。在它们变得至关重要之前进行重构。 **中等风险函数 (LRS 3.0-6.0):** 留意它们。阻断复杂性的增长。 **低风险函数 (LRS < 3.0):** 你做得很好。不要在这些上面过度思考。 ## 支持的语言 - **TypeScript** - `.ts`, `.tsx`, `.mts`, `.cts` - **JavaScript** - `.js`, `.jsx`, `.mjs`, `.cjs` - **Go** - `.go` - **Python** - `.py` - **Rust** - `.rs` - **Java** - `.java` 所有指标和功能均完全支持上述语言。详情请参阅 [docs/reference/language-support.md](docs/reference/language-support.md)。 ## 工作原理 Hotspots 根据以下因素为每个函数计算一个 **局部风险评分 (LRS)**： 1. **圈复杂度 (CC)** - 代码中有多少条路径？ 2. **嵌套深度 (ND)** - 你的 if/for/while 语句嵌套得有多深？ 3. **扇出 (FO)** - 这个函数调用了多少其他函数？ 4. **非结构化出口 (NS)** - 有多少早期返回、中断、抛出？ 这些指标组合成一个单一的 **局部风险评分 (LRS)**。LRS 越高 = 出现 bug、故障和开发人员困惑的风险越高。 然后，LRS 会与来自 git 历史和调用图的 **活跃度风险** 信号相结合： - **变动率** — 过去 30 天内更改的行数（易变代码） - **触碰频率** — 触及此函数的提交次数 - **最近性** — 自上次更改以来的天数（区分分支） - **扇入** — 有多少其他函数调用此函数（调用图） - **循环依赖** — SCC 成员身份（紧密耦合的代码） - **邻近变动率** — 直接依赖项中更改的行数 调用图引擎解析导入以检测扇入、PageRank、介数中心性和 SCC 成员身份。那些既复杂又被其他变动代码严重依赖的函数会浮现在顶部。 **示例：** ``` // LRS: 12.4 (Critical) - Complex AND frequently changed function processPlanUpgrade(user, newPlan, paymentMethod) { if (!user.isActive) return false; if (user.plan === newPlan) return true; if (paymentMethod.type === "card") { if (paymentMethod.isExpired) { try { paymentMethod = renewPaymentMethod(user); } catch (error) { logError(error); notifyUser(user, "payment_failed"); return false; } } if (newPlan.price > user.plan.price) { const prorated = calculateProration(user, newPlan); if (!chargeCard(paymentMethod, prorated)) { return false; } } } else if (paymentMethod.type === "invoice") { // Different logic for invoice customers... } updateDatabase(user, newPlan); sendConfirmation(user); return true; } ``` **此函数：** - CC: 15（大量分支） - ND: 4（深层嵌套） - FO: 8（调用许多函数） - NS: 3（多个早期返回） - **LRS: 12.4** ← 这是一个热点 在它导致生产事故之前重构它。 ## 功能特性 ### 🚦 策略执行 (CI/CD) 在 risky 代码合并前将其阻断： - **关键引入** - 如果新函数的 LRS 超过 9.0，则 CI 失败 - **过度回退** - 如果 LRS 增加 ≥1.0，则 CI 失败 - **观察/注意警告** - 警告接近阈值的函数 - **快速增长检测** - 捕获复杂性增长 >50% 的函数 ``` # 在 CI 中运行并执行 policy 检查 hotspots analyze src/ --mode delta --policy # Exit code 1 如果 policies 失败 → CI 失败 ``` ### 🔍 驱动因素标签与解释模式 了解*为什么*函数被标记并获得具体的重构建议： ``` hotspots analyze . --mode snapshot --format text --explain --top 10 ``` 每个函数显示其主要**驱动因素**（`high_complexity`, `deep_nesting`, `high_churn_low_cc`, `high_fanout_churning`, `high_fanin_complex`, `cyclic_dep`, `composite`）以及一条针对具体维度的**行动**指南： ``` processPayment /src/billing.ts:89 LRS: 14.52 | Band: critical | Driver: high_complexity CC: 15, ND: 4, FO: 8, NS: 3 Action: Reduce branching; extract sub-functions ``` 使用 `--level file` 或 `--level module` 获取更高级别的聚合视图。 ### 📊 多种输出格式 **终端（人类可读）：** ``` Critical (LRS ≥ 9.0): processPlanUpgrade src/api/billing.ts:142 LRS 12.4 CC 15 ND 4 FO 8 NS 3 ``` **JSON（机器可读）：** ``` { "schema_version": 2, "functions": [ { "function_id": "src/api/billing.ts::processPlanUpgrade", "file": "src/api/billing.ts", "line": 142, "lrs": 12.4, "band": "critical", "driver": "high_complexity", "metrics": { "cc": 15, "nd": 4, "fo": 8, "ns": 3 } } ] } ``` **JSONL（按函数流式传输）：** ``` hotspots analyze src/ --mode snapshot --format jsonl | grep '"band":"critical"' ``` 每行一个 JSON 对象 —— 适用于大型代码仓库和 shell 管道处理。 **HTML（交互式报告）：** - 可排序、可过滤的表格 - 风险带可视化 - 可与利益相关者共享 - 作为 CI 构件上传 ### 🔇 抑制注释 有无法立即重构的复杂代码？带上原因抑制警告： ``` // hotspots-ignore: legacy payment processor, rewrite scheduled Q2 2026 function legacyBillingLogic() { // Complex but can't touch it yet } ``` 带有抑制的函数： - ✅ 仍出现在报告中（可见性） - ❌ 不会导致 CI 策略失败（务实性） - 📝 需要填写原因（问责制） ### ⚙️ 配置 自定义阈值、权重和文件模式： ``` { "thresholds": { "moderate": 3.0, "high": 6.0, "critical": 9.0 }, "include": ["src/**/*.ts"], "exclude": ["**/*.test.ts", "**/__mocks__/**"] } ``` 有关所有选项，请参阅 [docs/guide/configuration.md](docs/guide/configuration.md)。 ### 🤖 AI 集成 **Claude Code:** ``` # 分析变更并 feed 给 Claude Code hotspots analyze . --mode delta --format json # 获取 agent 优化后的 output hotspots analyze . --mode delta --all-functions --format json ``` 完整指南请参阅 [docs/integrations/ai-agents.md](docs/integrations/ai-agents.md)。 **Cursor/GitHub Copilot:** ``` hotspots analyze src/ --format json | jq '.functions[] | select(.lrs > 9)' # 将结果 feed 给您的 AI 编程助手 ``` ### 📈 Git 历史分析 随时间追踪复杂性： ``` # 创建 baseline 快照 hotspots analyze src/ --mode snapshot # 比较当前代码与 baseline hotspots analyze src/ --mode delta # 查看复杂度趋势 hotspots trends . # 修剪不可达快照 (在 force-push 或分支删除后) hotspots prune --unreachable --older-than 30 # 压缩快照历史记录 hotspots compact --level 0 ``` Delta 模式显示： - 变得更复杂的函数 - 被简化的函数 - 引入的新的高复杂性函数 - 整体代码仓库复杂性趋势 ### ⚙️ 配置命令 ``` # 显示已解析的 configuration (weights, thresholds, filters) hotspots config show # 验证配置文件而不运行分析 hotspots config validate ``` ## 文档 - 🚀 [快速开始](docs/getting-started/quick-start.md) - 5 分钟上手 - 📖 [CLI 参考](docs/reference/cli.md) - 所有命令和选项 - 🎯 GitHub Action - CI/CD 集成 *（即将推出）* - 🤖 [AI 集成](docs/integrations/ai-agents.md) - Claude, Cursor, Copilot - 🏗️ [架构](docs/architecture/overview.md) - 工作原理 - 🤝 [贡献指南](docs/contributing/index.md) - 添加语言、修复 bug、改进文档 **完整文档：** [docs/index.md](docs/index.md) ## 为什么选择 Hotspots？ ### 对比 ESLint 复杂度规则 **ESLint:** 检查单个指标（CC > 10）。没有关于更改频率或现实世界风险的上下文。 **Hotspots:** 将多个指标组合成 LRS。集成 git 历史。根据实际风险确定优先级。 ### 对比 SonarQube / CodeClimate **SonarQube:** 企业级平台，设置复杂，扫描缓慢，需要服务器基础设施。 **Hotspots:** 单一二进制文件，即时分析，零配置，离线工作，内置 git 历史。 ### 对比代码审查 **审查:** 主观地捕获复杂性。错过逐渐的回退。不追踪趋势。 **Hotspots:** 客观指标。捕获每一个变化。显示随时间变化的趋势。自动执行策略。 **两者并用:** Hotspots + 代码审查 = 全面的质量控制。 ## 真实用例 ### 🔥 事故预防 “我们在第一季度发生了 3 起生产事故。全部源于相同的 5 个函数。Hotspots 将这 5 个都标记为关键。我们在第二季度重构了它们。此后零事故。” ### 🚀 更快的入职 “新工程师在触碰代码前使用 Hotspots 识别风险代码。‘这个函数是 LRS 11.2，要小心’ = 瞬间了解上下文。” ### 🎯 重构冲刺 “我们每个季度分配 1 个冲刺来减少前 10 个热点。6 个月内平均 LRS 从 6.2 降至 4.1。” ### 🤖 AI 引导的重构 “将 hotspots JSON 提供给 Claude。它为关键函数建议重构方案。接受、提交、验证 LRS 下降。重复。” ### ⚖️ 技术债务指标 “高管问‘我们的技术债务怎么样？’我向他们展示：23 个关键函数（从 31 个下降），平均 LRS 4.8（从 5.3 下降）。清晰的进展。” ## 安装 ### 快速安装 **macOS / Linux:** ``` curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh ``` 安装到 `~/.local/bin/hotspots`。使用 `hotspots --version` 进行验证。 **安装特定版本：** ``` HOTSPOTS_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/Stephen-Collins-tech/hotspots/main/install.sh | sh ``` ### 从源代码构建 ``` git clone https://github.com/Stephen-Collins-tech/hotspots.git cd hotspots cargo build --release mkdir -p ~/.local/bin cp target/release/hotspots ~/.local/bin/ ``` **要求：** Rust 1.75 或更高版本 ## 贡献 我们欢迎贡献！ - 🐛 [报告 bug](https://github.com/Stephen-Collins-tech/hotspots/issues) - 💡 [请求功能](https://github.com/Stephen-Collins-tech/hotspots/discussions) - 🔧 [提交 PR](docs/contributing/index.md) - 📖 [改进文档](docs/contributing/index.md) **想添加一种语言？** 请参阅 [docs/contributing/adding-languages.md](docs/contributing/adding-languages.md) - 我们有一套经过验证的模式，用于添加 TypeScript、JavaScript、Go、Python、Rust 和 Java。 ## 许可证 MIT 许可证 - 详情请参阅 [LICENSE-MIT](LICENSE-MIT)。 ## 下一步 1. ⚡ [安装 Hotspots](#installation)（2 分钟） 2. 🔍 运行你的第一次分析：`hotspots analyze src/` 3. 🎯 识别你的前 10 个热点 4. 🛠️ 重构最糟糕的那个 5. 📊 添加到 CI/CD：`hotspots analyze src/ --mode delta --policy`（GitHub Action 即将推出） 6. 🤖 与 AI 集成：[AI 集成指南](docs/integrations/ai-agents.md) **有问题？** 开启一个 [GitHub 讨论](https://github.com/Stephen-Collins-tech/hotspots/discussions)。 **发现了 bug？** 提交一个 [issue](https://github.com/Stephen-Collins-tech/hotspots/issues)。 **停止猜测如何重构。从 Hotspots 开始。**

标签：Git分析, JS文件枚举, 云安全监控, 代码复杂度, 代码安全, 代码重构, 可视化界面, 圈复杂度, 技术债, 数据可视化, 日志审计, 漏洞枚举, 热点分析, 生产力工具, 软件维护, 逆向工具, 通知系统, 静态分析, 风险分析