danyasync/explain-codebase

# 解释 Codebase [](https://pypi.org/project/explain-codebase/) [](https://pypi.org/project/explain-codebase/) [](https://github.com/danyasync/explain-codebase/actions/workflows/ci.yml) [](https://github.com/danyasync/explain-codebase/blob/main/LICENSE) 用于映射仓库架构、依赖关系、入口点、副作用和变更风险的静态分析 CLI。 `explain-codebase` 可帮助您发现执行从哪里开始、哪些文件是核心、源文件之间如何相互依赖，以及哪里发生的变更可能会产生最广泛的影响。它会读取源文件，而无需导入或运行目标项目。 ## 快速开始 从 PyPI 安装并检查当前目录： ``` python -m pip install explain-codebase explain-codebase . ``` 要进行隔离的命令行安装，请使用 `pipx`： ``` pipx install explain-codebase explain-codebase . ``` 默认视图特意保持了紧凑： ``` Explain Codebase -------------------------------- Repository Path C:\Projects\checkout-service Type Python backend service Language python Files 7 Architecture Entrypoints 1 Core modules 5 Side effects 4 Suggested starting point api_server.py Run with --verbose to see full architecture ``` ## 它展示的内容 - 可能的应用程序入口点 - 根据依赖使用情况排名的核心模块 - 相对路径和包的导入关系 - 可能的执行路径 - 与数据库、网络、文件系统或缓存交互的文件 - 常见的架构区域，如服务、存储库、路由和控制器 - 大文件、高连接度文件、循环依赖和有风险的变更点 - 建议的入职阅读顺序 - 聚焦的依赖图和 HTML 架构报告 这些结果是旨在缩短初步调查时间的启发式信号。它们不能替代阅读关键代码路径或运行目标项目自身的检查。 ## 安装说明 ### 前置条件 - Python 3.10 或更高版本 - 检查公共 GitHub 仓库时需要 Git - 进行远程仓库检查和克隆时需要网络访问权限 ### 从 PyPI 安装 ``` python -m pip install explain-codebase ``` ### 隔离的 CLI 安装 ``` pipx install explain-codebase ``` ### 本地开发 ``` python -m pip install -e ".[dev]" ``` ## 用法 ### 常用命令 | 目标 | 命令 | | --- | --- | | 检查当前目录 | `explain-codebase .` | | 检查另一个本地目录 | `explain-codebase path/to/repository` | | 显示详细的架构视图 | `explain-codebase . --verbose` | | 专注于架构风险 | `explain-codebase . --deep` | | 将 JSON 输出到标准输出 | `explain-codebase . --json` | | 限制扫描文件的数量 | `explain-codebase . --max-files 500` | | 建议阅读顺序 | `explain-codebase onboarding .` | | 在仓库上下文中解释单个文件 | `explain-codebase file src/services/orders.py` | | 生成交互式依赖图 | `explain-codebase . --graph` | | 生成 HTML 架构报告 | `explain-codebase . --report` | | 检测到架构问题时返回失败状态 | `explain-codebase . --ci` | | 显示已安装的版本 | `explain-codebase --version` | `--verbose` 和 `--deep` 不能组合使用。 ### 图表视图 `--graph` 会生成 `dependency_graph.html` 文件。`--report` 会生成 `codebase_report.html` 文件。这两个文件都会写入到当前工作目录。 交互式图表从确定性的节点位置开始，具有克制的环境脉动和方向性边流。选择某个节点会高亮其直接依赖项，而不会重启布局，同时搜索和过滤会使其余节点保持在原位。 可以拖动节点以将其调整到更有用的排列方式。当一个放下的节点与另一个节点重叠时，有界的局部碰撞处理只会轻柔地分开涉及的附近节点；它永远不会重启全局布局物理。在普通点击期间的微小指针移动将被忽略。 | 标志 | 视图 | | --- | --- | | `--architecture` | 架构级别的依赖关系；这是默认的图表视图 | | `--full` | 完整的文件级依赖图 | | `--entrypoint` | 从可能的入口点开始的路径 | | `--risk` | 高连接度和有风险的文件 | | `--side-effects` | 可能存在外部副作用的文件 | 最多选择一个图表视图标志。图表视图标志需要配合 `--graph` 或 `--report` 使用。 示例： ``` explain-codebase . --graph --architecture explain-codebase . --graph --entrypoint explain-codebase . --report --risk explain-codebase . --graph --full ``` ## 支持的源码格式 | 语言 | 扩展名 | 主要信号 | | --- | --- | --- | | Python | `.py` | 语法树、导入、定义、调用和副作用 | | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | 静态导入、CommonJS 导入、调用和副作用 | | TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | 静态导入、调用和副作用 | 导入解析会考虑相对路径、包入口文件以及支持的扩展名变体（前提是这些关系可以在静态分析下确定）。 ## 扫描行为 对于本地目录，扫描器会： - 仅考虑受支持的源码扩展名 - 将解析后的文件路径保留在所选仓库内 - 遵守可选的文件数量限制和每个文件 1 MiB 的大小限制 - 跳过常见的依赖、缓存、构建、覆盖率和环境目录 - 遵守根目录的 `.gitignore` 文件 - 当可以读取 Git 元数据时，将 Git 工作树限制为跟踪的文件，如果 Git 不可用，则回退到文件系统扫描 - 安全处理无法读取的源文件，并跳过不受支持或超大文件 使用 `--max-files` 可降低文件数量限制，以实现更聚焦或更快的扫描。 ## 公共 GitHub 仓库 传入标准格式的公共仓库 URL： ``` explain-codebase https://github.com/owner/repository ``` CLI 会检查公共仓库元数据、请求确认、在临时目录中执行受限克隆、分析克隆内容，并在之后删除该临时目录。不支持私有仓库、其他托管服务商和任意的 Git URL。 远程检查需要交互式终端、Git 和网络访问权限。克隆超时可能会停止远程准备工作，并且在分析期间会跳过超大源文件。 ## 输出与自动化 ### 标准输出与错误输出 人类可读的输出和 JSON 会写入到标准输出。进度阶段、警告和错误会写入到标准错误。这使得 JSON 适合进行重定向： ``` explain-codebase . --json > architecture.json ``` ### CI 模式 ``` explain-codebase . --ci ``` 未发现架构问题时，CI 模式会以状态码 `0` 退出；检测到问题时，则以状态码 `1` 退出。当前的问题检查包括循环依赖和实用工具类的上帝模块。阈值内置在 CLI 中。 ### JSON JSON 输出包含仓库信息、入口点、核心模块、副作用文件、架构区域、大文件、热点、有风险的文件、架构问题、执行路径以及可选的 HTML 输出路径。 ## 工作原理 从宏观层面来看，`explain-codebase` 会： 1. 解析并验证目标 2. 在安全边界内选择受支持的源文件 3. 解析静态导入和源码级信号 4. 解析导入并构建依赖图 5. 对核心模块进行排名，并识别入口点、副作用、热点和架构问题 6. 渲染选定的 CLI、JSON、图表或报告输出 在分析过程中，不会导入或执行目标项目的源代码。 ## 局限性 - 动态导入、反射、运行时依赖注入和特定于框架的装配可能不可见。 - 自定义路径别名和构建工具转换可能会降低导入解析的准确性。 - 仅在单独的转换步骤后才有效的语法可能会被跳过。 - 压缩的、第三方复制的、镜像的或高度重复的代码可能会降低信号质量。 - 大型 monorepo 应使用 `--max-files` 或分析更窄范围的目录。 - 远程分析仅支持公共 GitHub 仓库。 - 浅层远程克隆仍然可能传输大文件，因为仓库总下载大小没有上限。 - 交互式 HTML 视图会从公共 CDN 加载版本固定且经过完整性校验的图表库，并且在打开时需要网络访问权限。 ## 开发 安装开发工具并运行检查： ``` python -m pip install -e ".[dev]" ruff check . pytest python -m build python -m twine check --strict dist/* ``` ## 项目信息 - [更新日志](https://github.com/danyasync/explain-codebase/blob/main/CHANGELOG.md) - [安全策略](https://github.com/danyasync/explain-codebase/blob/main/SECURITY.md) - [问题追踪器](https://github.com/danyasync/explain-codebase/issues) - [PyPI 包](https://pypi.org/project/explain-codebase/) ## 许可证 根据 [MIT 许可证](https://github.com/danyasync/explain-codebase/blob/main/LICENSE) 授权。

标签：Python, WebSocket, 云安全监控, 代码审查, 依赖分析, 文档结构分析, 无后门, 架构分析, 逆向工具, 静态分析