HenryLok0/CodeState
GitHub: HenryLok0/CodeState
一款零遥测的本地代码度量 CLI 工具，提供从行数统计、复杂度分析到 Git 热点追踪的全方位代码库健康洞察，并支持终端可视化与多格式报告导出。
Stars: 9 | Forks: 0
# CodeState
[](https://github.com/HenryLok0/CodeState)
[](LICENSE)
[](https://github.com/HenryLok0/CodeState/stargazers)
在你的终端中即时获取代码库洞察 —— 快速、本地、零遥测。
CodeState 会分析你的代码仓库并生成详细的统计数据，例如按扩展名分类的代码行数、复杂度、注释密度、热点、贡献者等。它在终端中渲染 ASCII 图表，并可以导出 JSON/HTML/Markdown 用于报告。
## 功能特性
- **🚀 零安装：** 下载独立的二进制文件即可立即运行。无需安装 Python！
- **🤖 GitHub Action 就绪：** 轻松实现 PR 审查和代码库健康检查的自动化。
- **✨ 精美的 TUI：** 由 `rich` 驱动的绚丽终端 UI，支持彩色和样式化表格。
- 具备缓存和 .gitignore 感知能力的快速代码库概览
- 终端内 ASCII 可视化：饼图、条形图和复杂度热力图
- 详细的统计信息：文件、LOC（代码行数）、注释、函数、复杂度
- 质量检查：重复代码、命名规范、死代码提示
- 历史洞察：Git 热点/变动 和贡献者
- 灵活的导出：HTML、Markdown、JSON、CSV、Excel
## 安装说明
### 选项 1：零安装二进制文件（推荐）
从 [Releases 页面](https://github.com/HenryLok0/CodeState/releases) 下载独立的二进制文件。无需安装 Python！
```
# Linux / macOS
curl -L https://github.com/HenryLok0/CodeState/releases/latest/download/codestate -o codestate
chmod +x codestate
./codestate
# Windows
# 从 Releases 下载 codestate.exe 并直接运行
```
### 选项 2：Python / pip
```
# 通过 pipx 安装（推荐用于 CLI 工具）
pipx install codestate
# 或者通过 pip 安装
pip install codestate
```
## 快速开始
```
# 获取当前 repo 的摘要
codestate --summary
# 导出 HTML 报告
codestate --html --output report.html
```
## GitHub Action (CI/CD)
CodeState 内置支持 GitHub Actions！只需将以下内容添加到你的 `.github/workflows/pr.yml`，即可自动化代码库健康检查和 PR 审查：
```
name: PR CodeState Check
on: [pull_request]
jobs:
codestate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run CodeState Analysis
uses: HenryLok0/CodeState@v1
with:
args: '--summary --failures-only'
github_token: ${{ secrets.GITHUB_TOKEN }}
```
此 Action 将自动运行 CodeState，并将一份精美的报告作为 PR 评论发布。
## 使用说明
```
# 基本用法
codestate [directory] [options]
```
### 缓存选项（强烈推荐用于大型项目）
```
# 提示：对于大型项目，首次运行时使用 --cache 构建缓存，以便在后续的重复分析中大幅提升速度
codestate --cache
# 缓存构建完成后，后续的查询（如 --details、--html、--contributors 等）将自动使用该缓存
# 如果没有缓存数据，每条命令都会重新扫描整个项目，这对于大型项目来说可能会非常缓慢。
codestate --details
# 要重建缓存（例如，在大型重构之后或缓存已过期时），请删除缓存文件夹
codestate --cache-delete
```
## 选项
| 选项 | 描述 |
|------------------------|-------------|
| **[基础分析与过滤]** | |
| `directory` | 要分析的目标目录（默认：当前目录） |
| `--exclude` | 要排除的目录（例如：--exclude .git venv node_modules） |
| `--ext` | 要包含的文件扩展名（例如：--ext .py .js） |
| `--only-lang` | 仅分析特定的文件扩展名，以逗号分隔（例如：py,js） |
| `--top N` | 仅显示按行数或复杂度排名的前 N 个文件 |
| `--failures-only` | 仅显示有问题的文件（命名、大小、复杂度等） |
| `--regex` | 用于自定义代码检查的用户定义正则表达式规则（以空格分隔，需用引号括起） |
| `--file-age` | 显示文件创建和最后修改时间 |
| `--uncommitted` | 显示未提交更改的文件统计信息 |
| `--size` | 以表格形式显示每个文件的字节大小 |
| `--list-extensions` | 列出项目中找到的所有文件扩展名及其计数和百分比 |
| `--min-lines ` | 仅显示总行数 >= N 的文件 |
| `--find ` | 查找代码库中匹配关键字或正则表达式的所有行 |
| `--cache` | 构建并使用缓存，以实现更快的重复分析（强烈推荐用于大型代码库） |
| `--cache-delete` | 删除 `.codestate` 中的所有缓存数据（强制在下一次运行时重新构建缓存） |
| **[统计与详细分析]** | |
| `--details` | 显示每个文件的详细统计信息 |
| `--dup` | 显示重复的代码块（5行及以上） |
| `--maxmin` | 显示行数最多/最少的文件 |
| `--langdist` | 以 ASCII 饼图形式显示语言（文件扩展名）分布 |
| `--complexitymap` | 显示文件复杂度的 ASCII 热力图 |
| `--complexity-graph` | 显示文件复杂度的 ASCII 条形图 |
| `--warnsize` | 对大文件/函数发出警告（可选择指定文件和函数行数阈值，默认为 300/50） |
| `--naming` | 检查函数/类的命名规范（PEP8，PascalCase） |
| `--apidoc` | 显示 API/函数/类的 docstring 摘要 |
| `--deadcode` | 显示 Python 文件中未使用的（死）函数/类 |
| `--typestats` | 显示函数参数/类型注解的统计信息 |
| `--trend` | 显示特定文件的行数趋势 |
| `--refactor-suggest` | 显示需要重构的文件/函数及原因 |
| `--autofix-suggest` | 为命名、注释和重复代码提供自动修复补丁建议 |
| `--refactor-map` | 显示需要重构的文件/函数的表格 |
| `--complexity-threshold ` | 设置用于警告的自定义复杂度阈值（**需要一个值**，例如：--complexity-threshold 5） |
| `--open ` | 显示单个文件的详细分析 |
| `--blame ` | 显示某个文件的 git blame 统计信息 |
| `--compare ` | 比较两个目录之间的统计数据 |
| **[输出 / 报告]** | |
| `--html` | 将结果导出为 HTML 表格 |
| `--md` | 将结果导出为 Markdown 表格 |
| `--json` | 将结果导出为 JSON |
| `--csv` | 将摘要统计信息导出为 CSV |
| `--excel` | 将摘要统计信息导出为 Excel (.xlsx) |
| `--details-csv` | 将每个文件的详细统计信息导出为 CSV |
| `--groupdir-csv` | 将按目录分组的统计信息导出为 CSV |
| `--groupext-csv` | 将按扩展名分组的统计信息导出为 CSV |
| `--test-coverage ` | 从 coverage.xml 文件显示测试覆盖率分析 |
| `--output`, `-o` | HTML/Markdown/JSON/CSV/Excel 导出的输出文件 |
| `--report-issues` | 将所有检测到的问题（命名、大小、复杂度等）导出为 markdown 或 JSON 报告 |
| **[项目结构与健康度]** | |
| `--tree` | 显示项目结构的 ASCII 树状视图 |
| `--structure-mermaid` | 生成项目目录结构的 Mermaid 图表 |
| `--health` | 显示项目健康度评分和建议 |
| `--summary` | 生成 markdown 格式的项目摘要（打印或使用 --output） |
| `--badge-sustainability`| 输出 SVG 可持续性/健康度徽章 |
| `--lang-card-svg` | 输出 SVG 语言统计卡片（类似于 GitHub top-langs） |
| **[贡献者 / CI]** | |
| `--authors` | 显示每个文件的主要 git 作者和最后修改者 |
| `--contributors` | 显示贡献者统计信息（每个作者的文件数、行数、提交数） |
| `--contributors-detail`| 显示详细的贡献者统计信息 |
| `--hotspot` | 显示最频繁更改的文件 |
| `--churn` | 显示过去 N 天内更改最多的文件（默认为 30 天） |
| `--ci` | CI/CD 模式：如果发现重大问题则以非零状态退出 |
| **[自动化 / README / 徽章]** | |
| `--badges` | 自动检测并打印项目的语言/框架/许可证/CI 徽章，用于 README |
| `--readme` | 基于分析自动生成 README 模板 |
| **[其他]** | |
| `--style-check` | 检查代码风格：缩进、行长、末尾空格、EOF 换行符 |
| `--openapi` | 为 Flask/FastAPI 路由生成 OpenAPI 3.0 JSON |
| `--multi [dir2 ...]` | 分析多个根目录（支持 monorepo，**至少需要一个目录**） |
| `--version` | 显示 codestate 版本并退出 |
## 示例
```
# 分析当前目录（默认）
codestate
# 分析特定目录并排除 build 和 dist 文件夹
codestate myproject --exclude build dist
# 仅分析 Python 和 JavaScript 文件
codestate --only-lang py,js
# 仅显示最大的前 5 个文件
codestate --top 5
# 显示每个文件的详细统计信息
codestate --details
# 将结果导出为 HTML
codestate --html --output report.html
# 将结果导出为 CSV
codestate --csv --output report.csv
# 将结果导出为 Excel
codestate --excel --output report.xlsx
# 仅显示有问题的文件（命名、大小、复杂度等）
codestate --failures-only
# 显示文件创建和最后修改时间
codestate --file-age
# 生成 markdown 项目摘要
codestate --summary --output PROJECT_SUMMARY.md
# 设置自定义复杂度阈值（需要一个值）
codestate --complexity-threshold 5 --failures-only
# 分析多个目录（至少需要一个目录）
codestate --multi src tests
# 列出所有文件扩展名及其计数和百分比
codestate --list-extensions
```
## 对比
| 特性 | CodeState | cloc | scc | tokei |
| --- | --- | --- | --- | --- |
| 统计信息（文件/行数/注释） | 是 | 是 | 是 | 是 |
| 终端内的 ASCII 图表 / 热力图 | 是 | 否 | 否 | 否 |
| 报告导出 | 是 | 有限 | 有限 | 有限 |
| .gitignore 感知与缓存 | 是 | 手动排除 | 手动排除 | 手动排除 |
| 热点 / 重复代码 / 命名检查 | 是 | 否 | 否 | 否 |
备注：
- “手动排除”意味着该工具支持通过标志位来忽略路径，但不会像 CodeState 那样自动读取 .gitignore 或提供内置缓存。
- 有关速度指南以及如何复现测试指标，请参阅下文的性能基准测试。
## 为什么选择 CodeState？
- 即时理解：超越 LOC（代码行数），在你的终端中直接突出显示重复代码、复杂度热点、重构候选、命名问题和死代码。
- 默认可视化：ASCII 饼图/热力图/条形图使得趋势在审查中一目了然，无需离开 CLI。
- 基于历史的决策：git 热点/变动 帮助你优先处理最重要的文件。
- 团队可见性：按文件划分的贡献者和 blame 洞察可解锁所有权和入职上下文。
- CI 就绪的产出物：导出 HTML/Markdown/JSON/CSV/Excel 用于报告、仪表盘和流水线。
- 更快的重复运行：内置缓存和 .gitignore 支持可确保大型代码仓库长期保持敏捷。
提示：将 CodeState 与 GitHub Action 结合使用，在每个 PR 上发布紧凑的 Markdown 摘要。
## 贡献指南
欢迎贡献代码！请查阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
## 许可证
本项目基于 MIT 许可证授权。详情请参见 [LICENSE](LICENSE) 文件。
## 支持
如果你有任何问题或需要帮助，请在 GitHub 上提交 issue。
感谢所有贡献者和开源社区的支持。
## 常见问题排查
- 找不到命令：请尝试使用 `python -m codestate.cli` 而不是 `codestate`。
- Windows 路径/编码异常：请从本地文件夹运行（避免使用同步文件夹），并确保控制台使用 UTF-8 编码。
- 超大型代码仓库：请先使用 `--cache` 运行一次，随后的命令执行速度将会快得多。
标签：ASCII图表, CSV, Excel, GitHub Action, Git分析, HTML报告, Markdown, Python, TUI, 云安全监控, 代码健康度, 代码分析, 代码审查, 代码度量, 代码热力点, 代码统计, 代码重复检测, 凭证管理, 复杂度分析, 威胁情报, 开发者工具, 开源, 弱口令爆破, 技术债, 报告导出, 无后门, 漏洞挖掘, 离线分析, 终端UI, 网络安全研究, 逆向工具, 零遥测, 静态分析