# covgate **Repository Path**: wxzzhj/covgate ## Basic Information - **Project Name**: covgate - **Description**: 面向 AI 编码工作流的覆盖率门禁:客户端必须 100%,服务端至少 95%;无法覆盖的代码必须写明原因才能豁免。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-25 - **Last Updated**: 2026-10-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CovGate > 面向 AI 编码工作流的覆盖率门禁:**客户端必须 100%,服务端至少 95%;无法覆盖的代码必须写明原因才能豁免。** CovGate 是一个零依赖的 Node.js 工具。它不产生覆盖率,而是把测试、覆盖率报告、源码范围、豁免说明和阈值合成一道**可机器执行、可审计、可进 CI 的门禁**;同时提供本地可视化工作台和 HTML 覆盖率查看页。 ## 可视化工作台 在项目根目录运行: ```bash npx --no-install covgate ui ``` 默认打开 `http://127.0.0.1:4318`,也可以指定项目、端口或关闭自动打开浏览器: ```bash npx --no-install covgate ui --root D:/Projects/my-app --port 4319 --no-open ```  运行后在工具内直接查看报告:  工作台支持: - 指定客户端、服务端源码路径,路径有自动检测的建议列表; - 从项目 `package.json` 脚本中**下拉选择测试命令**,不需要手敲; - 单独指定客户端/服务端命令,自动生成临时配置并运行; - 客户端、服务端可以分别设置覆盖率报告路径,适配前后端分开产出的项目; - 工具内嵌覆盖率报告:左侧文件列表,中间源码,绿色已覆盖、白色未覆盖; - 运行前检查测试文件;没有测试时禁用运行,并提供可复制的 **AI 补测任务**,避免生成空报告; - 测试命令失败或没有生成报告时,直接显示日志和原因,不展示空结果页; - 不覆盖项目已有的 `covgate.config.json`,运行结果仍写入 `.covgate/`。 `covgate ui` 只监听本机回环地址,适合本地使用;CI 和 Agent 仍用 `covgate run`。 ## 为什么需要它 “让 AI 写完后自动跑测试”通常会坏在几个地方: | 常见问题 | CovGate 的处理 | | --- | --- | | AI 只运行了部分测试,没跑覆盖率 | 每个 scope 配置测试命令;非零退出码直接失败 | | 客户端覆盖率 99.9% 也放过 | 客户端所有指标硬性 100%,比较精确计数,不做四舍五入 | | 服务端统一写成 90% | 服务端底线 95%,配置不能低于底线 | | 没被 import 的新文件完全不出现在报告里 | `sources.include` 是源码事实来源;缺报告即失败 | | 用 `istanbul ignore next` 隐藏代码 | 原生忽略注释一律失败,必须换成带原因的 `covgate-ignore-*` | | 加一个“TODO”注释就豁免 | 原因长度、占位词、owner、过期时间、失效区间都会被审计 | | 测试没执行却读到上次的报告 | 按报告 mtime/size 检测陈旧产物 | | 豁免散落在代码里,评审看不到 | 报告 JSON/Markdown 列出全部豁免、排除、原因和状态 | ## 硬规则 1. **profile = client**:行、语句、函数、分支覆盖率都必须 **100%**(LCOV 不提供语句指标时,该指标为 N/A,其余仍为 100%)。 2. **profile = server**:行、语句、函数、分支覆盖率都必须 **≥ 95%**(LCOV 不提供语句指标时,该指标为 N/A)。 3. 配置只能**提高**门槛,不能降低。客户端写 `99` 会在加载配置时直接报错。 4. 每个 scope 必须声明 `sources.include`,且每个源码文件都必须出现在覆盖率报告中,或拥有一个带说明的文件级豁免。 5. 覆盖不到的代码必须使用 `covgate-ignore-*` 指令,提供具体原因;可使用 `owner`、`expires`、`ticket` 元数据。 6. 原生忽略注释(`istanbul ignore`、`c8 ignore`、`v8 ignore`、`node:coverage ignore`)一律失败。 7. 豁免没有移除任何未覆盖代码时视为 stale;默认失败。 8. 测试命令失败、报告缺失、报告陈旧、JSON 损坏都返回非零退出码。 ## 工作流 ```text covgate run ├─ 执行 scope 的测试命令(捕获输出,超时可控) ├─ 检查覆盖率报告是否是本次新生成的 ├─ 载入报告:Istanbul JSON / LCOV ├─ 枚举 sources.include 中的全部源码,找“漏报文件” ├─ 扫描 covgate 豁免、原生忽略、配置排除 ├─ 按“声明起点行”从统计中移除已说明的代码段 ├─ 精确比较阈值(covered * 10000 >= thresholdBp * total) └─ 输出文本 / JSON / Markdown,退出 0/1/2/3 ``` ## 安装 ### 从 npm registry 安装(推荐) 包已发布到 npm:[covgate](https://www.npmjs.com/package/covgate),当前 latest 为 **0.3.3**。 ```bash npm install --save-dev covgate npx --no-install covgate setup ``` > npm 上可能还能看到 `0.0.0-stage`,它是暂存发布占位版本,不会作为 `latest` 被安装,可以忽略。 ### 从 Gitee 安装(源码 / 镜像) ```bash # HTTPS npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git # 或 SSH npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git npx --no-install covgate setup ``` ### 本地目录安装 ```bash npm install --save-dev file:D:/Projects/DSH默认工作区/covgate npx --no-install covgate setup ``` 如果不想安装,也可以直接调用: ```bash node D:/Projects/DSH默认工作区/covgate/bin/covgate.js run ``` ### 安装后自动配置 安装后运行: ```bash npx --no-install covgate setup ``` setup 会: - 检测 npm/pnpm/yarn/bun 和已有测试框架; - **没有测试框架时询问是否安装 Vitest + @vitest/coverage-v8**,选择是则自动安装; - 写入 `coverage:gate`、`test:coverage` 脚本和 `covgate.config.json` 起始配置; - Electron 项目自动生成 `client`(`src/**`,100%)和 `server`(`desktop/**`,95%)两个 scope; - 生成 `AGENTS.md`、Agent 门禁脚本、GitHub Actions(如存在 `.github/`)和 `.gitignore` 条目;生成规则默认要求补测试,整体排除 UI/main/核心模块必须人工批准,未批准不得改范围或提交。 **CovGate 不生成测试,也不补测试。** 行为变更的测试必须由项目自己补;没有测试时 `test:coverage` 会直接失败,不会生成空覆盖率来蒙混过关。 如果 setup 找不到覆盖率命令,不会静默跳过:会打印具体的 `test:coverage` 建议、`--test-command` 用法和 GUI 命令。已有 `covgate.config.json` 会保留,并在输出中说明现有 scopes。 `postinstall` 也会尝试同样的流程,但 **npm 11.19+ 默认不执行依赖安装脚本**。如果安装时没有弹出询问,直接运行 `npx covgate setup` 即可;详细说明见 [安装与自动配置](docs/setup.md)。 ### 在 CovGate 仓库中开发 ```bash cd covgate npm test node bin/covgate.js --help ``` 要求 Node.js **20.11+**。没有运行时依赖,不需要构建。 ## 快速开始 ### 1. 创建 `covgate.config.json` 可以从 [templates/covgate.config.json](templates/covgate.config.json) 复制并修改。最小结构如下: ```json { "$schema": "./node_modules/covgate/schema/covgate.schema.json", "version": 1, "scopes": { "client": { "profile": "client", "label": "客户端", "commands": [ { "name": "客户端测试与覆盖率", "run": "npm --prefix web run test -- --coverage" } ], "coverage": { "format": "istanbul", "paths": ["web/coverage/coverage-final.json"] }, "sources": { "include": ["web/src/**/*.{ts,tsx,js,jsx}"] }, "exclude": [ { "pattern": "web/src/**/*.test.{ts,tsx,js,jsx}", "reason": "测试文件,不是产品运行时代码", "owner": "web-platform" }, { "pattern": "web/src/**/*.d.ts", "reason": "类型声明文件,没有运行时代码", "owner": "web-platform" } ] }, "server": { "profile": "server", "label": "服务端", "commands": [ { "name": "服务端测试与覆盖率", "run": "npm --prefix api run test -- --coverage" } ], "coverage": { "format": "lcov", "paths": ["api/coverage/lcov.info"] }, "sources": { "include": ["api/src/**/*.{ts,js}"] }, "exclude": [ { "pattern": "api/src/**/*.test.{ts,js}", "reason": "测试文件,不是产品运行时代码", "owner": "api-platform" } ] } }, "waivers": { "minReasonLength": 8, "requireOwner": true, "stale": "fail", "expiry": "fail" }, "reports": { "dir": ".covgate", "formats": ["json", "markdown", "html"] } } ``` 路径都相对于**配置文件所在目录**。测试命令默认也在该目录执行,可用每个命令的 `cwd` 覆盖。 ### 2. 让测试工具生成报告 CovGate 读取现成报告,不绑定测试框架。 | 生态 | 建议格式 | 产物 | | --- | --- | --- | | Jest | Istanbul JSON | `coverage/coverage-final.json` | | Vitest + v8/istanbul | Istanbul JSON 或 LCOV | `coverage/coverage-final.json` / `coverage/lcov.info` | | c8 / nyc | Istanbul JSON 或 LCOV | `coverage/coverage-final.json` / `coverage/lcov.info` | | pytest-cov | LCOV | `coverage/lcov.info` | | 生成 lcov 的其他语言工具 | LCOV | `lcov.info` | 示例: ```bash # Jest jest --coverage --coverageReporters=json --coverageReporters=lcov # Vitest(在 vitest.config 中设置 coverage.reporter = ['json', 'lcov']) vitest run --coverage # pytest-cov pytest --cov=app --cov-report=lcov:coverage/lcov.info ``` 一个 scope 只能使用一种格式;不要在同一 scope 内混用 Istanbul 和 LCOV。 ### 3. 运行门禁 ```bash npx --no-install covgate run ``` 手动检查已有报告: ```bash npx --no-install covgate check --json ``` 校验配置: ```bash npx --no-install covgate validate ``` ## 命令与退出码 | 命令 / 选项 | 作用 | | --- | --- | | `covgate setup` | 检测/安装测试框架,生成配置和 AI 编码代理接入。 | | `covgate run` | 执行测试命令,然后检查覆盖率。默认命令。 | | `covgate check` | 不执行测试,只检查已有报告。 | | `covgate validate` | 只校验配置和排除说明。 | | `covgate ui` | 启动本地可视化覆盖率工作台。 | | `--root