covgate 0.0.0-stage → 0.2.0

package/src/glob.js

@@ -0,0 +1,242 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { IS_WINDOWS, canonicalPath, toPosix } from "./util.js";
+
+const SKIP_DIRECTORIES = new Set(["node_modules", ".git", ".covgate", ".hg", ".svn"]);
+const MAGIC = /[*?\[\]{}]/;
+
+/**
+ * @param {string} pattern
+ * @returns {string[]}
+ */
+export function expandBraces(pattern) {
+  const open = pattern.indexOf("{");
+  if (open === -1) return [pattern];
+  const close = pattern.indexOf("}", open + 1);
+  if (close === -1) return [pattern];
+  const before = pattern.slice(0, open);
+  const body = pattern.slice(open + 1, close);
+  const after = pattern.slice(close + 1);
+  const choices = body.split(",");
+  if (choices.length === 1) return [pattern];
+  return choices.flatMap((choice) => expandBraces(`${before}${choice}${after}`));
+}
+
+/**
+ * @param {string} pattern
+ */
+function patternHasMagic(pattern) {
+  return MAGIC.test(pattern);
+}
+
+/**
+ * @param {string} absolutePattern
+ */
+function absoluteBase(absolutePattern) {
+  const normalized = toPosix(absolutePattern);
+  const segments = normalized.split("/");
+  let magicIndex = segments.length;
+  for (let index = 0; index < segments.length; index += 1) {
+    if (patternHasMagic(segments[index])) {
+      magicIndex = index;
+      break;
+    }
+  }
+  if (magicIndex === segments.length) {
+    return path.normalize(absolutePattern);
+  }
+  const baseSegments = segments.slice(0, magicIndex);
+  const joined = baseSegments.join("/");
+  if (!joined) return path.parse(absolutePattern).root;
+  return path.normalize(joined);
+}
+
+/**
+ * Convert a glob segment into a regular expression fragment.
+ * Supports **, *, ?, character classes and brace-free patterns.
+ * @param {string} glob
+ * @param {boolean} caseInsensitive
+ */
+function globToRegExp(glob, caseInsensitive = false) {
+  let source = "";
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === "*") {
+      if (glob[index + 1] === "*") {
+        while (glob[index + 1] === "*") index += 1;
+        if (glob[index + 1] === "/") {
+          source += "(?:.*/)?";
+          index += 1;
+        } else {
+          source += ".*";
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (character === "?") {
+      source += "[^/]";
+    } else if (character === "[") {
+      let close = glob.indexOf("]", index + 1);
+      if (close === -1) {
+        source += "\\[";
+      } else {
+        let body = glob.slice(index + 1, close);
+        if (body.startsWith("!")) body = `^${body.slice(1)}`;
+        source += `[${body}]`;
+        index = close;
+      }
+    } else if ("\\^$+.()|{}".includes(character)) {
+      source += `\\${character}`;
+    } else {
+      source += character;
+    }
+  }
+  return new RegExp(`^${source}$`, caseInsensitive ? "i" : "");
+}
+
+/**
+ * @param {string} pattern
+ * @param {{ caseInsensitive?: boolean }} [options]
+ */
+export function compileGlob(pattern, options = {}) {
+  let normalized = toPosix(pattern).trim();
+  if (!normalized) {
+    return { regex: /^$/, normalized };
+  }
+  if (normalized.startsWith("./")) normalized = normalized.slice(2);
+  const caseInsensitive = options.caseInsensitive ?? IS_WINDOWS;
+  if (!normalized.includes("/") && !normalized.startsWith("**")) {
+    normalized = `**/${normalized}`;
+  }
+  return { regex: globToRegExp(normalized, caseInsensitive), normalized };
+}
+
+/**
+ * Match a project-relative path against a glob. A pattern without a slash
+ * matches a basename at any depth, which is convenient for config exclusions.
+ * @param {string} relativePath
+ * @param {string} pattern
+ * @param {{ caseInsensitive?: boolean }} [options]
+ */
+export function matchGlob(relativePath, pattern, options = {}) {
+  const normalizedPath = toPosix(relativePath).replace(/^\.\//, "");
+  return compileGlob(pattern, options).regex.test(normalizedPath);
+}
+
+/**
+ * @param {string} relativePath
+ * @param {Array<{ pattern: string }>} entries
+ */
+export function matchAnyGlob(relativePath, entries) {
+  return entries.find((entry) => matchGlob(relativePath, entry.pattern));
+}
+
+/**
+ * @param {string} directory
+ * @returns {Promise<string[]>}
+ */
+export async function walkFiles(directory) {
+  const result = [];
+  const stack = [directory];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch (error) {
+      if (error && (error.code === "ENOENT" || error.code === "ENOTDIR")) continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRECTORIES.has(entry.name)) continue;
+        stack.push(absolute);
+      } else if (entry.isFile()) {
+        result.push(absolute);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Expand one or more glob patterns to absolute file paths.
+ * Symlinked files/directories are intentionally not followed, to keep source
+ * discovery deterministic and avoid cycles.
+ *
+ * @param {string | string[]} patterns
+ * @param {string} root
+ * @param {{ includeDirectories?: boolean }} [options]
+ * @returns {Promise<string[]>}
+ */
+export async function expandGlob(patterns, root, options = {}) {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+  const found = new Map();
+  for (const rawPattern of list) {
+    if (typeof rawPattern !== "string" || rawPattern.trim() === "") continue;
+    for (const pattern of expandBraces(rawPattern.trim())) {
+      if (toPosix(pattern).includes("..")) {
+        // Allowed, but intentionally resolved through path.resolve below.
+      }
+      const absolutePattern = path.isAbsolute(pattern)
+        ? path.normalize(pattern)
+        : path.resolve(root, pattern);
+      if (!patternHasMagic(absolutePattern)) {
+        let info;
+        try {
+          info = await stat(absolutePattern);
+        } catch (error) {
+          if (error && error.code === "ENOENT") continue;
+          throw error;
+        }
+        if (info.isFile()) {
+          found.set(canonicalPath(absolutePattern), absolutePattern);
+        } else if (info.isDirectory() && options.includeDirectories) {
+          for (const file of await walkFiles(absolutePattern)) {
+            found.set(canonicalPath(file), file);
+          }
+        }
+        continue;
+      }
+      const base = absoluteBase(absolutePattern);
+      let baseInfo;
+      try {
+        baseInfo = await stat(base);
+      } catch (error) {
+        if (error && error.code === "ENOENT") continue;
+        throw error;
+      }
+      const candidates = baseInfo.isDirectory() ? await walkFiles(base) : [base];
+      const absolutePatternPosix = toPosix(absolutePattern);
+      const regex = globToRegExp(absolutePatternPosix, IS_WINDOWS);
+      for (const candidate of candidates) {
+        if (regex.test(toPosix(candidate))) {
+          found.set(canonicalPath(candidate), candidate);
+        }
+      }
+    }
+  }
+  return [...found.values()].sort((left, right) =>
+    toPosix(left).localeCompare(toPosix(right), "en")
+  );
+}
+
+/**
+ * Expand an explicit list of files/directories/globs, keeping only files.
+ * Directories are scanned recursively.
+ * @param {string | string[]} patterns
+ * @param {string} root
+ */
+export async function expandFiles(patterns, root) {
+  return expandGlob(patterns, root, { includeDirectories: true });
+}
+
+/**
+ * @param {string} directory
+ * @param {string} root
+ */
+export function relativeToRoot(directory, root) {
+  return toPosix(path.relative(root, directory));
+}

package/src/index.js

@@ -0,0 +1,28 @@
+export { main } from "./cli.js";
+export { parseArgs, HELP_TEXT } from "./args.js";
+export {
+  loadConfig,
+  normalizeConfig,
+  selectScopes,
+  CONFIG_FILENAME,
+  CONFIG_VERSION,
+  METRICS,
+  PROFILES,
+  PROFILE_FLOORS
+} from "./config.js";
+export { loadCoverage } from "./coverage/index.js";
+export { parseIstanbulReports } from "./coverage/istanbul.js";
+export { parseLcovReports, parseLcovText } from "./coverage/lcov.js";
+export { parseAnnotations } from "./annotations.js";
+export { validateReason } from "./reason.js";
+export { evaluateScope } from "./scope.js";
+export { gateAll, gateScope } from "./gate.js";
+export {
+  buildReport,
+  plannedArtifactPaths,
+  renderMarkdownReport,
+  renderTextReport,
+  writeReportArtifacts
+} from "./report/index.js";
+export { VERSION, TOOL_NAME } from "./version.js";
+export { CovgateError, ConfigError, ExecutionError, CoverageDataError } from "./errors.js";

package/src/process.js

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+
+const MAX_CAPTURE = 4 * 1024 * 1024;
+
+/**
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {boolean} timedOut
+ */
+function killTree(child, timedOut) {
+  if (child.pid === undefined) return;
+  if (process.platform === "win32") {
+    const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    killer.on("error", () => {
+      try {
+        child.kill();
+      } catch {
+        // Ignore: process may already be gone.
+      }
+    });
+    return;
+  }
+  try {
+    process.kill(-child.pid, timedOut ? "SIGKILL" : "SIGTERM");
+  } catch {
+    try {
+      child.kill(timedOut ? "SIGKILL" : "SIGTERM");
+    } catch {
+      // Ignore: process may already be gone.
+    }
+  }
+}
+
+/**
+ * @param {string} current
+ * @param {string} chunk
+ * @param {number} limit
+ */
+function appendLimited(current, chunk, limit) {
+  if (chunk.length === 0) return { text: current, truncated: false };
+  const combined = current + chunk;
+  if (combined.length <= limit) return { text: combined, truncated: false };
+  return { text: combined.slice(-limit), truncated: true };
+}
+
+/**
+ * Run one shell command with bounded output capture and a timeout.
+ *
+ * @param {{
+ *   command: string,
+ *   cwd: string,
+ *   env?: Record<string, string>,
+ *   timeoutMs?: number,
+ *   onStdout?: (chunk: string) => void,
+ *   onStderr?: (chunk: string) => void
+ * }} options
+ */
+export function runShellCommand({
+  command,
+  cwd,
+  env = {},
+  timeoutMs = 900_000,
+  onStdout,
+  onStderr
+}) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const detached = process.platform !== "win32";
+    let child;
+    try {
+      child = spawn(command, {
+        cwd,
+        shell: true,
+        windowsHide: true,
+        detached,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, COVGATE: "1", ...env }
+      });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+    let settled = false;
+    let forceTimer = null;
+    const stdoutDecoder = new StringDecoder("utf8");
+    const stderrDecoder = new StringDecoder("utf8");
+
+    const finish = (/** @type {any} */ result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (forceTimer) clearTimeout(forceTimer);
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child, false);
+      forceTimer = setTimeout(() => {
+        killTree(child, true);
+        finish({
+          code: null,
+          signal: "SIGKILL",
+          timedOut: true,
+          stdout,
+          stderr,
+          stdoutTruncated,
+          stderrTruncated,
+          durationMs: Date.now() - startedAt,
+          error: "timeout"
+        });
+      }, 8_000);
+    }, timeoutMs);
+
+    child.stdout?.on("data", (chunk) => {
+      try {
+        onStdout?.(chunk.toString());
+      } catch {
+        // Logging must not break the command.
+      }
+      const decoded = stdoutDecoder.write(chunk);
+      const appended = appendLimited(stdout, decoded, MAX_CAPTURE);
+      stdout = appended.text;
+      stdoutTruncated ||= appended.truncated;
+    });
+    child.stderr?.on("data", (chunk) => {
+      try {
+        onStderr?.(chunk.toString());
+      } catch {
+        // Logging must not break the command.
+      }
+      const decoded = stderrDecoder.write(chunk);
+      const appended = appendLimited(stderr, decoded, MAX_CAPTURE);
+      stderr = appended.text;
+      stderrTruncated ||= appended.truncated;
+    });
+
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (forceTimer) clearTimeout(forceTimer);
+      reject(error);
+    });
+
+    child.on("close", (code, signal) => {
+      stdout += stdoutDecoder.end();
+      stderr += stderrDecoder.end();
+      finish({
+        code,
+        signal,
+        timedOut,
+        stdout,
+        stderr,
+        stdoutTruncated,
+        stderrTruncated,
+        durationMs: Date.now() - startedAt
+      });
+    });
+  });
+}

