# 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 ``` ![CovGate 可视化工作台](docs/ui-viewer.png) 运行后在工具内直接查看报告: ![CovGate 工作台内嵌覆盖率报告](docs/ui-result.png) 工作台支持: - 指定客户端、服务端源码路径,路径有自动检测的建议列表; - 从项目 `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 ` | `ui` 的项目根目录,默认当前目录。 | | `--port ` | `ui` 的本地端口,默认 4318。 | | `--no-open` | `ui` 启动后不自动打开浏览器。 | | `--config ` | 指定配置文件。 | | `--scope ` | 只检查指定 scope,可重复或逗号分隔。 | | `--json` | stdout 只输出 JSON;过程日志走 stderr。 | | `--changed` | 只门禁/展示本次 Git 变更文件;默认对比 `HEAD`。 | | `--base ` | 配合 `--changed` 指定 Git 对比版本,例如 `HEAD^`。 | | `--no-files` | 不写 `.covgate/report.json` / `report.md` / `report.html`。 | | `--report-dir ` | 覆盖报告目录(相对当前目录)。 | | `--verbose` | 实时转发测试命令输出。 | | `--color` / `--no-color` | 控制彩色输出。 | setup 的完整选项见 [安装与自动配置](docs/setup.md)。 | 退出码 | 含义 | | --- | --- | | `0` | 通过 | | `1` | 覆盖率或审计不通过 | | `2` | 配置 / 用法错误 | | `3` | 测试失败、报告缺失/损坏/陈旧、覆盖率无法读取 | `check` 不执行命令,也不检查报告是否新鲜,适合人工复查已有产物;CI 和 AI 代理应使用 `run`。 CI 只需要判断退出码是否为 0。 ### 只检查 Git 变更文件 ```bash # 工作区相对 HEAD 的新增/修改(包含未跟踪的新文件) npx --no-install covgate run --changed # 检查最新一次提交相对父提交的变更 npx --no-install covgate run --changed --base HEAD^ # PR / CI:相对目标分支 npx --no-install covgate run --changed --base origin/main ``` `--changed` 会把每个 scope 的源码范围收窄到变更文件,并只对这些文件计算覆盖率、展示文件和执行 100%/95% 门槛;未变更文件不会因为本次门禁被误判。HTML 报告也只列出变更文件。 它**不会自动筛选测试用例**。测试命令仍是项目在 `commands` 中配置的命令(通常是全量测试),CovGate 只负责覆盖率范围。测试命令自己决定跑哪些测试,才能避免漏掉依赖变更。 如果变更文件全部不在任何 scope 的 `sources.include` 内,CovGate 会失败而不是虚假通过。 ## 配置参考 ### profile `client` 和 `server`。scope 名称正好是 `client` / `server` 时可以省略;其他名称必须显式声明。 门槛底线: | profile | lines | statements | functions | branches | | --- | --- | --- | --- | --- | | `client` | 100 | 100 | 100 | 100 | | `server` | 95 | 95 | 95 | 95 | `thresholds` 可以省略(使用底线),也可以提高。降低会被配置校验拒绝。 ### coverage - `format`:`auto`、`istanbul`、`lcov`。 - `paths`:报告文件、目录或 glob,相对于配置目录。目录模式只识别 `coverage-final.json`(Istanbul)和 `.info` / `.lcov`(LCOV);自定义文件名请用显式路径或 glob。 同一 scope 内混用格式会失败。LCOV 不提供语句覆盖率,因此该指标显示为 N/A,不参与门禁(行、函数、分支仍会检查)。 ### sources.include **必填。** 这是 CovGate 能找到“漏测文件”的关键。 - 必须覆盖所有要门禁的产品源码。 - 测试文件、生成代码、类型声明等不在统计范围内的文件,应在 `exclude` 中带原因排除。 - 如果覆盖率工具自己配置了 exclude,请同步到 CovGate 的 `exclude`;否则 CovGate 会认为文件漏报。 - 报告里出现、但不在 `sources.include` 中的文件会被忽略,并在报告中给出 warning。不要依赖这个 warning 代替正确的 include。 ### exclude 文件级排除,每条都必须写 `reason`,可选 `owner`、`expires`、`ticket`。 ```json { "pattern": "web/src/generated/**", "reason": "由 OpenAPI 生成,仓库不手工维护,生成器已有独立测试", "owner": "api-platform", "expires": "2027-03-31" } ``` - 没有匹配到任何源码文件的排除规则会失败(避免规则腐烂)。 - 说明同样受长度、占位词和过期策略约束。 - 排除文件会让它完全退出统计;这是高影响操作,建议在 CODEOWNERS 中保护配置文件。 ### waivers | 字段 | 默认 | 说明 | | --- | --- | --- | | `minReasonLength` | 8 | 原因最少字符数 | | `requireOwner` | false | 是否要求 owner | | `stale` | `fail` | 豁免没有移除未覆盖代码时:`fail` / `warn` | | `expiry` | `fail` | 过期豁免:`fail` / `warn` | 原生忽略注释没有开关,始终失败。 ### reports - `dir`:输出目录,默认 `.covgate`。 - `formats`:`json`、`markdown`、`html`。 ## 写豁免:不可达代码的唯一方式 ### 1. 下一行 ```js // covgate-ignore-next-line: 平台灰度开关在 v1 永不开启,代码仅保留兼容路径 | owner=web-platform | expires=2027-06-30 export function legacyPath() { // ... } ``` ### 2. 单行(注释和代码同一行) ```js const generatedPlaceholder = 1; // covgate-ignore-line: 由代码生成器插入的占位语句,运行时不执行 | owner=codegen ``` ### 3. 代码块 ```js // covgate-ignore-start: 桌面外壳专用桥接,Web 运行时不会进入 | owner=desktop function nativeBridge() { // ... } // covgate-ignore-end ``` ### 4. 整文件 ```js // covgate-ignore-file: OpenAPI 生成文件,仓库不手工维护,生成流程有独立测试 | owner=api-platform | expires=2027-01-31 ``` ### 原因怎么写 可以写: > 平台保证 `process.platform` 为 `win32` 时不会进入此分支;v1 只支持 Linux 服务端。 不可以写: > unreachable > TODO > 无法覆盖 原因应说明**为什么这段代码无法被执行到**,而不是“我不想测”。占位词、过短说明、缺少 owner(如果启用)都会失败。 ### 豁免的生命周期 - 如果豁免区间没有移除任何未覆盖代码,默认失败。补了测试后请删除旧豁免。 - `expires` 到期默认失败。 - 覆盖区间重叠会失败,因为无法判断哪条说明对哪段代码负责。 - 文件级豁免与行级豁免不能混用。 - 所有豁免都会进入报告,供人工复核。 - `owner` 和 `expires` 不是装饰:推荐在团队配置中开启 `requireOwner`,并设置到期日。 ## 防止“假覆盖率” CovGate 是流程门禁,不是魔法。它做了这些约束: 1. **源码范围可枚举**:`sources.include` 没覆盖到的文件、没被测试加载的文件会失败。 2. **报告必须新鲜**:不会拿上一次的覆盖率结果糊弄。 3. **原生 ignore 被禁止**:不能绕过 CovGate 的说明检查。 4. **豁免不可静默**:所有原因、状态、过期时间都在报告里。 5. **门槛不可降低**:客户端 100、服务端 95 写死在代码里。 6. **精确比较**:`19/20` 是 95%,`18/20` 是 90%,不会因为显示四舍五入而误判。 仍然需要人类负责的部分: - 原因是否真实; - 测试断言是否有效(空测试也能产生覆盖率); - `covgate.config.json` 是否被滥用(建议 CODEOWNERS 保护); - 测试命令本身是否可信(配置里的命令会通过 shell 执行)。 ## AI 编码代理接入 运行 `npx covgate setup` 会自动生成 AGENTS、Agent 脚本和 CI 工作流。CovGate 本身不会监听文件保存;它是一道可被代理、Git hook 和 CI 调用的门禁。推荐三层: 1. **代理完成条件**:在 `AGENTS.md` 中要求任何代码修改后执行 `covgate run`,退出码 0 才能结束。 2. **代理 Stop hook / pre-commit**:在代理停止前或提交前自动执行,把 stderr/JSON 反馈给代理。 3. **CI required check**:最终阻止未通过门禁的合并。 现成片段: - [AGENTS.md 片段](templates/AGENTS.md.snippet.md) - [代理 Stop hook 脚本](templates/agent-stop-hook.sh) - [GitHub Actions 工作流](templates/github-actions-coverage.yml) - [pre-commit 示例](templates/pre-commit) - [.gitignore 片段](templates/gitignore) - [AI 工作流说明](docs/ai-workflow.md) 推荐给代理的命令: ```bash npx --no-install covgate run --json ``` stdout 是纯 JSON,代理可以读取 `status`、`scopes[].failingFiles`、`issues` 和 `commands`;过程日志在 stderr,不会污染 JSON。 ## 报告 每次运行默认写: - `.covgate/report.json`:机器可读,包含 scope 指标、失败文件、逐行未覆盖、行命中、全部豁免、排除、命令、退出码。 - `.covgate/report.md`:人类/评审可读的审计报告。 - `.covgate/report.html`:自包含网页查看器;左侧文件列表,中间源码,已覆盖行绿色背景、未覆盖行白色背景、非可执行行灰色。 打开网页: ```powershell start .covgate\report.html ``` macOS 用 `open .covgate/report.html`,Linux 用 `xdg-open .covgate/report.html`。 ![CovGate 覆盖率查看页:左侧文件列表,中间源码,绿色已覆盖、白色未覆盖](docs/coverage-viewer.png) 文本输出示例: ```text CovGate · 覆盖率门禁 v0.3.3 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s ✗ 客户端 [client/client] 未通过 行 97.50% (39/40, 目标 100%) ✗ · 语句 97.50% ... · 函数 100.00% ... · 分支 100.00% ... web/src/legacy.ts 行: 42, 43 结果: 未通过 JSON 报告: .covgate/report.json HTML 报告: .covgate/report.html ``` 建议把 `.covgate/` 加入 `.gitignore`。报告是本次运行的产物,不是源码。 ## 项目结构 ```text covgate/ bin/covgate.js CLI 入口 bin/covgate-postinstall.js 安装时检测/配置 src/ cli.js 执行编排 setup/ 测试框架检测、自动安装、AI 接入生成 config.js 严格配置校验与产品底线 scope.js 源码范围、排除、豁免审计 annotations.js covgate-ignore 解析 reason.js 原因质量/过期检查 gate.js 精确阈值比较 coverage/ Istanbul JSON / LCOV 适配 report/ JSON / Markdown / 文本报告 process.js 子进程、超时、输出捕获 reports.js 报告发现与陈旧检测 schema/ 配置 JSON Schema templates/ AI、CI、pre-commit、示例配置 docs/ 安装、设计与 AI 工作流 test/ Node.js 内置测试 ``` ## 限制 - 只内置 Istanbul JSON 和 LCOV 两种格式。其他格式可转换为 LCOV,或新增 adapter。 - 覆盖率不等于测试质量;CovGate 不能判断断言是否有效。 - 原因文本的“真实性”无法自动验证,只能通过 owner、到期日、stale 检查和人工评审约束。 - 配置文件可执行 shell 命令,必须视为代码来评审。 - 目前按整个 scope 统计,不支持“只看改动行”。大型遗留项目可以先通过带原因的排除规则缩小范围,再逐步扩大 `sources.include`。 ## 开发 ```bash cd covgate npm test ``` 测试覆盖:配置底线、glob、Istanbul/LCOV 解析与合并、豁免语法与审计、精确阈值、命令执行、陈旧报告、漏报文件、JSON 纯度、Markdown 输出、setup 检测与自动配置等(56 个测试)。 ## 设计文档 更完整的设计取舍、威胁模型和扩展方式见 [docs/design.md](docs/design.md)。 ## License MIT