covgate 0.2.1 → 0.2.2

package/README.md

@@ -48,7 +48,7 @@ covgate run
 
 ### 从 npm registry 安装（推荐）
 
-包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.2.1**。
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.2.2**。
 
 ```bash
 npm install --save-dev covgate
@@ -185,7 +185,7 @@ node bin/covgate.js --help
   },
   "reports": {
     "dir": ".covgate",
-    "formats": ["json", "markdown"]
+    "formats": ["json", "markdown", "html"]
   }
 }
 ```
@@ -248,7 +248,9 @@ npx --no-install covgate validate
 | `--config <path>` | 指定配置文件。 |
 | `--scope <name>` | 只检查指定 scope，可重复或逗号分隔。 |
 | `--json` | stdout 只输出 JSON；过程日志走 stderr。 |
-| `--no-files` | 不写 `.covgate/report.json` / `report.md`。 |
+| `--changed` | 只门禁/展示本次 Git 变更文件；默认对比 `HEAD`。 |
+| `--base <rev>` | 配合 `--changed` 指定 Git 对比版本，例如 `HEAD^`。 |
+| `--no-files` | 不写 `.covgate/report.json` / `report.md` / `report.html`。 |
 | `--report-dir <path>` | 覆盖报告目录（相对当前目录）。 |
 | `--verbose` | 实时转发测试命令输出。 |
 | `--color` / `--no-color` | 控制彩色输出。 |
@@ -266,6 +268,25 @@ setup 的完整选项见 [安装与自动配置](docs/setup.md)。
 
 CI 只需要判断退出码是否为 0。
 
+### 只检查 Git 变更文件
+
+```bash
+# 工作区相对 HEAD 的新增/修改（包含未跟踪的新文件）
+npx --no-install covgate run --changed
+
+# 检查最新一次提交相对父提交的变更
+npx --no-install covgate run --changed --base HEAD^
+
+# PR / CI：相对目标分支
+npx --no-install covgate run --changed --base origin/main
+```
+
+`--changed` 会把每个 scope 的源码范围收窄到变更文件，并只对这些文件计算覆盖率、展示文件和执行 100%/95% 门槛；未变更文件不会因为本次门禁被误判。HTML 报告也只列出变更文件。
+
+它**不会自动筛选测试用例**。测试命令仍是项目在 `commands` 中配置的命令（通常是全量测试），CovGate 只负责覆盖率范围。测试命令自己决定跑哪些测试，才能避免漏掉依赖变更。
+
+如果变更文件全部不在任何 scope 的 `sources.include` 内，CovGate 会失败而不是虚假通过。
+
 ## 配置参考
 
 ### profile
@@ -328,7 +349,7 @@ CI 只需要判断退出码是否为 0。
 ### reports
 
 - `dir`：输出目录，默认 `.covgate`。
-- `formats`：`json`、`markdown`。
+- `formats`：`json`、`markdown`、`html`。
 
 ## 写豁免：不可达代码的唯一方式
 
@@ -435,13 +456,24 @@ stdout 是纯 JSON，代理可以读取 `status`、`scopes[].failingFiles`、`is
 
 每次运行默认写：
 
-- `.covgate/report.json`：机器可读，包含 scope 指标、失败文件、逐行未覆盖、全部豁免、排除、命令、退出码。
+- `.covgate/report.json`：机器可读，包含 scope 指标、失败文件、逐行未覆盖、行命中、全部豁免、排除、命令、退出码。
 - `.covgate/report.md`：人类/评审可读的审计报告。
+- `.covgate/report.html`：自包含网页查看器；左侧文件列表，中间源码，已覆盖行绿色背景、未覆盖行白色背景、非可执行行灰色。
+
+打开网页：
+
+```powershell
+start .covgate\report.html
+```
+
+macOS 用 `open .covgate/report.html`，Linux 用 `xdg-open .covgate/report.html`。
+
+![CovGate 覆盖率查看页：左侧文件列表，中间源码，绿色已覆盖、白色未覆盖](docs/coverage-viewer.png)
 
 文本输出示例：
 
 ```text
-CovGate · 覆盖率门禁 v0.2.1
+CovGate · 覆盖率门禁 v0.2.2
 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s
 
 ✗ 客户端 [client/client] 未通过
@@ -451,6 +483,7 @@ CovGate · 覆盖率门禁 v0.2.1
 
 结果: 未通过
 JSON 报告: .covgate/report.json
+HTML 报告: .covgate/report.html
 ```
 
 建议把 `.covgate/` 加入 `.gitignore`。报告是本次运行的产物，不是源码。

package/docs/design.md

@@ -69,7 +69,7 @@ covgate.config.json
       └─ 不通过 ─▶ 1
       │
       ▼
-[写 report.json / report.md]
+[写 report.json / report.md / report.html]
 ```
 
 ## 4. 配置与信任边界

package/docs/setup.md

@@ -9,7 +9,7 @@ npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.2.1**。
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.2.2**。
 
 > `0.0.0-stage` 是 npm 暂存发布产生的占位版本，不会被 `npm install covgate` 选中，可以忽略。
 
