covgate 0.0.0-stage → 0.2.0

package/src/setup/agent.js

@@ -0,0 +1,327 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const START = "<!-- covgate:start -->";
+const END = "<!-- covgate:end -->";
+
+const AGENT_BLOCK = [
+  START,
+  "## CovGate 覆盖率门禁（完成定义）",
+  "",
+  "- 修改代码后必须运行 `npx --no-install covgate run --json`；退出码 0 才能结束任务。",
+  "- 客户端覆盖率必须 100%，服务端不低于 95%；不得降低 `covgate.config.json` 中的门槛。",
+  "- 禁止 `istanbul ignore`、`c8 ignore`、`v8 ignore`、`node:coverage ignore`。",
+  "- 确实不可达的代码使用 `covgate-ignore-next-line`、`covgate-ignore-start/end` 或 `covgate-ignore-file`，写具体原因、owner 和 expires。",
+  "- 禁止通过扩大 exclude、缩小 sources.include 或删除测试来让门禁通过；这类改动必须由人类评审。",
+  "- 失败详情在 `.covgate/report.json` 的 scopes/issues/waivers 中；修复后重跑。",
+  "",
+  "也可运行 `npm run coverage:gate -- --json`。Agent Stop hook 可调用 `scripts/covgate-agent-gate.ps1`（Windows）或 `scripts/covgate-agent-gate.sh`。",
+  "<!-- 由 covgate setup 生成；保留标记以便幂等更新。 -->",
+  END
+].join("\n");
+
+const CURSOR_RULE = [
+  "---",
+  "description: CovGate coverage gate",
+  "alwaysApply: true",
+  "---",
+  "",
+  "# CovGate 覆盖率门禁",
+  "",
+  "任何代码修改后运行 `npx --no-install covgate run --json`，退出码 0 才能结束。",
+  "客户端必须 100%，服务端至少 95%。禁止原生 ignore；豁免必须写原因、owner、expires。",
+  ""
+].join("\n");
+
+const SH_SCRIPT = [
+  "#!/bin/sh",
+  "# Generated by covgate setup. Use as an agent Stop hook or pre-commit step.",
+  "set -eu",
+  'root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"',
+  'cd "$root"',
+  "exec npx --no-install covgate run --json"
+].join("\n") + "\n";
+
+const PS1_SCRIPT = [
+  "# Generated by covgate setup. Use as an agent Stop hook or pre-commit step.",
+  "$ErrorActionPreference = 'Stop'",
+  "$root = git rev-parse --show-toplevel 2>$null",
+  "if (-not $root) { $root = (Get-Location).Path }",
+  "Set-Location $root",
+  "npx --no-install covgate run --json",
+  "exit $LASTEXITCODE"
+].join("\n") + "\n";
+
+function hasManagedBlock(text) {
+  return text.includes(START) && text.includes(END);
+}
+
+/**
+ * @param {string} text
+ * @param {string} block
+ */
+function replaceManagedBlock(text, block) {
+  const start = text.indexOf(START);
+  const end = text.indexOf(END);
+  if (start === -1 || end === -1 || end < start) return text + "\n\n" + block + "\n";
+  return text.slice(0, start) + block + text.slice(end + END.length);
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   file: string,
+ *   block: string,
+ *   force?: boolean,
+ *   dryRun?: boolean,
+ *   log: (message: string) => void,
+ *   changes: string[]
+ * }} options
+ */
+async function ensureManagedFile({ root, file, block, force, dryRun, log, changes }) {
+  const absolute = path.join(root, file);
+  let current = null;
+  try {
+    current = await readFile(absolute, "utf8");
+  } catch (error) {
+    if (!error || error.code !== "ENOENT") throw error;
+  }
+  if (current !== null && hasManagedBlock(current) && !force) {
+    log("  = " + file + " 已有 CovGate 区块，跳过");
+    return;
+  }
+  const next =
+    current === null
+      ? block + "\n"
+      : current.endsWith("\n")
+        ? current + "\n" + block + "\n"
+        : current + "\n\n" + block + "\n";
+  const finalContent =
+    current !== null && force && hasManagedBlock(current)
+      ? replaceManagedBlock(current, block)
+      : next;
+  if (!dryRun) {
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await writeFile(absolute, finalContent, "utf8");
+  }
+  changes.push(file);
+  log("  + " + file);
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   file: string,
+ *   content: string,
+ *   force?: boolean,
+ *   dryRun?: boolean,
+ *   executable?: boolean,
+ *   log: (message: string) => void,
+ *   changes: string[]
+ * }} options
+ */
+async function ensureNewFile({ root, file, content, force, dryRun, executable, log, changes }) {
+  const absolute = path.join(root, file);
+  if (existsSync(absolute) && !force) {
+    log("  = " + file + " 已存在，保留");
+    return;
+  }
+  if (!dryRun) {
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await writeFile(absolute, content, "utf8");
+    if (executable && process.platform !== "win32") {
+      await chmod(absolute, 0o755).catch(() => {});
+    }
+  }
+  changes.push(file);
+  log("  + " + file);
+}
+
+/**
+ * @param {string} root
+ * @param {boolean} dryRun
+ * @param {(message: string) => void} log
+ * @param {string[]} changes
+ */
+async function ensureGitignore(root, dryRun, log, changes) {
+  const file = path.join(root, ".gitignore");
+  let current = "";
+  try {
+    current = await readFile(file, "utf8");
+  } catch (error) {
+    if (!error || error.code !== "ENOENT") throw error;
+  }
+  const lines = current.split(/\n/);
+  const additions = ["/.covgate/", "/coverage/"].filter((entry) => !lines.includes(entry));
+  if (additions.length === 0) {
+    log("  = .gitignore 已包含覆盖率产物");
+    return;
+  }
+  const next =
+    current +
+    (current && !current.endsWith("\n") ? "\n" : "") +
+    additions.join("\n") +
+    "\n";
+  if (!dryRun) await writeFile(file, next, "utf8");
+  changes.push(".gitignore");
+  log("  + .gitignore（" + additions.join(", ") + "）");
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   packageManager: string,
+ *   force?: boolean,
+ *   dryRun?: boolean,
+ *   log: (message:string) => void
+ * }} options
+ */
+export async function scaffoldAgent({ root, packageManager, force = false, dryRun = false, log }) {
+  const changes = [];
+  const exists = (file) => existsSync(path.join(root, file));
+  await ensureManagedFile({
+    root,
+    file: "AGENTS.md",
+    block: AGENT_BLOCK,
+    force,
+    dryRun,
+    log,
+    changes
+  });
+
+  if (exists("CLAUDE.md") || exists(".claude")) {
+    await ensureManagedFile({
+      root,
+      file: "CLAUDE.md",
+      block: AGENT_BLOCK,
+      force,
+      dryRun,
+      log,
+      changes
+    });
+  }
+  if (exists(".cursor")) {
+    await ensureNewFile({
+      root,
+      file: ".cursor/rules/covgate.mdc",
+      content: CURSOR_RULE,
+      force,
+      dryRun,
+      log,
+      changes
+    });
+  }
+  if (exists(".github/copilot-instructions.md")) {
+    await ensureManagedFile({
+      root,
+      file: ".github/copilot-instructions.md",
+      block: AGENT_BLOCK,
+      force,
+      dryRun,
+      log,
+      changes
+    });
+  }
+
+  await ensureNewFile({
+    root,
+    file: "scripts/covgate-agent-gate.sh",
+    content: SH_SCRIPT,
+    force,
+    dryRun,
+    executable: true,
+    log,
+    changes
+  });
+  await ensureNewFile({
+    root,
+    file: "scripts/covgate-agent-gate.ps1",
+    content: PS1_SCRIPT,
+    force,
+    dryRun,
+    log,
+    changes
+  });
+
+  if (exists(".github")) {
+    await ensureNewFile({
+      root,
+      file: ".github/workflows/covgate.yml",
+      content: buildWorkflow(packageManager),
+      force,
+      dryRun,
+      log,
+      changes
+    });
+  }
+  await ensureGitignore(root, dryRun, log, changes);
+  return changes;
+}
+
+/**
+ * @param {string} packageManager
+ */
+export function buildWorkflow(packageManager) {
+  const setup = ["      - uses: actions/checkout@v4"];
+  let install = "      - run: npm ci";
+  if (packageManager === "pnpm") {
+    setup.push(
+      "      - uses: pnpm/action-setup@v4",
+      "        with:",
+      "          version: 9",
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 22",
+      "          cache: pnpm"
+    );
+    install = "      - run: pnpm install --frozen-lockfile";
+  } else if (packageManager === "yarn") {
+    setup.push(
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 22",
+      "          cache: yarn"
+    );
+    install = "      - run: corepack enable\n      - run: yarn install --immutable";
+  } else if (packageManager === "bun") {
+    setup.push("      - uses: oven-sh/setup-bun@v2");
+    install = "      - run: bun install --frozen-lockfile";
+  } else {
+    setup.push(
+      "      - uses: actions/setup-node@v4",
+      "        with:",
+      "          node-version: 22",
+      "          cache: npm"
+    );
+  }
+  return [
+    "name: coverage-gate",
+    "",
+    "on:",
+    "  pull_request:",
+    "  push:",
+    "    branches: [main]",
+    "",
+    "permissions:",
+    "  contents: read",
+    "",
+    "jobs:",
+    "  coverage:",
+    "    runs-on: ubuntu-latest",
+    "    timeout-minutes: 30",
+    "    steps:",
+    ...setup,
+    install,
+    "      - name: Run CovGate",
+    "        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",
+    ""
+  ].join("\n");
+}

