dsh-code-coverage

Readme

# dsh-code-coverage

[![CI](https://github.com/SleepEggTart/dsh-code-coverage/actions/workflows/ci.yml/badge.svg)](https://github.com/SleepEggTart/dsh-code-coverage/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/dsh-code-coverage)](https://www.npmjs.com/package/dsh-code-coverage)
[![license](https://img.shields.io/npm/l/dsh-code-coverage)](LICENSE)
[![node](https://img.shields.io/node/v-lts/dsh-code-coverage)](package.json)

> AI 给你写的代码，到底有多少在被测试保护着？

解析 [DeepSeek Harness](https://github.com/nicepkg/deepseek-harness)（DSH）session 日志，归因 AI 写了哪些文件，再叠加 [c8](https://github.com/bcoe/c8) 覆盖率数据，产出 **「AI 代码 vs 人工代码」覆盖率对比**、未测 AI 文件风险清单与信任分。

这不是又一个覆盖率工具——c8 已经解决了覆盖率本身。我们的护城河是**归因**：通过解析 DSH session 日志，精确知道哪些文件被 AI 碰过，这是 Qodo、Diffblue 等外部工具做不到的。

## 真实项目数据

一个实际项目的归因结果（17 个 DSH session）：

| 指标 | AI 代码 | 人工代码 |
|------|---------|----------|
| 行数 | 870 | 9,772 |
| 覆盖率 | **68%** | 5% |

**信任分：68 / B**

AI 生成的代码覆盖率反而更高——因为 AI 写代码的同时把测试也写了。而 9,772 行人工代码，覆盖率只有 5%。

## 安装

### 方式一：一键安装（推荐）

```bash
# Windows
git clone https://github.com/SleepEggTart/dsh-code-coverage.git
cd dsh-code-coverage
.\install-plugin.ps1

# Mac/Linux
git clone https://github.com/SleepEggTart/dsh-code-coverage.git
cd dsh-code-coverage
chmod +x install.sh && ./install.sh
```

### 方式二：作为 DSH 插件安装（npm）

```bash
# 安装到 DSH web profile（dsh 官方插件安装方式）
dsh plugin --profile web add dsh-code-coverage

# 重启 DSH
dsh web
```

### 方式三：手动安装（本地开发）

```bash
git clone https://github.com/SleepEggTart/dsh-code-coverage.git
cd dsh-code-coverage
npm install
npm run build

# 打包并安装到 DSH web profile（版本号以 npm pack 实际输出为准）
npm pack
dsh plugin --profile web add ./dsh-code-coverage-0.1.1.tgz

# 重启 DSH
dsh web
```

> 注意：DSH 不读取 `~/.dsh/config.yml` 之类的配置文件来加载插件。
> 插件统一通过 `dsh plugin --profile <name> add <包>` 安装到对应 profile。

**前提条件**：
- Node.js ≥ 18
- 本机已安装 DeepSeek Harness（`~/.dsh` 目录存在）
- 项目中存在 `package.json`

## 快速开始（CLI 独立使用）

```bash
# 安装 CLI（独立于 DSH 插件使用）
npm install -g dsh-code-coverage

# 分析当前目录
dsh-code-coverage

# 分析指定项目
dsh-code-coverage --cwd /path/to/your/project

# 覆盖自动探测的测试命令
dsh-code-coverage --test-command "npm test -- --pool=threads"

# 输出 JSON（供脚本/插件消费）
dsh-code-coverage --json

# 生成 HTML 报告
dsh-code-coverage --html report.html

# 限制"高危未测文件"显示条数
dsh-code-coverage --top 5

# 定位高危未测 AI 文件，生成补测试计划（写入 dsh-fix-plan.json）
dsh-code-coverage fix --top 3

# 按计划补完测试后，与上次存档对比验证提升效果
dsh-code-coverage verify
```

### 参数说明

| 参数 | 说明 |
|------|------|
| `--cwd <dir>` | 目标项目目录（默认：当前工作目录） |
| `--test-command <cmd>` | 覆盖自动探测的测试命令 |
| `--dsh-root <dir>` | DSH 根目录（默认：`~/.dsh`，主要用于测试） |
| `--json` | 输出 JSON 格式 |
| `--html <file>` | 生成 HTML 报告到指定文件路径 |
| `--top <n>` | 高危未测文件显示条数（默认：10） |
| `--help` | 查看帮助 |
| `--version` | 查看版本 |

### 输出示例

```
╭─────────────────────────────────────────────────────╮
│  dsh-code-coverage — AI 代码信任报告                │
╰─────────────────────────────────────────────────────╯

  项目:         /path/to/project
  Session 数:   17 个 DSH session 已归因
  测试命令:     vitest --pool=threads

  ┌──────────────┬────────┬──────────┐
  │              │   行数 │ 覆盖率   │
  ├──────────────┼────────┼──────────┤
  │  AI 代码     │    870 │     68%  │
  │  人工代码    │  9,772 │      5%  │
  └──────────────┴────────┴──────────┘

  信任分: 68 / B

  ⚠ 高危未测 AI 文件（Top 3）:
    1. src/hooks/userealsendmutation.ts — 250 行未覆盖
    2. ...
```

## 作为 DSH 插件使用

将本包安装为 DSH 插件后，Agent 在会话中可直接调用三个工具，无需手动运行 CLI：

```bash
# 安装到 DSH web profile（不要用 npm install -g，全局安装不会进入 DSH）
dsh plugin --profile web add dsh-code-coverage

# 重启 DSH
dsh web
```

| 工具 | 用途 |
|---|---|
| `code_coverage_check` | 分析 AI 代码覆盖率，产出信任分卡片 |
| `code_coverage_fix` | 定位高危未测 AI 文件，生成补测试计划（写入 `dsh-fix-plan.json`） |
| `code_coverage_verify` | 补测后重跑管线，与上次存档对比验证闭环效果 |

对话闭环示例：说"帮我提高这个项目的信任分"，Agent 会依次调用 check（发现）→ 按计划补测试 → verify（验证提升）。

## 工作原理

三步自动化完成：

1. **归因** — 解析 `~/.dsh/sessions/` 下的 session 日志，识别 AI 创建或修改过的文件。支持 `write`、`edit`、`str_replace_editor` 三类工具调用，包含 subagent 子会话。

2. **覆盖率** — spawn `c8 --all` 收集测试套件的 V8 覆盖率数据。`--all` 标志确保从未被测试 import 的文件也会出现在报告中——AI 写了但从未被加载的文件恰恰是最危险的。

3. **交叉分析** — 将归因结果与覆盖率数据交叉比对，产出：
   - AI 代码 vs 人工代码的行数与覆盖率对比
   - 未测 AI 文件风险清单（按未覆盖行数排序）
   - 信任分（0–100 分，附字母等级）

## 已知限制

提 issue 前请先阅读这些边界：

- **vitest 3 `pool=forks` 屏蔽覆盖率。** vitest 3 默认 `pool: forks`，会阻止 Node 的 `NODE_V8_COVERAGE` 传递到子进程，导致覆盖率恒为 0。解决方法：加 `--pool=threads`（如 `npm test -- --pool=threads`）。这是 vitest 的问题，不是本工具的 bug。

- **Shell 命令写文件不解析。** `pwsh`/`bash` 通过输出重定向（`>` / `>>`）写入文件的调用，MVP 不做解析。目前仅归因 `write`、`edit`、`str_replace_editor` 三种工具调用。

- **仅支持 JS/TS。** c8 的覆盖率采集针对 JavaScript 和 TypeScript，不支持其他语言。

- **文件级归因，非行级。** 只要文件被 AI 碰过，整个文件就算 AI 生成。行级归因计划在 v0.3 实现。

- **人工事后修改不重新分类。** 如果 AI 写了一个文件，人工后来改过，该文件仍算 AI 生成。这是有意为之的简化。

- **测试命令按空白拆分。** `--test-command` 按空白字符拆分参数，不支持带引号的复杂命令。建议传入 wrapper 脚本。

## 关于覆盖率数字

覆盖率是一个有用的**起点指标，不是质量判决**。

2026 年社区已有反面案例：91% 行覆盖率的项目在实践中零 bug 检出——因为被覆盖的行是 trivial 的，而关键路径仍处于测试盲区。

信任分高，只意味着 AI 生成的文件有测试，不代表测试质量高。用这个工具来**发现盲区**，而不是证明质量。

## Roadmap

| 版本 | 状态 | 说明 |
|------|------|------|
| **v0.1** | ✅ 已发布 | 文件级归因、c8 覆盖率叠加、信任分、终端 + JSON + HTML 输出 |
| **v0.1.1** | ✅ 已发布 | `fix` / `verify` 补测试闭环（插件三工具 + CLI 子命令）、行级 gap 精确指引（补测计划定位到"第 X-Y 行"） |
| **v0.2** | 计划中 | 趋势追踪 — 基于 `.dsh-coverage/history.jsonl` 运行存档展示覆盖率与信任分变化趋势 |
| **v0.3** | 计划中 | 行级归因（当前仅支持文件级） |

## 开发

```bash
# 克隆仓库
git clone https://github.com/SleepEggTart/dsh-code-coverage.git
cd dsh-code-coverage

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 类型检查
npm run typecheck
```

## License

[MIT](LICENSE)