covgate 0.2.0 → 0.2.2

package/README.md

@@ -46,30 +46,29 @@ covgate run
 
 ## 安装
 
-### 在线安装（Gitee）
+### 从 npm registry 安装（推荐）
+
+包已发布到 npm：[covgate](https://www.npmjs.com/package/covgate)，当前 latest 为 **0.2.2**。
 
 ```bash
-npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
+npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-也可以使用 SSH：
+> npm 上可能还能看到 `0.0.0-stage`，它是暂存发布占位版本，不会作为 `latest` 被安装，可以忽略。
 
-```bash
-npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
-```
+### 从 Gitee 安装（源码 / 镜像）
 
-### 从 npm registry 安装
+```bash
+# HTTPS
+npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
 
-包名是 `covgate`。发布到 npm 后：
+# 或 SSH
+npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
 
-```bash
-npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-发布需要 npm 登录：`npm login && npm publish`。
-
 ### 本地目录安装
 
 ```bash
@@ -96,8 +95,11 @@ setup 会：
 - 检测 npm/pnpm/yarn/bun 和已有测试框架；
 - **没有测试框架时询问是否安装 Vitest + @vitest/coverage-v8**，选择是则自动安装；
 - 写入 `coverage:gate`、`test:coverage` 脚本和 `covgate.config.json` 起始配置；
+- Electron 项目自动生成 `client`（`src/**`，100%）和 `server`（`desktop/**`，95%）两个 scope；
 - 生成 `AGENTS.md`、Agent 门禁脚本、GitHub Actions（如存在 `.github/`）和 `.gitignore` 条目。
 
+**CovGate 不生成测试，也不补测试。** 行为变更的测试必须由项目自己补；没有测试时 `test:coverage` 会直接失败，不会生成空覆盖率来蒙混过关。
+
 `postinstall` 也会尝试同样的流程，但 **npm 11.19+ 默认不执行依赖安装脚本**。如果安装时没有弹出询问，直接运行 `npx covgate setup` 即可；详细说明见 [安装与自动配置](docs/setup.md)。
 
 ### 在 CovGate 仓库中开发
@@ -183,7 +185,7 @@ node bin/covgate.js --help
   },
   "reports": {
     "dir": ".covgate",
-    "formats": ["json", "markdown"]
+    "formats": ["json", "markdown", "html"]
   }
 }
 ```
@@ -246,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` | 控制彩色输出。 |
@@ -264,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
@@ -326,7 +349,7 @@ CI 只需要判断退出码是否为 0。
 ### reports
 
 - `dir`：输出目录，默认 `.covgate`。
-- `formats`：`json`、`markdown`。
+- `formats`：`json`、`markdown`、`html`。
 
 ## 写豁免：不可达代码的唯一方式
 
@@ -433,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.0
+CovGate · 覆盖率门禁 v0.2.2
 模式 执行测试并检查 · 配置 covgate.config.json · 用时 12.4s
 
 ✗ 客户端 [client/client] 未通过
@@ -449,6 +483,7 @@ CovGate · 覆盖率门禁 v0.2.0
 
 结果: 未通过
 JSON 报告: .covgate/report.json
+HTML 报告: .covgate/report.html
 ```
 
 建议把 `.covgate/` 加入 `.gitignore`。报告是本次运行的产物，不是源码。

package/docs/ai-workflow.md

@@ -30,6 +30,7 @@ npx --no-install covgate setup
 - 任何代码修改完成后，必须运行 `npx --no-install covgate run --json`；退出码 0 才能说完成。
 - 退出码 1：补测试或修实现；2：修配置；3：修测试命令/报告。不要绕过。
 - 禁止降低 covgate.config.json 中的门槛、扩大 exclude、删除豁免检查来让门禁通过；这些改动必须由人类评审。
+- **行为变更必须新增或更新覆盖该行为的真实测试**；门禁失败不能作为完成理由，也不能用 `--passWithNoTests`、空报告或 ignore 绕过。
 - 禁止 istanbul ignore / c8 ignore / v8 ignore / node:coverage ignore。
 - 确实不可达的代码使用 covgate-ignore-next-line / start/end / file，写具体原因、owner 和 expires。
 - 新增或修改的源码必须出现在覆盖率报告中；sources.include 是范围事实来源。

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

@@ -2,36 +2,27 @@
 
 ## 在线安装
 
-### Gitee（当前可用）
-
-```bash
-# HTTPS（公开仓库）
-npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
-
-# 或 SSH
-npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
-```
-
-安装完成后运行一次：
+### npm registry（推荐）
 
 ```bash
