covgate 0.2.0 → 0.2.1

package/README.md

@@ -46,30 +46,29 @@ covgate run
 
 ## 安装
 
-### 在线安装（Gitee）
+### 从 npm registry 安装（推荐）
+
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.2.1**。
 
 ```bash
-npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
+npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-也可以使用 SSH：
+> npm 上可能还能看到 `0.0.0-stage`，它是暂存发布占位版本，不会作为 `latest` 被安装，可以忽略。
 
-```bash
-npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
-```
+### 从 Gitee 安装（源码 / 镜像）
 
-### 从 npm registry 安装
+```bash
+# HTTPS
+npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
 
-包名是 `covgate`。发布到 npm 后：
+# 或 SSH
+npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
 
-```bash
-npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-发布需要 npm 登录：`npm login && npm publish`。
-
 ### 本地目录安装
 
 ```bash
@@ -96,8 +95,11 @@ 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` 条目。
 
+**CovGate 不生成测试，也不补测试。** 行为变更的测试必须由项目自己补；没有测试时 `test:coverage` 会直接失败，不会生成空覆盖率来蒙混过关。
+
 `postinstall` 也会尝试同样的流程，但 **npm 11.19+ 默认不执行依赖安装脚本**。如果安装时没有弹出询问，直接运行 `npx covgate setup` 即可；详细说明见 [安装与自动配置](docs/setup.md)。
 
 ### 在 CovGate 仓库中开发
@@ -439,7 +441,7 @@ stdout 是纯 JSON，代理可以读取 `status`、`scopes[].failingFiles`、`is
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.2.0
+CovGate · 覆盖率门禁 v0.2.1
 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s
 
 ✗ 客户端 [client/client] 未通过

package/docs/ai-workflow.md

@@ -30,6 +30,7 @@ npx --no-install covgate setup
 - 任何代码修改完成后，必须运行 `npx --no-install covgate run --json`；退出码 0 才能说完成。
 - 退出码 1：补测试或修实现；2：修配置；3：修测试命令/报告。不要绕过。
 - 禁止降低 covgate.config.json 中的门槛、扩大 exclude、删除豁免检查来让门禁通过；这些改动必须由人类评审。
+- **行为变更必须新增或更新覆盖该行为的真实测试**；门禁失败不能作为完成理由，也不能用 `--passWithNoTests`、空报告或 ignore 绕过。
 - 禁止 istanbul ignore / c8 ignore / v8 ignore / node:coverage ignore。
 - 确实不可达的代码使用 covgate-ignore-next-line / start/end / file，写具体原因、owner 和 expires。
 - 新增或修改的源码必须出现在覆盖率报告中；sources.include 是范围事实来源。

package/docs/setup.md

@@ -2,36 +2,27 @@
 
 ## 在线安装
 
-### 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
-```
-
-安装完成后运行一次：
+### npm registry（推荐）
 
 ```bash
+npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-### npm registry
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.2.1**。
 
-包名是 `covgate`。发布到 npm 后可以直接：
+> `0.0.0-stage` 是 npm 暂存发布产生的占位版本，不会被 `npm install covgate` 选中，可以忽略。
+
+### Gitee（源码 / 镜像）
 
 ```bash
-npm install --save-dev covgate
-npx --no-install covgate setup
-```
+# HTTPS（公开仓库）
+npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
 
-发布命令（需要 npm 登录）：
+# 或 SSH
+npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
 
-```bash
-npm login
-npm publish
+npx --no-install covgate setup
 ```
 
 ### 从本地目录安装
