@wwkit/harness 1.0.27 → 1.0.29

package/skills/jstest/references/config.md

@@ -0,0 +1,148 @@
+# jstest 测试代理配置清单
+
+> 本文件是测试代理的全局配置，agent 启动时首先读取，后续所有 skill 共享。
+
+## 依赖工具
+
+| name | check | required | install |
+|------|-------|----------|---------|
+| node | `node --version` | true | null（系统级工具，需手动安装） |
+| jest | `npx jest --version` | true | `pnpm add -D jest` 或 `npm install --save-dev jest` |
+| supertest | `node -e "require.resolve('supertest')"` | false | `pnpm add -D supertest` 或 `npm install --save-dev supertest` |
+
+## 环境检查
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| npm_project_check | true | 必须是 npm/pnpm 项目（package.json + node_modules/） |
+| install_retry | 3 | 插件安装失败重试次数 |
+
+## 超时配置
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| test_timeout_unit | 60 | 单元测试单用例超时（秒） |
+| test_timeout_integration | 300 | 集成测试单用例超时（秒） |
+
+## Loop 控制
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| outer_max | 3 | 外层 loop（coverage→create→execute）最大轮次 |
+| inner_max | 3 | 内层 loop（fix→execute）最大轮次 |
+
+## 测试指标 — 单元测试（unit）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| coverage_threshold | 90 | 覆盖率达标线 |
+| line_coverage_weight | 30 | 行覆盖率权重 |
+| branch_coverage_weight | 30 | 分支覆盖率权重 |
+| function_coverage_weight | 20 | 函数覆盖率权重 |
+| test_quality_weight | 20 | 用例质量权重 |
+
+## 测试指标 — 集成测试（integration）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| coverage_threshold | 70 | 覆盖率达标线 |
+| line_coverage_weight | 20 | 行覆盖率权重 |
+| branch_coverage_weight | 20 | 分支覆盖率权重 |
+| function_coverage_weight | 10 | 函数覆盖率权重 |
+| test_quality_weight | 50 | 用例质量权重（更重场景质量） |
+
+## 命名规则
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| test_root | tests | 测试根目录 |
+| dir_mapping_pattern | `tests/{type}/{package_module}` | 归一化仅去除 src/ 前缀，保留包名 |
+| report_dir_pattern | `{test_dir}/reports/{YYYYMMDD_HHMMSS}/` | 报告输出目录 |
+| report.test_report | `test_report.md` | 最终测试报告文件名 |
+| report.bug_list | `bug_list.md` | 源码 Bug 清单文件名 |
+| file.pattern | `{ModuleName}.test.js` | 测试文件命名 |
+| describe.pattern | `describe('ModuleName')` | describe 块命名（与被测模块名一致） |
+| test.pattern | `test('should {action} {expected}')` | 测试用例命名 |
+| setup_file.name | `jest.setup.js` | 共享 setup 文件名 |
+| setup_file.data_dir | `fixtures` | 测试数据目录名 |
+
+### 目录映射算法（jstest skill Step 1 唯一权威定义）
+
+> jstest skill 的 Step 1 直接引用本算法，不另行重复定义。
+
+当用户未显式指定测试目录时，agent 按以下步骤自动推导 `test_dir`：
+
+**输入**: `source_path`（源码路径），`test_type`（unit 或 integration）
+
+**Step 1: 归一化源码路径**
+
+按顺序执行：
+
+1. 文件 → 取父目录
+2. 绝对路径 → 转为相对路径（相对于项目根目录）
+3. 含 `..` → 先 resolve 为标准路径再继续
+4. 为 `.` 或空 → 报错"请提供子目录路径，如 src/mymodule"
+5. 去除开头的 `./`
+6. 去除开头的 `src/`（仅去除一次）
+7. 归一化后为空 → 报错"归一化后路径为空，请提供 src/ 下的子目录"
+
+**归一化规则**：仅去除 `src/` 前缀，**保留包名及子模块路径**。无 `src/` 前缀的路径（flat layout）保持原样。
+
+**Step 2: 映射**
+
+```
+test_dir = tests/{test_type}/{归一化路径}/
+```
+
+**Step 3: 验证与创建**
+
+- `tests/` 不存在 → 自动创建 `tests/{test_type}/` 目录结构
+- 映射目录不存在 → 自动创建，标记为全新模式（无已有测试）
+
+### 映射示例
+
+| 源码路径 | test_type | 归一化 | 自动推导 test_dir |
+|---------|-----------|--------|------------------|
+| `src/mymodule` | unit | `mymodule` | `tests/unit/mymodule/` |
+| `src/mypackage/sub` | unit | `mypackage/sub` | `tests/unit/mypackage/sub/` |
+| `src/mypackage/MyService.js` | unit | `mypackage` | `tests/unit/mypackage/` |
+| `src/mymodule` | integration | `mymodule` | `tests/integration/mymodule/` |
+| `lib/util` | integration | `lib/util` | `tests/integration/lib/util/` |
+| `mypackage/sub`（flat layout） | unit | `mypackage/sub` | `tests/unit/mypackage/sub/` |
+
+### 命名示例
+
+```
+源码路径:   src/mypackage/MyService.js
+模块名:     MyService
+测试目录:   tests/unit/mypackage/
+测试文件:   tests/unit/mypackage/MyService.test.js
+describe:   describe('MyService', () => { ... })
+test:       test('should return expected result when ...', () => { ... })
+```
+
+## 测试类型
+
+### unit（单元测试）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| dir | tests/unit | 测试目录 |
+| jest_test_category | unit | jest test category（describe 命名约定） |
+| mock_strategy | full | 全部 Mock 外部依赖 |
+| coverage_focus | line, branch, function | 覆盖率关注点 |
+| timeout | 60 | 单用例超时（秒） |
+| run_command | `node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --coverage` | ESM 项目运行命令 |
+| run_command_cjs | `npx jest --no-cache --coverage` | CommonJS 项目运行命令 |
+
+### integration（集成测试）
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| dir | tests/integration | 测试目录 |
+| jest_test_category | integration | jest test category（describe 命名约定） |
+| mock_strategy | minimal | 最少 Mock，真实调用 |
+| coverage_focus | scenario, flow | 覆盖率关注点 |
+| timeout | 300 | 单用例超时（秒） |
+| run_command | `node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --coverage` | ESM 项目运行命令 |
+| run_command_cjs | `npx jest --no-cache --coverage` | CommonJS 项目运行命令 |

