covgate 0.0.0-stage → 0.2.1

package/src/setup/index.js

@@ -0,0 +1,270 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  SetupError,
+  addScripts,
+  coverageScriptFor,
+  detectFramework,
+  detectPackageManager,
+  detectProfile,
+  detectScopeSpecs,
+  detectSourceGlob,
+  displayPath,
+  installVitest,
+  readPackage,
+  writePackage
+} from "./project.js";
+import { buildStarterConfig } from "./config.js";
+import { scaffoldAgent } from "./agent.js";
+import { askYesNo, canPrompt } from "./prompt.js";
+
+const DEFAULT_COVERAGE_PATH = "coverage/coverage-final.json";
+
+/**
+ * @param {string} root
+ * @param {string} value
+ */
+function normalizeGlob(root, value) {
+  return String(value || "")
+    .trim()
+    .replaceAll("\\", "/")
+    .replace(/^\.\//, "");
+}
+
+/**
+ * @param {{
+ *   root?: string,
+ *   yes?: boolean,
+ *   installFramework?: boolean,
+ *   profile?: "client" | "server",
+ *   source?: string,
+ *   coverage?: string,
+ *   testCommand?: string,
+ *   noAgent?: boolean,
+ *   noConfig?: boolean,
+ *   force?: boolean,
+ *   dryRun?: boolean,
+ *   postinstall?: boolean,
+ *   log?: (message: string) => void,
+ *   stderr?: NodeJS.WritableStream
+ * }} options
+ */
+export async function runSetup(options = {}) {
+  const root = path.resolve(options.root || process.cwd());
+  const log = options.log || ((message) => process.stdout.write(message + String.fromCharCode(10)));
+  const writeError = options.stderr || process.stderr;
+  const project = await readPackage(root);
+  if (!project) {
+    throw new SetupError("当前目录没有 package.json。CovGate 的自动配置目前面向 Node.js 项目。");
+  }
+  let pkg = project.data;
+  const packageManager = detectPackageManager(root, pkg);
+  log("[covgate] 项目: " + root);
+  log("[covgate] 包管理器: " + packageManager);
+
+  let framework = detectFramework(pkg);
+  let installedFramework = false;
+
+  if (!framework.id && options.installFramework !== false) {
+    const approved =
+      options.yes === true
+        ? true
+        : await askYesNo(
+            "[covgate] 未检测到测试框架。是否安装 Vitest + @vitest/coverage-v8？",
+            { defaultYes: true, output: options.stderr || process.stderr }
+          );
+    if (approved) {
+      log("[covgate] 安装 Vitest 与 V8 覆盖率插件……");
+      const result = await installVitest(root, packageManager, options.dryRun === true, {
+        stdout: process.stdout,
+        stderr: writeError
+      });
+      if (result.ok) {
+        installedFramework = true;
+        framework = { id: "vitest", label: "Vitest", hasCoverageScript: true };
+        const refreshed = await readPackage(root);
+        if (refreshed) pkg = refreshed.data;
+      } else {
+        log("[covgate] 自动安装失败。可手动运行: " + result.command);
+      }
+    } else {
+      log("[covgate] 跳过测试框架安装。");
+    }
+  }
+
+  let packageChanged = false;
+  const scriptChanges = addScripts(pkg, framework.id, {
+    testCommand: options.testCommand,
+    force: options.force === true
+  });
+  if (scriptChanges.length > 0) {
+    packageChanged = true;
+    if (!options.dryRun) await writePackage(root, pkg);
+    log("[covgate] package.json 脚本: " + scriptChanges.join(", "));
+  }
+
+  let testCommand = options.testCommand;
+  if (!testCommand && pkg.scripts && pkg.scripts["test:coverage"]) {
+    testCommand = "npm run test:coverage";
+  }
+
+  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 coveragePath = normalizeGlob(root, options.coverage || DEFAULT_COVERAGE_PATH);
+  const configPath = path.join(root, "covgate.config.json");
+  let configWritten = false;
+
+  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,
+        scopes: scopeSpecs,
+        command: testCommand,
+        coveragePath
+      });
+      if (!options.dryRun) {
+        await mkdir(path.dirname(configPath), { recursive: true });
+        await writeFile(configPath, JSON.stringify(config, null, 2) + String.fromCharCode(10), "utf8");
+      }
+      configWritten = true;
+      log(
+        "[covgate] 生成 " +
+          displayPath(root, configPath) +
+          "（" +
+          scopeSpecs
+            .map((scope) => scope.profile + "：" + scope.sourceGlob)
+            .join("，") +
+          "）"
+      );
+      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 指定。");
+    }
+  }
+
+  let agentChanges = [];
+  if (options.noAgent !== true) {
+    agentChanges = await scaffoldAgent({
+      root,
+      packageManager,
+      force: options.force === true,
+      dryRun: options.dryRun === true,
+      log
+    });
+  }
+
+  const summary = {
+    root,
+    packageManager,
+    framework: framework.id || null,
+    installedFramework,
+    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,
+    packageChanged,
+    packageScripts: scriptChanges,
+    agentChanges,
+    dryRun: options.dryRun === true,
+    postinstall: options.postinstall === true
+  };
+
+  log("");
+  log("[covgate] 完成。");
+  if (summary.configPath) {
+    log("[covgate] 配置: " + displayPath(root, summary.configPath));
+  }
+  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.*");
+  }
+  return summary;
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   stderr?: NodeJS.WritableStream
+ * }} options
+ */
+export async function runPostinstall(options) {
+  const stderr = options.stderr || process.stderr;
+  const root = path.resolve(options.root || process.cwd());
+  const project = await readPackage(root).catch(() => null);
+  if (!project) return 0;
+  if (project.data?.name === "covgate") return 0;
+  if (process.env.COVGATE_SKIP_SETUP === "1") return 0;
+  if (process.env.CI) return 0;
+  if (process.env.npm_config_global === "true") return 0;
+  const hasDirectDependency =
+    project.data?.dependencies?.covgate ||
+    project.data?.devDependencies?.covgate ||
+    project.data?.optionalDependencies?.covgate;
+  if (!hasDirectDependency) return 0;
+
+  if (!canPrompt({ output: stderr }) && process.env.COVGATE_SETUP_ASSUME_YES !== "1") {
+    stderr.write(
+      "[covgate] 已安装。未检测到交互终端，未自动配置；可运行 npx covgate setup。\n"
+    );
+    return 0;
+  }
+
+  try {
+    await runSetup({
+      root,
+      postinstall: true,
+      installFramework: true,
+      stderr,
+      log: (message) => console.log(message)
+    });
+  } catch (error) {
+    stderr.write("[covgate] 安装后自动配置失败：" + (error?.message || error) + "\n");
+    stderr.write("[covgate] 可稍后运行 npx covgate setup。\n");
+  }
+  return 0;
+}

package/src/setup/project.js

@@ -0,0 +1,391 @@
+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);
+  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
+ * @returns {string | null}
+ */
+export function detectSourceGlob(root, profile) {
+  if (existsSync(path.join(root, "src"))) {
+    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 sourceGlobForDir(candidate);
+  }
+  if (existsSync(path.join(root, "app"))) {
+    return sourceGlobForDir("app");
+  }
+  if (existsSync(path.join(root, "lib"))) {
+    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";
+  }
+  if (frameworkId === "jest") {
+    return "jest --coverage --coverageReporters=json --coverageReporters=lcov";
+  }
+  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();
+  }
+}