@iyowei/sweep-node-modules 0.4.0 → 0.5.1
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 +612 -93
- package/README.zh-CN.md +612 -93
- 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 +1780 -0
- package/dist/manifest.json +4 -3
- 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 +14 -52
- package/bin/sweep-nm.mjs +0 -190
- package/dist/cli.js +0 -1699
package/dist/manifest.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
|
-
"
|
|
3
|
+
"entry": "index.js",
|
|
4
|
+
"entrySha256": "8b9a3b1299219ef256fcf271b99f20a9c7e1e0369cbbeed708f8004c053a1fc0",
|
|
5
|
+
"commit": "97a1b7e609a7c8fedd4741bea90525fd501b7678",
|
|
4
6
|
"dirty": false,
|
|
5
|
-
"
|
|
6
|
-
"builtAt": "2026-09-27T16:43:17.535Z"
|
|
7
|
+
"builtAt": "2026-09-30T07:08:54.449Z"
|
|
7
8
|
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** 运行时探测: 功能检测, 有 Bun 走 Bun 实现, 无则回退 Node 实现 */
|
|
2
|
+
export declare const isBun: boolean;
|
|
3
|
+
/**
|
|
4
|
+
* 运行时自述 (如 `bun 1.4.2`): 供输出如实展示本次的执行环境。
|
|
5
|
+
* 取运行时自报字段而非外部探测 —— 直接跑 `node dist/cli.js` 或经启动器跑, 报的都是真身。
|
|
6
|
+
*/
|
|
7
|
+
export declare const runtimeLabel: string;
|
|
8
|
+
export interface SpawnResult {
|
|
9
|
+
/** 标准输出全文 (UTF-8) */
|
|
10
|
+
stdout: string;
|
|
11
|
+
/** 退出码; 非零不视为错误, 由调用方判定 */
|
|
12
|
+
exitCode: number;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* 执行命令并捕获 stdout。
|
|
16
|
+
* 命令不存在 (ENOENT) 时抛出含命令名的错误; 退出码非零原样返回, 不抛错。
|
|
17
|
+
* stderr 直通 (inherit) 而非捕获: 既避免管道缓冲填满导致子进程阻塞, 又让错误原样可见。
|
|
18
|
+
* 裸名与解析面: win32 上传入裸名会先搜当前工作目录 (CreateProcessW 与 libuv 的搜索序皆然,
|
|
19
|
+
* 见 CLI 包 `bin/sweep-nm.mjs` 文件头与行为契约 EC-08), 调用方须先自行解析为绝对路径再传入;
|
|
20
|
+
* POSIX 侧 execvp 只搜 PATH, 裸名照常安全。
|
|
21
|
+
*/
|
|
22
|
+
export declare function spawnCapture(cmd: string, args: string[]): Promise<SpawnResult>;
|
|
23
|
+
/** 读取文本文件 (UTF-8); 文件不存在时 reject (两运行时行为一致) */
|
|
24
|
+
export declare function readTextFile(path: string): Promise<string>;
|
|
25
|
+
/** 写入文本文件 (UTF-8); 目标目录不存在时 reject */
|
|
26
|
+
export declare function writeTextFile(path: string, text: string): Promise<void>;
|
package/dist/scan.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Sizer } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* 探测可用的 du 可执行文件; 均缺失返回 null。
|
|
4
|
+
* win32 一律返回 null (du 快路径仅 unix, 行为契约 EC-03; 设计侧同款表述见
|
|
5
|
+
* scan-and-size.md「体积统计」): 探针是 POSIX 绝对路径, 在 win32 上会被解析为「当前盘根」
|
|
6
|
+
* 下的 usr\bin\du, 该盘存在同名外来程序时即被 spawn —— 与被扫目录同盘时构成执行链劫持面;
|
|
7
|
+
* 无 du 平台走纯 JS 候选本就是设计语义, 此处的平台守卫把该语义落到实现。
|
|
8
|
+
* platform 显式传入供测试注入 (win32 宿主不可得)。
|
|
9
|
+
*/
|
|
10
|
+
export declare function findDu(platform?: NodeJS.Platform): string | null;
|
|
11
|
+
/** stdout 与输入集合的一致性判定结果 (解析与判定合一, 供单测注入样本验证) */
|
|
12
|
+
export interface DuOutputAssessment {
|
|
13
|
+
/** 解析出的 路径 → 字节; 仅当 intact 为真时可信 */
|
|
14
|
+
sizes: Map<string, number>;
|
|
15
|
+
/** stdout 与本次输入相符 (无重复、无输入之外的路径): 每条可按下标归因 */
|
|
16
|
+
intact: boolean;
|
|
17
|
+
/** 同一路径出现多行 (行结构可疑) */
|
|
18
|
+
duplicated: boolean;
|
|
19
|
+
/** 出现输入集合之外的路径 (形态被改写或注入) */
|
|
20
|
+
unexpected: boolean;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* 解析 du 的 stdout 并判定与输入集合的一致性。
|
|
24
|
+
* 判据是「解析出的路径须全部来自本次输入且无重复」: 任一不符即整批不可信 (fail-safe, 不逐条采信),
|
|
25
|
+
* 因为不符只可能来自输出行结构被破坏 (注入 / 形态改写), 逐条采信会给伪行留下覆盖真实体积的入口。
|
|
26
|
+
*/
|
|
27
|
+
export declare function assessDuOutput(stdout: string, safeTargets: readonly string[]): DuOutputAssessment;
|
|
28
|
+
/**
|
|
29
|
+
* 构造 du 候选。
|
|
30
|
+
* bin 缺省走 findDu() 探针; 显式传入供测试注入 (如用包管理器装的 GNU du 复现 Linux 侧形态),
|
|
31
|
+
* 生产调用不传。
|
|
32
|
+
*/
|
|
33
|
+
export declare function createDuSizer(bin?: string | null): Sizer;
|
package/dist/size.d.ts
ADDED
package/dist/skip.d.ts
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 跳过类目标 (删除面的两道保守默认) 的集册: 判定集、批次排除与文案单源在此, 编排层只消费。
|
|
3
|
+
* 两类判定本体不在本模块: 疑似安装树见 classify.ts (纯路径形态, 零 IO), 跨设备目标见 guard.ts
|
|
4
|
+
* (设备比对); 本模块只管「挡下之后怎么说、怎么放行」——放行通道两样, 互不通兑:
|
|
5
|
+
* 疑似安装树是 `--force` (语义面: 删后能否由项目级重装恢复), 跨设备是声明独立根或先卸载
|
|
6
|
+
* (授权面: 目标落在另一文件系统上, 旗标放行不了, 见 docs/designs/deletion-guard.md「设备边界」)。
|
|
7
|
+
* 入参为 SkipCandidate (非渲染类型): 判定被绑在渲染类型上会让写侧依赖读侧的展示形态。
|
|
8
|
+
*/
|
|
9
|
+
import { type ClassifyOptions } from './classify.js';
|
|
10
|
+
import type { SkipReason } from './codes.js';
|
|
11
|
+
import type { CrossDeviceKind } from './guard.js';
|
|
12
|
+
import type { ScanHit, SizeResult, SkipBook, SkipCandidate, SweepPolicy } from './types.js';
|
|
13
|
+
/** 跨设备形态对应的清单行尾标注 */
|
|
14
|
+
export declare function crossDeviceNote(kind: CrossDeviceKind): string;
|
|
15
|
+
/**
|
|
16
|
+
* 跳过原因的编码判定 (单源): null 即进批。
|
|
17
|
+
* 判定顺序即优先级: 跨设备 (两类形态, 不受 policy 影响) → 体积未测到 → 疑似安装树
|
|
18
|
+
* (仅 policy.releaseSuspects 放行); 同时命中时取更严的一侧, 与行尾/集册文案同源。
|
|
19
|
+
*/
|
|
20
|
+
export declare function skipReasonOf(entry: SkipCandidate, crossDevice: ReadonlyMap<string, CrossDeviceKind>, policy: SweepPolicy): SkipReason | null;
|
|
21
|
+
/**
|
|
22
|
+
* 该条目是否因保守默认 (或未测到体积) 被排除出删除批。
|
|
23
|
+
* `releaseSuspects` 只放行疑似安装树那一类; 跨设备两类一律排除 (解除路径是改配置或卸载, 不是旗标)。
|
|
24
|
+
*/
|
|
25
|
+
export declare function skipsBatch(entry: SkipCandidate, crossDevice: ReadonlyMap<string, CrossDeviceKind>, policy: SweepPolicy): boolean;
|
|
26
|
+
/**
|
|
27
|
+
* 候选构造器: 由扫描命中 + 体积结果 + 类别判定组装 SkipCandidate[]。
|
|
28
|
+
* 与 CLI 的条目构造前半段同源 (target / bytes / suspect 三项), 把「三份数据手工 join」
|
|
29
|
+
* 收进库内; size.gone 里的目标同样产出候选 (bytes 为 undefined), 天然被挡。
|
|
30
|
+
*/
|
|
31
|
+
export declare function toSkipCandidates(hits: readonly ScanHit[], size: SizeResult, options?: ClassifyOptions): SkipCandidate[];
|
|
32
|
+
/** 删除批次: 测到体积且未被保守默认挡下的目标 (保清单顺序) */
|
|
33
|
+
export declare function deletionBatch(entries: SkipCandidate[], crossDevice: ReadonlyMap<string, CrossDeviceKind>, policy: SweepPolicy): string[];
|
|
34
|
+
/** 集册跳过类目标: 计数按清单上的标记行数 (与是否测得体积无关), 说明索引只收测得体积的条目 */
|
|
35
|
+
export declare function collectSkips(entries: SkipCandidate[], crossDevice: ReadonlyMap<string, CrossDeviceKind>, policy: SweepPolicy): SkipBook;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 结果缝合层 (纯函数, 零 IO): 成功侧判据与计数摘要。
|
|
3
|
+
* 契约基准: docs/designs/api-surface.md §2.7 与 §7.8。
|
|
4
|
+
*
|
|
5
|
+
* 存在价值是「随版本新增 EntryOutcome.kind 时不会静默漏判」: 手写的
|
|
6
|
+
* `every(kind !== 'x' && kind !== 'y')` 在库里新增一种成功侧 kind 后会把新 kind
|
|
7
|
+
* 误判为失败, 而本模块的判据跟着版本走 —— 新增 kind 时必过本文件的归类评审。
|
|
8
|
+
* 退出码口径 (「本次运行算不算成功」) 不在此处: 那是产品口径, 由调用方用
|
|
9
|
+
* summarizeReport 的三档配方自定 (见 §2.7)。
|
|
10
|
+
*/
|
|
11
|
+
import type { EntryOutcome, SweepReport, SweepSummary } from './types.js';
|
|
12
|
+
/** 条目的「达成没有」: 成功侧为真, 其余 (真失败与未处理) 为假 */
|
|
13
|
+
export declare function isSuccessOutcome(outcome: EntryOutcome): boolean;
|
|
14
|
+
/**
|
|
15
|
+
* 结果计数摘要: 成功侧 / 未处理 / 真失败 / 整批中止四档, 口径与 §2.7 的严格档配方
|
|
16
|
+
* 同源 (CLI 包即按该档落退出码)。计数表以显式字面量初始化: 新增 kind 时 TS
|
|
17
|
+
* 会在本处报缺键, 强制显式归类。
|
|
18
|
+
*
|
|
19
|
+
* ### 数据追踪示例
|
|
20
|
+
* ```text
|
|
21
|
+
* Input(真实 Payload)
|
|
22
|
+
* report.entries = [{ outcome: { kind: 'removed' } }, { outcome: { kind: 'missing' } },
|
|
23
|
+
* { outcome: { kind: 'skipped', reason: 'suspect-install-tree' } },
|
|
24
|
+
* { outcome: { kind: 'skipped', reason: 'unmeasured' } },
|
|
25
|
+
* { outcome: { kind: 'failed', failure: {...} } }]
|
|
26
|
+
* report.removal = { removed: [...], missing: [...], failed: [...] } // 无 aborted
|
|
27
|
+
*
|
|
28
|
+
* 步骤 1:逐条累计 counts
|
|
29
|
+
* counts = { removed: 1, missing: 1, skipped: 2, failed: 1, 其余 kind 为 0 }
|
|
30
|
+
*
|
|
31
|
+
* 步骤 2:按四档聚合
|
|
32
|
+
* succeeded = 1 + 1 + 0 = 2; unprocessed = 2 + 0 + 0 + 0 = 2; failed = 1; aborted = false
|
|
33
|
+
*
|
|
34
|
+
* Output(数据契约)
|
|
35
|
+
* return { counts, succeeded: 2, unprocessed: 2, failed: 1, aborted: false }
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
export declare function summarizeReport(report: SweepReport): SweepSummary;
|
package/dist/sweep.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import type { SweepOptions, Sweeper } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* 构造编排器。参数错误 (roots 为空 / 非字符串数组等) 在构造期**同步抛出**
|
|
4
|
+
* (INVALID_ARGUMENT, details.field 指首个不符字段); 其余异步入口 (plan / run) 的
|
|
5
|
+
* 参数与环境错误一律以 rejected promise 形式抛出。
|
|
6
|
+
*/
|
|
7
|
+
export declare function createSweeper(options: SweepOptions): Sweeper;
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,458 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 扫描契约: 候选实现共享的接口与返回形态 (设计: 分册「扫描与体积」)。
|
|
3
|
+
* 候选差异只允许存在于接口内部, 调用方无感。
|
|
4
|
+
*/
|
|
5
|
+
import type { TargetKind } from './classify.js';
|
|
6
|
+
import type { AbortCode, SizeBasis, SkipReason, SweepPhase, SweepWarningCode, UnmeasuredCode } from './codes.js';
|
|
7
|
+
import type { AbortedBatch, RemovalResult, TargetFailure } from './delete.js';
|
|
8
|
+
import type { CrossDeviceKind, PathStyle, RejectedTarget, ValidationResult } from './guard.js';
|
|
9
|
+
export interface ScanOptions {
|
|
10
|
+
/** 扫描根 (调用方保证为绝对路径) */
|
|
11
|
+
roots: string[];
|
|
12
|
+
/** 排除名单: 目录名; 从根到命中点的任意一级命中即整棵子树跳过 (装载层在配置省略该字段时缺省注入内置默认名单, 见 config.ts) */
|
|
13
|
+
exclude: string[];
|
|
14
|
+
/**
|
|
15
|
+
* 包含名单 (白名单): 目录名; 从根到 node_modules 的任意一级命中即纳入。
|
|
16
|
+
* 空数组 = 不过滤 (全部纳入); 与 exclude 同时命中时 exclude 优先 (先按白名单筛候选, 再排掉命中排除的)。
|
|
17
|
+
*/
|
|
18
|
+
include: string[];
|
|
19
|
+
/** 取消信号; 检查点在每个遍历任务开始前, 中断后 reject (SweepError CANCELLED) */
|
|
20
|
+
signal?: AbortSignal;
|
|
21
|
+
/** 进度回调; 粒度: 每命中一处发一条 hit 事件 */
|
|
22
|
+
onProgress?: (event: ScanProgressEvent) => void;
|
|
23
|
+
}
|
|
24
|
+
/** 扫描的进度事件 */
|
|
25
|
+
export type ScanProgressEvent = {
|
|
26
|
+
kind: 'hit';
|
|
27
|
+
hit: ScanHit;
|
|
28
|
+
};
|
|
29
|
+
export interface ScanHit {
|
|
30
|
+
/** 直接包含 node_modules 的项目目录 */
|
|
31
|
+
project: string;
|
|
32
|
+
/** node_modules 绝对路径 */
|
|
33
|
+
target: string;
|
|
34
|
+
/**
|
|
35
|
+
* 所属扫描根 (原拼写)。
|
|
36
|
+
* 取值规则: 各根串行推进, 命中以 realpath 去重、先到者胜,
|
|
37
|
+
* 故归属取输入顺序中首个遍历到该命中的根, 结果确定可复现。
|
|
38
|
+
*/
|
|
39
|
+
root: string;
|
|
40
|
+
}
|
|
41
|
+
export interface ScanResult {
|
|
42
|
+
/** 命中清单: 按 target 排序, 已按 realpath 去重 */
|
|
43
|
+
hits: ScanHit[];
|
|
44
|
+
/** 非致命告警 (结构化: 机器码 + 中文人话并存, 如不可读目录), 不中断扫描 */
|
|
45
|
+
warnings: SweepWarning[];
|
|
46
|
+
/**
|
|
47
|
+
* 排除名单命中统计 (名称 → 命中次数); 未命中的名称也在列 (hits === 0)。
|
|
48
|
+
* 性质: 破坏性动作的「保命名单」反馈通道 —— 名字打错/大小写不符时不得静默。
|
|
49
|
+
* 例外: 内置默认名单项零命中不告警 (名单依平台与用户环境而异, 不是可修正的拼写错误;
|
|
50
|
+
* 见 behavior-contract.md BC-09), 用户显式写出同名项时同样静默 (该项已由默认名单覆盖)。
|
|
51
|
+
* 必填的理由: 落盘形态不得随调用参数漂移 —— 月级 JSONL 序列里键时有时无,
|
|
52
|
+
* 下游 schema 校验器无从分辨「没配名单」与「版本不支持该字段」。
|
|
53
|
+
*/
|
|
54
|
+
excludeMatches: NameMatch[];
|
|
55
|
+
/**
|
|
56
|
+
* 包含名单命中统计 (名称 → 命中该名的子树数); 未命中的名称也在列 (hits === 0)。
|
|
57
|
+
* 计数独立于 exclude 优先: 名字命中白名单、随后被 exclude 截走的同样计入 (截走不等于没匹配上),
|
|
58
|
+
* 否则被截走的名字会以 0 报「未匹配」, 诱导用户去排查不存在的拼写问题。
|
|
59
|
+
* 性质: 与 excludeMatches 同款的名单反馈通道, 后果却更重: 白名单写错名字时扫描结果直接为空,
|
|
60
|
+
* 更不能静默。
|
|
61
|
+
*/
|
|
62
|
+
includeMatches: NameMatch[];
|
|
63
|
+
}
|
|
64
|
+
export interface Scanner {
|
|
65
|
+
/** 候选中立名, 供基准与日志区分 */
|
|
66
|
+
name: string;
|
|
67
|
+
scan(options: ScanOptions): Promise<ScanResult>;
|
|
68
|
+
}
|
|
69
|
+
export interface SizeEntry {
|
|
70
|
+
/** node_modules 绝对路径 (对应 ScanHit.target) */
|
|
71
|
+
target: string;
|
|
72
|
+
/** 字节数; 口径见 SizeResult.basis */
|
|
73
|
+
bytes: number;
|
|
74
|
+
}
|
|
75
|
+
/** 存在但无法测量的目标 (权限等): 结构化上报, 下游不得静默移出清单 */
|
|
76
|
+
export interface UnmeasuredEntry {
|
|
77
|
+
/** node_modules 绝对路径 (对应 ScanHit.target) */
|
|
78
|
+
target: string;
|
|
79
|
+
/** 机器可判别的未测到原因 */
|
|
80
|
+
code: UnmeasuredCode;
|
|
81
|
+
/** 人话中文原因 (不含路径本身, 与 target 字段各司其职) */
|
|
82
|
+
reason: string;
|
|
83
|
+
}
|
|
84
|
+
export interface SizeResult {
|
|
85
|
+
/** 可测量目标的体积, 按 target 升序 */
|
|
86
|
+
entries: SizeEntry[];
|
|
87
|
+
/** 本次调用实际生效的体积口径 (同一实例内恒定) */
|
|
88
|
+
basis: SizeBasis;
|
|
89
|
+
/** 非致命告警 (结构化); 含 SIZE_TARGET_VANISHED 事件条 */
|
|
90
|
+
warnings: SweepWarning[];
|
|
91
|
+
/** 存在但无法测量的目标 (如权限不足), 按 target 升序 */
|
|
92
|
+
unmeasured: UnmeasuredEntry[];
|
|
93
|
+
/**
|
|
94
|
+
* 扫描命中、测量时已不存在 (BC-13) 的目标, 按 target 升序 (体积三桶同此口径)。
|
|
95
|
+
* 「不存在」既不产生字节也不属「存在但测不到」, 故单列一桶, 与 warnings 里的
|
|
96
|
+
* SIZE_TARGET_VANISHED 事件同源同判定 (事件供诊断, 本桶供划分)。
|
|
97
|
+
* 划分完备性: entries ∪ unmeasured ∪ gone 恰好构成入参的全划分, 三者两两不相交。
|
|
98
|
+
*/
|
|
99
|
+
gone: string[];
|
|
100
|
+
}
|
|
101
|
+
/** 体积测量的调用选项 (取消与进度透传) */
|
|
102
|
+
export interface MeasureOptions {
|
|
103
|
+
/** 取消信号; 检查点在逐目标之间 (du 批量路径在批量调用前后各一次) */
|
|
104
|
+
signal?: AbortSignal;
|
|
105
|
+
/** 进度回调; 粒度: 每测到一个目标发一条事件 */
|
|
106
|
+
onProgress?: (event: MeasureProgressEvent) => void;
|
|
107
|
+
}
|
|
108
|
+
/** 体积测量的进度事件 */
|
|
109
|
+
export type MeasureProgressEvent = {
|
|
110
|
+
kind: 'measured';
|
|
111
|
+
target: string;
|
|
112
|
+
bytes: number;
|
|
113
|
+
basis: SizeBasis;
|
|
114
|
+
} | {
|
|
115
|
+
kind: 'unmeasured';
|
|
116
|
+
target: string;
|
|
117
|
+
code: UnmeasuredCode;
|
|
118
|
+
reason: string;
|
|
119
|
+
} | {
|
|
120
|
+
kind: 'gone';
|
|
121
|
+
target: string;
|
|
122
|
+
};
|
|
123
|
+
export interface Sizer {
|
|
124
|
+
/** 候选中立名 ('du' / 'js'), 供基准与日志区分 */
|
|
125
|
+
name: string;
|
|
126
|
+
/** 本实例的体积口径; 调用前即可读 */
|
|
127
|
+
basis: SizeBasis;
|
|
128
|
+
measure(targets: string[], options?: MeasureOptions): Promise<SizeResult>;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* 以下为编排层、跳过集册与诊断的类型 (设计基准: api-surface.md §2.5 / §2.7 / §3.5)。
|
|
132
|
+
* 可序列化承诺: 全部域类型是普通对象与数组, JSON.stringify 无损 (无类实例 / Map / Set / 函数);
|
|
133
|
+
* 时间无关 (库不打时间戳); 可跨会话复用 (形状不含运行时句柄)。
|
|
134
|
+
*/
|
|
135
|
+
/** 名单命中统计的命名形态 (ScanResult 的 excludeMatches / includeMatches 同形) */
|
|
136
|
+
export interface NameMatch {
|
|
137
|
+
/** 名单项 (目录名) */
|
|
138
|
+
name: string;
|
|
139
|
+
/** 命中次数 (未命中的名称也在列, hits === 0) */
|
|
140
|
+
hits: number;
|
|
141
|
+
}
|
|
142
|
+
/** 结构化告警: 机器可判别的 code + 中文人话并存 (替代裸 string) */
|
|
143
|
+
export interface SweepWarning {
|
|
144
|
+
/** 机器可判别的告警码 */
|
|
145
|
+
code: SweepWarningCode;
|
|
146
|
+
/** 中文人话全文 (逐字保留现状文案, CLI 直接打印这一条即与今天逐字节一致) */
|
|
147
|
+
message: string;
|
|
148
|
+
/** 涉及的路径 (根 / 目录 / 目标), 从文案里提出做字段 */
|
|
149
|
+
path?: string;
|
|
150
|
+
/** 原始 errno (若有) */
|
|
151
|
+
errno?: string;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* 跳过候选: 判定「这条会不会进删除批」所需的最小输入。
|
|
155
|
+
* suspect 为必填是安全设计 (承载语义闸的全部信息): 留成可选时, 最顺手的
|
|
156
|
+
* SizeEntry[] 就能通过类型检查喂进写侧函数, 疑似安装树静默进批且无报错;
|
|
157
|
+
* 不想手填的调用方走 toSkipCandidates()。
|
|
158
|
+
*/
|
|
159
|
+
export interface SkipCandidate {
|
|
160
|
+
/** node_modules 绝对路径 */
|
|
161
|
+
target: string;
|
|
162
|
+
/** undefined = 体积未测到 (未测到的条目不进删除批, BC-15) */
|
|
163
|
+
bytes?: number;
|
|
164
|
+
/**
|
|
165
|
+
* 体积未测到时的中文原因 (补, 供 collectSkips 的 entries[].note 单源化:
|
|
166
|
+
* 未测到条目的人话说明取「体积统计失败: <本字段>」, 与 CLI 现行行尾注记同源);
|
|
167
|
+
* bytes 有值时本字段无意义
|
|
168
|
+
*/
|
|
169
|
+
unmeasuredReason?: string;
|
|
170
|
+
/** 疑似安装树 (语义闸判定, BC-37 / BC-38) */
|
|
171
|
+
suspect: boolean;
|
|
172
|
+
}
|
|
173
|
+
/** 批次外的目标与原因 (机器码 + 人话并存) */
|
|
174
|
+
export interface SkippedTarget {
|
|
175
|
+
/** node_modules 绝对路径 */
|
|
176
|
+
target: string;
|
|
177
|
+
/** 机器可判别的跳过原因 */
|
|
178
|
+
reason: SkipReason;
|
|
179
|
+
/** 中文人话行尾说明 (恒有值) */
|
|
180
|
+
note: string;
|
|
181
|
+
}
|
|
182
|
+
/** 跳过集册: 码 + 人话一次给全; 与 plan.skipped 同源同值 */
|
|
183
|
+
export interface SkipBook {
|
|
184
|
+
/** 跳过集册条目 (与 SweepEntry.skipReason / skipNote 逐条一致) */
|
|
185
|
+
readonly entries: ReadonlyArray<SkippedTarget>;
|
|
186
|
+
/** 末行说明行: 按类与形态各一行, 只在出现时出 */
|
|
187
|
+
readonly trailer: string[];
|
|
188
|
+
/** 目标 → 行尾说明 (只收测得体积的条目: 未测到者的行尾已有体积失败注记, 不混同) */
|
|
189
|
+
readonly hints: ReadonlyMap<string, string>;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* 安全策略。
|
|
193
|
+
* releaseSuspects 对应 CLI 的 --force (BC-38): 只影响批次构造, 不放宽安全闸不变量。
|
|
194
|
+
* 跨设备目标不受本字段影响: 恒不进删除批 (BC-41), 解除路径是声明独立根或先卸载。
|
|
195
|
+
*/
|
|
196
|
+
export interface SweepPolicy {
|
|
197
|
+
/** 连同疑似安装树一并纳入删除批; 缺省 false */
|
|
198
|
+
releaseSuspects: boolean;
|
|
199
|
+
}
|
|
200
|
+
/** 编排器构造选项 */
|
|
201
|
+
export interface SweepOptions {
|
|
202
|
+
/** 扫描根 (必填, 非空; 库不读平台配置, 由调用方决定扫什么) */
|
|
203
|
+
roots: string[];
|
|
204
|
+
/** 排除名单; 缺省取 DEFAULT_EXCLUDE (与配置省略该字段时的行为同源, BC-20) */
|
|
205
|
+
exclude?: string[];
|
|
206
|
+
/** 包含名单; 缺省 [] (不过滤) */
|
|
207
|
+
include?: string[];
|
|
208
|
+
/** 家目录 (清单缩写与隐藏目录形态判定共用的同一份语义); 缺省 os.homedir(), null 关闭 home 本体防线 */
|
|
209
|
+
home?: string | null;
|
|
210
|
+
/** 路径风味; 缺省平台原生 (测试注入用) */
|
|
211
|
+
style?: PathStyle;
|
|
212
|
+
/** 安全策略; 缺省 { releaseSuspects: false } */
|
|
213
|
+
policy?: SweepPolicy;
|
|
214
|
+
}
|
|
215
|
+
/** 本次实际生效的选项 (合并缺省后的只读快照, 供审计与日志) */
|
|
216
|
+
export interface ResolvedSweepOptions {
|
|
217
|
+
roots: string[];
|
|
218
|
+
/** 已过 mergeNames 收口的生效名单 (去重 + 静默剔除永不生效名, BC-34) */
|
|
219
|
+
exclude: string[];
|
|
220
|
+
include: string[];
|
|
221
|
+
home: string | null;
|
|
222
|
+
style: PathStyle;
|
|
223
|
+
policy: SweepPolicy;
|
|
224
|
+
}
|
|
225
|
+
/** 只读面调用选项 (plan) */
|
|
226
|
+
export interface SweepPlanOptions {
|
|
227
|
+
/** 进度回调; 阶段事件 + 原语层事件透传 (粒度见 api-surface.md §4.2) */
|
|
228
|
+
onProgress?: (event: SweepProgressEvent) => void;
|
|
229
|
+
/** 取消信号; 透传到各层 */
|
|
230
|
+
signal?: AbortSignal;
|
|
231
|
+
}
|
|
232
|
+
/** 执行面调用选项 (run): 在只读面选项之上加「对账」与「陈旧容忍」两项 */
|
|
233
|
+
export interface SweepRunOptions extends SweepPlanOptions {
|
|
234
|
+
/**
|
|
235
|
+
* 期望批次 (通常是先前 plan().batch)。提供时本次删除面 = 期望批次 ∩ 本次实时批次:
|
|
236
|
+
* 期望批次里已消失或被策略挡下的目标不再删 (报告里给 drift.removed);
|
|
237
|
+
* 本次新出现、不在期望批次里的目标不删 (报告里给 drift.added, 条目结果为 not-expected)。
|
|
238
|
+
* 无论提供与否, 判定链上的每个事实仍是此刻的事实 (仍重跑扫描与安全闸),
|
|
239
|
+
* 故期望批次不是「拿旧计划执行」, 而是「给本次执行加一圈用户已批准的范围」。
|
|
240
|
+
*/
|
|
241
|
+
expectedBatch?: readonly string[];
|
|
242
|
+
/** 安全闸之前已不存在的目标如何处置; 缺省 'reject' */
|
|
243
|
+
staleTargets?: 'reject' | 'missing';
|
|
244
|
+
}
|
|
245
|
+
/** 编排器: 只读面与执行面两段 */
|
|
246
|
+
export interface Sweeper {
|
|
247
|
+
/** 本次实际生效的选项 (合并缺省后的只读快照, 供审计与日志) */
|
|
248
|
+
readonly options: Readonly<ResolvedSweepOptions>;
|
|
249
|
+
/** 只读: 扫描 + 体积 + 类别 + 设备 + 批次构造, 零删除 */
|
|
250
|
+
plan(options?: SweepPlanOptions): Promise<SweepPlan>;
|
|
251
|
+
/** 执行: 重跑 plan, 经安全闸删除, 出报告 */
|
|
252
|
+
run(options?: SweepRunOptions): Promise<SweepReport>;
|
|
253
|
+
}
|
|
254
|
+
/** 逐目标的领域条目: 一次清理里一个 node_modules 的完整状态 */
|
|
255
|
+
export interface SweepEntry {
|
|
256
|
+
/** node_modules 绝对路径 (扫描原拼写, 非 realpath 形态) */
|
|
257
|
+
target: string;
|
|
258
|
+
/** 直接包含 node_modules 的项目目录 (绝对路径) */
|
|
259
|
+
project: string;
|
|
260
|
+
/** 所属扫描根 (扫多根时按根分组的依据) */
|
|
261
|
+
root: string;
|
|
262
|
+
/** 字节数; undefined = 体积测不到 (与 0 严格可分) */
|
|
263
|
+
bytes?: number;
|
|
264
|
+
/** 有 bytes 时必在: 本次调用的体积口径 */
|
|
265
|
+
basis?: SizeBasis;
|
|
266
|
+
/** 类别 (语义闸判定, BC-37) */
|
|
267
|
+
kind: TargetKind;
|
|
268
|
+
/** suspect 时的中文理由 */
|
|
269
|
+
kindReason?: string;
|
|
270
|
+
/** 与所属根跨设备时给出形态; 同设备时缺省 */
|
|
271
|
+
crossDevice?: CrossDeviceKind;
|
|
272
|
+
/** 体积未测到时的机器可判别原因 */
|
|
273
|
+
unmeasuredCode?: UnmeasuredCode;
|
|
274
|
+
/** 体积未测到时的中文原因 */
|
|
275
|
+
unmeasuredReason?: string;
|
|
276
|
+
/** 是否进入删除批次 (policy 已应用) */
|
|
277
|
+
inBatch: boolean;
|
|
278
|
+
/** inBatch 为 false 时的机器可判别原因 (与 plan.skipped 逐条一致) */
|
|
279
|
+
skipReason?: SkipReason;
|
|
280
|
+
/**
|
|
281
|
+
* inBatch 为 false 时的中文行尾说明。
|
|
282
|
+
* 恒等于同 target 的 plan.skipped[].note 与 SkipBook.entries[].note;
|
|
283
|
+
* 随条目携带, 是为了让「目标 + 为什么跳过」的复核表不必再按 target join 两份数组。
|
|
284
|
+
*/
|
|
285
|
+
skipNote?: string;
|
|
286
|
+
}
|
|
287
|
+
/** 只读面的完整产物 */
|
|
288
|
+
export interface SweepPlan {
|
|
289
|
+
/** 生效的根 (原样回显) */
|
|
290
|
+
roots: string[];
|
|
291
|
+
/** 生效的排除 / 包含名单 (已过 mergeNames 收口, 供审计) */
|
|
292
|
+
exclude: string[];
|
|
293
|
+
include: string[];
|
|
294
|
+
/** 本计划所用的安全策略 */
|
|
295
|
+
policy: SweepPolicy;
|
|
296
|
+
/** 本次体积口径 (存在条目时给出; 全未测到时可与逐条 entry.basis 不同值; 无条目时缺省) */
|
|
297
|
+
basis?: SizeBasis;
|
|
298
|
+
/** 逐目标领域条目: 保扫描的 target 升序; 测量时已不存在的目标 (BC-13) 不产生条目 */
|
|
299
|
+
entries: SweepEntry[];
|
|
300
|
+
/** 删除批次 (与 deletionBatch 同源, 保清单顺序): policy 已应用 */
|
|
301
|
+
batch: string[];
|
|
302
|
+
/** 批次外目标与原因 (含未测到体积的条目) */
|
|
303
|
+
skipped: SkippedTarget[];
|
|
304
|
+
/** 扫描与体积的非致命告警 (两段合并, 保各自次序) */
|
|
305
|
+
warnings: SweepWarning[];
|
|
306
|
+
/** 两份名单的命中统计 (供 CLI 出名单回执与未命中告警, BC-09 / BC-33) */
|
|
307
|
+
nameMatches: {
|
|
308
|
+
exclude: NameMatch[];
|
|
309
|
+
include: NameMatch[];
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
/** 一次执行的总体状态 */
|
|
313
|
+
export type SweepRunStatus =
|
|
314
|
+
/** 批次非空且通过安全闸, 已执行删除 (逐条成败见 removal) */
|
|
315
|
+
'executed'
|
|
316
|
+
/** 安全闸整批拒绝, 零删除 (BC-22) */
|
|
317
|
+
| 'rejected'
|
|
318
|
+
/** 批次为空 (无可删目标), 零删除 */
|
|
319
|
+
| 'nothing-to-do';
|
|
320
|
+
/** 逐目标的执行结果 (判别联合) */
|
|
321
|
+
export type EntryOutcome =
|
|
322
|
+
/** 删除成功 */
|
|
323
|
+
{
|
|
324
|
+
kind: 'removed';
|
|
325
|
+
}
|
|
326
|
+
/** 删除阶段核验确认目标已不存在 (EC-01 / EC-07), 计成功侧 */
|
|
327
|
+
| {
|
|
328
|
+
kind: 'missing';
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* 安全闸之前目标已不存在, 按 staleTargets: 'missing' 从批次摘出。
|
|
332
|
+
* 与 missing 的区别是出处: missing 由删除器核验过, stale 从未进入删除面;
|
|
333
|
+
* 两者同属「目标已达成」, 同计成功侧。
|
|
334
|
+
*/
|
|
335
|
+
| {
|
|
336
|
+
kind: 'stale';
|
|
337
|
+
} | {
|
|
338
|
+
kind: 'failed';
|
|
339
|
+
failure: TargetFailure;
|
|
340
|
+
} | {
|
|
341
|
+
kind: 'rejected';
|
|
342
|
+
rejection: RejectedTarget;
|
|
343
|
+
}
|
|
344
|
+
/** 批次内但未轮到 (整批中止时中止点及其之后) */
|
|
345
|
+
| {
|
|
346
|
+
kind: 'not-attempted';
|
|
347
|
+
code: AbortCode;
|
|
348
|
+
}
|
|
349
|
+
/**
|
|
350
|
+
* 在期望批次之外 (提供了 expectedBatch, 且本目标不在其中)。
|
|
351
|
+
* 与 skipped 的区别: skipped 是安全策略挡下, not-expected 是调用方给的范围挡下。
|
|
352
|
+
*/
|
|
353
|
+
| {
|
|
354
|
+
kind: 'not-expected';
|
|
355
|
+
} | {
|
|
356
|
+
kind: 'skipped';
|
|
357
|
+
reason: SkipReason;
|
|
358
|
+
};
|
|
359
|
+
/** 逐目标执行结果的 kind 取值集 */
|
|
360
|
+
export type EntryOutcomeKind = EntryOutcome['kind'];
|
|
361
|
+
/** 期望批次与实时批次的差集; 未提供 expectedBatch 时缺省 */
|
|
362
|
+
export interface SweepDrift {
|
|
363
|
+
/** 在实时批次但不在期望批次: 本次新出现的目标 (未删) */
|
|
364
|
+
added: string[];
|
|
365
|
+
/** 在期望批次但不在实时批次: 已消失或被策略挡下的目标 (未删) */
|
|
366
|
+
removed: string[];
|
|
367
|
+
}
|
|
368
|
+
/** 带执行结果的条目 (与 plan.entries 同序同长) */
|
|
369
|
+
export interface SweepOutcomeEntry extends SweepEntry {
|
|
370
|
+
outcome: EntryOutcome;
|
|
371
|
+
}
|
|
372
|
+
/** 执行面的完整产物 */
|
|
373
|
+
export interface SweepReport {
|
|
374
|
+
status: SweepRunStatus;
|
|
375
|
+
/**
|
|
376
|
+
* 本次执行所依据的实时计划。与先前 plan() 的结果不一致时,
|
|
377
|
+
* 以本字段为准; 两者的差异另由 drift 显式给出。
|
|
378
|
+
*/
|
|
379
|
+
plan: SweepPlan;
|
|
380
|
+
/** 进入安全闸时的校验结果; status 为 nothing-to-do 时缺省 */
|
|
381
|
+
validation?: ValidationResult;
|
|
382
|
+
/** 删除分桶; 未执行删除 (整批拒绝 / 空批) 时缺省 */
|
|
383
|
+
removal?: RemovalResult;
|
|
384
|
+
/** 逐目标的执行结果 (与 plan.entries 同序同长) */
|
|
385
|
+
entries: SweepOutcomeEntry[];
|
|
386
|
+
/** 按 staleTargets: 'missing' 摘出的已消失目标 (保输入顺序); 未开启时为空数组 */
|
|
387
|
+
stale: string[];
|
|
388
|
+
/** 释放量: 成功侧 (removed + missing + stale) 的体积累计, 口径与 CLI 汇总行同源 */
|
|
389
|
+
releasedBytes: number;
|
|
390
|
+
/** 期望批次与实时批次的差集; 未提供 expectedBatch 时缺省 */
|
|
391
|
+
drift?: SweepDrift;
|
|
392
|
+
}
|
|
393
|
+
/** 结果计数摘要 (成功侧 / 未处理 / 真失败 / 整批中止四档) */
|
|
394
|
+
export interface SweepSummary {
|
|
395
|
+
/** 逐 kind 计数 (EntryOutcome 的每种 kind 恒有一项, 缺省 0) */
|
|
396
|
+
counts: Record<EntryOutcomeKind, number>;
|
|
397
|
+
/** 成功侧: removed + missing + stale */
|
|
398
|
+
succeeded: number;
|
|
399
|
+
/** 未处理 (非失败): skipped + rejected + not-attempted + not-expected */
|
|
400
|
+
unprocessed: number;
|
|
401
|
+
/** 真失败: failed */
|
|
402
|
+
failed: number;
|
|
403
|
+
/** 是否发生了整批中止 (存在 removal.aborted) */
|
|
404
|
+
aborted: boolean;
|
|
405
|
+
}
|
|
406
|
+
/**
|
|
407
|
+
* 进度事件 (编排层)。
|
|
408
|
+
* 终结事件契约: plan() 的事件流以 plan-done 收尾, run() 以 done 收尾, 两者之后不再有任何事件;
|
|
409
|
+
* 「流已结束」因此可判定, 异步迭代桥接不再需要把 Promise 结果塞进队列当结束哨兵。
|
|
410
|
+
*/
|
|
411
|
+
export type SweepProgressEvent = {
|
|
412
|
+
kind: 'phase';
|
|
413
|
+
phase: SweepPhase;
|
|
414
|
+
status: 'start' | 'done';
|
|
415
|
+
elapsedMs?: number;
|
|
416
|
+
} | {
|
|
417
|
+
kind: 'hit';
|
|
418
|
+
hit: ScanHit;
|
|
419
|
+
} | {
|
|
420
|
+
kind: 'measured';
|
|
421
|
+
target: string;
|
|
422
|
+
bytes: number;
|
|
423
|
+
basis: SizeBasis;
|
|
424
|
+
} | {
|
|
425
|
+
kind: 'unmeasured';
|
|
426
|
+
target: string;
|
|
427
|
+
code: UnmeasuredCode;
|
|
428
|
+
reason: string;
|
|
429
|
+
} | {
|
|
430
|
+
kind: 'skipped';
|
|
431
|
+
target: string;
|
|
432
|
+
reason: SkipReason;
|
|
433
|
+
} | {
|
|
434
|
+
kind: 'removed';
|
|
435
|
+
target: string;
|
|
436
|
+
outcome: 'removed' | 'missing';
|
|
437
|
+
} | {
|
|
438
|
+
kind: 'failed';
|
|
439
|
+
failure: TargetFailure;
|
|
440
|
+
} | {
|
|
441
|
+
kind: 'aborted';
|
|
442
|
+
aborted: AbortedBatch;
|
|
443
|
+
} | {
|
|
444
|
+
kind: 'warning';
|
|
445
|
+
warning: SweepWarning;
|
|
446
|
+
}
|
|
447
|
+
/** 只读面终结事件: plan() 的最后一个事件, 携带完整计划 */
|
|
448
|
+
| {
|
|
449
|
+
kind: 'plan-done';
|
|
450
|
+
plan: SweepPlan;
|
|
451
|
+
elapsedMs: number;
|
|
452
|
+
}
|
|
453
|
+
/** 执行面终结事件: run() 的最后一个事件 */
|
|
454
|
+
| {
|
|
455
|
+
kind: 'done';
|
|
456
|
+
status: SweepRunStatus;
|
|
457
|
+
elapsedMs: number;
|
|
458
|
+
};
|