covgate 0.3.1 → 0.3.2

package/README.md

@@ -80,7 +80,7 @@ covgate run
 
 ### 从 npm registry 安装（推荐）
 
-包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.3.1**。
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.3.2**。
 
 ```bash
 npm install --save-dev covgate
@@ -132,6 +132,8 @@ setup 会：
 
 **CovGate 不生成测试，也不补测试。** 行为变更的测试必须由项目自己补；没有测试时 `test:coverage` 会直接失败，不会生成空覆盖率来蒙混过关。
 
+如果 setup 找不到覆盖率命令，不会静默跳过：会打印具体的 `test:coverage` 建议、`--test-command` 用法和 GUI 命令。已有 `covgate.config.json` 会保留，并在输出中说明现有 scopes。
+
 `postinstall` 也会尝试同样的流程，但 **npm 11.19+ 默认不执行依赖安装脚本**。如果安装时没有弹出询问，直接运行 `npx covgate setup` 即可；详细说明见 [安装与自动配置](docs/setup.md)。
 
 ### 在 CovGate 仓库中开发
@@ -509,7 +511,7 @@ macOS 用 `open .covgate/report.html`，Linux 用 `xdg-open .covgate/report.html
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.3.1
+CovGate · 覆盖率门禁 v0.3.2
 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s
 
 ✗ 客户端 [client/client] 未通过

package/docs/setup.md

@@ -9,7 +9,7 @@ npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.3.1**。
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.3.2**。
 
 > `0.0.0-stage` 是 npm 暂存发布产生的占位版本，不会被 `npm install covgate` 选中，可以忽略。
 
