endrilickollari/debtdrone-cli
GitHub: endrilickollari/debtdrone-cli
一款基于 AST 解析的技术债务分析工具，提供交互式 TUI 与无头 CLI 以在开发与 CI/CD 中识别并治理复杂度与安全债务。
Stars: 12 | Forks: 0
# 🚁 DebtDrone CLI
**DebtDrone CLI** 是一个闪电般快速、高度可配置的技术债务分析器。
采用 **六边形架构**，DebtDrone 以单个静态链接的 Go 二进制文件分发，提供两个截然不同的用途：
1. **交互式 TUI**：一个美观、响应迅速的终端界面，供开发者在本地探索代码复杂度。
2. **无头 CLI**：一个健壮、可直接用于 CI/CD 流程的可执行文件，支持严格的质量门禁和 JSON 输出。
## ✨ 功能
### 🎨 交互式 TUI（面向人类）
基于 [Bubble Tea](https://github.com/charmbracelet/bubbletea) 和 [Lipgloss](https://github.com/charmbracelet/lipgloss) 构建。
* **主-详情浏览器**：无需文本截断，轻松浏览数百个问题。
* **历史追踪**：查看过往扫描记录，跟踪债务随时间是减少还是增长。
* **内联配置**：直接在终端中修改阈值和规则，无需触碰 Vim。
* **无缝更新**：内置自动更新器，支持变更日志弹窗（`/update`）。
### 🤖 无头 CLI（面向机器）
基于 [Cobra](https://github.com/spf13/cobra) 构建。
* **CI/CD 质量门禁**：使用 `--fail-on` 在引入新的严重或高级债务时自动失败构建流水线。
* **结构化输出**：导出结果为标准文本表格或机器可读的 JSON（`--format=json`）。
* **确定性执行**：绕过所有交互式提示，确保流水线不会挂起。
* **配置即代码**：提交 `.debtdrone.yaml` 到仓库，确保本地与流水线扫描使用完全相同的规则集。
## 🚀 安装
**通过 Homebrew（推荐）：**
```
brew install endrilickollari/tap/debtdrone
```
**通过 Shell 脚本（Mac/Linux）：**
```
curl -sL https://raw.githubusercontent.com/endrilickollari/debtdrone-cli/main/installation_scripts/install.sh | bash
```
**通过 PowerShell（Windows）：**
```
iwr -useb https://raw.githubusercontent.com/endrilickollari/debtdrone-cli/main/installation_scripts/install.ps1 | iex
```
**通过 Go 安装：**
```
go install github.com/endrilickollari/debtdrone-cli/cmd/debtdrone@latest
```
**通过预编译二进制文件：**
请查看 [发布页面](https://github.com/endrilickollari/debtdrone-cli/releases) 获取适用于 macOS、Linux 和 Windows 的静态二进制文件。
## 🎮 用法：交互式 TUI
要启动交互式仪表板，只需不带任何参数运行该工具：
```
debtdrone
```
### TUI 命令与导航
进入 TUI 后，你可以使用标准的 Vim 绑定（`j`/`k`）进行导航。使用命令栏在不同模块间跳转：
* `/scan` - 在当前目录启动新的技术债务扫描。
* `/history` - 查看过往扫描及其严重性分布。
* `/config` - 打开设置应用以调整全局或仓库特定的阈值。
* `/update` - 检查新版本并就地安装。
## ⚙️ 用法：无头 CLI（CI/CD）
无头 CLI 专为自动化、脚本编写和 CI/CD 工作流设计。
### 执行扫描
运行静默扫描并输出简洁的文本表格：
```
debtdrone scan ./my-project
```
以 JSON 格式输出结果供流水线解析：
```
debtdrone scan ./my-project --format=json
```
### 质量门禁（失败构建）
通过设置严重性阈值来阻止错误代码合并。如果扫描器发现任何达到或超过此级别的问题，它将返回非零退出码（`os.Exit(1)`）。
```
# 如果发现 Critical 或 High 债务，则管道失败
debtdrone scan ./my-project --fail-on=high
```
### 配置管理
在仓库中初始化默认的 `.debtdrone.yaml`：
```
debtdrone init
```
通过 CLI 查看或编辑设置：
```
debtdrone config list
debtdrone config set thresholds.max_complexity 15
```
## 🛠 GitHub Actions 集成
DebtDrone 专为集成到你的 CI/CD 流水线而设计。以下是在 GitHub Actions 中实现 DebtDrone 质量门禁的复制粘贴示例：
```
name: Code Quality Gate
on: [push, pull_request]
jobs:
debtdrone-scan:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Install DebtDrone
run: |
curl -sL https://github.com/endrilickollari/debtdrone-cli/releases/latest/download/debtdrone_Linux_x86_64.tar.gz | tar xz
sudo mv debtdrone /usr/local/bin/
- name: Run DebtDrone Quality Gate
# Fails the PR if high or critical technical debt is introduced
run: debtdrone scan ./ --format=text --fail-on=high
```
## 🏗 架构
DebtDrone 采用严格的 **端口与适配器（六边形）架构**，确保核心分析引擎与展示层保持解耦。
* **`internal/analysis/`**：核心业务逻辑。纯粹的 Go、无 UI 感知、高度并发的扫描引擎。
* **`cmd/debtdrone/`**：Cobra 路由层。处理无头执行、标志解析和操作系统退出码。
* **`internal/tui/`**：展示层。实现 Bubble Tea 嵌套路由模式。每个主要屏幕（AppModel、ConfigModel、ScanModel）均完全封装，并通过事件驱动的 `tea.Msg` 通信。
### 测试
我们维护两套独立的测试套件：
* **无头测试**：`go test ./cmd/...` 测试 Cobra 缓冲区、结构化 JSON 输出和操作系统退出码。
* **TUI 测试**：`go test ./internal/tui/...` 使用纯函数式状态注入测试 Bubble Tea 状态机。（注意：我们的测试辅助工具强制应用 TrueColor 配置文件，以确保在无头 CI 环境中 Lipgloss 字符串确定性渲染。）
## 📄 许可证
DebtDrone CLI 在 **MIT 许可证** 下分发。自由使用、修改和分发。
请参阅 [LICENSE](LICENSE) 获取完整细节。
## ☕ 支持该项目
如果 DebtDrone 帮助你修复了关键问题或节省了时间，请考虑请我喝杯咖啡！
标签：API安全, AST解析, Bubble Tea, CLI, Cobra, EVTX分析, Go语言, Hexagonal Architecture, JSON输出, Lipgloss, TUI, WiFi技术, 二进制发布, 云安全监控, 代码分析工具, 代码复杂度, 安全扫描, 工程效率, 开源工具, 技术债务, 日志审计, 时序注入, 确定性执行, 程序破解, 自动更新, 质量门禁, 静态分析