@@ -38,7 +38,7 @@ npm 11.19+ 默认不执行依赖的 `postinstall`，会显示类似：
 
 ```text
 npm warn install-scripts 1 package has install scripts not yet covered by allowScripts
-npm warn install-scripts   covgate@0.2.1 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.2.2 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "covgate",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "覆盖率门禁：客户端 100%，服务端至少 95%，安装时自动检测/配置测试框架与 AI 编码代理接入。",
   "type": "module",
   "bin": {

package/schema/covgate.schema.json

@@ -281,12 +281,14 @@
           "items": {
             "enum": [
               "json",
-              "markdown"
+              "markdown",
+              "html"
             ]
           },
           "default": [
             "json",
-            "markdown"
+            "markdown",
+            "html"
           ]
         }
       }

package/src/args.js

@@ -16,6 +16,8 @@ export const HELP_TEXT = [
   "  --config <path>          配置文件路径（默认 ./covgate.config.json）",
   "  --scope <name>           只检查指定 scope，可重复或用逗号分隔",
   "  --no-run                 等同 check：不执行测试命令",
+  "  --changed                只门禁/展示 Git 变更文件（默认对比 HEAD）",
+  "  --base <rev>             配合 --changed，指定 Git 对比版本（如 HEAD^）",
   "  --json                   向 stdout 输出纯 JSON（日志走 stderr）",
   "  --no-files               不写 .covgate/report.json 和 report.md",
   "  --report-dir <path>      覆盖报告输出目录（相对当前目录）",
@@ -61,6 +63,8 @@ export function parseArgs(argv) {
     noRun: false,
     noFiles: false,
     reportDir: undefined,
+    changed: false,
+    base: undefined,
     verbose: false,
     color: undefined,
     help: false,
@@ -137,6 +141,10 @@ export function parseArgs(argv) {
       options.noRun = true;
     } else if (key === "--no-files") {
       options.noFiles = true;
+    } else if (key === "--changed") {
+      options.changed = true;
+    } else if (key === "--base") {
+      options.base = value();
     } else if (key === "--report-dir") {
       options.reportDir = value();
     } else if (key === "--verbose") {
@@ -178,6 +186,12 @@ export function parseArgs(argv) {
   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 一起使用");
   }
+  if (options.base && !options.changed) {
+    throw new ConfigError("--base 必须和 --changed 一起使用");
+  }
+  if (options.changed && !["run", "check"].includes(options.command)) {
+    throw new ConfigError("--changed 只能用于 covgate run 或 covgate check");
+  }
   return options;
 }
 

package/src/cli.js

@@ -9,6 +9,7 @@ import {
 import { CovgateError, ExecutionError } from "./errors.js";
 import { loadCoverage } from "./coverage/index.js";
 import { gateScope } from "./gate.js";
+import { changedFileKeys, collectChangedFiles } from "./git.js";
 import {
   expandCoverageReportFiles,
   findStaleReports,
@@ -249,8 +250,8 @@ function printValidate(config, scopes, options) {
  * @param {any} options
  * @param {{ json?: string, markdown?: string }} paths
  */
-async function emitReport(report, options, paths) {
-  const writeErrors = await writeReportArtifacts(report, paths);
+async function emitReport(report, options, paths, config) {
+  const writeErrors = await writeReportArtifacts(report, paths, config);
   for (const message of writeErrors) {
     process.stderr.write("警告: " + message + "\n");
   }
@@ -297,6 +298,8 @@ async function executeGate(context) {
   const scopeResults = [];
   const topLevelIssues = [];
   const paths = plannedArtifactPaths(config, options.noFiles);
+  let changed = null;
+  let changedKeys = null;
 
   const finish = async () => {
     const report = buildReport({
@@ -307,9 +310,10 @@ async function executeGate(context) {
       topLevelIssues,
       durationMs: Date.now() - startedMs,
       startedAt,
-      artifactPaths: paths
+      artifactPaths: paths,
+      changed
     });
-    return emitReport(report, options, paths);
+    return emitReport(report, options, paths, config);
   };
 
   try {
@@ -321,6 +325,27 @@ async function executeGate(context) {
         " · " +
         relativeDisplay(config.configPath, config.root)
     );
+    if (options.changed) {
+      changed = await collectChangedFiles({
+        root: config.root,
+        base: options.base || "HEAD"
+      });
+      if (changed.files.length === 0) {
+        throw new ExecutionError(
+          "没有检测到相对 " +
+            changed.base +
+            " 的新增/修改文件。请确认 Git 基线，或用 --base 指定版本。"
+        );
+      }
+      changedKeys = changedFileKeys(changed.files);
+      log.info(
+        "变更文件: " +
+          changed.relativeFiles.join(", ") +
+          "（base " +
+          changed.base +
+          "）"
+      );
+    }
     for (const scope of scopes) {
       log.info("\n[" + scope.name + "] " + scope.label + " (" + scope.profile + ")");
       /** @type {Map<string, { path: string, mtimeMs: number, size: number }>} */
@@ -376,13 +401,14 @@ async function executeGate(context) {
         scope,
         root: config.root,
         coverage,
-        waiverPolicy: config.waivers
+        waiverPolicy: config.waivers,
+        changedKeys
       });
       const gated = gateScope(evaluated);
       scopeResults.push(gated);
       log.info(
         "  " +
-          (gated.passed ? "✓" : "✗") +
+          (gated.skipped ? "○" : gated.passed ? "✓" : "✗") +
           " " +
           METRICS.map((metric) => {
             const value = gated.metrics[metric];
@@ -396,6 +422,15 @@ async function executeGate(context) {
           }).join(" · ")
       );
     }
+    if (
+      options.changed &&
+      scopeResults.length > 0 &&
+      scopeResults.every((scope) => scope.skipped)
+    ) {
+      throw new ExecutionError(
+        "变更文件不在任何 scope 的 sources.include 中，无法执行覆盖率门禁。"
+      );
+    }
     return await finish();
   } catch (error) {
     const record = commandRecordFromError(error);

package/src/config.js

@@ -40,7 +40,7 @@ const WAIVER_KEYS = new Set([
 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 REPORT_FORMATS = new Set(["json", "markdown", "html"]);
 const POLICIES = new Set(["fail", "warn"]);
 
 /**
@@ -350,7 +350,7 @@ export function normalizeConfig(raw, context) {
     }
   }
 
-  const reports = { dir: ".covgate", formats: ["json", "markdown"] };
+  const reports = { dir: ".covgate", formats: ["json", "markdown", "html"] };
   if (raw.reports !== undefined) {
     assertObject(raw.reports, "reports", [...REPORT_KEYS]);
     if (raw.reports.dir !== undefined) {

package/src/coverage/model.js

@@ -277,6 +277,9 @@ export function fileReport(file, limit = Number.POSITIVE_INFINITY) {
   return {
     path: file.relPath,
     metrics: metricsForFile(file),
+    lineHits: Object.fromEntries(
+      [...file.lines].sort((left, right) => left[0] - right[0])
+    ),
     uncovered: {
       lines: uncoveredLines.values,
       linesTotal: uncoveredLines.total,

package/src/gate.js

@@ -41,6 +41,52 @@ function aggregate(files, metric) {
 export function gateScope(scopeData) {
   const issues = [...(scopeData.issues ?? [])];
   const warnings = [...(scopeData.warnings ?? [])];
+  const initialErrorIssues = issues.filter((issue) => issue.severity === "error");
+  const thresholds = Object.fromEntries(
+    METRICS.map((metric) => [metric, scopeData.thresholds[metric].value])
+  );
+
+  if (scopeData.skipped) {
+    const metrics = Object.fromEntries(
+      METRICS.map((metric) => [
+        metric,
+        {
+          metric,
+          applicable: false,
+          covered: 0,
+          total: 0,
+          percent: null,
+          threshold: thresholds[metric],
+          thresholdBasisPoints: scopeData.thresholds[metric].basisPoints,
+          passed: true,
+          note: "本次 Git 变更未涉及该 scope"
+        }
+      ])
+    );
+    return {
+      name: scopeData.name,
+      label: scopeData.label,
+      profile: scopeData.profile,
+      format: scopeData.format,
+      passed: initialErrorIssues.length === 0,
+      skipped: true,
+      changedOnly: Boolean(scopeData.changedOnly),
+      thresholds,
+      metrics,
+      files: [],
+      failingFiles: [],
+      expectedSourceCount: 0,
+      reportedFileCount: scopeData.reportedFileCount,
+      missingSources: [],
+      extras: [],
+      waivers: scopeData.waivers,
+      exclusions: scopeData.exclusions,
+      issues,
+      warnings,
+      reasons: errorIssues.map((issue) => issue.message)
+    };
+  }
+
   const fileReports = scopeData.files.map((file) => fileReport(file));
   const metrics = {};
 
@@ -112,16 +158,14 @@ export function gateScope(scopeData) {
       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,
+    skipped: false,
+    changedOnly: Boolean(scopeData.changedOnly),
     thresholds,
     metrics,
     files: fileReports,

package/src/git.js

@@ -0,0 +1,86 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ConfigError } from "./errors.js";
+import { canonicalPath, relativeDisplay } from "./util.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+async function git(cwd, args) {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+      maxBuffer: 20 * 1024 * 1024,
+      windowsHide: true
+    });
+    return stdout;
+  } catch (error) {
+    throw new ConfigError(
+      "Git 命令失败：" + (error.stderr?.toString().trim() || error.message),
+      { cause: error }
+    );
+  }
+}
+
+/**
+ * Collect added/copied/modified/renamed files between a base revision and the
+ * current working tree. Untracked files are included because AI agents often
+ * add new files before staging them.
+ *
+ * @param {{ root: string, base?: string }} options
+ */
+export async function collectChangedFiles({ root, base = "HEAD" }) {
+  const projectRoot = path.resolve(root);
+  const gitRoot = (await git(projectRoot, ["rev-parse", "--show-toplevel"]))
+    .trim()
+    .replaceAll("\\", "/");
+  if (!gitRoot) throw new ConfigError("当前目录不在 Git 仓库中，不能使用 --changed。");
+  try {
+    await git(projectRoot, ["rev-parse", "--verify", base + "^{commit}"]);
+  } catch (error) {
+    throw new ConfigError('找不到 Git base 版本 "' + base + '"。', { cause: error });
+  }
+
+  const tracked = (
+    await git(projectRoot, [
+      "diff",
+      "--name-only",
+      "--diff-filter=ACMR",
+      "-M",
+      base,
+      "--"
+    ])
+  )
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const untracked = (
+    await git(projectRoot, ["ls-files", "--others", "--exclude-standard"])
+  )
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const all = [...new Set([...tracked, ...untracked])]
+    .map((relative) => path.resolve(gitRoot, relative))
+    .filter((absolute) => existsSync(absolute))
+    .sort((left, right) => left.localeCompare(right, "en"));
+
+  return {
+    base,
+    gitRoot,
+    files: all,
+    relativeFiles: all.map((file) => relativeDisplay(file, projectRoot))
+  };
+}
+
+/**
+ * @param {string[]} files
+ */
+export function changedFileKeys(files) {
+  return new Set(files.map((file) => canonicalPath(file)));
+}

package/src/index.js

@@ -20,6 +20,7 @@ export { gateAll, gateScope } from "./gate.js";
 export {
   buildReport,
   plannedArtifactPaths,
+  renderHtmlReport,
   renderMarkdownReport,
   renderTextReport,
   writeReportArtifacts

package/src/report/build.js

@@ -46,7 +46,8 @@ function countScopeState(scopes) {
  *   topLevelIssues: any[],
  *   durationMs: number,
  *   startedAt: string,
- *   artifactPaths: { json?: string, markdown?: string }
+ *   artifactPaths: { json?: string, markdown?: string, html?: string },
+ *   changed?: { base: string, relativeFiles: string[] } | null
  * }} options
  */
 export function buildReport({
@@ -57,7 +58,8 @@ export function buildReport({
   topLevelIssues,
   durationMs,
   startedAt,
-  artifactPaths
+  artifactPaths,
+  changed
 }) {
   const errors = topLevelIssues.filter((issue) => issue.severity !== "warning");
   const hasExecutionError = errors.length > 0;
@@ -67,6 +69,9 @@ export function buildReport({
   const state = countScopeState(scopes);
   const failedScopes = scopes.filter((scope) => !scope.passed).map((scope) => scope.name);
   const artifacts = artifactDisplay(config, artifactPaths);
+  const changedSummary = changed
+    ? { enabled: true, base: changed.base, files: changed.relativeFiles }
+    : null;
 
   const sanitizedCommands = commands.map((command) => {
     const record = {
@@ -103,7 +108,8 @@ export function buildReport({
     },
     summary: {
       scopes: scopes.length,
-      passedScopes: scopes.filter((scope) => scope.passed).length,
+      passedScopes: scopes.filter((scope) => scope.passed && !scope.skipped).length,
+      skippedScopes: scopes.filter((scope) => scope.skipped).map((scope) => scope.name),
       failedScopes,
       waivers: state.waivers,
       exclusions: state.exclusions,
@@ -111,6 +117,7 @@ export function buildReport({
       errors: state.errors + errors.length,
       warnings: state.warnings
     },
+    changed: changedSummary,
     issues: topLevelIssues,
     commands: sanitizedCommands,
     scopes,
@@ -131,5 +138,8 @@ export function plannedArtifactPaths(config, noFiles = false) {
   if (config.reports.formats.includes("markdown")) {
     paths.markdown = path.join(config.reports.dir, "report.md");
   }
+  if (config.reports.formats.includes("html")) {
+    paths.html = path.join(config.reports.dir, "report.html");
+  }
   return paths;
 }

package/src/report/html.js

@@ -0,0 +1,257 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const ESCAPE_MAP = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ESCAPE_MAP[character]);
+}
+
+function percent(value) {
+  return value === null || value === undefined ? "N/A" : value.toFixed(2) + "%";
+}
+
+function statusLabel(status) {
+  if (status === "pass") return "通过";
+  if (status === "fail") return "未通过";
+  return "运行失败";
+}
+
+async function readSourceLines(root, relativePath) {
+  try {
+    const text = await readFile(path.resolve(root, relativePath), "utf8");
+    return text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  } catch (error) {
+    return ["// 无法读取源码：" + error.message];
+  }
+}
+
+function metricCard(label, value) {
+  if (!value || !value.applicable) {
+    return '<div class="metric"><span>' + escapeHtml(label) + '</span><strong>N/A</strong></div>';
+  }
+  const klass = value.passed ? "good" : "bad";
+  return (
+    '<div class="metric ' +
+    klass +
+    '"><span>' +
+    escapeHtml(label) +
+    "</span><strong>" +
+    percent(value.percent) +
+    "</strong><small>" +
+    value.covered +
+    "/" +
+    value.total +
+    " · 目标 " +
+    value.threshold +
+    "%</small></div>"
+  );
+}
+
+function lineHtml(number, line, hits) {
+  const hasHit = hits && Object.prototype.hasOwnProperty.call(hits, String(number));
+  const count = hasHit ? Number(hits[String(number)]) : null;
+  const state = !hasHit ? "neutral" : count > 0 ? "covered" : "uncovered";
+  const hitLabel = hasHit ? (count > 0 ? String(count) : "0") : "";
+  return (
+    '<div class="line ' +
+    state +
+    '"><span class="ln">' +
+    number +
+    '</span><span class="hit" title="命中次数">' +
+    escapeHtml(hitLabel) +
+    '</span><span class="code">' +
+    (line ? escapeHtml(line) : "&nbsp;") +
+    "</span></div>"
+  );
+}
+
+const CSS = [
+  ":root{color-scheme:light;--ink:#17202a;--muted:#65707c;--line:#e5e9ed;--bg:#f4f6f8;--panel:#fff;--green:#d9f7e2;--green-strong:#198754;--red:#e5484d;--neutral:#f5f6f7;--accent:#1f6feb}",
+  "*{box-sizing:border-box}",
+  "html,body{margin:0;height:100%}",
+  "body{font-family:ui-sans-serif,-apple-system,BlinkMacSystemFont,'Segoe UI','Microsoft YaHei',sans-serif;background:var(--bg);color:var(--ink)}",
+  ".app{display:flex;height:100vh;overflow:hidden}",
+  ".sidebar{width:340px;min-width:280px;border-right:1px solid var(--line);background:#fbfcfd;display:flex;flex-direction:column}",
+  ".brand{padding:18px 18px 12px;border-bottom:1px solid var(--line)}",
+  ".brand h1{font-size:17px;margin:0 0 6px;letter-spacing:.2px}",
+  ".brand p{margin:0;color:var(--muted);font-size:12px;line-height:1.5}",
+  ".summary{padding:12px 18px;border-bottom:1px solid var(--line);font-size:12px;color:var(--muted);display:flex;flex-wrap:wrap;gap:8px}",
+  ".pill{padding:3px 8px;border-radius:99px;background:#eef1f4;color:#46505b}",
+  ".pill.good{background:var(--green);color:#116a3e}.pill.bad{background:#ffe3e4;color:#a51d22}",
+  ".search{padding:12px 14px 8px}",
+  ".search input{width:100%;padding:8px 10px;border:1px solid var(--line);border-radius:8px;background:#fff;font:inherit;outline:none}",
+  ".search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px #1f6feb1a}",
+  ".file-list{overflow:auto;padding:4px 10px 24px;flex:1}",
+  ".scope-title{font-size:11px;text-transform:uppercase;letter-spacing:.8px;color:#8a94a0;padding:14px 8px 7px;display:flex;justify-content:space-between;gap:8px}",
+  ".scope-title span{font-weight:600;color:#56616d}",
+  ".file-link{display:flex;align-items:center;gap:8px;padding:8px 9px;border-radius:8px;color:var(--ink);text-decoration:none;font-size:13px;line-height:1.3}",
+  ".file-link:hover{background:#eef3f8}",
+  ".file-link.active{background:#e7f0ff;box-shadow:inset 2px 0 var(--accent)}",
+  ".file-link .name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;direction:rtl;text-align:left}",
+  ".file-link .pct{font-variant-numeric:tabular-nums;font-size:11px;color:var(--muted)}",
+  ".file-link .pct.ok{color:var(--green-strong)}.file-link .pct.bad{color:var(--red)}",
+  ".empty{padding:14px;font-size:13px;color:var(--muted);line-height:1.6}",
+  ".main{flex:1;min-width:0;display:flex;flex-direction:column;overflow:hidden}",
+  ".topbar{padding:16px 22px;border-bottom:1px solid var(--line);background:var(--panel);display:flex;align-items:center;gap:16px;flex-wrap:wrap}",
+  ".topbar h2{font-size:15px;margin:0;flex:1;min-width:200px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
+  ".changed-badge{font-size:11px;background:#fff3cd;color:#7a5b00;border-radius:99px;padding:3px 8px}",
+  ".metrics{display:flex;gap:8px;flex-wrap:wrap}",
+  ".metric{border:1px solid var(--line);background:#fff;border-radius:8px;padding:6px 10px;min-width:104px;display:flex;flex-direction:column;gap:1px}",
+  ".metric span{font-size:10px;color:var(--muted)}.metric strong{font-size:13px}.metric small{font-size:10px;color:var(--muted)}",
+  ".metric.good strong{color:var(--green-strong)}.metric.bad strong{color:var(--red)}",
+  ".content{overflow:auto;flex:1;padding:22px}",
+  ".file-view{max-width:1500px;margin:0 auto}",
+  ".file-meta{display:flex;gap:12px;flex-wrap:wrap;align-items:center;margin-bottom:12px;color:var(--muted);font-size:12px}",
+  ".file-meta .path{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;color:var(--ink);font-size:13px}",
+  ".legend{display:flex;gap:14px;font-size:11px;color:var(--muted);margin-bottom:12px;flex-wrap:wrap}",
+  ".legend i{display:inline-block;width:18px;height:10px;border:1px solid var(--line);border-radius:2px;vertical-align:-1px;margin-right:4px}",
+  ".legend .covered-bg{background:var(--green)}.legend .uncovered-bg{background:#fff}.legend .neutral-bg{background:var(--neutral)}",
+  ".code-pane{background:#fff;border:1px solid var(--line);border-radius:10px;overflow:auto;font-family:ui-monospace,SFMono-Regular,Consolas,'Liberation Mono',monospace;font-size:12.5px;line-height:1.55;padding:6px 0}",
+  ".line{display:flex;min-width:max-content;white-space:pre;border-bottom:1px solid #f1f3f5}",
+  ".line.covered{background:var(--green)}.line.uncovered{background:#fff;box-shadow:inset 3px 0 var(--red)}.line.neutral{background:var(--neutral);color:#8e99a4}",
+  ".ln{width:60px;flex:0 0 60px;text-align:right;padding-right:12px;color:#8a94a0;user-select:none;border-right:1px solid #0000000d}",
+  ".hit{width:42px;flex:0 0 42px;text-align:right;padding-right:12px;color:#8a94a0;user-select:none;border-right:1px solid #0000000d}",
+  ".line.covered .hit{color:var(--green-strong)}.line.uncovered .hit{color:var(--red)}",
+  ".code-text{padding:0 14px 0 10px;padding:0 14px 0 10px}",
+  ".line .code{padding:0 14px 0 10px}",
+  ".source-note{font-size:12px;color:var(--muted);margin:8px 0 12px}",
+  "@media(max-width:900px){.app{display:block;height:auto}.sidebar{width:auto;height:46vh}.main{height:54vh}.content{padding:12px}}",
+  ""
+].join("\n");
+
+const JS = [
+  "(function(){",
+  "  var links = Array.prototype.slice.call(document.querySelectorAll('.file-link'));",
+  "  var views = Array.prototype.slice.call(document.querySelectorAll('.file-view'));",
+  "  function show(id) {",
+  "    views.forEach(function(view){ view.hidden = view.id !== id; });",
+  "    links.forEach(function(link){ link.classList.toggle('active', link.getAttribute('data-file') === id); });",
+  "    if (id) { try { history.replaceState(null, '', '#' + id); } catch (_) {} }",
+  "  }",
+  "  links.forEach(function(link){",
+  "    link.addEventListener('click', function(event){ event.preventDefault(); show(link.getAttribute('data-file')); });",
+  "  });",
+  "  var search = document.getElementById('fileSearch');",
+  "  if (search) search.addEventListener('input', function(){",
+  "    var term = search.value.trim().toLowerCase();",
+  "    links.forEach(function(link){ link.style.display = !term || link.textContent.toLowerCase().indexOf(term) !== -1 ? '' : 'none'; });",
+  "  });",
+  "  var initial = location.hash ? location.hash.slice(1) : (links[0] && links[0].getAttribute('data-file'));",
+  "  if (initial) show(initial);",
+  "})();"
+].join("\n");
+
+function sidebarScope(scope, files) {
+  const title = escapeHtml(scope.label) + " · " + escapeHtml(scope.name);
+  const metrics = scope.metrics && scope.metrics.lines
+    ? (scope.metrics.lines.applicable ? percent(scope.metrics.lines.percent) : "N/A")
+    : "N/A";
+  const threshold = scope.metrics?.lines?.threshold ?? 100;
+  const rows = files.map((file) => {
+    const line = file.metrics && file.metrics.lines;
+    const value = line && line.percent !== null ? percent(line.percent) : "N/A";
+    const ok = line && line.percent !== null && line.percent >= threshold ? "ok" : "bad";
+    return (
+      '<a class="file-link" data-file="' + file.id + '" href="#' + file.id + '">' +
+      '<span class="name" title="' + escapeHtml(file.path) + '">' + escapeHtml(file.path) + "</span>" +
+      '<span class="pct ' + ok + '">' + value + "</span></a>"
+    );
+  });
+  return (
+    '<div class="scope-title"><span>' + title + "</span><span>" + metrics + "</span></div>" +
+    (rows.length > 0 ? rows.join("") : '<div class="empty">本次变更未涉及该 scope。</div>')
+  );
+}
+
+function fileView(scope, file, index) {
+  const source = file.source || [];
+  const lines = [];
+  for (let lineNumber = 1; lineNumber <= source.length; lineNumber += 1) {
+    lines.push(lineHtml(lineNumber, source[lineNumber - 1], file.lineHits));
+  }
+  const lineMetric = file.metrics && file.metrics.lines;
+  const statLine = lineMetric ? percent(lineMetric.percent) + " (" + lineMetric.covered + "/" + lineMetric.total + ")" : "N/A";
+  const hidden = index === 0 ? "" : " hidden";
+  return (
+    '<section class="file-view" id="' + file.id + '"' + hidden + ">" +
+    '<div class="file-meta"><span class="path">' + escapeHtml(file.path) + "</span>" +
+    "<span>行覆盖 " + statLine + "</span>" +
+    "<span>" + (file.changed ? "本次 Git 变更文件" : "") + "</span></div>" +
+    '<div class="legend"><span><i class="covered-bg"></i>已覆盖</span><span><i class="uncovered-bg"></i>未覆盖</span><span><i class="neutral-bg"></i>非可执行代码</span></div>' +
+    '<div class="code-pane">' + lines.join("") + "</div>" +
+    "</section>"
+  );
+}
+
+/**
+ * @param {any} report
+ * @param {{ root: string }} options
+ */
+export async function renderHtmlReport(report, options) {
+  const root = options.root;
+  const scopeViews = [];
+  const sidebar = [];
+  let fileIndex = 0;
+  for (let scopeIndex = 0; scopeIndex < report.scopes.length; scopeIndex += 1) {
+    const scope = report.scopes[scopeIndex];
+    const files = [];
+    for (const file of scope.files || []) {
+      const source = await readSourceLines(root, file.path);
+      files.push({
+        ...file,
+        id: "file-" + scopeIndex + "-" + fileIndex,
+        source,
+        changed: Boolean(report.changed && report.changed.enabled)
+      });
+      fileIndex += 1;
+    }
+    sidebar.push(sidebarScope(scope, files));
+    scopeViews.push(files);
+  }
+
+  const views = [];
+  for (let scopeIndex = 0; scopeIndex < report.scopes.length; scopeIndex += 1) {
+    for (const file of scopeViews[scopeIndex]) views.push(fileView(report.scopes[scopeIndex], file, views.length));
+  }
+
+  const changed = report.changed && report.changed.enabled
+    ? '<span class="changed-badge">只显示 Git 变更文件 · base ' + escapeHtml(report.changed.base) + "</span>"
+    : "";
+  const status = statusLabel(report.status);
+  const statusClass = report.status === "pass" ? "good" : "bad";
+  const summary = report.scopes.map((scope) => {
+    const lines = scope.metrics && scope.metrics.lines;
+    return metricCard(scope.label, lines);
+  }).join("");
+  const scopeCount = report.scopes.length;
+  const fileCount = report.scopes.reduce((sum, scope) => sum + (scope.files || []).length, 0);
+  const body = views.length > 0
+    ? views.join("")
+    : '<div class="file-view"><div class="empty">没有可展示的源码文件。请检查 sources.include 或本次 Git 变更。</div></div>';
+
+  return [
+    "<!doctype html>",
+    '<html lang="zh-CN"><head><meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width,initial-scale=1">',
+    "<title>CovGate 覆盖率报告</title>",
+    "<style>" + CSS + "</style></head><body>",
+    '<div class="app">',
+    '<aside class="sidebar"><div class="brand"><h1>CovGate 覆盖率</h1><p>' +
+      escapeHtml(report.generatedAt) + " · " + escapeHtml(report.mode === "check" ? "已有报告" : "本次运行") +
+      "</p></div>" +
+      '<div class="summary"><span class="pill ' + statusClass + '">' + status + "</span>" +
+      '<span class="pill">' + scopeCount + ' scopes</span><span class="pill">' + fileCount + ' files</span>' + changed + "</div>" +
+      '<div class="search"><input id="fileSearch" type="search" placeholder="搜索文件…" aria-label="搜索文件"></div>',
+    '<nav class="file-list">' + sidebar.join("") + "</nav></aside>",
+    '<main class="main"><header class="topbar"><h2>源码覆盖</h2><div class="metrics">' + summary + "</div></header>",
+    '<div class="content">' + body + "</div></main></div>",
+    "<script>" + JS + "</script></body></html>"
+  ].join("\n");
+}

package/src/report/index.js

@@ -1,15 +1,23 @@
 import { writeTextFile } from "../util.js";
 import { buildReport, plannedArtifactPaths } from "./build.js";
+import { renderHtmlReport } from "./html.js";
 import { renderMarkdownReport } from "./markdown.js";
 import { renderTextReport } from "./text.js";
 
-export { buildReport, plannedArtifactPaths, renderMarkdownReport, renderTextReport };
+export {
+  buildReport,
+  plannedArtifactPaths,
+  renderHtmlReport,
+  renderMarkdownReport,
+  renderTextReport
+};
 
 /**
  * @param {any} report
- * @param {{ json?: string, markdown?: string }} paths
+ * @param {{ json?: string, markdown?: string, html?: string }} paths
+ * @param {any} [config]
  */
-export async function writeReportArtifacts(report, paths) {
+export async function writeReportArtifacts(report, paths, config) {
   const errors = [];
   if (paths.json) {
     try {
@@ -25,5 +33,15 @@ export async function writeReportArtifacts(report, paths) {
       errors.push("无法写入 Markdown 报告 " + paths.markdown + ": " + error.message);
     }
   }
+  if (paths.html) {
+    try {
+      const html = await renderHtmlReport(report, {
+        root: config?.root || process.cwd()
+      });
+      await writeTextFile(paths.html, html);
+    } catch (error) {
+      errors.push("无法写入 HTML 报告 " + paths.html + ": " + error.message);
+    }
+  }
   return errors;
 }

package/src/report/markdown.js

@@ -57,7 +57,7 @@ function scopeTableRow(scope) {
         (value.passed ? "✓" : "✗")
     );
   }
-  cells.push(scope.passed ? "✓ 通过" : "✗ 未通过");
+  cells.push(scope.skipped ? "— 未涉及变更" : scope.passed ? "✓ 通过" : "✗ 未通过");
   return "| " + cells.join(" | ") + " |";
 }
 
@@ -111,6 +111,8 @@ export function renderMarkdownReport(report) {
       report.summary.scopes +
       " 个，通过 " +
       report.summary.passedScopes +
+      " 个；跳过 " +
+      report.summary.skippedScopes.length +
       " 个；豁免 " +
       report.summary.waivers +
       " 条；配置排除 " +

package/src/report/text.js

@@ -54,7 +54,7 @@ export function renderTextReport(report, options = {}) {
   if (report.issues.length > 0) lines.push("");
 
   for (const scope of report.scopes) {
-    const symbol = scope.passed ? symbols.pass : symbols.fail;
+    const symbol = scope.skipped ? "○" : scope.passed ? symbols.pass : symbols.fail;
     lines.push(
       symbol +
         " " +
@@ -62,7 +62,7 @@ export function renderTextReport(report, options = {}) {
         " " +
         dim("[" + scope.name + "/" + scope.profile + "]") +
         " " +
-        (scope.passed ? green("通过") : red("未通过"))
+        (scope.skipped ? dim("未涉及本次变更") : scope.passed ? green("通过") : red("未通过"))
     );
 
     const metricParts = [];
@@ -260,6 +260,9 @@ export function renderTextReport(report, options = {}) {
   if (report.artifacts.markdown) {
     lines.push(dim("Markdown 报告: " + report.artifacts.markdown));
   }
+  if (report.artifacts.html) {
+    lines.push(dim("HTML 报告: " + report.artifacts.html));
+  }
   if (report.status !== "pass" && report.summary.failedScopes.length > 0) {
     lines.push(dim("失败 scope: " + report.summary.failedScopes.join(", ")));
   }

package/src/scope.js

@@ -64,10 +64,11 @@ function findOverlaps(ranges) {
  *   root: string,
  *   coverage: { format: string, files: Map<string, any> },
  *   waiverPolicy: any,
+ *   changedKeys?: Set<string> | null,
  *   now?: Date
  * }} options
  */
-export async function evaluateScope({ scope, root, coverage, waiverPolicy, now = new Date() }) {
+export async function evaluateScope({ scope, root, coverage, waiverPolicy, changedKeys = null, now = new Date() }) {
   /** @type {Array<any>} */
   const issues = [];
   /** @type {Array<any>} */
@@ -161,6 +162,33 @@ export async function evaluateScope({ scope, root, coverage, waiverPolicy, now =
     });
   }
 
+  const universeKeys = new Set(expected.keys());
+  if (changedKeys) {
+    for (const key of [...expected.keys()]) {
+      if (!changedKeys.has(key)) expected.delete(key);
+    }
+    if (universeKeys.size > 0 && expected.size === 0) {
+      return {
+        name: scope.name,
+        label: scope.label,
+        profile: scope.profile,
+        thresholds: scope.thresholds,
+        format: coverage.format,
+        files: [],
+        expectedSourceCount: 0,
+        reportedFileCount: coverage.files.size,
+        missingSources: [],
+        extras: [],
+        waivers: [],
+        exclusions,
+        issues,
+        warnings,
+        skipped: true,
+        changedOnly: true
+      };
+    }
+  }
+
   // 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.
@@ -391,7 +419,7 @@ export async function evaluateScope({ scope, root, coverage, waiverPolicy, now =
   // 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;
+    if (universeKeys.has(key) || excludedKeys.has(key) || fileIgnoreKeys.has(key)) continue;
     extras.push(file.relPath);
   }
   if (extras.length > 0) {
@@ -435,6 +463,8 @@ export async function evaluateScope({ scope, root, coverage, waiverPolicy, now =
     waivers,
     exclusions,
     issues,
-    warnings
+    warnings,
+    skipped: false,
+    changedOnly: Boolean(changedKeys)
   };
 }

package/src/setup/config.js

@@ -108,7 +108,7 @@ export async function buildStarterConfig({
     },
     reports: {
       dir: ".covgate",
-      formats: ["json", "markdown"]
+      formats: ["json", "markdown", "html"]
     }
   };
 }

package/templates/covgate.config.json

@@ -92,7 +92,8 @@
     "dir": ".covgate",
     "formats": [
       "json",
-      "markdown"
+      "markdown",
+      "html"
     ]
   }
 }