covgate 0.0.0-stage → 0.2.0

package/src/reports.js

@@ -0,0 +1,113 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { expandBraces, expandGlob, walkFiles } from "./glob.js";
+import { canonicalPath, toPosix } from "./util.js";
+
+const MAGIC = /[*?\[\]{}]/;
+
+/**
+ * Directory paths are a convenience. Pick only conventional coverage report
+ * names there, so coverage-summary.json and HTML assets are not parsed as
+ * independent coverage databases. Use an explicit file or glob for custom names.
+ *
+ * @param {string} format
+ * @param {string} file
+ */
+function directoryReportAllowed(format, file) {
+  const extension = path.extname(file).toLowerCase();
+  const basename = path.basename(file).toLowerCase();
+  if (format === "lcov") {
+    return extension === ".info" || extension === ".lcov";
+  }
+  if (format === "istanbul") {
+    return basename === "coverage-final.json";
+  }
+  return (
+    basename === "coverage-final.json" ||
+    extension === ".info" ||
+    extension === ".lcov"
+  );
+}
+
+/**
+ * Expand coverage.paths. Explicit files, directories and globs are supported.
+ * Directories are scanned for conventional report names.
+ *
+ * @param {any} scope
+ * @param {string} root
+ * @returns {Promise<string[]>}
+ */
+export async function expandCoverageReportFiles(scope, root) {
+  const found = new Map();
+  for (const rawPattern of scope.coverage.paths) {
+    for (const pattern of expandBraces(rawPattern)) {
+      const absolute = path.isAbsolute(pattern)
+        ? path.normalize(pattern)
+        : path.resolve(root, pattern);
+      if (!MAGIC.test(absolute)) {
+        let info;
+        try {
+          info = await stat(absolute);
+        } catch (error) {
+          if (error && error.code === "ENOENT") continue;
+          throw error;
+        }
+        if (info.isFile()) {
+          found.set(canonicalPath(absolute), absolute);
+        } else if (info.isDirectory()) {
+          for (const file of await walkFiles(absolute)) {
+            if (directoryReportAllowed(scope.coverage.format, file)) {
+              found.set(canonicalPath(file), file);
+            }
+          }
+        }
+        continue;
+      }
+      for (const file of await expandGlob(pattern, root)) {
+        found.set(canonicalPath(file), file);
+      }
+    }
+  }
+  return [...found.values()].sort((left, right) =>
+    toPosix(left).localeCompare(toPosix(right), "en")
+  );
+}
+
+/**
+ * @param {string[]} files
+ * @returns {Promise<Map<string, { path: string, mtimeMs: number, size: number }>>}
+ */
+export async function snapshotReportFiles(files) {
+  const snapshot = new Map();
+  for (const file of files) {
+    const info = await stat(file);
+    snapshot.set(canonicalPath(file), {
+      path: file,
+      mtimeMs: info.mtimeMs,
+      size: info.size
+    });
+  }
+  return snapshot;
+}
+
+/**
+ * Detect reports left over from a previous run. A report is fresh when it is
+ * newly created or its mtime/size changed during this invocation.
+ *
+ * @param {Map<string, { path: string, mtimeMs: number, size: number }>} before
+ * @param {string[]} after
+ */
+export async function findStaleReports(before, after) {
+  const stale = [];
+  for (const file of after) {
+    const key = canonicalPath(file);
+    const previous = before.get(key);
+    if (!previous) continue;
+    const info = await stat(file);
+    if (info.mtimeMs === previous.mtimeMs && info.size === previous.size) {
+      stale.push(file);
+    }
+  }
+  return stale;
+}
+

package/src/runner.js

