covgate 0.0.0-stage → 0.2.1

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,10 @@
+## 覆盖率门禁（完成定义）
+
+- 任何代码修改完成后，必须运行 `npx --no-install covgate run --json`；**退出码 0 才能结束任务**。
+- 退出码 `1`：补测试或修实现；`2`：修配置；`3`：修测试命令/覆盖率报告。不要绕过。
+- 禁止降低 `covgate.config.json` 中的门槛、扩大 exclude、删除豁免检查来让门禁通过。任何配置改动都必须由人类评审。
+- **行为变更必须新增或更新覆盖该行为的真实测试**；不能把“门禁失败”当作完成理由，也不得用空报告、`--passWithNoTests`、ignore 或降低门槛绕过。
+- 禁止 `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/

package/templates/pre-commit

@@ -0,0 +1,10 @@
+#!/bin/sh
+# CovGate pre-commit hook (optional)
+# 安装：
+#   cp templates/pre-commit .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+# 该 hook 会跑完整测试套件；如果团队只在 CI 跑覆盖率，可以不启用。
+set -eu
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+exec npx --no-install covgate run