@davideasden/pi-undo 0.2.26 → 0.2.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,21 +1,36 @@
1
1
  # 原生目录扫描与普通文件恢复性能验证
2
2
 
3
- 这批优化基于 `d7d80230`,保留 undo 的五个拓扑检查点,降低完整目录扫描成本,并扩大已有父目录中的普通文件原生恢复范围。
3
+ 本轮实现目录项缓存与 scoped restore 的可见路径检查,保留恢复前后的拓扑校验。目录扫描仍会逐个打开、核验工作区内的目录;缓存减少 `readdir`,没有把整次检查变成只访问 changedPaths 的增量操作。
4
4
 
5
5
  ## 实现与边界
6
6
 
7
- - `scan-directories-v1` 在 macOS/Linux 上通过 `openat(O_DIRECTORY | O_NOFOLLOW)` 逐级打开目录,以目录流识别 Git 标记候选。扫描 ignored 目录,不进入名称恰为 `.git` 的元数据目录,不跟随符号链接;标记大小写、损坏仓库、失效 worktree 指针、Git index 与 submodule 仍由现有 TypeScript/Git 逻辑解释。
8
- - 每次重新扫描。上次目录数量仅选择执行器:小于 64 个目录时使用 TypeScript 完整遍历;增长后可重新进入原生扫描。没有缓存拓扑结果,也没有省略任何检查点。
9
- - 目录句柄、父目录绑定与扫描前后目录时间戳必须一致。扫描时并发增删目录项会使原生扫描失败,防止静默接受不完整结果;它不提供跨整个工作区的原子快照。能力确认后的路径错误向上传递。超过 128 层时,helper 明确返回 `depth_limit`,丢弃部分结果,由 TypeScript 从根重扫。
10
- - 原生扫描使用操作剩余预算,并遵守 `PI_UNDO_OPERATION_TIMEOUT_MS`(默认 300 秒)。能力探测只在私有目录运行,缺失能力时回退;取消、超时及无法确认子进程终止均保留现有错误处理契约。探测取消不会永久污染能力缓存。
11
- - `restore-files-v2` 支持普通文件覆盖、创建、删除的混合计划,以及子目录中的文件删除。父目录必须已经存在。读取、校验、no-clobber 安装及隔离均绑定同一组父目录句柄;最多保留 128 个非根父目录句柄。目录创建/删除、类型替换、过多父目录与不支持的平台继续使用 TypeScript。
12
- - durable pack 格式与恢复协议保持不变。仍在修改前发布并持久化 pack,逐项校验内容和 mode,保留同 inode 的 ownership artifacts。失败时由现有 packed recovery 回滚;外来冲突文件不会被当成本次产物删除。
7
+ - `scan-directories-v2` 在 macOS/Linux 上缓存每个目录的 `dev/ino/mtime/ctime`、Git 标记和直接子目录。每次检查仍核验全部目录的身份与时间戳,匹配时才复用目录项。检查点之间发生变化的目录重新枚举;扫描期间发生变化则显式失败,不接受部分结果。
8
+ - 缓存把 racy 标记固化到记录中,以开始枚举目录前的观察时刻计算两秒窗口。长子树扫描或之后的时间流逝不会让旧的 racy 记录自动变成可信记录。时间戳纳秒部分为零、无效或处于未来时采取保守重扫。
9
+ - 扫描继续进入 ignored 目录,以发现其中的嵌套仓库;不进入名称恰为 `.git` 的元数据目录,不跟随 symlink。目录句柄、父子绑定和工作区身份检查保留。超过 128 层时丢弃原生部分结果,由 TypeScript 从根重扫。
10
+ - v2 cache 绑定工作区路径与身份,结构解析失败或不匹配时不复用。它位于工作区外的私有临时目录,位置检查会解析 `TMPDIR` 的符号链接;无法安全放置请求时使用 TypeScript。cache 创建失败时使用本次请求目录,cache 写入失败不使成功扫描失败。正常进程退出时尽力清理,强制终止仍可能留下系统临时文件。
11
+ - 能力探测一次取得 capability 集合;旧 `scan-directories-v1` helper 继续完整扫描,缺少 helper 时使用 TypeScript。扫描仍受操作剩余时间和 `PI_UNDO_OPERATION_TIMEOUT_MS` 限制,取消或未确认退出保持原有处理契约。
12
+ - `listVisibleLeafPaths` 支持 `includePaths`。带 scope 的 complete restore 只枚举 scope 内的可见叶子;scope 外新增文件保留,scope 内新增可见路径仍会在修改前阻止恢复。未指定 scope 的完整恢复继续枚举整个工作区。嵌套仓库边界、内容、mode、symlink、mutation journal 和 quarantine 检查保留。
13
+ - 本轮没有引入 FSEvents/inotify 变更索引,也没有消除 settled 阶段完整 baseline 的枚举成本。因此,目录很多或 baseline 捕获很慢的工作区仍可能有明显等待,不能据此保证用户的 50GB 项目达到秒级响应。
13
14
 
