covgate 0.0.0-stage → 0.2.0

package/src/coverage/model.js

@@ -0,0 +1,316 @@
+import path from "node:path";
+import { canonicalPath, percentOf, relativeDisplay } from "../util.js";
+
+/**
+ * @typedef {Object} StatementUnit
+ * @property {string} key
+ * @property {number} line
+ * @property {number} column
+ * @property {number} endLine
+ * @property {number} count
+ *
+ * @typedef {Object} FunctionUnit
+ * @property {string} key
+ * @property {string} name
+ * @property {number} line
+ * @property {number} column
+ * @property {number} endLine
+ * @property {number} count
+ *
+ * @typedef {Object} BranchUnit
+ * @property {string} key
+ * @property {number} line
+ * @property {number} column
+ * @property {string} type
+ * @property {number} groupLine
+ * @property {number} index
+ * @property {number} count
+ *
+ * @typedef {Object} FileCoverage
+ * @property {string} absPath
+ * @property {string} relPath
+ * @property {"istanbul" | "lcov"} format
+ * @property {Map<string, StatementUnit> | null} statements
+ * @property {Map<string, FunctionUnit>} functions
+ * @property {Map<string, BranchUnit>} branches
+ * @property {Map<number, number>} lines
+ */
+
+/**
+ * @param {string} absPath
+ * @param {"istanbul" | "lcov"} format
+ * @param {string} root
+ * @returns {FileCoverage}
+ */
+export function createFileCoverage(absPath, format, root) {
+  return {
+    absPath: path.resolve(absPath),
+    relPath: relativeDisplay(absPath, root),
+    format,
+    statements: format === "istanbul" ? new Map() : null,
+    functions: new Map(),
+    branches: new Map(),
+    lines: new Map()
+  };
+}
+
+/**
+ * Istanbul's line coverage convention: the hit count for a line is the maximum
+ * hit count among statements that start on that line.
+ * @param {Map<string, StatementUnit> | null} statements
+ * @returns {Map<number, number>}
+ */
+export function deriveLinesFromStatements(statements) {
+  /** @type {Map<number, number>} */
+  const lines = new Map();
+  if (!statements) return lines;
+  for (const statement of statements.values()) {
+    const current = lines.get(statement.line);
+    if (current === undefined || statement.count > current) {
+      lines.set(statement.line, statement.count);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Merge another report for the same file into a base record. Counts are summed
+ * so independently-sharded test runs can be combined.
+ * @param {FileCoverage} base
+ * @param {FileCoverage} incoming
+ */
+export function mergeFileCoverage(base, incoming) {
+  if (base.format !== incoming.format) {
+    throw new Error(
+      `同一文件收到了不同格式的覆盖率数据：${base.relPath}（${base.format} / ${incoming.format}）`
+    );
+  }
+  if ((base.statements === null) !== (incoming.statements === null)) {
+    throw new Error(`同一文件收到了不兼容的语句覆盖率数据：${base.relPath}`);
+  }
+  if (base.statements && incoming.statements) {
+    mergeUnits(base.statements, incoming.statements, "语句", base.relPath);
+  }
+  mergeUnits(base.functions, incoming.functions, "函数", base.relPath);
+  mergeUnits(base.branches, incoming.branches, "分支", base.relPath);
+  for (const [line, count] of incoming.lines) {
+    base.lines.set(line, (base.lines.get(line) ?? 0) + count);
+  }
+  if (base.statements) {
+    base.lines = deriveLinesFromStatements(base.statements);
+  }
+  return base;
+}
+
+/**
+ * @template {{ key: string, line: number, count: number }} T
+ * @param {Map<string, T>} target
+ * @param {Map<string, T>} incoming
+ * @param {string} label
+ * @param {string} relPath
+ */
+function mergeUnits(target, incoming, label, relPath) {
+  for (const [key, unit] of incoming) {
+    const existing = target.get(key);
+    if (!existing) {
+      target.set(key, { ...unit });
+      continue;
+    }
+    if (existing.line !== unit.line) {
+      throw new Error(
+        `${relPath} 的${label}覆盖率数据不一致（键 ${key} 对应不同行号）`
+      );
+    }
+    existing.count += unit.count;
+  }
+}
+
+/**
+ * @param {FileCoverage} file
+ */
+export function metricsForFile(file) {
+  const withPercent = (value) => {
+    if (!value) return null;
+    return { ...value, percent: percentOf(value.covered, value.total) };
+  };
+  return {
+    lines: withPercent(countMap(file.lines)),
+    statements: file.statements ? withPercent(countMap(file.statements)) : null,
+    functions: withPercent(countMap(file.functions)),
+    branches: withPercent(countMap(file.branches))
+  };
+}
+
+/**
+ * @template {number | { count: number }} T
+ * @param {Map<string, T>} map
+ */
+function countMap(map) {
+  let covered = 0;
+  for (const value of map.values()) {
+    const count = typeof value === "number" ? value : value.count;
+    if (count > 0) covered += 1;
+  }
+  return { covered, total: map.size };
+}
+
+/**
+ * Remove rows in [startLine, endLine] from a file's normalized coverage.
+ * Statements/functions/branches are removed when their declared start line is
+ * in the range, mirroring what a human would call "this code segment".
+ * @param {FileCoverage} file
+ * @param {Array<{ startLine: number, endLine: number }>} ranges
+ * @returns {{ lines: number, statements: number, functions: number, branches: number }}
+ */
+export function removeRanges(file, ranges) {
+  const inside = (/** @type {number} */ line) =>
+    ranges.some((range) => line >= range.startLine && line <= range.endLine);
+  let removed = { lines: 0, statements: 0, functions: 0, branches: 0 };
+  for (const line of [...file.lines.keys()]) {
+    if (inside(line)) {
+      file.lines.delete(line);
+      removed.lines += 1;
+    }
+  }
+  if (file.statements) {
+    for (const [key, unit] of [...file.statements]) {
+      if (inside(unit.line)) {
+        file.statements.delete(key);
+        removed.statements += 1;
+      }
+    }
+  }
+  for (const [key, unit] of [...file.functions]) {
+    if (inside(unit.line)) {
+      file.functions.delete(key);
+      removed.functions += 1;
+    }
+  }
+  for (const [key, unit] of [...file.branches]) {
+    if (inside(unit.line)) {
+      file.branches.delete(key);
+      removed.branches += 1;
+    }
+  }
+  return removed;
+}
+
+/**
+ * Count uncovered rows that a set of ranges would remove, without mutating.
+ * Used to detect stale suppressions.
+ * @param {FileCoverage} file
+ * @param {Array<{ startLine: number, endLine: number }>} ranges
+ */
+export function countUncoveredInRanges(file, ranges) {
+  const inside = (/** @type {number} */ line) =>
+    ranges.some((range) => line >= range.startLine && line <= range.endLine);
+  let lines = 0;
+  let statements = 0;
+  let functions = 0;
+  let branches = 0;
+  for (const [line, count] of file.lines) {
+    if (count === 0 && inside(line)) lines += 1;
+  }
+  if (file.statements) {
+    for (const unit of file.statements.values()) {
+      if (unit.count === 0 && inside(unit.line)) statements += 1;
+    }
+  }
+  for (const unit of file.functions.values()) {
+    if (unit.count === 0 && inside(unit.line)) functions += 1;
+  }
+  for (const unit of file.branches.values()) {
+    if (unit.count === 0 && inside(unit.line)) branches += 1;
+  }
+  return { lines, statements, functions, branches };
+}
+
+/**
+ * @param {Iterable<number>} lines
+ * @param {number} limit
+ */
+export function summarizeLines(lines, limit = Number.POSITIVE_INFINITY) {
+  const sorted = [...new Set(lines)].sort((left, right) => left - right);
+  return {
+    values: sorted.slice(0, limit),
+    total: sorted.length,
+    truncated: sorted.length > limit
+  };
+}
+
+/**
+ * @param {Iterable<{ line: number }>} units
+ * @param {number} limit
+ */
+export function summarizeUnits(units, limit = Number.POSITIVE_INFINITY) {
+  const sorted = [...units].sort((left, right) => left.line - right.line);
+  return {
+    values: sorted.slice(0, limit),
+    total: sorted.length,
+    truncated: sorted.length > limit
+  };
+}
+
+/**
+ * @param {FileCoverage} file
+ * @param {number} [limit]
+ */
+export function fileReport(file, limit = Number.POSITIVE_INFINITY) {
+  const uncoveredLines = summarizeLines(
+    [...file.lines].filter(([, count]) => count === 0).map(([line]) => line),
+    limit
+  );
+  const uncoveredFunctions = summarizeUnits(
+    [...file.functions.values()].filter((unit) => unit.count === 0),
+    limit
+  );
+  const uncoveredBranches = summarizeUnits(
+    [...file.branches.values()].filter((unit) => unit.count === 0),
+    limit
+  );
+  const uncoveredStatements = file.statements
+    ? summarizeUnits(
+        [...file.statements.values()].filter((unit) => unit.count === 0),
+        limit
+      )
+    : null;
+  return {
+    path: file.relPath,
+    metrics: metricsForFile(file),
+    uncovered: {
+      lines: uncoveredLines.values,
+      linesTotal: uncoveredLines.total,
+      statements: uncoveredStatements?.values.map((unit) => ({
+        line: unit.line,
+        column: unit.column
+      })) ?? null,
+      statementsTotal: uncoveredStatements?.total ?? null,
+      functions: uncoveredFunctions.values.map((unit) => ({
+        name: unit.name,
+        line: unit.line
+      })),
+      functionsTotal: uncoveredFunctions.total,
+      branches: uncoveredBranches.values.map((unit) => ({
+        line: unit.line,
+        type: unit.type,
+        index: unit.index
+      })),
+      branchesTotal: uncoveredBranches.total
+    }
+  };
+}
+
+/**
+ * @param {Map<string, FileCoverage>} files
+ */
+export function mergeCoverageFiles(files) {
+  /** @type {Map<string, FileCoverage>} */
+  const merged = new Map();
+  for (const file of files.values()) {
+    const key = canonicalPath(file.absPath);
+    const existing = merged.get(key);
+    if (existing) mergeFileCoverage(existing, file);
+    else merged.set(key, file);
+  }
+  return merged;
+}

package/src/coverage/paths.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { IS_WINDOWS, toPosix } from "../util.js";
+
+/**
+ * Coverage tools disagree about path syntax. This normalizes the common cases:
+ * file:// URLs, Windows paths with a leading slash, mixed separators, and
+ * project-relative paths.
+ *
+ * @param {string} rawPath
+ * @param {string} root
+ * @returns {string}
+ */
+export function resolveCoverageSourcePath(rawPath, root) {
+  if (typeof rawPath !== "string" || rawPath.trim() === "") {
+    throw new Error("覆盖率报告包含空的源码路径");
+  }
+  let value = rawPath.trim();
+  if (value.startsWith("file://")) {
+    try {
+      value = fileURLToPath(value);
+    } catch {
+      // Keep the original value and let path handling produce a useful error.
+    }
+  }
+  if (IS_WINDOWS) {
+    if (/^\/[A-Za-z]:\//.test(value)) value = value.slice(1);
+    value = value.replaceAll("/", "\\");
+  }
+  return path.normalize(path.isAbsolute(value) ? value : path.resolve(root, value));
+}
+
+/**
+ * Paths in lcov SF records are often already relative to the project root.
+ * @param {string} rawPath
+ * @param {string} root
+ */
+export function displayCoveragePath(rawPath, root) {
+  return toPosix(path.relative(root, resolveCoverageSourcePath(rawPath, root)));
+}

package/src/errors.js

@@ -0,0 +1,34 @@
+export class CovgateError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ kind?: string, exitCode?: number, details?: unknown, cause?: unknown }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "CovgateError";
+    this.kind = options.kind ?? "error";
+    this.exitCode = options.exitCode ?? 2;
+    this.details = options.details;
+  }
+}
+
+export class ConfigError extends CovgateError {
+  constructor(message, options = {}) {
+    super(message, { ...options, kind: "config", exitCode: 2 });
+    this.name = "ConfigError";
+  }
+}
+
+export class ExecutionError extends CovgateError {
+  constructor(message, options = {}) {
+    super(message, { ...options, kind: "execution", exitCode: 3 });
+    this.name = "ExecutionError";
+  }
+}
+
+export class CoverageDataError extends CovgateError {
+  constructor(message, options = {}) {
+    super(message, { ...options, kind: "coverage-data", exitCode: 3 });
+    this.name = "CoverageDataError";
+  }
+}

package/src/gate.js

@@ -0,0 +1,203 @@
+import { fileReport, metricsForFile } from "./coverage/model.js";
+import { METRICS } from "./config.js";
+import { percentOf } from "./util.js";
+
+/**
+ * @param {number} covered
+ * @param {number} total
+ * @param {number} basisPoints
+ */
+function meetsThreshold(covered, total, basisPoints) {
+  if (total === 0) return true;
+  return covered * 10_000 >= basisPoints * total;
+}
+
+/**
+ * @param {Array<{ metrics: Record<string, { covered: number, total: number } | null> }>} files
+ * @param {string} metric
+ */
+function aggregate(files, metric) {
+  let covered = 0;
+  let total = 0;
+  let applicable = true;
+  for (const file of files) {
+    const value = file.metrics[metric];
+    if (!value) {
+      applicable = false;
+      continue;
+    }
+    covered += value.covered;
+    total += value.total;
+  }
+  return { covered, total, applicable };
+}
+
+/**
+ * Apply thresholds and issue state to an evaluated scope.
+ * Percentages are for display only; the gate compares exact integer counts.
+ *
+ * @param {any} scopeData
+ */
+export function gateScope(scopeData) {
+  const issues = [...(scopeData.issues ?? [])];
+  const warnings = [...(scopeData.warnings ?? [])];
+  const fileReports = scopeData.files.map((file) => fileReport(file));
+  const metrics = {};
+
+  for (const metric of METRICS) {
+    const counts = aggregate(fileReports, metric);
+    const threshold = scopeData.thresholds[metric];
+    if (!counts.applicable) {
+      metrics[metric] = {
+        metric,
+        applicable: false,
+        covered: 0,
+        total: 0,
+        percent: null,
+        threshold: threshold.value,
+        thresholdBasisPoints: threshold.basisPoints,
+        passed: true,
+        note: "当前覆盖率格式不提供该指标"
+      };
+      warnings.push({
+        code: "metric-not-reported",
+        severity: "warning",
+        message: `${metric} 覆盖率未由 ${scopeData.format} 报告提供，该指标不纳入本次门禁`
+      });
+      continue;
+    }
+    const passed = meetsThreshold(counts.covered, counts.total, threshold.basisPoints);
+    metrics[metric] = {
+      metric,
+      applicable: true,
+      covered: counts.covered,
+      total: counts.total,
+      percent: percentOf(counts.covered, counts.total),
+      threshold: threshold.value,
+      thresholdBasisPoints: threshold.basisPoints,
+      passed
+    };
+  }
+
+  const anyUnits = Object.values(metrics).some(
+    (metric) => metric.applicable && metric.total > 0
+  );
+  if (!anyUnits) {
+    issues.push({
+      code: "no-executable-coverage",
+      severity: "error",
+      message:
+        "scope 中没有任何可统计的代码单元。检查 sources.include、覆盖率报告路径和测试采集配置。"
+    });
+  }
+
+  const errorIssues = issues.filter((issue) => issue.severity === "error");
+  const failedMetrics = Object.values(metrics).filter(
+    (metric) => metric.applicable && !metric.passed
+  );
+  const passed = errorIssues.length === 0 && failedMetrics.length === 0;
+
+  const failingFiles = fileReports
+    .filter((file) => {
+      const uncovered =
+        file.uncovered.linesTotal +
+        (file.uncovered.statementsTotal ?? 0) +
+        file.uncovered.functionsTotal +
+        file.uncovered.branchesTotal;
+      return uncovered > 0;
+    })
+    .sort((left, right) => {
+      const leftPercent = left.metrics.lines?.percent ?? 100;
+      const rightPercent = right.metrics.lines?.percent ?? 100;
+      return leftPercent - rightPercent || left.path.localeCompare(right.path, "en");
+    });
+
+  const thresholds = Object.fromEntries(
+    METRICS.map((metric) => [metric, scopeData.thresholds[metric].value])
+  );
+
+  const result = {
+    name: scopeData.name,
+    label: scopeData.label,
+    profile: scopeData.profile,
+    format: scopeData.format,
+    passed,
+    thresholds,
+    metrics,
+    files: fileReports,
+    failingFiles,
+    expectedSourceCount: scopeData.expectedSourceCount,
+    reportedFileCount: scopeData.reportedFileCount,
+    missingSources: scopeData.missingSources,
+    extras: scopeData.extras,
+    waivers: scopeData.waivers,
+    exclusions: scopeData.exclusions,
+    issues,
+    warnings,
+    reasons: [
+      ...failedMetrics.map(
+        (metric) =>
+          `${metric.metric} 覆盖率 ${metric.percent.toFixed(2)}%，低于 ${metric.threshold}%（${metric.covered}/${metric.total}）`
+      ),
+      ...errorIssues.map((issue) => issue.message)
+    ]
+  };
+  return result;
+}
+
+/**
+ * @param {any[]} scopes
+ */
+export function gateAll(scopes) {
+  const results = scopes.map(gateScope);
+  return {
+    passed: results.every((scope) => scope.passed),
+    scopes: results
+  };
+}
+
+/**
+ * @param {any} scopeResult
+ */
+export function scopeMetricSummary(scopeResult) {
+  return METRICS.map((metric) => {
+    const value = scopeResult.metrics[metric];
+    return {
+      metric,
+      covered: value.covered,
+      total: value.total,
+      percent: value.percent,
+      threshold: value.threshold,
+      passed: value.passed
+    };
+  });
+}
+
+/**
+ * @param {any} scopeResult
+ */
+export function scopeCoveredUnits(scopeResult) {
+  const totals = { covered: 0, total: 0 };
+  for (const metric of METRICS) {
+    const value = scopeResult.metrics[metric];
+    if (!value.applicable) continue;
+    totals.covered += value.covered;
+    totals.total += value.total;
+  }
+  return totals;
+}
+
+/**
+ * @param {any} scopeResult
+ */
+export function scopeUncoveredFileCount(scopeResult) {
+  return scopeResult.failingFiles.length;
+}
+
+/**
+ * @param {any} file
+ */
+export function fileHasAnyCoverage(file) {
+  const metrics = metricsForFile(file);
+  return Object.values(metrics).some((metric) => metric && metric.total > 0);
+}