covgate 0.0.0-stage → 0.2.0

package/src/args.js

@@ -0,0 +1,189 @@
+import { ConfigError } from "./errors.js";
+
+const COMMANDS = new Set(["run", "check", "validate", "setup"]);
+const NL = String.fromCharCode(10);
+
+export const HELP_TEXT = [
+  "CovGate — AI 代码覆盖率门禁",
+  "",
+  "用法：",
+  "  covgate setup [选项]     检测/安装测试框架并生成门禁与 AI 接入配置",
+  "  covgate run [选项]       执行测试并检查覆盖率（默认命令）",
+  "  covgate check [选项]     不执行测试，只检查已有覆盖率报告",
+  "  covgate validate [选项]  只校验配置",
+  "",
+  "通用选项：",
+  "  --config <path>          配置文件路径（默认 ./covgate.config.json）",
+  "  --scope <name>           只检查指定 scope，可重复或用逗号分隔",
+  "  --no-run                 等同 check：不执行测试命令",
+  "  --json                   向 stdout 输出纯 JSON（日志走 stderr）",
+  "  --no-files               不写 .covgate/report.json 和 report.md",
+  "  --report-dir <path>      覆盖报告输出目录（相对当前目录）",
+  "  --verbose                实时转发测试命令输出到 stderr",
+  "  --color / --no-color     强制开启/关闭彩色输出",
+  "  --version                显示版本",
+  "  --help                   显示帮助",
+  "",
+  "setup 选项：",
+  "  --yes, -y                无框架时直接安装 Vitest，并接受默认配置",
+  "  --no-install             不安装测试框架",
+  "  --no-agent               不生成 AGENTS.md / Agent 脚本 / CI",
+  "  --no-config              不生成 covgate.config.json",
+  "  --profile <client|server> 强制 scope 类型，默认自动识别",
+  "  --source <glob>          源码范围，默认自动识别",
+  "  --coverage <path>        覆盖率报告路径，默认 coverage/coverage-final.json",
+  "  --test-command <command> 覆盖测试命令",
+  "  --force                  覆盖已有配置和 setup 生成的文件",
+  "  --dry-run                只打印计划，不写文件、不安装依赖",
+  "",
+  "硬性门槛（配置不可低于）：",
+  "  profile=client  行/语句/函数/分支覆盖率必须 100%",
+  "  profile=server  行/语句/函数/分支覆盖率必须至少 95%",
+  "",
+  "覆盖不到的代码必须写 covgate-ignore-* 说明，例如：",
+  "  // covgate-ignore-next-line: 平台灰度开关在 v1 永远不会开启 | owner=web | expires=2027-12-31",
+  "  // covgate-ignore-file: OpenAPI 生成文件，不手工维护 | owner=api",
+  "",
+  "退出码：0 通过；1 覆盖率/审计不通过；2 配置或用法错误；3 测试失败/报告读取失败。",
+  "",
+  "参见 README.md 与 docs/design.md。"
+].join(NL);
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const options = {
+    command: "run",
+    configPath: undefined,
+    scopes: [],
+    json: false,
+    noRun: false,
+    noFiles: false,
+    reportDir: undefined,
+    verbose: false,
+    color: undefined,
+    help: false,
+    version: false,
+    yes: false,
+    installFramework: true,
+    noAgent: false,
+    noConfig: false,
+    force: false,
+    dryRun: false,
+    profile: undefined,
+    source: undefined,
+    coverage: undefined,
+    testCommand: undefined
+  };
+
+  let index = 0;
+  let explicitCommand = false;
+  if (argv[0] === "help") {
+    options.help = true;
+    return options;
+  }
+  if (argv[0] && COMMANDS.has(argv[0])) {
+    options.command = argv[0];
+    explicitCommand = true;
+    index = 1;
+  } else if (argv[0] && !argv[0].startsWith("-")) {
+    throw new ConfigError('未知命令 "' + argv[0] + '"，可用命令：setup、run、check、validate');
+  }
+
+  for (; index < argv.length; index += 1) {
+    const argument = argv[index];
+    let key = argument;
+    let inlineValue;
+    if (argument.startsWith("--") && argument.includes("=")) {
+      const separator = argument.indexOf("=");
+      key = argument.slice(0, separator);
+      inlineValue = argument.slice(separator + 1);
+    }
+
+    const value = () => {
+      if (inlineValue !== undefined) return inlineValue;
+      index += 1;
+      if (index >= argv.length || argv[index].startsWith("--")) {
+        throw new ConfigError("选项 " + key + " 缺少值");
+      }
+      return argv[index];
+    };
+
+    if (argument === "help") {
+      options.help = true;
+      continue;
+    }
+    if (COMMANDS.has(argument) && !explicitCommand && !argument.startsWith("-")) {
+      options.command = argument;
+      explicitCommand = true;
+      continue;
+    }
+    if (COMMANDS.has(argument) && explicitCommand && index > 0) {
+      throw new ConfigError("命令只能指定一次");
+    }
+
+    if (key === "--config") {
+      options.configPath = value();
+    } else if (key === "--scope") {
+      const scopeValue = value();
+      for (const name of scopeValue.split(",")) {
+        const trimmed = name.trim();
+        if (trimmed && !options.scopes.includes(trimmed)) options.scopes.push(trimmed);
+      }
+    } else if (key === "--json") {
+      options.json = true;
+    } else if (key === "--no-run") {
+      options.noRun = true;
+    } else if (key === "--no-files") {
+      options.noFiles = true;
+    } else if (key === "--report-dir") {
+      options.reportDir = value();
+    } else if (key === "--verbose") {
+      options.verbose = true;
+    } else if (key === "--color") {
+      options.color = true;
+    } else if (key === "--no-color") {
+      options.color = false;
+    } else if (key === "--yes" || key === "-y") {
+      options.yes = true;
+    } else if (key === "--no-install") {
+      options.installFramework = false;
+    } else if (key === "--no-agent") {
+      options.noAgent = true;
+    } else if (key === "--no-config") {
+      options.noConfig = true;
+    } else if (key === "--force") {
+      options.force = true;
+    } else if (key === "--dry-run") {
+      options.dryRun = true;
+    } else if (key === "--profile") {
+      options.profile = value();
+    } else if (key === "--source") {
+      options.source = value();
+    } else if (key === "--coverage") {
+      options.coverage = value();
+    } else if (key === "--test-command") {
+      options.testCommand = value();
+    } else if (key === "--help" || key === "-h") {
+      options.help = true;
+    } else if (key === "--version") {
+      options.version = true;
+    } else {
+      throw new ConfigError('未知选项 "' + argument + '"；运行 covgate --help 查看用法');
+    }
+  }
+
+  if (options.command === "check") options.noRun = true;
+  if (options.command !== "setup" && (options.yes || options.profile || options.source || options.coverage || options.testCommand || options.noAgent || options.noConfig || options.force || options.dryRun || !options.installFramework)) {
+    throw new ConfigError("setup 相关选项只能和 covgate setup 一起使用");
+  }
+  return options;
+}
+
+/**
+ * @param {string[]} argv
+ */
+export function wantsJson(argv) {
+  return argv.includes("--json");
+}

