Project Maturity

---
name: project-maturity
description: >
  对任意项目进行全面的成熟度评估扫描。当用户说"检查项目成熟度"、"项目评估"、
  "maturity assessment"、"代码质量扫描"、"项目健康度"、"项目体检"、
  "scan project maturity"、"项目有多成熟"时触发。适用场景：接手新项目前的摸底、
  发布前的质量审查、技术尽调、团队内部代码健康度盘点。
---

# Project Maturity Scanner

对任意项目进行 8 维度深度成熟度扫描，产出结构化 Markdown 报告。

---

## 工作流概览

```
语言检测 → 加载 Reference → 并行收集 8 维度数据 → 综合评分 → 输出报告
```

三个核心原则：
1. **用数据说话，不做主观猜测** — 每个评分背后都有可复现的命令和数据
2. **先收集后评分** — 禁止在信息不全时下结论
3. **风险优先** — 高风险项放在报告最前面，方便读者优先关注

---

## Step 1: 语言检测与 Reference 加载

### 1.1 自动检测

扫描项目根目录，按优先级判断主语言：

| 信号 | 判定 |
|------|------|
| `Cargo.toml` | Rust |
| `package.json` + `tsconfig.json` | TypeScript |
| `package.json`（无 tsconfig） | JavaScript/Node |
| `go.mod` | Go |
| `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
| `pom.xml` / `build.gradle` | Java/Kotlin |
| `Gemfile` | Ruby |
| `CMakeLists.txt` | C/C++ |
| 以上皆无 | Generic（通用检查） |

多语言项目：按代码量占比识别主语言和次语言，报告中对每种语言分别评估。

### 1.2 加载语言 Reference

根据检测结果，读对应 reference 文件获取语言特定的检查命令和指标：

- `references/rust.md` — Rust 项目
- `references/typescript.md` — TypeScript/JavaScript 项目
- `references/python.md` — Python 项目
- `references/go.md` — Go 项目
- `references/generic.md` — 通用回退

Reference 文件包含的内容：
- 该语言的代码统计命令
- 测试框架识别与运行命令
- 静态分析/lint 工具
- 依赖审计工具
- 语言特定的成熟度阈值

---

## Step 2: 并行收集 8 维度数据

**关键**：所有收集操作必须并行执行。不要串行逐个询问。

### 维度 1：项目规模

用语言 reference 提供的命令统计：

```
✅ 源代码行数（排除依赖/target/node_modules/build）
✅ 源文件数量
✅ 模块/包/crate 数量
✅ 各模块代码分布（最大的 5 个模块）
✅ 按语言拆分的代码量（多语言项目）
```

评价标准：
- 小型 < 5,000 行 | 中型 5k-50k | 大型 50k-200k | 超大型 > 200k
- 模块化程度 = 模块数量是否与代码规模匹配

### 维度 2：开发活跃度

```
✅ 总提交数 + 首次/最后提交日期
✅ 近 30 天提交趋势（每日统计）
✅ 贡献者数量 + Top 3 贡献者占比（识别总线因子）
✅ 活跃分支数 + 标签数
✅ 版本标签命名规范度
✅ 合并提交比例（反映协作模式）
```

评价标准：
- 近 30 天日均提交 > 3 → 极度活跃 | 1-3 → 健康 | 0.1-1 → 维护模式 | < 0.1 → 停滞
- 单人贡献占比 > 90% → 总线风险高
- 无版本标签 → 发布不规范

### 维度 3：测试覆盖

**分两层检查**：单元测试 + 集成/E2E 测试。

```
✅ #[test] / it() / def test_* 等测试函数数量
✅ 测试目录结构（tests/ 或 __tests__/ 等）
✅ 运行完整测试套件，统计通过/失败/跳过
✅ 各子模块的测试代码行数 vs 源代码行数
✅ 是否有 E2E/集成测试及框架
✅ 是否有覆盖率工具配置（tarpaulin/istanbul/coverage.py 等）
✅ CI 中是否跑测试
```

评价标准（通用）：
- 测试/源代码比 > 50% → 优秀 | 20-50% → 良好 | 5-20% → 不足 | < 5% → 严重不足
- 核心模块零测试 → 直接标红
- CI 不跑测试 → 扣一档

**注意**：不同语言/框架的测试文化不同。Rust 项目 5% 测试比可能已经不错（大量类型系统保证），但 JS/Python 项目 5% 是严重不足。具体阈值见各语言 reference。

### 维度 4：代码质量

```
✅ 静态分析结果（clippy/eslint/pylint 等）
✅ 构建是否通过（build/compile）
✅ 格式化检查（fmt/format/check）
✅ unsafe/危险模式计数（如 Rust unsafe、Python eval/exec、JS eval）
✅ 错误处理模式（unwrap/panic 计数 vs expect/Result 处理）
✅ TODO/FIXME/HACK/XXX 残留数量
✅ pre-commit hooks 配置（lefthook/husky/pre-commit）
```

评价标准：
- Lint 0 warning → 优秀 | < 10 → 良好 | 10-50 → 需关注 | > 50 → 差
- 构建不通过 → 严重问题
- unwrap 密度 > 30 处/千行 → 错误处理薄弱
- 有 pre-commit → +1 分

### 维度 5：CI/CD 与 DevOps

```
✅ CI pipeline 文件（.github/workflows / .gitlab-ci.yml / Jenkinsfile 等）
✅ CI 覆盖的操作系统数
✅ CI 步骤完整性：build / test / lint / audit / bench
✅ 发布流程（release workflow / publish script / Docker）
✅ 多平台/多架构构建支持
✅ 容器化（Dockerfile / docker-compose）
✅ 安装/部署脚本
✅ 版本管理自动化程度
```

评价标准：
- CI 覆盖 3 OS + test + lint + audit → 优秀
- CI 只 build → 基础
- 无 CI → 严重不足
- 有自动化 release + Docker → +1 分

### 维度 6：文档

```
✅ README 质量（行数、是否有架构图、快速上手）
✅ CHANGELOG 是否存在及更新频率
✅ 设计文档/架构文档数量
✅ API 文档生成配置（rustdoc/jsdoc/sphinx 等）
✅ 贡献指南（CONTRIBUTING.md）
✅ 开发规范文档（CLAUDE.md / DEVELOPER.md）
✅ License 文件
```

评价标准：
- README > 100 行 + 架构图 → 优秀
- CHANGELOG 维护到最新版 → 良好
- 无 License → 法律风险
- 有 AI 开发规范（CLAUDE.md/AGENTS.md）→ 现代项目加分

### 维度 7：安全

```
✅ 依赖审计工具运行结果（cargo audit / npm audit / pip audit / govulncheck）
✅ unsafe 代码块 + 是否有安全注释
✅ 密钥/凭证硬编码检查（.env 文件是否在 .gitignore）
✅ 已知漏洞扫描
✅ 是否有安全策略文档（SECURITY.md）
```

评价标准：
- 0 已知漏洞 → 安全 | 有高危漏洞 → 严重
- .env 已 gitignored → 合格
- 有 SECURITY.md → +1 分

### 维度 8：外部集成与生态

```
✅ 监控/可观测性（tracing/logging/metrics）
✅ 第三方服务集成（数据库、消息队列、API 网关等）
✅ 插件/扩展系统
✅ i18n 国际化
✅ 多环境配置管理
✅ 外部工具链集成
```

评价标准：
- 有结构化日志 → 合格
- 有 tracing/metrics → 优秀
- 有插件系统 → 架构成熟度高

---

## Step 3: 综合评分

### 3.1 评分方法

每个维度给出 1-5 星评分：

| 星级 | 含义 | 典型特征 |
|:---:|------|---------|
| ★★★★★ | 行业领先 | 所有子项均达到最佳实践 |
| ★★★★☆ | 良好 | 大部分子项达标，有改进空间 |
| ★★★☆☆ | 基本合格 | 核心功能具备，但存在明显短板 |
| ★★☆☆☆ | 不足 | 多个子项缺失，影响项目健康 |
| ★☆☆☆☆ | 严重不足 | 关键维度存在重大缺陷 |

### 3.2 综合评分计算

综合分 = 各维度加权平均：

| 维度 | 权重 | 理由 |
|------|:---:|------|
| 测试覆盖 | 20% | 决定代码变更信心 |
| 代码质量 | 20% | 影响维护成本 |
| CI/CD | 15% | 影响交付效率 |
| 文档 | 15% | 影响新人上手 |
| 安全 | 15% | 影响生产可用性 |
| 项目规模 | 5% | 不是越大越好 |
| 活跃度 | 5% | 反映项目生命周期 |
| 外部集成 | 5% | 生态系统成熟度 |

### 3.3 风险分级

对发现的问题按严重程度分级：

| 级别 | 标识 | 定义 | 示例 |
|:----:|------|------|------|
| 🔴 高 | 必须修复 | 可能导致生产事故或安全漏洞 | 核心模块 0 测试、有已知高危漏洞、构建失败 |
| 🟡 中 | 建议修复 | 影响开发效率或长期维护 | CHANGELOG 过时、单人开发总线风险、.unwrap() 过多 |
| 🟢 低 | 宜改进 | 锦上添花的优化项 | 缺少 Dockerfile、无 API 文档 |

---

## Step 4: 输出报告

### 报告格式

保存为 `<项目根目录>/maturity-report.md`。使用以下模板（严格遵守）：

```markdown
# 🔬 [项目名] 成熟度评估报告