@@ -0,0 +1,95 @@
+import { ExecutionError } from "./errors.js";
+import { runShellCommand } from "./process.js";
+import { formatDuration, relativeDisplay, tail } from "./util.js";
+
+/**
+ * @param {boolean} enabled
+ */
+function makeStreamWriter(enabled) {
+  if (!enabled) return undefined;
+  return (/** @type {string} */ chunk) => {
+    process.stderr.write(chunk);
+  };
+}
+
+/**
+ * @param {any} scope
+ * @param {{ verbose?: boolean, root?: string, logger?: { info: (message: string) => void } }} options
+ */
+export async function runScopeCommands(scope, options = {}) {
+  const results = [];
+  const logger = options.logger;
+  for (const command of scope.commands) {
+    logger?.info(`  ▶ ${scope.label} / ${command.name}: ${command.run}`);
+    let result;
+    try {
+      result = await runShellCommand({
+        command: command.run,
+        cwd: command.cwd,
+        env: command.env,
+        timeoutMs: command.timeoutMs,
+        onStdout: makeStreamWriter(options.verbose === true),
+        onStderr: makeStreamWriter(options.verbose === true)
+      });
+    } catch (error) {
+      throw new ExecutionError(
+        `${scope.label} / ${command.name} 启动失败：${error.message}`,
+        {
+          cause: error,
+          details: {
+            scope: scope.name,
+            command: { ...command },
+            cwd: command.cwd
+          }
+        }
+      );
+    }
+    const record = {
+      scope: scope.name,
+      name: command.name,
+      command: command.run,
+      cwd: relativeDisplay(command.cwd, options.root ?? process.cwd()),
+      exitCode: result.code,
+      signal: result.signal,
+      timedOut: result.timedOut,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      stdoutTruncated: result.stdoutTruncated,
+      stderrTruncated: result.stderrTruncated
+    };
+    results.push(record);
+    if (result.timedOut) {
+      throw new ExecutionError(
+        `${scope.label} / ${command.name} 超时（${command.timeoutSeconds}s）`,
+        { details: { ...record, priorCommands: results.slice(0, -1) } }
+      );
+    }
+    if (result.code !== 0) {
+      throw new ExecutionError(
+        `${scope.label} / ${command.name} 失败（退出码 ${result.code ?? "null"}）`,
+        { details: { ...record, priorCommands: results.slice(0, -1) } }
+      );
+    }
+    logger?.info(`    ✓ 完成，用时 ${formatDuration(result.durationMs)}`);
+  }
+  return results;
+}
+
+/**
+ * Print a failed command's captured output to stderr.
+ * @param {any} record
+ */
+export function printCommandFailure(record) {
+  if (!record) return;
+  if (record.stdout?.trim()) {
+    process.stderr.write("\n--- 测试命令 stdout（末尾）---\n");
+    process.stderr.write(tail(record.stdout, 20_000));
+    if (!record.stdout.endsWith("\n")) process.stderr.write("\n");
+  }
+  if (record.stderr?.trim()) {
+    process.stderr.write("\n--- 测试命令 stderr（末尾）---\n");
+    process.stderr.write(tail(record.stderr, 20_000));
+    if (!record.stderr.endsWith("\n")) process.stderr.write("\n");
+  }
+}

package/src/scope.js

