claude-code/docs/jira/WSL-CI-RUNBOOK.md

WSL CI Runbook — feat/autofix-pr-test 本地验证

目的：在 WSL Ubuntu 把 fork CI 流水线（typecheck / test / build / coverage）整套跑通， 绕过 Bun 1.3.12 + Windows panic，算出本次 PR 的 patch coverage 真实数字。

当前分支：feat/autofix-pr-test（3 个 squash commit，HEAD = 0c5f1104） 目标基线：origin/feat/autofix-pr（HEAD = b5659846） 改动规模：67 文件 / +5738 / -385

---

0. 一次性准备（已装可跳过）

WSL 里运行：

# 检查 Bun
bun --version
# 期望 ≥ 1.3.11，建议升级到 1.3.12 与 Windows 主机对齐
bun upgrade

# 检查 Node（用于 nvm 兼容，不是必须，但 npm 触发 lifecycle 会用到）
node --version       # v24.x

# 安装 lcov 工具集（patch coverage 报告需要）
sudo apt update
sudo apt install -y lcov

# 验证 lcov
lcov --version       # 期望 ≥ 1.14
genhtml --version

---

1. 把代码同步到 WSL ext4（强烈推荐，IO 快 5-10×）

跨文件系统访问 /mnt/e/... 走 9P 协议非常慢，会让 bun install 和 bun test 慢得不可接受。

# 在 WSL 用户家目录建工作区
mkdir -p ~/work
cd ~/work

# 选项 A：clone fork 远端 + checkout 我们的 branch（推荐，一次到位）
git clone https://github.com/amDosion/claude-code-bast.git claude-code-bast
cd claude-code-bast
# 添加 unraid / gitea 远端（可选，跟 Windows worktree 远端一致）
# git remote add upstream https://github.com/claude-code-best/claude-code.git

# 我们的 squash 是本地 commit，origin 还没有 → 需要从 Windows 同步
# 选项 A.1：先在 Windows 推到 origin
#   (在 Windows PowerShell)  cd E:\Source_code\Claude-code-bast-autofix-pr-test
#   git push -u origin feat/autofix-pr-test
# 然后在 WSL 拉
git fetch origin
git checkout -b feat/autofix-pr-test origin/feat/autofix-pr-test

# 选项 B：直接 rsync 从 Windows worktree（不走远端）
# rsync -aH --delete --exclude=node_modules --exclude=dist --exclude=.squash-tmp \
#   /mnt/e/Source_code/Claude-code-bast-autofix-pr-test/ \
#   ~/work/claude-code-bast/

# 验证当前 HEAD
git log --oneline -3
# 期望前 3 行：
#   0c5f1104 feat(login): allow switch / replace / remove of workspace API key
#   0f3412b6 feat(commands): /local-memory + /local-vault interactive panels + path render fixes
#   acbbd5e2 feat(local-wiring): wire LocalMemoryRecall + VaultHttpFetch tools end-to-end

---

2. 安装依赖

cd ~/work/claude-code-bast

# 跳过 Chrome MCP 安装（CI 也跳过）
export CLAUDE_CODE_SKIP_CHROME_MCP_SETUP=1

bun install --frozen-lockfile
# 期望：~30s 完成，无 lockfile 冲突
# 若报 "lockfile mismatch" → 先在 Windows 跑 bun install 同步 lockfile，commit 再 push

---

3. 跑 CI 完整流水线（与 .github/workflows/ci.yml 一致）

# Step 1: typecheck
bun run typecheck
echo "exit=$?"
# 期望 exit=0（0 errors）

# Step 2: 全量测试 + lcov 覆盖率（CI 这一步用 grep/sed 过滤噪音，本地直接看完整输出）
mkdir -p coverage
bun test --coverage --coverage-reporter lcov --coverage-dir coverage 2>&1 | tee /tmp/test-output.log | tail -10

# 验证 lcov.info 生成
test -s coverage/lcov.info && echo "✓ lcov.info present ($(wc -l < coverage/lcov.info) lines)"
grep -c '^SF:' coverage/lcov.info
# 期望：~370 SF entries（每个 source file 一个）

# Step 3: build
bun run build:vite
echo "exit=$?"
# 期望 exit=0；产物在 dist/，预期看到几个 chunk: REPL / sentry / loadAgentsDir 等

预期结果汇总：

Step	命令	期望
typecheck	bun run typecheck	exit=0
test	bun test --coverage ...	≈4944 pass / ≈138 fail（pre-existing flaky）/ 1 error；lcov.info ≈ 数 MB
build	bun run build:vite	exit=0；dist/ 产物

138 fail 是 pre-existing 的 Bun mock pollution 抖动，不是我们引入的。 要确认这一点，本地已有 baseline 对比：基线 138 fail，当前 139 fail，其中 27 vs 27 对称差异 = 测试顺序导致。 真实新引入失败 = 0。

---

4. 算 patch coverage（仅本次 PR 改动行的覆盖率）

GitHub 上的 Codecov 默认会自己算 patch coverage（基于 PR diff），但本地想先看真实数字。

4.1 提取 patch 文件清单

cd ~/work/claude-code-bast
mkdir -p coverage/patch

# 67 个改动文件
git diff origin/feat/autofix-pr..HEAD --name-only > coverage/patch/files.txt
wc -l coverage/patch/files.txt   # 期望 67

# lcov 只关心源代码文件（排除 docs/scripts/test 文件）
grep -E '\.(ts|tsx)$' coverage/patch/files.txt \
  | grep -vE '__tests__|\.test\.' \
  | grep -vE '^scripts/' \
  | grep -vE '^docs/' \
  > coverage/patch/prod-files.txt
wc -l coverage/patch/prod-files.txt   # 大约 35-40 个 prod 源文件