> 评估日期：YYYY-MM-DD | 主语言：[语言] | 代码规模：[行数]
> 综合评分：★☆☆☆☆ ~ ★★★★★（X.X/5.0）— [一句话定性]

---

## 一、综合概览

[2-3 句话的总体评价，点出核心优势和核心短板]

### 成熟度雷达

[用 8 行 ASCII 文字绘制 8 轴雷达图，格式如下：]

```
        规模 ★★★★★
              /\
             /  \
    CI/CD   /    \  活跃度
    ★★★★  /      \  ★★★★★
          /        \
         /    ★★    \
        /   测试覆盖  \
       /              \
  文档 ★★★★ ────── ★★★★ 代码质量
              ★★★★
            外部集成

总评：[一句话]
最高维度：[维度名] 最低维度：[维度名]
```

---

## 二、8 维度详解

### 2.1 项目规模 ★★★★★

| 指标 | 数值 | 评价 |
|------|------|------|
| ... | ... | ... |

[如果需要，列出 Top 5 模块代码分布]

---

### 2.2 开发活跃度 ★★★★★

| 指标 | 数值 | 评价 |
|------|------|------|
| ... | ... | ... |

[包含近 30 天提交趋势 ASCII 图]

---

### 2.3 测试覆盖 ★★★★★