@@ -38,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.3.1 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.3.2 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：
@@ -82,7 +82,9 @@ npm warn install-scripts   covgate@0.3.1 (postinstall: node bin/covgate-postinst
    - `.github/workflows/covgate.yml`（如果存在 `.github/`）
    - `.gitignore` 加入 `.covgate/`、`coverage/`
    - 若已有 `CLAUDE.md`、`.cursor`、`.github/copilot-instructions.md`，同步写入对应说明。
-6. 输出下一步命令。
+6. 输出下一步命令，包括可视化工作台：`npx --no-install covgate ui`。
+
+> 找不到覆盖率测试命令时，setup 不会静默跳过：会给出 `test:coverage` 建议、`--test-command` 示例和 GUI 命令。如果项目已有 `covgate.config.json`，会保留并列出其中 scopes，不会因为缺少通用命令而覆盖或误报。
 
 > **CovGate 不生成测试，也不补测试。** setup 只配置测试框架和门禁；本次行为变更的测试必须由项目自己补。没有测试时 `test:coverage` 会直接失败（已移除 `--passWithNoTests`），不会产生可蒙混过关的空覆盖率。
 

package/package.json

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

package/src/setup/index.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
   SetupError,
@@ -20,6 +20,33 @@ import { scaffoldAgent } from "./agent.js";
 import { askYesNo, canPrompt } from "./prompt.js";
 
 const DEFAULT_COVERAGE_PATH = "coverage/coverage-final.json";
+const UI_COMMAND = "npx --no-install covgate ui";
+
+async function existingScopeNames(configPath) {
+  try {
+    const data = JSON.parse(await readFile(configPath, "utf8"));
+    return Object.keys(data.scopes || {});
+  } catch {
+    return [];
+  }
+}
+
+function printConfigGuidance(log, framework) {
+  log("[covgate] 未生成 covgate.config.json：缺少可用的覆盖率测试命令。");
+  if (framework.id === "vitest") {
+    log('[covgate] 在 package.json 添加 "test:coverage": "vitest run --coverage --coverage.reporter=json --coverage.reporter=lcov"，然后重新运行 setup。');
+  } else if (framework.id === "jest") {
+    log('[covgate] 在 package.json 添加 "test:coverage": "jest --coverage --coverageReporters=json --coverageReporters=lcov"，然后重新运行 setup。');
+  } else if (framework.id === "node-test") {
+    log("[covgate] 检测到 Node.js 内置 test runner。安装 c8 后添加覆盖率命令：");
+    log('  "test:coverage": "c8 --reporter=json --reporter=lcov node --test"');
+  } else {
+    log("[covgate] 先安装/配置测试框架，并在 package.json 添加 test:coverage。");
+  }
+  log('[covgate] 也可以直接指定命令：npx --no-install covgate setup --test-command "<覆盖率命令>"');
+  log("[covgate] 然后运行 npx --no-install covgate validate 检查配置。");
+  log("[covgate] 可视化配置工作台：" + UI_COMMAND);
+}
 
 /**
  * @param {string} root
@@ -134,12 +161,22 @@ export async function runSetup(options = {}) {
   }
   const coveragePath = normalizeGlob(root, options.coverage || DEFAULT_COVERAGE_PATH);
   const configPath = path.join(root, "covgate.config.json");
+  const configExists = existsSync(configPath);
   let configWritten = false;
+  let configPreserved = false;
 
-  if (options.noConfig !== true && testCommand && scopeSpecs.length > 0) {
-    if (existsSync(configPath) && options.force !== true) {
-      log("[covgate] " + displayPath(root, configPath) + " 已存在，保留现有配置");
-    } else {
+  if (options.noConfig !== true) {
+    if (configExists && options.force !== true) {
+      configPreserved = true;
+      const names = await existingScopeNames(configPath);
+      log(
+        "[covgate] " +
+          displayPath(root, configPath) +
+          " 已存在" +
+          (names.length ? "（scopes: " + names.join(", ") + "）" : "") +
+          "，保留现有配置，不因缺少通用覆盖率命令而覆盖或跳过。"
+      );
+    } else if (testCommand && scopeSpecs.length > 0) {
       const config = await buildStarterConfig({
         root,
         scopes: scopeSpecs,
@@ -163,13 +200,16 @@ export async function runSetup(options = {}) {
       if (framework.id && !coverageScriptFor(framework.id) && !options.testCommand) {
         log("[covgate] 注意：该测试框架的覆盖率命令需要你确认报告路径。");
       }
-    }
-  } else if (options.noConfig !== true) {
-    if (!testCommand) {
-      log("[covgate] 未找到可用的覆盖率测试命令，跳过 covgate.config.json。");
-    }
-    if (scopeSpecs.length === 0) {
-      log("[covgate] 未找到源码目录，跳过 covgate.config.json；请用 --source 指定。");
+    } else if (configExists) {
+      configPreserved = true;
+      log("[covgate] " + displayPath(root, configPath) + " 无法重新生成，保留现有配置。");
+      if (!testCommand) {
+        log("[covgate] 现有配置仍可使用；如需重新生成，请先补覆盖率命令。");
+      }
+    } else if (!testCommand) {
+      printConfigGuidance(log, framework);
+    } else if (scopeSpecs.length === 0) {
+      log("[covgate] 未找到源码目录，未生成 covgate.config.json；请用 --source 指定。");
     }
   }
 
@@ -195,6 +235,8 @@ export async function runSetup(options = {}) {
     testCommand: testCommand || null,
     coveragePath,
     configPath: configWritten ? configPath : existsSync(configPath) ? configPath : null,
+    configPreserved,
+    uiCommand: UI_COMMAND,
     packageChanged,
     packageScripts: scriptChanges,
     agentChanges,
@@ -219,6 +261,7 @@ export async function runSetup(options = {}) {
     );
   }
   log("[covgate] 运行门禁: " + (summary.dryRun ? "npx covgate run" : "npx --no-install covgate run"));
+  log("[covgate] 可视化工作台: " + UI_COMMAND);
   log("[covgate] 注意：CovGate 不会生成或补写测试；项目必须为行为变更补真实测试后才能通过门禁。");
   if (!options.noAgent) {
     log("[covgate] AI 接入: AGENTS.md 与 scripts/covgate-agent-gate.*");