@@ -0,0 +1,440 @@
+import { readFile } from "node:fs/promises";
+import { parseAnnotations } from "./annotations.js";
+import { expandFiles, matchGlob } from "./glob.js";
+import { validateReason } from "./reason.js";
+import {
+  countUncoveredInRanges,
+  removeRanges
+} from "./coverage/model.js";
+import {
+  canonicalPath,
+  relativeDisplay
+} from "./util.js";
+
+/**
+ * @param {"fail" | "warn"} policy
+ * @returns {"error" | "warning"}
+ */
+function severityFor(policy) {
+  return policy === "fail" ? "error" : "warning";
+}
+
+/**
+ * @param {Array<{ startLine: number, endLine: number }>} ranges
+ */
+function mergeRanges(ranges) {
+  const sorted = [...ranges].sort(
+    (left, right) => left.startLine - right.startLine || left.endLine - right.endLine
+  );
+  const merged = [];
+  for (const range of sorted) {
+    const previous = merged.at(-1);
+    if (previous && range.startLine <= previous.endLine) {
+      previous.endLine = Math.max(previous.endLine, range.endLine);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+/**
+ * @param {Array<{ startLine: number, endLine: number, directiveLine: number }>} ranges
+ */
+function findOverlaps(ranges) {
+  const sorted = [...ranges].sort(
+    (left, right) => left.startLine - right.startLine || left.endLine - right.endLine
+  );
+  const overlaps = [];
+  let previous = null;
+  for (const range of sorted) {
+    if (previous && range.startLine <= previous.endLine) {
+      overlaps.push([previous, range]);
+    }
+    if (!previous || range.endLine > previous.endLine) previous = range;
+  }
+  return overlaps;
+}
+
+/**
+ * Apply exclusions/waivers to one scope and produce the pre-gate audit data.
+ *
+ * @param {{
+ *   scope: any,
+ *   root: string,
+ *   coverage: { format: string, files: Map<string, any> },
+ *   waiverPolicy: any,
+ *   now?: Date
+ * }} options
+ */
+export async function evaluateScope({ scope, root, coverage, waiverPolicy, now = new Date() }) {
+  /** @type {Array<any>} */
+  const issues = [];
+  /** @type {Array<any>} */
+  const warnings = [];
+  /** @type {Array<any>} */
+  const waivers = [];
+  /** @type {Array<any>} */
+  const exclusions = [];
+  /** @type {Set<string>} */
+  const excludedKeys = new Set();
+  /** @type {Set<string>} */
+  const fileIgnoreKeys = new Set();
+
+  const addIssue = (issue) => issues.push(issue);
+
+  let discovered;
+  try {
+    discovered = await expandFiles(scope.sources.include, root);
+  } catch (error) {
+    addIssue({
+      code: "source-discovery-failed",
+      severity: "error",
+      message: `无法展开 sources.include：${error.message}`
+    });
+    discovered = [];
+  }
+  const expected = new Map();
+  for (const absPath of discovered) {
+    expected.set(canonicalPath(absPath), {
+      absPath,
+      relPath: relativeDisplay(absPath, root)
+    });
+  }
+  if (expected.size === 0) {
+    addIssue({
+      code: "no-source-files",
+      severity: "error",
+      message: "sources.include 没有匹配到任何源码文件，无法验证覆盖率"
+    });
+  }
+
+  // Config exclusions are file-level policy. Every reason is audited and every
+  // pattern must still match at least one source file.
+  for (const entry of scope.exclude) {
+    const matched = [];
+    for (const [key, file] of expected) {
+      if (matchGlob(file.relPath, entry.pattern)) matched.push({ key, file });
+    }
+    const validation = validateReason(
+      entry.reason,
+      waiverPolicy,
+      { owner: entry.owner, expires: entry.expires },
+      now
+    );
+    for (const message of validation.errors) {
+      addIssue({
+        code: "invalid-exclusion",
+        severity: "error",
+        message: `exclude "${entry.pattern}" 的说明无效：${message}`
+      });
+    }
+    if (validation.expired) {
+      addIssue({
+        code: "expired-exclusion",
+        severity: severityFor(waiverPolicy.expiry),
+        message: `exclude "${entry.pattern}" 已于 ${entry.expires} 过期，请重新评估`
+      });
+    }
+    if (matched.length === 0) {
+      addIssue({
+        code: "stale-exclusion",
+        severity: severityFor(waiverPolicy.stale),
+        message: `exclude "${entry.pattern}" 没有匹配任何源码文件，请删除这条失效规则`
+      });
+    }
+    for (const { key } of matched) {
+      excludedKeys.add(key);
+      expected.delete(key);
+    }
+    exclusions.push({
+      source: "config",
+      pattern: entry.pattern,
+      reason: entry.reason,
+      owner: entry.owner,
+      expires: entry.expires,
+      ticket: entry.ticket,
+      files: matched.map(({ file }) => file.relPath).sort(),
+      fileCount: matched.length,
+      status: validation.expired ? "expired" : matched.length === 0 ? "stale" : "applied",
+      validationErrors: validation.errors
+    });
+  }
+
+  // Read and scan every remaining expected source file. We need this before
+  // deciding missing coverage so file-level waivers can suppress that check
+  // with a documented reason.
+  const scans = new Map();
+  for (const [key, file] of expected) {
+    let text;
+    try {
+      text = await readFile(file.absPath, "utf8");
+    } catch (error) {
+      addIssue({
+        code: "source-read-failed",
+        severity: "error",
+        file: file.relPath,
+        message: `无法读取源码文件：${error.message}`
+      });
+      continue;
+    }
+    const parsed = parseAnnotations(text, file.relPath, waiverPolicy, now);
+    scans.set(key, { ...file, text, parsed });
+  }
+
+  // File-level waivers remove a whole source file. They are allowed to cover a
+  // missing report entry, but not a fully covered file (that would be stale).
+  for (const [key, scan] of scans) {
+    if (!scan.parsed.fileIgnore) continue;
+    const directive = scan.parsed.fileIgnore;
+    const coverageFile = coverage.files.get(key);
+    let uncovered = { lines: 0, statements: 0, functions: 0, branches: 0 };
+    if (coverageFile) {
+      uncovered = countUncoveredInRanges(coverageFile, [
+        { startLine: 1, endLine: Number.MAX_SAFE_INTEGER }
+      ]);
+    }
+    const uncoveredTotal = Object.values(uncovered).reduce((sum, count) => sum + count, 0);
+    const stale = coverageFile !== undefined && uncoveredTotal === 0;
+    if (stale) {
+      addIssue({
+        code: "stale-waiver",
+        severity: severityFor(waiverPolicy.stale),
+        file: scan.relPath,
+        line: directive.directiveLine,
+        message: "covgate-ignore-file 所在文件已经被完全覆盖；请删除这条豁免"
+      });
+    }
+    if (directive.expired) {
+      addIssue({
+        code: "expired-waiver",
+        severity: severityFor(waiverPolicy.expiry),
+        file: scan.relPath,
+        line: directive.directiveLine,
+        message: `豁免已于 ${directive.expires} 过期，请重新评估`
+      });
+    }
+    expected.delete(key);
+    excludedKeys.add(key);
+    fileIgnoreKeys.add(key);
+    coverage.files.delete(key);
+    waivers.push({
+      source: "inline",
+      kind: "file",
+      file: scan.relPath,
+      startLine: 1,
+      endLine: scan.text.split(/\r?\n/).length,
+      directiveLine: directive.directiveLine,
+      reason: directive.reason,
+      owner: directive.owner,
+      expires: directive.expires,
+      ticket: directive.ticket,
+      status: directive.expired ? "expired" : stale ? "stale" : "applied",
+      stale,
+      expired: directive.expired,
+      removedUncovered: { ...uncovered, files: 1 }
+    });
+  }
+
+  // Parser errors are fatal regardless of stale/expiry policy: a malformed
+  // waiver must not silently fall through as ordinary code.
+  for (const [key, scan] of scans) {
+    if (!expected.has(key) && !fileIgnoreKeys.has(key)) continue;
+    for (const error of scan.parsed.errors) {
+      addIssue({
+        code: "invalid-waiver",
+        severity: "error",
+        file: scan.relPath,
+        line: error.line,
+        message: error.message
+      });
+    }
+    if (fileIgnoreKeys.has(key)) continue;
+    if (scan.parsed.nativeIgnores.length > 0) {
+      addIssue({
+        code: "native-ignore",
+        severity: "error",
+        file: scan.relPath,
+        lines: scan.parsed.nativeIgnores.map((entry) => entry.line),
+        message:
+          "检测到原生覆盖率忽略注释（istanbul/c8/v8/node:coverage）。" +
+          "原生注释会让代码从报告中消失，绕过审计；请删除它，改用带原因的 covgate-ignore-* 指令。"
+      });
+    }
+  }
+
+  // Check for overlapping inline ranges. Overlaps make it impossible to know
+  // which explanation is responsible for which suppression.
+  for (const [key, scan] of scans) {
+    if (!expected.has(key)) continue;
+    const ranges = scan.parsed.directives.map((directive) => ({
+      startLine: directive.startLine,
+      endLine: directive.endLine,
+      directiveLine: directive.directiveLine
+    }));
+    for (const [previous, current] of findOverlaps(ranges)) {
+      addIssue({
+        code: "overlapping-waivers",
+        severity: "error",
+        file: scan.relPath,
+        line: current.directiveLine,
+        message: `豁免区间与第 ${previous.directiveLine} 行的豁免重叠，请合并为一条说明`
+      });
+    }
+  }
+
+  // Missing coverage: source includes is the source of truth. This is what
+  // prevents an AI from simply never importing a new file.
+  const missingSources = [];
+  for (const [key, file] of expected) {
+    if (coverage.files.has(key)) continue;
+    missingSources.push(file.relPath);
+    addIssue({
+      code: "missing-coverage",
+      severity: "error",
+      file: file.relPath,
+      message:
+        "源码文件未出现在任何覆盖率报告中（可能没有被测试加载）。" +
+        "请补充测试；如果确实无法统计，请用 covgate-ignore-file 写明原因。"
+    });
+  }
+
+  // Apply line/range waivers and annotate their effectiveness before mutating
+  // the coverage maps.
+  for (const [key, scan] of scans) {
+    if (!expected.has(key)) continue;
+    const directives = scan.parsed.directives;
+    if (directives.length === 0) continue;
+    const file = coverage.files.get(key);
+    for (const directive of directives) {
+      if (directive.expired) {
+        addIssue({
+          code: "expired-waiver",
+          severity: severityFor(waiverPolicy.expiry),
+          file: scan.relPath,
+          line: directive.directiveLine,
+          message: `豁免已于 ${directive.expires} 过期，请重新评估`
+        });
+      }
+      if (file) {
+        const uncovered = countUncoveredInRanges(file, [directive]);
+        const total = Object.values(uncovered).reduce((sum, count) => sum + count, 0);
+        if (total === 0) {
+          addIssue({
+            code: "stale-waiver",
+            severity: severityFor(waiverPolicy.stale),
+            file: scan.relPath,
+            line: directive.directiveLine,
+            message:
+              "豁免区间没有移除任何未覆盖代码；它可能已经失效，或说明/区间写错了位置"
+          });
+        }
+        waivers.push({
+          source: "inline",
+          kind:
+            directive.kind === "next-line"
+              ? "next-line"
+              : directive.kind === "line"
+                ? "line"
+                : "range",
+          file: scan.relPath,
+          startLine: directive.startLine,
+          endLine: directive.endLine,
+          directiveLine: directive.directiveLine,
+          reason: directive.reason,
+          owner: directive.owner,
+          expires: directive.expires,
+          ticket: directive.ticket,
+          status: directive.expired ? "expired" : total === 0 ? "stale" : "applied",
+          stale: total === 0,
+          expired: directive.expired,
+          removedUncovered: uncovered
+        });
+      } else {
+        addIssue({
+          code: "stale-waiver",
+          severity: severityFor(waiverPolicy.stale),
+          file: scan.relPath,
+          line: directive.directiveLine,
+          message: "该文件没有覆盖率记录，行级豁免无法生效；请补测试或使用 covgate-ignore-file"
+        });
+        waivers.push({
+          source: "inline",
+          kind: "range",
+          file: scan.relPath,
+          startLine: directive.startLine,
+          endLine: directive.endLine,
+          directiveLine: directive.directiveLine,
+          reason: directive.reason,
+          owner: directive.owner,
+          expires: directive.expires,
+          ticket: directive.ticket,
+          status: directive.expired ? "expired" : "stale",
+          stale: true,
+          expired: directive.expired,
+          removedUncovered: { lines: 0, statements: 0, functions: 0, branches: 0 }
+        });
+      }
+    }
+    if (file) {
+      const ranges = mergeRanges(
+        directives.map((directive) => ({
+          startLine: directive.startLine,
+          endLine: directive.endLine
+        }))
+      );
+      removeRanges(file, ranges);
+    }
+  }
+
+  // Anything outside sources.include is intentionally not gated, but surfacing
+  // it helps catch an accidentally narrow include pattern.
+  const extras = [];
+  for (const [key, file] of coverage.files) {
+    if (expected.has(key) || excludedKeys.has(key) || fileIgnoreKeys.has(key)) continue;
+    extras.push(file.relPath);
+  }
+  if (extras.length > 0) {
+    warnings.push({
+      code: "coverage-outside-sources",
+      severity: "warning",
+      message:
+        `覆盖率报告中有 ${extras.length} 个文件不在 sources.include 内，已忽略。` +
+        "如果其中有需要门禁的源码，请扩大 sources.include。",
+      files: extras.slice(0, 20)
+    });
+  }
+
+  if (expected.size === 0) {
+    addIssue({
+      code: "no-gated-sources",
+      severity: "error",
+      message:
+        "应用排除和文件豁免后，没有任何源码需要门禁。不能通过“排除全部文件”让门禁虚假通过。"
+    });
+  }
+
+  const filteredCoverage = new Map();
+  for (const [key, file] of coverage.files) {
+    if (expected.has(key)) filteredCoverage.set(key, file);
+  }
+
+  return {
+    name: scope.name,
+    label: scope.label,
+    profile: scope.profile,
+    thresholds: scope.thresholds,
+    format: coverage.format,
+    files: [...filteredCoverage.values()].sort((left, right) =>
+      left.relPath.localeCompare(right.relPath, "en")
+    ),
+    expectedSourceCount: expected.size,
+    reportedFileCount: coverage.files.size,
+    missingSources,
+    extras,
+    waivers,
+    exclusions,
+    issues,
+    warnings
+  };
+}