| 指标 | 数值 | 评价 |
|------|------|------|
| ... | ... | ... |

[包含各模块测试代码比表格]

⚠️ [如果有零测试模块，在此标注]

---

### 2.4 代码质量 ★★★★★

| 指标 | 数值 | 评价 |
|------|------|------|
| ... | ... | ... |

---

### 2.5 CI/CD 与 DevOps ★★★★★

| 指标 | 状态 |
|------|:--:|
| ... | ... |

---

### 2.6 文档 ★★★★★

| 指标 | 数值 | 评价 |
|------|------|------|
| ... | ... | ... |

---

### 2.7 安全 ★★★★★

| 指标 | 状态 |
|------|:--:|
| ... | ... |

---

### 2.8 外部集成与生态 ★★★★★

| 指标 | 状态 |
|------|:--:|
| ... | ... |

---

## 三、风险清单

### 🔴 高风险（必须修复）

1. **[风险标题]**：[具体描述 + 影响 + 建议修复方案]

### 🟡 中风险（建议修复）

1. **[风险标题]**：[具体描述 + 影响 + 建议修复方案]

### 🟢 改进建议

1. **[建议标题]**：[具体描述 + 预期收益]

---

## 四、改进路线图（可选）

如果发现 3+ 个高中风险，给出优先级排序的改进路线图：

| 优先级 | 改进项 | 预期工作量 | 预期收益 |
|:--:|------|:--:|------|
| 1 | ... | X 天 | 解决 N 个高/中风险 |
| 2 | ... | X 天 | ... |

---
```

### 输出后行为

1. 将报告保存到 `<项目根目录>/maturity-report.md`
2. 在对话中展示摘要（总体评分 + 风险数量 + 文件路径）
3. 询问用户是否需要深入分析某个维度

---

## 注意事项

### 通用原则

- **命令可复现**：报告中引用的每个数据都应来自一个可复现的命令。不要"估计"或"猜测"数值。
- **排除无关目录**：统计代码时永远排除 `target/`、`node_modules/`、`dist/`、`build/`、`.git/`、`worktrees/`
- **排除非核心项目**：`side-projects/`、`examples/`、`demo/` 中的代码默认不计入主项目统计，但需在报告中标注
- **失败不阻塞**：某个检查命令失败时，在报告中标注"未获取"，不要阻塞后续检查
- **区分 main 和子项目**：monorepo 中识别主项目，子项目单独统计

### 数据收集效率

- **所有 `Bash` 命令并行执行**：不要串行执行 10 个 `Bash` 调用。在一次响应中同时发出多个独立命令。
- **使用 `Glob` 而非 find**：找文件用 `Glob`，不用 `Bash` find
- **使用 `Grep` 而非 grep**：搜索内容用 `Grep`，不用 `Bash` grep
- **大输出用专用工具**：目录遍历用 `folder_operations`，不用 `ls -R`

### 评分公平性

- 刚创建 < 3 个月的项目：活跃度默认 +1 星（新项目不要求版本历史丰富）
- 单人项目：不因"总线风险"扣分（小型开源项目的合理状态），但仍需标注
- 非英语项目：文档语言不作为评分因子
- 已有测试但 CI 不跑：测试覆盖扣半星（测试不执行等于没测试）