package/skills/jstest/references/coverage-analyze.md

@@ -0,0 +1,247 @@
+> **原 skill**: `jstest-coverage-analyze`（已合并入 jstest）
+> **适用**: 测试代理外层 loop 的分析阶段，评估当前测试覆盖范围和质量。
+> **不适用**: 非 jest 项目、非覆盖率相关的代码分析。
+
+---
+
+# 覆盖率与质量分析
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **运行覆盖率**：执行 jest --coverage 生成 JSON 报告
+2. **解析覆盖率**：从 coverage-summary.json 提取行/分支/函数覆盖率
+3. **质量检查**：扫描测试文件检查质量维度
+4. **评分计算**：按评分规则计算总分
+5. **输出结果**：得分 + 未覆盖区域 + 改进建议
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target | 是 | string | 被测模块路径（如 src/mypackage） |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| report_dir | 是 | string | 报告输出目录（用于 coverage 输出路径） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 jstest-env-ensure 的配置对象 |
+| previous_score | 否 | number | 上一轮得分（用于无改进检测） |
+
+## 输出
+
+- 总分（0-100）
+- 各维度得分明细
+- 未覆盖文件/函数/分支列表
+- 改进建议
+- 是否达标的结论
+
+---
+
+## 阶段一：运行覆盖率
+
+**操作**：
+
+使用传入的 `test_dir` 运行覆盖率分析：
+
+```
+# unit 超时 60000ms，integration 超时 300000ms
+node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --coverage --coverageReporters=json-summary --coverageReporters=text --testTimeout={timeout} {test_dir}
+```
+
+**超时配置**：
+- test_type=unit → timeout=60000
+- test_type=integration → timeout=300000
+- 超时值来自 config.md 的 `test_timeout` 配置
+
+**覆盖率报告输出路径**：
+- jest 默认将覆盖率报告输出到 `coverage/` 目录
+- 完整路径：`{report_dir}/coverage/coverage-summary.json`
+
+**失败处理**：
+
+| 条件 | 动作 |
+|------|------|
+| jest 执行成功 | 进入阶段二 |
+| jest 有失败用例 | 仍然解析覆盖率（覆盖率基于已执行的用例），记录失败数 |
+| jest 执行错误（非测试失败） | 退出，输出错误信息 |
+
+---
+
+## 阶段二：解析覆盖率
+
+**输入**：`{report_dir}/coverage/coverage-summary.json` 文件
+
+**操作**：
+
+1. 读取 `coverage-summary.json`
+2. 提取 `total` 字段：
+   - `total.lines.total`, `total.lines.covered`, `total.lines.pct` → 行覆盖率
+   - `total.branches.total`, `total.branches.covered`, `total.branches.pct` → 分支覆盖率
+   - `total.functions.total`, `total.functions.covered`, `total.functions.pct` → 函数覆盖率
+3. 提取各文件条目：每个文件的覆盖率明细（key 为文件绝对路径）
+4. 识别未覆盖的文件、函数、分支
+
+**jest coverage-summary.json 格式**：
+
+```json
+{
+  "total": {
+    "lines": { "total": 100, "covered": 85, "skipped": 0, "pct": 85 },
+    "statements": { "total": 120, "covered": 100, "skipped": 0, "pct": 83.33 },
+    "functions": { "total": 20, "covered": 15, "skipped": 0, "pct": 75 },
+    "branches": { "total": 30, "covered": 20, "skipped": 0, "pct": 66.67 }
+  },
+  "/absolute/path/to/file.js": {
+    "lines": { "total": 50, "covered": 40, "skipped": 0, "pct": 80 },
+    "statements": { ... },
+    "functions": { ... },
+    "branches": { ... }
+  }
+}
+```
+
+**计算公式**：
+
+- 行覆盖率 = total.lines.pct（jest 已计算百分比）
+- 分支覆盖率 = total.branches.pct
+- 函数覆盖率 = total.functions.pct
+
+> **除零保护**：当 jest 报告中 pct 为 0 且 total 为 0 时（源码无分支/无函数/无语句），该项覆盖率记为 100%（满分）。
+> 这与 `scoring-rules.md` 的"分母为 0 时该项给满分"规则一致。
+
+---
+
+## 阶段三：质量检查
+
+**操作**：扫描传入的 `test_dir` 目录下所有测试文件（`*.test.js` / `*.test.ts`）
+
+### 检查项（按 test_type 加载对应权重）
+
+**unit 质量维度（20 分）**：
+
+| 维度 | 检查方法 |
+|------|---------|
+| 断言完整性(5) | 统计每个 test/it 回调函数内是否含 `expect(` 调用 |
+| 异常路径覆盖(5) | 源码中含 `throw`/`try` 的函数，测试中是否有 `toThrow` 或 `try-catch` |
+| 边界值覆盖(5) | 源码中含 `if`/`else` 的函数，测试用例数 ≥ 分支数（检查 `test.each`/`it.each`） |
+| 命名规范(5) | describe 名匹配 `^ModuleName$`，test/it 名匹配 `^should .+$` |
+
+**integration 质量维度（50 分）**：
+
+| 维度 | 检查方法 |
+|------|---------|
+| 场景完整性(15) | 核心业务场景是否都有对应测试（按源码公开导出方法数统计） |
+| 数据流验证(10) | 测试中是否验证了输入→处理→输出完整链路（含多步 expect） |
+| 断言完整性(10) | 每个 test/it 回调函数至少含 1 个 expect 调用 |
+| setup/teardown 使用(10) | 是否合理使用 `beforeEach`/`afterEach`/`beforeAll`/`afterAll` |
+| 命名规范(5) | describe 名匹配 `^ModuleName$`，test/it 名匹配 `^should .+$` |
+
+**通用规则**：
+- 分母为 0 时（无适用项），该项给满分
+- 超限封顶：`min(实际/阈值, 1.0)`
+
+---
+
+## 阶段四：评分计算
+
+**输入**：覆盖率数据 + 质量检查结果
+
+**操作**：按 `scoring-rules.md` 的评分规则计算总分
+
+**评分公式**：
+
+```
+总分 = 行覆盖率得分 + 分支覆盖率得分 + 函数覆盖率得分 + 质量维度得分
+
+单项得分 = min(实际值/阈值, 1.0) × 满分
+```
+
+**等级**：
+
+| 等级 | 分数 |
+|------|------|
+| A | 90-100 |
+| B | 80-89 |
+| C | 60-79 |
+| D | <60 |
+
+---
+
+## 阶段五：输出结果
+
+**输出格式**：
+
+```
+## 覆盖率与质量分析报告
+
+### 总分：XX / 100（等级：X）
+
+### 覆盖率明细
+| 维度 | 实际 | 阈值 | 权重 | 得分 |
+|------|------|------|------|------|
+| 行覆盖率 | XX% | XX% | XX | XX |
+| 分支覆盖率 | XX% | XX% | XX | XX |
+| 函数覆盖率 | XX% | XX% | XX | XX |
+
+### 质量明细
+| 维度 | 达标/应测 | 权重 | 得分 |
+|------|----------|------|------|
+| 断言完整性 | X/X | X | X |
+| 异常路径覆盖 | X/X | X | X |
+| 边界值覆盖 | X/X | X | X |
+| 命名规范 | X/X | X | X |
+
+### 未覆盖区域
+| 文件 | 未覆盖函数 | 未覆盖行数 |
+|------|-----------|-----------|
+| src/xxx.js | funcA, funcB | 15 |
+
+### 改进建议
+1. 为 funcA 添加正向测试用例
+2. 为 funcB 的 if 分支添加边界值用例
+3. ...
+
+### 结论
+- 得分 XX，阈值 XX → [达标/未达标]
+- [未达标] → 建议进入用例创建阶段
+```
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| score ≥ coverage_threshold | 输出"达标"，流程结束 |
+| score < coverage_threshold | 输出未覆盖区域，交给 Step 5（按 references/case-create.md 执行） |
+| score ≤ previous_score（非首轮） | 输出"无改进"，提前退出外层 loop |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| coverage-summary.json 不存在 | 退出，提示覆盖率报告未生成 |
+| 目标模块路径无效 | 退出，提示路径不存在 |
+| 测试目录不存在 | 输出 0 分，提示需要创建测试目录 |
+| 测试目录为空（无 *.test.js/*.test.ts 文件） | 输出 0 分，将全部源码文件列为未覆盖，提示需要先创建用例 |
+| jest 超时 | 退出，提示测试执行超时，建议检查是否有 hang 住的用例或增加 timeout 配置 |
+
+> **注意**：agent 在首轮检测到 test_dir 为空时会跳过本技能，直接进入 case-create。
+> 此场景仅作为兜底保护，确保即使 agent 未跳过也不会崩溃。
+
+## 一定要做
+
+1. 必须使用传入的 test_dir 运行覆盖率分析，并根据 test_type 选择评分权重
+2. 覆盖率数据必须来自 coverage-summary.json，不做主观判断
+3. 质量检查必须通过文件扫描，不猜测
+4. 分母为 0 时该项给满分（覆盖率维度和质量维度均适用）
+5. 必须输出未覆盖区域清单（供 case-create 使用）
+6. 非首轮时必须检查是否无改进
+
+## 一定不要做
+
+1. 不要混合 unit 和 integration 的覆盖率数据
+2. 不要修改源码或测试文件
+3. 不要跳过质量检查只看覆盖率
+4. 不要主观判断测试质量，只做可程序化检查的判断
+5. 不要忽略 coverage-summary.json 解析错误

package/skills/jstest/references/env-ensure.md

@@ -0,0 +1,210 @@
+> **原 skill**: `jstest-env-ensure`（已合并入 jstest）
+> **适用**: 测试代理启动前的环境准备，任何需要验证 jest 运行环境的场景。
+> **不适用**: 非 npm/pnpm 管理的 JS/TS 项目、非测试相关的环境检查。
+
+---
+
+# 环境检查与配置加载
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **项目检查**：验证是否为 npm/pnpm 管理的 JS/TS 项目
+2. **依赖检查与安装**：检查依赖包，未安装则自动安装
+3. **安装验证**：重新验证所有依赖是否可用
+4. **jest 配置检查**：检查 jest 配置、模块系统、TypeScript 支持
+5. **配置加载**：读取配置清单，输出给调用方
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| 无 | - | - | 自动检测当前工程 |
+
+## 输出
+
+- 配置对象（包含 dependencies、loops、metrics、naming、types 等字段）
+- 环境检查报告
+
+---
+
+## 阶段一：项目检查
+
+**操作**：
+
+1. 检查 `package.json` 是否存在且包含 `"name"` 字段
+2. 检查 `node_modules/` 目录是否存在
+3. 运行 `node --version` 验证 node 可用
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| package.json 存在且 node_modules 存在 | 进入阶段二 |
+| package.json 不存在 | **直接退出**，提示"当前 agent 仅支持 npm/pnpm 项目，未找到 package.json" |
+| node_modules 不存在 | **直接退出**，提示"当前 agent 仅支持 npm/pnpm 项目，未找到 node_modules 目录，请先运行 npm install 或 pnpm install" |
+| node --version 失败 | **直接退出**，提示"node 不可用，请先安装 Node.js" |
+
+---
+
+## 阶段二：依赖检查与安装
+
+**输入**：读取 `config.md` 的 dependencies 清单
+
+**操作**：
+
+1. 逐个执行 `check` 命令验证是否已安装
+2. 对未安装的依赖，执行 `install` 命令
+3. 安装失败 → 重试（最多 3 次，由 config 的 `env.install_retry` 控制）
+4. `install` 为 null 的依赖（如 node）→ 跳过安装，仅检查
+
+**包管理器检测**：
+
+- 检查 `pnpm-lock.yaml` 存在 → 使用 `pnpm` 命令
+- 检查 `package-lock.json` 存在 → 使用 `npm` 命令
+- 检查 `yarn.lock` 存在 → 使用 `yarn` 命令
+- 都不存在 → 默认使用 `npm`
+
+**重试逻辑**：
+
+```
+for each dependency:
+  if check passes:
+    mark as installed
+  else if install is null:
+    mark as missing (system-level, cannot auto-install)
+  else:
+    retry_count = 0
+    while retry_count < install_retry:
+      run install command (pnpm add -D <pkg> or npm install --save-dev <pkg>)
+      if check passes:
+        mark as installed
+        break
+      retry_count += 1
+    if still not installed:
+      mark as failed
+```
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部已安装 | 进入阶段三 |
+| 有 required 依赖安装失败 | **直接退出**，列出失败的依赖 |
+| 有非 required 依赖安装失败 | 记录警告，继续 |
+
+---
+
+## 阶段三：安装验证
+
+**操作**：对所有依赖重新执行 `check` 命令
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部通过 | 进入阶段四 |
+| 有 required 依赖未通过 | **直接退出**，列出未通过的依赖 |
+| 有非 required 依赖未通过 | 记录警告，继续 |
+
+---
+
+## 阶段四：jest 配置检查
+
+**操作**：
+
+1. 检查 jest 配置来源：
+   - `package.json` 的 `"jest"` 字段是否存在
+   - `jest.config.js` 是否存在
+   - `jest.config.cjs` 是否存在
+   - `jest.config.mjs` 是否存在
+   - `jest.config.ts` 是否存在
+2. 模块系统检测：
+   - 读取 `package.json` 的 `"type"` 字段
+   - `"type": "module"` → ESM 项目，运行 jest 需加 `--experimental-vm-modules` 标志
+   - 无 `"type"` 字段或 `"type": "commonjs"` → CommonJS 项目
+3. TypeScript 检测：
+   - 检查 `tsconfig.json` 是否存在
+   - 若存在 → 检查 jest transform 配置（`ts-jest`、`@swc/jest`、`babel-jest` with `@babel/preset-typescript`）
+   - 若 transform 未配置 → 记录警告，提示"检测到 TypeScript 项目但未配置 jest transform，测试可能失败"
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| jest 配置存在 | 进入阶段五 |
+| jest 配置不存在 | 记录警告，提示"未找到 jest 配置，将使用默认配置" |
+| ESM 项目未配置 transform | 记录警告，提示"ESM 项目运行 jest 需要 --experimental-vm-modules" |
+| TypeScript 项目未配置 transform | 记录警告，提示"TypeScript 项目需要配置 jest transform" |
+
+---
+
+## 阶段五：配置加载
+
+**操作**：
+
+1. 读取 `config.md`
+2. 解析配置项：dependencies、env、loops、metrics（unit + integration）、naming、types
+3. 输出配置对象给调用方（agent）
+
+**输出格式**：
+
+```
+## 环境检查报告
+
+### 项目检查
+- package.json: ✓
+- node_modules: ✓
+- node: ✓ (vXX.X.X)
+
+### 依赖检查
+| 依赖 | 状态 | 备注 |
+|------|------|------|
+| node | ✓ 已安装 | 系统级 |
+| jest | ✓ 已安装 | - |
+| supertest | ✗ 未安装 | 可选，跳过 |
+
+### jest 配置检查
+- 配置来源: package.json "jest" 字段 / jest.config.js / jest.config.cjs
+- 模块系统: ESM / CommonJS
+- TypeScript: ✓ (ts-jest) / ✗ (非 TS 项目)
+- 运行命令: node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache (ESM)
+            npx jest --no-cache (CommonJS)
+
+### 配置已加载
+- coverage_threshold: 90 (unit) / 70 (integration)
+- outer_max: 3
+- inner_max: 3
+- test_root: tests
+```
+
+---
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 非 npm/pnpm 项目 | 直接退出，提示仅支持 npm/pnpm 项目 |
+| required 依赖安装失败（重试 3 次） | 退出，列出失败依赖 |
+| required 依赖验证不通过 | 退出，列出未通过依赖 |
+| config.md 不存在或格式错误 | 退出，提示配置文件缺失 |
+| 非项目特定错误 | 记录警告，不阻断流程 |
+
+## 一定要做
+
+1. 必须先检查 npm/pnpm 项目结构，不满足直接退出
+2. 依赖检查必须读取 config.md 的 dependencies 清单
+3. 安装失败必须重试，重试次数由 config 控制
+4. 安装后必须重新验证
+5. 必须检查 jest 配置、模块系统和 TypeScript 支持
+6. 最终输出完整的配置对象给调用方
+
+## 一定不要做
+
+1. 不要跳过 npm/pnpm 项目检查
+2. 不要安装 install 为 null 的依赖（系统级工具）
+3. 不要忽略 required 依赖的失败
+4. 不要修改 config.md 文件内容
+5. 不要预设任何项目特定的依赖或配置
+6. 不要修改 jest 配置文件（除非直接导致失败）