14
- ## 实测结果
15
+ 缓存信任应用进程创建的私有文件及操作系统提供的目录元数据,不提供跨整个工作区的原子快照,也不提供抵抗同用户篡改 cache 的完整性保证。
15
16
 
16
- 环境为本机 macOS arm64、Node 23.11.1、真实 Pi 0.86.1 SDK 与离线 faux provider。每个场景执行三次 undo,中间执行 redo 并等待后台恢复/持久化清理结束;校验文件内容、撤回/重做历史状态和扫描次数。表内为中位数,单位毫秒。基线与优化版本在同一机器先后执行,未施加墙钟性能断言。
17
+ ## 本轮前后对比
17
18
 
18
- | 场景 | 优化前 | 优化后 | 耗时降低 |
19
+ 环境:本机 macOS arm64、Node 23.11.1、Pi 0.86.1 SDK、离线 faux provider。基线为本轮改动前的 `bbe5c3f8`;基线和最终实现分别在隔离 worktree 中顺序运行相同用例,均使用原生 helper。每组执行三次 undo,中间 redo 并等待后台持久化清理,校验文件内容、历史状态和扫描次数。
20
+
21
+ | 场景 | 本轮改动前 | 本轮改动后 | 耗时降低 |
22
+ | --- | ---: | ---: | ---: |
23
+ | 10,000 个依赖包,修改 1 文件 | 2,792 ms | 2,504 ms | 10.3% |
24
+
25
+ 基线三次耗时为 `[2970, 2792, 2763]` ms,最终实现为 `[2497, 2504, 2529]` ms;两组扫描次数都为 `[5, 5, 5]`。上述百分比只比较本轮前后,没有把更早版本的收益算入本轮。强制 TypeScript 回退也通过同一大型工作区用例,扫描次数为 `[6, 6, 6]`;额外一次来自无法复用原生 durable source 时重新捕获安全快照。
26
+
27
+ 此前开发中一次 v2 采样为 `[2443, 2423, 2419]` ms;它与最终对比属于不同批次,不合并计算。三次本机采样只能说明这一基准的表现,没有墙钟性能断言,也没有对用户实际 50GB 项目、其他平台或其他磁盘作出速度保证。
28
+
29
+ ## 上一轮原生优化的历史数据
30
+
31
+ 下表保留上一轮以 `d7d80230` 为起点的结果,便于追踪原生扫描及普通文件恢复的收益;这些数据不是本轮缓存改动的前后对比。单位为毫秒。
32
+
33
+ | 场景 | 上一轮优化前 | 上一轮优化后 | 耗时降低 |
19
34
  | --- | ---: | ---: | ---: |
20
35
  | 无依赖目录,修改 1 文件 | 146 | 148 | 约持平 |
21
36
  | 3,000 包,修改 1 文件 | 1,976 | 924 | 53% |
@@ -25,15 +40,13 @@
25
40
  | 100 文件在已有子目录新增后撤销 | 517 | 180 | 65% |
26
41
  | 50 文件覆盖、50 文件新增后混合撤销 | 711 | 186 | 74% |
27
42
 
