jbakchr/hewd
GitHub: jbakchr/hewd
一款 Go 编写的命令行工具，用于扫描、诊断和评估代码仓库的文档与结构健康度，支持 CI 集成与自动修复。
Stars: 0 | Forks: 0
# 📘 _**hewd**_ — 项目健康度、文档与结构工具包
`hewd` 是一个快速、无依赖的 CLI，用于分析、比较和改进软件仓库的整体健康状况。
它帮助团队强制执行文档标准，保持一致的结构，检测回归，并自动修复常见问题 —— 无论是在本地还是 CI 中。
## ✨ 功能特性
- 🔍 **扫描** 仓库的文档、配置、结构和元数据
- 🩺 通过 `hewd doctor` **诊断** 项目健康状况
- 🧮 对文档、配置和结构类别进行**评分**
- 🔁 使用 `hewd diff` **比较报告**（新增问题、已解决问题、分数变化）
- 🚨 CI 流水线的 **回归门禁**
- 🧾 **机器可读的 JSON/YAML 导出**
- 📝 用于 GitHub PR 评论的 **Markdown 报告**
- 🧰 **自动修复** 缺失的文档和 CI 文件
- 🏷️ **SVG 徽章** 生成器
- 🤖 支持更新 PR 评论的 **GitHub Action**
完整文档可在 `docs/` 目录中找到。
## 🚀 快速开始
### 安装（从源码构建）
```
git clone https://github.com/jbakchr/hewd
cd hewd
go build -o hewd ./cmd/hewd
sudo mv hewd /usr/local/bin/hewd
```
### 扫描你的项目
```
hewd scan --pretty
```
### 运行诊断
```
hewd doctor
```
生成 Markdown 报告：
```
hewd doctor --md > health.md
```
### 导出机器可读数据
```
hewd export --output hewd.json
```
### 比较报告（diff 引擎）
```
hewd diff old.json new.json
```
支持 Pretty、JSON、YAML 和 Markdown 输出。
## 📊 示例输出
### 🔍 运行 `hewd doctor`
```
===== OVERALL SCORE =====
82 / 100
===== CATEGORY SCORES =====
Documentation: 70
Config: 90
Structure: 85
===== DOCUMENTATION ISSUES =====
- DOC_LICENSE_MISSING (warn): LICENSE file is missing.
- DOC_CONTRIBUTING_MISSING (info): CONTRIBUTING.md not found.
===== CONFIG ISSUES =====
(none)
===== STRUCTURE ISSUES =====
- STR_DOCS_DIR_MISSING (warn): docs/ directory not found.
```
### 🔁 Diff 示例
```
===== OVERALL SCORE =====
Old: 78
New: 87
Change: +9 ↑
===== CATEGORY SCORES =====
Documentation: 65 → 75 (+10)
Config: 80 → 84 (+4)
Structure: 90 → 92 (+2)
===== NEW ISSUES =====
(none)
===== RESOLVED ISSUES =====
documentation
- DOC_LICENSE_MISSING (warn)
- DOC_README_STALE (info)
```
### 🤖 GitHub PR 评论示例 (`--md`)
Markdown 报告包括：
* 分数变化
* 类别分数增减
* 新增问题 / 已解决问题
* 趋势指示器
* 分组显示以提高可读性
## 🤖 GitHub Action
包含的 GitHub Action 可以：
* 运行 `hewd doctor` 或 `hewd diff`
* 发布或更新 PR 评论
* 运行回归门禁 (`--fail-on-any-regression`)
* 导出 Markdown + JSON diff 构件
最小化设置：
```
jobs:
hewd:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/hewd-action
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pr-comment: true
md-report: true
```
详见 `docs/github-action.md`。
## 🧰 自动修复模式
```
hewd fix # dry-run
hewd fix --apply # apply fixes
```
创建：
* LICENSE
* CONTRIBUTING.md
* CHANGELOG.md
* docs/ 目录
* 基础 CI 工作流模板
更多修复器将在未来的版本中推出。
## 📚 文档
所有扩展文档位于 **`docs/`**：
* 📘 入门指南 — `docs/getting-started.md`
* 🩺 Doctor — `docs/commands/doctor.md`
* 🔁 Diff — `docs/commands/diff.md`
* 🔧 Fix — `docs/commands/fix.md`
* 🧾 机器输出 — `docs/machine-output.md`
* ⚙️ 配置 — `docs/configuration.md`
* 🤖 GitHub Action — `docs/github-action.md`
* 🗺️ 路线图 — `docs/roadmap.md`
## 🏗 路线图
查看完整路线图：
👉 `docs/roadmap.md`
*当前状态：hewd 处于 **阶段 2 — v0.1.0 发布准备**。*
## 📄 许可证
待定。
## 🔗 链接
* 源码：
* 问题：
* 发布：
标签：DNS解析, EVTX分析, GitHub Action, Go, Homebrew安装, JSON, Markdown, Ruby工具, YAML, 云安全监控, 依赖管理, 健康检查, 威胁情报, 安全库, 开发者工具, 开源项目, 数据管道, 文档生成, 文档结构分析, 日志审计, 模块化设计, 自动化修复, 软件工程, 防御加固, 静态分析, 项目结构