Coverage

把 tool/ 那套 Bash + 内嵌 Python 的 JaCoCo 分支覆盖率能力，抽成 Python 全栈内核 + MCP server， 定位「Java 分支级、按测试类、能指到未覆盖行的 agent 覆盖率反馈器」，填补现有 MCP （test-coverage-mcp 只给%、se333 instruction/方法/全量）的精确缺口。

进度

• M0 解析层 ✅ csv/xml/surefire + 未覆盖分支行，搬成可单测纯函数（对 optaplanner 真实报告快照锁定）。
• M1 端到端 ✅ runner 复刻 maven 覆盖率链路；与 bash run-module-test.sh 对同一 case 逐字段一致（含未覆盖行）。
• M2 MCP 壳 ✅ FastMCP 暴露 coverage_check，返回紧凑 JSON。
• M3 按包自动收集 + JSON 瘦身 ✅ --package fanya/schedule 一条测整包；uncovered 的 file 相对模块路径省 token。
• M4 去耦合 ✅ 砍掉对 tool/env.sh、git bash、IDEA 集成参数的依赖；maven 发现 + 配置走纯 Python（env.py + jacov.toml）；跨平台 subprocess 直调 mvn。已独立 git 仓 + CI + entry points。

结构

src/jacov/
  model.py    数据模型 + 阈值兼容（80 / 0.8）
  jacoco.py   解析 jacoco.csv / jacoco.xml / surefire（对齐 run-module-test.sh 三段）
  runner.py   复刻 maven 覆盖率链路（复用 tool/env.sh 的 Maven 环境）
  check.py    编排 + 人读输出 + 结构化组装（check_coverage / build_result）
  server.py   FastMCP server（coverage_check 工具）
tests/        14 个用例（解析层 11 + 组装层 3），fixture 取自 optaplanner 真实报告

跑测试

cd coverage-mcp
python -m pytest -q          # 免安装（pyproject 配 pythonpath=src）

命令行用（人类用法）

适用于 PowerShell / CMD / Git Bash。命令一行写完最省事，不要用 bash 的 \ 换行。

第 0 步：装一次（只做一次）

pip install -e coverage-mcp

装完后 python -m jacov.check 在任何目录都能用——不用设 PYTHONPATH，也不用 cd 进 coverage-mcp。

最常用：测一个业务包（自动收集该包的测试类 + 业务类）

在项目根目录执行：

python -m jacov.check --module-dir fanyajwproject-course-v2\fanyajwproject-course-v2 --package fanya/schedule --min-branch 80

--package fanya/schedule 会自动找该包下所有 *Test.java 当测试、所有 .java 当业务类，不用手列一长串。

或者：手动指定测试类 / 业务类

python -m jacov.check --module-dir optaplanner-jxjy\optaplanner-jxjy --tests TeacherDayOfWeekParseStrategyTest --cover CommonMethods --min-branch 80

参数

参数	必填	含义
--module-dir	是	模块目录（含 pom.xml）；相对当前目录或绝对路径都行
--package	与 --tests 二选一	业务包（如 fanya/schedule），自动收集测试类 + 业务类
--tests	与 --package 二选一	测试类，逗号分隔（如 FooTest,BarTest）
--cover	否	卡覆盖率的业务类，逗号分隔；不填 = 整模块汇总
--min-branch	否	最低分支覆盖率，写 80 或 0.8；默认 0（只看不卡）
--no-compile	否	跳过编译（代码已编译时更快）
--no-reuse	否	每个测试类用独立 JVM（严格隔离，多测试类时慢）

看懂输出

测试结果汇总     → 总数 / 通过 / 失败
分支覆盖率汇总   → 每个业务类 [PASS/FAIL] 分支总数 / 已覆盖 / 未覆盖 / 覆盖率
未完全覆盖分支   → 文件:行号 + MISS（全没覆盖）/ PARTIAL（只覆盖一半）+ 源码

退出码：全通过且达标 = 0，否则 = 1（可用于 CI / 脚本判断成败）。

⚠️ PowerShell 用户注意