4.2 用 lcov 提取 patch 子集

# 把 67 文件清单转成 lcov --extract 接受的 pattern 列表
PATTERNS=$(awk '{printf "%s ", $0}' coverage/patch/prod-files.txt)

# extract 仅 patch 文件的覆盖数据
lcov --extract coverage/lcov.info $PATTERNS \
     --output-file coverage/patch/patch.info \
     --rc lcov_branch_coverage=0 \
     --ignore-errors unused 2>&1 | tail -10

# 看 summary
lcov --summary coverage/patch/patch.info
# 输出会有：
#   lines......: XX.X% (NN of MM lines)
#   functions..: XX.X% (NN of MM functions)

4.3 生成 HTML 详细报告（可选但很直观）

genhtml coverage/patch/patch.info \
        --output-directory coverage/patch/html \
        --title "feat/autofix-pr-test patch coverage" \
        --quiet

# 在 Windows 浏览器里打开
echo "file:///mnt/$(realpath coverage/patch/html/index.html | sed 's|^/mnt/c|c|;s|/|\\|g' | sed 's|^c|c:|')"
# 或简单：
# explorer.exe coverage/patch/html  # 直接调出 Windows 资源管理器

4.4 解读结果

• lines% ≥ 80% → 合格，可以推 PR
• lines% 60-80% → 可以推，PR 描述里说明哪些文件难测（UI / Ink TUI / barrel exports）
• lines% < 60% → 看 4.3 HTML 报告，找出未覆盖的关键 prod 文件，针对性补单测后再推

不是 prod 代码但会拉低数字的"假阳性"：

• tests/mocks/toolContext.ts — 是测试 fixture，本身不应算入 patch
• packages/builtin-tools/src/index.ts — 仅是 export barrel
• src/commands/*/index.ts — 仅注册 + USAGE 字符串，逻辑在 launch*.ts
• UI 组件：*.tsx 用 React Compiler，难直接单测

如果 patch coverage 数字偏低，但全是上述类型，可以在 PR 描述里说明。

---

5. 把结果带回 Windows（汇报用）

# 关键摘要复制到 Windows 可见的位置
{
  echo "# CI Run Summary — $(date -Iseconds)"
  echo ""
  echo "## Branch"
  git log --oneline origin/feat/autofix-pr..HEAD
  echo ""
  echo "## Test Results"
  grep -E "^ [0-9]+ (pass|fail|error)" /tmp/test-output.log | tail -4
  echo ""
  echo "## Coverage"
  lcov --summary coverage/patch/patch.info 2>&1 | grep -E "lines|functions|branches"
  echo ""
  echo "## Build"
  echo "build:vite — see dist/ in WSL ext4"
} | tee /mnt/e/Source_code/Claude-code-bast-autofix-pr-test/.wsl-ci-summary.md

# 然后回到 Windows，cat .wsl-ci-summary.md 可以看到

---

6. 故障排查

6.1 bun install 卡在 postinstall

CI 用环境变量 CLAUDE_CODE_SKIP_CHROME_MCP_SETUP=1 跳过 Chrome MCP setup。本地一定也要 export 它，否则 postinstall 会等几分钟。

6.2 bun test --coverage panic（Bun 1.3.12 + Windows 已知问题）

WSL 是 Linux 内核，不会 panic。如果在 WSL 也 panic，先 bun upgrade 到最新版。

6.3 lcov.info 里没有任何 SF: 行

可能是 bun 测试一启动就 crash。先不带 --coverage 跑一次 bun test 确认测试套件本身能跑。

6.4 patch coverage 显示 0%

最常见原因：lcov --extract 的 PATTERNS 路径跟 lcov.info 里的 SF 路径不匹配。 检查：

head -50 coverage/lcov.info | grep '^SF:'
# 看 SF 路径是绝对路径还是相对路径，调整 prod-files.txt 让它一致

6.5 跨文件系统执行很慢

确保你在 ~/work/ 而不是 /mnt/e/... 跑命令。pwd 应该是 /home/USERNAME/work/claude-code-bast，不是 /mnt/e/...。

6.6 git push 报 "no upstream"

git push -u origin feat/autofix-pr-test

---

7. 完成后做什么？

跑完拿到 patch coverage 数字后，回到 Windows 这边继续 /prp-pr 流程：

1. 数字 ≥ 80%：直接推 PR --base feat/autofix-pr，让 GitHub Codecov 复算并 PR review。
2. 数字 60-80%：PR 描述里写明哪些文件没测、为什么。
3. 数字 < 60%：补关键单测（重点：login.tsx、permissionValidation.ts、sanitize.ts），再回到 step 3 重跑。

不要为了凑数硬补 UI 组件单测——Ink TUI + React Compiler 的组件本身很难有意义地测，强测会写出脆弱、跟实现细节耦合的测试。

---

附录 A：CI workflow 实际命令对照

.github/workflows/ci.yml 里的步骤（runs-on: ubuntu-latest）：

- bun install --frozen-lockfile
  env: CLAUDE_CODE_SKIP_CHROME_MCP_SETUP=1
- bun run typecheck
- bun test --coverage --coverage-reporter lcov --coverage-dir coverage
  | grep -vE '^\s*\(pass|skip\)' | sed '/^.*\/__tests__\/.*:$/d' | cat -s
- # codecov-action upload (PR from same repo only)
- bun run build:vite

本地完全等价：忽略 grep | sed | cat 输出修饰，那只是减噪。

附录 B：Codecov 默认行为

仓库没有 codecov.yml，Codecov 用默认配置：

• Project coverage status check：informational（不会 fail PR）
• Patch coverage status check：informational（不会 fail PR）
• 没有 hard 阈值

所以 100% 不是必须。但 patch coverage 越高，reviewer 越放心。