28
- 分阶段计时中,3,000 包场景五次扫描合计从 1,759 ms 降至 716 ms;10,000 包从 5,470 ms 降至 2,398 ms。全部测量仍为五次扫描。新增目录的撤销测试保留父目录中的 `keep.txt`,因此测量的是文件删除,不含目录删除。混合与子目录场景原先未进入 native,优化后三次均调用原生恢复一次。
43
+ 上一轮分阶段计时中,3,000 包的五次扫描合计从 1,759 ms 降至 716 ms;10,000 包从 5,470 ms 降至 2,398 ms。另一批四组大型工作区测量覆盖 3,000/10,000 包 × 1/100 文件,中位数依次为 878、923、2,582、2,673 ms;这些独立批次不混算。
29
44
 
30
- 另一个既有大型工作区基准覆盖 3,000/10,000 包 × 1/100 文件,四组均通过内容、redo 和 `[5, 5, 5]` 扫描次数断言。该次单独运行的中位数依次为 878、923、2,582、2,673 ms;与分阶段诊断是不同批次,不把两批耗时混作同一组数据。
31
-
32
- 这些是三次采样的本机结果,主要证明已观察到的热路径得到改善。磁盘、目录结构、并发写入和机器负载会影响绝对耗时;没有从这些结果推断其他操作系统上的收益。
45
+ 已有 `restore-files-v2` 支持父目录已存在的普通文件覆盖、创建、删除和混合计划,最多保留 128 个非根父目录句柄。目录创建/删除、类型替换、过多父目录和不支持的平台继续使用 TypeScript。durable pack 格式与恢复协议未改变:修改前持久化 pack,逐项校验内容和 mode,失败由现有 recovery 回滚并保留外来冲突文件。历史新增文件测试保留父目录中的 `keep.txt`,不包含目录删除成本。
33
46
 
34
47
  ## 复现与验证
35
48
 
36
- 最终验证通过:默认原生路径 617 项、强制 TypeScript 回退 586 项、Rust 单测 8 项;TypeScript 类型检查、四组大型工作区基准及 npm 打包内容检查通过。跳过项为不适用平台/能力及按需基准,不计入通过数。
49
+ 本轮最终默认 Vitest:623 项通过、4 项按需基准跳过;Rust:12 项通过;原生相关 TypeScript:76 项通过。强制 TypeScript 回退完整测试和大型工作区用例、类型检查、npm 打包内容检查分别运行,不把跳过项算作通过。
37
50
 
38
51
  ```bash
39
52
  npm run build:native
@@ -42,11 +55,11 @@ npm run test:native
42
55
  npm test
43
56
  PI_UNDO_DISABLE_NATIVE=1 npm test
44
57
  npm run typecheck
45
- PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts
58
+ npm run pack:dry-run
59
+ PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts --testNamePattern='10000 个依赖包,修改 1 个文件'
60
+ PI_UNDO_DISABLE_NATIVE=1 PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts --testNamePattern='10000 个依赖包,修改 1 个文件'
46
61
  ```
47
62
 
48
- 上面的二进制复制路径用于本次 macOS arm64 环境;其他平台须使用对应构建产物。此批已更新仓库现有的 macOS arm64 二进制。Linux、其他架构和 Windows 的源码构建/运行不在本机验证范围内;缺少二进制或扩展能力时会回退,发布时仍需现有六平台构建流程提供对应产物。
49
-
50
- 补充测试覆盖:原生/TypeScript 拓扑一致性、ignored 嵌套仓库、大小写不同的 Git 标记、符号链接及目录删除/替换、深度回退、取消后重新探测、超时、混合计划回滚/前滚、外来文件冲突、旧 helper 门控,以及 128/129 个父目录的边界。
63
+ 二进制复制路径适用于本次 macOS arm64 环境;其他平台需要对应构建产物。本轮更新了仓库现有的 macOS arm64 二进制,未在本机验证 Linux、其他架构或 Windows 的构建与运行;发布仍依赖现有六平台构建流程。
51
64
 
