covgate 0.3.1 → 0.3.3

package/README.md

@@ -29,6 +29,7 @@ npx --no-install covgate ui --root D:/Projects/my-app --port 4319 --no-open
 - 指定客户端、服务端源码路径，路径有自动检测的建议列表；
 - 从项目 `package.json` 脚本中**下拉选择测试命令**，不需要手敲；
 - 单独指定客户端/服务端命令，自动生成临时配置并运行；
+- 客户端、服务端可以分别设置覆盖率报告路径，适配前后端分开产出的项目；
 - 工具内嵌覆盖率报告：左侧文件列表，中间源码，绿色已覆盖、白色未覆盖；
 - 运行前检查测试文件；没有测试时禁用运行，并提供可复制的 **AI 补测任务**，避免生成空报告；
 - 测试命令失败或没有生成报告时，直接显示日志和原因，不展示空结果页；
@@ -80,7 +81,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.3**。
 
 ```bash
 npm install --save-dev covgate
@@ -132,6 +133,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 +512,7 @@ macOS 用 `open .covgate/report.html`，Linux 用 `xdg-open .covgate/report.html
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.3.1
+CovGate · 覆盖率门禁 v0.3.3
 模式 执行测试并检查 · 配置 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.3**。
 
 > `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.3 (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.3",
   "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.*");

package/src/ui/page.html

@@ -201,7 +201,8 @@
       <div id="healthCard" class="health" hidden>
         <div class="health-row"><span>测试框架</span><b id="healthFramework">—</b></div>
         <div class="health-row"><span>测试文件</span><b id="healthTests">—</b></div>
-        <div class="health-row"><span>覆盖率报告</span><b id="healthCoverage">—</b></div>
+        <div class="health-row"><span>客户端报告</span><b id="healthClientCoverage">—</b></div>
+        <div class="health-row"><span>服务端报告</span><b id="healthServerCoverage">—</b></div>
       </div>
       <div id="healthWarn" class="health-warn" hidden>
         没有检测到测试文件。CovGate 不会生成测试，请先让项目/AI 补真实测试。
@@ -243,8 +244,12 @@
           <span class="hint">自动检测</span>
         </div>
         <div class="field">
-          <label for="coveragePath">报告文件</label>
-          <input id="coveragePath" list="coverageOptions" spellcheck="false" placeholder="coverage/coverage-final.json">
+          <label for="clientCoveragePath">客户端报告</label>
+          <input id="clientCoveragePath" list="coverageOptions" spellcheck="false" placeholder="coverage/client/coverage-final.json">
+        </div>
+        <div class="field">
+          <label for="serverCoveragePath">服务端报告</label>
+          <input id="serverCoveragePath" list="coverageOptions" spellcheck="false" placeholder="coverage/server/coverage-final.json">
         </div>
         <div id="configChip" class="config-chip temp">使用临时配置</div>
       </section>
@@ -322,7 +327,8 @@
         var server = $("serverPath").value.trim() || "（未指定）";
         var clientCommand = $("clientCommand").value || "（未选择）";
         var serverCommand = $("serverCommand").value || "（未选择）";
-        var coverage = $("coveragePath").value.trim() || "（未指定）";
+        var clientCoverage = $("clientCoveragePath").value.trim() || "（未指定）";
+        var serverCoverage = $("serverCoveragePath").value.trim() || "（未指定）";
         var framework = state && state.frameworkLabel ? state.frameworkLabel : "项目现有测试框架";
         return [
           "你正在为以下项目补真实测试，目标是让 CovGate 真正通过。",
@@ -333,7 +339,8 @@
           "服务端源码：" + server + "（目标 95%）",
           "客户端测试命令：" + clientCommand,
           "服务端测试命令：" + serverCommand,
-          "覆盖率报告：" + coverage,
+          "客户端覆盖率报告：" + clientCoverage,
+          "服务端覆盖率报告：" + serverCoverage,
           "",
           "当前测试文件数量：" + ((state && state.testCount) || 0) + "。请先建立/完善测试基础设施，再补真实测试。",
           "",
@@ -359,6 +366,14 @@
         area.remove();
         return Promise.resolve();
       }
+      function syncCoverageHealth() {
+        var client = $("clientCoveragePath").value.trim() || "未指定";
+        var server = $("serverCoveragePath").value.trim() || "未指定";
+        $("healthClientCoverage").textContent = client;
+        $("healthClientCoverage").title = client;
+        $("healthServerCoverage").textContent = server;
+        $("healthServerCoverage").title = server;
+      }
       function updateHealth(data) {
         var hasTests = (data.testCount || 0) > 0;
         $("healthCard").hidden = false;
@@ -366,7 +381,7 @@
         $("healthFramework").className = data.framework ? "good" : "bad";
         $("healthTests").textContent = hasTests ? data.testCount + " 个" : "0 个 · 需要补测试";
         $("healthTests").className = hasTests ? "good" : "bad";
-        $("healthCoverage").textContent = data.coveragePath || "未指定";
+        syncCoverageHealth();
         $("healthWarn").hidden = hasTests;
         $("emptyMark").textContent = hasTests ? "⌁" : "!";
         $("emptyTitle").textContent = hasTests ? "把覆盖率跑起来" : "项目还没有测试";
@@ -374,6 +389,7 @@
           ? "在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。"
           : "CovGate 不会生成测试。先让项目或编码代理补真实测试，再运行覆盖率。<br>可以复制下面的补测任务作为 AI 的输入。";
         $("emptyActions").hidden = hasTests;
+        syncCoverageHealth();
         setRunning(false);
       }
       function showView(name) {
@@ -422,12 +438,15 @@
         $("root").value = data.root;
         $("clientPath").value = data.clientPath || "";
         $("serverPath").value = data.serverPath || "";
-        $("coveragePath").value = data.coveragePath || "coverage/coverage-final.json";
+        $("clientCoveragePath").value = data.clientCoveragePath || data.coveragePath || "coverage/coverage-final.json";
+        $("serverCoveragePath").value = data.serverCoveragePath || data.coveragePath || "coverage/coverage-final.json";
         fillCommands($("clientCommand"), data.commands || [], data.clientCommand);
         fillCommands($("serverCommand"), data.commands || [], data.serverCommand);
         fillDatalist("sourceDirs", data.sourceDirs || []);
         var coverageOptions = (data.coverageFiles || []).slice();
-        if (data.coveragePath && coverageOptions.indexOf(data.coveragePath) === -1) coverageOptions.unshift(data.coveragePath);
+        [data.clientCoveragePath, data.serverCoveragePath, data.coveragePath].forEach(function (value) {
+          if (value && coverageOptions.indexOf(value) === -1) coverageOptions.unshift(value);
+        });
         fillDatalist("coverageOptions", coverageOptions);
         var chip = $("configChip");
         chip.textContent = data.existingConfig ? "已加载现有 covgate.config.json" : "使用临时配置";
@@ -578,7 +597,8 @@
               serverPath: serverPath,
               clientCommand: clientCommand,
               serverCommand: serverCommand,
-              coveragePath: $("coveragePath").value.trim(),
+              clientCoveragePath: $("clientCoveragePath").value.trim(),
+              serverCoveragePath: $("serverCoveragePath").value.trim(),
               allowNoTests: allowNoTests
             })
           });
@@ -598,6 +618,8 @@
       $("detectBtn").addEventListener("click", detect);
       $("root").addEventListener("keydown", function (event) { if (event.key === "Enter") detect(); });
       $("runBtn").addEventListener("click", run);
+      $("clientCoveragePath").addEventListener("input", syncCoverageHealth);
+      $("serverCoveragePath").addEventListener("input", syncCoverageHealth);
       $("copyPromptBtn").addEventListener("click", function () {
         copyText(buildPrompt()).then(function () {
           toast("补测任务已复制");

package/src/ui/server.js

@@ -178,8 +178,17 @@ async function inspectProject(root) {
   for (const candidate of COVERAGE_CANDIDATES) {
     if (existsSync(path.join(projectRoot, candidate))) coverageFiles.push(candidate);
   }
-  const configuredCoverage = scopes.client?.coverage?.paths?.[0] || scopes.server?.coverage?.paths?.[0];
+  const configuredClientCoverage = scopes.client?.coverage?.paths?.[0];
+  const configuredServerCoverage = scopes.server?.coverage?.paths?.[0];
+  const configuredCoverage = configuredClientCoverage || configuredServerCoverage;
   const coveragePath = configuredCoverage || coverageFiles[0] || COVERAGE_CANDIDATES[0];
+  const clientCoveragePath = configuredClientCoverage || coveragePath;
+  const serverCoveragePath = configuredServerCoverage || coveragePath;
+  const coverageSuggestions = [...new Set([
+    clientCoveragePath,
+    serverCoveragePath,
+    ...coverageFiles
+  ].filter(Boolean))];
 
   const pickExisting = (names) => names.find((name) => existsSync(path.join(projectRoot, name))) || "";
   const clientPath =
@@ -200,8 +209,10 @@ async function inspectProject(root) {
     frameworkLabel: framework.label,
     commands,
     sourceDirs,
-    coverageFiles,
+    coverageFiles: coverageSuggestions,
     coveragePath,
+    clientCoveragePath,
+    serverCoveragePath,
     clientPath,
     serverPath,
     clientCommand,
@@ -216,10 +227,21 @@ async function inspectProject(root) {
 async function buildConfig(state, input) {
   const clientPath = relativeInput(state.root, input.clientPath);
   const serverPath = relativeInput(state.root, input.serverPath);
-  const coveragePath = relativeInput(state.root, input.coveragePath || state.coveragePath);
+  const fallbackCoveragePath = relativeInput(
+    state.root,
+    input.coveragePath || state.coveragePath
+  );
+  const clientCoveragePath = relativeInput(
+    state.root,
+    input.clientCoveragePath || state.clientCoveragePath || fallbackCoveragePath
+  );
+  const serverCoveragePath = relativeInput(
+    state.root,
+    input.serverCoveragePath || state.serverCoveragePath || fallbackCoveragePath
+  );
   const existing = state.existing || {};
   const scopes = {};
-  const makeScope = async (name, profile, label, sourcePath, command) => {
+  const makeScope = async (name, profile, label, sourcePath, command, coveragePath) => {
     if (!sourcePath) return;
     const old = existing.scopes?.[name] || {};
     const oldExclude = Array.isArray(old.exclude) ? old.exclude : [];
@@ -247,8 +269,8 @@ async function buildConfig(state, input) {
       exclude
     };
   };
-  await makeScope("client", "client", "客户端", clientPath, input.clientCommand || state.clientCommand);
-  await makeScope("server", "server", "服务端", serverPath, input.serverCommand || state.serverCommand);
+  await makeScope("client", "client", "客户端", clientPath, input.clientCommand || state.clientCommand, clientCoveragePath);
+  await makeScope("server", "server", "服务端", serverPath, input.serverCommand || state.serverCommand, serverCoveragePath);
   if (Object.keys(scopes).length === 0) {
     throw new HttpError(400, "至少需要指定客户端或服务端源码路径。");
   }
@@ -379,7 +401,10 @@ export async function startUiServer(options = {}) {
             serverPath: body.serverPath || "",
             clientCommand: body.clientCommand || state.clientCommand || "",
             serverCommand: body.serverCommand || state.serverCommand || "",
-            coveragePath: body.coveragePath || state.coveragePath || ""
+            clientCoveragePath:
+              body.clientCoveragePath || state.clientCoveragePath || body.coveragePath || "",
+            serverCoveragePath:
+              body.serverCoveragePath || state.serverCoveragePath || body.coveragePath || ""
           }
         };
         jobs.set(id, job);