covgate 0.0.0-stage → 0.2.0

package/src/setup/project.js

@@ -0,0 +1,316 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const FRAMEWORK_LABELS = {
+  vitest: "Vitest",
+  jest: "Jest",
+  playwright: "Playwright Test",
+  mocha: "Mocha",
+  ava: "AVA",
+  tap: "node-tap",
+  "node-test": "Node.js 内置 test runner"
+};
+
+const BROWSER_DEPS = new Set([
+  "react",
+  "react-dom",
+  "vue",
+  "svelte",
+  "solid-js",
+  "next",
+  "nuxt",
+  "@angular/core",
+  "preact"
+]);
+
+const SERVER_DEPS = new Set([
+  "express",
+  "fastify",
+  "koa",
+  "hapi",
+  "@hapi/hapi",
+  "@nestjs/core"
+]);
+
+const TEST_DEPS = [
+  ["vitest", "vitest"],
+  ["jest", "jest"],
+  ["@playwright/test", "playwright"],
+  ["mocha", "mocha"],
+  ["ava", "ava"],
+  ["tap", "tap"]
+];
+
+const SOURCE_EXT = "{js,jsx,ts,tsx,mjs,cjs}";
+
+export class SetupError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SetupError";
+    this.exitCode = 2;
+  }
+}
+
+/**
+ * @param {string} root
+ */
+export function packageJsonPath(root) {
+  return path.join(root, "package.json");
+}
+
+/**
+ * @param {string} root
+ */
+export async function readPackage(root) {
+  const file = packageJsonPath(root);
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error && error.code === "ENOENT") return null;
+    throw new SetupError("无法读取 package.json: " + error.message);
+  }
+  try {
+    return { path: file, text, data: JSON.parse(text.replace(/^\uFEFF/, "")) };
+  } catch (error) {
+    throw new SetupError("package.json 不是合法 JSON: " + error.message);
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {any} data
+ */
+export async function writePackage(root, data) {
+  await writeFile(
+    packageJsonPath(root),
+    JSON.stringify(data, null, 2) + "\n",
+    "utf8"
+  );
+}
+
+/**
+ * @param {string} root
+ * @param {any} pkg
+ */
+export function detectPackageManager(root, pkg) {
+  const declared = String(pkg?.packageManager || "").split("@")[0];
+  if (["npm", "pnpm", "yarn", "bun"].includes(declared)) return declared;
+  if (existsSync(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(path.join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(path.join(root, "bun.lockb")) || existsSync(path.join(root, "bun.lock"))) return "bun";
+  return "npm";
+}
+
+/**
+ * @param {any} pkg
+ */
+export function directDependencyNames(pkg) {
+  return new Set([
+    ...Object.keys(pkg?.dependencies || {}),
+    ...Object.keys(pkg?.devDependencies || {}),
+    ...Object.keys(pkg?.optionalDependencies || {})
+  ]);
+}
+
+/**
+ * @param {any} pkg
+ */
+export function hasCovgateDependency(pkg) {
+  return directDependencyNames(pkg).has("covgate");
+}
+
+/**
+ * @param {any} pkg
+ * @returns {{ id: string | null, label: string, hasCoverageScript: boolean }}
+ */
+export function detectFramework(pkg) {
+  const deps = directDependencyNames(pkg);
+  const scripts = pkg?.scripts || {};
+  for (const [dependency, id] of TEST_DEPS) {
+    if (deps.has(dependency)) {
+      return {
+        id,
+        label: FRAMEWORK_LABELS[id],
+        hasCoverageScript: Boolean(scripts["test:coverage"] || scripts.test)
+      };
+    }
+  }
+  const testScript = String(scripts["test:coverage"] || scripts.test || "");
+  if (/\bnode\s+--test\b/.test(testScript)) {
+    return {
+      id: "node-test",
+      label: FRAMEWORK_LABELS["node-test"],
+      hasCoverageScript: Boolean(scripts["test:coverage"])
+    };
+  }
+  return { id: null, label: "未检测到", hasCoverageScript: false };
+}
+
+/**
+ * @param {string} root
+ * @param {any} pkg
+ * @returns {"client" | "server"}
+ */
+export function detectProfile(root, pkg) {
+  const deps = directDependencyNames(pkg);
+  if (existsSync(path.join(root, "index.html"))) return "client";
+  if (pkg?.browser) 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} root
+ * @param {"client" | "server"} profile
+ * @returns {string | null}
+ */
+export function detectSourceGlob(root, profile) {
+  if (existsSync(path.join(root, "src"))) {
+    return "src/**/*." + SOURCE_EXT;
+  }
+  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;
+  }
+  if (existsSync(path.join(root, "app"))) {
+    return "app/**/*." + SOURCE_EXT;
+  }
+  if (existsSync(path.join(root, "lib"))) {
+    return "lib/**/*." + SOURCE_EXT;
+  }
+  return null;
+}
+
+/**
+ * @param {"vitest" | "jest" | string} frameworkId
+ */
+export function coverageScriptFor(frameworkId) {
+  if (frameworkId === "vitest") {
+    return "vitest run --coverage --coverage.reporter=json --coverage.reporter=lcov --passWithNoTests";
+  }
+  if (frameworkId === "jest") {
+    return "jest --coverage --coverageReporters=json --coverageReporters=lcov --passWithNoTests";
+  }
+  return null;
+}
+
+/**
+ * @param {"vitest" | "jest" | string} frameworkId
+ */
+export function testScriptFor(frameworkId) {
+  if (frameworkId === "vitest") return "vitest run";
+  if (frameworkId === "jest") return "jest";
+  return null;
+}
+
+/**
+ * Add idempotent package scripts. Existing user scripts are preserved unless
+ * force is true.
+ * @param {any} pkg
+ * @param {"vitest" | "jest" | string} frameworkId
+ * @param {{ force?: boolean, testCommand?: string }} [options]
+ */
+export function addScripts(pkg, frameworkId, options = {}) {
+  pkg.scripts = pkg.scripts || {};
+  const changed = [];
+  if (!pkg.scripts["coverage:gate"] || options.force) {
+    pkg.scripts["coverage:gate"] = "covgate run";
+    changed.push("coverage:gate");
+  }
+  if (options.testCommand) {
+    if (!pkg.scripts["test:coverage"] || options.force) {
+      pkg.scripts["test:coverage"] = options.testCommand;
+      changed.push("test:coverage");
+    }
+  } else {
+    const coverageScript = coverageScriptFor(frameworkId);
+    if (coverageScript && (!pkg.scripts["test:coverage"] || options.force)) {
+      pkg.scripts["test:coverage"] = coverageScript;
+      changed.push("test:coverage");
+    }
+    const testScript = testScriptFor(frameworkId);
+    if (testScript && !pkg.scripts.test) {
+      pkg.scripts.test = testScript;
+      changed.push("test");
+    }
+  }
+  return changed;
+}
+
+/**
+ * @param {string} root
+ * @param {"npm" | "pnpm" | "yarn" | "bun"} packageManager
+ * @param {boolean} dryRun
+ * @param {{ stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream }} [io]
+ */
+export async function installVitest(root, packageManager, dryRun = false, io = {}) {
+  const packages = ["vitest", "@vitest/coverage-v8"];
+  const command =
+    packageManager === "pnpm"
+      ? "pnpm add -D --ignore-scripts " + packages.join(" ")
+      : packageManager === "yarn"
+        ? "yarn add -D --ignore-scripts " + packages.join(" ")
+        : packageManager === "bun"
+          ? "bun add -d --ignore-scripts " + packages.join(" ")
+          : "npm install --save-dev --ignore-scripts --no-audit --no-fund " + packages.join(" ");
+  if (dryRun) {
+    (io.stdout || process.stdout).write("[dry-run] " + command + "\n");
+    return { ok: true, command, dryRun: true };
+  }
+  return new Promise((resolve) => {
+    const timeout = 180000;
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const child = spawn(command, {
+      cwd: root,
+      shell: true,
+      detached: process.platform !== "win32",
+      stdio: "inherit",
+      windowsHide: false
+    });
+    const timer = setTimeout(() => {
+      try {
+        if (process.platform === "win32" && child.pid) {
+          spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+            stdio: "ignore",
+            windowsHide: true
+          });
+        } else if (child.pid) {
+          process.kill(-child.pid, "SIGKILL");
+        }
+      } catch {
+        try { child.kill(); } catch {}
+      }
+      (io.stderr || process.stderr).write("[covgate] 安装测试框架超时（180s），已终止。\n");
+      finish({ ok: false, command, timedOut: true });
+    }, timeout);
+    child.on("error", (error) => {
+      (io.stderr || process.stderr).write("[covgate] 无法启动测试框架安装：" + error.message + "\n");
+      finish({ ok: false, command });
+    });
+    child.on("exit", (code) => {
+      finish({ ok: code === 0, command, code });
+    });
+  });
+}
+
+/**
+ * @param {string} root
+ * @param {string} file
+ */
+export function displayPath(root, file) {
+  const relative = path.relative(root, file).replaceAll("\\", "/");
+  return relative && !relative.startsWith("..") ? relative : file;
+}