• 别抄 bash 写法：PYTHONPATH=src python ...（PS 不支持这种前缀赋值）和行尾 \ 换行（PS 续行符是反引号 `）——都会报 Missing expression after unary operator '--'。
• 装好包后一行命令最干净，什么前缀都不用加。

配置（jacov.toml，可选）

不放 jacov.toml 时走默认：maven 从 PATH / MAVEN_HOME 自动发现、JaCoCo 0.8.11、JDK17 add-opens、settings 和本地仓用 maven 默认（~/.m2）。

需要自定义时，把 jacov.example.toml 复制为 jacov.toml（已被 .gitignore，因含机器相关路径）：

[maven]
home = "/path/to/maven3"            # 本机没有 mvn/mvnw 时，指向 maven 安装根（其下有 bin/mvn）
settings = "/path/to/settings.xml"  # 私有仓 / 镜像 / 凭据
local_repo = "/path/to/.m2/repository"
[jacoco]
version = "0.8.11"
excludes = "com.sun.proxy.*"        # instrument 排除（动态代理类，避免污染覆盖率）
[test]
add_opens = ["java.base/java.lang"] # fork 测试 JVM 的 --add-opens（JDK17+）

查找顺序：从 --module-dir 上溯 → 包目录。

全量纯测试（像 Jenkins，不跑覆盖率）

只想跑测试看通过/失败、不要覆盖率（更快），用 jacov.runtests：

# 全量：模块下所有 *Test.java（相当于 mvn test）
python -m jacov.runtests --module-dir fanyajwproject-course-v2\fanyajwproject-course-v2

# 只测某个包 / 某几个类
python -m jacov.runtests --module-dir fanyajwproject-course-v2\fanyajwproject-course-v2 --package fanya/schedule
python -m jacov.runtests --module-dir fanyajwproject-course-v2\fanyajwproject-course-v2 --tests FooTest,BarTest

• 跑的过程实时显示编译（Building/Compiling）和每个测试类（Running XxxTest / Tests run: N），不会静默——能看到跑到哪、卡在哪。
• 结尾 Jenkins 式汇总：套件 / 用例 / 通过 / 失败 / 错误 / 跳过 + 失败套件清单；退出码 0（全过）/ 1（有失败）。
• ⚠️ 全量可能慢（course-v2 ~1900 用例、~3 分钟，大头是少数连外部/DB 的集成测试）；只验证某块用 --package 秒级。

项目编译（Python 版）

jacov.compile 把旧 tool/compile.sh 的项目编译策略迁到 Python，适合 CLI 和 MCP 共用。

# 默认双层项目：clean → compile
python -m jacov.compile fanyajwproject-course-v2 --workspace-root C:\Users\lin\IdeaProjects

# shared-jar：clean → install -Dmaven.test.skip=true
python -m jacov.compile fanyajw-shared-jar --workspace-root C:\Users\lin\IdeaProjects

# rpc：按旧脚本 7 步串联 clean/install/compile
python -m jacov.compile fanyajwproject-rpc --workspace-root C:\Users\lin\IdeaProjects

装包后也可以直接用：

jacov-compile fanyajwproject-course-v2 --workspace-root C:\Users\lin\IdeaProjects

编译日志统一写到 <workspace-root>/target/maven-logs/，避免 mvn clean 删除模块自身 target 时把正在写入的日志删掉。执行过程中会打印当前步骤、总步骤数、已耗时、单步开始/结束时间和单步耗时。

Git Bash 下 Windows 路径请用正斜杠，例如 --workspace-root C:/Users/lin/IdeaProjects。不要写 C:\Users\lin\IdeaProjects，反斜杠会被 Git Bash 当转义符吞掉。

性能与开关

覆盖率合并成单条 maven 命令（prepare-agent → 测试 → report），避免多次 JVM 冷启动；多测试类默认复用 fork JVM。

开关（CLI 反向）	默认	说明
compile_first（--no-compile）	True	True 含增量编译（测最新代码）；False 用 surefire:test 跳过编译
reuse_forks（--no-reuse）	True	True 多测试类复用同一 fork JVM（快 ~4x）；False 每类独立 JVM（严格隔离）

实测 course-v2 schedule 包 21 测试：拆 3 次 maven + 独立 JVM 会超时 → 合并 1 条 + 复用 fork 12s（覆盖率逐字段一致）。 若怀疑测试间静态状态污染导致覆盖率异常，用 --no-reuse 切独立 JVM 对照。

接入 Claude Code（MCP）

1. 装包：pip install -e coverage-mcp（带 mcp 依赖）。
2. 在项目 .mcp.json 的 mcpServers 里加一个 jacov 条目（command 用本机 python.exe 绝对路径，与装包的解释器一致；已有别的 server 就并列加）：

   {
     "mcpServers": {
       "jacov": {
         "command": "<python.exe 绝对路径>",
         "args": ["-m", "jacov.server"]
       }
     }
   }
   

3. 重启 Claude Code（或 /mcp 重连）。之后可调 coverage_check(module_dir, tests, cover, min_branch)。

注：coverage_check 首次调用会真跑 maven（编译 + 测试 + JaCoCo），耗时分钟级。 返回紧凑 JSON：status / tests / coverage / uncovered（行号+MISS·PARTIAL+源码） / reports。