+npm install --save-dev covgate
 npx --no-install covgate setup
 ```
 
-### npm registry
+包页面：[covgate](https://www.npmjs.com/package/covgate)。当前 latest 是 **0.2.2**。
 
-包名是 `covgate`。发布到 npm 后可以直接：
+> `0.0.0-stage` 是 npm 暂存发布产生的占位版本，不会被 `npm install covgate` 选中，可以忽略。
+
+### Gitee（源码 / 镜像）
 
 ```bash
-npm install --save-dev covgate
-npx --no-install covgate setup
-```
+# HTTPS（公开仓库）
+npm install --save-dev git+https://gitee.com/wxzzhj/covgate.git
 
-发布命令（需要 npm 登录）：
+# 或 SSH
+npm install --save-dev git+ssh://git@gitee.com/wxzzhj/covgate.git
 
-```bash
-npm login
-npm publish
+npx --no-install covgate setup
 ```
 
 ### 从本地目录安装
@@ -47,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.0 (postinstall: node bin/covgate-postinstall.js)
+npm warn install-scripts   covgate@0.2.2 (postinstall: node bin/covgate-postinstall.js)
 ```
 
 因此：
@@ -70,7 +61,7 @@ npm warn install-scripts   covgate@0.2.0 (postinstall: node bin/covgate-postinst
 3. 添加 `npm scripts`：
    - `coverage:gate`：`covgate run`
    - `test:coverage`：Vitest/Jest 的 JSON + LCOV 覆盖率命令
-4. 生成 `covgate.config.json`（单 scope 起始配置；已存在则不覆盖）：
+4. 生成 `covgate.config.json`（普通项目单 scope；Electron 自动生成 client + server；已存在则不覆盖）：
 
    ```json
    {
@@ -93,6 +84,8 @@ npm warn install-scripts   covgate@0.2.0 (postinstall: node bin/covgate-postinst
    - 若已有 `CLAUDE.md`、`.cursor`、`.github/copilot-instructions.md`，同步写入对应说明。
 6. 输出下一步命令。
 
+> **CovGate 不生成测试，也不补测试。** setup 只配置测试框架和门禁；本次行为变更的测试必须由项目自己补。没有测试时 `test:coverage` 会直接失败（已移除 `--passWithNoTests`），不会产生可蒙混过关的空覆盖率。
+
 ## setup 选项
 
 | 选项 | 作用 |
@@ -122,21 +115,30 @@ npx covgate setup --no-install --no-config
 npx covgate setup --profile client --source "web/src/**/*.{ts,tsx}"
 ```
 
-## 生成的是单 scope
+## 生成的 scope
 
-为了不猜测复杂仓库结构，setup 只生成一个 scope：
+普通项目只生成一个 scope：
 
-- 项目有 `src/` 或 `app.js` 时自动选源码；
-- 有 `index.html`、React/Vue/Svelte 等依赖时选 `client`；
+- 有源码目录时自动选择源码（优先 `src/`，其次 `app.js`、`app/`、`lib/`）；
+- 有根目录或 `src/index.html`、React/Vue/Svelte 等依赖、Electron 时选 `client`；
 - 否则选 `server`。
 
-全栈项目需要手工在 `covgate.config.json` 增加第二个 scope，或对两个子项目分别运行 setup。生成配置后请先运行：
+Electron 项目会生成两个 scope：
+
+- `client`（profile=client）：`src/**` 等渲染进程源码，目标 100%；
+- `server`（profile=server）：`desktop/**` 主进程/预加载源码，目标 95%。
+
+两个 scope 共用同一个测试命令和覆盖率报告；CovGate 会按各自源码范围计算覆盖率。若使用 `--profile` 或 `--source` 手工覆盖，则只生成一个 scope。
+
+生成配置后请先运行：
 
 ```bash
 npx --no-install covgate validate
 npx --no-install covgate run
 ```
 
+门禁失败时，正确做法是让项目补覆盖该行为的真实测试；CovGate 不会替项目补测试，也不会接受空报告、`--passWithNoTests` 或降低门槛。
+
 ## AI 代理如何真正做到“自动跑”
 
 生成的文件不等于自动触发。需要把它接到代理生命周期：
@@ -160,4 +162,4 @@ npx --no-install covgate run
 - **没有弹出测试框架询问**：npm 11 默认阻止 install scripts。运行 `npx covgate setup`。
 - **没有生成 CovGate 配置**：可能没有识别到源码目录或覆盖率命令。用 `--source`、`--test-command` 指定，或先安装框架。
 - **Vitest 安装超时**：setup 对安装命令有 180 秒限制。检查网络/registry，手动安装 `vitest @vitest/coverage-v8` 后重跑 setup。
-- **多 scope 项目**：setup 只生成一个；手工编辑或分目录 setup。
+- **多 scope 项目**：setup 只生成一个；手工编辑或分目录 setup。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "covgate",
-  "version": "0.2.0",
+  "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