package/src/setup/prompt.js

@@ -0,0 +1,43 @@
+import readline from "node:readline/promises";
+
+/**
+ * @param {{
+ *   input?: NodeJS.ReadableStream & { isTTY?: boolean },
+ *   output?: NodeJS.WritableStream & { isTTY?: boolean }
+ * }} [io]
+ */
+export function canPrompt(io = {}) {
+  const input = io.input || process.stdin;
+  const output = io.output || process.stderr;
+  return Boolean(input.isTTY && output.isTTY && !process.env.CI);
+}
+
+/**
+ * @param {string} question
+ * @param {{
+ *   defaultYes?: boolean,
+ *   forceYes?: boolean,
+ *   input?: any,
+ *   output?: any
+ * }} [options]
+ */
+export async function askYesNo(question, options = {}) {
+  const forceYes =
+    options.forceYes === true || process.env.COVGATE_SETUP_ASSUME_YES === "1";
+  if (forceYes) return true;
+  const input = options.input || process.stdin;
+  const output = options.output || process.stderr;
+  if (!input.isTTY || !output.isTTY) return false;
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    const suffix = options.defaultYes === false ? " [y/N] " : " [Y/n] ";
+    const answer = (await rl.question(question + suffix)).trim().toLowerCase();
+    if (!answer) return options.defaultYes !== false;
+    return answer === "y" || answer === "yes" || answer === "是";
+  } catch {
+    return false;
+  } finally {
+    rl.close();
+  }
+}