package/src/reason.js

@@ -0,0 +1,77 @@
+import { parseExpiryDate } from "./util.js";
+
+const PLACEHOLDER_REASONS = new Set([
+  "todo",
+  "fixme",
+  "na",
+  "none",
+  "ignore",
+  "skip",
+  "skipped",
+  "unreachable",
+  "uncovered",
+  "notest",
+  "notestable",
+  "coverage",
+  "excluded",
+  "无",
+  "忽略",
+  "跳过",
+  "不可达",
+  "无法覆盖",
+  "测试不到",
+  "无测试",
+  "不需要",
+  "无需覆盖"
+]);
+
+/**
+ * Normalize a reason before checking it against the placeholder list.
+ * @param {string} reason
+ */
+function normalizeReason(reason) {
+  return reason
+    .trim()
+    .toLowerCase()
+    .replace(/[\s.,;:!?'"()\[\]{}<>/\\|_\-—–]+/g, "");
+}
+
+/**
+ * Validate the human explanation attached to a suppression. This is
+ * deliberately strict: an audit trail with "TODO" is not an audit trail.
+ *
+ * @param {string} reason
+ * @param {{ minReasonLength: number, requireOwner: boolean }} policy
+ * @param {{ owner?: string, expires?: string }} metadata
+ * @param {Date} [now]
+ * @returns {{ errors: string[], expired: boolean, expiresAt: Date | null }}
+ */
+export function validateReason(reason, policy, metadata = {}, now = new Date()) {
+  const errors = [];
+  const trimmed = reason.trim();
+  if (!trimmed) {
+    errors.push("缺少原因说明");
+  } else {
+    const length = [...trimmed].length;
+    if (length < policy.minReasonLength) {
+      errors.push(
+        `原因说明太短（${length} 个字符，至少需要 ${policy.minReasonLength} 个）；请说明为什么这段代码无法被执行到`
+      );
+    }
+    if (PLACEHOLDER_REASONS.has(normalizeReason(trimmed))) {
+      errors.push("原因说明是占位词，必须解释不可达的具体原因");
+    }
+  }
+  if (policy.requireOwner && !metadata.owner?.trim()) {
+    errors.push("策略要求提供 owner 元数据");
+  }
+  let expiresAt = null;
+  if (metadata.expires !== undefined) {
+    expiresAt = parseExpiryDate(metadata.expires);
+    if (!expiresAt) {
+      errors.push(`expires 必须是合法的 YYYY-MM-DD 日期，收到 "${metadata.expires}"`);
+    }
+  }
+  const expired = expiresAt !== null && expiresAt.getTime() < now.getTime();
+  return { errors, expired, expiresAt };
+}

package/src/report/build.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { relativeDisplay, tail, toPosix } from "../util.js";
+import { VERSION } from "../version.js";
+
+/**
+ * @param {any} config
+ * @param {{ json?: string, markdown?: string }} paths
+ */
+function artifactDisplay(config, paths) {
+  const artifacts = {};
+  for (const [format, filePath] of Object.entries(paths)) {
+    if (!filePath) continue;
+    const relative = relativeDisplay(filePath, config.root);
+    artifacts[format] = relative.startsWith("..") ? toPosix(filePath) : relative;
+  }
+  return artifacts;
+}
+
+/**
+ * @param {any[]} scopes
+ */
+function countScopeState(scopes) {
+  let waivers = 0;
+  let exclusions = 0;
+  let errors = 0;
+  let warnings = 0;
+  let missing = 0;
+  for (const scope of scopes) {
+    waivers += scope.waivers.length;
+    exclusions += scope.exclusions.length;
+    errors += scope.issues.filter((issue) => issue.severity === "error").length;
+    warnings +=
+      scope.warnings.length +
+      scope.issues.filter((issue) => issue.severity === "warning").length;
+    missing += scope.missingSources.length;
+  }
+  return { waivers, exclusions, errors, warnings, missing };
+}
+
+/**
+ * @param {{
+ *   config: any,
+ *   mode: "run" | "check",
+ *   scopes: any[],
+ *   commands: any[],
+ *   topLevelIssues: any[],
+ *   durationMs: number,
+ *   startedAt: string,
+ *   artifactPaths: { json?: string, markdown?: string }
+ * }} options
+ */
+export function buildReport({
+  config,
+  mode,
+  scopes,
+  commands,
+  topLevelIssues,
+  durationMs,
+  startedAt,
+  artifactPaths
+}) {
+  const errors = topLevelIssues.filter((issue) => issue.severity !== "warning");
+  const hasExecutionError = errors.length > 0;
+  const allPassed = scopes.length > 0 && scopes.every((scope) => scope.passed);
+  const status = hasExecutionError ? "error" : allPassed ? "pass" : "fail";
+  const exitCode = status === "error" ? 3 : status === "pass" ? 0 : 1;
+  const state = countScopeState(scopes);
+  const failedScopes = scopes.filter((scope) => !scope.passed).map((scope) => scope.name);
+  const artifacts = artifactDisplay(config, artifactPaths);
+
+  const sanitizedCommands = commands.map((command) => {
+    const record = {
+      scope: command.scope,
+      name: command.name,
+      command: command.command,
+      cwd: command.cwd,
+      exitCode: command.exitCode,
+      signal: command.signal,
+      timedOut: command.timedOut,
+      durationMs: command.durationMs
+    };
+    if (command.exitCode !== 0 || command.timedOut) {
+      record.outputTail = tail(
+        ((command.stdout ?? "") + "\n" + (command.stderr ?? "")).trim(),
+        8000
+      );
+    }
+    return record;
+  });
+
+  return {
+    schemaVersion: 1,
+    tool: { name: "covgate", version: VERSION },
+    status,
+    exitCode,
+    generatedAt: new Date().toISOString(),
+    startedAt,
+    durationMs,
+    mode,
+    config: {
+      path: relativeDisplay(config.configPath, config.root),
+      sha256: config.hash
+    },
+    summary: {
+      scopes: scopes.length,
+      passedScopes: scopes.filter((scope) => scope.passed).length,
+      failedScopes,
+      waivers: state.waivers,
+      exclusions: state.exclusions,
+      missingSources: state.missing,
+      errors: state.errors + errors.length,
+      warnings: state.warnings
+    },
+    issues: topLevelIssues,
+    commands: sanitizedCommands,
+    scopes,
+    artifacts
+  };
+}
+
+/**
+ * @param {any} config
+ * @param {boolean} noFiles
+ */
+export function plannedArtifactPaths(config, noFiles = false) {
+  if (noFiles) return {};
+  const paths = {};
+  if (config.reports.formats.includes("json")) {
+    paths.json = path.join(config.reports.dir, "report.json");
+  }
+  if (config.reports.formats.includes("markdown")) {
+    paths.markdown = path.join(config.reports.dir, "report.md");
+  }
+  return paths;
+}

package/src/report/index.js

@@ -0,0 +1,29 @@
+import { writeTextFile } from "../util.js";
+import { buildReport, plannedArtifactPaths } from "./build.js";
+import { renderMarkdownReport } from "./markdown.js";
+import { renderTextReport } from "./text.js";
+
+export { buildReport, plannedArtifactPaths, renderMarkdownReport, renderTextReport };
+
+/**
+ * @param {any} report
+ * @param {{ json?: string, markdown?: string }} paths
+ */
+export async function writeReportArtifacts(report, paths) {
+  const errors = [];
+  if (paths.json) {
+    try {
+      await writeTextFile(paths.json, JSON.stringify(report, null, 2) + "\n");
+    } catch (error) {
+      errors.push("无法写入 JSON 报告 " + paths.json + ": " + error.message);
+    }
+  }
+  if (paths.markdown) {
+    try {
+      await writeTextFile(paths.markdown, renderMarkdownReport(report));
+    } catch (error) {
+      errors.push("无法写入 Markdown 报告 " + paths.markdown + ": " + error.message);
+    }
+  }
+  return errors;
+}