covgate 0.0.0-stage → 0.2.0

package/src/config.js

@@ -0,0 +1,442 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { isPlainObject, sha256 } from "./util.js";
+
+export const CONFIG_FILENAME = "covgate.config.json";
+export const CONFIG_VERSION = 1;
+export const METRICS = ["lines", "statements", "functions", "branches"];
+export const PROFILES = ["client", "server"];
+
+/**
+ * These floors are part of the product contract and are enforced in addition
+ * to the thresholds in the config. A project can raise a threshold, never lower
+ * it. Client code must be 100% on every metric; server code at least 95%.
+ */
+export const PROFILE_FLOORS = {
+  client: { lines: 100, statements: 100, functions: 100, branches: 100 },
+  server: { lines: 95, statements: 95, functions: 95, branches: 95 }
+};
+
+const CONFIG_KEYS = new Set(["$schema", "version", "scopes", "waivers", "reports"]);
+const SCOPE_KEYS = new Set([
+  "profile",
+  "label",
+  "commands",
+  "coverage",
+  "thresholds",
+  "sources",
+  "exclude"
+]);
+const COMMAND_KEYS = new Set(["name", "run", "cwd", "timeoutSeconds", "env"]);
+const COVERAGE_KEYS = new Set(["format", "paths"]);
+const SOURCE_KEYS = new Set(["include"]);
+const WAIVER_KEYS = new Set([
+  "minReasonLength",
+  "requireOwner",
+  "stale",
+  "expiry"
+]);
+const REPORT_KEYS = new Set(["dir", "formats"]);
+const EXCLUDE_KEYS = new Set(["pattern", "reason", "owner", "expires", "ticket"]);
+const COVERAGE_FORMATS = new Set(["auto", "istanbul", "lcov"]);
+const REPORT_FORMATS = new Set(["json", "markdown"]);
+const POLICIES = new Set(["fail", "warn"]);
+
+/**
+ * @param {string} field
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(field, message) {
+  throw new ConfigError(`配置错误 ${field}: ${message}`);
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {string[]} [allowed]
+ */
+function assertObject(value, field, allowed) {
+  if (!isPlainObject(value)) fail(field, "必须是 JSON 对象");
+  if (allowed) {
+    for (const key of Object.keys(value)) {
+      if (!allowed.includes(key)) fail(`${field}.${key}`, "未知字段（检查拼写）");
+    }
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {{ allowEmpty?: boolean }} [options]
+ */
+function assertString(value, field, options = {}) {
+  if (typeof value !== "string" || (!options.allowEmpty && value.trim() === "")) {
+    fail(field, "必须是非空字符串");
+  }
+  return value;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {string[]}
+ */
+function stringList(value, field) {
+  const list = typeof value === "string" ? [value] : value;
+  if (!Array.isArray(list) || list.length === 0) {
+    fail(field, "必须是非空字符串或字符串数组");
+  }
+  for (const [index, item] of list.entries()) {
+    if (typeof item !== "string" || item.trim() === "") {
+      fail(`${field}[${index}]`, "必须是非空字符串");
+    }
+  }
+  return list.map((item) => item.trim());
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @param {number} floor
+ * @param {number} ceiling
+ * @returns {{ value: number, basisPoints: number }}
+ */
+function thresholdValue(value, field, floor, ceiling) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    fail(field, "必须是数字");
+  }
+  if (value < floor) {
+    fail(
+      field,
+      `不得低于产品底线 ${floor}（本项目配置试图使用 ${value}）`
+    );
+  }
+  if (value > ceiling) fail(field, `不得大于 ${ceiling}`);
+  const scaled = value * 100;
+  if (Math.abs(scaled - Math.round(scaled)) > 1e-8) {
+    fail(field, "最多允许两位小数");
+  }
+  return { value, basisPoints: Math.round(scaled) };
+}
+
+/**
+ * @param {any} raw
+ * @param {number} index
+ * @param {string} scopeName
+ * @param {string} root
+ */
+function normalizeCommand(raw, index, scopeName, root) {
+  const field = `scopes.${scopeName}.commands[${index}]`;
+  let value;
+  if (typeof raw === "string") {
+    value = { run: raw };
+  } else {
+    assertObject(raw, field);
+    for (const key of Object.keys(raw)) {
+      if (!COMMAND_KEYS.has(key)) fail(`${field}.${key}`, "未知字段（检查拼写）");
+    }
+    value = raw;
+  }
+  const run = assertString(value.run, `${field}.run`);
+  const name = value.name === undefined
+    ? `命令 ${index + 1}`
+    : assertString(value.name, `${field}.name`);
+  const cwd = value.cwd === undefined
+    ? root
+    : path.resolve(root, assertString(value.cwd, `${field}.cwd`));
+  let timeoutSeconds = 900;
+  if (value.timeoutSeconds !== undefined) {
+    if (
+      typeof value.timeoutSeconds !== "number" ||
+      !Number.isFinite(value.timeoutSeconds) ||
+      value.timeoutSeconds <= 0 ||
+      value.timeoutSeconds > 86_400
+    ) {
+      fail(`${field}.timeoutSeconds`, "必须是 0 到 86400 之间的秒数");
+    }
+    timeoutSeconds = value.timeoutSeconds;
+  }
+  /** @type {Record<string, string>} */
+  const env = {};
+  if (value.env !== undefined) {
+    assertObject(value.env, `${field}.env`);
+    for (const [key, envValue] of Object.entries(value.env)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        fail(`${field}.env.${key}`, "不是合法的环境变量名");
+      }
+      if (
+        typeof envValue !== "string" &&
+        typeof envValue !== "number" &&
+        typeof envValue !== "boolean"
+      ) {
+        fail(`${field}.env.${key}`, "必须是字符串、数字或布尔值");
+      }
+      env[key] = String(envValue);
+    }
+  }
+  return {
+    name,
+    run,
+    cwd,
+    timeoutSeconds,
+    timeoutMs: Math.round(timeoutSeconds * 1_000),
+    env
+  };
+}
+
+/**
+ * @param {any} raw
+ * @param {string} scopeName
+ */
+function normalizeScope(raw, scopeName) {
+  const field = `scopes.${scopeName}`;
+  assertObject(raw, field);
+  for (const key of Object.keys(raw)) {
+    if (!SCOPE_KEYS.has(key)) fail(`${field}.${key}`, "未知字段（检查拼写）");
+  }
+  const profile = raw.profile ?? (scopeName === "client" || scopeName === "server" ? scopeName : null);
+  if (!profile) {
+    fail(`${field}.profile`, "必须显式设置为 \"client\" 或 \"server\"");
+  }
+  if (!PROFILES.includes(profile)) {
+    fail(`${field}.profile`, `必须是 ${PROFILES.join(" 或 ")}`);
+  }
+  const label = raw.label === undefined
+    ? scopeName
+    : assertString(raw.label, `${field}.label`);
+
+  if (!Array.isArray(raw.commands) || raw.commands.length === 0) {
+    fail(`${field}.commands`, "必须包含至少一个测试命令（脚本模式可用 check 跳过执行）");
+  }
+
+  const coverage = raw.coverage;
+  assertObject(coverage, `${field}.coverage`);
+  for (const key of Object.keys(coverage)) {
+    if (!COVERAGE_KEYS.has(key)) fail(`${field}.coverage.${key}`, "未知字段（检查拼写）");
+  }
+  const format = coverage.format ?? "auto";
+  if (!COVERAGE_FORMATS.has(format)) {
+    fail(`${field}.coverage.format`, `必须是 ${[...COVERAGE_FORMATS].join(", ")}`);
+  }
+  const coveragePaths = stringList(coverage.paths, `${field}.coverage.paths`);
+
+  const sources = raw.sources;
+  assertObject(sources, `${field}.sources`);
+  for (const key of Object.keys(sources)) {
+    if (!SOURCE_KEYS.has(key)) fail(`${field}.sources.${key}`, "未知字段（检查拼写）");
+  }
+  const include = stringList(sources.include, `${field}.sources.include`);
+
+  const floors = PROFILE_FLOORS[profile];
+  /** @type {Record<string, { value: number, basisPoints: number }>} */
+  const thresholds = {};
+  if (raw.thresholds !== undefined) {
+    assertObject(raw.thresholds, `${field}.thresholds`);
+    for (const key of Object.keys(raw.thresholds)) {
+      if (!METRICS.includes(key)) {
+        fail(`${field}.thresholds.${key}`, `未知指标，可用指标：${METRICS.join(", ")}`);
+      }
+    }
+  }
+  for (const metric of METRICS) {
+    const value = raw.thresholds?.[metric] ?? floors[metric];
+    thresholds[metric] = thresholdValue(
+      value,
+      `${field}.thresholds.${metric}`,
+      floors[metric],
+      100
+    );
+  }
+
+  // Commands need the config root to resolve cwd, so they are normalized in
+  // normalizeConfig after the root is known.
+  const excludes = raw.exclude ?? [];
+  if (!Array.isArray(excludes)) fail(`${field}.exclude`, "必须是数组");
+  const normalizedExcludes = excludes.map((entry, index) => {
+    const excludeField = `${field}.exclude[${index}]`;
+    if (typeof entry === "string") {
+      fail(
+        excludeField,
+        "不能使用裸路径；必须写成 {\"pattern\": \"...\", \"reason\": \"为什么可以排除\"}"
+      );
+    }
+    assertObject(entry, excludeField, [...EXCLUDE_KEYS]);
+    const pattern = assertString(entry.pattern, `${excludeField}.pattern`);
+    const reason = assertString(entry.reason, `${excludeField}.reason`);
+    return {
+      pattern,
+      reason,
+      owner: entry.owner === undefined ? undefined : assertString(entry.owner, `${excludeField}.owner`),
+      expires: entry.expires === undefined ? undefined : assertString(entry.expires, `${excludeField}.expires`),
+      ticket: entry.ticket === undefined ? undefined : assertString(entry.ticket, `${excludeField}.ticket`)
+    };
+  });
+
+  return {
+    name: scopeName,
+    label,
+    profile,
+    commands: raw.commands,
+    coverage: { format, paths: coveragePaths },
+    thresholds,
+    floors,
+    sources: { include },
+    exclude: normalizedExcludes
+  };
+}
+
+/**
+ * Validate and normalize a parsed config object.
+ * @param {any} raw
+ * @param {{ configPath: string, root: string, text?: string }} context
+ */
+export function normalizeConfig(raw, context) {
+  assertObject(raw, "config");
+  for (const key of Object.keys(raw)) {
+    if (!CONFIG_KEYS.has(key)) fail(key, "未知字段（检查拼写）");
+  }
+  if (raw.version !== undefined && raw.version !== CONFIG_VERSION) {
+    fail("version", `只支持 ${CONFIG_VERSION}`);
+  }
+  if (!isPlainObject(raw.scopes) || Object.keys(raw.scopes).length === 0) {
+    fail("scopes", "至少需要配置一个 scope");
+  }
+
+  const scopes = [];
+  for (const [name, scope] of Object.entries(raw.scopes)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+      fail(`scopes.${name}`, "scope 名称只能包含字母、数字、下划线或连字符");
+    }
+    const normalized = normalizeScope(scope, name);
+    normalized.commands = normalized.commands.map((command, index) =>
+      normalizeCommand(command, index, name, context.root)
+    );
+    scopes.push(normalized);
+  }
+
+  const waivers = {
+    minReasonLength: 8,
+    requireOwner: false,
+    stale: "fail",
+    expiry: "fail"
+  };
+  if (raw.waivers !== undefined) {
+    assertObject(raw.waivers, "waivers", [...WAIVER_KEYS]);
+    if (raw.waivers.minReasonLength !== undefined) {
+      if (
+        !Number.isInteger(raw.waivers.minReasonLength) ||
+        raw.waivers.minReasonLength < 1 ||
+        raw.waivers.minReasonLength > 500
+      ) {
+        fail("waivers.minReasonLength", "必须是 1 到 500 之间的整数");
+      }
+      waivers.minReasonLength = raw.waivers.minReasonLength;
+    }
+    if (raw.waivers.requireOwner !== undefined) {
+      if (typeof raw.waivers.requireOwner !== "boolean") {
+        fail("waivers.requireOwner", "必须是布尔值");
+      }
+      waivers.requireOwner = raw.waivers.requireOwner;
+    }
+    for (const key of ["stale", "expiry"]) {
+      if (raw.waivers[key] !== undefined) {
+        if (!POLICIES.has(raw.waivers[key])) {
+          fail(`waivers.${key}`, `必须是 ${[...POLICIES].join(" 或 ")}`);
+        }
+        waivers[key] = raw.waivers[key];
+      }
+    }
+  }
+
+  const reports = { dir: ".covgate", formats: ["json", "markdown"] };
+  if (raw.reports !== undefined) {
+    assertObject(raw.reports, "reports", [...REPORT_KEYS]);
+    if (raw.reports.dir !== undefined) {
+      reports.dir = assertString(raw.reports.dir, "reports.dir");
+    }
+    if (raw.reports.formats !== undefined) {
+      if (!Array.isArray(raw.reports.formats)) {
+        fail("reports.formats", "必须是字符串数组");
+      }
+      for (const format of raw.reports.formats) {
+        if (!REPORT_FORMATS.has(format)) {
+          fail("reports.formats", `不支持的格式 ${format}，可用：${[...REPORT_FORMATS].join(", ")}`);
+        }
+      }
+      reports.formats = [...new Set(raw.reports.formats)];
+    }
+  }
+
+  return {
+    version: CONFIG_VERSION,
+    configPath: context.configPath,
+    root: context.root,
+    scopes,
+    waivers,
+    reports: {
+      dir: path.resolve(context.root, reports.dir),
+      formats: reports.formats
+    },
+    hash: context.text === undefined ? undefined : sha256(context.text)
+  };
+}
+
+/**
+ * @param {string} configPath
+ */
+export async function loadConfig(configPath) {
+  const absolute = path.resolve(configPath);
+  let text;
+  try {
+    text = await readFile(absolute, "utf8");
+  } catch (error) {
+    throw new ConfigError(
+      `无法读取配置文件 ${absolute}: ${error.message}\n提示：在项目根目录创建 covgate.config.json，或使用 --config 指定路径。`,
+      { cause: error }
+    );
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch (error) {
+    throw new ConfigError(`配置文件不是合法 JSON（${absolute}）：${error.message}`, {
+      cause: error
+    });
+  }
+  return normalizeConfig(raw, {
+    configPath: absolute,
+    root: path.dirname(absolute),
+    text
+  });
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [explicitPath]
+ */
+export function resolveConfigPath(cwd, explicitPath) {
+  if (explicitPath) return path.resolve(cwd, explicitPath);
+  return path.resolve(cwd, CONFIG_FILENAME);
+}
+
+/**
+ * @param {any} config
+ * @param {string[]} names
+ */
+export function selectScopes(config, names) {
+  if (!names || names.length === 0) return config.scopes;
+  const byName = new Map(config.scopes.map((scope) => [scope.name, scope]));
+  const selected = [];
+  for (const name of names) {
+    const scope = byName.get(name);
+    if (!scope) {
+      throw new ConfigError(
+        `未知 scope "${name}"。可用 scope：${config.scopes.map((item) => item.name).join(", ")}`
+      );
+    }
+    selected.push(scope);
+  }
+  return selected;
+}

package/src/coverage/index.js

@@ -0,0 +1,85 @@
+import { open, readFile } from "node:fs/promises";
+import path from "node:path";
+import { CoverageDataError } from "../errors.js";
+import { parseIstanbulReports } from "./istanbul.js";
+import { parseLcovReports } from "./lcov.js";
+
+/**
+ * @param {string} reportFile
+ * @returns {Promise<"istanbul" | "lcov">}
+ */
+async function inferFormat(reportFile) {
+  const extension = path.extname(reportFile).toLowerCase();
+  if (extension === ".json") return "istanbul";
+  if (extension === ".info" || extension === ".lcov") return "lcov";
+  let handle;
+  try {
+    handle = await open(reportFile, "r");
+    const buffer = Buffer.alloc(2048);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    const head = buffer.subarray(0, bytesRead).toString("utf8").trimStart();
+    if (head.startsWith("{")) return "istanbul";
+    if (/(^|\n)SF:/.test(head)) return "lcov";
+  } catch {
+    // The caller will produce a precise read error when parsing.
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+  throw new CoverageDataError(
+    `无法从文件名推断覆盖率报告格式：${reportFile}；请在配置中显式设置 coverage.format。`
+  );
+}
+
+/**
+ * @param {string[]} reportFiles
+ * @param {string} format
+ * @returns {Promise<"istanbul" | "lcov">}
+ */
+async function resolveFormat(reportFiles, format) {
+  if (format === "istanbul" || format === "lcov") return format;
+  if (format !== "auto") {
+    throw new CoverageDataError(`不支持的覆盖率格式：${format}`);
+  }
+  const formats = new Set();
+  for (const reportFile of reportFiles) formats.add(await inferFormat(reportFile));
+  if (formats.size === 0) {
+    throw new CoverageDataError("没有可读取的覆盖率报告");
+  }
+  if (formats.size > 1) {
+    throw new CoverageDataError(
+      `同一 scope 内混用了多种覆盖率格式（${[...formats].join(", ")}）；请拆分为不同 scope，或统一报告格式。`
+    );
+  }
+  return [...formats][0];
+}
+
+/**
+ * @param {{ reportFiles: string[], format: string, root: string }} options
+ */
+export async function loadCoverage({ reportFiles, format, root }) {
+  if (!Array.isArray(reportFiles) || reportFiles.length === 0) {
+    throw new CoverageDataError(
+      "没有找到覆盖率报告。请检查 coverage.paths，并确认测试命令确实生成了报告。"
+    );
+  }
+  const resolvedFormat = await resolveFormat(reportFiles, format);
+  const files =
+    resolvedFormat === "istanbul"
+      ? await parseIstanbulReports(reportFiles, root)
+      : await parseLcovReports(reportFiles, root);
+  if (files.size === 0) {
+    throw new CoverageDataError(
+      "覆盖率报告存在，但其中没有任何源码记录。请检查测试命令和覆盖率采集配置。"
+    );
+  }
+  return { format: resolvedFormat, files };
+}
+
+/**
+ * Read a report for diagnostics only.
+ * @param {string} reportFile
+ */
+export async function readReportHead(reportFile) {
+  const text = await readFile(reportFile, "utf8");
+  return text.slice(0, 4000);
+}