package/src/cli.js

@@ -0,0 +1,486 @@
+import path from "node:path";
+import { parseArgs, HELP_TEXT, wantsJson } from "./args.js";
+import {
+  loadConfig,
+  resolveConfigPath,
+  selectScopes,
+  METRICS
+} from "./config.js";
+import { CovgateError, ExecutionError } from "./errors.js";
+import { loadCoverage } from "./coverage/index.js";
+import { gateScope } from "./gate.js";
+import {
+  expandCoverageReportFiles,
+  findStaleReports,
+  snapshotReportFiles
+} from "./reports.js";
+import {
+  buildReport,
+  plannedArtifactPaths,
+  renderTextReport,
+  writeReportArtifacts
+} from "./report/index.js";
+import { printCommandFailure, runScopeCommands } from "./runner.js";
+import { evaluateScope } from "./scope.js";
+import { runSetup } from "./setup/index.js";
+import { validateReason } from "./reason.js";
+import {
+  formatThreshold,
+  relativeDisplay,
+  tail
+} from "./util.js";
+import { VERSION } from "./version.js";
+
+const METRIC_LABELS = {
+  lines: "行",
+  statements: "语句",
+  functions: "函数",
+  branches: "分支"
+};
+
+const NL = String.fromCharCode(10);
+
+function logger() {
+  return {
+    info(message) {
+      process.stderr.write(message + "\n");
+    },
+    warn(message) {
+      process.stderr.write("警告: " + message + "\n");
+    },
+    error(message) {
+      process.stderr.write("错误: " + message + "\n");
+    }
+  };
+}
+
+/**
+ * @param {unknown} error
+ * @param {boolean} json
+ * @param {boolean} includeStack
+ */
+function printEarlyError(error, json, includeStack = false) {
+  const message = error instanceof Error ? error.message : String(error);
+  const exitCode = error instanceof CovgateError ? error.exitCode : 2;
+  if (includeStack && error instanceof Error && error.stack) {
+    process.stderr.write(error.stack + "\n");
+  }
+  if (json) {
+    const body = {
+      schemaVersion: 1,
+      tool: { name: "covgate", version: VERSION },
+      status: "error",
+      exitCode,
+      generatedAt: new Date().toISOString(),
+      issues: [
+        {
+          code: error instanceof CovgateError ? error.kind : "error",
+          severity: "error",
+          message
+        }
+      ]
+    };
+    process.stdout.write(JSON.stringify(body, null, 2) + "\n");
+  } else {
+    process.stderr.write("CovGate 错误: " + message + "\n");
+  }
+  return exitCode;
+}
+
+/**
+ * @param {any} options
+ */
+async function runSetupCommand(options) {
+  const log = options.json
+    ? (message) => process.stderr.write(message + NL)
+    : (message) => process.stdout.write(message + NL);
+  try {
+    const summary = await runSetup({
+      root: process.cwd(),
+      yes: options.yes,
+      installFramework: options.installFramework,
+      profile: options.profile,
+      source: options.source,
+      coverage: options.coverage,
+      testCommand: options.testCommand,
+      noAgent: options.noAgent,
+      noConfig: options.noConfig,
+      force: options.force,
+      dryRun: options.dryRun,
+      log
+    });
+    if (options.json) {
+      process.stdout.write(JSON.stringify({
+        schemaVersion: 1,
+        tool: { name: "covgate", version: VERSION },
+        status: "ok",
+        ...summary
+      }, null, 2) + NL);
+    }
+    return 0;
+  } catch (error) {
+    return printEarlyError(error, options.json, options.verbose);
+  }
+}
+
+/**
+ * @param {any} config
+ * @param {any[]} scopes
+ * @param {any} options
+ */
+function printValidate(config, scopes, options) {
+  const problems = [];
+  for (const scope of scopes) {
+    for (const entry of scope.exclude) {
+      const validation = validateReason(
+        entry.reason,
+        config.waivers,
+        { owner: entry.owner, expires: entry.expires },
+        new Date()
+      );
+      for (const message of validation.errors) {
+        problems.push({
+          code: "invalid-exclusion",
+          severity: "error",
+          scope: scope.name,
+          message: "exclude \"" + entry.pattern + "\" 的说明无效：" + message
+        });
+      }
+      if (validation.expired) {
+        problems.push({
+          code: "expired-exclusion",
+          severity: config.waivers.expiry === "fail" ? "error" : "warning",
+          scope: scope.name,
+          message: "exclude \"" + entry.pattern + "\" 已于 " + entry.expires + " 过期"
+        });
+      }
+    }
+  }
+  if (problems.some((problem) => problem.severity === "error")) {
+    if (options.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            tool: { name: "covgate", version: VERSION },
+            status: "error",
+            exitCode: 2,
+            config: relativeDisplay(config.configPath, config.root),
+            issues: problems
+          },
+          null,
+          2
+        ) + "\n"
+      );
+    } else {
+      for (const problem of problems) {
+        process.stderr.write("配置错误: " + problem.message + "\n");
+      }
+    }
+    return 2;
+  }
+  for (const problem of problems) {
+    process.stderr.write("警告: " + problem.message + "\n");
+  }
+
+  const rows = scopes.map((scope) => ({
+    name: scope.name,
+    label: scope.label,
+    profile: scope.profile,
+    thresholds: Object.fromEntries(
+      METRICS.map((metric) => [metric, scope.thresholds[metric].value])
+    ),
+    commands: scope.commands.length,
+    coverageFormat: scope.coverage.format,
+    coveragePaths: scope.coverage.paths,
+    sourceInclude: scope.sources.include,
+    excludeCount: scope.exclude.length
+  }));
+  if (options.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          tool: { name: "covgate", version: VERSION },
+          status: "ok",
+          config: relativeDisplay(config.configPath, config.root),
+          scopes: rows
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 0;
+  }
+  process.stdout.write("✓ 配置有效: " + config.configPath + "\n");
+  for (const row of rows) {
+    process.stdout.write("\n[" + row.name + "] " + row.label + " (" + row.profile + ")\n");
+    process.stdout.write(
+      "  门槛: " +
+        METRICS.map(
+          (metric) =>
+            METRIC_LABELS[metric] + " ≥ " + formatThreshold(row.thresholds[metric]) + "%"
+        ).join(" · ") +
+        "\n"
+    );
+    process.stdout.write(
+      "  测试命令: " +
+        row.commands +
+        " 条 · 覆盖率格式: " +
+        row.coverageFormat +
+        " · 报告: " +
+        row.coveragePaths.join(", ") +
+        "\n"
+    );
+    process.stdout.write(
+      "  源码: " +
+        row.sourceInclude.join(", ") +
+        " · 配置排除: " +
+        row.excludeCount +
+        " 条\n"
+    );
+  }
+  process.stdout.write("\n报告目录: " + config.reports.dir + "\n");
+  return 0;
+}
+
+/**
+ * @param {any} report
+ * @param {any} options
+ * @param {{ json?: string, markdown?: string }} paths
+ */
+async function emitReport(report, options, paths) {
+  const writeErrors = await writeReportArtifacts(report, paths);
+  for (const message of writeErrors) {
+    process.stderr.write("警告: " + message + "\n");
+  }
+  if (options.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+  } else {
+    const color =
+      options.color === false
+        ? false
+        : options.color === true
+          ? true
+          : Boolean(process.stdout.isTTY);
+    process.stdout.write(renderTextReport(report, { color }));
+  }
+  return report.exitCode;
+}
+
+/**
+ * @param {unknown} error
+ */
+function commandRecordFromError(error) {
+  if (!(error instanceof Error)) return null;
+  const details = /** @type {any} */ (error).details;
+  if (details && typeof details.stdout === "string" && typeof details.stderr === "string") {
+    return details;
+  }
+  return null;
+}
+
+/**
+ * @param {{
+ *   config: any,
+ *   scopes: any[],
+ *   options: any,
+ *   startedAt: string,
+ *   startedMs: number,
+ *   log: any
+ * }} context
+ */
+async function executeGate(context) {
+  const { config, scopes, options, startedAt, startedMs, log } = context;
+  const mode = options.noRun ? "check" : "run";
+  const commands = [];
+  const scopeResults = [];
+  const topLevelIssues = [];
+  const paths = plannedArtifactPaths(config, options.noFiles);
+
+  const finish = async () => {
+    const report = buildReport({
+      config,
+      mode,
+      scopes: scopeResults,
+      commands,
+      topLevelIssues,
+      durationMs: Date.now() - startedMs,
+      startedAt,
+      artifactPaths: paths
+    });
+    return emitReport(report, options, paths);
+  };
+
+  try {
+    log.info(
+      "CovGate " +
+        VERSION +
+        " · " +
+        (mode === "run" ? "执行测试" : "只检查已有报告") +
+        " · " +
+        relativeDisplay(config.configPath, config.root)
+    );
+    for (const scope of scopes) {
+      log.info("\n[" + scope.name + "] " + scope.label + " (" + scope.profile + ")");
+      /** @type {Map<string, { path: string, mtimeMs: number, size: number }>} */
+      let before = new Map();
+      if (mode === "run") {
+        const existingReports = await expandCoverageReportFiles(scope, config.root);
+        before = await snapshotReportFiles(existingReports);
+        const ran = await runScopeCommands(scope, {
+          verbose: options.verbose,
+          root: config.root,
+          logger: log
+        });
+        commands.push(...ran);
+      }
+
+      const reportFiles = await expandCoverageReportFiles(scope, config.root);
+      if (reportFiles.length === 0) {
+        throw new ExecutionError(
+          "scope " +
+            scope.name +
+            " 没有找到覆盖率报告。检查 coverage.paths：" +
+            scope.coverage.paths.join(", ")
+        );
+      }
+
+      if (mode === "run") {
+        const stale = await findStaleReports(before, reportFiles);
+        if (stale.length > 0) {
+          throw new ExecutionError(
+            "以下覆盖率报告在本次测试后没有更新，拒绝使用旧数据：\n  " +
+              stale.map((file) => relativeDisplay(file, config.root)).join("\n  "),
+            {
+              details: {
+                staleReports: stale.map((file) => relativeDisplay(file, config.root))
+              }
+            }
+          );
+        }
+      }
+
+      log.info(
+        "  覆盖率报告: " +
+          reportFiles
+            .map((file) => relativeDisplay(file, config.root))
+            .join(", ")
+      );
+      const coverage = await loadCoverage({
+        reportFiles,
+        format: scope.coverage.format,
+        root: config.root
+      });
+      const evaluated = await evaluateScope({
+        scope,
+        root: config.root,
+        coverage,
+        waiverPolicy: config.waivers
+      });
+      const gated = gateScope(evaluated);
+      scopeResults.push(gated);
+      log.info(
+        "  " +
+          (gated.passed ? "✓" : "✗") +
+          " " +
+          METRICS.map((metric) => {
+            const value = gated.metrics[metric];
+            return (
+              METRIC_LABELS[metric] +
+              " " +
+              (value.applicable
+                ? (value.percent === null ? "N/A" : value.percent.toFixed(2) + "%")
+                : "N/A")
+            );
+          }).join(" · ")
+      );
+    }
+    return await finish();
+  } catch (error) {
+    const record = commandRecordFromError(error);
+    if (record) {
+      printCommandFailure(record);
+      if (Array.isArray(record.priorCommands)) commands.push(...record.priorCommands);
+      commands.push(record);
+    }
+    const issue = {
+      code: error instanceof CovgateError ? error.kind : "run-error",
+      severity: "error",
+      message: error instanceof Error ? error.message : String(error)
+    };
+    if (record) {
+      issue.outputTail = tail(
+        ((record.stdout ?? "") + "\n" + (record.stderr ?? "")).trim(),
+        12_000
+      );
+    }
+    const details = /** @type {any} */ (error)?.details;
+    if (Array.isArray(details?.staleReports)) issue.files = details.staleReports;
+    topLevelIssues.push(issue);
+    if (options.verbose && error instanceof Error && error.stack) {
+      log.error(error.stack);
+    } else if (error instanceof Error) {
+      log.error(error.message);
+    }
+    return await finish();
+  }
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function main(argv) {
+  const startedAt = new Date().toISOString();
+  const startedMs = Date.now();
+  const jsonRequested = wantsJson(argv);
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    return printEarlyError(error, jsonRequested);
+  }
+  if (options.help) {
+    process.stdout.write(HELP_TEXT + "\n");
+    return 0;
+  }
+  if (options.version) {
+    process.stdout.write(VERSION + "\n");
+    return 0;
+  }
+
+  if (options.command === "setup") {
+    return runSetupCommand(options);
+  }
+
+  let config;
+  let scopes;
+  try {
+    const configPath = resolveConfigPath(process.cwd(), options.configPath);
+    config = await loadConfig(configPath);
+    if (options.reportDir) {
+      config.reports.dir = path.resolve(process.cwd(), options.reportDir);
+    }
+    scopes = selectScopes(config, options.scopes);
+  } catch (error) {
+    return printEarlyError(error, options.json, options.verbose);
+  }
+
+  if (options.command === "validate") {
+    return printValidate(config, scopes, options);
+  }
+
+  const log = logger();
+  try {
+    return await executeGate({
+      config,
+      scopes,
+      options,
+      startedAt,
+      startedMs,
+      log
+    });
+  } catch (error) {
+    return printEarlyError(error, options.json, options.verbose);
+  }
+}