@@ -47,7 +38,7 @@ npm 11.19+ 默认不执行依赖的 `postinstall`，会显示类似：
 
 ```text
 npm warn install-scripts 1 package has install scripts not yet covered by allowScripts
-npm warn install-scripts   covgate@0.2.0 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.2.1 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：
@@ -70,7 +61,7 @@ npm warn install-scripts   covgate@0.2.0 (postinstall: node bin/covgate-postinst
 3. 添加 `npm scripts`：
    - `coverage:gate`：`covgate run`
    - `test:coverage`：Vitest/Jest 的 JSON + LCOV 覆盖率命令
-4. 生成 `covgate.config.json`（单 scope 起始配置；已存在则不覆盖）：
+4. 生成 `covgate.config.json`（普通项目单 scope；Electron 自动生成 client + server；已存在则不覆盖）：
 
    ```json
    {
@@ -93,6 +84,8 @@ npm warn install-scripts   covgate@0.2.0 (postinstall: node bin/covgate-postinst
    - 若已有 `CLAUDE.md`、`.cursor`、`.github/copilot-instructions.md`，同步写入对应说明。
 6. 输出下一步命令。
 
+> **CovGate 不生成测试，也不补测试。** setup 只配置测试框架和门禁；本次行为变更的测试必须由项目自己补。没有测试时 `test:coverage` 会直接失败（已移除 `--passWithNoTests`），不会产生可蒙混过关的空覆盖率。
+
 ## setup 选项
 
 | 选项 | 作用 |
@@ -122,21 +115,30 @@ npx covgate setup --no-install --no-config
 npx covgate setup --profile client --source "web/src/**/*.{ts,tsx}"
 ```
 
-## 生成的是单 scope
+## 生成的 scope
 
-为了不猜测复杂仓库结构，setup 只生成一个 scope：
+普通项目只生成一个 scope：
 
-- 项目有 `src/` 或 `app.js` 时自动选源码；
-- 有 `index.html`、React/Vue/Svelte 等依赖时选 `client`；
+- 有源码目录时自动选择源码（优先 `src/`，其次 `app.js`、`app/`、`lib/`）；
+- 有根目录或 `src/index.html`、React/Vue/Svelte 等依赖、Electron 时选 `client`；
 - 否则选 `server`。
 
-全栈项目需要手工在 `covgate.config.json` 增加第二个 scope，或对两个子项目分别运行 setup。生成配置后请先运行：
+Electron 项目会生成两个 scope：
+
+- `client`（profile=client）：`src/**` 等渲染进程源码，目标 100%；
+- `server`（profile=server）：`desktop/**` 主进程/预加载源码，目标 95%。
+
+两个 scope 共用同一个测试命令和覆盖率报告；CovGate 会按各自源码范围计算覆盖率。若使用 `--profile` 或 `--source` 手工覆盖，则只生成一个 scope。
+
+生成配置后请先运行：
 
 ```bash
 npx --no-install covgate validate
 npx --no-install covgate run
 ```
 
+门禁失败时，正确做法是让项目补覆盖该行为的真实测试；CovGate 不会替项目补测试，也不会接受空报告、`--passWithNoTests` 或降低门槛。
+
 ## AI 代理如何真正做到“自动跑”
 
 生成的文件不等于自动触发。需要把它接到代理生命周期：
@@ -160,4 +162,4 @@ npx --no-install covgate run
 - **没有弹出测试框架询问**：npm 11 默认阻止 install scripts。运行 `npx covgate setup`。
 - **没有生成 CovGate 配置**：可能没有识别到源码目录或覆盖率命令。用 `--source`、`--test-command` 指定，或先安装框架。
 - **Vitest 安装超时**：setup 对安装命令有 180 秒限制。检查网络/registry，手动安装 `vitest @vitest/coverage-v8` 后重跑 setup。
-- **多 scope 项目**：setup 只生成一个；手工编辑或分目录 setup。
+- **多 scope 项目**：setup 只生成一个；手工编辑或分目录 setup。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "covgate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "覆盖率门禁：客户端 100%，服务端至少 95%，安装时自动检测/配置测试框架与 AI 编码代理接入。",
   "type": "module",
   "bin": {

package/src/setup/agent.js

@@ -14,6 +14,7 @@ const AGENT_BLOCK = [
   "- 禁止 `istanbul ignore`、`c8 ignore`、`v8 ignore`、`node:coverage ignore`。",
   "- 确实不可达的代码使用 `covgate-ignore-next-line`、`covgate-ignore-start/end` 或 `covgate-ignore-file`，写具体原因、owner 和 expires。",
   "- 禁止通过扩大 exclude、缩小 sources.include 或删除测试来让门禁通过；这类改动必须由人类评审。",
+  "- 行为变更必须新增或更新覆盖该行为的真实测试；不能把“门禁失败”当作完成理由，也不得用空报告、`--passWithNoTests`、ignore 或降低门槛绕过。",
   "- 失败详情在 `.covgate/report.json` 的 scopes/issues/waivers 中；修复后重跑。",
   "",
   "也可运行 `npm run coverage:gate -- --json`。Agent Stop hook 可调用 `scripts/covgate-agent-gate.ps1`（Windows）或 `scripts/covgate-agent-gate.sh`。",
@@ -30,7 +31,8 @@ const CURSOR_RULE = [
   "# CovGate 覆盖率门禁",
   "",
   "任何代码修改后运行 `npx --no-install covgate run --json`，退出码 0 才能结束。",
-  "客户端必须 100%，服务端至少 95%。禁止原生 ignore；豁免必须写原因、owner、expires。",
+  "客户端必须 100%，服务端至少 95%。行为变更必须补真实测试；门禁失败不能作为完成理由。",
+  "禁止原生 ignore；豁免必须写原因、owner、expires。",
   ""
 ].join("\n");
 

package/src/setup/config.js

@@ -44,45 +44,62 @@ async function pickExcludes(root, sourceGlob) {
 /**
  * @param {{
  *   root: string,
- *   profile: "client" | "server",
- *   sourceGlob: string,
+ *   scopes?: Array<{ name: string, profile: "client" | "server", label?: string, sourceGlob: string }>,
+ *   profile?: "client" | "server",
+ *   sourceGlob?: string,
  *   command: string,
  *   coveragePath: string
  * }} options
  */
 export async function buildStarterConfig({
   root,
+  scopes,
   profile,
   sourceGlob,
   command,
   coveragePath
 }) {
-  const exclude = await pickExcludes(root, sourceGlob);
-  const label = profile === "client" ? "客户端" : "服务端";
+  const specs =
+    scopes && scopes.length > 0
+      ? scopes
+      : [
+          {
+            name: profile,
+            profile,
+            label: profile === "client" ? "客户端" : "服务端",
+            sourceGlob
+          }
+        ];
+  const scopeConfigs = {};
+  for (const spec of specs) {
+    if (!spec.profile || !spec.sourceGlob || !spec.name) continue;
+    const label =
+      spec.label || (spec.profile === "client" ? "客户端" : "服务端");
+    const exclude = await pickExcludes(root, spec.sourceGlob);
+    scopeConfigs[spec.name] = {
+      profile: spec.profile,
+      label,
+      commands: [
+        {
+          name: label + "测试与覆盖率",
+          run: command,
+          timeoutSeconds: 900
+        }
+      ],
+      coverage: {
+        format: "auto",
+        paths: [coveragePath]
+      },
+      sources: {
+        include: [spec.sourceGlob]
+      },
+      exclude
+    };
+  }
   return {
     $schema: "./node_modules/covgate/schema/covgate.schema.json",
     version: 1,
-    scopes: {
-      [profile]: {
-        profile,
-        label,
-        commands: [
-          {
-            name: label + "测试与覆盖率",
-            run: command,
-            timeoutSeconds: 900
-          }
-        ],
-        coverage: {
-          format: "auto",
-          paths: [coveragePath]
-        },
-        sources: {
-          include: [sourceGlob]
-        },
-        exclude
-      }
-    },
+    scopes: scopeConfigs,
     waivers: {
       minReasonLength: 8,
       requireOwner: false,

package/src/setup/index.js

@@ -8,6 +8,7 @@ import {
   detectFramework,
   detectPackageManager,
   detectProfile,
+  detectScopeSpecs,
   detectSourceGlob,
   displayPath,
   installVitest,
@@ -108,23 +109,40 @@ export async function runSetup(options = {}) {
     testCommand = "npm run test:coverage";
   }
 
-  const profile = options.profile || detectProfile(root, pkg);
-  if (!["client", "server"].includes(profile)) {
-    throw new SetupError("profile 必须是 client 或 server");
+  let scopeSpecs;
+  if (options.profile || options.source) {
+    const profile = options.profile || detectProfile(root, pkg);
+    if (!["client", "server"].includes(profile)) {
+      throw new SetupError("profile 必须是 client 或 server");
+    }
+    const sourceGlob = normalizeGlob(
+      root,
+      options.source || detectSourceGlob(root, profile) || ""
+    );
+    scopeSpecs = sourceGlob
+      ? [
+          {
+            name: profile,
+            profile,
+            label: profile === "client" ? "客户端" : "服务端",
+            sourceGlob
+          }
+        ]
+      : [];
+  } else {
+    scopeSpecs = detectScopeSpecs(root, pkg);
   }
-  const sourceGlob = normalizeGlob(root, options.source || detectSourceGlob(root, profile) || "");
   const coveragePath = normalizeGlob(root, options.coverage || DEFAULT_COVERAGE_PATH);
   const configPath = path.join(root, "covgate.config.json");
   let configWritten = false;
 
-  if (options.noConfig !== true && testCommand && sourceGlob) {
+  if (options.noConfig !== true && testCommand && scopeSpecs.length > 0) {
     if (existsSync(configPath) && options.force !== true) {
       log("[covgate] " + displayPath(root, configPath) + " 已存在，保留现有配置");
     } else {
       const config = await buildStarterConfig({
         root,
-        profile,
-        sourceGlob,
+        scopes: scopeSpecs,
         command: testCommand,
         coveragePath
       });
@@ -137,9 +155,9 @@ export async function runSetup(options = {}) {
         "[covgate] 生成 " +
           displayPath(root, configPath) +
           "（" +
-          profile +
-          "，源码 " +
-          sourceGlob +
+          scopeSpecs
+            .map((scope) => scope.profile + "：" + scope.sourceGlob)
+            .join("，") +
           "）"
       );
       if (framework.id && !coverageScriptFor(framework.id) && !options.testCommand) {
@@ -150,7 +168,7 @@ export async function runSetup(options = {}) {
     if (!testCommand) {
       log("[covgate] 未找到可用的覆盖率测试命令，跳过 covgate.config.json。");
     }
-    if (!sourceGlob) {
+    if (scopeSpecs.length === 0) {
       log("[covgate] 未找到源码目录，跳过 covgate.config.json；请用 --source 指定。");
     }
   }
@@ -171,8 +189,9 @@ export async function runSetup(options = {}) {
     packageManager,
     framework: framework.id || null,
     installedFramework,
-    profile,
-    sourceGlob: sourceGlob || null,
+    profile: scopeSpecs.length === 1 ? scopeSpecs[0].profile : null,
+    sourceGlob: scopeSpecs.length === 1 ? scopeSpecs[0].sourceGlob : null,
+    scopes: scopeSpecs,
     testCommand: testCommand || null,
     coveragePath,
     configPath: configWritten ? configPath : existsSync(configPath) ? configPath : null,
@@ -191,7 +210,16 @@ export async function runSetup(options = {}) {
   if (summary.framework) {
     log("[covgate] 测试框架: " + (framework.label || summary.framework));
   }
+  if (scopeSpecs.length > 0) {
+    log(
+      "[covgate] Scope: " +
+        scopeSpecs
+          .map((scope) => scope.name + "/" + scope.profile + " (" + scope.sourceGlob + ")")
+          .join(", ")
+    );
+  }
   log("[covgate] 运行门禁: " + (summary.dryRun ? "npx covgate run" : "npx --no-install covgate run"));
+  log("[covgate] 注意：CovGate 不会生成或补写测试；项目必须为行为变更补真实测试后才能通过门禁。");
   if (!options.noAgent) {
     log("[covgate] AI 接入: AGENTS.md 与 scripts/covgate-agent-gate.*");
   }

package/src/setup/project.js

@@ -156,13 +156,27 @@ export function detectFramework(pkg) {
  */
 export function detectProfile(root, pkg) {
   const deps = directDependencyNames(pkg);
-  if (existsSync(path.join(root, "index.html"))) return "client";
+  const htmlLocations = [
+    "index.html",
+    "src/index.html",
+    "app/index.html",
+    "renderer/index.html"
+  ];
+  if (htmlLocations.some((file) => existsSync(path.join(root, file)))) return "client";
   if (pkg?.browser) return "client";
+  if (deps.has("electron") || deps.has("electron-builder")) return "client";
   if ([...BROWSER_DEPS].some((dependency) => deps.has(dependency))) return "client";
   if ([...SERVER_DEPS].some((dependency) => deps.has(dependency))) return "server";
   return "server";
 }
 
+/**
+ * @param {string} directory
+ */
+export function sourceGlobForDir(directory) {
+  return directory + "/**/*." + SOURCE_EXT;
+}
+
 /**
  * @param {string} root
  * @param {"client" | "server"} profile
@@ -170,33 +184,94 @@ export function detectProfile(root, pkg) {
  */
 export function detectSourceGlob(root, profile) {
   if (existsSync(path.join(root, "src"))) {
-    return "src/**/*." + SOURCE_EXT;
+    return sourceGlobForDir("src");
   }
   if (profile === "client" && existsSync(path.join(root, "app.js"))) {
     return "app.js";
   }
   const candidate = profile === "client" ? "client" : "server";
   if (existsSync(path.join(root, candidate))) {
-    return candidate + "/**/*." + SOURCE_EXT;
+    return sourceGlobForDir(candidate);
   }
   if (existsSync(path.join(root, "app"))) {
-    return "app/**/*." + SOURCE_EXT;
+    return sourceGlobForDir("app");
   }
   if (existsSync(path.join(root, "lib"))) {
-    return "lib/**/*." + SOURCE_EXT;
+    return sourceGlobForDir("lib");
   }
   return null;
 }
 
+/**
+ * Electron apps usually have a renderer tree (src) and a main-process tree
+ * (desktop). Treating src as server (the old setup default) was wrong.
+ *
+ * @param {string} root
+ * @param {any} pkg
+ */
+export function detectElectronApp(root, pkg) {
+  const deps = directDependencyNames(pkg);
+  if (deps.has("electron") || deps.has("electron-builder") || deps.has("@electron/packager")) {
+    return true;
+  }
+  const main = typeof pkg?.main === "string" ? pkg.main.replaceAll("\\", "/") : "";
+  return main.startsWith("desktop/") && existsSync(path.join(root, "src"));
+}
+
+/**
+ * @param {string} root
+ * @param {any} pkg
+ * @returns {Array<{ name: string, profile: "client" | "server", label: string, sourceGlob: string }>}
+ */
+export function detectScopeSpecs(root, pkg) {
+  if (detectElectronApp(root, pkg)) {
+    const clientDir = ["src", "app", "renderer", "client"].find((directory) =>
+      existsSync(path.join(root, directory))
+    );
+    const serverDir = ["desktop", "electron", "main"].find((directory) =>
+      existsSync(path.join(root, directory))
+    );
+    const specs = [];
+    if (clientDir) {
+      specs.push({
+        name: "client",
+        profile: "client",
+        label: "桌面客户端",
+        sourceGlob: sourceGlobForDir(clientDir)
+      });
+    }
+    if (serverDir) {
+      specs.push({
+        name: "server",
+        profile: "server",
+        label: "桌面主进程",
+        sourceGlob: sourceGlobForDir(serverDir)
+      });
+    }
+    if (specs.length > 0) return specs;
+  }
+  const profile = detectProfile(root, pkg);
+  const sourceGlob = detectSourceGlob(root, profile);
+  if (!sourceGlob) return [];
+  return [
+    {
+      name: profile,
+      profile,
+      label: profile === "client" ? "客户端" : "服务端",
+      sourceGlob
+    }
+  ];
+}
+
 /**
  * @param {"vitest" | "jest" | string} frameworkId
  */
 export function coverageScriptFor(frameworkId) {
   if (frameworkId === "vitest") {
-    return "vitest run --coverage --coverage.reporter=json --coverage.reporter=lcov --passWithNoTests";
+    return "vitest run --coverage --coverage.reporter=json --coverage.reporter=lcov";
   }
   if (frameworkId === "jest") {
-    return "jest --coverage --coverageReporters=json --coverageReporters=lcov --passWithNoTests";
+    return "jest --coverage --coverageReporters=json --coverageReporters=lcov";
   }
   return null;
 }

package/templates/AGENTS.md.snippet.md

@@ -3,6 +3,7 @@
 - 任何代码修改完成后，必须运行 `npx --no-install covgate run --json`；**退出码 0 才能结束任务**。
 - 退出码 `1`：补测试或修实现；`2`：修配置；`3`：修测试命令/覆盖率报告。不要绕过。
 - 禁止降低 `covgate.config.json` 中的门槛、扩大 exclude、删除豁免检查来让门禁通过。任何配置改动都必须由人类评审。
+- **行为变更必须新增或更新覆盖该行为的真实测试**；不能把“门禁失败”当作完成理由，也不得用空报告、`--passWithNoTests`、ignore 或降低门槛绕过。
 - 禁止 `istanbul ignore`、`c8 ignore`、`v8 ignore`、`node:coverage ignore`。
 - 确实不可达的代码使用 `covgate-ignore-next-line`、`covgate-ignore-start/end` 或 `covgate-ignore-file`，并写具体原因、owner 和 expires。
 - 新增或修改的源码必须出现在覆盖率报告中；`sources.include` 是范围事实来源。