package/src/util.js

@@ -0,0 +1,163 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const IS_WINDOWS = process.platform === "win32";
+
+/** @param {string} value */
+export function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+/** @param {unknown} value */
+export function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @param {string} absPath */
+export function pathKey(absPath) {
+  const normalized = path.normalize(absPath);
+  return IS_WINDOWS ? normalized.toLowerCase() : normalized;
+}
+
+/**
+ * Canonical identity for matching files across coverage tools, source globs,
+ * Windows drive-letter casing and mixed slash styles.
+ * @param {string} absPath
+ */
+export function canonicalPath(absPath) {
+  return pathKey(path.resolve(absPath));
+}
+
+/**
+ * @param {string} absPath
+ * @param {string} root
+ */
+export function relativeDisplay(absPath, root) {
+  return toPosix(path.relative(root, absPath));
+}
+
+/** @param {number} ms */
+export function formatDuration(ms) {
+  if (ms < 1_000) return `${Math.max(0, Math.round(ms))}ms`;
+  if (ms < 60_000) return `${(ms / 1_000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60_000);
+  const seconds = Math.round((ms % 60_000) / 1_000);
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * @param {number} covered
+ * @param {number} total
+ * @param {number} [fractionDigits]
+ */
+export function percentOf(covered, total, fractionDigits = 2) {
+  if (total === 0) return null;
+  return Number(((covered / total) * 100).toFixed(fractionDigits));
+}
+
+/** @param {number | null} value */
+export function displayPercent(value) {
+  return value === null || value === undefined ? "N/A" : `${value.toFixed(2)}%`;
+}
+
+/** @param {number} value */
+export function formatThreshold(value) {
+  return Number.isInteger(value) ? String(value) : String(value);
+}
+
+/** @param {number} value @param {number} min @param {number} max */
+export function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** @param {string} text @param {number} max */
+export function tail(text, max = 20_000) {
+  if (text.length <= max) return text;
+  return `… 已截断 ${text.length - max} 个字符 …\n${text.slice(-max)}`;
+}
+
+/** @param {string} text */
+export function sha256(text) {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+/** @param {string} text */
+export function escapeMarkdown(text) {
+  return text.replaceAll("|", "\\|").replaceAll("\n", "<br>");
+}
+
+/**
+ * Parse YYYY-MM-DD as an inclusive local end-of-day date.
+ * @param {string} value
+ * @returns {Date | null}
+ */
+export function parseExpiryDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return null;
+  const [year, month, day] = value.split("-").map(Number);
+  const date = new Date(year, month - 1, day, 23, 59, 59, 999);
+  if (
+    date.getFullYear() !== year ||
+    date.getMonth() !== month - 1 ||
+    date.getDate() !== day
+  ) {
+    return null;
+  }
+  return date;
+}
+
+/** @param {Date} [now] */
+export function todayIso(now = new Date()) {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/** @param {string} filePath */
+export async function readJsonFile(filePath) {
+  const text = await readFile(filePath, "utf8");
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new SyntaxError(`无法解析 JSON 文件 ${filePath}: ${error.message}`);
+  }
+}
+
+/** @param {string} filePath @param {string} content */
+export async function writeTextFile(filePath, content) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content, "utf8");
+}
+
+/** @param {string} text @param {number} max */
+export function firstLine(text, max = 240) {
+  const line = text.split(/\r?\n/, 1)[0] ?? "";
+  return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+
+/** @param {PropertyKey} key */
+export function keyToString(key) {
+  return typeof key === "symbol" ? key.description ?? String(key) : String(key);
+}
+
+/**
+ * @template T
+ * @param {T[]} values
+ * @param {(value: T) => string} key
+ * @returns {T[]}
+ */
+export function uniqueBy(values, key) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    const id = key(value);
+    if (!seen.has(id)) {
+      seen.add(id);
+      result.push(value);
+    }
+  }
+  return result;
+}

package/src/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+
+export const VERSION = pkg.version;
+export const TOOL_NAME = "covgate";

package/templates/AGENTS.md.snippet.md

@@ -0,0 +1,9 @@
+## 覆盖率门禁（完成定义）
+
+- 任何代码修改完成后，必须运行 `npx --no-install covgate run --json`；**退出码 0 才能结束任务**。
+- 退出码 `1`：补测试或修实现；`2`：修配置；`3`：修测试命令/覆盖率报告。不要绕过。
+- 禁止降低 `covgate.config.json` 中的门槛、扩大 exclude、删除豁免检查来让门禁通过。任何配置改动都必须由人类评审。
+- 禁止 `istanbul ignore`、`c8 ignore`、`v8 ignore`、`node:coverage ignore`。
+- 确实不可达的代码使用 `covgate-ignore-next-line`、`covgate-ignore-start/end` 或 `covgate-ignore-file`，并写具体原因、owner 和 expires。
+- 新增或修改的源码必须出现在覆盖率报告中；`sources.include` 是范围事实来源。
+- 交付时附上 `covgate run` 的结果摘要；不要只说“已写测试”。

package/templates/agent-stop-hook.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Generic agent stop hook: runs the gate and blocks completion on failure.
+# Put it in scripts/ and call it from your agent's Stop hook configuration.
+set -eu
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+exec npx --no-install covgate run --json

package/templates/covgate.config.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "./node_modules/covgate/schema/covgate.schema.json",
+  "version": 1,
+  "scopes": {
+    "client": {
+      "profile": "client",
+      "label": "客户端",
+      "commands": [
+        {
+          "name": "客户端测试与覆盖率",
+          "run": "npm --prefix web run test -- --coverage",
+          "timeoutSeconds": 900
+        }
+      ],
+      "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/**/__tests__/**",
+          "reason": "测试目录，不是产品运行时代码",
+          "owner": "web-platform"
+        },
+        {
+          "pattern": "web/src/**/*.d.ts",
+          "reason": "类型声明文件，没有运行时代码",
+          "owner": "web-platform"
+        },
+        {
+          "pattern": "web/src/generated/**",
+          "reason": "由 OpenAPI 生成，仓库不手工维护，生成器有独立测试",
+          "owner": "api-platform",
+          "expires": "2027-03-31"
+        }
+      ]
+    },
+    "server": {
+      "profile": "server",
+      "label": "服务端",
+      "commands": [
+        {
+          "name": "服务端测试与覆盖率",
+          "run": "npm --prefix api run test -- --coverage",
+          "timeoutSeconds": 1200
+        }
+      ],
+      "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"
+        },
+        {
+          "pattern": "api/src/**/*.d.ts",
+          "reason": "类型声明文件，没有运行时代码",
+          "owner": "api-platform"
+        }
+      ]
+    }
+  },
+  "waivers": {
+    "minReasonLength": 8,
+    "requireOwner": true,
+    "stale": "fail",
+    "expiry": "fail"
+  },
+  "reports": {
+    "dir": ".covgate",
+    "formats": [
+      "json",
+      "markdown"
+    ]
+  }
+}

package/templates/github-actions-coverage.yml

@@ -0,0 +1,41 @@
+name: coverage-gate
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: coverage-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      # covgate 需要通过 file:、workspace 或私有 registry 安装。
+      # 如果使用 npm link / 本地路径，请改成 CI 可复现的安装方式。
+      - name: Run coverage gate
+        run: npx --no-install covgate run --json
+
+      - name: Upload audit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: covgate-report
+          path: .covgate/
+          if-no-files-found: ignore

package/templates/gitignore

@@ -0,0 +1,5 @@
+# CovGate report artifacts
+/.covgate/
+
+# Typical local coverage output (root only; do not ignore src/coverage)
+/coverage/