covgate 0.0.0-stage → 0.2.1

package/src/setup/agent.js

@@ -0,0 +1,329 @@
+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 或删除测试来让门禁通过；这类改动必须由人类评审。",
+  "- 行为变更必须新增或更新覆盖该行为的真实测试；不能把“门禁失败”当作完成理由，也不得用空报告、`--passWithNoTests`、ignore 或降低门槛绕过。",
+  "- 失败详情在 `.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,129 @@
+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,
+ *   scopes?: Array<{ name: string, profile: "client" | "server", label?: string, sourceGlob: string }>,
+ *   profile?: "client" | "server",
+ *   sourceGlob?: string,
+ *   command: string,
+ *   coveragePath: string
+ * }} options
+ */
+export async function buildStarterConfig({
+  root,
+  scopes,
+  profile,
+  sourceGlob,
+  command,
+  coveragePath
+}) {
+  const specs =
+    scopes && scopes.length > 0
+      ? scopes
+      : [
+          {
+            name: profile,
+            profile,
+            label: profile === "client" ? "客户端" : "服务端",
+            sourceGlob
+          }
+        ];
+  const scopeConfigs = {};
+  for (const spec of specs) {
+    if (!spec.profile || !spec.sourceGlob || !spec.name) continue;
+    const label =
+      spec.label || (spec.profile === "client" ? "客户端" : "服务端");
+    const exclude = await pickExcludes(root, spec.sourceGlob);
+    scopeConfigs[spec.name] = {
+      profile: spec.profile,
+      label,
+      commands: [
+        {
+          name: label + "测试与覆盖率",
+          run: command,
+          timeoutSeconds: 900
+        }
+      ],
+      coverage: {
+        format: "auto",
+        paths: [coveragePath]
+      },
+      sources: {
+        include: [spec.sourceGlob]
+      },
+      exclude
+    };
+  }
+  return {
+    $schema: "./node_modules/covgate/schema/covgate.schema.json",
+    version: 1,
+    scopes: scopeConfigs,
+    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;
+}