covgate 0.3.0 → 0.3.1

package/README.md

@@ -30,6 +30,8 @@ npx --no-install covgate ui --root D:/Projects/my-app --port 4319 --no-open
 - 从项目 `package.json` 脚本中**下拉选择测试命令**，不需要手敲；
 - 单独指定客户端/服务端命令，自动生成临时配置并运行；
 - 工具内嵌覆盖率报告：左侧文件列表，中间源码，绿色已覆盖、白色未覆盖；
+- 运行前检查测试文件；没有测试时禁用运行，并提供可复制的 **AI 补测任务**，避免生成空报告；
+- 测试命令失败或没有生成报告时，直接显示日志和原因，不展示空结果页；
 - 不覆盖项目已有的 `covgate.config.json`，运行结果仍写入 `.covgate/`。
 
 `covgate ui` 只监听本机回环地址，适合本地使用；CI 和 Agent 仍用 `covgate run`。
@@ -78,7 +80,7 @@ covgate run
 
 ### 从 npm registry 安装（推荐）
 
-包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.3.0**。
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.3.1**。
 
 ```bash
 npm install --save-dev covgate
@@ -507,7 +509,7 @@ macOS 用 `open .covgate/report.html`，Linux 用 `xdg-open .covgate/report.html
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.3.0
+CovGate · 覆盖率门禁 v0.3.1
 模式 执行测试并检查 · 配置 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.0**。
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.3.1**。
 
 > `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.0 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.3.1 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：

package/package.json

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

package/src/ui/page.html

@@ -68,6 +68,18 @@
       padding: 18px;
     }
     .panel-intro { margin: 0 0 16px; color: var(--muted); font-size: 12px; line-height: 1.7; }
+    .health {
+      background: #edf6ff; border: 1px solid #cfe3f8; border-radius: 10px;
+      padding: 10px 12px; margin-bottom: 12px; display: grid; gap: 6px; font-size: 11px;
+    }
+    .health-row { display: flex; justify-content: space-between; gap: 10px; color: #4d6b86; }
+    .health-row b { color: #17324a; font-weight: 700; text-align: right; }
+    .health-row b.bad { color: var(--red); }
+    .health-row b.good { color: var(--green); }
+    .health-warn {
+      border: 1px solid #f1d58a; background: #fff8e3; color: #735700;
+      border-radius: 9px; padding: 9px 10px; margin: 0 0 12px; font-size: 11px; line-height: 1.55;
+    }
     .card {
       background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
       padding: 14px; margin-bottom: 12px; box-shadow: 0 2px 5px rgba(24,44,66,.03);
@@ -110,6 +122,14 @@
     .empty-mark { width: 64px; height: 64px; margin: 0 auto 18px; border-radius: 18px; background: #dcecfb; color: #1473e6; display: grid; place-items: center; font-size: 26px; }
     .empty h1 { margin: 0 0 8px; font-size: 22px; letter-spacing: -.3px; }
     .empty p { color: var(--muted); font-size: 13px; line-height: 1.8; margin: 0; }
+    .empty-actions { display: flex; gap: 8px; justify-content: center; flex-wrap: wrap; margin-top: 16px; }
+    .secondary-btn {
+      height: 38px; border: 1px solid #b9cde2; border-radius: 8px;
+      background: #fff; color: #17324a; padding: 0 14px; font-size: 12px;
+    }
+    .secondary-btn:hover { border-color: var(--accent); color: var(--accent); }
+    .text-btn { border: 0; background: transparent; color: var(--muted); font-size: 11px; padding: 6px; text-decoration: underline; }
+    .text-btn:hover { color: var(--accent); }
     .run-view { padding: 22px; overflow: auto; flex: 1; }
     .run-card { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 18px; box-shadow: var(--shadow); }
     .run-head { display: flex; align-items: center; gap: 12px; margin-bottom: 14px; }
@@ -143,6 +163,12 @@
     .report-frame-wrap { flex: 1; min-height: 0; background: #fff; }
     .report-frame { width: 100%; height: 100%; border: 0; display: block; }
     .error-box { background: var(--red-bg); border: 1px solid #f5c2c5; color: #8d1f24; border-radius: 9px; padding: 12px; font-size: 12px; line-height: 1.7; margin-bottom: 12px; white-space: pre-wrap; }
+    .error-box .hint-line { margin-top: 7px; color: #6d3a3d; font-size: 11px; }
+    .toast {
+      position: fixed; left: 50%; bottom: 26px; transform: translateX(-50%);
+      background: #17324a; color: #fff; border-radius: 8px; padding: 9px 14px;
+      font-size: 12px; box-shadow: var(--shadow); z-index: 20;
+    }
     [hidden] { display: none !important; }
     @media (max-width: 980px) {
       .layout { grid-template-columns: 1fr; height: auto; }
@@ -172,6 +198,15 @@
     <aside class="panel">
       <p class="panel-intro">选择客户端、服务端的源码路径和测试命令。运行时会使用临时配置，不会覆盖项目里的 <code>covgate.config.json</code>。</p>
 
+      <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>
+      <div id="healthWarn" class="health-warn" hidden>
+        没有检测到测试文件。CovGate 不会生成测试，请先让项目/AI 补真实测试。
+      </div>
+
       <section class="card">
         <div class="card-head">
           <div class="card-title"><span class="dot"></span>客户端</div>
@@ -214,7 +249,7 @@
         <div id="configChip" class="config-chip temp">使用临时配置</div>
       </section>
 
-      <button id="runBtn" class="run-button" type="button">运行覆盖率</button>
+      <button id="runBtn" class="run-button" type="button" disabled>运行覆盖率</button>
       <div id="panelStatus" class="panel-status"></div>
 
       <datalist id="sourceDirs"></datalist>
@@ -223,9 +258,13 @@
 
     <section class="workspace">
       <div id="emptyView" class="empty">
-        <div class="empty-mark">⌁</div>
-        <h1>把覆盖率跑起来</h1>
-        <p>在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。</p>
+        <div id="emptyMark" class="empty-mark">⌁</div>
+        <h1 id="emptyTitle">把覆盖率跑起来</h1>
+        <p id="emptyText">在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。</p>
+        <div id="emptyActions" class="empty-actions" hidden>
+          <button id="copyPromptBtn" class="secondary-btn" type="button">复制 AI 补测任务</button>
+          <button id="allowRunBtn" class="text-btn" type="button">仍然运行一次</button>
+        </div>
       </div>
 
       <div id="runView" class="run-view" hidden>
@@ -256,6 +295,7 @@
       var state = null;
       var activeJob = null;
       var pollTimer = null;
+      var allowNoTests = false;
 
       function text(value) { return value === null || value === undefined ? "" : String(value); }
       function setStatus(message, kind) {
@@ -264,8 +304,77 @@
         el.className = "panel-status" + (kind ? " " + kind : "");
       }
       function setRunning(running) {
-        $("runBtn").disabled = running;
+        var noTests = Boolean(state && state.testCount === 0 && !allowNoTests);
+        $("runBtn").disabled = running || noTests;
         $("detectBtn").disabled = running;
+        $("runBtn").title = noTests ? "没有测试文件：先补测试，或使用“仍然运行一次”" : "";
+      }
+      function toast(message) {
+        var el = document.createElement("div");
+        el.className = "toast";
+        el.textContent = message;
+        document.body.appendChild(el);
+        setTimeout(function () { el.remove(); }, 1800);
+      }
+      function buildPrompt() {
+        var root = $("root").value.trim() || (state && state.root) || "";
+        var client = $("clientPath").value.trim() || "（未指定）";
+        var server = $("serverPath").value.trim() || "（未指定）";
+        var clientCommand = $("clientCommand").value || "（未选择）";
+        var serverCommand = $("serverCommand").value || "（未选择）";
+        var coverage = $("coveragePath").value.trim() || "（未指定）";
+        var framework = state && state.frameworkLabel ? state.frameworkLabel : "项目现有测试框架";
+        return [
+          "你正在为以下项目补真实测试，目标是让 CovGate 真正通过。",
+          "",
+          "项目根目录：" + root,
+          "测试框架：" + framework,
+          "客户端源码：" + client + "（目标 100%）",
+          "服务端源码：" + server + "（目标 95%）",
+          "客户端测试命令：" + clientCommand,
+          "服务端测试命令：" + serverCommand,
+          "覆盖率报告：" + coverage,
+          "",
+          "当前测试文件数量：" + ((state && state.testCount) || 0) + "。请先建立/完善测试基础设施，再补真实测试。",
+          "",
+          "硬性规则：",
+          "- 不得使用 ignore、伪造覆盖率、空报告或降低阈值；客户端 100%、服务端 95%。",
+          "- 不得整体排除客户端 UI、主进程或核心模块；只允许对第三方生成物或确实不可达的薄启动层提出窄范围 exclude/waiver，并写 reason/owner/expires，等待人工批准。",
+          "- 先补测试，再考虑配置；不要通过缩小 sources.include 或扩大 exclude 让门禁通过。",
+          "- 每轮至少完成一个可验证的测试里程碑；每轮运行 npx covgate run --json，退出码 0 才算完成。",
+          "- 最终通过后再提交/合并；WIP 请提交到独立分支并明确标注 coverage WIP。",
+          "",
+          "请从测试基础设施和第一批核心模块测试开始，直接修改代码并运行测试，不要只给计划。"
+        ].join(String.fromCharCode(10));
+      }
+      function copyText(value) {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          return navigator.clipboard.writeText(value);
+        }
+        var area = document.createElement("textarea");
+        area.value = value;
+        document.body.appendChild(area);
+        area.select();
+        document.execCommand("copy");
+        area.remove();
+        return Promise.resolve();
+      }
+      function updateHealth(data) {
+        var hasTests = (data.testCount || 0) > 0;
+        $("healthCard").hidden = false;
+        $("healthFramework").textContent = data.frameworkLabel || "未检测到";
+        $("healthFramework").className = data.framework ? "good" : "bad";
+        $("healthTests").textContent = hasTests ? data.testCount + " 个" : "0 个 · 需要补测试";
+        $("healthTests").className = hasTests ? "good" : "bad";
+        $("healthCoverage").textContent = data.coveragePath || "未指定";
+        $("healthWarn").hidden = hasTests;
+        $("emptyMark").textContent = hasTests ? "⌁" : "!";
+        $("emptyTitle").textContent = hasTests ? "把覆盖率跑起来" : "项目还没有测试";
+        $("emptyText").innerHTML = hasTests
+          ? "在左侧选择源码路径和测试命令，点击“运行覆盖率”。<br>完成后会在这里显示文件列表和逐行覆盖情况。"
+          : "CovGate 不会生成测试。先让项目或编码代理补真实测试，再运行覆盖率。<br>可以复制下面的补测任务作为 AI 的输入。";
+        $("emptyActions").hidden = hasTests;
+        setRunning(false);
       }
       function showView(name) {
         $("emptyView").hidden = name !== "empty";
@@ -309,6 +418,7 @@
       }
       function applyState(data) {
         state = data;
+        allowNoTests = false;
         $("root").value = data.root;
         $("clientPath").value = data.clientPath || "";
         $("serverPath").value = data.serverPath || "";
@@ -322,6 +432,7 @@
         var chip = $("configChip");
         chip.textContent = data.existingConfig ? "已加载现有 covgate.config.json" : "使用临时配置";
         chip.className = "config-chip" + (data.existingConfig ? "" : " temp");
+        updateHealth(data);
         setStatus(data.name ? "已检测：" + data.name + " · " + (data.frameworkLabel || "未检测到测试框架") : "已检测项目");
       }
       async function api(url, options) {
@@ -384,20 +495,28 @@
         activeJob = null;
         pollTimer = null;
         $("runView").hidden = true;
-        if (job.status === "failed" || !job.report) {
+        var report = job.report;
+        var emptyReport = !report || report.status === "error" || (report.scopes || []).length === 0;
+        if (job.status === "failed" || emptyReport) {
           showView("run");
           $("runTitle").textContent = "运行失败";
-          $("runMeta").textContent = job.error || "";
+          $("runMeta").textContent = job.exitCode === null ? "" : "退出码 " + job.exitCode;
+          var message = job.error;
+          if (!message && report && report.issues && report.issues.length) message = report.issues[0].message;
+          if (!message) message = "没有生成可用的覆盖率报告。";
+          if (/No test files found|没有测试文件/i.test(job.logs || "")) {
+            message += "\n\n检测到测试命令没有测试文件可执行。请先补真实测试，再重新运行。";
+          }
           $("runError").hidden = false;
-          $("runError").textContent = job.error || "没有生成覆盖率报告。";
-          $("logs").textContent = job.logs || "";
+          $("runError").textContent = message;
+          $("logs").textContent = job.logs || "测试命令没有输出。";
           setStatus("运行失败", "error");
           return;
         }
         try {
           renderSummary(job);
           showView("result");
-          setStatus("覆盖率完成：" + (job.report.status === "pass" ? "通过" : "未通过"), job.report.status === "pass" ? "ok" : "error");
+          setStatus("覆盖率完成：" + (report.status === "pass" ? "通过" : "未通过"), report.status === "pass" ? "ok" : "error");
         } catch (error) {
           showView("run");
           $("runTitle").textContent = "结果解析失败";
@@ -427,6 +546,11 @@
       }
       async function run() {
         if (activeJob) return;
+        if (state && state.testCount === 0 && !allowNoTests) {
+          showView("empty");
+          setStatus("项目没有测试文件。先补测试，或选择“仍然运行一次”。", "error");
+          return;
+        }
         var clientPath = $("clientPath").value.trim();
         var serverPath = $("serverPath").value.trim();
         if (!clientPath && !serverPath) {
@@ -454,7 +578,8 @@
               serverPath: serverPath,
               clientCommand: clientCommand,
               serverCommand: serverCommand,
-              coveragePath: $("coveragePath").value.trim()
+              coveragePath: $("coveragePath").value.trim(),
+              allowNoTests: allowNoTests
             })
           });
           activeJob = job.jobId;
@@ -463,12 +588,28 @@
           setRunning(false);
           setStatus(error.message, "error");
           showView("empty");
+          if (/没有检测到测试文件/.test(error.message)) {
+            allowNoTests = false;
+            if (state) updateHealth(state);
+          }
         }
       }
 
       $("detectBtn").addEventListener("click", detect);
       $("root").addEventListener("keydown", function (event) { if (event.key === "Enter") detect(); });
       $("runBtn").addEventListener("click", run);
+      $("copyPromptBtn").addEventListener("click", function () {
+        copyText(buildPrompt()).then(function () {
+          toast("补测任务已复制");
+        }).catch(function () {
+          toast("复制失败，请手动选择文本");
+        });
+      });
+      $("allowRunBtn").addEventListener("click", function () {
+        allowNoTests = true;
+        updateHealth(state);
+        run();
+      });
       detect();
     })();
   </script>

package/src/ui/server.js

@@ -5,6 +5,7 @@ import { readFile, stat, unlink, writeFile } from "node:fs/promises";
 import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { expandFiles, matchGlob } from "../glob.js";
 import { detectFramework, detectPackageManager } from "../setup/project.js";
 
 const BIN = fileURLToPath(new URL("../../bin/covgate.js", import.meta.url));
@@ -25,12 +26,49 @@ const SOURCE_DIR_CANDIDATES = [
   "web",
   "lib"
 ];
+const TEST_PATTERNS = [
+  "**/*.{test,spec}.{js,jsx,ts,tsx,mjs,cjs}",
+  "tests/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+  "test/**/*.{js,jsx,ts,tsx,mjs,cjs}",
+  "__tests__/**/*.{js,jsx,ts,tsx,mjs,cjs}"
+];
+const TEST_EXCLUDES = [
+  { pattern: "**/*.test.*", reason: "测试文件，不是产品运行时代码" },
+  { pattern: "**/*.spec.*", reason: "测试文件，不是产品运行时代码" },
+  { pattern: "**/__tests__/**", reason: "测试目录，不是产品运行时代码" }
+];
 const MAX_BODY = 1024 * 1024;
 
 class HttpError extends Error {
-  constructor(status, message) {
+  constructor(status, message, code) {
     super(message);
     this.status = status;
+    this.code = code || null;
+  }
+}
+
+async function pickTestExcludes(root, sourcePath) {
+  let files = [];
+  try {
+    files = await expandFiles([sourceGlob(sourcePath)], root);
+  } catch {
+    return [];
+  }
+  const relative = files.map((file) => toPosix(path.relative(root, file)));
+  return TEST_EXCLUDES.filter((entry) =>
+    relative.some((file) => matchGlob(file, entry.pattern))
+  );
+}
+
+async function findTestFiles(root) {
+  try {
+    const files = await expandFiles(TEST_PATTERNS, root);
+    return files
+      .map((file) => toPosix(path.relative(root, file)))
+      .filter((file) => !file.startsWith("../"))
+      .sort((left, right) => left.localeCompare(right, "en"));
+  } catch {
+    return [];
   }
 }
 
@@ -143,10 +181,16 @@ async function inspectProject(root) {
   const configuredCoverage = scopes.client?.coverage?.paths?.[0] || scopes.server?.coverage?.paths?.[0];
   const coveragePath = configuredCoverage || coverageFiles[0] || COVERAGE_CANDIDATES[0];
 
-  const clientPath = existingPath(scopes, "client") || (existsSync(path.join(projectRoot, "src")) ? "src" : "");
-  const serverPath = existingPath(scopes, "server") || (existsSync(path.join(projectRoot, "desktop")) ? "desktop" : "");
+  const pickExisting = (names) => names.find((name) => existsSync(path.join(projectRoot, name))) || "";
+  const clientPath =
+    existingPath(scopes, "client") ||
+    pickExisting(["src", "web", "client", "app", "renderer"]);
+  const serverPath =
+    existingPath(scopes, "server") ||
+    pickExisting(["server", "desktop", "api"]);
   const clientCommand = scopes.client?.commands?.[0]?.run || defaultCommand;
   const serverCommand = scopes.server?.commands?.[0]?.run || defaultCommand;
+  const testFiles = await findTestFiles(projectRoot);
 
   return {
     root: projectRoot,
@@ -162,20 +206,31 @@ async function inspectProject(root) {
     serverPath,
     clientCommand,
     serverCommand,
+    testCount: testFiles.length,
+    testFiles: testFiles.slice(0, 50),
     existingConfig: Boolean(existing),
     reportsDir: existing?.reports?.dir || ".covgate"
   };
 }
 
-function buildConfig(state, input) {
+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 existing = state.existing || {};
   const scopes = {};
-  const makeScope = (name, profile, label, sourcePath, command) => {
+  const makeScope = async (name, profile, label, sourcePath, command) => {
     if (!sourcePath) return;
     const old = existing.scopes?.[name] || {};
+    const oldExclude = Array.isArray(old.exclude) ? old.exclude : [];
+    const testExclude = await pickTestExcludes(state.root, sourcePath);
+    const merged = [...oldExclude, ...testExclude];
+    const seen = new Set();
+    const exclude = merged.filter((entry) => {
+      if (!entry || seen.has(entry.pattern)) return false;
+      seen.add(entry.pattern);
+      return true;
+    });
     scopes[name] = {
       profile,
       label,
@@ -189,11 +244,11 @@ function buildConfig(state, input) {
       ],
       coverage: { format: "auto", paths: [coveragePath] },
       sources: { include: [sourceGlob(sourcePath)] },
-      exclude: Array.isArray(old.exclude) ? old.exclude : []
+      exclude
     };
   };
-  makeScope("client", "client", "客户端", clientPath, input.clientCommand || state.clientCommand);
-  makeScope("server", "server", "服务端", serverPath, input.serverCommand || state.serverCommand);
+  await makeScope("client", "client", "客户端", clientPath, input.clientCommand || state.clientCommand);
+  await makeScope("server", "server", "服务端", serverPath, input.serverCommand || state.serverCommand);
   if (Object.keys(scopes).length === 0) {
     throw new HttpError(400, "至少需要指定客户端或服务端源码路径。");
   }
@@ -294,10 +349,17 @@ export async function startUiServer(options = {}) {
         const body = await readBody(req);
         const root = path.resolve(body.root || defaultRoot);
         const state = await inspectProject(root);
+        if (state.testCount === 0 && body.allowNoTests !== true) {
+          throw new HttpError(
+            422,
+            "项目中没有检测到测试文件。请先让项目补真实测试，再运行覆盖率；CovGate 不会生成测试。",
+            "no-tests"
+          );
+        }
         const existing = (await readJson(path.join(root, "covgate.config.json"))) || null;
         state.existing = existing || {};
         state.defaultCommand = state.commands[0]?.run || "";
-        const config = buildConfig(state, body);
+        const config = await buildConfig(state, body);
         const id = randomUUID();
         const configPath = path.join(root, ".covgate-ui-" + id + ".json");
         await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
@@ -387,7 +449,10 @@ export async function startUiServer(options = {}) {
       throw new HttpError(404, "Not found");
     } catch (error) {
       const status = error instanceof HttpError ? error.status : 500;
-      send(res, status, { error: error.message || String(error) });
+      send(res, status, {
+        error: error.message || String(error),
+        ...(error instanceof HttpError && error.code ? { code: error.code } : {})
+      });
     }
   });