covgate 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CovGate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,503 @@
-# Temporary Holding Version
+# CovGate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 面向 AI 编码工作流的覆盖率门禁：**客户端必须 100%，服务端至少 95%；无法覆盖的代码必须写明原因才能豁免。**
+
+CovGate 是一个零依赖的 Node.js CLI。它不产生覆盖率，而是把测试、覆盖率报告、源码范围、豁免说明和阈值合成一道**可机器执行、可审计、可进 CI 的门禁**。
+
+## 为什么需要它
+
+“让 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
+```
+
+## 安装
+
+### 在线安装（Gitee）
+
+```bash
+npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
+npx --no-install covgate setup
+```
+
+也可以使用 SSH：
+
+```bash
+npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
+```
+
+### 从 npm registry 安装
+
+包名是 `covgate`。发布到 npm 后：
+
+```bash
+npm install --save-dev covgate
+npx --no-install covgate setup
+```
+
+发布需要 npm 登录：`npm login && npm publish`。
+
+### 本地目录安装
+
+```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` 起始配置；
+- 生成 `AGENTS.md`、Agent 门禁脚本、GitHub Actions（如存在 `.github/`）和 `.gitignore` 条目。
+
+`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"]
+  }
+}
+```
+
+路径都相对于**配置文件所在目录**。测试命令默认也在该目录执行，可用每个命令的 `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` | 只校验配置和排除说明。 |
+| `--config <path>` | 指定配置文件。 |
+| `--scope <name>` | 只检查指定 scope，可重复或逗号分隔。 |
+| `--json` | stdout 只输出 JSON；过程日志走 stderr。 |
+| `--no-files` | 不写 `.covgate/report.json` / `report.md`。 |
+| `--report-dir <path>` | 覆盖报告目录（相对当前目录）。 |
+| `--verbose` | 实时转发测试命令输出。 |
+| `--color` / `--no-color` | 控制彩色输出。 |
+
+setup 的完整选项见 [安装与自动配置](docs/setup.md)。
+
+| 退出码 | 含义 |
+| --- | --- |
+| `0` | 通过 |
+| `1` | 覆盖率或审计不通过 |
+| `2` | 配置 / 用法错误 |
+| `3` | 测试失败、报告缺失/损坏/陈旧、覆盖率无法读取 |
+
+`check` 不执行命令，也不检查报告是否新鲜，适合人工复查已有产物；CI 和 AI 代理应使用 `run`。
+
+CI 只需要判断退出码是否为 0。
+
+## 配置参考
+
+### 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`。
+
+## 写豁免：不可达代码的唯一方式
+
+### 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`：人类/评审可读的审计报告。
+
+文本输出示例：
+
+```text
+CovGate · 覆盖率门禁 v0.2.0
+模式 执行测试并检查 · 配置 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
+```
+
+建议把 `.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

package/bin/covgate-postinstall.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runPostinstall } from "../src/setup/index.js";
+
+const root = process.env.INIT_CWD || process.cwd();
+try {
+  await runPostinstall({ root });
+} catch (error) {
+  process.stderr.write(
+    "[covgate] 安装后提示失败：" + (error instanceof Error ? error.message : String(error)) + String.fromCharCode(10)
+  );
+  process.stderr.write("[covgate] 可稍后运行 npx covgate setup。" + String.fromCharCode(10));
+}
+process.exitCode = 0;

package/bin/covgate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+const exitCode = await main(process.argv.slice(2));
+process.exitCode = exitCode;