52
- 独立审查运行器异常退出,正式审查结果未能落盘。已保留失败运行的状态与补丁证据,并人工核对日志中的具体意见;这不计为独立审查通过。已修复候选错误类型与扫描预算,补充句柄边界测试。旧 helper 在混合计划中仍可能先准备 pack 再回退,存在额外准备开销;兼容性分类与平台发布覆盖也仍需后续维护。
65
+ 测试覆盖目录缓存命中、深层 Git 标记新增、目录删除后的失效、racy 记录重扫、缓存身份与重复子项校验、TMPDIR 符号链接、v1/v2 协议、取消和超时,以及 scoped restore 保留范围外文件、拒绝范围内新增可见文件。独立只读审查已完成,审查提出的时间戳窗口、缓存清理和复用测试问题已修正;最终边界修正由主代理复核并重新验证。旧 helper 的混合计划仍可能先准备 pack 再回退,保留额外准备开销。
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davideasden/pi-undo",
3
- "version": "0.2.26",
3
+ "version": "0.2.27",
4
4
  "description": "Persistent workspace undo and redo for Pi",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -2,11 +2,10 @@ import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
2
2
  import { checkOperation, OperationError, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
3
3
 
4
4
  /** 在私有目录探测,防止旧 helper 把 --capabilities 当成工作区里的请求文件。 */
5
- export async function probeNativeCapability(
5
+ export async function probeNativeCapabilities(
6
6
  executable: string,
7
- capability: string,
8
7
  isolatedDirectory: string,
9
- ): Promise<boolean> {
8
+ ): Promise<ReadonlySet<string>> {
10
9
  const budget = operationProcessOptions(5_000);
11
10
  try {
12
11
  const result = await runSupervisedProcess({
@@ -23,12 +22,21 @@ export async function probeNativeCapability(
23
22
  throw new OperationError("operation_cancelled", "native 能力探测已被取消");
24
23
  }
25
24
  checkOperation();
26
- if (result.outcome !== "exit" || result.code !== 0) return false;
25
+ if (result.outcome !== "exit" || result.code !== 0) return new Set();
27
26
  const value: unknown = JSON.parse(result.stdout.toString("utf8"));
28
- return typeof value === "object" && value !== null && "ok" in value && value.ok === true &&
29
- "capabilities" in value && Array.isArray(value.capabilities) && value.capabilities.includes(capability);
27
+ if (typeof value !== "object" || value === null || !("ok" in value) || value.ok !== true ||
28
+ !("capabilities" in value) || !Array.isArray(value.capabilities)) return new Set();
29
+ return new Set(value.capabilities.filter((entry): entry is string => typeof entry === "string"));
30
30
  } catch (error) {
31
31
  rethrowOperationFailure(error);
32
- return false;
32
+ return new Set();
33
33
  }
34
34
  }
35
+
36
+ export async function probeNativeCapability(
37
+ executable: string,
38
+ capability: string,
39
+ isolatedDirectory: string,
40
+ ): Promise<boolean> {
41
+ return (await probeNativeCapabilities(executable, isolatedDirectory)).has(capability);
42
+ }
@@ -1,10 +1,10 @@
1
- import { constants } from "node:fs";
2
- import { access, mkdtemp, rm, writeFile } from "node:fs/promises";
1
+ import { constants, rmSync } from "node:fs";
2
+ import { access, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
3
3
  import { tmpdir } from "node:os";
4
- import { join } from "node:path";
4
+ import { isAbsolute, join, relative, resolve, sep } from "node:path";
5
5
 
6
6
  import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
7
- import { probeNativeCapability } from "./native-capabilities.ts";
7
+ import { probeNativeCapabilities } from "./native-capabilities.ts";
8
8
  import { nativeExecutable } from "./native-restore.ts";
9
9
  import { checkOperation, configuredTimeout, OperationError, operationProcessOptions } from "./operation-context.ts";
10
10
 
@@ -23,10 +23,30 @@ export interface NativeDirectoryScanPort {
23
23
  scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined>;
24
24
  }
25
25
 
26
- /** 只缓存 helper 能力;每个拓扑检查点均重新完整扫描工作区,包括 ignored 目录。 */
26
+ const nativeScanCacheDirectories = new Set<string>();
27
+ let nativeScanCacheCleanupRegistered = false;
28
+
29
+ function registerNativeScanCacheDirectory(directory: string): void {
30
+ nativeScanCacheDirectories.add(directory);
31
+ if (nativeScanCacheCleanupRegistered) return;
32
+ nativeScanCacheCleanupRegistered = true;
33
+ process.once("exit", () => {
34
+ for (const path of nativeScanCacheDirectories) {
35
+ try { rmSync(path, { recursive: true, force: true }); } catch { /* 退出阶段尽力清理 */ }
36
+ }
37
+ });
38
+ }
39
+
40
+ function isPathInside(root: string, candidate: string): boolean {
41
+ const child = relative(resolve(root), resolve(candidate));
42
+ return child === "" || (child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child));
43
+ }
44
+
45
+ /** 原生 helper 能力之外,目录快照只在逐目录元数据仍可证明时复用。 */
27
46
  export class NativeDirectoryScanner implements NativeDirectoryScanPort {
28
47
  private readonly executable: string | undefined;
29
- private capability: Promise<boolean> | undefined;
48
+ private capability: Promise<"v2" | "v1" | undefined> | undefined;
49
+ private cacheDirectory: Promise<string> | undefined;
30
50
 
31
51
  constructor(executable = nativeExecutable()) {
32
52
  this.executable = process.env.PI_UNDO_DISABLE_NATIVE === "1" || process.platform === "win32"
@@ -35,18 +55,29 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
35
55
 
36
56
  async scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined> {
37
57
  checkOperation();
38
- if (this.executable === undefined || (this.capability !== undefined && !await this.capability)) return undefined;
39
- const requestDirectory = await mkdtemp(join(tmpdir(), "pi-undo-native-scan-"));
58
+ if (this.executable === undefined ||
59
+ (this.capability !== undefined && await this.capability === undefined)) return undefined;
60
+ // TMPDIR 可能通过符号链接指向工作区;先核验真实路径,再创建任何请求或缓存。
61
+ const temporaryRoot = await realpath(tmpdir()).catch(() => undefined);
62
+ if (temporaryRoot === undefined || isPathInside(workspaceRoot, temporaryRoot)) return undefined;
63
+ const requestDirectory = await mkdtemp(join(temporaryRoot, "pi-undo-native-scan-"));
40
64
  try {
41
65
  this.capability ??= this.supportsScan(requestDirectory).catch((error) => {
42
66
  // 取消或未确认终止不能污染后续操作的能力缓存。
43
67
  this.capability = undefined;
44
68
  throw error;
45
69
  });
46
- if (!await this.capability) return undefined;
70
+ const version = await this.capability;
71
+ if (version === undefined) return undefined;
47
72
  const budget = operationProcessOptions(configuredTimeout("PI_UNDO_OPERATION_TIMEOUT_MS", 300_000));
48
73
  const requestPath = join(requestDirectory, "request.json");
49
- await writeFile(requestPath, JSON.stringify({ schemaVersion: 1, workspaceRoot }), { mode: 0o600, flag: "wx" });
74
+ const cachePath = version === "v2"
75
+ ? await this.directoryCachePath(workspaceRoot, temporaryRoot, requestDirectory) : undefined;
76
+ await writeFile(requestPath, JSON.stringify({
77
+ schemaVersion: version === "v2" ? 2 : 1,
78
+ workspaceRoot,
79
+ ...(cachePath === undefined ? {} : { cachePath }),
80
+ }), { mode: 0o600, flag: "wx" });
50
81
  const result = await runSupervisedProcess({
51
82
  command: this.executable,
52
83
  args: ["--scan-directories", requestPath],
@@ -70,13 +101,42 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
70
101
  }
71
102
  }
72
103
 
73
- private async supportsScan(directory: string): Promise<boolean> {
104
+ private async supportsScan(directory: string): Promise<"v2" | "v1" | undefined> {
74
105
  try {
75
106
  await access(this.executable!, constants.X_OK);
76
107
  } catch {
77
- return false;
108
+ return undefined;
109
+ }
110
+ const capabilities = await probeNativeCapabilities(this.executable!, directory);
111
+ if (capabilities.has("scan-directories-v2")) return "v2";
112
+ return capabilities.has("scan-directories-v1") ? "v1" : undefined;
113
+ }
114
+
115
+ private async directoryCachePath(
116
+ workspaceRoot: string,
117
+ temporaryRoot: string,
118
+ requestDirectory: string,
119
+ ): Promise<string> {
120
+ try {
121
+ if (this.cacheDirectory === undefined) {
122
+ this.cacheDirectory = mkdtemp(join(temporaryRoot, "pi-undo-native-scan-cache-")).catch((error) => {
123
+ this.cacheDirectory = undefined;
124
+ throw error;
125
+ });
126
+ }
127
+ const directory = await this.cacheDirectory;
128
+ if (isPathInside(workspaceRoot, directory)) {
129
+ // 工作区切换后不再把该目录当成本实例可以删除的私有缓存。
130
+ nativeScanCacheDirectories.delete(directory);
131
+ this.cacheDirectory = undefined;
132
+ return join(requestDirectory, "directories.json");
133
+ }
134
+ registerNativeScanCacheDirectory(directory);
135
+ return join(directory, "directories.json");
136
+ } catch {
137
+ this.cacheDirectory = undefined;
138
+ return join(requestDirectory, "directories.json");
78
139
  }
79
- return probeNativeCapability(this.executable!, "scan-directories-v1", directory);
80
140
  }
81
141
  }
82
142
 
@@ -106,6 +106,7 @@ interface VisibleSubsetCheck {
106
106
  */
107
107
  readonly topologyValidated: boolean;
108
108
  readonly extraExclusions?: readonly string[];
109
+ readonly scopePaths?: readonly string[];
109
110
  readonly ownedPaths?: readonly (ReadonlyMap<string, OwnedPath> | undefined)[];
110
111
  }
111
112
 
@@ -819,7 +820,8 @@ export class RestoreEngine {
819
820
  options.mutationJournal,
820
821
  {
821
822
  topologyValidated: !compatibilityMode,
822
- ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [currentPaths, targetPaths]),
823
+ scopePaths: plan.scopePaths,
824
+ ownedPaths: [currentPaths, targetPaths],
823
825
  },
824
826
  );
825
827
  } catch (error) {
@@ -942,7 +944,8 @@ export class RestoreEngine {
942
944
  options.mutationJournal,
943
945
  {
944
946
  topologyValidated: true,
945
- ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
947
+ scopePaths: plan.scopePaths,
948
+ ownedPaths: [targetPaths],
946
949
  },
947
950
  );
948
951
  const verification = await this.verifyTarget(
@@ -1019,7 +1022,8 @@ export class RestoreEngine {
1019
1022
  ? []
1020
1023
  : [artifacts.source, ...(artifacts.target === null ? [] : [artifacts.target])];
1021
1024
  }),
1022
- ownedPaths: this.completeCoverageOwnedPaths(plan.scopePaths, [targetPaths]),
1025
+ scopePaths: plan.scopePaths,
1026
+ ownedPaths: [targetPaths],
1023
1027
  },
1024
1028
  );
1025
1029
  const totalPaths = plan.deletePaths.length + plan.writePaths.length;
@@ -1199,13 +1203,6 @@ export class RestoreEngine {
1199
1203
  return result;
1200
1204
  }
1201
1205
 
1202
- private completeCoverageOwnedPaths(
1203
- scopePaths: readonly string[] | undefined,
1204
- ownedPaths: readonly ReadonlyMap<string, OwnedPath>[],
1205
- ): readonly ReadonlyMap<string, OwnedPath>[] | undefined {
1206
- return scopePaths === undefined ? ownedPaths : undefined;
1207
- }
1208
-
1209
1206
  private async prefetchCompleteRestoreBlobs(
1210
1207
  plan: RestorePlan,
1211
1208
  current: SnapshotManifest,
@@ -1542,7 +1539,8 @@ export class RestoreEngine {
1542
1539
  options.mutationJournal,
1543
1540
  {
1544
1541
  topologyValidated: true,
1545
- ownedPaths: this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
1542
+ scopePaths,
1543
+ ownedPaths: [currentPaths],
1546
1544
  },
1547
1545
  );
1548
1546
  const verification = await this.verifyTarget(
@@ -1587,7 +1585,8 @@ export class RestoreEngine {
1587
1585
  options.mutationJournal,
1588
1586
  {
1589
1587
  topologyValidated: true,
1590
- ownedPaths: this.completeCoverageOwnedPaths(scopePaths, [currentPaths]),
1588
+ scopePaths,
1589
+ ownedPaths: [currentPaths],
1591
1590
  },
1592
1591
  );
1593
1592
  const verification = await this.verifyTarget(
@@ -1791,10 +1790,10 @@ export class RestoreEngine {
1791
1790
  }
1792
1791
  const allowedPaths = new Set<string>();
1793
1792
  for (const [index, manifest] of allowedManifests.entries()) {
1794
- for (const path of ignoredWorkspacePaths(manifest)) {
1793
+ for (const path of ignoredWorkspacePaths(manifest, check.scopePaths)) {
1795
1794
  allowedPaths.add(path);
1796
1795
  }
1797
- const paths = check.ownedPaths?.[index] ?? await this.readOwnedPaths(manifest);
1796
+ const paths = check.ownedPaths?.[index] ?? await this.readOwnedPaths(manifest, check.scopePaths);
1798
1797
  for (const [path, owned] of paths) {
1799
1798
  if (owned.entry.kind !== "directory") {
1800
1799
  allowedPaths.add(path);
@@ -1808,6 +1807,7 @@ export class RestoreEngine {
1808
1807
  }
1809
1808
  const livePaths = await this.store.listVisibleLeafPaths(topology, {
1810
1809
  excludePaths: exclusions.size === 0 ? undefined : [...exclusions],
1810
+ includePaths: check.scopePaths,
1811
1811
  topologyAlreadyValidated: check.topologyValidated,
1812
1812
  });
1813
1813
  for (const path of livePaths) {
@@ -2144,9 +2144,17 @@ function workspacePath(root: string, path: string): string {
2144
2144
  return root === "." ? path : path === "." ? root : `${root}/${path}`;
2145
2145
  }
2146
2146
 
2147
- function ignoredWorkspacePaths(manifest: SnapshotManifest): Set<string> {
2147
+ function ignoredWorkspacePaths(
2148
+ manifest: SnapshotManifest,
2149
+ scopePaths?: readonly string[],
2150
+ ): Set<string> {
2151
+ const scope = scopePaths === undefined ? undefined : new Set(scopePaths);
2152
+ const scopeAncestors = new Set(scopePaths?.flatMap(strictPathAncestors));
2148
2153
  return new Set(manifest.roots.flatMap((root) =>
2149
- root.ignoredPresentPaths.map((path) => workspacePath(root.relativeRoot, path))
2154
+ root.ignoredPresentPaths
2155
+ .map((path) => workspacePath(root.relativeRoot, path))
2156
+ .filter((path) => scope === undefined || scope.has(".") || scope.has(path) ||
2157
+ scopeAncestors.has(path) || strictPathAncestors(path).some((ancestor) => scope.has(ancestor)))
2150
2158
  ));
2151
2159
  }
2152
2160
 
@@ -155,6 +155,11 @@ export interface CaptureOptions {
155
155
  readonly topologyAlreadyValidated?: boolean;
156
156
  }
157
157
 
158
+ export interface VisibleLeafOptions extends CaptureOptions {
159
+ /** 未传时枚举整个工作区;空数组不枚举,目录路径包含其子树。 */
160
+ readonly includePaths?: readonly string[];
161
+ }
162
+
158
163
  export interface SnapshotBlobRequest {
159
164
  readonly rootPath: string;
160
165
  readonly blobId: string;
@@ -188,7 +193,7 @@ export interface SnapshotStore {
188
193
  scope?: readonly string[],
189
194
  options?: CaptureOptions,
190
195
  ): Promise<SnapshotManifest>;
191
- listVisibleLeafPaths(topology: RootTopology, options?: CaptureOptions): Promise<readonly string[]>;
196
+ listVisibleLeafPaths(topology: RootTopology, options?: VisibleLeafOptions): Promise<readonly string[]>;
192
197
  loadManifest(id: ManifestId): Promise<SnapshotManifest>;
193
198
  assertComplete(id: ManifestId, scopePaths?: readonly string[]): Promise<void>;
194
199
  listTree(id: ManifestId, root: string, rootScopePaths?: readonly string[]): Promise<readonly RestorePath[]>;
@@ -552,7 +557,7 @@ export class SnapshotStore {
552
557
 
553
558
  async listVisibleLeafPaths(
554
559
  topology: RootTopology,
555
- options: CaptureOptions = {},
560
+ options: VisibleLeafOptions = {},
556
561
  ): Promise<readonly string[]> {
557
562
  await this.assertPrivateStore(topology.workspaceIdentity);
558
563
  const lockIdentity = `snapshot-store:${await prospectiveCanonicalPath(this.storesRoot)}`;
@@ -561,7 +566,7 @@ export class SnapshotStore {
561
566
 
562
567
  private async listVisibleLeafPathsLocked(
563
568
  topology: RootTopology,
564
- options: CaptureOptions,
569
+ options: VisibleLeafOptions,
565
570
  ): Promise<readonly string[]> {
566
571
  let transactionDirectory: string | undefined;
567
572
  try {
@@ -581,9 +586,23 @@ export class SnapshotStore {
581
586
  const transactionsRoot = join(storeDirectory, "transactions");
582
587
  await mkdir(transactionsRoot, { recursive: true });
583
588
  transactionDirectory = await mkdtemp(join(transactionsRoot, "visible-"));
589
+ const includePaths = options.includePaths === undefined ? undefined : [...new Set(
590
+ options.includePaths.map((path) => {
591
+ const safe = relativeSafePath(topology.workspaceIdentity, path);
592
+ if (safe.split("/").some((part) => part.toLowerCase() === ".git")) {
593
+ throw new SnapshotStoreError("capture_failed", `可见路径 scope 不能包含 Git metadata:${path}`);
594
+ }
595
+ return safe;
596
+ }),
597
+ )].sort(comparePaths);
584
598
  const result = new Set<string>();
585
599
  for (const root of topology.roots) {
586
600
  if (root.state !== "active") continue;
601
+ const exclusions = topology.roots
602
+ .filter((candidate) => isStrictRootAncestor(root.relativeRoot, candidate.relativeRoot))
603
+ .map((candidate) => rootRelativePath(root.relativeRoot, candidate.relativeRoot));
604
+ const inclusions = ownedRootInclusions(rootScopePathspecs(root.relativeRoot, includePaths), exclusions);
605
+ if (inclusions === null) continue;
587
606
  const gitDirectory = this.rootGitDirectory(storeDirectory, root);
588
607
  await this.ensurePrivateRepository(gitDirectory);
589
608
  await this.assertNoAlternates(gitDirectory);
@@ -592,15 +611,12 @@ export class SnapshotStore {
592
611
  const environment = privateGitEnvironment(gitDirectory, absoluteRoot, indexPath);
593
612
  await this.runGit(["read-tree", "--empty"], { cwd: absoluteRoot, env: environment });
594
613
  await this.validateIgnoreQuery(absoluteRoot, environment, root.gitBacked);
595
- const exclusions = topology.roots
596
- .filter((candidate) => isStrictRootAncestor(root.relativeRoot, candidate.relativeRoot))
597
- .map((candidate) => rootRelativePath(root.relativeRoot, candidate.relativeRoot));
598
614
  const exactExclusions = ownedArtifactExclusions(topology.roots, root.relativeRoot, artifactExclusions);
599
615
  for (const relativePath of await this.queryVisibleLeafPaths(
600
616
  absoluteRoot,
601
617
  environment,
602
618
  root.gitBacked,
603
- [],
619
+ inclusions,
604
620
  exclusions,
605
621
  exactExclusions,
606
622
  true,