iepathos/debtmap

# 债务图 [](https://crates.io/crates/debtmap) [](https://crates.io/crates/debtmap) [](https://github.com/iepathos/debtmap/actions/workflows/ci.yml) [](LICENSE) Debtmap 分析您的代码库并按风险对技术债务进行排序。您可以直接在终端、TUI 或仪表板中使用它，以了解在哪里集中重构努力，或者当适合您的流程时，将结果传递给 AI 助手。 ## 为什么选择 Debtmap？ 大型代码库会积累复杂性。您知道存在债务，但您从哪里开始呢？ Debtmap 将静态分析与 git 历史结合，通过多个信号对技术债务进行评分： | 信号 | 衡量内容 | 重要性 | |------|-----------|--------| | **复杂性** | 节点、认知、嵌套深度 | 代码理解难度 | | **覆盖率** | 每个函数的测试覆盖率百分比 | 变更风险 | | **Git 历史** | 变更频率、错误修复率、作者数量 | 哪些代码经常出错 | | **耦合** | 依赖关系、调用图深度 | 变更如何影响代码库 | | **纯度** | 副作用、I/O 操作 | 代码的可测试性和可预测性 | | **熵** | 代码库内模式一致性 | 减少有意复杂性的误报 | 这些信号组合成一个统一的优先级分数，并带有严重性等级，包括关键、高、中、低风险。结果是：一个按优先级排序的待修复列表，以及理解原因所需的上下文，无论您是自己审查还是将其交给自动化。 ## 快速入门 ``` # 安装 cargo install debtmap # 交互式探索问题（默认） debtmap analyze . # JSON 用于程序访问 debtmap analyze . --format json --top 10 --output debt.json # 可选：通过管道传递给 LLM 以自动修复 debtmap analyze . --format markdown --top 1 | claude "Fix this" ``` ## 支持的语言 - **Rust** — 使用 syn 进行完整的 AST 分析，包括宏扩展和特质检测 - **Python** — 基于 Tree-sitter 的分析，包括函数、类、装饰器、生成器和 Python 特定的复杂性模式 - **JavaScript** — 使用 Tree-sitter 解析 ES 模块、React/JSX 模式和异步工作流程分析 - **TypeScript** — 使用 Tree-sitter 解析，支持 TS/TSX，具有类型感知模式和现代前端/服务器语法 ``` # 分析特定语言 debtmap analyze . --languages rust,python,javascript,typescript # 所有支持的语言默认启用 debtmap analyze . ``` ## 交互式 TUI 运行 `debtmap analyze .` 以交互式地探索结果：     功能： - 按严重性浏览债务项 - 深入分数分解以了解代码为何排名较高 - 查看每个函数的 git 历史、依赖关系和测试覆盖率 - 在需要时将上下文复制到剪贴板以供 AI 助手使用 - 跳转到编辑器中的代码 ## LLM 集成 Debtmap 可以独立使用，并且当您想将发现传递给 AI 编码助手时，`--format markdown` 输出是可用的。它提供： - **上下文建议** - LLM 应读取的特定文件范围以了解问题 - **结构化元数据** - 评分因素、依赖关系上下文、纯度信号、覆盖率、熵以及可选的 git 历史风险，以便 LLM 可以推理优先级 - **最小化令牌** - 紧凑的格式，可以将更多上下文放入 LLM 的窗口 - **确定性输出** - 相同的输入产生相同的输出，以便可重复的工作流程 ``` # 直接传递给 Claude Code debtmap analyze . --format markdown --top 1 | claude "Fix this technical debt" ``` 有关详细信息，请参阅 [LLM 集成指南](https://iepathos.github.io/debtmap/llm-integration.html). ## 输出格式 ``` # Markdown（适用于 AI 工作流程） debtmap analyze . --format markdown # JSON 用于程序访问 debtmap analyze . --format json # 终端/TUI 用于直接探索 debtmap analyze . # Graphviz 依赖可视化 debtmap analyze . --format dot -o deps.dot ``` ## 可视化仪表板 使用 **[在线仪表板](https://iepathos.github.io/debtmap/dashboard/)** 交互式地探索您的结果： ``` # 生成 JSON 输出 debtmap analyze . --format json -o debtmap.json --lcov coverage.lcov --context # 打开仪表板并加载您的 JSON 文件 open https://iepathos.github.io/debtmap/dashboard/ ``` **本地开发**：如果您已克隆了存储库，请直接在浏览器中打开 `viz-dev/dashboard.html`。 仪表板提供： - **风险象限** - 函数按复杂性与覆盖率差距绘制 - **最高债务项** - 可排序的最高优先级问题表 - **模块流程** - 显示债务关系的弦图 - **风险雷达** - 对顶级文件的多维比较 所有处理都在客户端进行 - 您的数据永远不会离开您的浏览器。 ## 包含覆盖率数据 ``` # Rust 覆盖率 cargo llvm-cov --lcov --output-path coverage.lcov # 与覆盖率集成分析 debtmap analyze . --lcov coverage.lcov ``` ``` # Python 覆盖率 pytest --cov=. --cov-report=lcov:coverage.lcov # 与覆盖率集成分析 debtmap analyze . --lcov coverage.lcov ``` 覆盖率数据使风险评估更加准确 - 具有良好测试的复杂代码比没有测试的简单代码排名更低。 ## CI/CD 集成 ``` # .github/workflows/quality.yml name: Code Quality on: [push, pull_request] jobs: debtmap: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: iepathos/debtmap-action@v1 with: max-complexity-density: '10.0' fail-on-violation: 'true' ``` ## 文档 **[完整文档](https://iepathos.github.io/debtmap/)** — 指南、示例、配置参考 快速链接： - [入门](https://iepathos.github.io/debtmap/getting-started.html) - [可视化仪表板](https://iepathos.github.io/debtmap/dashboard/) - [LLM 集成](https://iepathos.github.io/debtmap/llm-integration.html) - [配置](https://iepathos.github.io/debtmap/configuration.html) - [指标参考](https://iepathos.github.io/debtmap/metrics-reference.html) ## 性能分析 Debtmap 包含内置分析以识别性能瓶颈。 ### 内置计时 ``` # 显示每个分析阶段的计时分解 debtmap analyze . --profile # 将详细计时数据写入 JSON debtmap analyze . --profile --profile-output timing.json ``` 示例输出： ``` === Profiling Report === Total analysis time: 38.55s Phase breakdown: Operation Duration % Count ------------------------------------------------------------------------ analyze_project 27.94s 72.5% 1 duplication_detection 24.94s 64.7% 1 parsing 2.57s 6.7% 1 unified_analysis 10.75s 27.9% 1 call_graph_building 8.05s 20.9% 1 debt_scoring 1.89s 4.9% 1 ``` ### 外部分析器 对于 CPU 级别的分析，请使用采样分析器与调试构建： **macOS (samply)** ``` # 安装 samply cargo install samply # 构建带调试符号 cargo build --profile dev # 分析 debtmap samply record ./target/debug/debtmap analyze /path/to/project # 使用火焰图打开 Firefox Profiler ``` **macOS (Instruments)** ``` # 构建带调试符号 cargo build --profile dev # 使用 Instruments 分析 xcrun xctrace record --template 'Time Profiler' --launch ./target/debug/debtmap analyze . ``` **Linux (perf)** ``` # 构建带调试符号 cargo build --profile dev # 记录配置文件 perf record -g ./target/debug/debtmap analyze /path/to/project # 查看结果 perf report ``` **提示**：`--profile` 标志标识 *什么* 慢；采样分析器显示 *为什么* 代码级别上慢。 ## 路线图 **当前重点**：Rust、Python、JavaScript 和 TypeScript 分析质量 + AI 工作流程集成 - [x] 认知 + 节点复杂性 - [x] 测试覆盖率相关性 - [x] 基于模式的误报减少 - [x] LLM 优化输出格式 - [x] AI 上下文建议 - [x] Rust 语言支持 - [x] Python 语言支持 - [x] JavaScript 语言支持 - [x] TypeScript 语言支持 - [x] 用于仪表板和自动化的统一 JSON 输出 - [x] Graphviz DOT 依赖关系输出 - [x] 覆盖率诊断和函数级覆盖率说明 - [x] 之前/之后比较和改进验证 - [ ] 大型代码库的流式输出 - [ ] Go 语言支持 ## 贡献 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。 **良好的入门问题**： - 改进 Rust 特定的分析 - 添加新的复杂性指标 - 扩展测试覆盖率 - 文档改进 ## 许可证 MIT — 查看 [LICENSE](LICENSE) **有问题？** [打开问题](https://github.com/iepathos/debtmap/issues) 或查看 [文档](https://iepathos.github.io/debtmap/).

标签：Anchore, Git历史分析, TUI, 代码纯度, 代码耦合度, 代码覆盖率, 代码重构, 仪表盘, 优先级评分, 可视化界面, 复杂度度量, 技术债务分析, 技术栈分析, 数据可视化, 模式识别, 测试覆盖率, 熵, 终端工具, 网络安全研究, 自动化辅助, 认知复杂度, 逆向工具, 通知系统, 错误基检测, 静态代码分析, 风险预测