@iyowei/sweep-node-modules 0.3.0 → 0.5.0
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.
- package/LICENSE +1 -1
- package/README.md +628 -82
- package/README.zh-CN.md +675 -0
- package/dist/classify.d.ts +48 -0
- package/dist/codes.d.ts +41 -0
- package/dist/config.d.ts +115 -0
- package/dist/delete.d.ts +155 -0
- package/dist/display.d.ts +29 -0
- package/dist/errors.d.ts +43 -0
- package/dist/guard.d.ts +230 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +1775 -0
- package/dist/manifest.json +8 -0
- package/dist/runtime.d.ts +26 -0
- package/dist/scan-native.d.ts +2 -0
- package/dist/scan-parallel.d.ts +2 -0
- package/dist/scan-prune.d.ts +2 -0
- package/dist/scan.d.ts +6 -0
- package/dist/size-du.d.ts +33 -0
- package/dist/size-js.d.ts +2 -0
- package/dist/size.d.ts +2 -0
- package/dist/skip.d.ts +35 -0
- package/dist/summary.d.ts +38 -0
- package/dist/sweep.d.ts +7 -0
- package/dist/types.d.ts +458 -0
- package/package.json +18 -31
- package/bin/sweep-nm.mjs +0 -43
- package/dist/cli.js +0 -1348
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,675 @@
|
|
|
1
|
+
# sweep-node-modules
|
|
2
|
+
|
|
3
|
+
[](https://github.com/iyowei/sweep-node-modules/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/@iyowei/sweep-node-modules)
|
|
5
|
+
[](https://www.npmjs.com/package/@iyowei/sweep-node-modules)
|
|
6
|
+

|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
[English](README.md) | **中文**
|
|
10
|
+
|
|
11
|
+
工作区级 `node_modules` 清理能力的可编程 API: 扫描、测体积并安全删除, 供你自己的脚本与工具直接调用。CLI 包就是这套 API 之上的一层薄壳。
|
|
12
|
+
|
|
13
|
+
> **包定位变更说明**: 0.4.0 及以前, `@iyowei/sweep-node-modules` 是命令行工具; 自 0.5.0 起, 该名字承载可编程 API 包 (纯库形态, 无 `bin`), CLI 则迁到独立包 **[@iyowei/sweep-node-modules-cli](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)**。要找 `sweep-nm` 命令的, 请改装该包; 命令名、旗标与配置文件均照旧。机器上装着旧名 CLI 的, 升级它只会得到本库、不再有命令: 卸载旧的全局安装, 改装 `-cli` 包。迁移细节见 release notes。
|
|
14
|
+
|
|
15
|
+
## 目录
|
|
16
|
+
|
|
17
|
+
- [要求](#要求)
|
|
18
|
+
- [安装](#安装)
|
|
19
|
+
- [快速上手](#快速上手)
|
|
20
|
+
- [两级导出面](#两级导出面)
|
|
21
|
+
- [编排层](#编排层)
|
|
22
|
+
- [原语层](#原语层)
|
|
23
|
+
- [错误与代码](#错误与代码)
|
|
24
|
+
- [进度与取消](#进度与取消)
|
|
25
|
+
- [安全模型](#安全模型)
|
|
26
|
+
- [数据形态与稳定性](#数据形态与稳定性)
|
|
27
|
+
- [开发](#开发)
|
|
28
|
+
- [文档](#文档)
|
|
29
|
+
|
|
30
|
+
## 要求
|
|
31
|
+
|
|
32
|
+
- **双运行时**: 有 bun 走 bun, 否则 node (功能一致, bun 启动更快); node 版本下限 `>= 22.18.0` (本包 `engines` 字段)。
|
|
33
|
+
- 零第三方运行时依赖: 只用运行时内置能力 (见 [ADR 0003](../../docs/adrs/0003-zero-runtime-deps.md))。
|
|
34
|
+
- 平台: Windows / macOS / Linux 三平台均可运行 (见 [ADR 0007](../../docs/adrs/0007-platform-portability.md))。
|
|
35
|
+
- 源码为 TypeScript; 类型声明随包分发。
|
|
36
|
+
|
|
37
|
+
## 安装
|
|
38
|
+
|
|
39
|
+
```shell
|
|
40
|
+
npm install @iyowei/sweep-node-modules
|
|
41
|
+
bun add @iyowei/sweep-node-modules
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
本包不装命令: 它是一个库。命令行工具请装 [@iyowei/sweep-node-modules-cli](https://www.npmjs.com/package/@iyowei/sweep-node-modules-cli)。
|
|
45
|
+
|
|
46
|
+
## 快速上手
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import {
|
|
50
|
+
createSweeper,
|
|
51
|
+
formatBytes,
|
|
52
|
+
summarizeReport,
|
|
53
|
+
} from '@iyowei/sweep-node-modules';
|
|
54
|
+
|
|
55
|
+
// 编排层不读平台配置文件: 扫什么由你显式给定
|
|
56
|
+
const sweeper = createSweeper({
|
|
57
|
+
roots: ['/Users/me/workspace/development'], // 绝对路径
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
// plan(): 只读面。扫描 + 体积 + 类别 + 设备 + 批次构造, 零删除
|
|
61
|
+
const plan = await sweeper.plan();
|
|
62
|
+
|
|
63
|
+
for (const entry of plan.entries) {
|
|
64
|
+
const size = entry.bytes === undefined ? '?' : formatBytes(entry.bytes);
|
|
65
|
+
const note = entry.inBatch ? '' : ` (${entry.skipNote})`;
|
|
66
|
+
console.log(
|
|
67
|
+
`${entry.inBatch ? '*' : '-'} ${size.padStart(9)} ${entry.target}${note}`,
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
console.log(`将清理 ${plan.batch.length} 处`);
|
|
71
|
+
|
|
72
|
+
// run(): 以此刻的磁盘事实重跑判定链, 过安全闸后执行删除
|
|
73
|
+
const report = await sweeper.run({
|
|
74
|
+
expectedBatch: plan.batch, // 把删除面收在上一步刚批准的清单内
|
|
75
|
+
staleTargets: 'missing', // 已被别人删掉的目标不算失败
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
const summary = summarizeReport(report);
|
|
79
|
+
console.log(
|
|
80
|
+
`已删 ${summary.counts.removed} 处, 释放 ${formatBytes(report.releasedBytes)}`,
|
|
81
|
+
);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
上手前值得先知道的几件事:
|
|
85
|
+
|
|
86
|
+
- `roots` 用绝对路径; 删除侧还要求**真实路径形态**: 根及其祖先链不得有符号链接介入。macOS 的 `tmpdir()` 经过 `/var` (系统链接), 当根用之前先归一: `const root = await realpath(await mkdtemp(...))`。读取侧不受此限。
|
|
87
|
+
- 编排层不装载平台配置, 交互向导也留在 CLI 包; 下文的配置装载件, 是给「想在自己的工具里接同一套配置行为」的调用方准备的可选原语。
|
|
88
|
+
- 本包不向 stdout / stderr 写任何东西: 一切给人看的文字都以字符串形式返回, 往哪输出由你决定。
|
|
89
|
+
|
|
90
|
+
## 两级导出面
|
|
91
|
+
|
|
92
|
+
| 层 | 是什么 | 什么时候用 |
|
|
93
|
+
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------- |
|
|
94
|
+
| 编排层: `createSweeper(...).plan()` / `.run()` | 整条链: 扫描 → 体积 → 类别 → 设备 → 批次构造 → 安全闸 → 删除 → 报告 | 默认选它。你只管声明扫什么, 并决定报告怎么用 |
|
|
95
|
+
| 原语层: `createScanner` / `createSizer` / `validateTargets` / `removeTargets` / ... | 单点能力, 每个都可独立使用 | 需要逐步控制, 或只取链上某一环嵌进自己的流程 |
|
|
96
|
+
|
|
97
|
+
CLI 包是编排层的薄壳: 解析 → 调用 → 渲染 → 确认。业务语义只有本包一份实现, CLI 是消费方, 不是第二份拷贝。
|
|
98
|
+
|
|
99
|
+
## 编排层
|
|
100
|
+
|
|
101
|
+
### `createSweeper(options): Sweeper`
|
|
102
|
+
|
|
103
|
+
构造编排器: 整条链收在一个对象之后。工厂不做任何 IO, 第二个实例不花什么成本。
|
|
104
|
+
|
|
105
|
+
- `options` `SweepOptions`:
|
|
106
|
+
- `roots` `string[]` (必填, 非空): 扫描根, 绝对路径。
|
|
107
|
+
- `exclude?` `string[]`: 要跳过的目录名; 根到命中点之间任意一级命中即整棵子树跳过。缺省取 `DEFAULT_EXCLUDE` (与 CLI 同一份内置名单)。
|
|
108
|
+
- `include?` `string[]`: 包含名单; 根到 `node_modules` 之间出现其一才纳入。缺省 `[]` (不过滤)。两个名单同时命中时 `exclude` 优先。
|
|
109
|
+
- `home?` `string | null`: 家目录 (清单缩写与隐藏目录形态判定共用的同一份语义)。缺省 `os.homedir()`; `null` 关闭 home 本体防线与隐藏目录形态判定。
|
|
110
|
+
- `style?` `PathStyle`: 路径风味; 缺省平台原生 (测试注入用)。
|
|
111
|
+
- `policy?` `SweepPolicy`: `{ releaseSuspects: boolean }`。缺省 `{ releaseSuspects: false }`。
|
|
112
|
+
- Returns: `Sweeper`:
|
|
113
|
+
- `options` `Readonly<ResolvedSweepOptions>`: 合并缺省后的只读选项快照, 供日志与审计。
|
|
114
|
+
- `plan(options?)`: 只读面, 见下。
|
|
115
|
+
- `run(options?)`: 执行面, 见下。
|
|
116
|
+
|
|
117
|
+
参数错误 (`roots` 为空或非字符串数组) 在**构造期同步抛出**: 无 IO 即失败, 尽早报错; 下文全部异步入口则一律以 rejected promise 抛出, 同一规则的另一半。
|
|
118
|
+
|
|
119
|
+
- 两份名单都过 CLI 同款的合并 (`mergeNames`): 去重, 且 `node_modules` / `.git` 被静默剔除 (这两个名字写进任何名单都永不生效)。
|
|
120
|
+
- `policy.releaseSuspects` 就是库侧的 `--force`: 放行「疑似安装树」进批, 只放行这一类, 不放宽任何不变量; 跨设备目标不受它影响。
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
const sweeper = createSweeper({
|
|
124
|
+
roots, // 必填, 非空: 扫描根, 绝对路径
|
|
125
|
+
exclude, // 缺省取 DEFAULT_EXCLUDE (与 CLI 同一份内置名单)
|
|
126
|
+
include, // 缺省 [] (不过滤)
|
|
127
|
+
home, // 缺省 os.homedir(); 传 null 关闭 home 本体防线与隐藏目录形态判定
|
|
128
|
+
style, // posix / win32 路径风味; 缺省平台原生 (测试注入用)
|
|
129
|
+
policy: { releaseSuspects: false },
|
|
130
|
+
});
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### `sweeper.plan(options?): Promise<SweepPlan>`
|
|
134
|
+
|
|
135
|
+
只读面: 扫描 + 体积 + 类别 + 设备 + 批次构造, 零删除。
|
|
136
|
+
|
|
137
|
+
- `options?` `SweepPlanOptions`:
|
|
138
|
+
- `onProgress?` `(event: SweepProgressEvent) => void`: 进度回调; 阶段事件加上透传的各类原语事件。
|
|
139
|
+
- `signal?` `AbortSignal`: 取消信号, 传给各层。
|
|
140
|
+
- Returns: `Promise<SweepPlan>`:
|
|
141
|
+
- `roots` / `exclude` / `include` / `policy`: 本次生效的输入, 回显供审计 (名单已过 `mergeNames`)。
|
|
142
|
+
- `basis?` `SizeBasis`: 本次运行的体积口径, 有目标被测到时给出 (与逐条 `entry.basis` 同值)。
|
|
143
|
+
- `entries` `SweepEntry[]`: 每个命中一条: `target` / `project` / `root` / `bytes?` / `basis?` / `kind` / `kindReason?` / `crossDevice?` / `unmeasuredCode?` / `unmeasuredReason?` / `inBatch`, 未进批者另带 `skipReason` 与 `skipNote` (码与话随条目携带, 复核表不必按 target 去 join)。
|
|
144
|
+
- `batch` `string[]`: 将进入删除的目标清单, 保清单顺序。
|
|
145
|
+
- `skipped` `SkippedTarget[]`: 全部批次外目标, 各带 `reason` 与 `note`。
|
|
146
|
+
- `warnings` `SweepWarning[]`: 扫描与体积的非致命告警 (`{ code, message, path?, errno? }`); `code` 为 `SweepWarningCode`, 即 `ScanWarningCode` 与 `SizeWarningCode` 的并集。
|
|
147
|
+
- `nameMatches`: `{ exclude: NameMatch[]; include: NameMatch[] }`, 两份名单的逐名命中统计 (零命中的名字也在列, 拼错了当场可见)。
|
|
148
|
+
|
|
149
|
+
```ts
|
|
150
|
+
const plan = await sweeper.plan({ onProgress, signal });
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### `sweeper.run(options?): Promise<SweepReport>`
|
|
154
|
+
|
|
155
|
+
先重跑一遍只读面 (绝不拿旧计划执行: 每个事实都以此刻的磁盘状态重判), 再送安全闸、执行删除。
|
|
156
|
+
|
|
157
|
+
- `options?` `SweepRunOptions` (继承 `SweepPlanOptions`, 因此 `onProgress` 与 `signal` 照旧可用):
|
|
158
|
+
- `expectedBatch?` `readonly string[]`: 刚被批准的那份清单。给了它, 本次删除面 = 期望批次 ∩ 实时批次: 之后新冒出来的目标不删 (进 `drift.added`, 条目结果为 `{ kind: 'not-expected' }`), 已消失或被策略挡下的也不删 (进 `drift.removed`)。它收窄范围, 不跳过重判。
|
|
159
|
+
- `staleTargets?` `'reject' | 'missing'` (缺省 `'reject'`): 安全闸之前「目标已不存在」怎么处置。`'missing'` 把这类目标从批次摘出、按「目标已达成」计成功侧, 不触发整批拒绝 (对应「别人已经删掉了」这类情形); 缺省维持保守规则: 一处被拒, 整批零删除。只有 `GUARD_TARGET_MISSING` 适用这条; 不可读与其余任何拒绝码仍维持整批拒绝。
|
|
160
|
+
- Returns: `Promise<SweepReport>`:
|
|
161
|
+
- `status` `SweepRunStatus`: `'executed'` | `'rejected'` (整批拒绝) | `'nothing-to-do'` (空批)。
|
|
162
|
+
- `plan` `SweepPlan`: 本次执行实际依据的实时计划; 与先前 `plan()` 不一致时以它为准, 差异另由 `drift` 给出。
|
|
163
|
+
- `validation?` `ValidationResult` / `removal?` `RemovalResult`: 安全闸结果与删除分桶 (`removed` / `missing` / `failed` / `aborted`); 未执行删除时缺省。
|
|
164
|
+
- `entries` `SweepOutcomeEntry[]`: 与 `plan.entries` 同序同长, 每条为条目加 `outcome`。
|
|
165
|
+
- `stale` `string[]`: 按 `staleTargets: 'missing'` 摘出的已消失目标。
|
|
166
|
+
- `drift?` `SweepDrift`: `{ added, removed }`, 提供了 `expectedBatch` 时给出。
|
|
167
|
+
- `releasedBytes` `number`: 成功侧 (removed + missing + stale) 的体积累计。
|
|
168
|
+
|
|
169
|
+
`outcome` 是 `EntryOutcome` 判别联合。`kind` 取值: `removed` / `missing` / `stale` (成功侧: 删掉、核验已不存在、或压根没进删除面), `failed`, `rejected`, `not-attempted` (整批中止时中止点及其之后), `not-expected` (在期望批次之外), `skipped` (被策略挡下)。
|
|
170
|
+
|
|
171
|
+
```ts
|
|
172
|
+
const report = await sweeper.run({
|
|
173
|
+
onProgress,
|
|
174
|
+
signal,
|
|
175
|
+
expectedBatch,
|
|
176
|
+
staleTargets,
|
|
177
|
+
});
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### `isSuccessOutcome(outcome): boolean`
|
|
181
|
+
|
|
182
|
+
- `outcome` `EntryOutcome`
|
|
183
|
+
- Returns: `boolean`: 成功侧 (`removed` / `missing` / `stale`) 为 `true`, 其余 (真失败与未处理项) 为 `false`。
|
|
184
|
+
|
|
185
|
+
别手写 `kind !== 'x' && kind !== 'y'`: 库里哪天新增一种成功侧 kind, 手写判据会静默漏判, 库函数则跟着版本走。
|
|
186
|
+
|
|
187
|
+
### `summarizeReport(report): SweepSummary`
|
|
188
|
+
|
|
189
|
+
- `report` `SweepReport`
|
|
190
|
+
- Returns: `SweepSummary`:
|
|
191
|
+
- `counts` `Record<EntryOutcomeKind, number>`: 逐 kind 计数, 恒有项, 缺省 0。
|
|
192
|
+
- `succeeded` `number`: `removed` + `missing` + `stale`。
|
|
193
|
+
- `unprocessed` `number`: `skipped` + `rejected` + `not-attempted` + `not-expected`。
|
|
194
|
+
- `failed` `number`: 真失败。
|
|
195
|
+
- `aborted` `boolean`: 是否发生了整批中止 (存在 `removal.aborted`)。
|
|
196
|
+
|
|
197
|
+
### 成功口径与退出码
|
|
198
|
+
|
|
199
|
+
「本次运行算不算成功」是产品口径, 不是数据事实, 所以库不内置 `ok` 字段, 只给数字与三种常见配方:
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
const summary = summarizeReport(report);
|
|
203
|
+
|
|
204
|
+
// ① 严格 (与 CLI 包同口径): 任何未处理项或失败都算失败
|
|
205
|
+
const strict =
|
|
206
|
+
summary.failed === 0 &&
|
|
207
|
+
summary.unprocessed === 0 &&
|
|
208
|
+
!summary.aborted &&
|
|
209
|
+
report.status !== 'rejected';
|
|
210
|
+
|
|
211
|
+
// ② 宽松 (交互式): 只有真失败与整批中止算失败
|
|
212
|
+
const relaxed =
|
|
213
|
+
summary.failed === 0 && !summary.aborted && report.status !== 'rejected';
|
|
214
|
+
|
|
215
|
+
// ③ 只读面: 没删成不算失败, 只报数字
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## 原语层
|
|
219
|
+
|
|
220
|
+
每个原语都可独立使用, 导入零副作用, 且都不打印任何东西; 异步入口失败一律 reject。做只读快照, 串 `scan` → `measure` → `classifyTarget` 即可, 这条路径上不存在任何删除动作。
|
|
221
|
+
|
|
222
|
+
### 扫描
|
|
223
|
+
|
|
224
|
+
#### `createScanner(): Scanner`
|
|
225
|
+
|
|
226
|
+
- Returns: `Scanner`:
|
|
227
|
+
- `name` `string`: 候选中立名 (`'parallel'`), 供基准与日志区分实现。
|
|
228
|
+
- `scan(options)`: 见下。
|
|
229
|
+
|
|
230
|
+
#### `scanner.scan(options): Promise<ScanResult>`
|
|
231
|
+
|
|
232
|
+
- `options` `ScanOptions`:
|
|
233
|
+
- `roots` `string[]` (必填): 扫描根 (调用方保证为绝对路径)。
|
|
234
|
+
- `exclude` `string[]` (此处必填: 不过滤就传 `[]`): 目录名; 从根到命中点的任意一级命中即整棵子树跳过。
|
|
235
|
+
- `include` `string[]` (此处必填): 包含名单; 空数组 = 不过滤; 两个名单同时命中时 `exclude` 优先。
|
|
236
|
+
- `signal?` `AbortSignal`: 在每个遍历任务开始前检查; 中断后以 `SweepError('CANCELLED')` reject。
|
|
237
|
+
- `onProgress?` `(event: ScanProgressEvent) => void`: 每命中一处发一条 `hit` 事件。
|
|
238
|
+
- Returns: `Promise<ScanResult>`:
|
|
239
|
+
- `hits` `ScanHit[]`: `{ project, target, root }[]`, 按 `target` 升序、按真实路径去重。`root` 取输入顺序中首个遍历到该命中的根, 按根分组因此确定可复现。
|
|
240
|
+
- `warnings` `SweepWarning[]`: 非致命扫描告警 (`code` 为 `ScanWarningCode`); 某个根不存在或不可读不中断遍历。
|
|
241
|
+
- `excludeMatches` / `includeMatches` `NameMatch[]`: `{ name, hits }[]`, 恒在 (未命中的名字以 `hits: 0` 在列, 拼错了当场可见)。
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
const scan = await createScanner().scan({
|
|
245
|
+
roots,
|
|
246
|
+
exclude: [...DEFAULT_EXCLUDE], // 原语层为必填: 不过滤就传 []
|
|
247
|
+
include: [],
|
|
248
|
+
signal,
|
|
249
|
+
onProgress: (event) => ..., // 每命中一处一条 'hit' 事件
|
|
250
|
+
});
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### 体积
|
|
254
|
+
|
|
255
|
+
#### `createSizer(): Sizer`
|
|
256
|
+
|
|
257
|
+
- Returns: `Sizer`:
|
|
258
|
+
- `name` `string`: 候选中立名 (`'du'` 为 `du` 快路径, `'js'` 为纯实现), 供基准与日志区分实现。
|
|
259
|
+
- `basis` `SizeBasis`: 本实例的体积口径, 调用前即可读。
|
|
260
|
+
- `measure(targets, options?)`: 见下。
|
|
261
|
+
|
|
262
|
+
#### `sizer.measure(targets, options?): Promise<SizeResult>`
|
|
263
|
+
|
|
264
|
+
- `targets` `string[]`: 要测的路径 (通常是 `scan.hits.map((hit) => hit.target)`)。
|
|
265
|
+
- `options?` `MeasureOptions`:
|
|
266
|
+
- `signal?` `AbortSignal`: 逐目标之间检查 (`du` 批量路径在批量调用前后各一次)。
|
|
267
|
+
- `onProgress?` `(event: MeasureProgressEvent) => void`: 每目标一条 (`measured` / `unmeasured` / `gone`)。
|
|
268
|
+
- Returns: `Promise<SizeResult>`:
|
|
269
|
+
- `entries` `SizeEntry[]`: 测到的目标 (`{ target, bytes }`), 按 `target` 升序。
|
|
270
|
+
- `basis` `SizeBasis`: `'disk-usage'` (`du` 快路径, 报磁盘占用) 或 `'logical-bytes'` (纯实现, 报逻辑字节); 一次调用恒一口径, 调用前后都可读, 不要猜它。win32 恒为 `logical-bytes`。
|
|
271
|
+
- `warnings` `SweepWarning[]`: 非致命体积告警 (`code` 为 `SizeWarningCode`)。
|
|
272
|
+
- `unmeasured` `UnmeasuredEntry[]`: 存在但测不到的目标 (`{ target, code, reason }`, `code` 为 `UnmeasuredCode`), 按 `target` 升序。
|
|
273
|
+
- `gone` `string[]`: 测量时已不存在, 保输入顺序。
|
|
274
|
+
|
|
275
|
+
入参每个目标恒落在且仅落在一个桶, 无第四类: `entries` (测到了)、`unmeasured` (存在但测不到)、`gone` (测量时已不存在)。这条完备性恒等式是契约, 不必再造 `'unknown'` 兜底分支。
|
|
276
|
+
|
|
277
|
+
```ts
|
|
278
|
+
const size = await createSizer().measure(targets, { signal, onProgress });
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### 类别
|
|
282
|
+
|
|
283
|
+
#### `classifyTarget(target, options?): Classification`
|
|
284
|
+
|
|
285
|
+
- `target` `string`: 一个 `node_modules` 路径。
|
|
286
|
+
- `options?` `ClassifyOptions`:
|
|
287
|
+
- `style?` `PathStyle`: 路径风味; 缺省平台原生。
|
|
288
|
+
- `home?` `string | null`: 家目录, 供下述隐藏目录形态使用。缺省 `os.homedir()`; `null` 关闭该形态。
|
|
289
|
+
- Returns: `Classification`:
|
|
290
|
+
- `kind` `TargetKind`: `'project'` | `'suspect-install-tree'`。
|
|
291
|
+
- `reason?` `string`: 判定为疑似安装树时的中文理由。
|
|
292
|
+
|
|
293
|
+
纯路径判定, 零 IO, 语义与 CLI 的清单标记同源。三种疑似形态按序判定: 祖先链上任一段命中内置名单 (另加 `extensions` 与 `_npx`); 父目录名为 `lib` (版本管理器把全局包放在 `<版本目录>/lib/node_modules`); `node_modules` 落在**家目录下的隐藏目录**里。比较一律折叠大小写: 多出来的误判同样落在安全侧。
|
|
294
|
+
|
|
295
|
+
```ts
|
|
296
|
+
const { kind, reason } = classifyTarget(target, options?);
|
|
297
|
+
// kind: 'project' | 'suspect-install-tree'
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### 安全闸
|
|
301
|
+
|
|
302
|
+
#### `validateTargets(targets, options): Promise<ValidationResult>`
|
|
303
|
+
|
|
304
|
+
- `targets` `string[]`: 候选目标。
|
|
305
|
+
- `options` `ValidateOptions`:
|
|
306
|
+
- `roots` `string[]` (必填): 扫描根, 须保留配置里的原始拼写; 锚点判定读的是拼写, 不是真实路径。
|
|
307
|
+
- `home?` `string | null`: home 本体防线; 缺省 `os.homedir()`, `null` 关闭。
|
|
308
|
+
- `style?` `PathStyle`: 路径风味; 缺省平台原生。
|
|
309
|
+
- `signal?` `AbortSignal`: 逐目标之间检查。
|
|
310
|
+
- Returns: `Promise<ValidationResult>`:
|
|
311
|
+
- `accepted` `string[]`: 可删目标: 已 realpath 归一、已去重、保输入顺序。
|
|
312
|
+
- `rejected` `RejectedTarget[]`: 每条被拒目标的 `{ target, code, message, details? }`, 与输入逐条对应; `code` 为 `GuardCode`, `details?` 为 `RejectionDetails` (`{ errno?, root?, symlink? }`)。
|
|
313
|
+
- `mappings` `PathMapping[]`: `{ original, real }` 配对, 与 `accepted` 逐位对应; 显示用 `original`, 删除用 `real`, 不必再靠位次手工对齐。
|
|
314
|
+
|
|
315
|
+
各不变量逐条判定、命中即短路: 末段必须恰为 `node_modules`; 目标须存在且可读 (realpath); 配置拼写的根链上有符号链接介入时, 其下目标整类被拒; 文件系统根本体与 home 本体直接拒绝; 真实路径仍须以 `node_modules` 结尾、落在某个声明的根之下, 且按真实路径去重。拒绝**走返回值而非抛错**: 整份清单恒被处理完, 每条拒绝都带 `code` 供分流。
|
|
316
|
+
|
|
317
|
+
### 设备边界
|
|
318
|
+
|
|
319
|
+
#### `findCrossDeviceTargets(targets, options): Promise<CrossDeviceEntry[]>`
|
|
320
|
+
|
|
321
|
+
- `targets` `string[]`
|
|
322
|
+
- `options` `CrossDeviceOptions`:
|
|
323
|
+
- `roots` `string[]` (必填): 目标的所属根取包含它且路径最长的那个根。
|
|
324
|
+
- `style?` `PathStyle`: 路径风味; 缺省平台原生。
|
|
325
|
+
- `probe?` `DeviceProbe`: 设备号探针; 缺省 `fsDeviceProbe` (注入它可在单一文件系统上测跨设备流程)。
|
|
326
|
+
- Returns: `Promise<CrossDeviceEntry[]>`: `{ target, kind }` 条目, 保输入顺序; 无跨设备目标时为空数组。
|
|
327
|
+
|
|
328
|
+
`kind: CrossDeviceKind` 取 `'on-path' | 'target-itself'`: 要么挂载点位于根与目标之间, 要么目标本体即挂载点。两形态的解除路径不同 (把挂载点声明为独立根, 或先卸载该卷), 故分列呈现, 且都不由 policy 放行。结果返回数组而非 `Map`, 是为了让它能穿过 `JSON.stringify` 进审计而不丢列。
|
|
329
|
+
|
|
330
|
+
#### `crossDeviceIndex(entries): ReadonlyMap<string, CrossDeviceKind>`
|
|
331
|
+
|
|
332
|
+
- `entries` `readonly CrossDeviceEntry[]`
|
|
333
|
+
- Returns: `ReadonlyMap<string, CrossDeviceKind>`: 查询视图 (跳过集册家族第二参要的 `has` / `get` 形态)。
|
|
334
|
+
|
|
335
|
+
```ts
|
|
336
|
+
const crossDevice = await findCrossDeviceTargets(targets, { roots });
|
|
337
|
+
const index = crossDeviceIndex(crossDevice); // 需要 has / get 时用这个视图
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
#### `fsDeviceProbe(path, follow): Promise<number | null>`
|
|
341
|
+
|
|
342
|
+
- `path` `string`
|
|
343
|
+
- `follow` `boolean`: `true` 取 `stat` 语义 (解析末段符号链接), `false` 取 `lstat` 语义 (不解析)。
|
|
344
|
+
- Returns: `Promise<number | null>`: 该路径的 `st_dev`; 读不到 (路径已消失或不可读) 时为 `null`。
|
|
345
|
+
|
|
346
|
+
`DeviceProbe` 的缺省实现 (`(path: string, follow: boolean) => Promise<number | null>`)。两种语义并存, 因为两处调用方要的读法相反: 根按 `follow: true` 读 (其解析出的实际目录才是参照面), 目标按 `follow: false` 读 (与 `fs.rm` 对齐: 删的是链接, 不跟进)。
|
|
347
|
+
|
|
348
|
+
### 路径风味与锚点判定
|
|
349
|
+
|
|
350
|
+
安全闸的路径层, 暴露给测试与自定义流程。每个判定函数都把 `PathStyle` 显式传参, 且不做任何 IO。
|
|
351
|
+
|
|
352
|
+
#### `POSIX_STYLE` / `WIN32_STYLE`
|
|
353
|
+
|
|
354
|
+
- `PathStyle` 常量, 可直接注入: `WIN32_STYLE` 在每次比较前折叠大小写; `POSIX_STYLE` 不折叠。
|
|
355
|
+
- `PathStyle`: `{ name: 'posix' | 'win32', ops: PathOps, caseInsensitive: boolean }`, 其中 `PathOps` 是最小路径能力集 (`sep` / `basename` / `relative` / `isAbsolute` / `parse` / `join` / `resolve` / `dirname`), `node:path` 的两种风味都满足。
|
|
356
|
+
|
|
357
|
+
#### `nativeStyle(): PathStyle`
|
|
358
|
+
|
|
359
|
+
- Returns: `PathStyle`: 当前平台的风味; 凡省略 `style` 选项处, 它就是缺省。
|
|
360
|
+
|
|
361
|
+
#### `dedupeKey(realPath, style): string`
|
|
362
|
+
|
|
363
|
+
- `realPath` `string`, `style` `PathStyle`
|
|
364
|
+
- Returns: `string`: 真实路径的去重键 (win32 上先折叠大小写)。
|
|
365
|
+
|
|
366
|
+
#### `hasNodeModulesLeaf(target, style): boolean`
|
|
367
|
+
|
|
368
|
+
- `target` `string`, `style` `PathStyle`
|
|
369
|
+
- Returns: `boolean`: 末段是否恰为 `node_modules` (win32 上大小写不敏感)。
|
|
370
|
+
|
|
371
|
+
#### `insideAnyRoot(realPath, roots, style): boolean`
|
|
372
|
+
|
|
373
|
+
- `realPath` `string`, `roots` `string[]`, `style` `PathStyle`
|
|
374
|
+
- Returns: `boolean`: 该路径是否严格位于某个根之下, 按 `path.relative` 语义判定而非字符串前缀。等于根本体、上溯逃逸 (`..`)、或结果为绝对路径 (win32 跨盘), 一律算在外。
|
|
375
|
+
|
|
376
|
+
#### `isFilesystemRootBody(realPath, style): boolean`
|
|
377
|
+
|
|
378
|
+
- `realPath` `string`, `style` `PathStyle`
|
|
379
|
+
- Returns: `boolean`: 该路径是否即文件系统根本体 (posix 的 `/`, win32 的盘根)。
|
|
380
|
+
|
|
381
|
+
#### `isHomeBody(realPath, home, style): boolean`
|
|
382
|
+
|
|
383
|
+
- `realPath` `string`, `home` `string | null`, `style` `PathStyle`
|
|
384
|
+
- Returns: `boolean`: 该路径是否即 home 本体; `home: null` 关闭该判定。
|
|
385
|
+
|
|
386
|
+
#### `firstSymlinkOnAnchor(links): string | null`
|
|
387
|
+
|
|
388
|
+
- `links` `AnchorLink[]`: 链上逐级一条 `{ path, symlink }`, `symlink` 由 `lstat` 判得 (指向哪里都算, 悬空也算: 链上有链接这一事实本身就是证据)。
|
|
389
|
+
- Returns: `string | null`: 首个符号链接那一级的路径; 全级皆真目录时为 `null`。
|
|
390
|
+
|
|
391
|
+
锚点判在配置拼写上, 不判在 realpath 上: realpath 永远只报此刻的解析结果, 名字被换成链接这件事在它那里不留痕, 而拼写上看得见。系统固有链接 (macOS 的 `/var`、`/tmp`) 同样命中, 这是刻意的: 在拼写层, 用户环境与攻击无法区分, 一律拒绝; 解法是改写成真实路径。
|
|
392
|
+
|
|
393
|
+
#### `anchorChainPaths(root, style): string[]`
|
|
394
|
+
|
|
395
|
+
- `root` `string`: 一个扫描根或任意写入目标; 端点自身入链, 文件系统根本身不入 (它不可能是符号链接)。
|
|
396
|
+
- Returns: `string[]`: 自文件系统根的一级子目录逐级前缀, 直至端点。相对拼写先按给定风格绝对化 (与 `lstat` 读取同一坐标系)。
|
|
397
|
+
|
|
398
|
+
```ts
|
|
399
|
+
anchorChainPaths('/Users/x/ws/app', POSIX_STYLE);
|
|
400
|
+
// ['/Users', '/Users/x', '/Users/x/ws', '/Users/x/ws/app']
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
#### `firstSymlinkOnTarget(target): Promise<string | null>`
|
|
404
|
+
|
|
405
|
+
- `target` `string`
|
|
406
|
+
- Returns: `Promise<string | null>`: 链上首个符号链接的路径; 全链为真目录或各级均不可核验时为 `null`。
|
|
407
|
+
|
|
408
|
+
采集 (逐级 `lstat` 走链) 与检出一步到位。写侧在写之前用它: 写入会跟随链接改写其目标, 故与删除侧读同一条链, 实现只此一份。
|
|
409
|
+
|
|
410
|
+
#### `firstSymlinkOnRoot(root): Promise<string | null>`
|
|
411
|
+
|
|
412
|
+
- `root` `string`
|
|
413
|
+
- Returns: `Promise<string | null>`: 与 `firstSymlinkOnTarget` 同一实现, 单独留名, 因为该调用点把它读作扫描根的信任锚。
|
|
414
|
+
|
|
415
|
+
### 删除
|
|
416
|
+
|
|
417
|
+
#### `removeTargets(targets, options): Promise<RemovalResult>`
|
|
418
|
+
|
|
419
|
+
- `targets` `string[]`: 过安全闸的目标 (realpath 形态)。
|
|
420
|
+
- `options` `RemovalOptions`:
|
|
421
|
+
- `roots` `TrustRoot[]` (必填): 拥有这些目标的信任根; 目标不在任何根之下即整批中止。
|
|
422
|
+
- `signal?` `AbortSignal`: 条目之间检查 (单条 `rm` 中途的硬纪律见 [进度与取消](#进度与取消))。
|
|
423
|
+
- `onProgress?` `(event: RemovalProgressEvent) => void`: 每条目标出桶即发一条 (`removed` / `missing` / `failed` / `aborted`)。
|
|
424
|
+
- Returns: `Promise<RemovalResult>`:
|
|
425
|
+
- `removed` `string[]`: 已删除, 保输入顺序。
|
|
426
|
+
- `missing` `string[]`: `rm` 报 ENOENT 且复核确认目标本体已不存在 (计成功侧, 保输入顺序)。
|
|
427
|
+
- `failed` `TargetFailure[]`: `{ target, code, errno?, message, partialRisk }`, `code` 为 `RemoveFailureCode`; `partialRisk: true` 表示内容可能已被部分删除, 提示人工复查 (`partialRisk: false` 的失败从未尝试删除)。
|
|
428
|
+
- `aborted?` `AbortedBatch`: 复核未通过致整批中止 (`{ target, code, message, path? }`, `code` 为 `AbortCode`); 中止点及其之后一条未动。
|
|
429
|
+
|
|
430
|
+
每条目标删除前, 自根向下至其父目录逐级复核; 半路检出替换即整批停手。
|
|
431
|
+
|
|
432
|
+
```ts
|
|
433
|
+
const removal = await removeTargets(accepted, {
|
|
434
|
+
roots: await toTrustRoots(roots),
|
|
435
|
+
signal,
|
|
436
|
+
onProgress,
|
|
437
|
+
});
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
#### `toTrustRoots(roots): Promise<TrustRoot[]>`
|
|
441
|
+
|
|
442
|
+
- `roots` `string[]`: 配置里的原始拼写。
|
|
443
|
+
- Returns: `Promise<TrustRoot[]>`: `{ configured, real }` 配对, 每根一对; realpath 失败时 `real` 回落为拼写。
|
|
444
|
+
|
|
445
|
+
给每个配置根配上它的真实路径。这对配对是锚点防线的一半, 不要手写。
|
|
446
|
+
|
|
447
|
+
#### `removeBatch(targets, options): Promise<BatchOutcome>`
|
|
448
|
+
|
|
449
|
+
推荐的写侧入口: 安全闸 + 整批拒绝规则 + 配对 + 删除一次吃掉, 调用方不必知道 `TrustRoot` 的存在。
|
|
450
|
+
|
|
451
|
+
- `targets` `string[]`
|
|
452
|
+
- `options` `RemoveBatchOptions`:
|
|
453
|
+
- `roots` `string[]` (必填): 扫描根, 保留配置里的原始拼写; 安全闸据它判归属与锚点, 配对助手供给删除侧。
|
|
454
|
+
- `home?` / `style?` / `signal?` / `onProgress?`: 同 `validateTargets` 与 `removeTargets`。
|
|
455
|
+
- `staleTargets?` `'reject' | 'missing'`: 与 `sweeper.run` 同款的窄容忍。
|
|
456
|
+
- Returns: `Promise<BatchOutcome>`: `{ status: 'rejected', rejected }` (零删除) 或 `{ status: 'executed', accepted, mappings, stale, removal }`。
|
|
457
|
+
|
|
458
|
+
```ts
|
|
459
|
+
const outcome = await removeBatch(targets, { roots, staleTargets });
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
### 跳过集册
|
|
463
|
+
|
|
464
|
+
自己组装「什么不进批、为什么」时:
|
|
465
|
+
|
|
466
|
+
| 你手上有什么 / 想要什么 | 用哪个 |
|
|
467
|
+
| ---------------------------------- | --------------------------------------------- |
|
|
468
|
+
| 有 hits + 体积 + 类别, 要候选数组 | `toSkipCandidates(hits, size, options?)` |
|
|
469
|
+
| 问「这一条进不进批」(单个布尔) | `skipsBatch(entry, crossDevice, policy)` |
|
|
470
|
+
| 问「这一条为什么不进批」(单个编码) | `skipReasonOf(entry, crossDevice, policy)` |
|
|
471
|
+
| 只要进批的目标清单 | `deletionBatch(entries, crossDevice, policy)` |
|
|
472
|
+
| 要整份「码 + 人话 + 末行说明」 | `collectSkips(entries, crossDevice, policy)` |
|
|
473
|
+
| 要跨设备形态的人话标签 | `crossDeviceNote(kind)` |
|
|
474
|
+
|
|
475
|
+
#### `toSkipCandidates(hits, size, options?): SkipCandidate[]`
|
|
476
|
+
|
|
477
|
+
- `hits` `readonly ScanHit[]`: 扫描命中。
|
|
478
|
+
- `size` `SizeResult`: 这些命中的体积结果。
|
|
479
|
+
- `options?` `ClassifyOptions`: 透传给类别判定。
|
|
480
|
+
- Returns: `SkipCandidate[]`: `{ target, bytes?, unmeasuredReason?, suspect }`, 按命中顺序 (`size.gone` 里的目标同样产出, `bytes` 为 undefined)。
|
|
481
|
+
|
|
482
|
+
#### `skipsBatch(entry, crossDevice, policy): boolean`
|
|
483
|
+
|
|
484
|
+
- `entry` `SkipCandidate`; `crossDevice` `ReadonlyMap<string, CrossDeviceKind>` (用 `crossDeviceIndex` 构造); `policy` `SweepPolicy`。
|
|
485
|
+
- Returns: `boolean`: 该条目是否被挡在删除批之外。
|
|
486
|
+
|
|
487
|
+
#### `skipReasonOf(entry, crossDevice, policy): SkipReason | null`
|
|
488
|
+
|
|
489
|
+
- 参数同 `skipsBatch`。
|
|
490
|
+
- Returns: `SkipReason | null`, `null` 即进批。判定顺序即优先级: 跨设备 (两种形态, 不受 policy 影响) → 体积未测到 → 疑似安装树 (仅 `policy.releaseSuspects` 放行)。
|
|
491
|
+
|
|
492
|
+
#### `deletionBatch(entries, crossDevice, policy): string[]`
|
|
493
|
+
|
|
494
|
+
- 参数同 `skipsBatch`。
|
|
495
|
+
- Returns: `string[]`: 进批的目标清单, 保清单顺序。
|
|
496
|
+
|
|
497
|
+
#### `collectSkips(entries, crossDevice, policy): SkipBook`
|
|
498
|
+
|
|
499
|
+
- 参数同 `skipsBatch`。
|
|
500
|
+
- Returns: `SkipBook`:
|
|
501
|
+
- `entries` `ReadonlyArray<SkippedTarget>`: `{ target, reason, note }`, 码与人话一次给全 (与 `plan.skipped` 同源同值)。
|
|
502
|
+
- `trailer` `string[]`: 末行说明行, 按类各一行, 只在出现时出。
|
|
503
|
+
- `hints` `ReadonlyMap<string, string>`: 目标 → 行尾说明, 只收测得体积的条目。
|
|
504
|
+
|
|
505
|
+
`SkipCandidate.suspect` 定为必填是刻意的: 它承载「这条会不会被语义闸挡下」的全部信息, 留成可选的话, 一个裸体积条目就能滑进写侧、安全语义静默消失; 不想手填就走 `toSkipCandidates`。
|
|
506
|
+
|
|
507
|
+
#### `crossDeviceNote(kind): string`
|
|
508
|
+
|
|
509
|
+
- `kind` `CrossDeviceKind`
|
|
510
|
+
- Returns: `string`: 跨设备形态的人话标签。
|
|
511
|
+
|
|
512
|
+
### 配置装载 (可选原语)
|
|
513
|
+
|
|
514
|
+
库不自动读平台配置文件; 这组装载件是给「想在自己的工具里接同一套配置行为」的调用方准备的:
|
|
515
|
+
|
|
516
|
+
#### `resolveConfigPath(options): ResolvedConfigPath`
|
|
517
|
+
|
|
518
|
+
- `options` `ResolveConfigPathOptions`:
|
|
519
|
+
- `flag?` `string`: `--config` 旗标值, 优先级最高。
|
|
520
|
+
- `platform?` `string`: 平台标识; 缺省 `process.platform` (测试注入 `'win32'`)。
|
|
521
|
+
- `homedir?` `string`: 缺省 `os.homedir()`。
|
|
522
|
+
- `env?` `EnvTable`: 环境变量表; 缺省 `process.env` (它承载 `SWEEP_NM_CONFIG`, win32 上还有 `APPDATA` / `USERPROFILE`)。
|
|
523
|
+
- Returns: `ResolvedConfigPath`: `{ path, source }`, `source: ConfigSource` 取 `'flag' | 'env' | 'platform-default'`。
|
|
524
|
+
|
|
525
|
+
优先级: `--config` 旗标 > `SWEEP_NM_CONFIG` 环境变量 > 平台默认。平台默认是 `~/.config/sweep-node-modules/config.json`; win32 上是 `%APPDATA%\sweep-node-modules\config.json`, `APPDATA` 未设时回落到 `USERPROFILE\AppData\Roaming`。
|
|
526
|
+
|
|
527
|
+
#### `loadConfig(path): Promise<LoadConfigResult>`
|
|
528
|
+
|
|
529
|
+
- `path` `string`
|
|
530
|
+
- Returns: `Promise<LoadConfigResult>`: `{ state: 'ok', config }` 或 `{ state: 'absent' }`。文件缺失是正常状态 (向导据此分流); 文件损坏或读取失败抛 `SweepError` (`CONFIG_CORRUPT_JSON` / `CONFIG_CORRUPT_SHAPE` / `CONFIG_READ_FAILED`)。
|
|
531
|
+
|
|
532
|
+
`ok` 分支里, `Config` 携带 `roots` (必填) / `exclude` / `include`: 省略 `exclude` 字段取 `DEFAULT_EXCLUDE`, 省略 `include` 取 `[]`; 而显式写出的空数组意味着由调用方接管该名单。
|
|
533
|
+
|
|
534
|
+
#### `loadResolvedConfig(resolved): Promise<LoadConfigResult>`
|
|
535
|
+
|
|
536
|
+
- `resolved` `ResolvedConfigPath`
|
|
537
|
+
- Returns: 与 `loadConfig` 同形。
|
|
538
|
+
- 来源为显式时更严: `--config` 旗标或 `SWEEP_NM_CONFIG` 指向的文件不存在即抛错 (`SweepError('CONFIG_ABSENT')`), 不让打错的路径静默降级成「没有配置」。平台默认来源保留软行为。
|
|
539
|
+
|
|
540
|
+
#### `mergeNames(configNames, cliNames): string[]`
|
|
541
|
+
|
|
542
|
+
- `configNames` `string[]`, `cliNames` `string[]`
|
|
543
|
+
- Returns: `string[]`: 配置名单在前、CLI 名单殿后, 跨来源去重 (首见者胜), 并静默剔除 `node_modules` 与 `.git` (这两个名字写进名单永不生效)。
|
|
544
|
+
|
|
545
|
+
#### `DEFAULT_EXCLUDE`
|
|
546
|
+
|
|
547
|
+
- `readonly string[]`: 内置排除名单: 包管理器与版本管理器的安装树、编辑器扩展目录、系统 / 应用数据根。
|
|
548
|
+
|
|
549
|
+
### 展示辅助
|
|
550
|
+
|
|
551
|
+
#### `formatBytes(bytes): string`
|
|
552
|
+
|
|
553
|
+
- `bytes` `number`
|
|
554
|
+
- Returns: `string`: 清单同款人类可读体积, 逐级 1024 走 `B` / `KB` / `MB` / `GB` / `TB`; 保留 1 位小数, 整数值省小数尾。
|
|
555
|
+
|
|
556
|
+
#### `sanitizeLine(text): string`
|
|
557
|
+
|
|
558
|
+
- `text` `string`
|
|
559
|
+
- Returns: `string`: 剥控制类字符 (C0 含 ESC 与 DEL、C1、bidi 控制、零宽与 BOM), 剩余空白 (含换行) 折成单空格, 两端去空白。
|
|
560
|
+
|
|
561
|
+
#### `sanitizeOutputLine(text): string`
|
|
562
|
+
|
|
563
|
+
- `text` `string`
|
|
564
|
+
- Returns: `string`: 即 `sanitizeLine`, 差别只有一处: 保留每行的行首缩进 (工具自带的分级手段); 行内其余空白照常折叠。
|
|
565
|
+
|
|
566
|
+
`sanitizeLine` / `sanitizeOutputLine` 是全输出面共用的唯一实现。外部数据 (路径、名字) 进任何输出面前先过它们; CLI 就是这么做的, 也不要再写第二份。
|
|
567
|
+
|
|
568
|
+
## 错误与代码
|
|
569
|
+
|
|
570
|
+
一条规则决定通道: **能列出结果的失败走返回值; 无法开始或无法继续的失败才抛错。**
|
|
571
|
+
|
|
572
|
+
| 通道 | 装什么 | 出现位置 |
|
|
573
|
+
| ------ | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
574
|
+
| 返回值 | 域内可预期结果: 安全闸拒绝、删除失败、整批中止、体积测不到、策略跳过 | `rejected` / `failed` / `aborted` / `unmeasured` / `gone` / `skipped` |
|
|
575
|
+
| 抛错 | 无法开始或无法继续: 参数错误、配置损坏、取消 | 同步入口同步抛; 异步入口 reject |
|
|
576
|
+
|
|
577
|
+
### `SweepError`
|
|
578
|
+
|
|
579
|
+
- `class SweepError extends Error`: `{ name: 'SweepError', code, message, details? }`。
|
|
580
|
+
- `code` `SweepErrorCode`: `CONFIG_READ_FAILED` / `CONFIG_CORRUPT_JSON` / `CONFIG_CORRUPT_SHAPE` / `CONFIG_ABSENT` / `INVALID_ARGUMENT` / `CANCELLED`。
|
|
581
|
+
- `message` `string`: 可读文本 (规矩见下)。
|
|
582
|
+
- `details?` `SweepErrorDetails`: 按 `code` 取值的判别联合: `{ path, errno? }`、`{ path }`、`{ path, field }`、`{ path, source }`、`{ field }`、`{ phase, partial? }`。
|
|
583
|
+
- 构造: `new SweepError(code, message, details?)`。
|
|
584
|
+
- 包内唯一的类: 其余实例一律来自 `createXxx()` 工厂, 域数据则一律是普通对象。
|
|
585
|
+
|
|
586
|
+
### `isSweepError(value): value is SweepError`
|
|
587
|
+
|
|
588
|
+
- `value` `unknown`
|
|
589
|
+
- Returns: `value is SweepError`: 按形状判别 (Error 形状 + `name` + 已知 `code`), 不是类判别。
|
|
590
|
+
|
|
591
|
+
打包或多实例环境 (同一进程里可能并存两份库) 里, `instanceof SweepError` 会给出假阴; 跨实例场景一律用它。未预期的内部异常不作包装, 原样冒泡。
|
|
592
|
+
|
|
593
|
+
### code 家族
|
|
594
|
+
|
|
595
|
+
域内 code 按家族列出 (每个 code 的完整触发表见 [可编程 API 面设计](../../docs/designs/api-surface.md)):
|
|
596
|
+
|
|
597
|
+
```text
|
|
598
|
+
安全闸 (validateTargets → rejected[].code)
|
|
599
|
+
GUARD_LEAF_NOT_NODE_MODULES、GUARD_TARGET_MISSING、GUARD_TARGET_UNREADABLE、
|
|
600
|
+
GUARD_REALPATH_FAILED、GUARD_ROOT_ANCHOR_SYMLINK、GUARD_FILESYSTEM_ROOT_BODY、
|
|
601
|
+
GUARD_HOME_BODY、GUARD_REAL_LEAF_NOT_NODE_MODULES、GUARD_OUTSIDE_ROOTS、
|
|
602
|
+
GUARD_DUPLICATE_TARGET
|
|
603
|
+
|
|
604
|
+
删除失败 (RemovalResult.failed[].code)
|
|
605
|
+
REMOVE_FAILED、REMOVE_ENOENT_SURVIVOR、REVIEW_UNVERIFIED、REVIEW_COMPONENT_VANISHED
|
|
606
|
+
|
|
607
|
+
整批中止 (RemovalResult.aborted.code)
|
|
608
|
+
REVIEW_NOT_UNDER_ANY_ROOT、REVIEW_HEAD_SYMLINK、REVIEW_COMPONENT_REPLACED
|
|
609
|
+
|
|
610
|
+
体积未测到 (SizeResult.unmeasured[].code)
|
|
611
|
+
SIZE_UNMEASURED_PERMISSION、SIZE_UNMEASURED_NOT_DIR、SIZE_UNMEASURED_LOOP、
|
|
612
|
+
SIZE_UNMEASURED_UNPARSEABLE、SIZE_UNMEASURED_CONTROL_CHAR、SIZE_UNMEASURED_OTHER
|
|
613
|
+
|
|
614
|
+
告警 (SweepWarning.code)
|
|
615
|
+
SCAN_ROOT_MISSING、SCAN_ROOT_UNREADABLE、SCAN_ROOT_NOT_DIR、SCAN_ROOT_UNAVAILABLE、
|
|
616
|
+
SCAN_DIR_UNREADABLE、SIZE_DU_OUTPUT_MISMATCH、SIZE_DU_LINE_UNATTRIBUTED、
|
|
617
|
+
SIZE_SUBPATH_FAILED、SIZE_TARGET_VANISHED、SIZE_DU_UNAVAILABLE
|
|
618
|
+
|
|
619
|
+
跳过原因 (SweepEntry.skipReason / SkippedTarget.reason)
|
|
620
|
+
suspect-install-tree、cross-device:on-path、cross-device:target-itself、unmeasured
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
几条要紧的纪律:
|
|
624
|
+
|
|
625
|
+
- **程序判断只许看 `code` 与 `details`, 严禁解析 `message`。** `message` 是给人读的中文人话; 要本地化就丢掉它, 用 `code` + `details` 自造文案。
|
|
626
|
+
- 三个 realpath 拒绝码刻意共用同一句 `message`: 它们靠 `code` 与 `details.errno` (`ENOENT` / `EACCES` / 其余) 区分, 因为处置方向相反: 「已不存在」可容忍, 「不可读」不可。
|
|
627
|
+
- code 一经发布即冻结: 只增不改, 取值不回收。`switch` 的 `default` 分支请记录 code 原文, 不要归入「其他」静默吞掉。
|
|
628
|
+
|
|
629
|
+
## 进度与取消
|
|
630
|
+
|
|
631
|
+
`onProgress` 与 `signal` 可传给 `plan` / `run`, 以及支持它们的任一原语 (`scan`、`measure`、`validateTargets`、`removeTargets`、`removeBatch`)。
|
|
632
|
+
|
|
633
|
+
事件种类: `phase` (逐阶段 start / done, 阶段取 `SweepPhase` 全集: `scan` · `measure` · `classify` · `device` · `plan` · `validate` · `remove`), 原语事件 (`hit` · `measured` · `unmeasured` · `skipped` · `removed` · `failed` · `aborted` · `warning`), 以及终结事件: `plan()` 的流恒以 `plan-done` (携带完整计划) 收尾, `run()` 的流恒以 `done` (携带运行状态) 收尾。终结事件之后不再有任何事件; 取消时流以抛错收场, 终结事件不出现。
|
|
634
|
+
|
|
635
|
+
- 回调同步调用, 库不 await 其返回值; 回调抛错原样冒泡, 中断本次调用 (不吞错)。
|
|
636
|
+
- 事件高频且**不承诺顺序** (并发完成序); 结果承诺有序 (hits 升序、分桶保输入顺序)。
|
|
637
|
+
- 不得在回调里再次调用同一个 `Sweeper` 实例, 也不要在一个实例上并发跑两次调用 (重入未定义); 工厂零 IO, 需要并发就建第二个实例。
|
|
638
|
+
- 取消检查落在条目之间与阶段边界; 取消以 `SweepError('CANCELLED')` 抛错。删除阶段绝不中断单条 `rm` 中途 (那只会新造半删状态): 取消落在条目之间, 错误里带 `details.partial` 给出已出桶的部分结果; 其余阶段只带 `details.phase`, 不返回部分结果。
|
|
639
|
+
|
|
640
|
+
库不提供 `watch()` 异步迭代入口: CLI 直接消费回调, 那是常态; 编辑器一类需要 `for await` 的宿主, 参考实现 (约 20 行) 写在设计文档里。
|
|
641
|
+
|
|
642
|
+
## 安全模型
|
|
643
|
+
|
|
644
|
+
> 本包的性格, 一句话: 看不准的时候, 默认不删。
|
|
645
|
+
|
|
646
|
+
- **导入不做事, `plan()` 也不删任何东西。** 删除只经显式的 `run()` / `removeTargets()` / `removeBatch()` 发生。
|
|
647
|
+
- **删什么, 由名字与归属双重判定。** 只认名字恰为 `node_modules` 的目录, 且必须落在声明的根之下; 归属按路径层级判定, 不是字符串前缀, `..` 上溯与冒名路径一概拒绝。文件系统根本体与 home 本体直接拒绝。
|
|
648
|
+
- **要真实路径, 否则整批拒绝。** 删除侧要求根及其祖先链无符号链接介入, 命中即整批拒绝并指出链接所在; 读取侧照常跟进符号链接根。门槛跟着可逆性走: 不可逆的那一步, 不放行。
|
|
649
|
+
- **一处被拒, 整批零删除**, 而不是逐条放行; 动手前自根至目标父目录逐级复核, 半路被掉包即停止后续条目的删除。唯一窄例外是显式开启的 `staleTargets: 'missing'`, 且只容忍「目标已不存在」: 不放宽任何不变量, 也绝不会把目标加进删除面。
|
|
650
|
+
- **两类目标默认不进批**: 疑似安装树 (只由显式 `policy.releaseSuspects` 放行) 与跨设备目标 (policy 不放行, 解除走布局: 把挂载点声明为独立根, 或先卸载该卷)。体积测不到的目标一律不删: 宁可留着, 不猜。
|
|
651
|
+
- **外部数据进输出前先净化。** `sanitizeLine` / `sanitizeOutputLine` 是全输出面共用的唯一实现; 用它, 别抄一份。
|
|
652
|
+
|
|
653
|
+
## 数据形态与稳定性
|
|
654
|
+
|
|
655
|
+
- 域数据一律普通对象与数组: `JSON.stringify` 无损 (无类实例、无 `Map` / `Set`、无函数)。包内唯一的类是 `SweepError`。
|
|
656
|
+
- 与时间无关: 域数据不带时间戳 (唯一的时钟读数是进度事件里的 `elapsedMs`)。今天写进 JSONL 审计的形状, 明天读回来仍是决策输入。
|
|
657
|
+
- 结果确定: `hits` 按 target 升序、分桶保输入顺序、扫描按真实路径去重; 事件顺序明确不承诺。
|
|
658
|
+
- 导入零副作用; 零 stdout / stderr 写入; 不做 TTY 探测 (交互向导是 CLI 专属面)。
|
|
659
|
+
|
|
660
|
+
| 分级 | 内容 | 承诺 |
|
|
661
|
+
| ---------------------- | ----------------------------------------------------------------------------------- | -------------------------- |
|
|
662
|
+
| 冻结 | 域类型字段名、`code` 取值、`SkipReason` 取值、函数签名、`EntryOutcome` 的 kind 取值 | 破坏性改动须走主版本 |
|
|
663
|
+
| 冻结但允许新增可选字段 | 选项对象 (`SweepOptions`、`SweepRunOptions`、`MeasureOptions` 等) | 加字段是 minor |
|
|
664
|
+
| 允许演化 | `message` / `reason` / `note` 的中文措辞 | 不承诺逐字稳定 |
|
|
665
|
+
| 不承诺 | 进度事件顺序、`warnings` 内部次序 | 结果序有承诺, 事件序无承诺 |
|
|
666
|
+
|
|
667
|
+
## 开发
|
|
668
|
+
|
|
669
|
+
环境准备、常用命令、双运行时验证与提交钩子, 见 [开发指南](../../docs/development.md); 本包位于该仓库的 `packages/sweep-node-modules` 目录。
|
|
670
|
+
|
|
671
|
+
## 文档
|
|
672
|
+
|
|
673
|
+
- [工程技术文档总索引](../../docs/README.md)
|
|
674
|
+
- [可编程 API 面设计](../../docs/designs/api-surface.md): 本页背后的权威导出面、错误码与行为契约
|
|
675
|
+
- [安全防护保障](../../docs/safety-guardrails.md): 全量版 (含已知残余风险的诚实账)
|