package/src/setup/config.js

@@ -0,0 +1,112 @@
+import { expandFiles, matchGlob } from "../glob.js";
+import { relativeDisplay } from "../util.js";
+
+const TEST_EXCLUDE_CANDIDATES = [
+  {
+    pattern: "**/*.test.*",
+    reason: "测试文件，不是产品运行时代码"
+  },
+  {
+    pattern: "**/*.spec.*",
+    reason: "测试文件，不是产品运行时代码"
+  },
+  {
+    pattern: "**/__tests__/**",
+    reason: "测试目录，不是产品运行时代码"
+  },
+  {
+    pattern: "**/*.d.ts",
+    reason: "类型声明文件，没有运行时代码"
+  }
+];
+
+/**
+ * Only add exclusions that currently match something. CovGate intentionally
+ * fails stale exclusions, so a starter config must not contain guesses that
+ * match zero files.
+ *
+ * @param {string} root
+ * @param {string} sourceGlob
+ */
+async function pickExcludes(root, sourceGlob) {
+  let files = [];
+  try {
+    files = await expandFiles([sourceGlob], root);
+  } catch {
+    return [];
+  }
+  const relative = files.map((file) => relativeDisplay(file, root));
+  return TEST_EXCLUDE_CANDIDATES.filter((entry) =>
+    relative.some((file) => matchGlob(file, entry.pattern))
+  );
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   profile: "client" | "server",
+ *   sourceGlob: string,
+ *   command: string,
+ *   coveragePath: string
+ * }} options
+ */
+export async function buildStarterConfig({
+  root,
+  profile,
+  sourceGlob,
+  command,
+  coveragePath
+}) {
+  const exclude = await pickExcludes(root, sourceGlob);
+  const label = profile === "client" ? "客户端" : "服务端";
+  return {
+    $schema: "./node_modules/covgate/schema/covgate.schema.json",
+    version: 1,
+    scopes: {
+      [profile]: {
+        profile,
+        label,
+        commands: [
+          {
+            name: label + "测试与覆盖率",
+            run: command,
+            timeoutSeconds: 900
+          }
+        ],
+        coverage: {
+          format: "auto",
+          paths: [coveragePath]
+        },
+        sources: {
+          include: [sourceGlob]
+        },
+        exclude
+      }
+    },
+    waivers: {
+      minReasonLength: 8,
+      requireOwner: false,
+      stale: "fail",
+      expiry: "fail"
+    },
+    reports: {
+      dir: ".covgate",
+      formats: ["json", "markdown"]
+    }
+  };
+}
+
+/**
+ * @param {any} config
+ */
+export function configSummary(config) {
+  const scopes = Object.entries(config.scopes || {}).map(([name, scope]) => ({
+    name,
+    profile: scope.profile,
+    command: scope.commands?.[0]?.run,
+    source: scope.sources?.include?.[0],
+    coverage: scope.coverage?.paths?.[0],
+    exclusions: scope.exclude?.length || 0
+  }));
+  return scopes;
+}

package/src/setup/index.js

@@ -0,0 +1,242 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  SetupError,
+  addScripts,
+  coverageScriptFor,
+  detectFramework,
+  detectPackageManager,
+  detectProfile,
+  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";
+  }
+
+  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) || "");
+  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 && sourceGlob) {
+    if (existsSync(configPath) && options.force !== true) {
+      log("[covgate] " + displayPath(root, configPath) + " 已存在，保留现有配置");
+    } else {
+      const config = await buildStarterConfig({
+        root,
+        profile,
+        sourceGlob,
+        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) +
+          "（" +
+          profile +
+          "，源码 " +
+          sourceGlob +
+          "）"
+      );
+      if (framework.id && !coverageScriptFor(framework.id) && !options.testCommand) {
+        log("[covgate] 注意：该测试框架的覆盖率命令需要你确认报告路径。");
+      }
+    }
+  } else if (options.noConfig !== true) {
+    if (!testCommand) {
+      log("[covgate] 未找到可用的覆盖率测试命令，跳过 covgate.config.json。");
+    }
+    if (!sourceGlob) {
+      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,
+    sourceGlob: sourceGlob || null,
+    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));
+  }
+  log("[covgate] 运行门禁: " + (summary.dryRun ? "npx covgate run" : "npx --no-install covgate run"));
+  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;
+}